Summary

This PR adds domain-range scale annotations to most of our functions as a special form of lean metadata on parameters and return values:

def XYZ_to_CIECAM16(
    XYZ: Annotated[ArrayLike, 100],
    XYZ_w: Annotated[ArrayLike, 100],
    L_A: ArrayLike,
    Y_b: ArrayLike,
    surround: (
        InductionFactors_CIECAM02 | InductionFactors_CIECAM16
    ) = VIEWING_CONDITIONS_CIECAM16["Average"],
    discount_illuminant: bool = False,
    compute_H: bool = True,
) -> Annotated[CAM_Specification_CIECAM16, (100, 100, 360, 100, 100, 100, 400)]:


def XYZ_to_Lab(
    XYZ: Annotated[ArrayLike, 1],
    illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"][
        "D65"
    ],
) -> Annotated[NDArrayFloat, 100]:

They can then be retrieved with the new colour.get_domain_range_scale_metadata definition:

>>> from colour.hints import Annotated, ArrayLike, NDArrayFloat
>>> def example_function(
...     XYZ: Annotated[ArrayLike, 1],
...     illuminant: ArrayLike = None,
... ) -> Annotated[NDArrayFloat, 100]:
...     pass
>>> metadata = get_domain_range_scale_metadata(example_function)
>>> metadata["domain"]
{'XYZ': 1}
>>> metadata["range"]
100

The most common cases have dedicated type aliases:

• Domain1 : 1,
• Domain10 : 10,
• Domain100 : 100,
• Domain360 : 360,
• Domain100_100_360 : (100, 100, 360),
• Range1 : 1,
• Range10 : 10,
• Range100 : 100,
• Range360 : 360,
• Range100_100_360 : (100, 100, 360),

Thus XYZ_to_Lab is effectively

def XYZ_to_Lab(
    XYZ: Domain1,
    illuminant: ArrayLike = CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"][
        "D65"
    ],
) -> Range100:

The conversion graph is now able to input and output at the reference scale using the new from_reference and to_reference parameters.

I took that opportunity to simplify the docstring tables and cross-check them.

Preflight

Code Style and Quality

• Unit tests have been implemented and passed.
• Pyright static checking has been run and passed.
• Pre-commit hooks have been run and passed.
• New transformations have been added to the Automatic Colour Conversion Graph.
• New transformations have been exported to the relevant namespaces, e.g. colour, colour.models.

Documentation

• New features are documented along with examples if relevant.
• The documentation is Sphinx and numpydoc compliant.