doc/libvips-colour.md
Title: Operator index > By section > Colour
<!-- libvips/colour -->These operators let you transform coordinates and images between colour spaces, calculate colour differences, and move to and from device spaces.
All operations process colour from the first few bands and pass other bands through unaltered. This means you can operate on images with alpha channels safely. If you move to or from 16-bit RGB, any alpha channels are rescaled for you.
Radiance images have four 8-bits bands and store 8 bits of R, G and B and another 8 bits of exponent, common to all channels. They are widely used in the HDR imaging community.
The colour functions can be divided into three main groups. First, functions to transform images between the different colour spaces supported by libvips: [[email protected]], [[email protected]], [[email protected]], [[email protected]_W], [[email protected]], [[email protected]], [[email protected]], [[email protected]], [[email protected]], [[email protected]], [[email protected]], and [[email protected]].
There are also a set of minor colourspaces which are one of the above in a slightly different format: [[email protected]], [[email protected]], [[email protected]], and [[email protected]].
Use [[email protected]] to move an image to a target colourspace using the best sequence of colour transform operations.
Use [[email protected]] to convert an SDR image with an attached gainmap to a full HDR scRGB image.
Secondly, there are a set of operations for calculating colour difference metrics. Finally, libvips wraps LittleCMS and uses it to provide a set of operations for reading and writing images with ICC profiles.
This figure shows how the libvips colour spaces interconvert:
The colour spaces supported by libvips are:
[[email protected]]: CIELAB '76 colourspace with a D65 white. This uses three floats for each band, and bands have the obvious range.
There are two variants, [[email protected]] and [[email protected]], which use ints to store values. These are less precise, but can be quicker to store and process.
[[email protected]] is the same, but with a*b* as polar coordinates. Hue is expressed in degrees.
[[email protected]]: The Oklab colourspace with a D65 white. This uses three floats for each band, with 0 - 1 for L and roughly plus or minus 0.5 for a and b. Values can be outside this range for HDR images.
[[email protected]] is the same, but with a and b as polar coordinates. Hue is expressed in degrees.
[[email protected]]: CIE XYZ. This uses three floats. See [const@D75_X0] and friends for values for the ranges under various illuminants.
[[email protected]] is the same, but with little x and y.
[[email protected]]: a linear colourspace with the sRGB primaries. This is useful if you need linear light and don't care much what the primaries are.
Linearization is performed with the usual sRGB equations, see below.
[[email protected]]: the standard sRGB colourspace, see: wikipedia sRGB.
This uses three 8-bit values for each of RGB.
[[email protected]] is the same, but using three 16-bit values for RGB.
[[email protected]] is sRGB, but in polar coordinates. [[email protected]] is much better, only use HSV if you have to.
[[email protected]_W]: a monochrome image, roughly G from sRGB. The grey value is calculated in linear [[email protected]] space with RGB ratios 0.2126, 0.7152, 0.0722 as defined by CIE 1931 linear luminance.
[[email protected]] is the same, but using 16 bits.
[[email protected]]: a colour space based on the CMC(1:1) colour difference measurement. This is a highly uniform colour space, and much better than CIELAB for expressing small differences.
The CMC colourspace is described in “Uniform Colour Space Based on the CMC(l:c) Colour-difference Formula”, M R Luo and B Rigg, Journal of the Society of Dyers and Colourists, vol 102, 1986. Distances in this colourspace approximate, within 10% or so, differences in the CMC(l:c) colour difference formula.
You can calculate metrics like CMC(2:1) by scaling the spaces before finding differences.