@photivra/engine 1.5.0 → 2.1.0

package/dist/color/gamut-mapping.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Perceptual gamut mapping into a bounded linear RGB cube [0, 1]³ by hue- and
+ * lightness-preserving chroma reduction toward the neutral axis in CIE LCh(ab).
+ *
+ * Method, for each colour:
+ * 1. Keep L* and h_ab fixed.
+ * 2. Find the chroma at the gamut boundary, C_max(L*, h), by bisection.
+ * 3. Compress chroma above a knee k·C_max smoothly:
+ *    C′ = kC_max + (1 − k)C_max·tanh((C − kC_max)/((1 − k)C_max)).
+ *    This is continuous and monotone and never reaches C_max. k = 1 means hard clipping to the
+ *    boundary at constant (L*, h) ("chroma clipping").
+ *
+ * Sources: the binary-search chroma reduction in W3C CSS Color Module Level 4 §14, which uses OKLCh;
+ * also the constant-lightness, constant-hue chroma reduction methods surveyed by Morovič (2008),
+ * Color Gamut Mapping (Wiley), §10. This independent implementation uses CIELAB, to avoid extra
+ * third-party matrices.
+ *
+ * Limits: CIELAB hue is not perceptually constant for saturated blues, so blues can shift toward
+ * purple. Lightness outside [0, 100] is clipped to black or white. The result only approximates
+ * perceptual preservation.
+ *
+ * Input XYZ must be relative to the target space's D65 white, with white Y = 1.
+ * @see docs/COLORIMETRY.md for equations, coordinate/unit conventions and limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type CieXyzTristimulus, type ColorVector3 } from "./colorimetry-math.js";
+import { type RgbColorSpaceId } from "./rgb-color-spaces.js";
+export type GamutMappingMethod = "cielab-hue-preserving-chroma-compression";
+export interface PrepareRgbGamutMappingInput {
+    colorSpace: RgbColorSpaceId;
+    method: GamutMappingMethod;
+    /** Fraction of the boundary chroma left untouched, in [0, 1]. 1 means clip to the boundary. */
+    kneeFraction: number;
+}
+export interface GamutMappedColor {
+    /** Linear RGB in the target space, each component in [0, 1]. */
+    linearRgb: ColorVector3;
+    /** True when lightness or chroma was changed. */
+    adjusted: boolean;
+    /** Lightness was outside [0, 100] and was clipped to black or white. */
+    lightnessClipped: boolean;
+}
+export interface PreparedRgbGamutMapping {
+    colorSpace: RgbColorSpaceId;
+    kneeFraction: number;
+    /** Maps one XYZ colour (D65-relative, white Y = 1). */
+    map(xyz: ColorVector3): GamutMappedColor;
+}
+/** Validates the target space once and returns a reusable per-colour mapper. */
+export declare function prepareRgbGamutMapping(input: PrepareRgbGamutMappingInput): PreparedRgbGamutMapping;
+/** Maps one D65-relative XYZ colour into a target RGB gamut (see module notes). */
+export declare function calculateGamutMappedColor(input: PrepareRgbGamutMappingInput & {
+    xyz: CieXyzTristimulus;
+}): CalculationResult<GamutMappedColor>;

