CRI: Fix integration of TCS15

This commit fixes the TCS15 integration with the following steps:
* Adding COLOUR_RENDERING_INDEX_METHODS to switch between "CIE 1995" and
  "CIE 2024" TCS sets
* Introduce `SDS_TCS_SETS` to get the TCS set for the desired method
* Introduce SDS_TCS_CIE_1995 (was SDS_TCS before) SDS_TCS_CIE_2024
* Add new parameter `method` to colour.colour_rendering_index to select
  the TCS set
* Add a test for this new `method` parameter
* Adjust the docs to reflect these changes with inspiration from
  the symbols exported by the CQS module

Suggested-by: Thomas Mansencal <[email protected]>
Signed-off-by: Christoph Müllner <[email protected]>

Author: cmuellner

README.rst

@@ -1802,6 +1802,14 @@ Colour Rendering Index
 
     64.233724121664793
 
+.. code-block:: python
+
+    sorted(colour.COLOUR_RENDERING_INDEX_METHODS)
+
+.. code-block:: text
+
+    ['CIE 1995', 'CIE 2024']
+
 Academy Spectral Similarity Index (SSI)
 ***************************************
 

colour/__init__.py

@@ -443,6 +443,7 @@
 from .quality import (
     COLOUR_FIDELITY_INDEX_METHODS,
     COLOUR_QUALITY_SCALE_METHODS,
+    COLOUR_RENDERING_INDEX_METHODS,
     colour_fidelity_index,
     colour_quality_scale,
     colour_rendering_index,
@@ -838,6 +839,7 @@
 __all__ += [
     "COLOUR_FIDELITY_INDEX_METHODS",
     "COLOUR_QUALITY_SCALE_METHODS",
+    "COLOUR_RENDERING_INDEX_METHODS",
     "colour_fidelity_index",
     "colour_quality_scale",
     "colour_rendering_index",

colour/quality/__init__.py

@@ -14,7 +14,11 @@
     ColourRendering_Specification_CIE2017,
     colour_fidelity_index_CIE2017,
 )
-from .cri import ColourRendering_Specification_CRI, colour_rendering_index
+from .cri import (
+    COLOUR_RENDERING_INDEX_METHODS,
+    ColourRendering_Specification_CRI,
+    colour_rendering_index,
+)
 from .cqs import (
     COLOUR_QUALITY_SCALE_METHODS,
     ColourRendering_Specification_CQS,
@@ -38,6 +42,7 @@
     "colour_fidelity_index_ANSIIESTM3018",
 ]
 __all__ += [
+    "COLOUR_RENDERING_INDEX_METHODS",
     "ColourRendering_Specification_CRI",
     "colour_rendering_index",
 ]

colour/quality/cri.py

@@ -40,9 +40,10 @@
 
 from colour.hints import cast
 from colour.models import UCS_to_uv, XYZ_to_UCS, XYZ_to_xyY
-from colour.quality.datasets.tcs import INDEXES_TO_NAMES_TCS, SDS_TCS
+from colour.quality.datasets.tcs import INDEXES_TO_NAMES_TCS, SDS_TCS_SETS
 from colour.temperature import CCT_to_xy_CIE_D, uv_to_CCT_Robertson1968
-from colour.utilities import domain_range_scale
+from colour.utilities import domain_range_scale, validate_method
+from colour.utilities.documentation import DocstringTuple, is_documentation_building
 
 __author__ = "Colour Developers"
 __copyright__ = "Copyright 2013 Colour Developers"
@@ -55,6 +56,7 @@
     "DataColorimetry_TCS",
     "DataColourQualityScale_TCS",
     "ColourRendering_Specification_CRI",
+    "COLOUR_RENDERING_INDEX_METHODS",
     "colour_rendering_index",
     "tcs_colorimetry_data",
     "colour_rendering_indexes",
@@ -110,26 +112,47 @@ class ColourRendering_Specification_CRI:
     ]
 
 
