## GimpColorSpace

GimpColorSpace — Utility functions which convert colors between different color models.

## Synopsis

                GimpHSL;
    void        gimp_rgb_to_hsv                 (const GimpRGB *rgb,
                                                 GimpHSV *hsv);
    void        gimp_rgb_to_hsl                 (const GimpRGB *rgb,
                                                 GimpHSL *hsl);
    void        gimp_rgb_to_cmyk                (const GimpRGB *rgb,
                                                 gdouble pullout,
                                                 GimpCMYK *cmyk);
    void        gimp_hsv_to_rgb                 (const GimpHSV *hsv,
                                                 GimpRGB *rgb);
    void        gimp_hsl_to_rgb                 (const GimpHSL *hsl,
                                                 GimpRGB *rgb);
    void        gimp_cmyk_to_rgb                (const GimpCMYK *cmyk,
                                                 GimpRGB *rgb);
    void        gimp_rgb_to_hwb                 (const GimpRGB *rgb,
                                                 gdouble *hue,
                                                 gdouble *whiteness,
                                                 gdouble *blackness);
    void        gimp_hwb_to_rgb                 (gdouble hue,
                                                 gdouble whiteness,
                                                 gdouble blackness,
                                                 GimpRGB *rgb);
    void        gimp_rgb_to_hsv_int             (gint *red,
                                                 gint *green,
                                                 gint *blue);
    void        gimp_hsv_to_rgb_int             (gint *hue,
                                                 gint *saturation,
                                                 gint *value);
    void        gimp_rgb_to_hsl_int             (gint *red,
                                                 gint *green,
                                                 gint *blue);
    void        gimp_rgb_to_cmyk_int            (gint *red,
                                                 gint *green,
                                                 gint *blue,
                                                 gint *pullout);
    void        gimp_cmyk_to_rgb_int            (gint *cyan,
                                                 gint *magenta,
                                                 gint *yellow,
                                                 gint *black);
    gint        gimp_rgb_to_l_int               (gint red,
                                                 gint green,
                                                 gint blue);
    void        gimp_hsl_to_rgb_int             (gint *hue,
                                                 gint *saturation,
                                                 gint *lightness);
    void        gimp_rgb_to_hsv4                (guchar *rgb,
                                                 gdouble *hue,
                                                 gdouble *saturation,
                                                 gdouble *value);
    void        gimp_hsv_to_rgb4                (guchar *rgb,
                                                 gdouble hue,
                                                 gdouble saturation,
                                                 gdouble value);

## Description

When programming pixel data manipulation functions you will often use algorithms operating on a color model different from the one GIMP uses. This file provides utility functions to convert colors between different color spaces.

## Details

### GimpHSL

    typedef struct {
      gdouble h, s, l, a;
    } GimpHSL;

### gimp_rgb_to_hsv ()

    void        gimp_rgb_to_hsv                 (const GimpRGB *rgb,
                                                 GimpHSV *hsv);

Does a conversion from RGB to HSV (Hue, Saturation, Value) colorspace.

`rgb` : | A color value in the RGB colorspace
`hsv` : | The value converted to the HSV colorspace

### gimp_rgb_to_hsl ()

    void        gimp_rgb_to_hsl                 (const GimpRGB *rgb,
                                                 GimpHSL *hsl);

Convert an RGB color value to a HSL (Hue, Saturation, Lightness) color value.

`rgb` : | A color value in the RGB colorspace
`hsl` : | The value converted to HSL

### gimp_rgb_to_cmyk ()

    void        gimp_rgb_to_cmyk                (const GimpRGB *rgb,
                                                 gdouble pullout,
                                                 GimpCMYK *cmyk);

Does a naive conversion from RGB to CMYK colorspace. A simple formula that doesn't take any color-profiles into account is used. The amount of black pullout how can be controlled via the `pullout` parameter. A `pullout` value of 0 makes this a conversion to CMY. A value of 1 causes the maximum amount of black to be pulled out.

`rgb` : | A value in the RGB colorspace
`pullout` : | A scaling value (0-1) indicating how much black should be pulled out
`cmyk` : | The input value naively converted to the CMYK colorspace

### gimp_hsv_to_rgb ()

    void        gimp_hsv_to_rgb                 (const GimpHSV *hsv,
                                                 GimpRGB *rgb);

Converts a color value from HSV to RGB colorspace

`hsv` : | A color value in the HSV colorspace
`rgb` : | The returned RGB value.

### gimp_hsl_to_rgb ()

    void        gimp_hsl_to_rgb                 (const GimpHSL *hsl,
                                                 GimpRGB *rgb);

Convert a HSL color value to an RGB color value.

`hsl` : | A color value in the HSL colorspace
`rgb` : | The value converted to a value in the RGB colorspace

### gimp_cmyk_to_rgb ()

    void        gimp_cmyk_to_rgb                (const GimpCMYK *cmyk,
                                                 GimpRGB *rgb);

Does a simple transformation from the CMYK colorspace to the RGB colorspace, without taking color profiles into account.

`cmyk` : | A color value in the CMYK colorspace
`rgb` : | The value converted to the RGB colorspace

### gimp_rgb_to_hwb ()

    void        gimp_rgb_to_hwb                 (const GimpRGB *rgb,
                                                 gdouble *hue,
                                                 gdouble *whiteness,
                                                 gdouble *blackness);

Theoretically, hue 0 (pure red) is identical to hue 6 in these transforms. Pure red always maps to 6 in this implementation. Therefore UNDEFINED can be defined as 0 in situations where only unsigned numbers are desired.

RGB are each on [0, 1]. Whiteness and Blackness are returned in the range [0, 1] and H is returned in the range [0, 6]. If W == 1 - B, H is undefined.