package/dist/color/gamut-mapping.js

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Perceptual gamut mapping into a bounded linear RGB cube [0, 1]³ by hue- and
+ * lightness-preserving chroma reduction toward the neutral axis in CIE LCh(ab).
+ *
+ * Method, for each colour:
+ * 1. Keep L* and h_ab fixed.
+ * 2. Find the chroma at the gamut boundary, C_max(L*, h), by bisection.
+ * 3. Compress chroma above a knee k·C_max smoothly:
+ *    C′ = kC_max + (1 − k)C_max·tanh((C − kC_max)/((1 − k)C_max)).
+ *    This is continuous and monotone and never reaches C_max. k = 1 means hard clipping to the
+ *    boundary at constant (L*, h) ("chroma clipping").
+ *
+ * Sources: the binary-search chroma reduction in W3C CSS Color Module Level 4 §14, which uses OKLCh;
+ * also the constant-lightness, constant-hue chroma reduction methods surveyed by Morovič (2008),
+ * Color Gamut Mapping (Wiley), §10. This independent implementation uses CIELAB, to avoid extra
+ * third-party matrices.
+ *
+ * Limits: CIELAB hue is not perceptually constant for saturated blues, so blues can shift toward
+ * purple. Lightness outside [0, 100] is clipped to black or white. The result only approximates
+ * perceptual preservation.
+ *
+ * Input XYZ must be relative to the target space's D65 white, with white Y = 1.
+ * @see docs/COLORIMETRY.md for equations, coordinate/unit conventions and limits.
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { COLORIMETRY_MODEL_VERSION } from "./color-matching-functions.js";
+import { cielabOfXyz, xyzOfCielab } from "./color-difference.js";
+import { multiplyMatrixVector, parseXyz, requireNonNegativeNumber, vectorToXyz, xyzToVector } from "./colorimetry-math.js";
+import { resolveRgbColorSpace } from "./rgb-color-spaces.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+const IN_GAMUT_TOLERANCE = 1e-12;
+const BISECTION_STEPS = 60;
+function inCube(rgb) {
+    return rgb.every((v) => v >= -IN_GAMUT_TOLERANCE && v <= 1 + IN_GAMUT_TOLERANCE);
+}
+function clampCube(rgb) {
+    return rgb.map((v) => Math.min(1, Math.max(0, v)));
+}
+/** Validates the target space once and returns a reusable per-colour mapper. */
+export function prepareRgbGamutMapping(input) {
+    requireInputKeys(input, "prepareRgbGamutMapping", ["colorSpace", "method", "kneeFraction"]);
+    if (input.method !== "cielab-hue-preserving-chroma-compression")
+        throw new InvalidConfigurationError("method is not supported.");
+    const k = requireNonNegativeNumber(input.kneeFraction, "kneeFraction");
+    if (k > 1)
+        throw new InvalidScientificInputError("kneeFraction must lie in [0, 1].");
+    const space = resolveRgbColorSpace(input.colorSpace).value;
+    const white = space.whiteXyz;
+    const toRgb = (lStar, a, b) => multiplyMatrixVector(space.xyzToRgb, xyzToVector(xyzOfCielab({ lStar, aStar: a, bStar: b }, white)));
+    return Object.freeze({
+        colorSpace: space.id,
+        kneeFraction: k,
+        map(xyzInput) {
+            const xyz = parseXyz(vectorToXyz(xyzInput), "xyz");
+            const rgb = multiplyMatrixVector(space.xyzToRgb, xyzInput);
+            const lab = cielabOfXyz(xyz, white);
+            if (!(lab.lStar > 0))
+                return { linearRgb: [0, 0, 0], adjusted: !rgb.every((v) => v === 0), lightnessClipped: true };
+            if (lab.lStar >= 100) {
+                return { linearRgb: [1, 1, 1], adjusted: !rgb.every((v) => Math.abs(v - 1) <= IN_GAMUT_TOLERANCE), lightnessClipped: lab.lStar > 100 };
+            }
+            const chroma = Math.hypot(lab.aStar, lab.bStar);
+            const inside = inCube(rgb);
+            if (chroma === 0 || (inside && k === 1))
+                return { linearRgb: clampCube(rgb), adjusted: false, lightnessClipped: false };
+            const ua = lab.aStar / chroma, ub = lab.bStar / chroma;
+            // Find the boundary chroma at constant L* and h by bisection. The neutral point is inside the cube.
+            let lo = 0, hi = chroma;
+            if (inside) {
+                hi = Math.max(chroma, 1);
+                while (inCube(toRgb(lab.lStar, ua * hi, ub * hi)) && hi < 1e4)
+                    hi *= 2;
+            }
+            for (let i = 0; i < BISECTION_STEPS; i++) {
+                const mid = (lo + hi) / 2;
+                if (inCube(toRgb(lab.lStar, ua * mid, ub * mid)))
+                    lo = mid;
+                else
+                    hi = mid;
+            }
+            const cMax = lo;
+            const knee = k * cMax;
+            let mapped = chroma;
+            if (chroma > knee) {
+                mapped = k === 1 || cMax === 0 ? cMax : knee + (1 - k) * cMax * Math.tanh((chroma - knee) / ((1 - k) * cMax));
+                mapped = Math.min(mapped, cMax);
+            }
+            if (mapped === chroma && inside)
+                return { linearRgb: clampCube(rgb), adjusted: false, lightnessClipped: false };
+            return { linearRgb: clampCube(toRgb(lab.lStar, ua * mapped, ub * mapped)), adjusted: true, lightnessClipped: false };
+        }
+    });
+}
+/** Maps one D65-relative XYZ colour into a target RGB gamut (see module notes). */
+export function calculateGamutMappedColor(input) {
+    requireInputKeys(input, "calculateGamutMappedColor", ["colorSpace", "method", "kneeFraction", "xyz"]);
+    const xyz = parseXyz(input.xyz, "xyz");
+    const value = prepareRgbGamutMapping({ colorSpace: input.colorSpace, method: input.method, kneeFraction: input.kneeFraction }).map(xyzToVector(xyz));
+    return approximationResult(value, "gamut-mapping-cielab-chroma-compression", COLORIMETRY_MODEL_VERSION, [
+        "Constant CIELAB L* and hue; chroma reduced toward the neutral axis with a tanh knee",
+        "CIELAB hue is not perceptually constant for saturated blues; lightness outside [0, 100] is clipped"
+    ]);
+}
+//# sourceMappingURL=gamut-mapping.js.map

