colour.appearance.ciecam02 Module

CIECAM02 Colour Appearance Model

Defines CIECAM02 colour appearance model objects:

See also

CIECAM02 Colour Appearance Model IPython Notebook

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...])