QOI.jl

QOI (Quite OK Image) format decoder/encoder.
Author KristofferC
Popularity
18 Stars
Updated Last
1 Year Ago
Started In
December 2021

QOI.jl - Implementation of the QOI (Quite OK Image) format

Build Statuscodecov

This Julia package contains a decoder and encoder for the QOI image format. The QOI format is very simple and can be faster than using PNG (see the benchmarks) at the cost of a slightly worse compression ratio.

The code here is based on the reference C implementation given in https://github.com/phoboslab/qoi.

FileIO API

This is the simplest API and likely the one that most should use. Simply, use the load/save API from FileIO.jl to load and save QOI images.

using FileIO
image = load("test.qoi")
save("test2.qoi", image)

Basic API

  • QOI.qoi_decode(f::Union{String, IO}) - Read an image in the QOI format from the file/IO f and return a matrix with RGB or RGBA colorants from ColorTypes.jl
  • QOI.qoi_encode(f::Union{String, IO}, image::AbstractMatrix{<:Colorant}) - Write the image to the the file/IO f.

Advanced API

The QOI format is read in row-major order. This means that a transpose is required to create the matrices returned in the basic API. To avoid this, the following more advanced APIs exist:

  • QOI.qoi_decode_raw(v::AbstractVector{UIt8}}) - Takes a vector of the bytes of an image in QOI format and returns the uncompressed vector of bytes from decoding.

  • QOI.qoi_encode_raw(image::AbstractVecOrMat{UInt8}, header::QOI.QOIHeader) - Returns the bytes from compressing the bytes in image. The required header is defined as

    struct QOIHeader
      width::UInt32
      height::UInt32
      channels::QOI.QOIChannel # @enum
      colorspace::QOI.QOIColorSpace # @enum
    end

    where channels can be either QOI.QOI_RGB or QOI.QOI_RGBA and colorspace can be either QOI.QOI_SRGB or QOI.QOI_LINEAR

  • QOI.qoi_encode_raw!(data::AbstractVecOrMat{UInt8}, image::AbstractVecOrMat{UInt8}, header::QOIHeader) - Same as above except writing the compressed data into data.

Benchmarks

The benchmarks here compares the speed of encoding/decoding images with QOI.jl and PNGFiles.jl (which uses libpng) It is supposed to mimic https://qoiformat.org/benchmark/. The images used in the benchmark are taken from TestImages.jl, specifically, all the PNG images in https://testimages.juliaimages.org/stable/imagelist/. The benchmarks were run on Linux on a 12th Gen Intel(R) Core(TM) i9-12900K CPU. They can be repeated by running the benchmark/runbenchmarks.jl file with the associated environment.

Expand to see benchmark results

autumn_leaves.png 105x140 57.42kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 0.24 0.41 233.52 137.4 22.18 38.6%
QOI 0.04 0.13 1418.35 425.17 28.25 49.2%

barbara_color.png 576x720 1215.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 9.05 14.07 131.12 84.35 812.84 66.9%
QOI 3.52 5.03 337.19 235.74 945.75 77.8%

chelsea.png 300x451 396.39kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 2.24 4.4 172.82 88.02 218.84 55.2%
QOI 0.64 1.55 605.92 250.3 233.27 58.8%

coffee.png 400x600 703.12kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 5.35 11.6 128.28 59.19 443.18 63.0%
QOI 1.98 5.23 346.76 131.24 493.3 70.2%

fabio_color_256.png 256x256 192.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 1.56 2.11 119.84 88.84 118.0 61.5%
QOI 0.54 0.86 344.22 216.96 154.86 80.7%

fabio_color_512.png 512x512 768.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 5.42 8.0 138.44 93.76 327.45 42.6%
QOI 2.04 3.13 366.9 239.9 463.9 60.4%

fabio_gray_256.png 256x256 192.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 1.08 1.65 174.16 113.7 108.65 56.6%
QOI 0.38 0.78 491.28 239.6 87.99 45.8%

fabio_gray_512.png 512x512 768.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 3.68 5.84 203.88 128.53 259.41 33.8%
QOI 1.55 2.99 483.08 251.05 298.29 38.8%

lena_gray_16bit.png 256x256 192.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 1.12 1.7 167.17 109.98 100.71 52.5%
QOI 0.4 0.78 468.04 241.2 82.01 42.7%

lighthouse.png 512x768 1152.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 8.4 13.02 133.94 86.39 692.56 60.1%
QOI 3.41 8.14 329.92 138.25 638.75 55.4%

monarch_color.png 512x768 1152.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 8.36 13.34 134.6 84.3 613.23 53.2%
QOI 3.64 5.04 309.24 223.43 715.79 62.1%

monarch_color_256.png 256x256 192.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 1.24 2.3 150.65 81.55 129.52 67.5%
QOI 0.34 1.46 557.65 128.6 144.39 75.2%

mountainstream.png 512x768 1152.0kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 8.8 13.46 127.78 83.6 892.34 77.5%
QOI 3.05 4.41 369.44 255.16 824.83 71.6%

toucan.png 150x162 94.92kB

decode ms encode ms decode mpps encode mpps size kb rate
PNGFiles 0.34 0.58 274.49 158.87 25.84 27.2%
QOI 0.06 0.18 1513.03 514.79 43.28 45.6%