colour.appearance.ciecam02 Module¶

CIECAM02 Colour Appearance Model¶

Defines CIECAM02 colour appearance model objects:

CIECAM02_InductionFactors
CIECAM02_VIEWING_CONDITIONS
CIECAM02_Specification
XYZ_to_CIECAM02()
CIECAM02_to_XYZ()

References

[1]	http://en.wikipedia.org/wiki/CIECAM02 (Last accessed 14 August 2014)

[2]	Mark D. Fairchild, Color Appearance Models, 2nd Edition, The Wiley-IS&T Series in Imaging Science and Technology, published 19 November 2004, ISBN-13: 978-0470012161, pages 265-277.

[3]	Stephen Westland, Caterina Ripamonti, Vien Cheung, Computational Colour Science Using MATLAB, 2nd Edition, The Wiley-IS&T Series in Imaging Science and Technology, published July 2012, ISBN-13: 978-0-470-66569-5, page 38.

[4]	The CIECAM02 Color Appearance Model (Last accessed 30 July 2014)

class colour.appearance.ciecam02.CIECAM02_InductionFactors[source]¶

Bases: colour.appearance.ciecam02.CIECAM02_InductionFactors

CIECAM02 colour appearance model induction factors.

Parameters:	F (numeric) – Maximum degree of adaptation $F$ . c (numeric) – Exponential non linearity $c$ . N_c (numeric) – Chromatic induction factor $N_c$ .

colour.appearance.ciecam02.CIECAM02_VIEWING_CONDITIONS = CaseInsensitiveMapping({u'Dark': CIECAM02_InductionFactors(F=0.8, c=0.525, N_c=0.8), u'Dim': CIECAM02_InductionFactors(F=0.9, c=0.59, N_c=0.95), u'Average': CIECAM02_InductionFactors(F=1, c=0.69, N_c=1)})¶

Reference CIECAM02 colour appearance model viewing conditions.

CIECAM02_VIEWING_CONDITIONS : dict: (‘Average’, ‘Dim’, ‘Dark’)

class colour.appearance.ciecam02.CIECAM02_Specification[source]¶

Bases: colour.appearance.ciecam02.CIECAM02_Specification

Defines the CIECAM02 colour appearance model specification.

Parameters:	J (numeric) – Correlate of Lightness $J$ . C (numeric) – Correlate of chroma $C$ . h (numeric) – Hue angle $h$ in degrees. s (numeric) – Correlate of saturation $s$ . Q (numeric) – Correlate of brightness $Q$ . M (numeric) – Correlate of colourfulness $M$ . H (numeric) – Hue $h$ quadrature $H$ . HC (numeric) – Hue $h$ composition $H^C$ .

colour.appearance.ciecam02.XYZ_to_CIECAM02(XYZ, XYZ_w, L_A, Y_b, surround=CIECAM02_InductionFactors(F=1, c=0.69, N_c=1), discount_illuminant=False)[source]¶

Computes the CIECAM02 colour appearance model correlates from given CIE XYZ colourspace matrix.

This is the forward implementation.

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_w (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. L_A (numeric) – Adapting field luminance $L_A$ in $cd/m^2$ . Y_b (numeric) – Adapting field Y tristimulus value $Y_b$ . surround (CIECAM02_InductionFactors, optional) – Surround viewing conditions induction factors. discount_illuminant (bool, optional) – Truth value indicating if the illuminant should be discounted.
Returns:	CIECAM02 colour appearance model specification.
Return type:	CIECAM02_Specification

Warning

The input domain of that definition is non standard!

Notes

Input CIE XYZ colourspace matrix is in domain [0, 100].
Input CIE XYZ_w colourspace matrix is in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20.00, 21.78])
>>> XYZ_w = np.array([95.05, 100.00, 108.88])
>>> L_A = 318.31
>>> Y_b = 20.0
>>> surround = CIECAM02_VIEWING_CONDITIONS['Average']
>>> XYZ_to_CIECAM02(XYZ, XYZ_w, L_A, Y_b, surround)  
CIECAM02_Specification(J=41.7310911..., C=0.1047077..., h=219.0484326..., s=2.3603053..., Q=195.3713259..., M=0.1088421..., H=278.0607358..., HC=None)

