From 14dfda4e02661945be264510b8b7a7dab73b6890 Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Mon, 22 Jun 2015 09:35:16 +0100 Subject: [PATCH] improve colour docs --- libvips/colour/colour.c | 156 +++++++++++++++------------------------- 1 file changed, 57 insertions(+), 99 deletions(-) diff --git a/libvips/colour/colour.c b/libvips/colour/colour.c index f2c92467..c8d2d8d6 100644 --- a/libvips/colour/colour.c +++ b/libvips/colour/colour.c @@ -57,20 +57,33 @@ * 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 VIPS: sRGB, - * scRGB, - * XYZ, Yxy, - * Lab, LabQ, - * LabS, LCh and - * CMC). Use vips_colourspace() to move an image to a + * by VIPS: #VIPS_INTERPRETATION_sRGB, #VIPS_INTERPRETATION_scRGB, + * #VIPS_INTERPRETATION_B_W, + * #VIPS_INTERPRETATION_XYZ, #VIPS_INTERPRETATION_YXY, + * #VIPS_INTERPRETATION_LAB, + * #VIPS_INTERPRETATION_LCH, and + * #VIPS_INTERPRETATION_CMC. + * + * There are also a set of minor colourspaces which are one of the above in a + * slightly different format: + * #VIPS_INTERPRETATION_LAB, #VIPS_INTERPRETATION_LABQ, + * #VIPS_INTERPRETATION_LABS, #VIPS_INTERPRETATION_LCH, + * #VIPS_INTERPRETATION_RGB16, and #VIPS_INTERPRETATION_GREY16. + * + * Use vips_colourspace() to move an image to a * target colourspace using the best sequence of colour transform operations. + * * Secondly, there are a set of operations for * calculating colour difference metrics. Finally, VIPS wraps LittleCMS and * uses it to provide a set of operations for reading and writing images with @@ -84,112 +97,57 @@ * * The colour spaces supported by VIPS are: * - * - * - * - * LabQ + * * #VIPS_INTERPRETATION_LAB -- CIELAB '76 colourspace with a D65 white. This + * uses three floats for each band, and bands have the obvious range. * - * This is the principal VIPS colorimetric storage format. - * LabQ images have four 8-bit bands and store 10 bits of L and 11 bits - * of a and b. + * There are two + * variants, #VIPS_INTERPRETATION_LABQ and #VIPS_INTERPRETATION_LABS, which + * use ints to store values. These are less precise, but can be quicker to + * store and process. * - * You cannot perform calculations on LabQ images (they are - * tagged with %VIPS_CODING_LABQ), though a few operations such as - * vips_extract_area() will work directly with them. - * - * - * - * - * LabS + * #VIPS_INTERPRETATION_LCH is the same, but with a*b* as polar coordinates. + * Hue is expressed in degrees. * - * This format represents coordinates in CIELAB space as a - * three-band #VIPS_FORMAT_SHORT image, scaled to fit the full range of - * bits. It is the best format for computation, being relatively - * compact, quick, and accurate. Colour values expressed in this way - * are hard to visualise. - * - * - * - * - * Lab + * * #VIPS_INTERPRETATION_XYZ -- CIE XYZ. This uses three floats. + * See #VIPS_D75_X0 and friends for values for the ranges + * under various illuminants. * - * Lab colourspace represents CIELAB colour values with a three-band - * #VIPS_FORMAT_FLOAT image. This is the simplest format for general - * work: adding the constant 50 to the L channel, for example, has the - * expected result. + * #VIPS_INTERPRETATION_YXY is the same, but with little x and y. * - * VIPS uses D65 LAB, but you can use other colour temperatures with a - * little effort, see vips_XYZ2Lab(). - * - * - * - * - * XYZ + * * #VIPS_INTERPRETATION_scRGB -- a linear colourspace with the sRGB + * primaries. This is useful if you need linear light and don't care + * much what the primaries are. * - * CIE XYZ colour space represented as a three-band #VIPS_FORMAT_FLOAT - * image. - * - * - * - * - * Yxy + * Linearization is performed with the usual sRGB equations, see below. * - * CIE Yxy colour space represented as a three-band #VIPS_FORMAT_FLOAT - * image. - * - * + * * #VIPS_INTERPRETATION_sRGB -- the standard sRGB colourspace, see: + * [wikipedia sRGB](http://en.wikipedia.org/wiki/SRGB). * - * - * - * sRGB + * This uses three 8-bit values for each of RGB. * - * VIPS converts XYZ to and from sRGB using the usual formula: + * #VIPS_INTERPRETATION_RGB16 is the same, but using three 16-bit values for + * RGB. * - * http://en.wikipedia.org/wiki/SRGB + * * #VIPS_INTERPRETATION_B_W -- a monochrome image, roughly G from sRGB. + * The grey value is + * calculated in #VIPS_INTERPRETATION_scRGB space with the usual 0.2, 0.7, 0.1 + * RGB ratios. * - * You can also use vips_icc_transform() and friends to go to and from - * device space with a generic profile. - * - * - * - * - * scRGB + * #VIPS_INTERPRETATION_GREY16 is the same, but using 16-bits. * - * scRGB is sRGB bit with linear primaries. It uses floats in the range - * 0 - 1. It's convenient if you need a linear colourspace but don't - * care too much what the primaries are. - * - * + * * #VIPS_INTERPRETATION_CMC -- a colour space based on the CMC(1:1) + * colour difference measurement. This is a highly uniform colour space, + * much better than CIELAB for expressing small differences. * - * - * - * LCh + * 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. * - * Like Lab, but rectangular ab coordinates - * are replaced with - * polar Ch (Chroma and hue) coordinates. - * Hue angles are expressed in degrees. - * - * - * - * - * CMC - * - * A colour space based on the CMC(1:1) colour difference measurement. - * This is a highly uniform colour space, 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. - * - * - * + * You can calculate metrics like CMC(2:1) by scaling the spaces before + * finding differences. + * */ /* Areas under curves for Dxx. 2 degree observer.