PR: Add TLCI-2012 and TLMF-2013 quality metrics

[cmuellner]

Summary

Add EBU Tech 3355 TLCI-2012 and TLMF-2013 quality metrics.

This implements:

• Television Lighting Consistency Index, TLCI-2012.
• Television Luminaire Matching Factor, TLMF-2013.
• EBU Tech 3355 camera, display, saturation, and reference-selection data.
• EBU Tech 3355 Appendix 2 Planckian and daylight chromaticity tables used
  for TLCI CCT selection.
• EBU Tech 3355 Appendix 3 daylight radiation vector data used for TLCI
  daylight references.
• EBU Tech 3355 Appendix 4 test colour sample data used by TLCI/TLMF,
  including the documented BBC R&D Report 1988/2 and unpublished BBC R&D
  provenance.
• Public colour and colour.quality API exports.
• Documentation, examples, and bibliography entries.

Fixes #974.

Implementation Notes

TLCI/TLMF was not a straightforward transcription from the public
specification. A few parts of EBU Tech 3355 require careful interpretation:

• The CCT selection is defined by Tech 3355, not by Colour's existing
  CCT/D_uv methods such as Ohno (2013) or Robertson (1968). Tech 3355 uses
  the Appendix 2 Planckian and daylight chromaticity tables, scans adjacent
  locus points, and computes the normal intersection using the section 1.1.1
  slope/angle procedure.
• The Planckian and daylight CCT loci are the Appendix 2 lookup tables, not
  regenerated blackbody or CIE daylight loci. The Planckian and daylight loci
  also remain separate through the 3400-5000 K mixed-reference region.
• The Planckian reference spectrum is Tech 3355-specific. Section 1.1.2.1
  equation [9] uses a simplified Planckian expression with wavelength in
  nanometres, a 1.435e7 nm K radiation constant, and normalisation at
  560 nm; this is not delegated to Colour's generic blackbody helper.
• The daylight reference spectrum is also Tech 3355-specific. Section 1.1.2.2
  uses Appendix 3 daylight radiation vectors and Tech 3355 coefficients for
  M, M1, and M2; this differs from Colour's general
  sd_CIE_illuminant_D_series helper, which uses the library CIE D-series
  basis data and its standard coefficient/rounding path.
• The 3400-5000 K mixed-reference spectrum is interpolated from fixed
  Planckian 3400 K and daylight 5000 K endpoint spectra, after normalising
  each endpoint at 560 nm. It is not generated from Planckian/daylight spectra
  at the test source CCT.
• The Appendix 4 test-colour samples are the mandatory TLCI/TLMF data, but
  they are not simply a direct copy of the published BBC R&D Report 1988/2
  ColorChecker table. Some coloured samples differ slightly from the published
  BBC table, and the greyscale samples are attributed by Tech 3355 to
  unpublished BBC R&D data. The dataset is therefore documented as Tech 3355
  data, with BBC R&D Report 1988/2 as partial provenance.
• The Tech 3355 d_uv calculation differs from Colour's existing
  CCT/D_uv methods such as Ohno (2013) and Robertson (1968): it uses the
  Tech 3355 reference loci, normalises the distance by 0.0054, and reports
  positive values on the magenta side and negative values on the green side.
  This follows the section 1.1.1 prose that reverses the sign for green-side
  offsets, where u_T < u_L, and the section 1.1.2.3 equations [16]-[17]
  labels (d > 0 towards magenta, d <= 0 towards green). The EBU reference
  binary appears to report this secondary d_uv value with the opposite sign,
  but the implementation follows the published specification. The reported
  d_uv also includes the Tech 3355 mixed-region adjustment between 4000 K
  and 5000 K, where the Planckian and daylight loci are not joined.
• TLMF shares the TLCI camera/display pipeline but uses the reference luminaire
  balance with a test-luminaire exposure correction, matching the TLMF
  procedure instead of independently white-balancing both sources as TLCI does.
  The exposure correction uses the reference/test neutral luma ratio after the
  camera matrix.
• TLCI-2012 aggregates colour differences over only the first 18 coloured
  ColorChecker samples, while TLMF-2013 uses all 24 samples, including the
  greyscale patches.
• The camera BT.709 signal path preserves the studio-swing headroom described
  by Tech 3355 section 2, equation [61], capping at code value 255 relative
  to the nominal 16-235 range instead of clipping at nominal white.
• The Tech 3355 colour-difference calculation follows the section 1.5
  CIEDE2000 path with unity k factors, using Colour's existing CIE 2000
  implementation for the standard colour-difference calculation.

