colour.ZCAM_to_XYZ#

colour.ZCAM_to_XYZ(specification: CAM_Specification_ZCAM, XYZ_w: ArrayLike, L_A: ArrayLike, Y_b: ArrayLike, surround: InductionFactors_ZCAM = VIEWING_CONDITIONS_ZCAM['Average'], discount_illuminant: bool = False) NDArrayFloat[source]#

Convert from ZCAM specification to CIE XYZ tristimulus values.

Parameters:
  • specification (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 (ArrayLike) – 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 (ArrayLike) – 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 (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 specification 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 symmetrical 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.])