colour.appearance.ciecam02 Module

CIECAM02 Colour Appearance Model

Defines CIECAM02 colour appearance model objects:

See also

CIECAM02 Colour Appearance Model IPython Notebook

References

[1]Wikipedia. (n.d.). CIECAM02. Retrieved August 14, 2014, from http://en.wikipedia.org/wiki/CIECAM02
[2]Fairchild, M. D. (2004). CIECAM02. In Color Appearance Models (2nd ed., pp. 289–301). Wiley. ISBN:978-0470012161
[3]Westland, S., Ripamonti, C., & Cheung, V. (2012). Extrapolation Methods. Computational Colour Science Using MATLAB (2nd ed., p. 38). ISBN:978-0-470-66569-5
[4]Moroney, N., Fairchild, M. D., Hunt, R. W. G., Li, C., Luo, M. R., & Newman, T. (n.d.). The CIECAM02 Color Appearance Model. Color and Imaging Conference, 2002(1), 23–27. Retrieved from http://www.ingentaconnect.com/content/ist/cic/2002/00002002/00000001/art00006
colour.appearance.ciecam02.CAT02_INVERSE_CAT = array([[ 1.09612382, -0.278869 , 0.18274518], [ 0.45436904, 0.47353315, 0.0720978 ], [-0.00962761, -0.00569803, 1.01532564]])

Inverse CAT02 chromatic adaptation transform.

CAT02_INVERSE_CAT : array_like, (3, 3)

class colour.appearance.ciecam02.CIECAM02_InductionFactors[source]

Bases: colour.appearance.ciecam02.CIECAM02_InductionFactors

CIECAM02 colour appearance model induction factors.

Parameters:
  • F (numeric or array_like) – Maximum degree of adaptation \(F\).
  • c (numeric or array_like) – Exponential non linearity \(c\).
  • N_c (numeric or array_like) – 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 : CaseInsensitiveMapping
{‘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 or array_like) – Correlate of Lightness \(J\).
  • C (numeric or array_like) – Correlate of chroma \(C\).
  • h (numeric or array_like) – Hue angle \(h\) in degrees.
  • s (numeric or array_like) – Correlate of saturation \(s\).
  • Q (numeric or array_like) – Correlate of brightness \(Q\).
  • M (numeric or array_like) – Correlate of colourfulness \(M\).
  • H (numeric or array_like) – Hue \(h\) quadrature \(H\).
  • HC (numeric or array_like) – 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 tristimulus values.

This is the forward implementation.

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100].
  • XYZ_w (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100].
  • L_A (numeric or array_like) – Adapting field luminance \(L_A\) in \(cd/m^2\).
  • Y_b (numeric or array_like) – 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 tristimulus values are in domain [0, 100].
  • Input CIE XYZ_w tristimulus values are 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=array(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 tristimulus values.

This is the reverse implementation.

Parameters:
  • CIECAM02_Specification (CIECAM02_Specification) – CIECAM02 specification.
  • XYZ_w (array_like) – CIE XYZ tristimulus values of reference white.
  • L_A (numeric or array_like) – Adapting field luminance \(L_A\) in \(cd/m^2\).
  • Y_b (numeric or array_like) – 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 tristimulus values.
Return type:

ndarray

Warning

The output domain of that definition is non standard!

Notes

  • Input CIE XYZ_w tristimulus values are in domain [0, 100].
  • Output CIE XYZ tristimulus values are in domain [0, 100].

Examples

>>> J = 41.731091132513917
>>> C = 0.1047077571711053
>>> h = 219.04843265827190
>>> 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 or array_like) – Function of the luminance factor of the background \(n\).
Returns:Chromatic induction factors \(N_{bb}\) and \(N_{cb}\).
Return type:ndarray

Examples

>>> chromatic_induction_factors(0.2)  
array([ 1.000304...,  1.000304...])
colour.appearance.ciecam02.base_exponential_non_linearity(n)[source]

Returns the base exponential non linearity \(n\).

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

Examples

>>> base_exponential_non_linearity(0.2)  
1.9272135...
colour.appearance.ciecam02.viewing_condition_dependent_parameters(Y_b, Y_w, L_A)[source]