+COLOUR_RENDERING_INDEX_METHODS: tuple = ("CIE 1995", "CIE 2024")
+if is_documentation_building():  # pragma: no cover
+    COLOUR_RENDERING_INDEX_METHODS = DocstringTuple(COLOUR_RENDERING_INDEX_METHODS)
+    COLOUR_RENDERING_INDEX_METHODS.__doc__ = """
+Supported *Colour Rendering Index* (CRI) computation methods.
+
+References
+----------
+:cite:`Ohno2008a`
+"""
+
+
 @typing.overload
 def colour_rendering_index(
-    sd_test: SpectralDistribution, additional_data: Literal[True] = True
+    sd_test: SpectralDistribution,
+    additional_data: Literal[True] = True,
+    method: Literal["CIE 1995", "CIE 2024"] | str = ...,
 ) -> ColourRendering_Specification_CRI: ...
 
 
 @typing.overload
 def colour_rendering_index(
-    sd_test: SpectralDistribution, *, additional_data: Literal[False]
+    sd_test: SpectralDistribution,
+    *,
+    additional_data: Literal[False],
+    method: Literal["CIE 1995", "CIE 2024"] | str = ...,
 ) -> float: ...
 
 
 @typing.overload
 def colour_rendering_index(
-    sd_test: SpectralDistribution, additional_data: Literal[False]
+    sd_test: SpectralDistribution,
+    additional_data: Literal[False],
+    method: Literal["CIE 1995", "CIE 2024"] | str = ...,
 ) -> float: ...
 
 
 def colour_rendering_index(
-    sd_test: SpectralDistribution, additional_data: bool = False
+    sd_test: SpectralDistribution,
+    additional_data: bool = False,
+    method: Literal["CIE 1995", "CIE 2024"] | str = "CIE 1995",
 ) -> float | ColourRendering_Specification_CRI:
     """
     Return the *Colour Rendering Index* (CRI) :math:`Q_a` of given spectral
@@ -141,6 +164,8 @@ def colour_rendering_index(
         Test spectral distribution.
     additional_data
         Whether to output additional data.
+    method
+        Computation method.
 
     Returns
     -------
@@ -160,6 +185,8 @@ def colour_rendering_index(
     64.2337241...
     """
 
+    method = validate_method(method, tuple(COLOUR_RENDERING_INDEX_METHODS))
+
     cmfs = reshape_msds(
         MSDS_CMFS["CIE 1931 2 Degree Standard Observer"],
         SPECTRAL_SHAPE_DEFAULT,
@@ -168,7 +195,8 @@ def colour_rendering_index(
 
     shape = cmfs.shape
     sd_test = reshape_sd(sd_test, shape, copy=False)
-    tcs_sds = {sd.name: reshape_sd(sd, shape, copy=False) for sd in SDS_TCS.values()}
+    sds_tcs = SDS_TCS_SETS[method]
+    tcs_sds = {sd.name: reshape_sd(sd, shape, copy=False) for sd in sds_tcs.values()}
 
     with domain_range_scale("1"):
         XYZ = sd_to_XYZ(sd_test, cmfs)
@@ -250,6 +278,8 @@ def tcs_colorimetry_data(
 
     tcs_data = []
     for _key, value in sorted(INDEXES_TO_NAMES_TCS.items()):
+        if value not in sds_tcs:
+            continue
         sd_tcs = sds_tcs[value]
         XYZ_tcs = sd_to_XYZ(sd_tcs, cmfs, sd_t)
         xyY_tcs = XYZ_to_xyY(XYZ_tcs)

colour/quality/datasets/__init__.py

@@ -1,7 +1,8 @@
-from .tcs import SDS_TCS
+from .tcs import SDS_TCS, SDS_TCS_SETS
 from .vs import SDS_VS
 
 __all__ = [
     "SDS_TCS",
+    "SDS_TCS_SETS",
     "SDS_VS",
 ]

colour/quality/datasets/tcs.py

@@ -34,6 +34,9 @@
     "INDEXES_TO_NAMES_TCS",
     "APPROXIMATE_MUNSELL_NOTATIONS_TCS",
     "DATA_TCS",
+    "SDS_TCS_CIE_1995",
+    "SDS_TCS_CIE_2024",
+    "SDS_TCS_SETS",
     "SDS_TCS",
 ]
 
@@ -1521,9 +1524,68 @@
     },
 }
 
