Collaboration diagram for Color Manipulation:

Modules
	HSI Color Coordinate System Conversions
Functions
double	imColorZeroShift (int data_type)
int	imColorMax (int data_type)
int	imColorMin (int data_type)
template<class T , class R >
T	imColorQuantize (const R &value, const T &min, const T &max)
template<class T >
double	imColorReconstruct (const T &value, const T &min, const T &max)
template<class T >
void	imColorYCbCr2RGB (const T Y, const T Cb, const T Cr, T &R, T &G, T &B, const T &zero, const T &min, const T &max)
template<class T >
void	imColorRGB2YCbCr (const T R, const T G, const T B, T &Y, T &Cb, T &Cr, const T &zero)
template<class T >
void	imColorCMYK2RGB (const T C, const T M, const T Y, const T K, T &R, T &G, T &B, const T &max)
template<class T >
void	imColorXYZ2RGB (const T X, const T Y, const T Z, T &R, T &G, T &B)
template<class T >
void	imColorRGB2XYZ (const T R, const T G, const T B, T &X, T &Y, T &Z)
void	imColorXYZ2Lab (const double X, const double Y, const double Z, double &L, double &a, double &b)
void	imColorLab2XYZ (const double L, const double a, const double b, double &X, double &Y, double &Z)
void	imColorXYZ2Luv (const double X, const double Y, const double Z, double &L, double &u, double &v)
void	imColorLuv2XYZ (const double L, const double u, const double v, double &X, double &Y, double &Z)
double	imColorTransfer2Linear (const double &nonlinear_value)
double	imColorTransfer2Nonlinear (const double &value)
void	imColorRGB2RGBNonlinear (const double RL, const double GL, const double BL, double &R, double &G, double &B)
template<class T >
T	imColorRGB2Luma (const T R, const T G, const T B)
double	imColorLuminance2Lightness (const double &Y)
double	imColorLightness2Luminance (const double &L)

Detailed Description

: Functions to convert from one color space to another, and color gamut utilities.

: See im_color.h

Some Color Science

: Y is luminance, a linear-light quantity. It is directly proportional to physical intensity weighted by the spectral sensitivity of human vision.

: L* is lightness, a nonlinear luminance that approximates the perception of brightness. It is nearly perceptual uniform. It has a range of 0 to 100.

: Y' is luma, a nonlinear luminance that approximates lightness.

: Brightness is a visual sensation according to which an area appears to exhibit more or less light. It is a subjective quantity and can not be measured.

: One unit of Euclidian distance in CIE L*u*v* or CIE L*a*b* corresponds roughly to a just-noticeable difference (JND) of color.

 ChromaUV = sqrt(u*u + v*v)       
 HueUV = atan2(v, u)
 SaturationUV = ChromaUV / L      (called psychometric saturation) 
 (the same can be calculated for Lab)

IEC 61966-2.1 Default RGB color space - sRGB

ITU-R Recommendation BT.709 (D65 white point).
D65 White Point (X,Y,Z) = (0.9505 1.0000 1.0890)

: Documentation extracted from Charles Poynton - Digital Video and HDTV - Morgan Kaufmann - 2003.

Links

www.color.org - ICC
www.srgb.com - sRGB
www.poynton.com - Charles Poynton
www.littlecms.com - A free Color Management System (use this if you need precise color conversions)

Color Component Intervals

: When minimum and maximum values must be pre-defined values, the following values are used:

 byte   [0,255]              (1 byte)
 short  [-32768,32767]       (2 bytes)
 ushort [0,65535]            (2 bytes)
 int    [-8388608,+8388607]  (3 bytes of 4 possible)
 float  [0,1]                (4 bytes)
 double [0,1]                (8 bytes)

Usually this intervals are used when converting from real to integer, and when demoting an integer data type.

Function Documentation

double imColorZeroShift ( int data_type ) [inline]

Returns the zero value for YCbCr color conversion.
When data type is unsigned Cb and Cr are shifted to 0-max. So before they can be used in conversion equations Cb and Cr values must be shifted back to fix the zero position.

int imColorMax ( int data_type ) [inline]

Returns the maximum value for pre-defined color conversion purposes.
See Color Component Intervals.

int imColorMin ( int data_type ) [inline]

Returns the minimum value for pre-defined color conversion purposes.
See Color Component Intervals.

template<class T , class R >