Returns the viewing condition dependent parameters.

Parameters:
  • Y_b (numeric or array_like) – Adapting field Y tristimulus value \(Y_b\).
  • Y_w (numeric or array_like) – Whitepoint Y tristimulus value \(Y_w\).
  • L_A (numeric or array_like) – Adapting field luminance \(L_A\) in \(cd/m^2\).
Returns:

Viewing condition dependent parameters.
Return type:

ndarray

Examples

>>> viewing_condition_dependent_parameters(  
...     20.0, 100.0, 318.31)
array([ 0.2...,  1.1675444...,  1.000304...,  1.000304...,  1.9272136...])
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 or array_like) – Surround maximum degree of adaptation \(F\).
  • L_A (numeric or array_like) – Adapting field luminance \(L_A\) in \(cd/m^2\).
Returns:

Degree of adaptation \(D\).
Return type:

numeric or ndarray

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 array using given CMCCAT2000 transform sharpened whitepoint RGB_w array.

Parameters:
  • RGB (array_like) – CMCCAT2000 transform sharpened RGB array.
  • RGB_w (array_like) – CMCCAT2000 transform sharpened whitepoint RGB_w array.
  • Y_w (numeric or array_like) – Whitepoint Y tristimulus value \(Y_w\).
  • D (numeric or array_like) – Degree of adaptation \(D\).
Returns:

Adapted RGB array.
Return type:

ndarray

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 array using given CMCCAT2000 transform sharpened whitepoint RGB_w array.

Parameters:
  • RGB (array_like) – CMCCAT2000 transform sharpened RGB array.
  • RGB_w (array_like) – CMCCAT2000 transform sharpened whitepoint RGB_w array.
  • Y_w (numeric or array_like) – Whitepoint Y tristimulus value \(Y_w\).
  • D (numeric or array_like) – Degree of adaptation \(D\).
Returns:

Adapted RGB array.
Return type:

ndarray

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 array to Hunt-Pointer-Estevez \(\rho\gamma\beta\) colourspace.

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

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 array to RGB array.

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

Examples

>>> rgb = np.array([19.99693975, 20.00186123, 20.01350530])
>>> 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 array with post adaptation non linear response compression.

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

Examples

>>> RGB = np.array([19.99693975, 20.00186123, 20.01350530])
>>> 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 array without post adaptation non linear response compression.

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

Examples

>>> RGB = np.array([7.94632020, 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 array for forward CIECAM02 implementation

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

Examples

>>> RGB = np.array([7.94632020, 7.94711528, 7.94899595])
>>> opponent_colour_dimensions_forward(RGB)  
array([-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 or array_like) – Hue \(h\) in degrees.
Returns:

Opponent colour dimensions.
Return type:

ndarray

Examples

>>> p = np.array([30162.890815335879, 24.237205467134817, 1.05])
>>> h = -140.9515673417281
>>> opponent_colour_dimensions_reverse(p, h)  
array([-0.0006241..., -0.0005062...])
colour.appearance.ciecam02.hue_angle(a, b)[source]

Returns the hue angle \(h\) in degrees.

Parameters:
  • a (numeric or array_like) – Opponent colour dimension \(a\).
  • b (numeric or array_like) – Opponent colour dimension \(b\).
Returns:

Hue angle \(h\) in degrees.
Return type:

numeric or ndarray

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 or array_like) – Hue \(h\) angle in degrees.
Returns:Hue quadrature.
Return type:numeric or ndarray

Examples

>>> hue_quadrature(219.0484326582719)  
array(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 or array_like) – Hue \(h\) angle in degrees.
Returns:Eccentricity factor \(e_t\).
Return type:numeric or ndarray

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 array and \(N_{bb}\) chromatic induction factor for forward CIECAM02 implementation.

Parameters:
  • RGB (array_like) – Compressed CMCCAT2000 transform sharpened RGB array.
  • N_bb (numeric or array_like) – Chromatic induction factor \(N_{bb}\).
Returns:

Achromatic response \(A\).
Return type:

numeric or ndarray

Examples

>>> RGB = np.array([7.94632020, 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 or array_like) – Achromatic response \(A_w\) for the whitepoint.
  • J (numeric or array_like) – Lightness correlate \(J\).
  • c (numeric or array_like) – Surround exponential non linearity \(c\).
  • z (numeric or array_like) – Base exponential non linearity \(z\).
Returns:

Achromatic response \(A\).
Return type:

numeric or ndarray

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 or array_like) – Achromatic response \(A\) for the stimulus.
  • A_w (numeric or array_like) – Achromatic response \(A_w\) for the whitepoint.
  • c (numeric or array_like) – Surround exponential non linearity \(c\).
  • z (numeric or array_like) – Base exponential non linearity \(z\).
Returns:

Lightness correlate \(J\).
Return type:

numeric or ndarray

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 or array_like) – Surround exponential non linearity \(c\).
  • J (numeric or array_like) – Lightness correlate \(J\).
  • A_w (numeric or array_like) – Achromatic response \(A_w\) for the whitepoint.
  • F_L (numeric or array_like) – Luminance level adaptation factor \(F_L\).
Returns:

Brightness correlate \(Q\).
Return type:

numeric or ndarray

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 or array_like) – Surround chromatic induction factor \(N_{c}\).
  • N_cb (numeric or array_like) – Chromatic induction factor \(N_{cb}\).
  • e_t (numeric or array_like) – Eccentricity factor \(e_t\).
  • a (numeric or array_like) – Opponent colour dimension \(a\).
  • b (numeric or array_like) – Opponent colour dimension \(b\).
  • RGB_a (array_like) – Compressed stimulus CMCCAT2000 transform sharpened RGB array.
