Module Gg.Color

Colors and color profiles.

Color provides some function to operate on color values and basic support for ICC based color profiles to precisely specify how to interpret raw color samples.

References.

Constructors, accessors and constants

type t = color

The type for colors in a device independent RGB color space with an alpha component. The color space is defined by a D65 white point and the ITU-R BT.709 primaries (corresponds to a linearized sRGB space). The alpha component represent the color's opacity ranging from 0., a fully transparent color, to 1. a completly opaque one.

type stops = (float * color) list

The type for color stops. A piecewise linear color curve.

val v : float -> float -> float -> float -> color

v r g b a is the linear sRGB color (r, g, b, a) as a color value.

val v_srgb : ?a:float -> float -> float -> float -> color

v r g b ~a is the sRGB color (r, g, b, a) converted to a Gg color value.

val v_srgbi : ?a:float -> int -> int -> int -> color

v_srgbi r g b ~a is the 24-bit sRGB color (r, g, b, a) converted to a Gg color value by (v_srgb (float r /. 255.) (float g /. 255.) (float b /. 255.) ~a)

val r : color -> float

r c is the red component of c.

val g : color -> float

g c is the green component of c.

val b : color -> float

b c is the blue component of c.

val a : color -> float

a c is the alpha component of c.

val void : color

void is (v 0. 0. 0. 0.) an invisible color.

val black : color

black is (v 0. 0. 0. 1.)

val gray : ?a:float -> float -> color

gray a g is the sRGB color (g, g, g, a) converted to color a value.

val white : color

white is (v 1. 1. 1. 1.)

val red : color

red is (v 1. 0. 0. 1.)

val green : color

green is (v 0. 1. 0. 1.)

val blue : color

blue is (v 0. 0. 1. 1.)

Functions

val blend : color -> color -> color

blend src dst is src blended over dst using source over destination alpha blending. See Alvy Ray Smith. Image compositing fundamentals. 1995.

val clamp : color -> color

clamp c is c with all components clamped to [0;1]. nan components are left untouched.

val with_a : color -> float -> color

with_a c a is the same color as c but with the alpha component a.

Color conversions

Note. In the following conversions all color spaces carry an alpha component. The alpha component is always left untouched by the conversions.

WARNING. Converting between color spaces may result in out of gamut colors whose components are out of the destination color space expected ranges. The client is responsible to handle these; for values of type color simply clamping these is one option. Currently some conversion do not even round trip due to floating point inaccuracies, see this issue, so it is a good idea to clamp the conversions to color.

sRGB

type srgb = v4

The type for colors in the sRGB color space with an alpha component. This is the color space used, for example, by CSS.

val of_srgb : srgb -> color

of_srgb c is the sRGB color c as a Gg color.

val to_srgb : color -> srgb

to_srgb c is the Gg color c as a sRGB color.

val to_srgbi : color -> int * int * int * float

to_srgbi c is the Gg color c as a 24-bit sRGB color (r, g, b, a), see v_srgbi.

Oklab

type oklab = v4

The type for colors in the Oklab color space with an alpha component. The meaning and range of components is:

  • L is the perceived lightness in the range 0. to 1.
  • a is how green/red the color is, unbounded but typical range in -0.5 to 0.5
  • b is how blue/yellow the color is, unbounded but typical range in -0.5 to 0.5

Note that euclidian distance between two oklab colors can be used as a perceptual color difference metric. A JND is a difference of 0.02 (ref).

val of_oklab : oklab -> color

of_oklab c is the Oklab color c as a Gg color.

val to_oklab : color -> oklab

to_oklab c is the Gg color c as an Oklab color.

Oklch

type oklch = v4

The type for colors in the Oklch color space with an alpha component. This is a polar form of Oklab. The meaning and range of components is:

  • L is the perceived lightness in the range 0. to 1.
  • C is the chroma in the range 0. to unbounded but typically 0.5
  • h is the hue in radians in the range 0. to 2pi.
val of_oklch : oklch -> color

of_oklch c is the Oklch color c as a Gg color.

val to_oklch : color -> oklch

to_oklch c is the Gg color c as an Oklch color.