T imColorQuantize	(	const R &	value,
		const T &	min,
		const T &	max
	)			`[inline]`

Quantize 0-1 values into min-max.
Value are usually integers, but the dummy quantizer uses real values. See also Math Utilities.

References imRound().

template<class T >

double imColorReconstruct	(	const T &	value,
		const T &	min,
		const T &	max
	)			`[inline]`

Reconstruct min-max values into 0-1.
Values are usually integers, but the dummy re-constructor uses real values. See also Math Utilities.

template<class T >

void imColorYCbCr2RGB	(	const T	Y,
		const T	Cb,
		const T	Cr,
		T &	R,
		T &	G,
		T &	B,
		const T &	zero,
		const T &	min,
		const T &	max
	)			`[inline]`

Converts Y'CbCr to R'G'B' (all nonlinear).
ITU-R Recommendation 601-1 with no headroom/footroom.

 0 <= Y <= 1 ; -0.5 <= CbCr <= 0.5 ; 0 <= RGB <= 1 

 R'= Y' + 0.000 *Cb + 1.402 *Cr
 G'= Y' - 0.344 *Cb - 0.714 *Cr
 B'= Y' + 1.772 *Cb + 0.000 *Cr

template<class T >

void imColorRGB2YCbCr	(	const T	R,
		const T	G,
		const T	B,
		T &	Y,
		T &	Cb,
		T &	Cr,
		const T &	zero
	)			`[inline]`

Converts R'G'B' to Y'CbCr (all nonlinear).
ITU-R Recommendation 601-1 with no headroom/footroom.

 0 <= Y <= 1 ; -0.5 <= CbCr <= 0.5 ; 0 <= RGB <= 1 

 Y' =  0.299 *R' + 0.587 *G' + 0.114 *B'
 Cb = -0.169 *R' - 0.331 *G' + 0.500 *B'
 Cr =  0.500 *R' - 0.419 *G' - 0.081 *B'

template<class T >

void imColorCMYK2RGB	(	const T	C,
		const T	M,
		const T	Y,
		const T	K,
		T &	R,
		T &	G,
		T &	B,
		const T &	max
	)			`[inline]`

Converts C'M'Y'K' to R'G'B' (all nonlinear).
This is a poor conversion that works for a simple visualization.

  0 <= CMYK <= 1 ; 0 <= RGB <= 1 

  R = (1 - K) * (1 - C)
  G = (1 - K) * (1 - M)
  B = (1 - K) * (1 - Y)

template<class T >

void imColorXYZ2RGB	(	const T	X,
		const T	Y,
		const T	Z,
		T &	R,
		T &	G,
		T &	B
	)			`[inline]`

Converts CIE XYZ to Rec 709 RGB (all linear).
ITU-R Recommendation BT.709 (D65 white point).

  0 <= XYZ <= 1 ; 0 <= RGB <= 1    

  R =  3.2406 *X - 1.5372 *Y - 0.4986 *Z
  G = -0.9689 *X + 1.8758 *Y + 0.0415 *Z
  B =  0.0557 *X - 0.2040 *Y + 1.0570 *Z

template<class T >

void imColorRGB2XYZ	(	const T	R,
		const T	G,
		const T	B,
		T &	X,
		T &	Y,
		T &	Z
	)			`[inline]`

Converts Rec 709 RGB to CIE XYZ (all linear).
ITU-R Recommendation BT.709 (D65 white point).

  0 <= XYZ <= 1 ; 0 <= RGB <= 1    

  X = 0.4124 *R + 0.3576 *G + 0.1805 *B
  Y = 0.2126 *R + 0.7152 *G + 0.0722 *B
  Z = 0.0193 *R + 0.1192 *G + 0.9505 *B

void imColorXYZ2Lab	(	const double	X,
		const double	Y,
		const double	Z,
		double &	L,
		double &	a,
		double &	b
	)			`[inline]`

Converts CIE XYZ (linear) to CIE L*a*b* (nonlinear).
The white point is D65.

  0 <= L <= 1 ; -0.5 <= ab <= +0.5 ; 0 <= XYZ <= 1 

  if (t > 0.008856)
    f(t) = pow(t, 1/3)
  else
    f(t) = 7.787*t + 16/116

  fX = f(X / Xn)      fY = f(Y / Yn)      fZ = f(Z / Zn)

  L = 1.16 * fY - 0.16
  a = 2.5 * (fX - fY)
  b = (fY - fZ)

