colour.appearance Package — Colour 0.3.0 documentation

# colour.appearance Package

## Sub-Modules

- colour.appearance.atd95 Module
  - ATD (1995) Colour Vision Model
- colour.appearance.ciecam02 Module
  - CIECAM02 Colour Appearance Model
- colour.appearance.hunt Module
  - Hunt Colour Appearance Model
- colour.appearance.llab Module
  - LLAB(l:c) Colour Appearance Model
- colour.appearance.nayatani95 Module
  - Nayatani (1995) Colour Appearance Model
- colour.appearance.rlab Module
  - RLAB Colour Appearance Model

## Module Contents

class `colour.appearance.` `Hunt_InductionFactors`

  Bases: `colour.appearance.hunt.Hunt_InductionFactors`

  Hunt colour appearance model induction factors.

  Parameters: | N_c (numeric) – Chromatic surround induction factor \(N_c\). N_b (numeric) – Brightness surround induction factor \(N_b\). N_cb (numeric, optional) – Chromatic background induction factor \(N_{cb}\), approximated using tristimulus values \(Y_w\) and \(Y_b\) of respectively the reference white and the background if not specified. N_bb (numeric, optional) – Brightness background induction factor \(N_{bb}\), approximated using tristimulus values \(Y_w\) and \(Y_b\) of respectively the reference white and the background if not specified.

class `colour.appearance.` `Hunt_Specification`

  Bases: `colour.appearance.hunt.Hunt_Specification`

  Defines the Hunt colour appearance model specification.

  This specification has field names consistent with the remaining colour appearance models in `colour.appearance` but diverge from Mark D. Fairchild reference.

  Parameters: | J (numeric) – Correlate of Lightness \(J\). C (numeric) – Correlate of chroma \(C_94\). h (numeric) – Hue angle \(h_S\) in degrees. s (numeric) – Correlate of saturation \(s\). Q (numeric) – Correlate of brightness \(Q\). M (numeric) – Correlate of colourfulness \(M_94\). H (numeric) – Hue \(h\) quadrature \(H\). HC (numeric) – Hue \(h\) composition \(H_C\).

`colour.appearance.` `XYZ_to_Hunt`(XYZ, XYZ_w, XYZ_b, L_A, surround=Hunt_InductionFactors(N_c=1, N_b=75, N_cb=None, N_bb=None), L_AS=None, CCT_w=None, XYZ_p=None, p=None, S=None, S_W=None, helson_judd_effect=False, discount_illuminant=True)

  Computes the Hunt colour appearance model correlates.

  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]. XYZ_b (array_like, (3,)) – CIE XYZ colourspace matrix of background in domain [0, 100]. L_A (numeric) – Adapting field luminance \(L_A\) in \(cd/m^2\). surround (Hunt_InductionFactors, optional) – Surround viewing conditions induction factors. L_AS (numeric, optional) – Scotopic luminance \(L_{AS}\) of the illuminant, approximated if not specified. CCT_w (numeric, optional) – Correlated color temperature \(T_{cp}\): of the illuminant, needed to approximate \(L_{AS}\). XYZ_p (array_like, (3,), optional) – CIE XYZ colourspace matrix of proximal field in domain [0, 100], assumed to be equal to background if not specified. p (numeric, optional) – Simultaneous contrast / assimilation factor \(p\) with value in domain [-1, 0] when simultaneous contrast occurs and domain [0, 1] when assimilation occurs. S (numeric, optional) – Scotopic response \(S\) to the stimulus, approximated using tristimulus values \(Y\) of the stimulus if not specified. S_w (numeric, optional) – Scotopic response \(S_w\) for the reference white, approximated using the tristimulus values \(Y_w\) of the reference white if not specified. helson_judd_effect (bool, optional) – Truth value indicating whether the Helson-Judd effect should be accounted for. discount_illuminant (bool, optional) – Truth value indicating if the illuminant should be discounted.

  Warning

  The input domain of that definition is non standard!

  Notes

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

  Returns: | Hunt colour appearance model specification.
  Return type: | Hunt_Specification
  Raises: | `ValueError` – If an illegal arguments combination is specified.

  Examples

      >>> XYZ = np.array([19.01, 20.00, 21.78])
      >>> XYZ_w = np.array([95.05, 100.00, 108.88])
      >>> XYZ_b = np.array([95.05, 100.00, 108.88])
      >>> L_A = 318.31
      >>> surround = HUNT_VIEWING_CONDITIONS['Normal Scenes']
      >>> CCT_w = 6504.0
      >>> XYZ_to_Hunt(XYZ, XYZ_w, XYZ_b, L_A, surround, CCT_w=CCT_w)
      Hunt_Specification(J=30.0462678..., C=0.1210508..., h=269.2737594..., s=0.0199093..., Q=22.2097654..., M=0.1238964..., H=None, HC=None)

