colour: libvips Reference Manual

## colour colour — colour operators |

## Stability Level

Stable, unless otherwise indicated

## Functions

gboolean | vips_colourspace_issupported ()
int | vips_colourspace ()
int | vips_LabQ2sRGB ()
int | vips_rad2float ()
int | vips_float2rad ()
int | vips_LabS2LabQ ()
int | vips_LabQ2LabS ()
int | vips_LabQ2Lab ()
int | vips_Lab2LabQ ()
int | vips_LCh2Lab ()
int | vips_Lab2LCh ()
int | vips_Yxy2Lab ()
int | vips_CMC2XYZ ()
int | vips_Lab2XYZ ()
int | vips_XYZ2Lab ()
int | vips_XYZ2scRGB ()
int | vips_scRGB2sRGB ()
int | vips_scRGB2BW ()
int | vips_sRGB2scRGB ()
int | vips_scRGB2XYZ ()
int | vips_HSV2sRGB ()
int | vips_sRGB2HSV ()
int | vips_LCh2CMC ()
int | vips_CMC2LCh ()
int | vips_XYZ2Yxy ()
int | vips_Yxy2XYZ ()
int | vips_LabS2Lab ()
int | vips_Lab2LabS ()
int | vips_CMYK2XYZ ()
int | vips_XYZ2CMYK ()
int | vips_profile_load ()
int | vips_icc_present ()
int | vips_icc_transform ()
int | vips_icc_import ()
int | vips_icc_export ()
int | vips_icc_ac2rc ()
gboolean | vips_icc_is_compatible_profile ()
int | vips_dE76 ()
int | vips_dE00 ()
int | vips_dECMC ()
void | vips_col_Lab2XYZ ()
void | vips_col_XYZ2Lab ()
double | vips_col_ab2h ()
void | vips_col_ab2Ch ()
void | vips_col_Ch2ab ()
float | vips_col_L2Lcmc ()
float | vips_col_C2Ccmc ()
float | vips_col_Ch2hcmc ()
void | vips_col_make_tables_CMC ()
float | vips_col_Lcmc2L ()
float | vips_col_Ccmc2C ()
float | vips_col_Chcmc2h ()
int | vips_col_sRGB2scRGB_8 ()
int | vips_col_sRGB2scRGB_16 ()
int | vips_col_sRGB2scRGB_8_noclip ()
int | vips_col_sRGB2scRGB_16_noclip ()
int | vips_col_scRGB2XYZ ()
int | vips_col_XYZ2scRGB ()
int | vips_col_scRGB2sRGB_8 ()
int | vips_col_scRGB2sRGB_16 ()
int | vips_col_scRGB2BW_16 ()
int | vips_col_scRGB2BW_8 ()
float | vips_pythagoras ()
float | vips_col_dE00 ()

## Types and Values

#define | VIPS_D93_X0
#define | VIPS_D93_Y0
#define | VIPS_D93_Z0
#define | VIPS_D75_X0
#define | VIPS_D75_Y0
#define | VIPS_D75_Z0
#define | VIPS_D65_X0
#define | VIPS_D65_Y0
#define | VIPS_D65_Z0
#define | VIPS_D55_X0
#define | VIPS_D55_Y0
#define | VIPS_D55_Z0
#define | VIPS_D50_X0
#define | VIPS_D50_Y0
#define | VIPS_D50_Z0
#define | VIPS_A_X0
#define | VIPS_A_Y0
#define | VIPS_A_Z0
#define | VIPS_B_X0
#define | VIPS_B_Y0
#define | VIPS_B_Z0
#define | VIPS_C_X0
#define | VIPS_C_Y0
#define | VIPS_C_Z0
#define | VIPS_E_X0
#define | VIPS_E_Y0
#define | VIPS_E_Z0
#define | VIPS_D3250_X0
#define | VIPS_D3250_Y0
#define | VIPS_D3250_Z0
enum | VipsIntent
enum | VipsPCS