Returns:

Temporary magnitude quantity \(t\).
Return type:

numeric or ndarray

Examples

>>> N_c = 1.0
>>> N_cb = 1.00030400456
>>> e_t = 1.1740054728519145
>>> a = -0.000624112068243
>>> b = -0.000506270106773
>>> RGB_a = np.array([7.94632020, 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 or array_like) – Chroma correlate \(C\).
  • J (numeric or array_like) – Lightness correlate \(J\).
  • n (numeric or array_like) – Function of the luminance factor of the background \(n\).
Returns:

Temporary magnitude quantity \(t\).
Return type:

numeric or ndarray

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 or array_like) – Lightness correlate \(J\).
  • n (numeric or array_like) – Function of the luminance factor of the background \(n\).
  • N_c (numeric or array_like) – Surround chromatic induction factor \(N_{c}\).
  • N_cb (numeric or array_like) – Chromatic induction factor \(N_{cb}\).
  • e_t (numeric or array_like) – Eccentricity factor \(e_t\).
  • a (numeric or array_like) – Opponent colour dimension \(a\).
  • b (numeric or array_like) – Opponent colour dimension \(b\).
  • RGB_a (array_like) – Compressed stimulus CMCCAT2000 transform sharpened RGB array.
Returns:

Chroma correlate \(C\).
Return type:

numeric or ndarray

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.94632020, 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 or array_like) – Chroma correlate \(C\).
  • F_L (numeric or array_like) – Luminance level adaptation factor \(F_L\).
Returns:

Colourfulness correlate \(M\).
Return type:

numeric or ndarray

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 or array_like) – Colourfulness correlate \(M\).
  • Q (numeric or array_like) – Brightness correlate \(C\).
Returns:

Saturation correlate \(s\).
Return type:

numeric or ndarray

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 or array_like) – Surround chromatic induction factor \(N_{c}\).
  • N_cb (numeric or array_like) – Chromatic induction factor \(N_{cb}\).
  • e_t (numeric or array_like) – Eccentricity factor \(e_t\).
  • t (numeric or array_like) – Temporary magnitude quantity \(t\).
  • A (numeric or array_like) – Achromatic response \(A\) for the stimulus.
  • N_bb (numeric or array_like) – Chromatic induction factor \(N_{bb}\).
Returns:

Points \(P\).
Return type:

ndarray

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)  
array([  3.0162890...e+04,   2.4237205...e+01,   1.0500000...e+00])
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 or array_like) – Point \(P_2\).
  • a (numeric or array_like) – Opponent colour dimension \(a\).
  • b (numeric or array_like) – Opponent colour dimension \(b\).
Returns:

Points \(P\).
Return type:

ndarray

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