void imColorLab2XYZ	(	const double	L,
		const double	a,
		const double	b,
		double &	X,
		double &	Y,
		double &	Z
	)			`[inline]`

Converts CIE L*a*b* (nonlinear) to CIE XYZ (linear).
The white point is D65.
0 <= L <= 1 ; -0.5 <= ab <= +0.5 ; 0 <= XYZ <= 1

void imColorXYZ2Luv	(	const double	X,
		const double	Y,
		const double	Z,
		double &	L,
		double &	u,
		double &	v
	)			`[inline]`

Converts CIE XYZ (linear) to CIE L*u*v* (nonlinear).
The white point is D65.

  0 <= L <= 1 ; -1 <= uv <= +1 ; 0 <= XYZ <= 1

  Y = Y / 1.0      (for D65)
  if (Y > 0.008856)
    fY = pow(Y, 1/3)
  else
    fY = 7.787 * Y + 0.16/1.16
  L = 1.16 * fY - 0.16

  U(x, y, z) = (4 * x)/(x + 15 * y + 3 * z)
  V(x, y, z) = (9 * x)/(x + 15 * y + 3 * z)
  un = U(Xn, Yn, Zn) = 0.1978      (for D65)
  vn = V(Xn, Yn, Zn) = 0.4683      (for D65)
  fu = U(X, Y, Z) 
  fv = V(X, Y, Z) 

  u = 13 * L * (fu - un)
  v = 13 * L * (fv - vn)

void imColorLuv2XYZ	(	const double	L,
		const double	u,
		const double	v,
		double &	X,
		double &	Y,
		double &	Z
	)			`[inline]`

Converts CIE L*u*v* (nonlinear) to CIE XYZ (linear).
The white point is D65. 0 <= L <= 1 ; -0.5 <= uv <= +0.5 ; 0 <= XYZ <= 1

double imColorTransfer2Linear ( const double & nonlinear_value ) [inline]

Converts nonlinear values to linear values.
We use the sRGB transfer function. sRGB uses ITU-R 709 primaries and D65 white point.

  0 <= l <= 1 ; 0 <= v <= 1 

  if (v < 0.03928)
    l = v / 12.92
  else
    l = pow((v + 0.055) / 1.055, 2.4)

double imColorTransfer2Nonlinear ( const double & value ) [inline]

Converts linear values to nonlinear values.
We use the sRGB transfer function. sRGB uses ITU-R 709 primaries and D65 white point.

  0 <= l <= 1 ; 0 <= v <= 1 

  if (l < 0.0031308)
    v = 12.92 * l
  else
    v = 1.055 * pow(l, 1/2.4) - 0.055

Referenced by imColorRGB2RGBNonlinear().

void imColorRGB2RGBNonlinear	(	const double	RL,
		const double	GL,
		const double	BL,
		double &	R,
		double &	G,
		double &	B
	)			`[inline]`

Converts RGB (linear) to R'G'B' (nonlinear).

References imColorTransfer2Nonlinear().

template<class T >

T imColorRGB2Luma	(	const T	R,
		const T	G,
		const T	B
	)			`[inline]`

Converts R'G'B' to Y' (all nonlinear).

 Y'  =  0.299 *R' + 0.587 *G' + 0.114 *B'

double imColorLuminance2Lightness ( const double & Y ) [inline]

Converts Luminance (CIE Y) to Lightness (CIE L*) (all linear).
The white point is D65.

  0 <= Y <= 1 ; 0 <= L* <= 1

  Y = Y / 1.0      (for D65)
  if (Y > 0.008856)
    fY = pow(Y, 1/3)
  else
    fY = 7.787 * Y + 0.16/1.16
  L = 1.16 * fY - 0.16

double imColorLightness2Luminance ( const double & L ) [inline]

Converts Lightness (CIE L*) to Luminance (CIE Y) (all linear).
The white point is D65.

  0 <= Y <= 1 ; 0 <= L* <= 1

  fY = (L + 0.16)/1.16
  if (fY > 0.20689)
    Y = pow(fY, 3)
  else
    Y = 0.1284 * (fY - 0.16/1.16)
  Y = Y * 1.0      (for D65)

Color Manipulation [Utilities]

Modules

Functions

Detailed Description

Some Color Science

Links

Color Component Intervals

Function Documentation

Color Manipulation
[Utilities]