colour.ZCAM_to_XYZ

colour.ZCAM_to_XYZ(specification: colour.appearance.zcam.CAM_Specification_ZCAM, XYZ_w: ArrayLike, L_A: FloatingOrArrayLike, Y_b: FloatingOrArrayLike, surround: colour.appearance.zcam.InductionFactors_ZCAM = VIEWING_CONDITIONS_ZCAM['Average'], discount_illuminant: bool = False) → numpy.ndarray

Convert from ZCAM specification to CIE XYZ tristimulus values.

Parameters

• specification (colour.appearance.zcam.CAM_Specification_ZCAM) – ZCAM 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 (ArrayLike) – Absolute CIE XYZ tristimulus values of the white under reference illuminant.

• L_A (FloatingOrArrayLike) – Test adapting field luminance \(L_A\) in \(cd/m^2\) such as \(L_A = L_w * Y_b / 100\) (where \(L_w\) is luminance of the reference white and \(Y_b\) is the background luminance factor).

• Y_b (FloatingOrArrayLike) – Luminous factor of background \(Y_b\) such as \(Y_b = 100 x L_b / L_w\) where \(L_w\) is the luminance of the light source and \(L_b\) is the luminance of the background. For viewing images, \(Y_b\) can be the average \(Y\) value for the pixels in the entire image, or frequently, a \(Y\) value of 20, approximate an \(L^*\) of 50 is used.

• surround (colour.appearance.zcam.InductionFactors_ZCAM) – Surround viewing conditions induction factors.

• discount_illuminant (bool) – Truth value indicating if the illuminant should be discounted.

Returns

CIE XYZ tristimulus values.

Return type

numpy.ndarray

Raises

ValueError – If neither C or M correlates have been defined in the CAM_Specification_ZCAM argument.

Warning

The underlying SMPTE ST 2084:2014 transfer function is an absolute transfer function.

Notes

• Safdar, Hardeberg and Luo (2021) does not specify how the chromatic adaptation to CIE Standard Illuminant D65 in Step 0 should be performed. A one-step Von Kries chromatic adaptation transform is not symetrical or transitive when a degree of adptation is involved. Safdar, Hardeberg and Luo (2018) uses Zhai and Luo (2018) two-steps chromatic adaptation transform, thus it seems sensible to adopt this transform for the ZCAM colour appearance model until more information is available. It is worth noting that a one-step Von Kries chromatic adaptation transform with support for degree of adaptation produces values closer to the supplemental document compared to the Zhai and Luo (2018) two-steps chromatic adaptation transform but then the ZCAM colour appearance model does not round-trip properly.

• Step 4 of the inverse model uses a rounded exponent of 1.3514 preventing the model to round-trip properly. Given that this implementation takes some liberties with respect to the chromatic adaptation transform to use, it was deemed appropriate to use an exponent value that enables the ZCAM colour appearance model to round-trip.

• The underlying SMPTE ST 2084:2014 transfer function is an absolute transfer function, thus the domain and range values for the Reference and 1 scales are only indicative that the data is not affected by scale transformations.

Domain	Scale - Reference	Scale - 1
CAM_Specification_ZCAM.J	[UN]	[0, 1]
CAM_Specification_ZCAM.C	[UN]	[0, 1]
CAM_Specification_ZCAM.h	[0, 360]	[0, 1]
CAM_Specification_ZCAM.s	[UN]	[0, 1]
CAM_Specification_ZCAM.Q	[UN]	[0, 1]
CAM_Specification_ZCAM.M	[UN]	[0, 1]
CAM_Specification_ZCAM.H	[0, 400]	[0, 1]
CAM_Specification_ZCAM.HC	[UN]	[0, 1]
CAM_Specification_ZCAM.V	[UN]	[0, 1]
CAM_Specification_ZCAM.K	[UN]	[0, 1]
CAM_Specification_ZCAM.H	[UN]	[0, 1]

Range	Scale - Reference	Scale - 1
XYZ	[UN]	[UN]

References

[SHKL18], [SHRL21], [ZL18]

Examples

>>> specification = CAM_Specification_ZCAM(J=92.250443780723629,
...                                        C=3.0216926733329013,
...                                        h=196.32457375575581)
>>> XYZ_w = np.array([256, 264, 202])
>>> L_A = 264
>>> Y_b = 100
>>> surround = VIEWING_CONDITIONS_ZCAM['Average']
>>> ZCAM_to_XYZ(specification, XYZ_w, L_A, Y_b, surround)
... 
array([ 185.,  206.,  163.])

previous

colour.XYZ_to_ZCAM

next

colour.CAM_Specification_ZCAM