colour.appearance.ciecam02.CIECAM02_to_XYZ(J, C, h, XYZ_w, L_A, Y_b, surround=CIECAM02_InductionFactors(F=1, c=0.69, N_c=1), discount_illuminant=False)[source]¶

Converts CIECAM02 specification to CIE XYZ colourspace matrix.

This is the reverse implementation.

Parameters:	CIECAM02_Specification (CIECAM02_Specification) – CIECAM02 specification. XYZ_w (array_like) – CIE XYZ colourspace matrix of reference white. L_A (numeric) – Adapting field luminance $L_A$ in $cd/m^2$ . Y_b (numeric) – Adapting field Y tristimulus value $Y_b$ . surround (CIECAM02_Surround, optional) – Surround viewing conditions. discount_illuminant (bool, optional) – Discount the illuminant.
Returns:	XYZ – CIE XYZ colourspace matrix.
Return type:	ndarray

Warning

The output domain of that definition is non standard!

Notes

Input CIE XYZ_w colourspace matrix is in domain [0, 100].
Output CIE XYZ colourspace matrix is in domain [0, 100].

Examples

>>> J = 41.731091132513917
>>> C = 0.1047077571711053
>>> h = 219.0484326582719
>>> XYZ_w = np.array([95.05, 100.00, 108.88])
>>> L_A = 318.31
>>> Y_b = 20.0
>>> CIECAM02_to_XYZ(J, C, h, XYZ_w, L_A, Y_b)  
array([ 19.01...,  20...  ,  21.78...])

colour.appearance.ciecam02.chromatic_induction_factors(n)[source]¶

Returns the chromatic induction factors $N_{bb}$ and $N_{cb}$ .

Parameters:	n (numeric) – Function of the luminance factor of the background $n$ .
Returns:	Chromatic induction factors $N_{bb}$ and $N_{cb}$ .
Return type:	tuple

Examples

>>> chromatic_induction_factors(0.2)  
(1.0003040..., 1.0003040...)

colour.appearance.ciecam02.base_exponential_non_linearity(n)[source]¶

Returns the base exponential non linearity $n$ .

Parameters:	n (numeric) – Function of the luminance factor of the background $n$ .
Returns:	Base exponential non linearity $z$ .
Return type:	numeric

Examples

>>> base_exponential_non_linearity(0.2)  
1.9272135...

colour.appearance.ciecam02.viewing_condition_dependent_parameters(*args, **kwds)[source]¶

Returns the viewing condition dependent parameters.

Parameters:	Y_b (numeric) – Adapting field Y tristimulus value $Y_b$ . Y_w (numeric) – Whitepoint Y tristimulus value $Y_w$ . L_A (numeric) – Adapting field luminance $L_A$ in $cd/m^2$ .
Returns:	Viewing condition dependent parameters.
Return type:	tuple

Examples

>>> viewing_condition_dependent_parameters(20.0, 100.0, 318.31)    
(0.2000000..., 1.1675444..., 1.0003040..., 1.0003040..., 1.9272135...)

colour.appearance.ciecam02.degree_of_adaptation(F, L_A)[source]¶

Returns the degree of adaptation $D$ from given surround maximum degree of adaptation $F$ and Adapting field luminance $L_A$ in $cd/m^2$ .

Parameters:	F (numeric) – Surround maximum degree of adaptation $F$ . L_A (numeric) – Adapting field luminance $L_A$ in $cd/m^2$ .
Returns:	Degree of adaptation $D$ .
Return type:	numeric

Examples

>>> degree_of_adaptation(1.0, 318.31)  
0.9944687...

colour.appearance.ciecam02.full_chromatic_adaptation_forward(RGB, RGB_w, Y_w, D)[source]¶

