qoi

README

QOI Go

Implementation of QOI encoding and decoding in Go.

For more info about QOI, see:

• the specification at https://qoiformat.org/qoi-specification.pdf
• the reference implementation at https://github.com/phoboslab/qoi

Performance

Even though this implementation is very straightforward and not particularly optimised (there is not much to optimise with such a simple format anyway), I found that it is much faster than the existing Go implementations:

compared to...	decoding	encoding
takeyourhatoff/qoi	4.3x faster	12.4x faster
xfmoulet/qoi	1.43x faster	7.1x faster
arian/go-qoi	7.5x faster	7.5x faster

Full benchmark comparisons can be found here.

I think a lot of the difference is caused by these libraries making huge amounts of unneeded allocations.

Compared to the reference C implem, I didn't make a full benchmark, but I have some evidence that this package would be about 20-50% slower. Encoding especially takes a hit because it needs to compare pixels a lot and Go doesn't have (C-style) union types, so 4 bytes cannot be cast to an uint32 for free to make a single comparison, it needs to do 4 compares.

The only thing I did that I would call "optimisation" (i.e. apart from doing sensible allocations) simply consists of replacing the check for whether we can use an OP_DIFF in the encoder (and similarly for OP_LUMA):

if dr >= -2 && dr <= 1 && dg >= -2 && dg <= 1 && db >= -2 && db <= 1 { ...

with this equivalent version:

if uint8((dr+2)|(dg+2)|(db+2))&0xfc == 0 { ...

This avoids having too many branches and for photographic images where OP_DIFF and OP_LUMA are plentiful, this can speed up encoding by more than 10 %.

Documentation

Overview

Package qoi implements a QOI image encoder and decoder.

The QOI specification is at https://qoiformat.org/qoi-specification.pdf

This package registers the decoder on import to be used by the standard library's image.Decode.

Index

• Constants
• func Decode(r io.Reader) (image.Image, error)
• func DecodeBytes(b []byte) (image.Image, error)
• func DecodeConfig(r io.Reader) (image.Config, error)
• func Encode(w io.Writer, img image.Image, o *Options) error
• type ConfigExtra
  • func DecodeConfigExtra(r io.Reader) (ConfigExtra, error)
• type Options

Constants

const ChannelsRGB = 3

const ChannelsRGBA = 4

const ColorspaceLinear = 1

const ColorspaceSRGB = 0

const Magic = "qoif"

Functions

func Decode

func Decode(r io.Reader) (image.Image, error)

Decode decodes a QOI image. The returned image.Image is always an *image.NRGBAImage.

func DecodeBytes

func DecodeBytes(b []byte) (image.Image, error)

DecodeBytes decodes a QOI image. It is similar to Decode but is faster and should be preferred if you already have the data in a byte slice.

func DecodeConfig

func DecodeConfig(r io.Reader) (image.Config, error)

DecodeConfig returns the dimensions of a QOI image without decoding the entire image. The color model is always color.NRGBAModel as QOI always uses this model when decoding.

func Encode

func Encode(w io.Writer, img image.Image, o *Options) error

Encode encodes the image to its QOI representation. If nil Options are passed, defaults of ChannelsRGBA and ColorspaceSRGB are used.

Types

type ConfigExtra

type ConfigExtra struct {
	image.Config
	Channels   int
	Colorspace int
}

ConfigExtra represents the standard library's image.Config extended with QOI-specific metadata.

func DecodeConfigExtra

func DecodeConfigExtra(r io.Reader) (ConfigExtra, error)

DecodeConfigExtra returns the extra config data embedded in a QOI header.

type Options

type Options struct {
	// Channels should be [ChannelsRGB] or [ChannelsRGBA]. It is only used to
	// set the metadata in the header and has no impact on the encoding.
	Channels int
	// Colorspace should be [ColorspaceSRGB] or [ColorspaceLinear]. It is only
	// used to set the metadata in the header and has no impact on the encoding.
	Colorspace int
}

Options are encoding options.