## Object Hierarchy

        GEnum
        ├── VipsIntent
        ╰── VipsPCS

## Includes

    #include <vips/vips.h>

## Description

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 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 ICC profiles.

This figure shows how the VIPS colour spaces interconvert:

<para> <inlinegraphic fileref="interconvert.png" format="PNG" /> </para>

The colour spaces supported by VIPS are:

- VIPS_INTERPRETATION_LAB -- CIELAB '76 colourspace with a D65 white. This uses three floats for each band, and bands have the obvious range.

  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.

  VIPS_INTERPRETATION_LCH is the same, but with a*b* as polar coordinates. Hue is expressed in degrees.

- VIPS_INTERPRETATION_XYZ -- CIE XYZ. This uses three floats. See VIPS_D75_X0 and friends for values for the ranges under various illuminants.

  VIPS_INTERPRETATION_YXY is the same, but with little x and y.

- 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.

  Linearization is performed with the usual sRGB equations, see below.

- VIPS_INTERPRETATION_sRGB -- the standard sRGB colourspace, see: wikipedia sRGB.

  This uses three 8-bit values for each of RGB.

  VIPS_INTERPRETATION_RGB16 is the same, but using three 16-bit values for RGB.

  VIPS_INTERPRETATION_HSV is sRGB, but in polar coordinates. VIPS_INTERPRETATION_LCH is much better, only use HSV if you have to.

- 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.

  VIPS_INTERPRETATION_GREY16 is the same, but using 16-bits.

- 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.

  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.

## Functions

### vips_colourspace_issupported ()

    gboolean
    vips_colourspace_issupported (const VipsImage *image);

Test if `image` is in a colourspace that `vips_colourspace()` can process.

[method]

#### Parameters

image | input image |

#### Returns

`TRUE` if `image` is in a supported colourspace.

### vips_colourspace ()

    int
    vips_colourspace (VipsImage *in,
                      VipsImage **out,
                      VipsInterpretation space,
                      ...);

Optional arguments:

- `source_space` : input colour space

This operation looks at the interpretation field of `in` (or uses `source_space` , if set) and runs a set of colourspace conversion functions to move it to `space` .

For example, given an image tagged as VIPS_INTERPRETATION_YXY, running `vips_colourspace()` with `space` set to VIPS_INTERPRETATION_LAB will convert with `vips_Yxy2XYZ()` and `vips_XYZ2Lab()`.

See also: `vips_colourspace_issupported()`, `vips_image_guess_interpretation()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
space | convert to this colour space |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_LabQ2sRGB ()

    int
    vips_LabQ2sRGB (VipsImage *in,
                    VipsImage **out,
                    ...);

Unpack a LabQ (VIPS_CODING_LABQ) image to a three-band short image.

See also: `vips_LabS2LabQ()`, `vips_LabQ2sRGB()`, `vips_rad2float()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_rad2float ()

    int
    vips_rad2float (VipsImage *in,
                    VipsImage **out,
                    ...);

Unpack a RAD (VIPS_CODING_RAD) image to a three-band float image.

See also: `vips_float2rad()`, `vips_LabQ2LabS()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_float2rad ()

    int
    vips_float2rad (VipsImage *in,
                    VipsImage **out,
                    ...);

Convert a three-band float image to Radiance 32-bit packed format.

See also: `vips_rad2float()`, VIPS_CODING_RAD, `vips_LabQ2Lab()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_LabS2LabQ ()

    int
    vips_LabS2LabQ (VipsImage *in,
                    VipsImage **out,
                    ...);

Convert a LabS three-band signed short image to LabQ

See also: `vips_LabQ2LabS()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_LabQ2LabS ()

    int
    vips_LabQ2LabS (VipsImage *in,
                    VipsImage **out,
                    ...);

Unpack a LabQ (VIPS_CODING_LABQ) image to a three-band short image.

See also: `vips_LabS2LabQ()`, `vips_LabQ2LabS()`, `vips_rad2float()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_LabQ2Lab ()

    int
    vips_LabQ2Lab (VipsImage *in,
                   VipsImage **out,
                   ...);

