colour.XYZ_to_ZCAM#

Compute the ZCAM colour appearance model correlates from the specified CIE XYZ tristimulus values.

Parameters:

XYZ (Annotated[_Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], 1]) – Absolute CIE XYZ tristimulus values of test sample / stimulus.
XYZ_w (Annotated[_Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], 1]) – 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 * 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, approximating 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.
compute_H (bool) – Whether to compute Hue \(h\) quadrature \(H\). \(H\) is rarely used, and expensive to compute.

Returns:

ZCAM colour appearance model specification.

Return type:

colour.CAM_Specification_ZCAM

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 adaptation 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.
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
`XYZ`	UN	UN
`XYZ_w`	UN	UN

Range	Scale - Reference	Scale - 1
`specification.J`	UN	1
`specification.C`	UN	1
`specification.h`	360	1
`specification.s`	UN	1
`specification.Q`	UN	1
`specification.M`	UN	1
`specification.H`	400	1
`specification.HC`	UN	1
`specification.V`	UN	1
`specification.K`	UN	1
`specification.H`	UN	1

References

[SHKL18], [SHRL21], [ZL18]

Examples

>>> XYZ = np.array([185, 206, 163])
>>> XYZ_w = np.array([256, 264, 202])
>>> L_A = 264
>>> Y_b = 100
>>> surround = VIEWING_CONDITIONS_ZCAM["Average"]
>>> XYZ_to_ZCAM(XYZ, XYZ_w, L_A, Y_b, surround)
CAM_Specification_ZCAM(J=np.float64(92.2504437...), C=np.float64(3.0216926...), h=np.float64(196.3245737...), s=np.float64(19.1319556...), Q=np.float64(321.3408463...), M=np.float64(10.5256217...), H=np.float64(237.6114442...), HC=None, V=np.float64(34.7006776...), K=np.float64(25.8835968...), W=np.float64(91.6821728...))

colour.XYZ_to_ZCAM#

This Page