package/dist/color/gamut-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gamut-mapping.js","sourceRoot":"","sources":["../../src/color/gamut-mapping.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Perceptual gamut mapping into a bounded linear RGB cube [0, 1]³ by hue- and\n * lightness-preserving chroma reduction toward the neutral axis in CIE LCh(ab).\n *\n * Method, for each colour:\n * 1. Keep L* and h_ab fixed.\n * 2. Find the chroma at the gamut boundary, C_max(L*, h), by bisection.\n * 3. Compress chroma above a knee k·C_max smoothly:\n *    C′ = kC_max + (1 − k)C_max·tanh((C − kC_max)/((1 − k)C_max)).\n *    This is continuous and monotone and never reaches C_max. k = 1 means hard clipping to the\n *    boundary at constant (L*, h) (\"chroma clipping\").\n *\n * Sources: the binary-search chroma reduction in W3C CSS Color Module Level 4 §14, which uses OKLCh;\n * also the constant-lightness, constant-hue chroma reduction methods surveyed by Morovič (2008),\n * Color Gamut Mapping (Wiley), §10. This independent implementation uses CIELAB, to avoid extra\n * third-party matrices.\n *\n * Limits: CIELAB hue is not perceptually constant for saturated blues, so blues can shift toward\n * purple. Lightness outside [0, 100] is clipped to black or white. The result only approximates\n * perceptual preservation.\n *\n * Input XYZ must be relative to the target space's D65 white, with white Y = 1.\n * @see docs/COLORIMETRY.md for equations, coordinate/unit conventions and limits.\n */\n\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { COLORIMETRY_MODEL_VERSION } from \"./color-matching-functions.js\";\nimport { cielabOfXyz, xyzOfCielab } from \"./color-difference.js\";\nimport {\n  multiplyMatrixVector,\n  parseXyz,\n  requireNonNegativeNumber,\n  vectorToXyz,\n  xyzToVector,\n  type CieXyzTristimulus,\n  type ColorVector3\n} from \"./colorimetry-math.js\";\nimport { resolveRgbColorSpace, type RgbColorSpaceId } from \"./rgb-color-spaces.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport type GamutMappingMethod = \"cielab-hue-preserving-chroma-compression\";\n\nexport interface PrepareRgbGamutMappingInput {\n  colorSpace: RgbColorSpaceId;\n  method: GamutMappingMethod;\n  /** Fraction of the boundary chroma left untouched, in [0, 1]. 1 means clip to the boundary. */\n  kneeFraction: number;\n}\n\nexport interface GamutMappedColor {\n  /** Linear RGB in the target space, each component in [0, 1]. */\n  linearRgb: ColorVector3;\n  /** True when lightness or chroma was changed. */\n  adjusted: boolean;\n  /** Lightness was outside [0, 100] and was clipped to black or white. */\n  lightnessClipped: boolean;\n}\n\nexport interface PreparedRgbGamutMapping {\n  colorSpace: RgbColorSpaceId;\n  kneeFraction: number;\n  /** Maps one XYZ colour (D65-relative, white Y = 1). */\n  map(xyz: ColorVector3): GamutMappedColor;\n}\n\nconst IN_GAMUT_TOLERANCE = 1e-12;\nconst BISECTION_STEPS = 60;\n\nfunction inCube(rgb: ColorVector3): boolean {\n  return rgb.every((v) => v >= -IN_GAMUT_TOLERANCE && v <= 1 + IN_GAMUT_TOLERANCE);\n}\n\nfunction clampCube(rgb: ColorVector3): ColorVector3 {\n  return rgb.map((v) => Math.min(1, Math.max(0, v))) as unknown as ColorVector3;\n}\n\n/** Validates the target space once and returns a reusable per-colour mapper. */\nexport function prepareRgbGamutMapping(input: PrepareRgbGamutMappingInput): PreparedRgbGamutMapping {\n  requireInputKeys(input, \"prepareRgbGamutMapping\", [\"colorSpace\", \"method\", \"kneeFraction\"]);\n  if (input.method !== \"cielab-hue-preserving-chroma-compression\") throw new InvalidConfigurationError(\"method is not supported.\");\n  const k = requireNonNegativeNumber(input.kneeFraction, \"kneeFraction\");\n  if (k > 1) throw new InvalidScientificInputError(\"kneeFraction must lie in [0, 1].\");\n  const space = resolveRgbColorSpace(input.colorSpace).value;\n  const white = space.whiteXyz;\n  const toRgb = (lStar: number, a: number, b: number): ColorVector3 =>\n    multiplyMatrixVector(space.xyzToRgb, xyzToVector(xyzOfCielab({ lStar, aStar: a, bStar: b }, white)));\n  return Object.freeze({\n    colorSpace: space.id,\n    kneeFraction: k,\n    map(xyzInput: ColorVector3): GamutMappedColor {\n      const xyz: CieXyzTristimulus = parseXyz(vectorToXyz(xyzInput), \"xyz\");\n      const rgb = multiplyMatrixVector(space.xyzToRgb, xyzInput);\n      const lab = cielabOfXyz(xyz, white);\n      if (!(lab.lStar > 0)) return { linearRgb: [0, 0, 0], adjusted: !rgb.every((v) => v === 0), lightnessClipped: true };\n      if (lab.lStar >= 100) {\n        return { linearRgb: [1, 1, 1], adjusted: !rgb.every((v) => Math.abs(v - 1) <= IN_GAMUT_TOLERANCE), lightnessClipped: lab.lStar > 100 };\n      }\n      const chroma = Math.hypot(lab.aStar, lab.bStar);\n      const inside = inCube(rgb);\n      if (chroma === 0 || (inside && k === 1)) return { linearRgb: clampCube(rgb), adjusted: false, lightnessClipped: false };\n      const ua = lab.aStar / chroma, ub = lab.bStar / chroma;\n      // Find the boundary chroma at constant L* and h by bisection. The neutral point is inside the cube.\n      let lo = 0, hi = chroma;\n      if (inside) {\n        hi = Math.max(chroma, 1);\n        while (inCube(toRgb(lab.lStar, ua * hi, ub * hi)) && hi < 1e4) hi *= 2;\n      }\n      for (let i = 0; i < BISECTION_STEPS; i++) {\n        const mid = (lo + hi) / 2;\n        if (inCube(toRgb(lab.lStar, ua * mid, ub * mid))) lo = mid; else hi = mid;\n      }\n      const cMax = lo;\n      const knee = k * cMax;\n      let mapped = chroma;\n      if (chroma > knee) {\n        mapped = k === 1 || cMax === 0 ? cMax : knee + (1 - k) * cMax * Math.tanh((chroma - knee) / ((1 - k) * cMax));\n        mapped = Math.min(mapped, cMax);\n      }\n      if (mapped === chroma && inside) return { linearRgb: clampCube(rgb), adjusted: false, lightnessClipped: false };\n      return { linearRgb: clampCube(toRgb(lab.lStar, ua * mapped, ub * mapped)), adjusted: true, lightnessClipped: false };\n    }\n  });\n}\n\n/** Maps one D65-relative XYZ colour into a target RGB gamut (see module notes). */\nexport function calculateGamutMappedColor(input: PrepareRgbGamutMappingInput & { xyz: CieXyzTristimulus }): CalculationResult<GamutMappedColor> {\n  requireInputKeys(input, \"calculateGamutMappedColor\", [\"colorSpace\", \"method\", \"kneeFraction\", \"xyz\"]);\n  const xyz = parseXyz(input.xyz, \"xyz\");\n  const value = prepareRgbGamutMapping({ colorSpace: input.colorSpace, method: input.method, kneeFraction: input.kneeFraction }).map(xyzToVector(xyz));\n  return approximationResult(value, \"gamut-mapping-cielab-chroma-compression\", COLORIMETRY_MODEL_VERSION, [\n    \"Constant CIELAB L* and hue; chroma reduced toward the neutral axis with a tanh knee\",\n    \"CIELAB hue is not perceptually constant for saturated blues; lightness outside [0, 100] is clipped\"\n  ]);\n}\n"]}