class `colour.appearance.` `ATD95_Specification`

  Bases: `colour.appearance.atd95.ATD95_Specification`

  Defines the ATD (1995) colour vision model specification.

  This specification has field names consistent with the remaining colour appearance models in `colour.appearance` but diverge from Mark D. Fairchild reference.

  Notes

  - This specification is the one used in the current model implementation.

  Parameters: | h (numeric) – Hue angle \(H\) in degrees. C (numeric) – Correlate of saturation \(C\). Guth (1995) incorrectly uses the terms saturation and chroma interchangeably. However, \(C\) is here a measure of saturation rather than chroma since it is measured relative to the achromatic response for the stimulus rather than that of a similarly illuminated white. Q (numeric) – Correlate of brightness \(Br\). A_1 (numeric) – First stage \(A_1\) response. T_1 (numeric) – First stage \(T_1\) response. D_1 (numeric) – First stage \(D_1\) response. A_2 (numeric) – Second stage \(A_2\) response. T_2 (numeric) – Second stage \(A_2\) response. D_2 (numeric) – Second stage \(D_2\) response.

`colour.appearance.` `XYZ_to_ATD95`(XYZ, XYZ_0, Y_0, k_1, k_2, sigma=300)

  Computes the ATD (1995) colour vision model correlates.

  Parameters: | XYZ (array_like, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_0 (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. Y_0 (numeric) – Absolute adapting field luminance in \(cd/m^2\). k_1 (numeric) – Application specific weight \(k_1\). k_2 (numeric) – Application specific weight \(k_2\). sigma (numeric, optional) – Constant \(\sigma\) varied to predict different types of data.
  Returns: | ATD (1995) colour vision model specification.
  Return type: | ATD95_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_0 colourspace matrix is in domain [0, 100].
  - For unrelated colors, there is only self-adaptation, and \(k_1\) is set to 1.0 while \(k_2\) is set to 0.0. For related colors such as typical colorimetric applications, \(k_1\) is set to 0.0 and \(k_2\) is set to a value between 15 and 50 Guth (1995).

  Examples

      >>> XYZ = np.array([19.01, 20.00, 21.78])
      >>> XYZ_0 = np.array([95.05, 100.00, 108.88])
      >>> Y_0 = 318.31
      >>> k_1 = 0.0
      >>> k_2 = 50.0
      >>> XYZ_to_ATD95(XYZ, XYZ_0, Y_0, k_1, k_2)
      ATD95_Specification(h=1.9089869..., C=1.2064060..., Q=0.1814003..., A_1=0.1787931... T_1=0.0286942..., D_1=0.0107584..., A_2=0.0192182..., T_2=0.0205377..., D_2=0.0107584...)

class `colour.appearance.` `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\).

class `colour.appearance.` `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.` `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_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...])

class `colour.appearance.` `LLAB_Specification`

  Bases: `colour.appearance.llab.LLAB_Specification`

  Defines the LLAB(l:c) colour appearance model specification.

  This specification has field names consistent with the remaining colour appearance models in `colour.appearance` but diverge from Mark D. Fairchild reference.

  Parameters: | J (numeric) – Correlate of Lightness \(L_L\). C (numeric) – Correlate of chroma \(Ch_L\). h (numeric) – Hue angle \(h_L\) in degrees. s (numeric) – Correlate of saturation \(s_L\). M (numeric) – Correlate of colourfulness \(C_L\). HC (numeric) – Hue \(h\) composition \(H^C\). a (numeric) – Opponent signal \(A_L\). b (numeric) – Opponent signal \(B_L\).

