colour.appearance Package¶

Sub-Modules¶

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