Source code for colour.quality.tm3018

"""
ANSI/IES TM-30-18 Colour Fidelity Index
=======================================

Define the *ANSI/IES TM-30-18 Colour Fidelity Index* (CFI) computation
objects.

- :class:`colour.quality.ColourQuality_Specification_ANSIIESTM3018`
- :func:`colour.quality.colour_fidelity_index_ANSIIESTM3018`

References
----------
-   :cite:`ANSI2018` : ANSI, & IES Color Committee. (2018). ANSI/IES TM-30-18 -
    IES Method for Evaluating Light Source Color Rendition.
    ISBN:978-0-87995-379-9
-   :cite:`VincentJ2017` : Vincent J. (2017). Is there any numpy group by
    function? Retrieved June 30, 2023, from https://stackoverflow.com/a/43094244
"""

from __future__ import annotations

import typing
from dataclasses import dataclass

if typing.TYPE_CHECKING:
    from colour.hints import ArrayLike, Literal, NDArrayFloat, NDArrayInt, Tuple

from colour.colorimetry import MultiSpectralDistributions, SpectralDistribution
from colour.quality import colour_fidelity_index_CIE2017
from colour.quality.cfi2017 import (
    DataColorimetry_TCS_CIE2017,
    delta_E_to_R_f,
)
from colour.utilities import (
    array_namespace,
    as_float_array,
    as_float_scalar,
    as_int_array,
    xp_as_float_array,
    xp_matrix_transpose,
    xp_nanmean,
    xp_reshape,
)