`colour.appearance.` `XYZ_to_LLAB`(XYZ, XYZ_0, Y_b, L, surround=LLAB_InductionFactors(D=1, F_S=3, F_L=1, F_C=1))

  Computes the LLAB(L:c) colour appearance model correlates.

  Parameters: | XYZ (array_like, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_0 (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. Y_b (numeric) – Luminance factor of the background in \(cd/m^2\). L (numeric) – Absolute luminance \(L\) of reference white in \(cd/m^2\). surround (LLAB_InductionFactors, optional) – Surround viewing conditions induction factors.
  Returns: | LLAB(L:c) colour appearance model specification.
  Return type: | LLAB_Specification

  Warning

  The output domain of that definition is non standard!

  Notes

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

  Examples

      >>> XYZ = np.array([19.01, 20, 21.78])
      >>> XYZ_0 = np.array([95.05, 100, 108.88])
      >>> Y_b = 20.0
      >>> L = 318.31
      >>> surround = LLAB_VIEWING_CONDITIONS['ref_average_4_minus']
      >>> XYZ_to_LLAB(XYZ, XYZ_0, Y_b, L, surround)
      LLAB_Specification(J=37.3680474..., C=0.0086506..., h=229.4635727..., s=0.0002314..., M=0.0183832..., HC=None, a=-0.0119478..., b=-0.0139711...)

class `colour.appearance.` `Nayatani95_Specification`

  Bases: `colour.appearance.nayatani95.Nayatani95_Specification`

  Defines the Nayatani (1995) colour appearance model specification.

  This specification has field names consistent with the remaining colour appearance models in `colour.appearance` but diverge from Mark D. Fairchild reference.

  Parameters: | Lstar_P (numeric) – Correlate of achromatic Lightness \(L_p^\star\). C (numeric) – Correlate of chroma \(C\). h (numeric) – Hue angle \(\theta\) in degrees. s (numeric) – Correlate of saturation \(S\). Q (numeric) – Correlate of brightness \(B_r\). M (numeric) – Correlate of colourfulness \(M\). H (numeric) – Hue \(h\) quadrature \(H\). HC (numeric) – Hue \(h\) composition \(H_C\). Lstar_N (numeric) – Correlate of normalised achromatic Lightness \(L_n^\star\).

`colour.appearance.` `XYZ_to_Nayatani95`(XYZ, XYZ_n, Y_o, E_o, E_or, n=1)

  Computes the Nayatani (1995) colour appearance model correlates.

  Parameters: | XYZ (array_like, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_n (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. Y_o (numeric) – Luminance factor \(Y_o\) of achromatic background as percentage in domain [0.18,] E_o (numeric) – Illuminance \(E_o\) of the viewing field in lux. E_or (numeric) – Normalising illuminance \(E_{or}\) in lux usually in domain [1000, 3000] n (numeric, optional) – Noise term used in the non linear chromatic adaptation model.
  Returns: | Nayatani (1995) colour appearance model specification.
  Return type: | Nayatani95_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_n colourspace matrix is in domain [0, 100].

  Raises: | `ValueError` – If Luminance factor \(Y_o\) is not greater or equal than 18%.

  Examples

      >>> XYZ = np.array([19.01, 20, 21.78])
      >>> XYZ_n = np.array([95.05, 100, 108.88])
      >>> Y_o = 20.0
      >>> E_o = 5000.0
      >>> E_or = 1000.0
      >>> XYZ_to_Nayatani95(XYZ, XYZ_n, Y_o, E_o, E_or)
      Nayatani95_Specification(Lstar_P=49.9998829..., C=0.0133550..., h=257.5232268..., s=0.0133550..., Q=62.6266734..., M=0.0167262..., H=None, HC=None, Lstar_N=50.0039154...)

class `colour.appearance.` `RLAB_Specification`

  Bases: `colour.appearance.rlab.RLAB_Specification`

  Defines the RLAB colour appearance model specification.

  This specification has field names consistent with the remaining colour appearance models in `colour.appearance` but diverge from Mark D. Fairchild reference.

  Parameters: | J (numeric) – Correlate of Lightness \(L^R\). C (numeric) – Correlate of achromatic chroma \(C^R\). h (numeric) – Hue angle \(h^R\) in degrees. s (numeric) – Correlate of saturation \(s^R\). HC (numeric) – Hue \(h\) composition \(H^C\). a (numeric) – Red–green chromatic response \(a^R\). b (numeric) – Yellow–blue chromatic response \(b^R\).

`colour.appearance.` `XYZ_to_RLAB`(XYZ, XYZ_n, Y_n, sigma=0.4347826086956522, D=1)

  Computes the RLAB model color appearance correlates.

  Parameters: | XYZ (array_like, (3, n)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_n (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. Y_n (numeric) – Absolute adapting luminance in \(cd/m^2\). sigma (numeric, optional) – Relative luminance of the surround, see `RLAB_VIEWING_CONDITIONS` for reference. D (numeric, optional) – Discounting-the-Illuminant factor in domain [0, 1].
  Returns: | RLAB colour appearance model specification.
  Return type: | RLAB_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_n colourspace matrix is in domain [0, 100].

  Examples

      >>> XYZ = np.array([19.01, 20, 21.78])
      >>> XYZ_n = np.array([109.85, 100, 35.58])
      >>> Y_n = 31.83
      >>> sigma = RLAB_VIEWING_CONDITIONS['Average']
      >>> D = RLAB_D_FACTOR['Hard Copy Images']
      >>> XYZ_to_RLAB(XYZ, XYZ_n, Y_n, sigma, D)
      RLAB_Specification(J=49.8347069..., C=54.8700585..., h=286.4860208..., s=1.1010410..., HC=None, a=15.5711021..., b=-52.6142956...)