CIE L*u*v*

type luv = v4

The type for colors in the CIE L*u*v* color space with a D65 reference white point and an alpha component. The meaning and range of the components is:

  • L* is lightness in the range 0. to 100.
  • u*'s practical range is -134. to 220.
  • v*'s practical range is -140. to 122.
val of_luv : luv -> color

of_luv c is the L*u*v* color c as a Gg color.

val to_luv : color -> luv

to_luv c is the Gg color c as a L*u*v* color.

CIE L*C*huv

type lch_uv = v4

The type for colors in the CIE L*C*huv color space with a D65 reference white point and an alpha component. This color space is CIE L*u*v* with polar coordinates, the meaning and range of the components is:

  • L* is the lightness in the range 0. to 100.
  • C* represents chroma, in the range 0. to 260.77 in practice.
  • h represents hue in radians in the range 0. to 2pi.
val of_lch_uv : lch_uv -> color

of_lch_uv c is the L*C*huv color c as a Gg color.

val to_lch_uv : color -> lch_uv

to_lch_uv c is the Gg color c as a L*C*huv.

CIE L*a*b*

type lab = v4

The type for colors in the CIE L*a*b* color space with a D50 reference white point and an alpha component. The meaning and range of the components is:

  • L* is lightness in the range 0. to 100.
  • a* and b*'s practical range is -128. to 127.
val of_lab : v4 -> color

of_lab c is the L*a*b* color c as a Gg color value.

val to_lab : color -> v4

to_lab c is the Gg color c as a L*a*b* color.

CIE L*C*hab

type lch_ab = v4

The type for colors in the CIE L*C*h*ab color space with a D50 reference white point and an alpha component. This color space is CIE L*a*b* with polar coordinates, the meaning and range of the components is:

  • L* is the lightness in the range 0. to 100.
  • C* represents chroma, in the range 0. to 181.02, but less in practice.
  • h represents hue in degrees in the range 0. to 2pi.
val of_lch_ab : lch_ab -> color

of_lch_ab c is the L*C*hab color c as a Gg color.

val to_lch_ab : color -> lch_ab

to_lch_ab c is the Gg color c as a L*C*hab.

Color spaces

type space = [
  1. | `XYZ
  2. | `Lab
  3. | `Luv
  4. | `YCbr
  5. | `Yxy
  6. | `RGB
  7. | `Gray
  8. | `HSV
  9. | `HLS
  10. | `CMYK
  11. | `CMY
  12. | `CLR2
  13. | `CLR3
  14. | `CLR4
  15. | `CLR5
  16. | `CLR6
  17. | `CLR7
  18. | `CLR8
  19. | `CLR9
  20. | `CLRA
  21. | `CLRB
  22. | `CLRC
  23. | `CLRD
  24. | `CLRE
  25. | `CLRF
]

The type for color spaces. These correspond to the ICC v4 supported color space, see the specification, section 7.2.6.

val space_dim : space -> int

space_dim s is the dimension of the color space s.

val pp_space : Stdlib.Format.formatter -> space -> unit

pp_space s prints a textual representation of s on ppf.

Color profiles

type profile

The type for ICC color profiles. A color profile can describe the characteristics of a color space, an input or output device and provide a mapping to a profile connection space (PCS), which is either CIE L*a*b* or XYZ with a D50 white point. For more information about ICC profile consult the ICC FAQ and the ICC v4 specification.

This module defines only a profile for the color space of color and a grayscale color space.

val profile_of_icc : string -> profile option

profile_of_icc s is a profile from the ICC profile byte stream s. None is returned if s doesn't seem to be a ICC profile.

Note A profile value is returned if a color space can be extracted, it doesn't guarantee a correct ICC profile byte stream.

val profile_to_icc : profile -> string

profile_to_icc p is p's ICC profile byte stream.

val profile_space : profile -> space

profile_space p is p's color space.

val profile_dim : profile -> int

profile_space p is space_dim (profile_space d).

val p_gray_l : profile

p_gray_l is a linear gray color profile

val p_rgb_l : profile

p_rgb_l is the color profile of color values.