colour.appearance.ciecam02 Module — Colour 0.3.0 documentation

# 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()`

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`

  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`

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

  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)

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