Applies full chromatic adaptation to given CMCCAT2000 transform sharpened RGB matrix using given CMCCAT2000 transform sharpened whitepoint RGB_w matrix.

Parameters:	RGB (array_like) – CMCCAT2000 transform sharpened RGB matrix. RGB_w (array_like) – CMCCAT2000 transform sharpened whitepoint RGB_w matrix. Y_w (numeric) – Whitepoint Y tristimulus value $Y_w$ . D (numeric) – Degree of adaptation $D$ .
Returns:	Adapted RGB matrix.
Return type:	ndarray, (3,)

Examples

>>> RGB = np.array([18.985456, 20.707422, 21.747482])
>>> RGB_w = np.array([94.930528, 103.536988, 108.717742])
>>> Y_w = 100.0
>>> D = 0.994468780088
>>> full_chromatic_adaptation_forward(RGB, RGB_w, Y_w, D)    
array([ 19.9937078...,  20.0039363...,  20.0132638...])

colour.appearance.ciecam02.full_chromatic_adaptation_reverse(RGB, RGB_w, Y_w, D)[source]¶

Reverts full chromatic adaptation of given CMCCAT2000 transform sharpened RGB matrix using given CMCCAT2000 transform sharpened whitepoint RGB_w matrix.

Parameters:	RGB (array_like) – CMCCAT2000 transform sharpened RGB matrix. RGB_w (array_like) – CMCCAT2000 transform sharpened whitepoint RGB_w matrix. Y_w (numeric) – Whitepoint Y tristimulus value $Y_w$ . D (numeric) – Degree of adaptation $D$ .
Returns:	Adapted RGB matrix.
Return type:	ndarray, (3,)

Examples

>>> RGB = np.array([19.99370783, 20.00393634, 20.01326387])
>>> RGB_w = np.array([94.930528, 103.536988, 108.717742])
>>> Y_w = 100.0
>>> D = 0.994468780088
>>> full_chromatic_adaptation_reverse(RGB, RGB_w, Y_w, D)
array([ 18.985456,  20.707422,  21.747482])

colour.appearance.ciecam02.RGB_to_rgb(RGB)[source]¶

Converts given RGB matrix to Hunt-Pointer-Estevez $\rho\gamma\beta$ colourspace.

Parameters:	RGB (array_like, (3,)) – RGB matrix.
Returns:	Hunt-Pointer-Estevez $\rho\gamma\beta$ colourspace matrix.
Return type:	ndarray, (3,)

Examples

>>> RGB = np.array([19.99370783, 20.00393634, 20.01326387])
>>> RGB_to_rgb(RGB)  
array([ 19.9969397...,  20.0018612...,  20.0135053...])

colour.appearance.ciecam02.rgb_to_RGB(rgb)[source]¶

Converts given Hunt-Pointer-Estevez $\rho\gamma\beta$ colourspace matrix to RGB matrix.

Parameters:	rgb (array_like, (3,)) – Hunt-Pointer-Estevez $\rho\gamma\beta$ colourspace matrix.
Returns:	RGB matrix.
Return type:	ndarray, (3,)

Examples

>>> rgb = np.array([19.99693975, 20.00186123, 20.0135053])
>>> rgb_to_RGB(rgb)  
array([ 19.9937078...,  20.0039363...,  20.0132638...])

colour.appearance.ciecam02.post_adaptation_non_linear_response_compression_forward(RGB, F_L)[source]¶

Returns given CMCCAT2000 transform sharpened RGB matrix with post adaptation non linear response compression.

Parameters:	RGB (array_like) – CMCCAT2000 transform sharpened RGB matrix.
Returns:	Compressed CMCCAT2000 transform sharpened RGB matrix.
Return type:	ndarray, (3,)

Examples

>>> RGB = np.array([19.99693975, 20.00186123, 20.0135053])
>>> F_L = 1.16754446415
>>> post_adaptation_non_linear_response_compression_forward(RGB, F_L)    
array([ 7.9463202...,  7.9471152...,  7.9489959...])