Unpack a LabQ (VIPS_CODING_LABQ) image to a three-band float image.

See also: `vips_LabQ2Lab()`, `vips_LabQ2LabS()`, `vips_rad2float()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_Lab2LabQ ()

    int
    vips_Lab2LabQ (VipsImage *in,
                   VipsImage **out,
                   ...);

Convert a Lab three-band float image to LabQ (VIPS_CODING_LABQ).

See also: `vips_LabQ2Lab()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_LCh2Lab ()

    int
    vips_LCh2Lab (VipsImage *in,
                  VipsImage **out,
                  ...);

Turn LCh to Lab.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_Lab2LCh ()

    int
    vips_Lab2LCh (VipsImage *in,
                  VipsImage **out,
                  ...);

Turn Lab to LCh.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_Yxy2Lab ()

    int
    vips_Yxy2Lab (VipsImage *in,
                  VipsImage **out,
                  ...);

### vips_CMC2XYZ ()

    int
    vips_CMC2XYZ (VipsImage *in,
                  VipsImage **out,
                  ...);

### vips_Lab2XYZ ()

    int
    vips_Lab2XYZ (VipsImage *in,
                  VipsImage **out,
                  ...);

Optional arguments:

- `temp` : VipsArrayDouble, colour temperature

Turn Lab to XYZ. The colour temperature defaults to D65, but can be specified with `temp` .

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_XYZ2Lab ()

    int
    vips_XYZ2Lab (VipsImage *in,
                  VipsImage **out,
                  ...);

Optional arguments:

- `temp` : VipsArrayDouble, colour temperature

Turn XYZ to Lab, optionally specifying the colour temperature. `temp` defaults to D65.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_XYZ2scRGB ()

    int
    vips_XYZ2scRGB (VipsImage *in,
                    VipsImage **out,
                    ...);

Turn XYZ to scRGB.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_scRGB2sRGB ()

    int
    vips_scRGB2sRGB (VipsImage *in,
                     VipsImage **out,
                     ...);

Optional arguments:

- `depth` : depth of output image in bits

Convert an scRGB image to sRGB. Set `depth` to 16 to get 16-bit output.

If `depth` is 16, any extra channels after RGB are multiplied by 256.

See also: `vips_LabS2LabQ()`, `vips_sRGB2scRGB()`, `vips_rad2float()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_scRGB2BW ()

    int
    vips_scRGB2BW (VipsImage *in,
                   VipsImage **out,
                   ...);

Optional arguments:

- `depth` : depth of output image in bits

Convert an scRGB image to greyscale. Set `depth` to 16 to get 16-bit output.

If `depth` is 16, any extra channels after RGB are multiplied by 256.

See also: `vips_LabS2LabQ()`, `vips_sRGB2scRGB()`, `vips_rad2float()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_sRGB2scRGB ()

    int
    vips_sRGB2scRGB (VipsImage *in,
                     VipsImage **out,
                     ...);

Convert an sRGB image to scRGB. The input image can be 8 or 16-bit.

If the input image is tagged as VIPS_INTERPRETATION_RGB16, any extra channels after RGB are divided by 256. Thus, scRGB alpha is always 0 - 255.99.

See also: `vips_scRGB2XYZ()`, `vips_scRGB2sRGB()`, `vips_rad2float()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_scRGB2XYZ ()

    int
    vips_scRGB2XYZ (VipsImage *in,
                    VipsImage **out,
                    ...);

Turn XYZ to scRGB.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_HSV2sRGB ()

    int
    vips_HSV2sRGB (VipsImage *in,
                   VipsImage **out,
                   ...);

Convert HSV to sRGB.

HSV is a crude polar coordinate system for RGB images. It is provided for compatibility with other image processing systems. See `vips_Lab2LCh()` for a much better colour space.

See also: `vips_sRGB2HSV()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_sRGB2HSV ()

    int
    vips_sRGB2HSV (VipsImage *in,
                   VipsImage **out,
                   ...);