`rgb` : | A color value in the RGB colorspace
`hue` : | The hue value of the above color, in the range 0 to 6
`whiteness` : | The whiteness value of the above color, in the range 0 to 1
`blackness` : | The blackness value of the above color, in the range 0 to 1

### gimp_hwb_to_rgb ()

    void        gimp_hwb_to_rgb                 (gdouble hue,
                                                 gdouble whiteness,
                                                 gdouble blackness,
                                                 GimpRGB *rgb);

H is defined in the range [0, 6] or UNDEFINED, B and W are both in the range [0, 1]. The returned RGB values are all in the range [0, 1].

`hue` : | A hue value, in the range 0 to 6
`whiteness` : | A whiteness value, in the range 0 to 1
`blackness` : | A blackness value, in the range 0 to 1
`rgb` : | The above color converted to the RGB colorspace

### gimp_rgb_to_hsv_int ()

    void        gimp_rgb_to_hsv_int             (gint *red,
                                                 gint *green,
                                                 gint *blue);

The arguments are pointers to int representing channel values in the RGB colorspace, and the values pointed to are all in the range [0, 255].

The function changes the arguments to point to the HSV value corresponding, with the returned values in the following ranges: H [0, 360], S [0, 255], V [0, 255].

`red` : | The red channel value, returns the Hue channel
`green` : | The green channel value, returns the Saturation channel
`blue` : | The blue channel value, returns the Value channel

### gimp_hsv_to_rgb_int ()

    void        gimp_hsv_to_rgb_int             (gint *hue,
                                                 gint *saturation,
                                                 gint *value);

The arguments are pointers to int, with the values pointed to in the following ranges: H [0, 360], S [0, 255], V [0, 255].

The function changes the arguments to point to the RGB value corresponding, with the returned values all in the range [0, 255].

`hue` : | The hue channel, returns the red channel
`saturation` : | The saturation channel, returns the green channel
`value` : | The value channel, returns the blue channel

### gimp_rgb_to_hsl_int ()

    void        gimp_rgb_to_hsl_int             (gint *red,
                                                 gint *green,
                                                 gint *blue);

The arguments are pointers to int representing channel values in the RGB colorspace, and the values pointed to are all in the range [0, 255].

The function changes the arguments to point to the corresponding HLS value with the values pointed to in the following ranges: H [0, 360], L [0, 255], S [0, 255].

`red` : | Red channel, returns Hue channel
`green` : | Green channel, returns Lightness channel
`blue` : | Blue channel, returns Saturation channel

### gimp_rgb_to_cmyk_int ()

    void        gimp_rgb_to_cmyk_int            (gint *red,
                                                 gint *green,
                                                 gint *blue,
                                                 gint *pullout);

Does a naive conversion from RGB to CMYK colorspace. A simple formula that doesn't take any color-profiles into account is used. The amount of black pullout how can be controlled via the `pullout` parameter. A `pullout` value of 0 makes this a conversion to CMY. A value of 100 causes the maximum amount of black to be pulled out.

`red` : | the red channel; returns the cyan value (0-255)
`green` : | the green channel; returns the magenta value (0-255)
`blue` : | the blue channel; returns the yellow value (0-255)
`pullout` : | the percentage of black to pull out (0-100); returns the black value (0-255)

### gimp_cmyk_to_rgb_int ()

    void        gimp_cmyk_to_rgb_int            (gint *cyan,
                                                 gint *magenta,
                                                 gint *yellow,
                                                 gint *black);

Does a naive conversion from CMYK to RGB colorspace. A simple formula that doesn't take any color-profiles into account is used.

`cyan` : | the cyan channel; returns the red value (0-255)
`magenta` : | the magenta channel; returns the green value (0-255)
`yellow` : | the yellow channel; returns the blue value (0-255)
`black` : | the black channel (0-255); doesn't change

### gimp_rgb_to_l_int ()

    gint        gimp_rgb_to_l_int               (gint red,
                                                 gint green,
                                                 gint blue);

Calculates the lightness value of an RGB triplet with the formula L = (max(R, G, B) + min (R, G, B)) / 2

`red` : | Red channel
`green` : | Green channel
`blue` : | Blue channel
Returns : | Luminance vaue corresponding to the input RGB value

### gimp_hsl_to_rgb_int ()

    void        gimp_hsl_to_rgb_int             (gint *hue,
                                                 gint *saturation,
                                                 gint *lightness);

The arguments are pointers to int, with the values pointed to in the following ranges: H [0, 360], L [0, 255], S [0, 255].

The function changes the arguments to point to the RGB value corresponding, with the returned values all in the range [0, 255].

`hue` : | Hue channel, returns Red channel
`saturation` : | Saturation channel, returns Green channel
`lightness` : | Lightness channel, returns Blue channel

### gimp_rgb_to_hsv4 ()

    void        gimp_rgb_to_hsv4                (guchar *rgb,
                                                 gdouble *hue,
                                                 gdouble *saturation,
                                                 gdouble *value);

`rgb` : | RGB triplet, rgb[0] is red channel, rgb[1] is green, rgb[2] is blue (0..255)
`hue` : | Pointer to hue channel (0..1)
`saturation` : | Pointer to saturation channel (0..1)
`value` : | Pointer to value channel (0..1)

### gimp_hsv_to_rgb4 ()

    void        gimp_hsv_to_rgb4                (guchar *rgb,
                                                 gdouble hue,
                                                 gdouble saturation,
                                                 gdouble value);

`rgb` : | RGB triplet, rgb[0] is red channel, rgb[1] is green, rgb[2] is blue (0..255)
`hue` : | Hue channel (0..1)
`saturation` : | Saturation channel (0..1)
`value` : | Value channel (0..1)