Processing math: 100%

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 Mark D. Fairchild 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 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 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 Mark D. Fairchild 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.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 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,]
  • 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].
Raises:ValueError – If Luminance factor Yo 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 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...)