-SDS_TCS: CanonicalMapping = CanonicalMapping(
-    {key: SpectralDistribution(value, name=key) for key, value in DATA_TCS.items()}
+SDS_TCS_CIE_1995: CanonicalMapping = CanonicalMapping(
+    {
+        key: SpectralDistribution(value, name=key)
+        for key, value in {
+            x: DATA_TCS[x]
+            for x in [
+                "TCS01",
+                "TCS02",
+                "TCS03",
+                "TCS04",
+                "TCS05",
+                "TCS06",
+                "TCS07",
+                "TCS08",
+                "TCS09",
+                "TCS10",
+                "TCS11",
+                "TCS12",
+                "TCS13",
+                "TCS14",
+            ]
+        }.items()
+    }
 )
+
+SDS_TCS_CIE_2024: CanonicalMapping = CanonicalMapping(
+    {
+        key: SpectralDistribution(value, name=key)
+        for key, value in {
+            x: DATA_TCS[x]
+            for x in [
+                "TCS01",
+                "TCS02",
+                "TCS03",
+                "TCS04",
+                "TCS05",
+                "TCS06",
+                "TCS07",
+                "TCS08",
+                "TCS09",
+                "TCS10",
+                "TCS11",
+                "TCS12",
+                "TCS13",
+                "TCS14",
+                "TCS15",
+            ]
+        }.items()
+    }
+)
+
+SDS_TCS_SETS: CanonicalMapping = CanonicalMapping(
+    {
+        "CIE 1995": SDS_TCS_CIE_1995,
+        "CIE 2024": SDS_TCS_CIE_2024,
+    }
+)
+
+# TODO: deprecate SDS_TCS (was renamed to SDS_TCS_CIE_1995)
+SDS_TCS = SDS_TCS_CIE_1995
+
+
 """
 Test colour samples spectral distributions.
 

colour/quality/tests/test_cri.py

@@ -348,6 +348,35 @@ def test_colour_rendering_index(self) -> None:
             ),
         )
 
+        specification_t = colour_rendering_index(
+            SDS_ILLUMINANTS["FL1"], additional_data=True, method="CIE 2024"
+        )
+
+        np.testing.assert_allclose(
+            [data.Q_a for _index, data in sorted(specification_r.Q_as.items())],
+            [data.Q_a for _index, data in sorted(specification_t.Q_as.items())],
+            atol=TOLERANCE_ABSOLUTE_TESTS,
+        )
+
+        # Drop CIE 2024 results to get CIE 1995 results
+        specification_r.Q_as.pop(15)
+        specification_r.colorimetry_data[0] =
+            specification_r.colorimetry_data[0][:-1]
+        specification_r.colorimetry_data[1] =
+            specification_r.colorimetry_data[1][:-1]
+
+        # Test for CIE 1995
+        specification_t = colour_rendering_index(
+            SDS_ILLUMINANTS["FL1"], additional_data=True, method="CIE 1995"
+        )
+
+        np.testing.assert_allclose(
+            [data.Q_a for _index, data in sorted(specification_r.Q_as.items())],
+            [data.Q_a for _index, data in sorted(specification_t.Q_as.items())],
+            atol=TOLERANCE_ABSOLUTE_TESTS,
+        )
+
+        # If method not defined, then CIE 1995 is used
         specification_t = colour_rendering_index(
             SDS_ILLUMINANTS["FL1"], additional_data=True
         )

docs/colour.quality.rst

@@ -36,6 +36,7 @@ Colour Rendering Index
 .. autosummary::
     :toctree: generated/
 
+    COLOUR_RENDERING_INDEX_METHODS
     colour_rendering_index
 
 ``colour.quality``

docs/index.rst

@@ -1537,6 +1537,14 @@ Colour Rendering Index
 
     64.233724121664793
 
+.. code-block:: python
+
+    sorted(colour.COLOUR_RENDERING_INDEX_METHODS)
+
+.. code-block:: text
+
+    ['CIE 1995', 'CIE 2024']
+
 Academy Spectral Similarity Index (SSI)
 ***************************************