Modules | Functions

Color Manipulation
[Utilities]

Collaboration diagram for Color Manipulation:

Modules

 HSI Color Coordinate System Conversions

Functions

float imColorZeroShift (int data_type)
int imColorMax (int data_type)
int imColorMin (int data_type)
template<class T >
imColorQuantize (const float &value, const T &min, const T &max)
template<class T >
float 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 float X, const float Y, const float Z, float &L, float &a, float &b)
void imColorLab2XYZ (const float L, const float a, const float b, float &X, float &Y, float &Z)
void imColorXYZ2Luv (const float X, const float Y, const float Z, float &L, float &u, float &v)
void imColorLuv2XYZ (const float L, const float u, const float v, float &X, float &Y, float &Z)
float imColorTransfer2Linear (const float &nonlinear_value)
float imColorTransfer2Nonlinear (const float &value)
void imColorRGB2RGBNonlinear (const float RL, const float GL, const float BL, float &R, float &G, float &B)
template<class T >
imColorRGB2Luma (const T R, const T G, const T B)
float imColorLuminance2Lightness (const float &Y)
float imColorLightness2Luminance (const float &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

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

float 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 >
T imColorQuantize ( const float &  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 >
float 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 reconstructor 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 float  X,
const float  Y,
const float  Z,
float &  L,
float &  a,
float &  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 float  L,
const float  a,
const float  b,
float &  X,
float &  Y,
float &  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 float  X,
const float  Y,
const float  Z,
float &  L,
float &  u,
float &  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 float  L,
const float  u,
const float  v,
float &  X,
float &  Y,
float &  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

float imColorTransfer2Linear ( const float &  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)
float imColorTransfer2Nonlinear ( const float &  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 float  RL,
const float  GL,
const float  BL,
float &  R,
float &  G,
float &  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'
float imColorLuminance2Lightness ( const float &  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
float imColorLightness2Luminance ( const float &  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)