## colour

colour — colour operators

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <vips/vips.h>

    #define             IM_D93_X0
    #define             IM_D93_Y0
    #define             IM_D93_Z0
    #define             IM_D75_X0
    #define             IM_D75_Y0
    #define             IM_D75_Z0
    #define             IM_D65_X0
    #define             IM_D65_Y0
    #define             IM_D65_Z0
    #define             IM_D55_X0
    #define             IM_D55_Y0
    #define             IM_D55_Z0
    #define             IM_D50_X0
    #define             IM_D50_Y0
    #define             IM_D50_Z0
    #define             IM_A_X0
    #define             IM_A_Y0
    #define             IM_A_Z0
    #define             IM_B_X0
    #define             IM_B_Y0
    #define             IM_B_Z0
    #define             IM_C_X0
    #define             IM_C_Y0
    #define             IM_C_Z0
    #define             IM_E_X0
    #define             IM_E_Y0
    #define             IM_E_Z0
    #define             IM_D3250_X0
    #define             IM_D3250_Y0
    #define             IM_D3250_Z0
    void                im_col_ab2Ch                        (float a,
                                                             float b,
                                                             float *C,
                                                             float *h);
    void                im_col_Ch2ab                        (float C,
                                                             float h,
                                                             float *a,
                                                             float *b);
    void                im_col_XYZ2Lab                      (float X,
                                                             float Y,
                                                             float Z,
                                                             float *L,
                                                             float *a,
                                                             float *b);
    void                im_col_Lab2XYZ                      (float L,
                                                             float a,
                                                             float b,
                                                             float *X,
                                                             float *Y,
                                                             float *Z);
    float               im_col_pythagoras                   (float L1,
                                                             float a1,
                                                             float b1,
                                                             float L2,
                                                             float a2,
                                                             float b2);
    void                im_col_make_tables_UCS              (void);
    float               im_col_L2Lucs                       (float L);
    float               im_col_Lucs2L                       (float Lucs);
    float               im_col_C2Cucs                       (float C);
    float               im_col_Cucs2C                       (float Cucs);
    float               im_col_Ch2hucs                      (float C,
                                                             float h);
    float               im_col_Chucs2h                      (float C,
                                                             float hucs);
    double              im_col_ab2h                         (double a,
                                                             double b);
    float               im_col_dECMC                        (float L1,
                                                             float a1,
                                                             float b1,
                                                             float L2,
                                                             float a2,
                                                             float b2);
    float               im_col_dE00                         (float L1,
                                                             float a1,
                                                             float b1,
                                                             float L2,
                                                             float a2,
                                                             float b2);
    int                 im_LCh2Lab                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_LabQ2XYZ                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_rad2float                        (VipsImage *in,
                                                             VipsImage *out);
    int                 im_float2rad                        (VipsImage *in,
                                                             VipsImage *out);
    int                 im_LCh2UCS                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_Lab2LCh                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_Lab2LabQ                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_Lab2LabS                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_Lab2XYZ                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_Lab2XYZ_temp                     (VipsImage *in,
                                                             VipsImage *out,
                                                             double X0,
                                                             double Y0,
                                                             double Z0);
    int                 im_Lab2UCS                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_LabQ2Lab                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_LabQ2LabS                        (VipsImage *in,
                                                             VipsImage *out);
    int                 im_LabS2LabQ                        (VipsImage *in,
                                                             VipsImage *out);
    int                 im_LabS2Lab                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_UCS2XYZ                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_UCS2LCh                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_UCS2Lab                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_XYZ2Lab                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_XYZ2Lab_temp                     (VipsImage *in,
                                                             VipsImage *out,
                                                             double X0,
                                                             double Y0,
                                                             double Z0);
    int                 im_XYZ2UCS                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_sRGB2XYZ                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_XYZ2sRGB                         (VipsImage *in,
                                                             VipsImage *out);
    int                 im_Yxy2XYZ                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_XYZ2Yxy                          (VipsImage *in,
                                                             VipsImage *out);
    int                 im_dECMC_fromLab                    (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_dE00_fromLab                     (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_dE_fromXYZ                       (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_dE_fromLab                       (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);
    int                 im_lab_morph                        (VipsImage *in,
                                                             VipsImage *out,
                                                             DOUBLEMASK *mask,
                                                             double L_offset,
                                                             double L_scale,
                                                             double a_scale,
                                                             double b_scale);
    enum                VipsIntent;
    int                 im_icc_present                      (void);
    int                 im_icc_transform                    (VipsImage *in,
                                                             VipsImage *out,
                                                             const char *input_profile_filename,
                                                             const char *output_profile_filename,
                                                             VipsIntent intent);
    int                 im_icc_import                       (VipsImage *in,
                                                             VipsImage *out,
                                                             const char *input_profile_filename,
                                                             VipsIntent intent);
    int                 im_icc_import_embedded              (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsIntent intent);
    int                 im_icc_export_depth                 (VipsImage *in,
                                                             VipsImage *out,
                                                             int depth,
                                                             const char *output_profile_filename,
                                                             VipsIntent intent);
    int                 im_icc_ac2rc                        (VipsImage *in,
                                                             VipsImage *out,
                                                             const char *profile_filename);

## Description

These operators let you transform coordinates and images between colour spaces, calculate colour differences, and move to and from device spaces.

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: RGB (also referred to as disp), sRGB, XYZ, Yxy, Lab, LabQ, LabS, LCh and UCS). 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:

The colour spaces supported by VIPS are:

- `LabQ`

  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.

  You cannot perform calculations on `LabQ` images (they are tagged with `IM_CODING_LABQ`), though a few operations such as `im_extract_area()` will work directly with them.

- `LabS`

  This format represents coordinates in CIELAB space as a three-band IM_BANDFMT_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`

  Lab colourspace represents CIELAB colour values with a three-band IM_BANDFMT_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 uses D65 LAB, but you can use other colour temperatures with a little effort, see `im_XYZ2Lab_temp()`.

- `XYZ`

  CIE XYZ colour space represented as a three-band `IM_BANDFMT_FLOAT` image.

- `Yxy`

  CIE Yxy colour space represented as a three-band `IM_BANDFMT_FLOAT` image.

- `RGB`

  (also refered to as `disp`+) This is a generic 8-bit RGB image. VIPS has a system for going to and from RGB with a simple display structure, but it's mostly deprecated. See disp.

  Use `im_icc_export()` and friends as a modern replacement.

- `LCh`

  Like `Lab`, but rectangular `ab` coordinates are replaced with polar `Ch` (Chroma and hue) coordinates. Hue angles are expressed in degrees.

- `UCS`

  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. Conversions to and from `UCS` are extremely slow.

## Details

### IM_D93_X0

    #define IM_D93_X0 (89.7400)

Areas under curves for D93, 2 degree observer.

### IM_D93_Y0

    #define IM_D93_Y0 (100.0)

### IM_D93_Z0

    #define IM_D93_Z0 (130.7700)

### IM_D75_X0

    #define IM_D75_X0 (94.9682)

Areas under curves for D75, 2 degree observer.

### IM_D75_Y0

    #define IM_D75_Y0 (100.0)

### IM_D75_Z0

    #define IM_D75_Z0 (122.5710)

### IM_D65_X0

    #define IM_D65_X0 (95.0470)

Areas under curves for D65, 2 degree observer.

### IM_D65_Y0

    #define IM_D65_Y0 (100.0)

### IM_D65_Z0

    #define IM_D65_Z0 (108.8827)

### IM_D55_X0

    #define IM_D55_X0 (95.6831)

Areas under curves for D55, 2 degree observer.

### IM_D55_Y0

    #define IM_D55_Y0 (100.0)

### IM_D55_Z0

    #define IM_D55_Z0 (92.0871)

### IM_D50_X0

    #define IM_D50_X0 (96.4250)

Areas under curves for D50, 2 degree observer.

### IM_D50_Y0

    #define IM_D50_Y0 (100.0)

### IM_D50_Z0

    #define IM_D50_Z0 (82.4680)

### IM_A_X0

    #define IM_A_X0 (109.8503)

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

### IM_A_Y0

    #define IM_A_Y0 (100.0)

### IM_A_Z0

    #define IM_A_Z0 (35.5849)

### IM_B_X0

    #define IM_B_X0 (99.0720)

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

### IM_B_Y0

    #define IM_B_Y0 (100.0)

### IM_B_Z0

    #define IM_B_Z0 (85.2230)

### IM_C_X0

    #define IM_C_X0 (98.0700)

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

### IM_C_Y0

    #define IM_C_Y0 (100.0)

### IM_C_Z0

    #define IM_C_Z0 (118.2300)

### IM_E_X0

    #define IM_E_X0 (100.0)

Areas under curves for equal energy illuminant E.

### IM_E_Y0

    #define IM_E_Y0 (100.0)

### IM_E_Z0

    #define IM_E_Z0 (100.0)

### IM_D3250_X0

    #define IM_D3250_X0 (105.6590)

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

### IM_D3250_Y0

    #define IM_D3250_Y0 (100.0)

### IM_D3250_Z0

    #define IM_D3250_Z0 (45.8501)

### im_col_ab2Ch ()

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

Calculate Ch from ab, h in degrees.

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

### im_col_Ch2ab ()

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

Calculate ab from Ch, h in degrees.

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

### im_col_XYZ2Lab ()

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

Calculate Lab from XYZ, D65.

See also: `im_XYZ2Lab_temp()`.

`X` : | Input CIE XYZ colour
`Y` : | Input CIE XYZ colour
`Z` : | Input CIE XYZ colour
`L` : | return CIE Lab value
`a` : | return CIE Lab value
`b` : | return CIE Lab value

### im_col_Lab2XYZ ()

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

Calculate XYZ from Lab, D65.

See also: `im_Lab2XYZ_temp()`.

`L` : | Input CIE Lab value
`a` : | Input CIE Lab value
`b` : | Input CIE Lab value
`X` : | Return CIE XYZ colour
`Y` : | Return CIE XYZ colour
`Z` : | Return CIE XYZ colour

### im_col_pythagoras ()

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

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

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

### im_col_make_tables_UCS ()

    void                im_col_make_tables_UCS              (void);

Make the lookup tables for ucs.

### im_col_L2Lucs ()

    float               im_col_L2Lucs                       (float L);

Calculate Lucs from L.

`L` : | CIE L*
Returns : | Lucs

### im_col_Lucs2L ()

    float               im_col_Lucs2L                       (float Lucs);

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

`Lucs` : | L ucs
Returns : | L*

### im_col_C2Cucs ()

    float               im_col_C2Cucs                       (float C);

Calculate Cucs from C.

`C` : | Chroma
Returns : | Cucs.

### im_col_Cucs2C ()

    float               im_col_Cucs2C                       (float Cucs);

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

`Cucs` : | Cucs
Returns : | C.

### im_col_Ch2hucs ()

    float               im_col_Ch2hucs                      (float C,
                                                             float h);

Calculate hucs from C and h.

`C` : | Chroma
`h` : | Hue (degrees)
Returns : | hucs.

### im_col_Chucs2h ()

    float               im_col_Chucs2h                      (float C,
                                                             float hucs);

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

`C` : | Chroma
`hucs` : | Hue ucs (degrees)
Returns : | h.

### im_col_ab2h ()

    double              im_col_ab2h                         (double a,
                                                             double b);

`a` : | CIE a
`b` : | CIE b
Returns : | Hue (degrees)

### im_col_dECMC ()

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

CMC colour difference from a pair of Lab values.

`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 : | CMC(1:1) colour difference

### im_col_dE00 ()

    float               im_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

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

### im_LCh2Lab ()

    int                 im_LCh2Lab                          (VipsImage *in,
                                                             VipsImage *out);

Turn LCh to Lab.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_LabQ2XYZ ()

    int                 im_LabQ2XYZ                         (VipsImage *in,
                                                             VipsImage *out);

Convert an image from LabQ (Coding == IM_CODING_LABQ) to XYZ.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_rad2float ()

    int                 im_rad2float                        (VipsImage *in,
                                                             VipsImage *out);

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

See also: `im_rad2float()`, `im_LabQ2LabS()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_float2rad ()

    int                 im_float2rad                        (VipsImage *in,
                                                             VipsImage *out);

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

See also: `im_rad2float()`, VipsFormatRad, `im_LabQ2Lab()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_LCh2UCS ()

    int                 im_LCh2UCS                          (VipsImage *in,
                                                             VipsImage *out);

Turn LCh to UCS.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_Lab2LCh ()

    int                 im_Lab2LCh                          (VipsImage *in,
                                                             VipsImage *out);

Turn Lab to LCh.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_Lab2LabQ ()

    int                 im_Lab2LabQ                         (VipsImage *in,
                                                             VipsImage *out);

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

See also: `im_LabQ2Lab()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_Lab2LabS ()

    int                 im_Lab2LabS                         (VipsImage *in,
                                                             VipsImage *out);

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

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_Lab2XYZ ()

    int                 im_Lab2XYZ                          (VipsImage *in,
                                                             VipsImage *out);

Turn D65 Lab to XYZ.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_Lab2XYZ_temp ()

    int                 im_Lab2XYZ_temp                     (VipsImage *in,
                                                             VipsImage *out,
                                                             double X0,
                                                             double Y0,
                                                             double Z0);

Turn Lab to XYZ. `X0`, `y0`, `Z0` give the Lab colour temperature.

`in` : | input image
`out` : | output image
`X0` : | colour temperature
`Y0` : | colour temperature
`Z0` : | colour temperature
Returns : | 0 on success, -1 on error.

### im_Lab2UCS ()

    int                 im_Lab2UCS                          (VipsImage *in,
                                                             VipsImage *out);

Convert an image from Lab to UCS.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_LabQ2Lab ()

    int                 im_LabQ2Lab                         (VipsImage *in,
                                                             VipsImage *out);

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

See also: `im_LabQ2Lab()`, `im_LabQ2LabS()`, `im_rad2float()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_LabQ2LabS ()

    int                 im_LabQ2LabS                        (VipsImage *in,
                                                             VipsImage *out);

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

See also: `im_LabS2LabQ()`, `im_LabQ2Lab()`, `im_rad2float()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_LabS2LabQ ()

    int                 im_LabS2LabQ                        (VipsImage *in,
                                                             VipsImage *out);

Convert a LabS three-band signed short image to LabQ

See also: `im_LabQ2LabS()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_LabS2Lab ()

    int                 im_LabS2Lab                         (VipsImage *in,
                                                             VipsImage *out);

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

See also: `im_Lab2LabS()`.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_UCS2XYZ ()

    int                 im_UCS2XYZ                          (VipsImage *in,
                                                             VipsImage *out);

Convert an image from UCS to XYZ.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_UCS2LCh ()

    int                 im_UCS2LCh                          (VipsImage *in,
                                                             VipsImage *out);

Turn UCS to LCh.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_UCS2Lab ()

    int                 im_UCS2Lab                          (VipsImage *in,
                                                             VipsImage *out);

Convert an image from UCS to Lab.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_XYZ2Lab ()

    int                 im_XYZ2Lab                          (VipsImage *in,
                                                             VipsImage *out);

Turn XYZ to D65 Lab.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_XYZ2Lab_temp ()

    int                 im_XYZ2Lab_temp                     (VipsImage *in,
                                                             VipsImage *out,
                                                             double X0,
                                                             double Y0,
                                                             double Z0);

Turn XYZ to Lab. `X0`, `y0`, `Z0` give the Lab colour temperature.

`in` : | input image
`out` : | output image
`X0` : | colour temperature
`Y0` : | colour temperature
`Z0` : | colour temperature
Returns : | 0 on success, -1 on error.

### im_XYZ2UCS ()

    int                 im_XYZ2UCS                          (VipsImage *in,
                                                             VipsImage *out);

### im_sRGB2XYZ ()

    int                 im_sRGB2XYZ                         (VipsImage *in,
                                                             VipsImage *out);

Convert an image from sRGB to XYZ. The conversion is supposed to be quick rather than accurate. Use an ICC profile with `im_icc_transform()` for more precision.

See also: im_icc_transform.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_XYZ2sRGB ()

    int                 im_XYZ2sRGB                         (VipsImage *in,
                                                             VipsImage *out);

Convert an image from XYZ to sRGB. The conversion is supposed to be quick rather than accurate. Use an ICC profile with `im_icc_transform()` for more precision.

See also: im_icc_transform.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_Yxy2XYZ ()

    int                 im_Yxy2XYZ                          (VipsImage *in,
                                                             VipsImage *out);

Turn Yxy to XYZ.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_XYZ2Yxy ()

    int                 im_XYZ2Yxy                          (VipsImage *in,
                                                             VipsImage *out);

Turn XYZ to Yxy.

`in` : | input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_dECMC_fromLab ()

    int                 im_dECMC_fromLab                    (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);

Calculate dE CMC from two Lab images.

`in1` : | first input image
`in2` : | second input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_dE00_fromLab ()

    int                 im_dE00_fromLab                     (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);

Calculate CIE dE00 from two Lab images.

`in1` : | first input image
`in2` : | second input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_dE_fromXYZ ()

    int                 im_dE_fromXYZ                       (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);

Calculate CIELAB dE 1976 from a pair of XYZ images.

`in1` : | first input image
`in2` : | second input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_dE_fromLab ()

    int                 im_dE_fromLab                       (VipsImage *in1,
                                                             VipsImage *in2,
                                                             VipsImage *out);

Calculate CIE dE 1976 from two Lab images.

`in1` : | first input image
`in2` : | second input image
`out` : | output image
Returns : | 0 on success, -1 on error.

### im_lab_morph ()

    int                 im_lab_morph                        (VipsImage *in,
                                                             VipsImage *out,
                                                             DOUBLEMASK *mask,
                                                             double L_offset,
                                                             double L_scale,
                                                             double a_scale,
                                                             double b_scale);

Morph an image in CIELAB colour space. Useful for certain types of gamut mapping, or correction of greyscales on some printers.

We perform three adjustments:

- cast

  Pass in `mask` containing CIELAB readings for a neutral greyscale. For example:

  3 | 4 |
  14.23 | 4.8 | -3.95
  18.74 | 2.76 | -2.62
  23.46 | 1.4 | -1.95
  27.53 | 1.76 | -2.01

  Interpolation from this makes cast corrector. The top and tail are interpolated towards [0, 0, 0] and [100, 0, 0], intermediate values are interpolated along straight lines fitted between the specified points. Rows may be in any order (ie. they need not be sorted on L*).

  Each pixel is displaced in a/b by the amount specified for that L in the table.

- L*

  Pass in scale and offset for L. L' = (L + offset) * scale.

- saturation

  scale a and b by these amounts, eg. 1.5 increases saturation.

Find the top two by generating and printing a greyscale. Find the bottom by printing a Macbeth and looking at a/b spread

`in` : | input image
`out` : | output image
`mask` : | cast correction table
`L_offset` : | L adjustment
`L_scale` : | L adjustment
`a_scale` : | a scale
`b_scale` : | b scale
Returns : | 0 on success, -1 on error.

### enum VipsIntent

    typedef enum {
    	IM_INTENT_PERCEPTUAL = 0,
    	IM_INTENT_RELATIVE_COLORIMETRIC,
    	IM_INTENT_SATURATION,
    	IM_INTENT_ABSOLUTE_COLORIMETRIC
    } VipsIntent;

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

`IM_INTENT_PERCEPTUAL` | perceptual rendering intent
`IM_INTENT_RELATIVE_COLORIMETRIC` | relative colorimetric rendering intent
`IM_INTENT_SATURATION` | saturation rendering intent
`IM_INTENT_ABSOLUTE_COLORIMETRIC` | absolute colorimetric rendering intent

### im_icc_present ()

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

### im_icc_transform ()

    int                 im_icc_transform                    (VipsImage *in,
                                                             VipsImage *out,
                                                             const char *input_profile_filename,
                                                             const char *output_profile_filename,
                                                             VipsIntent intent);

Transform an image with the ICC library. The input image is moved to profile-connection space with the input profile and then to the output space with the output profile.

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

See also: `im_icc_import()`, `im_icc_export_depth()`.

`in` : | input image
`out` : | output image
`input_profile_filename` : | get the input profile from here
`output_profile_filename` : | get the output profile from here
`intent` : | transform with this intent
Returns : | 0 on success, -1 on error.

### im_icc_import ()

    int                 im_icc_import                       (VipsImage *in,
                                                             VipsImage *out,
                                                             const char *input_profile_filename,
                                                             VipsIntent intent);

Import an image with the ICC library. The input image in device space is moved to D65 LAB with the input profile.

See also: `im_icc_transform()`, `im_icc_import_embedded()`.

`in` : | input image
`out` : | output image
`input_profile_filename` : | get the input profile from here
`intent` : | transform with this intent
Returns : | 0 on success, -1 on error.

### im_icc_import_embedded ()

    int                 im_icc_import_embedded              (VipsImage *in,
                                                             VipsImage *out,
                                                             VipsIntent intent);

Import an image with the ICC library. The input image in device space is moved to D65 LAB with the input profile attached to the image under the name IM_META_ICC_NAME.

See also: `im_icc_transform()`, `im_icc_import()`.

`in` : | input image
`out` : | output image
`intent` : | transform with this intent
Returns : | 0 on success, -1 on error.

### im_icc_export_depth ()

    int                 im_icc_export_depth                 (VipsImage *in,
                                                             VipsImage *out,
                                                             int depth,
                                                             const char *output_profile_filename,
                                                             VipsIntent intent);

Export an image with the ICC library. The input image in D65 LAB is transformed to device space using the supplied profile. `depth` can be 8 or 16, for 8 or 16-bit image export.

See also: `im_icc_transform()`, `im_icc_import()`.

`in` : | input image
`out` : | output image
`depth` : | depth to export at
`output_profile_filename` : | use this profile
`intent` : | transform with this intent
Returns : | 0 on success, -1 on error.

### im_icc_ac2rc ()

    int                 im_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: `im_icc_transform()`, `im_icc_import()`.

`in` : | input image
`out` : | output image
`profile_filename` : | use this profile
Returns : | 0 on success, -1 on error.

## See Also

arithmetic