colour.appearance Package¶

Sub-Modules¶

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.

Returns a new instance of the Hunt_InductionFactors class.

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

Notes

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

Create new instance of Hunt_Specification(J, C, h, s, Q, M, H, 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)[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.

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.

Notes

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

Create new instance of ATD95_Specification(h, C, Q, A_1, T_1, D_1, A_2, T_2, D_2)

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

Create new instance of CIECAM02_InductionFactors(F, c, 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\).

Returns a new instance of the CIECAM02_Specification class.

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\), (often taken to be 20% of the luminance of a white object in the scene). Y_b (numeric or array_like) – Relative luminance of background \(Y_b\) in \(cd/m^2\). 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=278.0607358..., HC=None)

colour.appearance.CIECAM02_to_XYZ(CIECAM02_specification, 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:	CIECAM02_specification (CIECAM02_Specification) – CIECAM02 colour appearance model specification. Correlate of Lightness \(J\), correlate of chroma \(C\) or correlate of colourfulness \(M\) and hue angle \(h\) in degrees must be specified, e.g. \(JCh\) or \(JMh\). 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\), (often taken to be 20% of the luminance of a white object in the scene). Y_b (numeric or array_like) – Relative luminance of background \(Y_b\) in \(cd/m^2\). surround (CIECAM02_Surround, optional) – Surround viewing conditions. discount_illuminant (bool, optional) – Discount the illuminant.
Returns:	XYZ – CIE XYZ tristimulus values.
Return type:	ndarray
Raises:	`ValueError` – If neither C or M correlates have been defined in the CIECAM02_specification argument.

Warning

The output range of that definition is non standard!

Notes

CIECAM02_specification can also be passed as a compatible argument colour.as_namedtuple() definition.
Input CIE XYZ_w tristimulus values are in domain [0, 100].
Output CIE XYZ tristimulus values are in range [0, 100].

Examples

>>> specification = CIECAM02_Specification(
...     J=41.731091132513917,
...     C=0.104707757171031,
...     h=219.048432658311780)
>>> XYZ_w = np.array([95.05, 100.00, 108.88])
>>> L_A = 318.31
>>> Y_b = 20.0
>>> CIECAM02_to_XYZ(specification, 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\).

Notes

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

Create new instance of LLAB_Specification(J, C, h, s, M, HC, a, b)

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 range 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..., s=0.0002395..., M=0.0190185..., HC=None, a=..., 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\).

Notes

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

Create new instance of Nayatani95_Specification(Lstar_P, C, h, s, Q, M, H, HC, Lstar_N)

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

Notes

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

Create new instance of RLAB_Specification(J, C, h, s, HC, a, b)

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