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.

Charles Poynton. Frequently asked questions about color. 2006
Charles Poynton. A guided tour of color space. 1997
Bruce MacEvoy. Color vision and modern color models.
International Color Consortium. ICC.1:2010-12 Image technology colour management - Architecture, profile format, and data structure. 2010.

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.

CIE Luv*

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 LCh_uv

type lch_uv = v4

The type for colors in the CIE L*C*h_uv 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 degrees in the range 0. to 2pi.

val of_lch_uv : lch_uv -> color: of_lch_uv c is the L*C*h_uv 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*h_uv.

CIE Lab*

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 LCh_ab

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

Color spaces

type space = [ | `XYZ | `Lab | `Luv | `YCbr | `Yxy | `RGB | `Gray | `HSV | `HLS | `CMYK | `CMY | `CLR2 | `CLR3 | `CLR4 | `CLR5 | `CLR6 | `CLR7 | `CLR8 | `CLR9 | `CLRA | `CLRB | `CLRC | `CLRD | `CLRE | `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.