QOI (image format)

Quite OK Image

Filename extension	.qoi
Magic number	qoif(4 bytes, ASCII)
Developed by	Dominic Szablewski
Initial release	24 November 2021
Latest release	1.0 5 January 2022(2022-01-05)
Type of format	Losslessbitmapimage format
Standard	Specification
Open format?	Yes
Free format?	Yes
Website	qoiformat.org

TheQuite OK Image Format(QOI) is a specification forlosslessimage compressionof24-bit(8bitsper colorRGB) or 32-bit (8 bits per color with 8-bitAlphachannelRGBA) colorraster(bitmapped) images, invented by Dominic Szablewski and first announced on 24 November 2021.

Description

The intended purpose was to create anopen sourcelossless compressionmethod that was faster and easier to implement thanPNG.Figures specified in the blog post announcing the format claim twenty to fifty times faster encoding, and three to four times faster decoding speed compared to PNG, with similar file sizes.The author has donated the specification to thepublic domain(CC0).

Software and language support

QOI is supported natively byImageMagick,Imagine (v1.3.9+),IrfanView(v4.60+),FFmpeg(v5.1+),andGraphicConverter(v11.8+).Microsoft PowerToys(v0.76+) for Windows 10 and 11 adds support for previewing QOI images to the Windows File Explorer.Community madepluginsare available inGIMP,Paint.NETandXnView MP.

The game engineGameMakerdesignatesbzip2+ QOI as the default format oftexturegroups since version 2022.1.0.609, to achieve the better compression but still quicker to decompress, while the standalone QOI and PNG formats are optional for the even faster performance and better compabilities respectively.

There are also implementations for variouslanguagessuch asRust,Python,Java,C++,C#and more.A full list can be found on theproject's Git(Hub) repository README.

File format

Header

A QOI file consists of a 14-byte header, followed by any number of data “chunks” and an 8-byte end marker.

qoi_header{
charmagic[4];// magic bytes "qoif"
uint32_twidth;// image width in pixels (BE)
uint32_theight;// image height in pixels (BE)
uint8_tchannels;// 3 = RGB, 4 = RGBA
uint8_tcolorspace;// 0 = sRGB with linear Alpha
// 1 = all channels linear
};

The colorspace and channel fields are purely informative. They do not change the way data chunks are encoded.

Encoding

Images are encoded row by row, left to right, top to bottom. The decoder and encoder start with{r:0,g:0,b:0,a:255}as the previous pixel value. An image is complete when allpixelsspecified bywidth * heighthave been covered. Pixels are encoded as:

• Run-length encodingof the previous pixel (QOI_OP_RUN)
• an index into the array of previously seen pixels (QOI_OP_INDEX)
• a difference compared to the previous pixel value in r,g,b (QOI_OP_DIFForQOI_OP_LUMA)
• Full r,g,b or r,g,b,a values (QOI_OP_RGBorQOI_OP_RGBA)

The color channels are assumed to not be premultiplied with the Alpha channel ( “un-premultiplied Alpha” ). A runningarray[64](zero-initialized) of previously seen pixel values is maintained by the encoder and decoder. Each pixel that is seen by the encoder and decoder is put into this array at the position formed by ahash functionof the color value.

In the encoder, if the pixel value at the index matches the current pixel, this index position is written to the stream asQOI_OP_INDEX.The hash function for the index is:

index_position=(r*3+g*5+b*7+a*11)%64

Each chunk starts with a 2- or 8-bit tag, followed by a number of data bits. The bit length of chunks is divisible by 8 - i.e. all chunks are byte aligned. All values encoded in these data bits have the most significant bit on the left. The 8-bit tags have precedence over the 2-bit tags. A decoder must check for the presence of an 8-bit tag first. The byte stream's end is marked with 70x00bytes followed by a single0x01byte.

The possible chunks are:

QOI_OP_RGB

Byte[0]								Byte[1]	Byte[2]	Byte[3]
7	6	5	4	3	2	1	0	7.. 0	7.. 0	7.. 0
1	1	1	1	1	1	1	0	red	green	blue

• 8-bit tagb11111110(254)
• 8-bit red channel value
• 8-bit green channel value
• 8-bit blue channel value

The Alpha value remains unchanged from the previous pixel.

QOI_OP_RGBA

Byte[0]								Byte[1]	Byte[2]	Byte[3]	Byte[4]
7	6	5	4	3	2	1	0	7.. 0	7.. 0	7.. 0	7.. 0
1	1	1	1	1	1	1	1	red	green	blue	Alpha

• 8-bit tagb11111111(255)
• 8-bit red channel value
• 8-bit green channel value
• 8-bit blue channel value
• 8-bit Alpha channel value

QOI_OP_INDEX

Byte[0] (Range: 0.. 63)
7	6	5	4	3	2	1	0
0	0	index

• 2-bit tagb00
• 6-bit index into the color index array:0..63

A valid encoder must not issue 2 or more consecutiveQOI_OP_INDEX chunks to the same index.QOI_OP_RUNshould be used instead.

QOI_OP_DIFF

Byte[0] (Range: 64.. 127)
7	6	5	4	3	2	1	0
0	1	dr		dg		db

• 2-bit tagb01
• 2-bit red channel difference from the previous pixel-2..1
• 2-bit green channel difference from the previous pixel-2..1
• 2-bit blue channel difference from the previous pixel-2..1

The difference to the current channel values are using awraparound operation,so1 - 2will result in 255, while255 + 1will result in 0.

Values are stored asunsigned integerswith a bias of 2. E.g. −2 is stored as 0 (b00). 1 is stored as 3 (b11). The Alpha value remains unchanged from the previous pixel.

QOI_OP_LUMA

Byte[0] (Range: 128.. 191)								Byte[1]
7	6	5	4	3	2	1	0	7	6	5	4	3	2	1	0
1	0	dg						dr - dg				db - dg

• 2-bit tagb10
• 6-bit green channel difference from the previous pixel-32..31
• 4-bit red channel difference minus green channel difference-8..7
• 4-bit blue channel difference minus green channel difference-8..7

The green channel is used to indicate the general direction of change and is encoded in 6 bits. The red and blue channels (dr and db) base their diffs off of the green channel difference. I.e.:

dr_dg=(cur_px.r-prev_px.r)-(cur_px.g-prev_px.g)
db_dg=(cur_px.b-prev_px.b)-(cur_px.g-prev_px.g)

The difference to the current channel values are using a wraparound operation, so10 - 13will result in 253, while250 + 7will result in 1.

Values are stored as unsigned integers with a bias of 32 for the green channel and a bias of 8 for the red and blue channel. The Alpha value remains unchanged from the previous pixel.

QOI_OP_RUN

Byte[0] (Range: 192.. 253)
7	6	5	4	3	2	1	0
1	1	run

• 2-bit tagb11
• 6-bit run-length repeating the previous pixel

Therun-lengthis stored with a bias of −1. Note that the runlengths 63 and 64 (b111110andb111111) are illegal as they are occupied by theQOI_OP_RGBandQOI_OP_RGBAtags.

External links

• Format website: C Source code and benchmark results
• 1 page PDF specification
• GitHub repository (including C implementation)
• How PNG Works: Compromising Speed for Quality - YouTubeA video comparing compression techniques in PNG and QOI with animations and examples.