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