[docs] @dataclass class ColourQuality_Specification_ANSIIESTM3018: """ Define the *ANSI/IES TM-30-18 Colour Fidelity Index* (CFI) colour quality specification. Parameters ---------- name Name of the test spectral distribution. sd_test Spectral distribution of the tested illuminant. sd_reference Spectral distribution of the reference illuminant. R_f *Colour Fidelity Index* (CFI) :math:`R_f`. R_s Individual *colour fidelity indexes* data for each sample. CCT Correlated colour temperature :math:`T_{cp}`. D_uv Distance from the Planckian locus :math:`\\Delta_{uv}`. colorimetry_data Colorimetry data for the test and reference computations. R_g Gamut index :math:`R_g`. bins List of 16 lists, each containing the indexes of colour samples that lie in the respective hue bin. averages_test Averages of *CAM02-UCS* a', b' coordinates for each hue bin for test samples. averages_reference Averages for reference samples. average_norms Distance of averages for reference samples from the origin. R_fs Local colour fidelities for each hue bin. R_cs Local chromaticity shifts for each hue bin, in percents. R_hs Local hue shifts for each hue bin. """ name: str sd_test: SpectralDistribution sd_reference: SpectralDistribution R_f: float R_s: NDArrayFloat CCT: float D_uv: float colorimetry_data: Tuple[DataColorimetry_TCS_CIE2017, DataColorimetry_TCS_CIE2017] R_g: float bins: NDArrayInt averages_test: NDArrayFloat averages_reference: NDArrayFloat average_norms: NDArrayFloat R_fs: NDArrayFloat R_cs: NDArrayFloat R_hs: NDArrayFloat
@typing.overload def colour_fidelity_index_ANSIIESTM3018( sd_test: SpectralDistribution, additional_data: Literal[True] = True ) -> ColourQuality_Specification_ANSIIESTM3018: ... @typing.overload def colour_fidelity_index_ANSIIESTM3018( sd_test: SpectralDistribution, *, additional_data: Literal[False] ) -> float: ... @typing.overload def colour_fidelity_index_ANSIIESTM3018( sd_test: SpectralDistribution, additional_data: Literal[False] ) -> float: ... @typing.overload def colour_fidelity_index_ANSIIESTM3018( sd_test: MultiSpectralDistributions, additional_data: Literal[False] = False, ) -> NDArrayFloat: ...
[docs] def colour_fidelity_index_ANSIIESTM3018( sd_test: SpectralDistribution | MultiSpectralDistributions, additional_data: bool = False, ) -> float | NDArrayFloat | ColourQuality_Specification_ANSIIESTM3018: """ Compute the *ANSI/IES TM-30-18 Colour Fidelity Index* (CFI) :math:`R_f` for the specified test spectral distribution. Parameters ---------- sd_test Test spectral distribution. A :class:`colour.MultiSpectralDistributions` of ``N`` test illuminants is also accepted, in which case ``additional_data`` must be ``False`` and the return value is a :class:`numpy.ndarray` of ``N`` :math:`R_f` values. additional_data Whether to output additional data. Returns ------- :class:`float`, :class:`numpy.ndarray` or \ :class:`colour.quality.ColourQuality_Specification_ANSIIESTM3018` *ANSI/IES TM-30-18 Colour Fidelity Index* (CFI). References ---------- :cite:`ANSI2018`, :cite:`VincentJ2017` Examples -------- >>> from colour import SDS_ILLUMINANTS >>> sd = SDS_ILLUMINANTS["FL2"] >>> colour_fidelity_index_ANSIIESTM3018(sd) # doctest: +ELLIPSIS np.float64(70.1208244...) """ if not additional_data: return colour_fidelity_index_CIE2017(sd_test, False) if not isinstance(sd_test, SpectralDistribution): error = ( '"additional_data=True" is not supported when "sd_test" is a ' '"MultiSpectralDistributions" instance.' ) raise NotImplementedError(error) specification = colour_fidelity_index_CIE2017(sd_test, True) # Setup bins based on where the reference a'b' points are located. JMh = specification.colorimetry_data[1].JMh xp = array_namespace(JMh) bins = as_int_array(xp.floor(JMh[:, 2] / 22.5)) arange_16 = xp.arange(16) bin_mask = bins == xp_reshape(arange_16, (-1, 1), xp=xp) # "bin_mask" is used later with broadcasting and "nanmean" to skip a list # comprehension and keep all the mean calculation vectorised as per # :cite:`VincentJ2017`. bin_mask = xp.where(bin_mask == 0, float("nan"), 1.0) # Per-bin a'b' averages. test_apbp = specification.colorimetry_data[0].Jpapbp[:, 1:] ref_apbp = specification.colorimetry_data[1].Jpapbp[:, 1:] # Tile the "apbp" data in the third dimension and use broadcasting to place # each bin mask along the third dimension. By multiplying these matrices # together, the backend automatically expands the apbp data in the third # dimension and multiplies by the nan-filled bin mask. Finally, # "nanmean" can compute the bin mean apbp positions with the appropriate # axis argument. averages_test = xp_matrix_transpose( xp_nanmean( xp_reshape(xp_matrix_transpose(bin_mask, xp=xp), (99, 1, 16), xp=xp) * xp_reshape(test_apbp, (*ref_apbp.shape, 1), xp=xp), axis=0, xp=xp, ), xp=xp, ) averages_reference = xp_matrix_transpose( xp_nanmean( xp_reshape(xp_matrix_transpose(bin_mask, xp=xp), (99, 1, 16), xp=xp) * xp_reshape(ref_apbp, (*ref_apbp.shape, 1), xp=xp), axis=0, xp=xp, ), xp=xp, ) # Gamut Index. R_g = 100 * (averages_area(averages_test) / averages_area(averages_reference)) # Local colour fidelity indexes, i.e., 16 CFIs for each bin. bin_delta_E_s = xp_nanmean( xp_reshape(specification.delta_E_s, (1, -1), xp=xp) * bin_mask, axis=1, xp=xp ) R_fs = delta_E_to_R_f(bin_delta_E_s) # Angles bisecting the 16 hue bins of width ``360 / 16 = 22.5`` degrees, # offset by half a bin (*ANSI/IES TM-30-18*, Section 4.5). # ``xp.arange`` yields an integer array whose promotion would adopt the # backend default float dtype, e.g. float32 for stock *PyTorch*; the # samples are anchored to the *Colour* default float dtype instead. angles = ( (22.5 * xp_as_float_array(xp.arange(16), xp=xp, like=averages_test) + 11.25) / 180 * xp.pi ) cosines = xp.cos(angles) sines = xp.sin(angles) average_norms = xp.linalg.vector_norm(averages_reference, axis=1) a_deltas = averages_test[:, 0] - averages_reference[:, 0] b_deltas = averages_test[:, 1] - averages_reference[:, 1] # Local chromaticity shifts, multiplied by 100 to obtain percentages. R_cs = 100 * (a_deltas * cosines + b_deltas * sines) / average_norms # Local hue shifts. R_hs = (-a_deltas * sines + b_deltas * cosines) / average_norms return ColourQuality_Specification_ANSIIESTM3018( specification.name, sd_test, specification.sd_reference, specification.R_f, specification.R_s, specification.CCT, specification.D_uv, specification.colorimetry_data, R_g, bins, averages_test, averages_reference, average_norms, R_fs, R_cs, R_hs, )
def averages_area(averages: ArrayLike) -> float: """ Compute the area of the polygon formed by the hue bin averages. Parameters ---------- averages Hue bin averages. Returns ------- :class:`float` Area of the polygon. """ averages = as_float_array(averages) xp = array_namespace(averages) # Vectorized shoelace formula u = averages v = xp.roll(averages, -1, axis=0) triangle_areas = (u[:, 0] * v[:, 1] - u[:, 1] * v[:, 0]) / 2 return as_float_scalar(xp.sum(triangle_areas))