Convert to HSV.

HSV is a crude polar coordinate system for RGB images. It is provided for compatibility with other image processing systems. See `vips_Lab2LCh()` for a much better colour space.

See also: `vips_HSV2sRGB()`, `vips_Lab2LCh()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_LCh2CMC ()

    int
    vips_LCh2CMC (VipsImage *in,
                  VipsImage **out,
                  ...);

Turn LCh to CMC.

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.

This operation generates CMC(1:1). For CMC(2:1), halve Lucs and double Cucs.

See also: `vips_CMC2LCh()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_CMC2LCh ()

    int
    vips_CMC2LCh (VipsImage *in,
                  VipsImage **out,
                  ...);

Turn LCh to CMC.

See also: `vips_LCh2CMC()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_XYZ2Yxy ()

    int
    vips_XYZ2Yxy (VipsImage *in,
                  VipsImage **out,
                  ...);

Turn XYZ to Yxy.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_Yxy2XYZ ()

    int
    vips_Yxy2XYZ (VipsImage *in,
                  VipsImage **out,
                  ...);

Turn XYZ to Yxy.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_LabS2Lab ()

    int
    vips_LabS2Lab (VipsImage *in,
                   VipsImage **out,
                   ...);

Convert a LabS three-band signed short image to a three-band float image.

See also: `vips_LabS2Lab()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_Lab2LabS ()

    int
    vips_Lab2LabS (VipsImage *in,
                   VipsImage **out,
                   ...);

Turn Lab to LabS, signed 16-bit int fixed point.

