PR: Improve CFI 2017 and TM30-18 Performance (#1120)

* Update various docstrings.

* Ensure that spectral distribution not starting or  ending on a tenth wavelength and having an interval of 10 or 20 can be integrated using practise "ASTM E308-15".

* Implement support for better `ndarray` copy management in `colour.continuous.Signal` class.

* Optionally compute hue quadrature

* Optimize blackbody spectrum generation

* Reshape within the daylight spectrum function

* Optimize CCT computation

* lazy compute NPM for RGB spaces

Saves a ton of time on first colour import

* Various speedups in CFI17

Re-architect output types
TCS computation vectorize instead of list comp

* Use shape broadcasting to skip list comprehension

* Improve hashing speed of signals

* Improve spectrum init time

* address review and tests

* accelerate hash functions

* switch to optional xxhash feature

* Remove illuminant modifications side effect

* re-architect output to include CAM

* Re-evaluate speed in planck generation

* Improve default interpolation performance

Repair documenation build error

fix test due to default interpolation change


[pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

fix peculier init case in MaxOS environment

fix type checking

Auto stash before revert of "Improve default interpolation performance"

* fix tests

fix domain / range copy on signal init

fix doctests

* trim could cause an incorrect result in some edge cases (neq interval)

* Hash signal objects now that we have the power of xxhash

* resolve old comments on PR

* Improve hue quadrature computation consistency in CAMs.

* Improve spectral generator default interpolation changes.

- Remove unnecessary interpolator change.
- Improve documentation around spectral generator interpolation changes.

* Improve unit tests for `colour.planck_law` definition.

* Remove colour quality scale unnecessary unit test changes.

* Revert `DataColorimetry_TCS_CIE2017` fields to "Colour" 0.4.2 ordering.

* Update various doctests.

* Update various imports.

* Varnish some performance code changes.

* Imeplement or simplify directory change in various utility scripts.

* Update various docstrings.

---------

Co-authored-by: Thomas Mansencal <[email protected]>

Author: tjdcs

colour/appearance/cam16.py

@@ -173,6 +173,7 @@ def XYZ_to_CAM16(
     surround: InductionFactors_CIECAM02
     | InductionFactors_CAM16 = VIEWING_CONDITIONS_CAM16["Average"],
     discount_illuminant: bool = False,
+    compute_H: bool = True,
 ) -> CAM_Specification_CAM16:
     """
     Compute the *CAM16* colour appearance model correlates from given
@@ -198,6 +199,9 @@ def XYZ_to_CAM16(
         Surround viewing conditions induction factors.
     discount_illuminant
         Truth value indicating if the illuminant should be discounted.
+    compute_H
+        Whether to compute *Hue* :math:`h` quadrature :math:`H`. :math:`H` is
+        rarely used, and expensive to compute.
 
     Returns
     -------
@@ -304,7 +308,7 @@ def XYZ_to_CAM16(
     e_t = eccentricity_factor(h)
 
     # Computing hue :math:`h` quadrature :math:`H`.
-    H = hue_quadrature(h)
+    H = hue_quadrature(h) if compute_H else np.full(h.shape, np.nan)
     # TODO: Compute hue composition.
 
     # Step 6

colour/appearance/ciecam02.py

@@ -231,6 +231,7 @@ def XYZ_to_CIECAM02(
         "Average"
     ],
     discount_illuminant: bool = False,
+    compute_H: bool = True,
 ) -> CAM_Specification_CIECAM02:
     """
     Compute the *CIECAM02* colour appearance model correlates from given
@@ -256,6 +257,9 @@ def XYZ_to_CIECAM02(
         Surround viewing conditions induction factors.
     discount_illuminant
         Truth value indicating if the illuminant should be discounted.
+    compute_H
+        Whether to compute *Hue* :math:`h` quadrature :math:`H`. :math:`H` is
+        rarely used, and expensive to compute.
 
     Returns
     -------
@@ -368,7 +372,7 @@ def XYZ_to_CIECAM02(
     h = hue_angle(a, b)
 
     # Computing hue :math:`h` quadrature :math:`H`.
-    H = hue_quadrature(h)
+    H = hue_quadrature(h) if compute_H else np.full(h.shape, np.nan)
     # TODO: Compute hue composition.
 
     # Computing eccentricity factor *e_t*.

colour/appearance/ciecam16.py

@@ -168,6 +168,7 @@ def XYZ_to_CIECAM16(
     surround: InductionFactors_CIECAM02
     | InductionFactors_CIECAM16 = VIEWING_CONDITIONS_CIECAM16["Average"],
     discount_illuminant: bool = False,
+    compute_H: bool = True,
 ) -> CAM_Specification_CIECAM16:
     """
     Compute the *CIECAM16* colour appearance model correlates from given
@@ -193,6 +194,9 @@ def XYZ_to_CIECAM16(
         Surround viewing conditions induction factors.
     discount_illuminant
         Truth value indicating if the illuminant should be discounted.
+    compute_H
+        Whether to compute *Hue* :math:`h` quadrature :math:`H`. :math:`H` is
+        rarely used, and expensive to compute.
 
     Returns
     -------
@@ -316,7 +320,7 @@ def XYZ_to_CIECAM16(
     e_t = eccentricity_factor(h)
 
     # Computing hue :math:`h` quadrature :math:`H`.
-    H = hue_quadrature(h)
+    H = hue_quadrature(h) if compute_H else np.full(h.shape, np.nan)
     # TODO: Compute hue composition.
 
     # Step 6

colour/appearance/hellwig2022.py

@@ -188,6 +188,7 @@ def XYZ_to_Hellwig2022(
     surround: InductionFactors_CIECAM02
     | InductionFactors_Hellwig2022 = VIEWING_CONDITIONS_HELLWIG2022["Average"],
     discount_illuminant: bool = False,
+    compute_H: bool = True,
 ) -> CAM_Specification_Hellwig2022:
     """
     Compute the *Hellwig and Fairchild (2022)* colour appearance model
@@ -216,6 +217,9 @@ def XYZ_to_Hellwig2022(
         Surround viewing conditions induction factors.
     discount_illuminant
         Truth value indicating if the illuminant should be discounted.
+    compute_H
+        Whether to compute *Hue* :math:`h` quadrature :math:`H`. :math:`H` is
+        rarely used, and expensive to compute.
 
     Returns
     -------
@@ -346,7 +350,7 @@ def XYZ_to_Hellwig2022(
     e_t = eccentricity_factor(h)
 
     # Computing hue :math:`h` quadrature :math:`H`.
-    H = hue_quadrature(h)
+    H = hue_quadrature(h) if compute_H else np.full(h.shape, np.nan)
     # TODO: Compute hue composition.
 
     # Step 6

colour/appearance/kim2009.py

@@ -219,8 +219,9 @@ def XYZ_to_Kim2009(
     L_A: ArrayLike,
     media: MediaParameters_Kim2009 = MEDIA_PARAMETERS_KIM2009["CRT Displays"],
     surround: InductionFactors_Kim2009 = VIEWING_CONDITIONS_KIM2009["Average"],
-    discount_illuminant: bool = False,
     n_c: float = 0.57,
+    discount_illuminant: bool = False,
+    compute_H: bool = True,
 ) -> CAM_Specification_Kim2009:
     """
     Compute the *Kim, Weyrich and Kautz (2009)* colour appearance model
@@ -241,6 +242,9 @@ def XYZ_to_Kim2009(
         Surround viewing conditions induction factors.
     discount_illuminant
         Truth value indicating if the illuminant should be discounted.
+    compute_H
+        Whether to compute *Hue* :math:`h` quadrature :math:`H`. :math:`H` is
+        rarely used, and expensive to compute.
     n_c
         Cone response sigmoidal curve modulating factor :math:`n_c`.
 
@@ -365,7 +369,7 @@ def XYZ_to_Kim2009(
     h = np.degrees(np.arctan2(b, a)) % 360
 
     # Computing hue :math:`h` quadrature :math:`H`.
-    H = hue_quadrature(h)
+    H = hue_quadrature(h) if compute_H else np.full(h.shape, np.nan)
 
     return CAM_Specification_Kim2009(
         as_float(from_range_100(J)),
@@ -385,8 +389,8 @@ def Kim2009_to_XYZ(
     L_A: ArrayLike,
     media: MediaParameters_Kim2009 = MEDIA_PARAMETERS_KIM2009["CRT Displays"],
     surround: InductionFactors_Kim2009 = VIEWING_CONDITIONS_KIM2009["Average"],
-    discount_illuminant: bool = False,
     n_c: float = 0.57,
+    discount_illuminant: bool = False,
 ) -> NDArrayFloat:
     """
     Convert from *Kim, Weyrich and Kautz (2009)* specification to *CIE XYZ*

colour/appearance/zcam.py

@@ -308,6 +308,7 @@ def XYZ_to_ZCAM(
     Y_b: ArrayLike,
     surround: InductionFactors_ZCAM = VIEWING_CONDITIONS_ZCAM["Average"],
     discount_illuminant: bool = False,
+    compute_H: bool = True,
 ) -> CAM_Specification_ZCAM:
     """
     Compute the *ZCAM* colour appearance model correlates from given *CIE XYZ*
@@ -335,6 +336,9 @@ def XYZ_to_ZCAM(
         Surround viewing conditions induction factors.
     discount_illuminant
         Truth value indicating if the illuminant should be discounted.
+    compute_H
+        Whether to compute *Hue* :math:`h` quadrature :math:`H`. :math:`H` is
+        rarely used, and expensive to compute.
 
     Returns
     -------
@@ -460,7 +464,7 @@ def XYZ_to_ZCAM(
     h_z = hue_angle(a_z, b_z)
 
     # Step 4 (Forward) - Computing hue quadrature :math:`H`.
-    H = hue_quadrature(h_z)
+    H = hue_quadrature(h_z) if compute_H else np.full(h_z.shape, np.nan)
 
     # Computing eccentricity factor :math:`e_z`.
     e_z = 1.015 + np.cos(np.radians(89.038 + h_z % 360))

colour/colorimetry/blackbody.py

@@ -18,7 +18,6 @@
 
 import numpy as np
 
-from colour.algebra import sdiv, sdiv_mode
 from colour.colorimetry import (
     SPECTRAL_SHAPE_DEFAULT,
     SpectralDistribution,
@@ -27,6 +26,7 @@
 from colour.constants import CONSTANT_BOLTZMANN, CONSTANT_LIGHT_SPEED
 from colour.hints import ArrayLike, NDArrayFloat
 from colour.utilities import as_float, as_float_array
+from colour.utilities.common import attest
 
 __author__ = "Colour Developers"
 __copyright__ = "Copyright 2013 Colour Developers"
@@ -124,13 +124,12 @@ def planck_law(
     l = as_float_array(wavelength)  # noqa: E741
     t = as_float_array(temperature)
 
+    attest(np.all(l > 0), "Wavelengths must be positive real numbers!")
+
     l = np.ravel(l)[..., None]  # noqa: E741
     t = np.ravel(t)[None, ...]
 
-    with sdiv_mode():
-        d = sdiv(c2, (n * l * t))
-
-    d[d != 0] = np.expm1(d[d != 0]) ** -1
+    d = 1 / np.expm1(c2 / (n * l * t))
     p = ((c1 * n**-2 * l**-5) / np.pi) * d
 
     return as_float(np.squeeze(p))

colour/colorimetry/generation.py

@@ -36,6 +36,7 @@
 
 import numpy as np
 
+from colour.algebra.interpolation import LinearInterpolator
 from colour.colorimetry import (
     SPECTRAL_SHAPE_DEFAULT,
     MultiSpectralDistributions,
@@ -113,6 +114,7 @@ def sd_constant(
     -----
     -   By default, the spectral distribution will use the shape given by
         :attr:`colour.SPECTRAL_SHAPE_DEFAULT` attribute.
+    -   The interpolator is set to :class:`colour.LinearInterpolator` class.
 
     Examples
     --------
@@ -123,7 +125,7 @@ def sd_constant(
     100.0
     """
 
-    settings = {"name": f"{k} Constant"}
+    settings = {"name": f"{k} Constant", "interpolator": LinearInterpolator}
     settings.update(kwargs)
 
     values = full(len(shape.wavelengths), k)
@@ -157,6 +159,7 @@ def sd_zeros(
     -----
     -   By default, the spectral distribution will use the shape given by
         :attr:`colour.SPECTRAL_SHAPE_DEFAULT` attribute.
+    -   The interpolator is set to :class:`colour.LinearInterpolator` class.
 
     Examples
     --------
@@ -196,6 +199,7 @@ def sd_ones(
     -----
     -   By default, the spectral distribution will use the shape given by
         :attr:`colour.SPECTRAL_SHAPE_DEFAULT` attribute.
+    -   The interpolator is set to :class:`colour.LinearInterpolator` class.
 
     Examples
     --------
@@ -244,6 +248,7 @@ def msds_constant(
     -----
     -   By default, the multi-spectral distributions will use the shape given
         by :attr:`colour.SPECTRAL_SHAPE_DEFAULT` attribute.
+    -   The interpolator is set to :class:`colour.LinearInterpolator` class.
 
     Examples
     --------
@@ -256,7 +261,7 @@ def msds_constant(
     ['a', 'b', 'c']
     """
 
-    settings = {"name": f"{k} Constant"}
+    settings = {"name": f"{k} Constant", "interpolator": LinearInterpolator}
     settings.update(kwargs)
 
     wavelengths = shape.wavelengths
@@ -299,6 +304,7 @@ def msds_zeros(
     -----
     -   By default, the multi-spectral distributions will use the shape given
         by :attr:`colour.SPECTRAL_SHAPE_DEFAULT` attribute.
+    -   The interpolator is set to :class:`colour.LinearInterpolator` class.
 
     Examples
     --------
@@ -346,6 +352,7 @@ def msds_ones(
     -----
     -   By default, the multi-spectral distributions will use the shape given
         by :attr:`colour.SPECTRAL_SHAPE_DEFAULT` attribute.
+    -   The interpolator is set to :class:`colour.LinearInterpolator` class.
 
     Examples
     --------
@@ -755,7 +762,7 @@ def sd_multi_leds_Ohno2005(
 
     sd = sd_zeros(shape)
 
-    for (peak_wavelength, fwhm_s, peak_power_ratio) in zip(
+    for peak_wavelength, fwhm_s, peak_power_ratio in zip(
         peak_wavelengths, fwhm, peak_power_ratios
     ):
         sd += (

colour/colorimetry/illuminants.py

@@ -34,6 +34,7 @@
     SDS_BASIS_FUNCTIONS_CIE_ILLUMINANT_D_SERIES,
     SpectralDistribution,
     SpectralShape,
+    reshape_sd,
 )
 from colour.hints import ArrayLike, NDArrayFloat
 from colour.utilities import as_float_array, as_float, tsplit
@@ -136,7 +137,9 @@ def sd_CIE_standard_illuminant_A(
 
 
 def sd_CIE_illuminant_D_series(
-    xy: ArrayLike, M1_M2_rounding: bool = True
+    xy: ArrayLike,
+    M1_M2_rounding: bool = True,
+    shape: SpectralShape | None = None,
 ) -> SpectralDistribution:
     """
     Return the spectral distribution of given *CIE Illuminant D Series* using
@@ -149,6 +152,9 @@ def sd_CIE_illuminant_D_series(
     M1_M2_rounding
         Whether to round :math:`M1` and :math:`M2` variables to 3 decimal
         places in order to yield the internationally agreed values.
+    shape
+        Specifies the shape of the returned SpectralDistribution. Optional,
+        default None.
 
     Returns
     -------
@@ -306,6 +312,11 @@ def sd_CIE_illuminant_D_series(
     S1 = SDS_BASIS_FUNCTIONS_CIE_ILLUMINANT_D_SERIES["S1"]
     S2 = SDS_BASIS_FUNCTIONS_CIE_ILLUMINANT_D_SERIES["S2"]
 
+    if shape is not None:
+        S0 = reshape_sd(S0, shape=shape, copy=False)
+        S1 = reshape_sd(S1, shape=shape, copy=False)
+        S2 = reshape_sd(S2, shape=shape, copy=False)
+
     distribution = S0.values + M1 * S1.values + M2 * S2.values
 
     return SpectralDistribution(