How libvips handles colour

[update: the colour package has been rewritten for 7.32, see this post for an outline of the new system]

I was asked to write some notes on how libvips handles colourspaces. I thought it might be handy to have as a blog post for reference.

libvips started out as a library for very high-resolution, colorimetric imaging of old master paintings. It therefore emphasises efficiency, large file sizes and high accuracy; it does not think much of being easy to use. It's a low-level, rather manual library.

libvips images are 3D arrays with the dimensions width / height / bands (usually called channels in other packages I think), where each value can be 8, 16 or 32-bit int, signed or unsigned, float, double, complex or double complex. All values in an image must have the same type. All operations (almost) can work on images of any size or type. libvips uses templates so you (usually) only write one inner loop and the compiler will expand it to the 10 cases for you.

Colour transforms are implemented as a set of functions on top of this. libvips has D65 XYZ, represented as a 3-band float image, as its core colourspace:

There's no such thing as a LAB image (for example). Instead, operations like im_XYZ2Lab() assume you know what you are doing and that the array of values you pass in does indeed represent a D65 XYZ image. Operations set a hint field on their output (called "interpretation" -- it'd be set to LAB by im_XYZ2Lab(), for example) that higher-level libraries can use to help display an image to the user sensibly.

The colour-related operations libvips provides are:

• conversion between XYZ, Lab, LCh, Yxy and CMC
• a few colour difference metrics: CIELAB 76, CIELAB 2000, CMC
• D65 / D50 conversion, based on Bradford
• conversion to and from device space and D65 XYZ with lcms and an ICC profile
• a fast path to sRGB from XYZ for GUIs

And that's about it.

The file load/save operations (like tiffload, jpegsave etc.) don't do anything with colour. On load they attach any ICC profiles they see to the vips image as metadata and on save they write any attached profile to the file. They aim to give you something very close to what's actually stored in the file and leave colour processing for you to arrange.

What's good about the way libvips handles colour? It's simple, fast and predictable. There's no magic and it won't do strange things behind your back. Because there's no colour knowledge embedded in images it's also very easy to extend.

The downsides are: it takes some level of knowledge to drive it, there's not much support for other colour temperatures (better D50 support would be useful for printing), and like all of libvips there's no support for alpha.

nip2 tries to provide a slightly higher-level way of working with colour. It has simple menus which flip between colour spaces and temperatures, buttons for calculating distance maps, and fairly automatic import and export features.