Validation

EBU Tech 3355 does not distribute official reference test vectors. The tests
therefore use reproducible generated spectral distributions covering the main
specified algorithm paths:

• Planckian sources.
• Tech 3355 daylight-reference sources.
• Mixed-reference spectra in the 3400-5000 K transition.
• Reference-locus distance sign checks for green/magenta chromaticity
  offsets.
• Phosphor-like LED spectra.
• RGB LED spectra.
• Public in-tree CIE/NIST LED spectral distributions as regression/stress
  coverage.
• TLMF identical, close-match, mismatch, and mixed-reference pairs.

Additional local validation sets, including a 1000-case TLCI and 1000-pair
TLMF diagnostic set, were used to stress the CCT branches, mixed-reference
transition, green/magenta d_uv sign, LED spectra, fixture-like spectra, and
low-score TLMF cases. The committed tests use only deterministic,
redistributable spectra and public in-tree spectral data; they do not depend
on local measurement files.

Because no official reference vectors are published, this PR cannot claim
independent conformance from official test data. The validation strategy is
instead:

• implement each calculation step from the published specification;
• reuse existing Colour mathematics for spectral integration, colour
  transfer functions, and colourspace conversions;
• keep TLCI-specific code only where Tech 3355 defines a calculation that is
  not covered by an existing Colour routine;
• commit a smaller redistributable validation set that exercises the same
  algorithm branches.

Tests

• Relevant pre-commit hook tools run directly: isort, ruff format,
  ruff check, codespell, blacken-docs, check-added-large-files,
  check-case-conflict, check-merge-conflict, check-symlinks,
  check-yaml, debug-statement-hook, end-of-file-fixer,
  mixed-line-ending, name-tests-test, and trailing-whitespace-fixer.
• prettier and the RST pygrep hooks were run through prek; no
  requirements.txt files are touched by the commit.
• uv run ruff check colour/quality/tlci.py colour/quality/datasets/tlci2012.py colour/quality/datasets/__init__.py colour/quality/tests/test_tlci.py
• uv run pyright --threads --skipunannotated colour/quality/tlci.py colour/quality/datasets/tlci2012.py colour/quality/tests/test_tlci.py
• uv run python -m doctest colour/quality/tlci.py
• uv run pytest --doctest-modules colour/quality/tlci.py
• uv run pytest colour/quality/tests/test__init__.py colour/quality/tests/test_tlci.py

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.
• [n/a] New transformations have been added to the Automatic Colour Conversion Graph.
• [n/a] 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.

[cmuellner]

CI is currently failing for two reasons.

The GitHub Actions failure appears unrelated to this PR. The failing job is windows-latest - Python 3.12, and the failures are all urllib.error.HTTPError: HTTP Error 429: Too Many Requests in existing network-dependent tests while downloading Munsell ONNX assets / test resources via download_url(). The new TLCI/TLMF tests are not among the failures, and the other OS/Python jobs passed, so this looks like external rate limiting rather than a behavioral regression.

Codacy reports 65 new issues, mostly in the new TLCI/TLMF files:

• 24x Bandit_B101 for pytest assert usage in colour/quality/tests/test_tlci.py.
• 41x Prospector/pydocstyle findings, mostly docstring spacing/formatting rules
  such as D202, D200, D203, D205, D212, D413, and D415.
• Codacy also reports one new duplication item in
  colour/quality/datasets/tlci2012.py, which appears to be related to reference
  dataset content.

My read is that many of these findings conflict with the existing project style: the test suite widely uses pytest assert, Ruff ignores S101 for test_* files, and several of the pydocstyle rules reported by Codacy are explicitly ignored by
the local Ruff configuration or conflict with existing module/class docstring patterns. That said, if maintainers prefer satisfying Codacy on this PR, I can adjust the new files accordingly or add targeted suppressions/configuration. I’m
fine with either direction; the main tradeoff is consistency with existing style versus making Codacy green without changing Codacy configuration.

[KelSolaar]

Hi @cmuellner,

Thanks a lot! Great work. #1406 is pending and is incompatible with it at the moment so, the best way would be for me to merge it and rebase #1406 on top of it and bring it up to Array API standard compatibility.

Don't worry about Codacy and the ONNX download CI issue.

[cmuellner]

Thanks! If you would prefer the opposite sequencing for any reason (Python Array API lands first), I’m also happy to adjust this PR accordingly.

[KelSolaar]

The issue is that we might change some of our Array API Standard implementation. I will keep you posted!