colour.appearance Package

Module Contents

class colour.appearance.Hunt_InductionFactors[source]

Bases: colour.appearance.hunt.Hunt_InductionFactors

Hunt colour appearance model induction factors.

Parameters:
  • N_c (numeric or array_like) – Chromatic surround induction factor \(N_c\).
  • N_b (numeric or array_like) – Brightness surround induction factor \(N_b\).
  • N_cb (numeric or array_like, 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 or array_like, 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[source]

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 or array_like) – Correlate of Lightness \(J\).
  • C (numeric or array_like) – Correlate of chroma \(C_94\).
  • h (numeric or array_like) – Hue angle \(h_S\) 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_94\).
  • H (numeric or array_like) – Hue \(h\) quadrature \(H\).
  • HC (numeric or array_like) – 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)[source]

Computes the Hunt colour appearance model correlates.

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].
  • XYZ_b (array_like) – CIE XYZ tristimulus values of background in domain [0, 100].
  • L_A (numeric or array_like) – Adapting field luminance \(L_A\) in \(cd/m^2\).
  • surround (Hunt_InductionFactors, optional) – Surround viewing conditions induction factors.
  • L_AS (numeric or array_like, optional) – Scotopic luminance \(L_{AS}\) of the illuminant, approximated if not specified.
  • CCT_w (numeric or array_like, optional) – Correlated color temperature \(T_{cp}\): of the illuminant, needed to approximate \(L_{AS}\).
  • XYZ_p (array_like, optional) – CIE XYZ tristimulus values of proximal field in domain [0, 100], assumed to be equal to background if not specified.
  • p (numeric or array_like, 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 or array_like, optional) – Scotopic response \(S\) to the stimulus, approximated using tristimulus values \(Y\) of the stimulus if not specified.
  • S_w (numeric or array_like, 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 tristimulus values are in domain [0, 100].
  • Input CIE XYZ_b tristimulus values are in domain [0, 100].
  • Input CIE XYZ_w tristimulus values are in domain [0, 100].
  • Input CIE XYZ_p tristimulus values are 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[source]

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 or array_like) – Hue angle \(H\) in degrees.
  • C (numeric or array_like) – 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 or array_like) – Correlate of brightness \(Br\).
  • A_1 (numeric or array_like) – First stage \(A_1\) response.
  • T_1 (numeric or array_like) – First stage \(T_1\) response.
  • D_1 (numeric or array_like) – First stage \(D_1\) response.
  • A_2 (numeric or array_like) – Second stage \(A_2\) response.
  • T_2 (numeric or array_like) – Second stage \(A_2\) response.
  • D_2 (numeric or array_like) – Second stage \(D_2\) response.
colour.appearance.XYZ_to_ATD95(XYZ, XYZ_0, Y_0, k_1, k_2, sigma=300)[source]

Computes the ATD (1995) colour vision model correlates.

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100].
  • XYZ_0 (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100].
  • Y_0 (numeric or array_like) – Absolute adapting field luminance in \(cd/m^2\).
  • k_1 (numeric or array_like) – Application specific weight \(k_1\).
  • k_2 (numeric or array_like) – Application specific weight \(k_2\).
  • sigma (numeric or array_like, 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 tristimulus values are in domain [0, 100].
  • Input CIE XYZ_0 tristimulus values are 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[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\).
class colour.appearance.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.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_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:
  • 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.
  • 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...])
class colour.appearance.LLAB_Specification[source]

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 or array_like) – Correlate of Lightness \(L_L\).
  • C (numeric or array_like) – Correlate of chroma \(Ch_L\).
  • h (numeric or array_like) – Hue angle \(h_L\) in degrees.
  • s (numeric or array_like) – Correlate of saturation \(s_L\).
  • M (numeric or array_like) – Correlate of colourfulness \(C_L\).
  • HC (numeric or array_like) – Hue \(h\) composition \(H^C\).
  • a (numeric or array_like) – Opponent signal \(A_L\).
  • b (numeric or array_like) – 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))[source]

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

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100].
  • XYZ_0 (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100].
  • Y_b (numeric or array_like) – Luminance factor of the background in \(cd/m^2\).
  • L (numeric or array_like) – 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 tristimulus values are in domain [0, 100].
  • Input CIE XYZ_0 tristimulus values are in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20.00, 21.78])
>>> XYZ_0 = np.array([95.05, 100.00, 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.0000000..., s=0.0002395..., M=0.0190185..., HC=None, a=1.4742890..., b=-0.0190185...)
class colour.appearance.Nayatani95_Specification[source]

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 or array_like) – Correlate of achromatic Lightness \(L_p^\star\).
  • C (numeric or array_like) – Correlate of chroma \(C\).
  • h (numeric or array_like) – Hue angle \(\theta\) in degrees.
  • s (numeric or array_like) – Correlate of saturation \(S\).
  • Q (numeric or array_like) – Correlate of brightness \(B_r\).
  • 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\).
  • Lstar_N (numeric or array_like) – Correlate of normalised achromatic Lightness \(L_n^\star\).
colour.appearance.XYZ_to_Nayatani95(XYZ, XYZ_n, Y_o, E_o, E_or, n=1)[source]

Computes the Nayatani (1995) colour appearance model correlates.

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100].
  • XYZ_n (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100].
  • Y_o (numeric or array_like) – Luminance factor \(Y_o\) of achromatic background as percentage in domain [0.18, 1.0]
  • E_o (numeric or array_like) – Illuminance \(E_o\) of the viewing field in lux.
  • E_or (numeric or array_like) – Normalising illuminance \(E_{or}\) in lux usually in domain [1000, 3000]
  • n (numeric or array_like, 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 tristimulus values are in domain [0, 100].
  • Input CIE XYZ_n tristimulus values are in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20.00, 21.78])
>>> XYZ_n = np.array([95.05, 100.00, 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[source]

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 or array_like) – Correlate of Lightness \(L^R\).
  • C (numeric or array_like) – Correlate of achromatic chroma \(C^R\).
  • h (numeric or array_like) – Hue angle \(h^R\) in degrees.
  • s (numeric or array_like) – Correlate of saturation \(s^R\).
  • HC (numeric or array_like) – Hue \(h\) composition \(H^C\).
  • a (numeric or array_like) – Red–green chromatic response \(a^R\).
  • b (numeric or array_like) – Yellow–blue chromatic response \(b^R\).
colour.appearance.XYZ_to_RLAB(XYZ, XYZ_n, Y_n, sigma=0.4347826086956522, D=1)[source]

Computes the RLAB model color appearance correlates.

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100].
  • XYZ_n (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100].
  • Y_n (numeric or array_like) – Absolute adapting luminance in \(cd/m^2\).
  • sigma (numeric or array_like, optional) – Relative luminance of the surround, see RLAB_VIEWING_CONDITIONS for reference.
  • D (numeric or array_like, 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 tristimulus values are in domain [0, 100].
  • Input CIE XYZ_n tristimulus values are in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20.00, 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...)