colour.appearance.ciecam02.post_adaptation_non_linear_response_compression_reverse(RGB, F_L)[source]¶

Returns given CMCCAT2000 transform sharpened RGB matrix without post adaptation non linear response compression.

Parameters:	RGB (array_like) – CMCCAT2000 transform sharpened RGB matrix.
Returns:	Uncompressed CMCCAT2000 transform sharpened RGB matrix.
Return type:	ndarray, (3,)

Examples

>>> RGB = np.array([7.9463202, 7.94711528, 7.94899595])
>>> F_L = 1.16754446415
>>> post_adaptation_non_linear_response_compression_reverse(RGB, F_L)    
array([ 19.9969397...,  20.0018612...,  20.0135052...])

colour.appearance.ciecam02.opponent_colour_dimensions_forward(RGB)[source]¶

Returns opponent colour dimensions from given compressed CMCCAT2000 transform sharpened RGB matrix for forward CIECAM02 implementation

Parameters:	RGB (array_like) – Compressed CMCCAT2000 transform sharpened RGB matrix.
Returns:	Opponent colour dimensions.
Return type:	tuple

Examples

>>> RGB = np.array([7.9463202, 7.94711528, 7.94899595])
>>> opponent_colour_dimensions_forward(RGB)  
(-0.0006241..., -0.0005062...)

colour.appearance.ciecam02.opponent_colour_dimensions_reverse(P, h)[source]¶

Returns opponent colour dimensions from given points $P$ and hue $h$ in degrees for reverse CIECAM02 implementation.

Parameters:	p (array_like) – Points $P$ . h (numeric) – Hue $h$ in degrees.
Returns:	Opponent colour dimensions.
Return type:	tuple

Examples

>>> p = (30162.890815335879, 24.237205467134817, 1.05)
>>> h = -140.9515673417281
>>> opponent_colour_dimensions_reverse(p, h)  
(-0.0006241..., -0.0005062...)

colour.appearance.ciecam02.hue_angle(a, b)[source]¶

Returns the hue angle $h$ in degrees.

Parameters:	a (numeric) – Opponent colour dimension $a$ . b (numeric) – Opponent colour dimension $b$ .
Returns:	Hue angle $h$ in degrees.
Return type:	numeric

Examples

>>> a = -0.0006241120682426434
>>> b = -0.0005062701067729668
>>> hue_angle(a, b)  
219.0484326...

colour.appearance.ciecam02.hue_quadrature(h)[source]¶

Returns the hue quadrature from given hue $h$ angle in degrees.

Parameters:	h (numeric) – Hue $h$ angle in degrees.
Returns:	Hue quadrature.
Return type:	numeric

Examples

>>> hue_quadrature(219.0484326582719)  
278.0607358...

colour.appearance.ciecam02.eccentricity_factor(h)[source]¶

Returns the eccentricity factor $e_t$ from given hue $h$ angle for forward CIECAM02 implementation.

Parameters:	h (numeric) – Hue $h$ angle in degrees.
Returns:	Eccentricity factor $e_t$ .
Return type:	numeric

Examples

>>> eccentricity_factor(-140.951567342)  
1.1740054...

colour.appearance.ciecam02.achromatic_response_forward(RGB, N_bb)[source]¶

Returns the achromatic response $A$ from given compressed CMCCAT2000 transform sharpened RGB matrix and $N_{bb}$ chromatic induction factor for forward CIECAM02 implementation.

Parameters:	RGB (array_like) – Compressed CMCCAT2000 transform sharpened RGB matrix. N_bb (numeric) – Chromatic induction factor $N_{bb}$ .
Returns:	Achromatic response $A$ .
Return type:	numeric

Examples

>>> RGB = np.array([7.9463202, 7.94711528, 7.94899595])
>>> N_bb = 1.0003040045593807
>>> achromatic_response_forward(RGB, N_bb)  
23.9394809...