package/dist/color/illuminants.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Illuminant spectra and correlated-colour-temperature (CCT) helpers.
+ *
+ * - Planckian radiator: exact Planck law (BIPM Mise en pratique for the kelvin, Absolute Primary
+ *   Radiometry 2018, Eq. 1, free) with the exact SI defining constants (h, c, k; BIPM SI Brochure
+ *   9th ed. 2019), so c₂ = hc/k = 1.438776877…e-2 m·K (NIST CODATA 2022). Wavelength is the vacuum
+ *   wavelength.
+ * - CIE standard illuminant A: Planck's law relative to 560 nm with the CIE's defining constants
+ *   c₂ = 1.435e-2 m·K and T = 2848 K (also CIE 15:2018 Eq. 4.1 / ISO/CIE 11664-2, paid):
+ *   S_A(λ) = 100 (560/λ)^5 (exp(1.435e7/(2848·560)) − 1)/(exp(1.435e7/(2848 λ)) − 1)
+ *   (≈ 2856 K with the exact c₂). Computed from the formula, not a copied table; it reproduces the
+ *   free CIE 1 nm table (DOI 10.25039/CIE.DS.8jsxjrsn) to its six significant digits.
+ * - CIE daylight: the CIE daylight-locus chromaticity polynomial and the M₁/M₂ weights (CIE 15:2018,
+ *   paid; no free text of the formulas found). With three-decimal rounding they reproduce the free
+ *   CIE D55 and D65 tables. The S₀/S₁/S₂ basis is a CIE dataset (CC BY-SA 4.0, not bundled);
+ *   callers supply it.
+ * - Planckian locus: the chromaticity of a Planckian radiator at T, computed by integrating Planck's
+ *   law against colour-matching functions. The default uses the engine's analytic CIE 1931 fit with
+ *   1 nm nodes from 360 to 830 nm (so it inherits that fit's approximation); callers may select
+ *   tabulated CMFs and their own nodes. Valid 1000–100000 K.
+ * - CCT from chromaticity: McCamy (1992) cubic (approximation), or a nearest-point
+ *   search on the Planckian locus in the CIE 1960 UCS (CCT and signed Duv as defined in Smet et al.,
+ *   LEUKOS 2023, free archival copy from the US DOE; also CIE 15:2018). Duv sign: positive above the
+ *   locus (toward green), negative below (toward magenta), following Ohno, "Calculation of CCT and Duv
+ *   and Practical Conversion Formulae", CORM 2011 slides (free), slide 5; the engine documents and
+ *   tests it.
+ * @see docs/COLORIMETRY.md for equations, coordinate/unit conventions and limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import type { SpectralWavelengthRangeNanometers } from "../core/spectral.js";
+import { type ColorMatchingFunctionsSource, type ColorimetricQuadratureNode, type ColorimetricSpectralSample, type ColorimetricSpectrum } from "./color-matching-functions.js";
+import { type CieXyChromaticity } from "./colorimetry-math.js";
+/** Exact SI defining constants (BIPM SI Brochure, 9th edition, 2019). */
+export declare const PLANCK_CONSTANT_JOULE_SECONDS = 6.62607015e-34;
+export declare const SPEED_OF_LIGHT_METERS_PER_SECOND = 299792458;
+export declare const BOLTZMANN_CONSTANT_JOULES_PER_KELVIN = 1.380649e-23;
+/** Second radiation constant c₂ = hc/k in m·K (derived from the exact constants). */
+export declare const SECOND_RADIATION_CONSTANT_METER_KELVIN: number;
+/** Temperature range of the Planckian-locus models, K. */
+export declare const PLANCKIAN_LOCUS_RANGE_KELVIN: Readonly<{
+    minimum: 1000;
+    maximum: 100000;
+}>;
+/** CIE daylight-locus validity, K. */
+export declare const CIE_DAYLIGHT_LOCUS_RANGE_KELVIN: Readonly<{
+    minimum: 4000;
+    maximum: 25000;
+}>;
+/**
+ * Engine limit: no CCT beyond |Duv| = 0.05, the range over which Smet et al. (2023, free) evaluate CCT
+ * methods for nominally white light (CIE 15:2018 §9.5, paid, gives the same limit).
+ */
+export declare const MAX_CORRELATED_COLOR_TEMPERATURE_DUV = 0.05;
+/**
+ * Planck's law for blackbody spectral radiance per unit (vacuum) wavelength:
+ * L(λ, T) = 2hc² / λ⁵ / (exp(hc/(λkT)) − 1). Returns W·m⁻²·sr⁻¹·nm⁻¹.
+ */
+export declare function calculatePlanckianSpectralRadiance(input: {
+    temperatureKelvin: number;
+    wavelengthNanometers: number;
+}): number;
+/** Planckian spectral radiance (W·m⁻²·sr⁻¹·nm⁻¹) as a function spectrum over the given range. */
+export declare function createPlanckianSpectrum(input: {
+    temperatureKelvin: number;
+    wavelengthRangeNanometers: SpectralWavelengthRangeNanometers;
+}): ColorimetricSpectrum;
+/** CIE illuminant A defining range (nm). */
+export declare const CIE_ILLUMINANT_A_RANGE_NANOMETERS: Readonly<{
+    minimum: 300;
+    maximum: 830;
+}>;
+/**
+ * CIE standard illuminant A relative SPD from its defining formula (100 at 560 nm),
+ * with c₂ = 1.435e-2 m·K and T = 2848 K as in the standard (≈ 2856 K with the
+ * current c₂). Valid 300–830 nm.
+ */
+export declare function calculateCieIlluminantARelativeSpectralPower(wavelengthNanometers: number): number;
+/** CIE illuminant A as a function spectrum over its defining range. */
+export declare function createCieIlluminantASpectrum(): ColorimetricSpectrum;
+export interface CieDaylightComponentWeights {
+    correlatedColorTemperatureKelvin: number;
+    chromaticity: CieXyChromaticity;
+    m1: number;
+    m2: number;
+    coefficientRounding: "none" | "cie-three-decimals";
+}
+/**
+ * CIE daylight-locus chromaticity and S₁/S₂ weights for a CCT in 4000–25000 K
+ * (CIE 15:2018 §4.1.2, paid; no free text of the formulas found). M₁, M₂ rounded to three decimals
+ * reproduce the free CIE D55 and D65 tables (DOI 10.25039/CIE.DS.qewfb3kp, 10.25039/CIE.DS.hjfjmt59)
+ * to their rounding; `coefficientRounding` makes that rounding explicit.
+ * The temperature is used as given: D65's nominal 6500 K corresponds to 6504 K here.
+ */
+export declare function calculateCieDaylightComponentWeights(input: {
+    correlatedColorTemperatureKelvin: number;
+    coefficientRounding: "none" | "cie-three-decimals";
+}): CalculationResult<CieDaylightComponentWeights>;
+/** Caller-supplied CIE daylight basis S₀, S₁, S₂ (tabulated; CIE dataset not bundled). */
+export interface CieDaylightBasis {
+    s0: readonly ColorimetricSpectralSample[];
+    s1: readonly ColorimetricSpectralSample[];
+    s2: readonly ColorimetricSpectralSample[];
+    /** Caller identity of the basis dataset (for example a DOI). */
+    datasetId: string;
+}
+/**
+ * Builds a CIE D-series relative SPD S(λ) = S₀ + M₁S₁ + M₂S₂ on the S₀ wavelengths from
+ * caller-supplied basis tables (S₁, S₂ linearly interpolated; fail closed outside range).
+ */
+export declare function createCieDaylightSpectrum(input: {
+    correlatedColorTemperatureKelvin: number;
+    coefficientRounding: "none" | "cie-three-decimals";
+    basis: CieDaylightBasis;
+}): ColorimetricSpectrum;
+/** Selects how the Planckian locus is evaluated. */
+export type PlanckianLocusModel = {
+    /** Planck's law integrated against the engine's analytic CIE 1931 CMFs, 1 nm nodes 360–830 nm (the default). */
+    kind: "planck-analytic-cmf";
+} | {
+    kind: "planck-integration";
+    colorMatchingFunctions: ColorMatchingFunctionsSource;
+    quadratureNodes: readonly ColorimetricQuadratureNode[];
+};
+/**
+ * Planckian-locus chromaticity at T (1000–100000 K): Planck's law integrated against the engine's
+ * analytic CIE 1931 CMFs with 1 nm nodes from 360 to 830 nm. An approximation, because the CMFs are
+ * an analytic fit; with tabulated CMFs use {@link calculatePlanckianChromaticity}.
+ */
+export declare function estimatePlanckianLocusChromaticity(input: {
+    temperatureKelvin: number;
+}): CalculationResult<CieXyChromaticity>;
+/** Planckian chromaticity at T using either locus model. */
+export declare function calculatePlanckianChromaticity(input: {
+    temperatureKelvin: number;
+    locus: PlanckianLocusModel;
+}): CalculationResult<CieXyChromaticity>;
+/**
+ * McCamy (1992) cubic estimate of CCT from CIE 1931 xy:
+ * n = (x − 0.3320)/(0.1858 − y), CCT = 449 n³ + 3525 n² + 6823.3 n + 5520.33.
+ * An approximation that carries no Duv. Measured for this engine (October 17, 2026) on points of a
+ * Planckian locus integrated from the CIE 1931 2° 1 nm table (360–830 nm, exact c₂): it deviates by up
+ * to 10 K over 2856–6504 K (largest near 3500 K), 19 K at 2000 K, 17 K at 8000 K, 118 K at 10000 K
+ * and 442 K at 12500 K. See docs/COLORIMETRY.md.
+ */
+export declare function estimateCorrelatedColorTemperatureMcCamy(input: {
+    chromaticity: CieXyChromaticity;
+}): CalculationResult<{
+    correlatedColorTemperatureKelvin: number;
+}>;
+export interface CorrelatedColorTemperatureResult {
+    correlatedColorTemperatureKelvin: number;
+    /** Signed CIE 1960 uv distance from the locus; positive above (greenish), negative below (the engine's convention). */
+    duv: number;
+}
+/**
+ * CCT and Duv of a chromaticity as the nearest point of the Planckian locus in the CIE
+ * 1960 UCS (Smet et al. 2023; also CIE 15:2018). Finds the root of the analytic temperature derivative
+ * of the squared uv distance (safeguarded Newton with bisection fallback, bracketed by a cached coarse
+ * scan in reciprocal temperature), converged until a step changes T by at most 1e-10 of T. Throws
+ * (fails closed) when the nearest point lies beyond the model's range, or when |Duv| > 0.05 (see
+ * {@link MAX_CORRELATED_COLOR_TEMPERATURE_DUV}). Duv is positive above the locus (toward green) and
+ * negative below it, the engine's documented sign convention.
+ */
+export declare function calculateCorrelatedColorTemperature(input: {
+    chromaticity: CieXyChromaticity;
+    locus: PlanckianLocusModel;
+}): CalculationResult<CorrelatedColorTemperatureResult>;
+/** Locus whose temperature defines a white for CCT + Duv. */
+export type WhiteLocus = "planckian" | "cie-daylight";
+/**
+ * Chromaticity for CCT and Duv: the locus point (Planckian or CIE daylight) offset by
+ * Duv along the unit normal of the Planckian locus at the same temperature in the CIE
+ * 1960 UCS. For `cie-daylight`, Duv = 0 returns the daylight-locus point itself.
+ * Throws InvalidScientificInputError when the offset point is not a physical chromaticity
+ * (x ≥ 0, y > 0, x + y ≤ 1), for example 2000 K with Duv +0.02 (x + y ≈ 1.06).
+ */
+export declare function calculateChromaticityFromCorrelatedColorTemperature(input: {
+    correlatedColorTemperatureKelvin: number;
+    duv: number;
+    whiteLocus: WhiteLocus;
+    locus: PlanckianLocusModel;
+}): CalculationResult<CieXyChromaticity>;