Loading [MathJax]/jax/output/HTML-CSS/jax.js

colour.appearance Package

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 Nc.
  • N_b (numeric) – Brightness surround induction factor Nb.
  • N_cb (numeric, optional) – Chromatic background induction factor Ncb, approximated using tristimulus values Yw and Yb of respectively the reference white and the background if not specified.
  • N_bb (numeric, optional) – Brightness background induction factor Nbb, approximated using tristimulus values Yw and Yb 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 Fairchild (2013) reference.

Parameters:
  • J (numeric) – Correlate of Lightness J.
  • C (numeric) – Correlate of chroma C94.
  • h (numeric) – Hue angle hS in degrees.
  • s (numeric) – Correlate of saturation s.
  • Q (numeric) – Correlate of brightness Q.
  • M (numeric) – Correlate of colourfulness M94.
  • H (numeric) – Hue h quadrature H.
  • HC (numeric) – Hue h composition HC.
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 LA in cd/m2.
  • surround (Hunt_InductionFactors, optional) – Surround viewing conditions induction factors.
  • L_AS (numeric, optional) – Scotopic luminance LAS of the illuminant, approximated if not specified.
  • CCT_w (numeric, optional) – Correlated color temperature Tcp: of the illuminant, needed to approximate LAS.
  • 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 Sw for the reference white, approximated using the tristimulus values Yw 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 Fairchild (2013) 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 A1 response.
  • T_1 (numeric) – First stage T1 response.
  • D_1 (numeric) – First stage D1 response.
  • A_2 (numeric) – Second stage A2 response.
  • T_2 (numeric) – Second stage A2 response.
  • D_2 (numeric) – Second stage D2 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/m2.
  • k_1 (numeric) – Application specific weight k1.
  • k_2 (numeric) – Application specific weight k2.
  • sigma (numeric, optional) – Constant σ 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 k1 is set to 1.0 while k2 is set to 0.0. For related colors such as typical colorimetric applications, k1 is set to 0.0 and k2 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 Nc.
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 HC.
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 LA in cd/m2.
  • Y_b (numeric) – Adapting field Y tristimulus value Yb.
  • 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 LA in cd/m2.
  • Y_b (numeric) – Adapting field Y tristimulus value Yb.
  • surround (CIECAM02_Surround, optional) – Surround viewing conditions.
  • discount_illuminant (bool, optional) – Discount the illuminant.
Returns:

XYZCIE 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 Fairchild (2013) reference.

Parameters:
  • J (numeric) – Correlate of Lightness LL.
  • C (numeric) – Correlate of chroma ChL.
  • h (numeric) – Hue angle hL in degrees.
  • s (numeric) – Correlate of saturation sL.
  • M (numeric) – Correlate of colourfulness CL.
  • HC (numeric) – Hue h composition HC.
  • a (numeric) – Opponent signal AL.
  • b (numeric) – Opponent signal BL.
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/m2.
  • L (numeric) – Absolute luminance L of reference white in cd/m2.
  • 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.3668650..., C=0.0089496..., h=270.0, s=0.0002395..., M=0.0190185..., HC=None, a=-3.4936555..., b=-0.0190185...)
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 Fairchild (2013) reference.

Parameters:
  • Lstar_P (numeric) – Correlate of achromatic Lightness Lp.
  • C (numeric) – Correlate of chroma C.
  • h (numeric) – Hue angle θ in degrees.
  • s (numeric) – Correlate of saturation S.
  • Q (numeric) – Correlate of brightness Br.
  • M (numeric) – Correlate of colourfulness M.
  • H (numeric) – Hue h quadrature H.
  • HC (numeric) – Hue h composition HC.
  • Lstar_N (numeric) – Correlate of normalised achromatic Lightness Ln.
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 Yo of achromatic background as percentage in domain [0.18, 1.0]
  • E_o (numeric) – Illuminance Eo of the viewing field in lux.
  • E_or (numeric) – Normalising illuminance Eor 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].

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 Fairchild (2013) reference.

Parameters:
  • J (numeric) – Correlate of Lightness LR.
  • C (numeric) – Correlate of achromatic chroma CR.
  • h (numeric) – Hue angle hR in degrees.
  • s (numeric) – Correlate of saturation sR.
  • HC (numeric) – Hue h composition HC.
  • a (numeric) – Red–green chromatic response aR.
  • b (numeric) – Yellow–blue chromatic response bR.
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/m2.
  • 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...)