See also: `vips_LabQ2Lab()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_CMYK2XYZ ()

    int
    vips_CMYK2XYZ (VipsImage *in,
                   VipsImage **out,
                   ...);

Turn CMYK to XYZ. If the image has an embedded ICC profile this will be used for the conversion. If there is no embedded profile, a generic fallback profile will be used.

Conversion is to D65 XYZ with relative intent. If you need more control over the process, use `vips_icc_import()` instead.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_XYZ2CMYK ()

    int
    vips_XYZ2CMYK (VipsImage *in,
                   VipsImage **out,
                   ...);

Turn XYZ to CMYK.

Conversion is from D65 XYZ with relative intent. If you need more control over the process, use `vips_icc_export()` instead.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_profile_load ()

    int
    vips_profile_load (const char *name,
                       VipsBlob **profile,
                       ...);

Load a named profile.

Profiles are loaded from four sources:

- The special name `"none"` means no profile. `profile` will be `NULL` in this case.

- `name` can be the name of one of the ICC profiles embedded in libvips. These names can be at least `"cmyk"`, `"p3"` and `"srgb"`.

- `name` can be the full path to a file.

- `name` can be the name of an ICC profile in the system profile directory for your platform.

#### Parameters

name | name of profile to load |
profile | loaded profile. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_icc_present ()

    int
    vips_icc_present (void);

VIPS can optionally be built without the ICC library. Use this function to test for its availability.

#### Returns

non-zero if the ICC library is present.

### vips_icc_transform ()

    int
    vips_icc_transform (VipsImage *in,
                        VipsImage **out,
                        const char *output_profile,
                        ...);

Optional arguments:

- `pcs` : VipsPCS, use XYZ or LAB PCS

- `intent` : VipsIntent, transform with this intent

- `black_point_compensation` : `gboolean`, enable black point compensation

- `embedded` : `gboolean`, use profile embedded in input image

- `input_profile` : `gchararray`, get the input profile from here

- `depth` : `gint`, depth of output image in bits

Transform an image with a pair of ICC profiles. The input image is moved to profile-connection space with the input profile and then to the output space with the output profile.

The input profile is searched for in three places:

1. If `embedded` is set, libvips will try to use any profile in the input image metadata. You can test for the presence of an embedded profile with `vips_image_get_typeof()` with VIPS_META_ICC_NAME as an argument. This will return `GType` 0 if there is no profile.

2. Otherwise, if `input_profile` is set, libvips will try to load a profile from the named file. This can aslso be the name of one of the built-in profiles.

3. Otherwise, libvips will try to pick a compatible profile from the set of built-in profiles.

If `black_point_compensation` is set, LCMS black point compensation is enabled.

`depth` defaults to 8, or 16 if `in` is a 16-bit image.

The output image has the output profile attached to the VIPS_META_ICC_NAME field.

Use `vips_icc_import()` and `vips_icc_export()` to do either the first or second half of this operation in isolation.

[method]

#### Parameters

in | input image |
out | output image. | [out]
output_profile | get the output profile from here |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_icc_import ()

    int
    vips_icc_import (VipsImage *in,
                     VipsImage **out,
                     ...);

Optional arguments:

- `pcs` : VipsPCS, use XYZ or LAB PCS

- `intent` : VipsIntent, transform with this intent

- `black_point_compensation` : `gboolean`, enable black point compensation

- `embedded` : `gboolean`, use profile embedded in input image

- `input_profile` : `gchararray`, get the input profile from here

Import an image from device space to D65 LAB with an ICC profile. If `pcs` is set to VIPS_PCS_XYZ, use CIE XYZ PCS instead.

The input profile is searched for in three places:

1. If `embedded` is set, libvips will try to use any profile in the input image metadata. You can test for the presence of an embedded profile with `vips_image_get_typeof()` with VIPS_META_ICC_NAME as an argument. This will return `GType` 0 if there is no profile.

2. Otherwise, if `input_profile` is set, libvips will try to load a profile from the named file. This can aslso be the name of one of the built-in profiles.

3. Otherwise, libvips will try to pick a compatible profile from the set of built-in profiles.

If `black_point_compensation` is set, LCMS black point compensation is enabled.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_icc_export ()

    int
    vips_icc_export (VipsImage *in,
                     VipsImage **out,
                     ...);

Optional arguments:

- `pcs` : VipsPCS, use XYZ or LAB PCS

- `intent` : VipsIntent, transform with this intent

- `black_point_compensation` : `gboolean`, enable black point compensation

- `output_profile` : `gchararray`, get the output profile from here

- `depth` : `gint`, depth of output image in bits

Export an image from D65 LAB to device space with an ICC profile. If `pcs` is set to VIPS_PCS_XYZ, use CIE XYZ PCS instead. If `output_profile` is not set, use the embedded profile, if any. If `output_profile` is set, export with that and attach it to the output image.

If `black_point_compensation` is set, LCMS black point compensation is enabled.

[method]

#### Parameters

in | input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error.

### vips_icc_ac2rc ()

    int
    vips_icc_ac2rc (VipsImage *in,
                    VipsImage **out,
                    const char *profile_filename);

Transform an image from absolute to relative colorimetry using the MediaWhitePoint stored in the ICC profile.

See also: `vips_icc_transform()`, `vips_icc_import()`.

[method]

#### Parameters

in | input image |
out | output image. | [out]
profile_filename | use this profile |

#### Returns

0 on success, -1 on error.

### vips_icc_is_compatible_profile ()

    gboolean
    vips_icc_is_compatible_profile (VipsImage *image,
                                    const void *data,
                                    size_t data_length);

### vips_dE76 ()

    int
    vips_dE76 (VipsImage *left,
               VipsImage *right,
               VipsImage **out,
               ...);

Calculate dE 76.

#### Parameters

left | first input image |
right | second input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_dE00 ()

    int
    vips_dE00 (VipsImage *left,
               VipsImage *right,
               VipsImage **out,
               ...);

Calculate dE 00.

#### Parameters

left | first input image |
right | second input image |
out | output image |
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_dECMC ()

    int
    vips_dECMC (VipsImage *left,
                VipsImage *right,
                VipsImage **out,
                ...);

Calculate dE CMC. The input images are transformed to CMC colour space and the euclidean distance between corresponding pixels calculated.

To calculate a colour difference with values for (l:c) other than (1:1), transform the two source images to CMC yourself, scale the channels appropriately, and call this function.

See also: `vips_colourspace()`

#### Parameters

left | first input image |
right | second input image |
out | output image. | [out]
... | `NULL`-terminated list of optional named arguments |

#### Returns

0 on success, -1 on error

### vips_col_Lab2XYZ ()

    void
    vips_col_Lab2XYZ (float L,
                      float a,
                      float b,
                      float *X,
                      float *Y,
                      float *Z);

Calculate XYZ from Lab, D65.

See also: `vips_Lab2XYZ()`.

#### Parameters

L | Input CIE Lab value |
a | Input CIE Lab value |
b | Input CIE Lab value |
X | Return CIE XYZ colour. | [out]
Y | Return CIE XYZ colour. | [out]
Z | Return CIE XYZ colour. | [out]

### vips_col_XYZ2Lab ()

    void
    vips_col_XYZ2Lab (float X,
                      float Y,
                      float Z,
                      float *L,
                      float *a,
                      float *b);

Calculate XYZ from Lab, D65.

See also: `vips_XYZ2Lab()`.

#### Parameters

X | Input CIE XYZ colour |
Y | Input CIE XYZ colour |
Z | Input CIE XYZ colour |
L | Return CIE Lab value. | [out]
a | Return CIE Lab value. | [out]
b | Return CIE Lab value. | [out]

### vips_col_ab2h ()

    double
    vips_col_ab2h (double a,
                   double b);

#### Parameters

a | CIE a |
b | CIE b |

#### Returns

Hue (degrees)

### vips_col_ab2Ch ()

    void
    vips_col_ab2Ch (float a,
                    float b,
                    float *C,
                    float *h);

### vips_col_Ch2ab ()

    void
    vips_col_Ch2ab (float C,
                    float h,
                    float *a,
                    float *b);

Calculate ab from Ch, h in degrees.

#### Parameters

C | Chroma |
h | Hue angle (degrees) |
a | return CIE a* value |
b | return CIE b* value |

### vips_col_L2Lcmc ()

    float
    vips_col_L2Lcmc (float L);

Calculate Lcmc from L.

#### Parameters

L | CIE L* |

#### Returns

Lcmc

### vips_col_C2Ccmc ()

    float
    vips_col_C2Ccmc (float C);

Calculate Ccmc from C.

#### Parameters

C | Chroma |

#### Returns

Ccmc.

### vips_col_Ch2hcmc ()

    float
    vips_col_Ch2hcmc (float C,
                      float h);

Calculate hcmc from C and h.

#### Parameters

C | Chroma |
h | Hue (degrees) |

#### Returns

hcmc.

### vips_col_make_tables_CMC ()

    void
    vips_col_make_tables_CMC (void);

Make the lookup tables for cmc.

### vips_col_Lcmc2L ()

    float
    vips_col_Lcmc2L (float Lcmc);

Calculate L from Lcmc using a table. Call `vips_col_make_tables_CMC()` at least once before using this function.

#### Parameters

Lcmc | L cmc |

#### Returns

L*

### vips_col_Ccmc2C ()

    float
    vips_col_Ccmc2C (float Ccmc);

Calculate C from Ccmc using a table. Call `vips_col_make_tables_CMC()` at least once before using this function.

#### Parameters

Ccmc | Ccmc |

#### Returns

C.

### vips_col_Chcmc2h ()

    float
    vips_col_Chcmc2h (float C,
                      float hcmc);

Calculate h from C and hcmc, using a table. Call `vips_col_make_tables_CMC()` at least once before using this function.

#### Parameters

C | Chroma |
hcmc | Hue cmc (degrees) |

#### Returns

h.

### vips_col_sRGB2scRGB_8 ()

    int
    vips_col_sRGB2scRGB_8 (int r,
                           int g,
                           int b,
                           float *R,
                           float *G,
                           float *B);

### vips_col_sRGB2scRGB_16 ()

    int
    vips_col_sRGB2scRGB_16 (int r,
                            int g,
                            int b,
                            float *R,
                            float *G,
                            float *B);

### vips_col_sRGB2scRGB_8_noclip ()

    int
    vips_col_sRGB2scRGB_8_noclip (int r,
                                  int g,
                                  int b,
                                  float *R,
                                  float *G,
                                  float *B);

### vips_col_sRGB2scRGB_16_noclip ()

    int
    vips_col_sRGB2scRGB_16_noclip (int r,
                                   int g,
                                   int b,
                                   float *R,
                                   float *G,
                                   float *B);

### vips_col_scRGB2XYZ ()

    int
    vips_col_scRGB2XYZ (float R,
                        float G,
                        float B,
                        float *X,
                        float *Y,
                        float *Z);

Turn scRGB into XYZ.

See also: `vips_scRGB2XYZ()`.

#### Parameters

R | Input scRGB value |
G | Input scRGB value |
B | Input scRGB value |
X | Return XYZ colour. | [out]
Y | Return XYZ colour. | [out]
Z | Return XYZ colour. | [out]

### vips_col_XYZ2scRGB ()

    int
    vips_col_XYZ2scRGB (float X,
                        float Y,
                        float Z,
                        float *R,
                        float *G,
                        float *B);

Turn XYZ into scRGB.

See also: `vips_XYZ2scRGB()`.

#### Parameters

X | Input XYZ value |
Y | Input XYZ value |
Z | Input XYZ value |
R | Return scRGB colour. | [out]
G | Return scRGB colour. | [out]
B | Return scRGB colour. | [out]

### vips_col_scRGB2sRGB_8 ()

    int
    vips_col_scRGB2sRGB_8 (float R,
                           float G,
                           float B,
                           int *r,
                           int *g,
                           int *b,
                           int *og);

### vips_col_scRGB2sRGB_16 ()

    int
    vips_col_scRGB2sRGB_16 (float R,
                            float G,
                            float B,
                            int *r,
                            int *g,
                            int *b,
                            int *og);

### vips_col_scRGB2BW_16 ()

    int
    vips_col_scRGB2BW_16 (float R,
                          float G,
                          float B,
                          int *g,
                          int *og);

### vips_col_scRGB2BW_8 ()

    int
    vips_col_scRGB2BW_8 (float R,
                         float G,
                         float B,
                         int *g,
                         int *og);

### vips_pythagoras ()

    float
    vips_pythagoras (float L1,
                     float a1,
                     float b1,
                     float L2,
                     float a2,
                     float b2);

Pythagorean distance between two points in colour space. Lab/XYZ/CMC etc.

#### Parameters

L1 | Input coordinate 1 |
a1 | Input coordinate 1 |
b1 | Input coordinate 1 |
L2 | Input coordinate 2 |
a2 | Input coordinate 2 |
b2 | Input coordinate 2 |

### vips_col_dE00 ()

    float
    vips_col_dE00 (float L1,
                   float a1,
                   float b1,
                   float L2,
                   float a2,
                   float b2);

CIEDE2000, from:

Luo, Cui, Rigg, "The Development of the CIE 2000 Colour-Difference Formula: CIEDE2000", COLOR research and application, pp 340

#### Parameters

L1 | Input coordinate 1 |
a1 | Input coordinate 1 |
b1 | Input coordinate 1 |
L2 | Input coordinate 2 |
a2 | Input coordinate 2 |
b2 | Input coordinate 2 |

#### Returns

CIE dE2000 colour difference.

## Types and Values

### VIPS_D93_X0

    #define VIPS_D93_X0 (89.7400)

Areas under curves for D93, 2 degree observer.

### VIPS_D93_Y0

    #define VIPS_D93_Y0 (100.0)

### VIPS_D93_Z0

    #define VIPS_D93_Z0 (130.7700)

### VIPS_D75_X0

    #define VIPS_D75_X0 (94.9682)

Areas under curves for D75, 2 degree observer.

### VIPS_D75_Y0

    #define VIPS_D75_Y0 (100.0)

### VIPS_D75_Z0

    #define VIPS_D75_Z0 (122.5710)

### VIPS_D65_X0

    #define VIPS_D65_X0 (95.0470)

Areas under curves for D65, 2 degree observer.

### VIPS_D65_Y0

    #define VIPS_D65_Y0 (100.0)

### VIPS_D65_Z0

    #define VIPS_D65_Z0 (108.8827)

### VIPS_D55_X0

    #define VIPS_D55_X0 (95.6831)

Areas under curves for D55, 2 degree observer.

### VIPS_D55_Y0

    #define VIPS_D55_Y0 (100.0)

### VIPS_D55_Z0

    #define VIPS_D55_Z0 (92.0871)

### VIPS_D50_X0

    #define VIPS_D50_X0 (96.4250)

Areas under curves for D50, 2 degree observer.

### VIPS_D50_Y0

    #define VIPS_D50_Y0 (100.0)

### VIPS_D50_Z0

    #define VIPS_D50_Z0 (82.4680)

### VIPS_A_X0

    #define VIPS_A_X0 (109.8503)

Areas under curves for illuminant A (2856K), 2 degree observer.

### VIPS_A_Y0

    #define VIPS_A_Y0 (100.0)

### VIPS_A_Z0

    #define VIPS_A_Z0 (35.5849)

### VIPS_B_X0

    #define VIPS_B_X0 (99.0720)

Areas under curves for illuminant B (4874K), 2 degree observer.

### VIPS_B_Y0

    #define VIPS_B_Y0 (100.0)

### VIPS_B_Z0

    #define VIPS_B_Z0 (85.2230)

### VIPS_C_X0

    #define VIPS_C_X0 (98.0700)

Areas under curves for illuminant C (6774K), 2 degree observer.

### VIPS_C_Y0

    #define VIPS_C_Y0 (100.0)

### VIPS_C_Z0

    #define VIPS_C_Z0 (118.2300)

### VIPS_E_X0

    #define VIPS_E_X0 (100.0)

Areas under curves for equal energy illuminant E.

### VIPS_E_Y0

    #define VIPS_E_Y0 (100.0)

### VIPS_E_Z0

    #define VIPS_E_Z0 (100.0)

### VIPS_D3250_X0

    #define VIPS_D3250_X0 (105.6590)

Areas under curves for black body at 3250K, 2 degree observer.

### VIPS_D3250_Y0

    #define VIPS_D3250_Y0 (100.0)

### VIPS_D3250_Z0

    #define VIPS_D3250_Z0 (45.8501)

### enum VipsIntent

The rendering intent. VIPS_INTENT_ABSOLUTE is best for scientific work, VIPS_INTENT_RELATIVE is usually best for accurate communication with other imaging libraries.

#### Members

VIPS_INTENT_PERCEPTUAL | perceptual rendering intent |
VIPS_INTENT_RELATIVE | relative colorimetric rendering intent |
VIPS_INTENT_SATURATION | saturation rendering intent |
VIPS_INTENT_ABSOLUTE | absolute colorimetric rendering intent |
VIPS_INTENT_LAST |  |

### enum VipsPCS

Pick a Profile Connection Space for `vips_icc_import()` and `vips_icc_export()`. LAB is usually best, XYZ can be more convenient in some cases.

#### Members

VIPS_PCS_LAB | use CIELAB D65 as the Profile Connection Space |
VIPS_PCS_XYZ | use XYZ as the Profile Connection Space |
VIPS_PCS_LAST |  |

## See Also

<link linkend="libvips-arithmetic">arithmetic</link>