colour.appearance.ciecam02.achromatic_response_reverse(A_w, J, c, z)[source]¶

Returns the achromatic response $A$ from given achromatic response $A_w$ for the whitepoint, Lightness correlate $J$ , surround exponential non linearity $c$ and base exponential non linearity $z$ for reverse CIECAM02 implementation.

Parameters:	A_w (numeric) – Achromatic response $A_w$ for the whitepoint. J (numeric) – Lightness correlate $J$ . c (numeric) – Surround exponential non linearity $c$ . z (numeric) – Base exponential non linearity $z$ .
Returns:	Achromatic response $A$ .
Return type:	numeric

Examples

>>> A_w = 46.1882087914
>>> J = 41.73109113251392
>>> c = 0.69
>>> z = 1.9272135954999579
>>> achromatic_response_reverse(A_w, J, c, z)  
23.9394809...

colour.appearance.ciecam02.lightness_correlate(A, A_w, c, z)[source]¶

Returns the Lightness correlate $J$ .

Parameters:	A (numeric) – Achromatic response $A$ for the stimulus. A_w (numeric) – Achromatic response $A_w$ for the whitepoint. c (numeric) – Surround exponential non linearity $c$ . z (numeric) – Base exponential non linearity $z$ .
Returns:	Lightness correlate $J$ .
Return type:	numeric

Examples

>>> A = 23.9394809667
>>> A_w = 46.1882087914
>>> c = 0.69
>>> z = 1.9272135955
>>> lightness_correlate(A, A_w, c, z)  
41.7310911...

colour.appearance.ciecam02.brightness_correlate(c, J, A_w, F_L)[source]¶

Returns the brightness correlate $Q$ .

Parameters:	c (numeric) – Surround exponential non linearity $c$ . J (numeric) – Lightness correlate $J$ . A_w (numeric) – Achromatic response $A_w$ for the whitepoint. F_L (numeric) – Luminance level adaptation factor $F_L$ .
Returns:	Brightness correlate $Q$ .
Return type:	numeric

Examples

>>> c = 0.69
>>> J = 41.7310911325
>>> A_w = 46.1882087914
>>> F_L = 1.16754446415
>>> brightness_correlate(c, J, A_w, F_L)  
195.3713259...

colour.appearance.ciecam02.temporary_magnitude_quantity_forward(N_c, N_cb, e_t, a, b, RGB_a)[source]¶

Returns the temporary magnitude quantity $t$ . for forward CIECAM02 implementation.

Parameters:	N_c (numeric) – Surround chromatic induction factor $N_{c}$ . N_cb (numeric) – Chromatic induction factor $N_{cb}$ . e_t (numeric) – Eccentricity factor $e_t$ . a (numeric) – Opponent colour dimension $a$ . b (numeric) – Opponent colour dimension $b$ . RGB_a (array_like) – Compressed stimulus CMCCAT2000 transform sharpened RGB matrix.
Returns:	Temporary magnitude quantity $t$ .
Return type:	numeric

Examples

>>> N_c = 1.0
>>> N_cb = 1.00030400456
>>> e_t = 1.1740054728519145
>>> a = -0.000624112068243
>>> b = -0.000506270106773
>>> RGB_a = np.array([7.9463202, 7.94711528, 7.94899595])
>>> temporary_magnitude_quantity_forward(N_c, N_cb, e_t, a, b, RGB_a)    
0.1497462...

colour.appearance.ciecam02.temporary_magnitude_quantity_reverse(C, J, n)[source]¶

Returns the temporary magnitude quantity $t$ . for reverse CIECAM02 implementation.

Parameters:	C (numeric) – Chroma correlate $C$ . J (numeric) – Lightness correlate $J$ . n (numeric) – Function of the luminance factor of the background $n$ .
Returns:	Temporary magnitude quantity $t$ .
Return type:	numeric

Examples

>>> C = 68.8364136888275
>>> J = 41.749268505999
>>> n = 0.2
>>> temporary_magnitude_quantity_reverse(C, J, n)  
202.3873619...

colour.appearance.ciecam02.chroma_correlate(J, n, N_c, N_cb, e_t, a, b, RGB_a)[source]¶

Returns the chroma correlate $C$ .

Parameters:	J (numeric) – Lightness correlate $J$ . n (numeric) – Function of the luminance factor of the background $n$ . N_c (numeric) – Surround chromatic induction factor $N_{c}$ . N_cb (numeric) – Chromatic induction factor $N_{cb}$ . e_t (numeric) – Eccentricity factor $e_t$ . a (numeric) – Opponent colour dimension $a$ . b (numeric) – Opponent colour dimension $b$ . RGB_a (array_like) – Compressed stimulus CMCCAT2000 transform sharpened RGB matrix.
Returns:	Chroma correlate $C$ .
Return type:	numeric

Examples

>>> J = 41.7310911325
>>> n = 0.2
>>> N_c = 1.0
>>> N_cb = 1.00030400456
>>> e_t = 1.17400547285
>>> a = -0.000624112068243
>>> b = -0.000506270106773
>>> RGB_a = np.array([7.9463202, 7.94711528, 7.94899595])
>>> chroma_correlate(J, n, N_c, N_cb, e_t, a, b, RGB_a)    
0.1047077...

colour.appearance.ciecam02.colourfulness_correlate(C, F_L)[source]¶

Returns the colourfulness correlate $M$ .

Parameters:	C (numeric) – Chroma correlate $C$ . F_L (numeric) – Luminance level adaptation factor $F_L$ .
Returns:	Colourfulness correlate $M$ .
Return type:	numeric

Examples

>>> C = 0.104707757171
>>> F_L = 1.16754446415
>>> colourfulness_correlate(C, F_L)  
0.1088421...

colour.appearance.ciecam02.saturation_correlate(M, Q)[source]¶

Returns the saturation correlate $s$ .

Parameters:	M (numeric) – Colourfulness correlate $M$ . Q (numeric) – Brightness correlate $C$ .
Returns:	Saturation correlate $s$ .
Return type:	numeric

Examples

>>> M = 0.108842175669
>>> Q = 195.371325966
>>> saturation_correlate(M, Q)  
2.3603053...

colour.appearance.ciecam02.P(N_c, N_cb, e_t, t, A, N_bb)[source]¶

Returns the points $P_1$ , $P_2$ and $P_3$ .

Parameters:	N_c (numeric) – Surround chromatic induction factor $N_{c}$ . N_cb (numeric) – Chromatic induction factor $N_{cb}$ . e_t (numeric) – Eccentricity factor $e_t$ . t (numeric) – Temporary magnitude quantity $t$ . A (numeric) – Achromatic response $A$ for the stimulus. N_bb (numeric) – Chromatic induction factor $N_{bb}$ .
Returns:	Points $P$ .
Return type:	tuple

Examples

>>> N_c = 1.0
>>> N_cb = 1.00030400456
>>> e_t = 1.1740054728519145
>>> t = 0.149746202921
>>> A = 23.9394809667
>>> N_bb = 1.00030400456
>>> P(N_c, N_cb, e_t, t, A, N_bb)  
(30162.8908154..., 24.2372054..., 1.05)

colour.appearance.ciecam02.post_adaptation_non_linear_response_compression_matrix(P_2, a, b)[source]¶

Returns the post adaptation non linear response compression matrix.

Parameters:	P_2 (numeric) – Point $P_2$ . a (numeric) – Opponent colour dimension $a$ . b (numeric) – Opponent colour dimension $b$ .
Returns:	Points $P$ .
Return type:	ndarray, (3,)

Examples

>>> P_2 = 24.2372054671
>>> a = -0.000624112068243
>>> b = -0.000506270106773
>>> post_adaptation_non_linear_response_compression_matrix(P_2, a, b)    
array([ 7.9463202...,  7.9471152...,  7.9489959...])