@photivra/engine 1.5.0 → 2.0.0

package/dist/color/illuminants.js

@@ -0,0 +1,434 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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 { approximationResult, calculatedResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { COLORIMETRY_MODEL_VERSION, integrateSampledXyz, prepareColorMatchingFunctions, prepareColorimetricSpectrum, sampleColorimetricBasis } from "./color-matching-functions.js";
+import { chromaticityOfUv, chromaticityOfXyz, parseChromaticity, requireFiniteNumber, requirePositiveNumber, requireRecordValue, uvOfChromaticity } from "./colorimetry-math.js";
+import { rejectUnknownFields, requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+/** Exact SI defining constants (BIPM SI Brochure, 9th edition, 2019). */
+export const PLANCK_CONSTANT_JOULE_SECONDS = 6.62607015e-34;
+export const SPEED_OF_LIGHT_METERS_PER_SECOND = 299_792_458;
+export const BOLTZMANN_CONSTANT_JOULES_PER_KELVIN = 1.380649e-23;
+/** Second radiation constant c₂ = hc/k in m·K (derived from the exact constants). */
+export const SECOND_RADIATION_CONSTANT_METER_KELVIN = (PLANCK_CONSTANT_JOULE_SECONDS * SPEED_OF_LIGHT_METERS_PER_SECOND) / BOLTZMANN_CONSTANT_JOULES_PER_KELVIN;
+const FIRST_RADIATION_CONSTANT_RADIANCE = 2 * PLANCK_CONSTANT_JOULE_SECONDS * SPEED_OF_LIGHT_METERS_PER_SECOND ** 2;
+/** Temperature range of the Planckian-locus models, K. */
+export const PLANCKIAN_LOCUS_RANGE_KELVIN = Object.freeze({ minimum: 1000, maximum: 100000 });
+/** CIE daylight-locus validity, K. */
+export const CIE_DAYLIGHT_LOCUS_RANGE_KELVIN = Object.freeze({ 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 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 function calculatePlanckianSpectralRadiance(input) {
+    requireInputKeys(input, "calculatePlanckianSpectralRadiance", ["temperatureKelvin", "wavelengthNanometers"]);
+    const t = requirePositiveNumber(input.temperatureKelvin, "temperatureKelvin");
+    const nm = requirePositiveNumber(input.wavelengthNanometers, "wavelengthNanometers");
+    const lambda = nm * 1e-9;
+    const exponent = SECOND_RADIATION_CONSTANT_METER_KELVIN / (lambda * t);
+    // expm1 keeps precision in the Rayleigh–Jeans limit; overflow gives radiance 0.
+    const radiancePerMeter = FIRST_RADIATION_CONSTANT_RADIANCE / lambda ** 5 / Math.expm1(exponent);
+    return radiancePerMeter * 1e-9;
+}
+/** Planckian spectral radiance (W·m⁻²·sr⁻¹·nm⁻¹) as a function spectrum over the given range. */
+export function createPlanckianSpectrum(input) {
+    requireInputKeys(input, "createPlanckianSpectrum", ["temperatureKelvin", "wavelengthRangeNanometers"]);
+    const temperatureKelvin = requirePositiveNumber(input.temperatureKelvin, "temperatureKelvin");
+    const range = requireRecordValue(input.wavelengthRangeNanometers, "wavelengthRangeNanometers");
+    rejectUnknownFields(range, ["minimum", "maximum"], "wavelengthRangeNanometers");
+    const spectrum = {
+        kind: "function",
+        wavelengthRangeNanometers: { minimum: range.minimum, maximum: range.maximum },
+        evaluate: (wavelengthNanometers) => calculatePlanckianSpectralRadiance({ temperatureKelvin, wavelengthNanometers })
+    };
+    prepareColorimetricSpectrum(spectrum, "planckianSpectrum");
+    return spectrum;
+}
+/** CIE illuminant A defining range (nm). */
+export const CIE_ILLUMINANT_A_RANGE_NANOMETERS = Object.freeze({ 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 function calculateCieIlluminantARelativeSpectralPower(wavelengthNanometers) {
+    const nm = requireFiniteNumber(wavelengthNanometers, "wavelengthNanometers");
+    if (nm < CIE_ILLUMINANT_A_RANGE_NANOMETERS.minimum || nm > CIE_ILLUMINANT_A_RANGE_NANOMETERS.maximum) {
+        throw new InvalidScientificInputError("CIE illuminant A is defined from 300 nm to 830 nm.");
+    }
+    const c = 1.435e7 / 2848; // nm·K / K
+    return 100 * (560 / nm) ** 5 * (Math.expm1(c / 560) / Math.expm1(c / nm));
+}
+/** CIE illuminant A as a function spectrum over its defining range. */
+export function createCieIlluminantASpectrum() {
+    return { kind: "function", wavelengthRangeNanometers: { ...CIE_ILLUMINANT_A_RANGE_NANOMETERS }, evaluate: calculateCieIlluminantARelativeSpectralPower };
+}
+function requireTemperatureIn(t, range, what) {
+    const value = requirePositiveNumber(t, what);
+    if (value < range.minimum || value > range.maximum) {
+        throw new InvalidScientificInputError(what + " must lie in [" + range.minimum + ", " + range.maximum + "] K.");
+    }
+    return value;
+}
+function daylightChromaticity(t) {
+    const x = t <= 7000
+        ? -4.6070e9 / t ** 3 + 2.9678e6 / t ** 2 + 0.09911e3 / t + 0.244063
+        : -2.0064e9 / t ** 3 + 1.9018e6 / t ** 2 + 0.24748e3 / t + 0.237040;
+    return { x, y: -3.000 * x * x + 2.870 * x - 0.275 };
+}
+/**
+ * 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 function calculateCieDaylightComponentWeights(input) {
+    requireInputKeys(input, "calculateCieDaylightComponentWeights", ["correlatedColorTemperatureKelvin", "coefficientRounding"]);
+    const t = requireTemperatureIn(input.correlatedColorTemperatureKelvin, CIE_DAYLIGHT_LOCUS_RANGE_KELVIN, "correlatedColorTemperatureKelvin");
+    if (input.coefficientRounding !== "none" && input.coefficientRounding !== "cie-three-decimals") {
+        throw new InvalidConfigurationError("coefficientRounding must be \"none\" or \"cie-three-decimals\".");
+    }
+    const xy = daylightChromaticity(t);
+    const m = 0.0241 + 0.2562 * xy.x - 0.7341 * xy.y;
+    let m1 = (-1.3515 - 1.7703 * xy.x + 5.9114 * xy.y) / m;
+    let m2 = (0.0300 - 31.4424 * xy.x + 30.0717 * xy.y) / m;
+    if (input.coefficientRounding === "cie-three-decimals") {
+        m1 = Math.round(m1 * 1000) / 1000;
+        m2 = Math.round(m2 * 1000) / 1000;
+    }
+    return calculatedResult({ correlatedColorTemperatureKelvin: t, chromaticity: xy, m1, m2, coefficientRounding: input.coefficientRounding }, "cie-daylight-locus", COLORIMETRY_MODEL_VERSION, ["CIE daylight-locus polynomial and M1/M2 weights, checked against the free CIE D55 and D65 datasets (no free formula text found); valid 4000–25000 K"]);
+}
+/**
+ * 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 function createCieDaylightSpectrum(input) {
+    requireInputKeys(input, "createCieDaylightSpectrum", ["correlatedColorTemperatureKelvin", "coefficientRounding", "basis"]);
+    const weights = calculateCieDaylightComponentWeights({
+        correlatedColorTemperatureKelvin: input.correlatedColorTemperatureKelvin,
+        coefficientRounding: input.coefficientRounding
+    }).value;
+    const basis = requireRecordValue(input.basis, "basis");
+    rejectUnknownFields(basis, ["s0", "s1", "s2", "datasetId"], "basis");
+    if (typeof basis.datasetId !== "string" || basis.datasetId.trim().length === 0) {
+        throw new InvalidConfigurationError("basis.datasetId must be a non-empty string.");
+    }
+    const s0 = prepareColorimetricSpectrum({ kind: "tabulated", samples: input.basis.s0 }, "basis.s0");
+    const s1 = prepareColorimetricSpectrum({ kind: "tabulated", samples: input.basis.s1 }, "basis.s1");
+    const s2 = prepareColorimetricSpectrum({ kind: "tabulated", samples: input.basis.s2 }, "basis.s2");
+    const samples = input.basis.s0.map((sample) => {
+        const w = sample.wavelengthNanometers;
+        return { wavelengthNanometers: w, value: s0.evaluate(w) + weights.m1 * s1.evaluate(w) + weights.m2 * s2.evaluate(w) };
+    });
+    return { kind: "tabulated", samples };
+}
+/** Number of intervals of the coarse reciprocal-temperature scan that brackets the CCT search. */
+const CCT_SCAN_STEPS = 200;
+/**
+ * Convergence tolerance of the CCT root-find: it stops once a Newton (or bisection) step changes T by
+ * at most this fraction of T (1e-6 K at 10000 K).
+ */
+const CCT_RELATIVE_TOLERANCE = 1e-10;
+/**
+ * Prepares a Planck-integration locus: the CMF values and 1/λ⁵ factors are sampled once, so each
+ * temperature costs one exponential per node. Planck's constant factor 2hc² cancels in chromaticity.
+ *
+ * Derivatives: with x = 1/T, aᵢ = c₂/λᵢ and rᵢ = 1/(exp(aᵢx) − 1), Planck's law is proportional to
+ * λᵢ⁻⁵ rᵢ, and exactly dr/dx = −a(r + r²) and d²r/dx² = a²(r + 3r² + 2r³) (differentiate
+ * r = 1/(E − 1), E = exp(ax), and use E = 1 + 1/r). They are summed in the same quadrature as X, Y, Z.
+ */
+function preparePlanckIntegrationLocus(cmfSource, quadratureNodes, model) {
+    const cmf = prepareColorMatchingFunctions(cmfSource);
+    const unit = prepareColorimetricSpectrum({ kind: "function", wavelengthRangeNanometers: cmf.wavelengthRangeNanometers, evaluate: () => 1 });
+    const basis = sampleColorimetricBasis(quadratureNodes, unit, cmf);
+    const n = basis.nodes.length;
+    const exponentPerKelvin = new Float64Array(n), inverseFifth = new Float64Array(n);
+    // Per-node constants of the derivative sums: weight × CMF × λ⁻⁵ for X, Y and Z.
+    const wx = new Float64Array(n), wy = new Float64Array(n), wz = new Float64Array(n);
+    for (let i = 0; i < n; i++) {
+        const lambda = basis.nodes[i].wavelengthNanometers * 1e-9;
+        exponentPerKelvin[i] = SECOND_RADIATION_CONSTANT_METER_KELVIN / lambda;
+        inverseFifth[i] = 1 / lambda ** 5;
+        const w = basis.weights[i] * inverseFifth[i];
+        wx[i] = w * basis.xBar[i];
+        wy[i] = w * basis.yBar[i];
+        wz[i] = w * basis.zBar[i];
+    }
+    const factor = new Float64Array(n);
+    const range = PLANCKIAN_LOCUS_RANGE_KELVIN;
+    let scanCache;
+    const locus = {
+        range,
+        approximation: cmf.scientificStatus === "approximation",
+        model,
+        chromaticity(t) {
+            // expm1 keeps precision at long wavelengths; overflow at short ones gives 0, as in Planck's law.
+            for (let i = 0; i < n; i++)
+                factor[i] = inverseFifth[i] / Math.expm1(exponentPerKelvin[i] / t);
+            return chromaticityOfXyz(integrateSampledXyz(basis, factor));
+        },
+        sample(x) {
+            let sx = 0, sy = 0, sz = 0, sx1 = 0, sy1 = 0, sz1 = 0, sx2 = 0, sy2 = 0, sz2 = 0;
+            for (let i = 0; i < n; i++) {
+                const a = exponentPerKelvin[i];
+                // An overflowing expm1 gives r = 0 and zero derivatives, the exact limit.
+                const r = 1 / Math.expm1(a * x), r2 = r * r;
+                const q1 = r + r2, k1 = -a * q1, k2 = a * a * (q1 + 2 * r2 * (1 + r));
+                const cx = wx[i], cy = wy[i], cz = wz[i];
+                sx += cx * r;
+                sy += cy * r;
+                sz += cz * r;
+                sx1 += cx * k1;
+                sy1 += cy * k1;
+                sz1 += cz * k1;
+                sx2 += cx * k2;
+                sy2 += cy * k2;
+                sz2 += cz * k2;
+            }
+            // u = 4X/d, v = 6Y/d, d = X + 15Y + 3Z; quotient rule: q' = (N' − q d')/d, q'' = (N'' − 2q'd' − q d'')/d.
+            const d = sx + 15 * sy + 3 * sz, d1 = sx1 + 15 * sy1 + 3 * sz1, d2 = sx2 + 15 * sy2 + 3 * sz2;
+            if (!(d > 0) || !Number.isFinite(d))
+                throw new InvalidScientificInputError("Chromaticity requires X + Y + Z > 0.");
+            const u = (4 * sx) / d, v = (6 * sy) / d;
+            const du = (4 * sx1 - u * d1) / d, dv = (6 * sy1 - v * d1) / d;
+            return { u, v, du, dv, d2u: (4 * sx2 - 2 * du * d1 - u * d2) / d, d2v: (6 * sy2 - 2 * dv * d1 - v * d2) / d };
+        },
+        scan() {
+            if (scanCache === undefined) {
+                const lo = 1e6 / range.maximum, hi = 1e6 / range.minimum;
+                scanCache = Array.from({ length: CCT_SCAN_STEPS + 1 }, (_, i) => uvOfChromaticity(locus.chromaticity(1e6 / (lo + ((hi - lo) * i) / CCT_SCAN_STEPS))));
+            }
+            return scanCache;
+        }
+    };
+    return locus;
+}
+/** 1 nm nodes at 360, 361, …, 830 nm with Δλ = 1 nm (the CIE 15 summation convention). */
+const DEFAULT_LOCUS_NODES = Object.freeze(Array.from({ length: 471 }, (_, i) => Object.freeze({ wavelengthNanometers: 360 + i, wavelengthMeasureNanometers: 1 })));
+let defaultLocus;
+/** The default locus, prepared on first use and shared (its scan cache is computed once). */
+function analyticCmfLocus() {
+    defaultLocus ??= preparePlanckIntegrationLocus({ kind: "analytic-cie-1931-multi-lobe-fit" }, DEFAULT_LOCUS_NODES, "planck-analytic-cmf");
+    return defaultLocus;
+}
+/**
+ * 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 function estimatePlanckianLocusChromaticity(input) {
+    requireInputKeys(input, "estimatePlanckianLocusChromaticity", ["temperatureKelvin"]);
+    const t = requireTemperatureIn(input.temperatureKelvin, PLANCKIAN_LOCUS_RANGE_KELVIN, "temperatureKelvin");
+    return approximationResult(analyticCmfLocus().chromaticity(t), "planckian-locus-planck-analytic-cmf", COLORIMETRY_MODEL_VERSION, ["Planck's law integrated against the engine's analytic CIE 1931 CMF fit, 1 nm nodes 360–830 nm; valid 1000–100000 K"]);
+}
+function prepareLocus(model) {
+    const record = requireRecordValue(model, "locus");
+    if (record.kind === "planck-analytic-cmf") {
+        rejectUnknownFields(record, ["kind"], "locus");
+        return analyticCmfLocus();
+    }
+    if (record.kind !== "planck-integration")
+        throw new InvalidConfigurationError("locus.kind is not supported.");
+    rejectUnknownFields(record, ["kind", "colorMatchingFunctions", "quadratureNodes"], "locus");
+    const m = model;
+    const cmf = prepareColorMatchingFunctions(m.colorMatchingFunctions);
+    return preparePlanckIntegrationLocus(m.colorMatchingFunctions, m.quadratureNodes, "planck-integration-" + cmf.sourceKind);
+}
+/** Planckian chromaticity at T using either locus model. */
+export function calculatePlanckianChromaticity(input) {
+    requireInputKeys(input, "calculatePlanckianChromaticity", ["temperatureKelvin", "locus"]);
+    const locus = prepareLocus(input.locus);
+    const t = requireTemperatureIn(input.temperatureKelvin, locus.range, "temperatureKelvin");
+    const value = locus.chromaticity(t);
+    const assumptions = ["Planckian locus model: " + locus.model];
+    return locus.approximation
+        ? approximationResult(value, "planckian-chromaticity", COLORIMETRY_MODEL_VERSION, assumptions)
+        : calculatedResult(value, "planckian-chromaticity", COLORIMETRY_MODEL_VERSION, assumptions);
+}
+/**
+ * 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 function estimateCorrelatedColorTemperatureMcCamy(input) {
+    requireInputKeys(input, "estimateCorrelatedColorTemperatureMcCamy", ["chromaticity"]);
+    const xy = parseChromaticity(input.chromaticity, "chromaticity");
+    const n = (xy.x - 0.3320) / (0.1858 - xy.y);
+    const cct = 449 * n ** 3 + 3525 * n ** 2 + 6823.3 * n + 5520.33;
+    if (!Number.isFinite(cct) || cct <= 0)
+        throw new InvalidScientificInputError("Chromaticity is outside the McCamy approximation domain.");
+    return approximationResult({ correlatedColorTemperatureKelvin: cct }, "cct-mccamy-1992", COLORIMETRY_MODEL_VERSION, ["McCamy (1992) cubic; intended for chromaticities near the Planckian locus, about 2000–12500 K"]);
+}
+/** The "above-locus" unit normal at a sample: the increasing-T unit tangent (−du/dx, −dv/dx) turned by −90°. */
+function locusNormal(s) {
+    const len = Math.hypot(s.du, s.dv);
+    const tangent = { u: -s.du / len, v: -s.dv / len };
+    // u decreases as T rises, so turning the tangent by −90° points toward larger v (above the locus).
+    return { u: tangent.v, v: -tangent.u };
+}
+/**
+ * Nearest locus point to `target` in CIE 1960 uv: the root of the derivative of the squared distance
+ * F = (u − u₀)² + (v − v₀)². Roots of dF/dT and of dF/dx (x = 1/T) coincide, since dx/dT = −1/T² ≠ 0;
+ * the root-find runs in x with g = ½ dF/dx = (u − u₀)u′ + (v − v₀)v′ and
+ * g′ = u′² + v′² + (u − u₀)u″ + (v − v₀)v″ (analytic, see {@link preparePlanckIntegrationLocus}).
+ * The cached coarse scan brackets the minimum; a Newton step falls back to bisection whenever it would
+ * leave the bracket. Returns the root and the locus sample there, or undefined when the nearest point
+ * lies beyond the model's range (by more than the tolerance).
+ */
+function nearestLocusPoint(locus, target) {
+    const steps = CCT_SCAN_STEPS;
+    const lo = 1e6 / locus.range.maximum, hi = 1e6 / locus.range.minimum, step = (hi - lo) / steps;
+    const gridX = (i) => (lo + step * i) * 1e-6;
+    const scan = locus.scan();
+    const f = (i) => (scan[i].u - target.u) ** 2 + (scan[i].v - target.v) ** 2;
+    let best = 0, bestValue = Infinity;
+    for (let i = 0; i <= steps; i++) {
+        const value = f(i);
+        if (value < bestValue) {
+            bestValue = value;
+            best = i;
+        }
+    }
+    const tolerance = (x) => CCT_RELATIVE_TOLERANCE * x;
+    const derivatives = (s) => {
+        const eu = s.u - target.u, ev = s.v - target.v;
+        return { g: eu * s.du + ev * s.dv, gp: s.du * s.du + s.dv * s.dv + eu * s.d2u + ev * s.d2v };
+    };
+    let a, b, x;
+    if (best === 0 || best === steps) {
+        // The scan minimum is a range limit: the nearest point is inside only if F still falls inward.
+        x = gridX(best);
+        const s = locus.sample(x), { g, gp } = derivatives(s);
+        if (best === 0 ? g >= 0 : g <= 0) {
+            // At the limit within the tolerance (one Newton step estimates the distance), or beyond it.
+            return g === 0 || (gp > 0 && Math.abs(g / gp) <= tolerance(x)) ? { x, sample: s } : undefined;
+        }
+        a = best === 0 ? x : gridX(steps - 1);
+        b = best === 0 ? gridX(1) : x;
+    }
+    else {
+        // A discrete minimum between its neighbours brackets a local minimum; start at the parabola vertex.
+        a = gridX(best - 1);
+        b = gridX(best + 1);
+        const fm = f(best - 1), fp = f(best + 1), curvature = fm - 2 * bestValue + fp;
+        x = gridX(best) + (curvature > 0 ? (step * 1e-6 * (fm - fp)) / (2 * curvature) : 0);
+    }
+    let s = locus.sample(x);
+    for (let i = 0; i < 100; i++) {
+        const { g, gp } = derivatives(s);
+        if (g === 0)
+            break;
+        if (g < 0)
+            a = x;
+        else
+            b = x;
+        let next = x - g / gp;
+        if (!(gp > 0) || !(next > a && next < b))
+            next = 0.5 * (a + b);
+        const converged = Math.abs(next - x) <= tolerance(next) || b - a <= tolerance(next);
+        x = next;
+        s = locus.sample(x);
+        if (converged)
+            break;
+    }
+    return { x, sample: s };
+}
+/**
+ * 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 function calculateCorrelatedColorTemperature(input) {
+    requireInputKeys(input, "calculateCorrelatedColorTemperature", ["chromaticity", "locus"]);
+    const xy = parseChromaticity(input.chromaticity, "chromaticity");
+    const locus = prepareLocus(input.locus);
+    const target = uvOfChromaticity(xy);
+    const nearest = nearestLocusPoint(locus, target);
+    if (nearest === undefined)
+        throw new InvalidScientificInputError("Chromaticity's nearest Planckian point lies outside the locus model range.");
+    const t = Math.min(locus.range.maximum, Math.max(locus.range.minimum, 1 / nearest.x));
+    const point = nearest.sample, normal = locusNormal(point);
+    const duv = (target.u - point.u) * normal.u + (target.v - point.v) * normal.v;
+    if (Math.abs(duv) > MAX_CORRELATED_COLOR_TEMPERATURE_DUV) {
+        throw new InvalidScientificInputError("|Duv| exceeds 0.05; no CCT is reported this far from the Planckian locus (the range evaluated by Smet et al. 2023).");
+    }
+    const value = { correlatedColorTemperatureKelvin: t, duv };
+    const assumptions = ["Nearest point on the Planckian locus in CIE 1960 uv; locus model: " + locus.model, "Duv sign: positive above the locus (toward green), negative below (engine convention)"];
+    return locus.approximation
+        ? approximationResult(value, "cct-duv-locus-search", COLORIMETRY_MODEL_VERSION, assumptions)
+        : calculatedResult(value, "cct-duv-locus-search", COLORIMETRY_MODEL_VERSION, assumptions);
+}
+/**
+ * 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 function calculateChromaticityFromCorrelatedColorTemperature(input) {
+    requireInputKeys(input, "calculateChromaticityFromCorrelatedColorTemperature", ["correlatedColorTemperatureKelvin", "duv", "whiteLocus", "locus"]);
+    const locus = prepareLocus(input.locus);
+    const duv = requireFiniteNumber(input.duv, "duv");
+    if (Math.abs(duv) > MAX_CORRELATED_COLOR_TEMPERATURE_DUV)
+        throw new InvalidScientificInputError("|duv| must not exceed 0.05.");
+    if (input.whiteLocus !== "planckian" && input.whiteLocus !== "cie-daylight")
+        throw new InvalidConfigurationError("whiteLocus is not supported.");
+    const range = input.whiteLocus === "cie-daylight"
+        ? { minimum: Math.max(locus.range.minimum, CIE_DAYLIGHT_LOCUS_RANGE_KELVIN.minimum), maximum: Math.min(locus.range.maximum, CIE_DAYLIGHT_LOCUS_RANGE_KELVIN.maximum) }
+        : locus.range;
+    const t = requireTemperatureIn(input.correlatedColorTemperatureKelvin, range, "correlatedColorTemperatureKelvin");
+    const normal = locusNormal(locus.sample(1 / t));
+    const base = uvOfChromaticity(input.whiteLocus === "cie-daylight" ? daylightChromaticity(t) : locus.chromaticity(t));
+    const value = chromaticityOfUv({ u: base.u + duv * normal.u, v: base.v + duv * normal.v });
+    // The same domain parseChromaticity enforces on input, so every result can be passed back in.
+    if (!(value.x >= 0) || !(value.y > 0) || !(value.x + value.y <= 1)) {
+        throw new InvalidScientificInputError("correlatedColorTemperatureKelvin and duv give a chromaticity outside x >= 0, y > 0, x + y <= 1.");
+    }
+    const assumptions = ["White locus: " + input.whiteLocus + "; Duv offset along the Planckian-locus normal (" + locus.model + ") in CIE 1960 uv"];
+    const exactDaylightPoint = input.whiteLocus === "cie-daylight" && duv === 0;
+    return locus.approximation && !exactDaylightPoint
+        ? approximationResult(value, "chromaticity-from-cct-duv", COLORIMETRY_MODEL_VERSION, assumptions)
+        : calculatedResult(value, "chromaticity-from-cct-duv", COLORIMETRY_MODEL_VERSION, assumptions);
+}
+//# sourceMappingURL=illuminants.js.map

package/dist/color/illuminants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"illuminants.js","sourceRoot":"","sources":["../../src/color/illuminants.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAA0B,MAAM,+BAA+B,CAAC;AAE9G,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,6BAA6B,EAC7B,2BAA2B,EAC3B,uBAAuB,EAKxB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAGjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrF,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,yEAAyE;AACzE,MAAM,CAAC,MAAM,6BAA6B,GAAG,cAAc,CAAC;AAC5D,MAAM,CAAC,MAAM,gCAAgC,GAAG,WAAW,CAAC;AAC5D,MAAM,CAAC,MAAM,oCAAoC,GAAG,YAAY,CAAC;AACjE,qFAAqF;AACrF,MAAM,CAAC,MAAM,sCAAsC,GAAG,CAAC,6BAA6B,GAAG,gCAAgC,CAAC,GAAG,oCAAoC,CAAC;AAChK,MAAM,iCAAiC,GAAG,CAAC,GAAG,6BAA6B,GAAG,gCAAgC,IAAI,CAAC,CAAC;AAEpH,0DAA0D;AAC1D,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;AAC9F,sCAAsC;AACtC,MAAM,CAAC,MAAM,+BAA+B,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;AAChG;;;GAGG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,IAAI,CAAC;AAEzD;;;GAGG;AACH,MAAM,UAAU,kCAAkC,CAAC,KAAkE;IACnH,gBAAgB,CAAC,KAAK,EAAE,oCAAoC,EAAE,CAAC,mBAAmB,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAC7G,MAAM,CAAC,GAAG,qBAAqB,CAAC,KAAK,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAAC;IAC9E,MAAM,EAAE,GAAG,qBAAqB,CAAC,KAAK,CAAC,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;IACrF,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC;IACzB,MAAM,QAAQ,GAAG,sCAAsC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACvE,gFAAgF;IAChF,MAAM,gBAAgB,GAAG,iCAAiC,GAAG,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAChG,OAAO,gBAAgB,GAAG,IAAI,CAAC;AACjC,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,uBAAuB,CAAC,KAAkG;IACxI,gBAAgB,CAAC,KAAK,EAAE,yBAAyB,EAAE,CAAC,mBAAmB,EAAE,2BAA2B,CAAC,CAAC,CAAC;IACvG,MAAM,iBAAiB,GAAG,qBAAqB,CAAC,KAAK,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAAC;IAC9F,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,yBAAyB,EAAE,2BAA2B,CAAC,CAAC;IAC/F,mBAAmB,CAAC,KAAK,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,2BAA2B,CAAC,CAAC;IAChF,MAAM,QAAQ,GAAyB;QACrC,IAAI,EAAE,UAAU;QAChB,yBAAyB,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAiB,EAAE,OAAO,EAAE,KAAK,CAAC,OAAiB,EAAE;QACjG,QAAQ,EAAE,CAAC,oBAAoB,EAAE,EAAE,CAAC,kCAAkC,CAAC,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,CAAC;KACpH,CAAC;IACF,2BAA2B,CAAC,QAAQ,EAAE,mBAAmB,CAAC,CAAC;IAC3D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,4CAA4C;AAC5C,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;AAE/F;;;;GAIG;AACH,MAAM,UAAU,4CAA4C,CAAC,oBAA4B;IACvF,MAAM,EAAE,GAAG,mBAAmB,CAAC,oBAAoB,EAAE,sBAAsB,CAAC,CAAC;IAC7E,IAAI,EAAE,GAAG,iCAAiC,CAAC,OAAO,IAAI,EAAE,GAAG,iCAAiC,CAAC,OAAO,EAAE,CAAC;QACrG,MAAM,IAAI,2BAA2B,CAAC,oDAAoD,CAAC,CAAC;IAC9F,CAAC;IACD,MAAM,CAAC,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC,WAAW;IACrC,OAAO,GAAG,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,4BAA4B;IAC1C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,yBAAyB,EAAE,EAAE,GAAG,iCAAiC,EAAE,EAAE,QAAQ,EAAE,4CAA4C,EAAE,CAAC;AAC3J,CAAC;AAED,SAAS,oBAAoB,CAAC,CAAU,EAAE,KAA2C,EAAE,IAAY;IACjG,MAAM,KAAK,GAAG,qBAAqB,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC7C,IAAI,KAAK,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;QACnD,MAAM,IAAI,2BAA2B,CAAC,IAAI,GAAG,gBAAgB,GAAG,KAAK,CAAC,OAAO,GAAG,IAAI,GAAG,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC;IACjH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,oBAAoB,CAAC,CAAS;IACrC,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI;QACjB,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,GAAG,CAAC,GAAG,QAAQ;QACnE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,GAAG,CAAC,GAAG,QAAQ,CAAC;IACtE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC;AACtD,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,oCAAoC,CAAC,KAGpD;IACC,gBAAgB,CAAC,KAAK,EAAE,sCAAsC,EAAE,CAAC,kCAAkC,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAC7H,MAAM,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,gCAAgC,EAAE,+BAA+B,EAAE,kCAAkC,CAAC,CAAC;IAC5I,IAAI,KAAK,CAAC,mBAAmB,KAAK,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,oBAAoB,EAAE,CAAC;QAC/F,MAAM,IAAI,yBAAyB,CAAC,iEAAiE,CAAC,CAAC;IACzG,CAAC;IACD,MAAM,EAAE,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC;IACjD,IAAI,EAAE,GAAG,CAAC,CAAC,MAAM,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC,GAAG,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACvD,IAAI,EAAE,GAAG,CAAC,MAAM,GAAG,OAAO,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxD,IAAI,KAAK,CAAC,mBAAmB,KAAK,oBAAoB,EAAE,CAAC;QACvD,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;QAClC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,CAAC;IACD,OAAO,gBAAgB,CAAC,EAAE,gCAAgC,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,mBAAmB,EAAE,KAAK,CAAC,mBAAmB,EAAE,EACvI,oBAAoB,EAAE,yBAAyB,EAAE,CAAC,qJAAqJ,CAAC,CAAC,CAAC;AAC9M,CAAC;AAWD;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAIzC;IACC,gBAAgB,CAAC,KAAK,EAAE,2BAA2B,EAAE,CAAC,kCAAkC,EAAE,qBAAqB,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3H,MAAM,OAAO,GAAG,oCAAoC,CAAC;QACnD,gCAAgC,EAAE,KAAK,CAAC,gCAAgC;QACxE,mBAAmB,EAAE,KAAK,CAAC,mBAAmB;KAC/C,CAAC,CAAC,KAAK,CAAC;IACT,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACvD,mBAAmB,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,CAAC;IACrE,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC/E,MAAM,IAAI,yBAAyB,CAAC,6CAA6C,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,EAAE,GAAG,2BAA2B,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IACnG,MAAM,EAAE,GAAG,2BAA2B,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IACnG,MAAM,EAAE,GAAG,2BAA2B,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IACnG,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QAC5C,MAAM,CAAC,GAAG,MAAM,CAAC,oBAAoB,CAAC;QACtC,OAAO,EAAE,oBAAoB,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IACxH,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AACxC,CAAC;AAcD,kGAAkG;AAClG,MAAM,cAAc,GAAG,GAAG,CAAC;AAC3B;;;GAGG;AACH,MAAM,sBAAsB,GAAG,KAAK,CAAC;AA0BrC;;;;;;;GAOG;AACH,SAAS,6BAA6B,CAAC,SAAuC,EAAE,eAAsD,EAAE,KAAa;IACnJ,MAAM,GAAG,GAAG,6BAA6B,CAAC,SAAS,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,2BAA2B,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,yBAAyB,EAAE,GAAG,CAAC,yBAAyB,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5I,MAAM,KAAK,GAAG,uBAAuB,CAAC,eAAe,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAClE,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;IAC7B,MAAM,iBAAiB,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IAClF,gFAAgF;IAChF,MAAM,EAAE,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IACnF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,oBAAoB,GAAG,IAAI,CAAC;QAC3D,iBAAiB,CAAC,CAAC,CAAC,GAAG,sCAAsC,GAAG,MAAM,CAAC;QACvE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI,CAAC,CAAC;QAClC,MAAM,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAE,GAAG,YAAY,CAAC,CAAC,CAAE,CAAC;QAC/C,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC;QAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC;QAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC;IACrF,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,4BAA4B,CAAC;IAC3C,IAAI,SAAuD,CAAC;IAC5D,MAAM,KAAK,GAAkB;QAC3B,KAAK;QACL,aAAa,EAAE,GAAG,CAAC,gBAAgB,KAAK,eAAe;QACvD,KAAK;QACL,YAAY,CAAC,CAAS;YACpB,iGAAiG;YACjG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;gBAAE,MAAM,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC,CAAC;YACjG,OAAO,iBAAiB,CAAC,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,MAAM,CAAC,CAAS;YACd,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC;YACjF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3B,MAAM,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAE,CAAC;gBAChC,0EAA0E;gBAC1E,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;gBAC5C,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBACtE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC;gBAC5C,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBAAC,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;gBACzC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;gBAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;gBAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;gBAC/C,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;gBAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;gBAAC,GAAG,IAAI,EAAE,GAAG,EAAE,CAAC;YACjD,CAAC;YACD,0GAA0G;YAC1G,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,EAAE,EAAE,GAAG,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,EAAE,EAAE,GAAG,GAAG,GAAG,EAAE,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;YAC9F,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,MAAM,IAAI,2BAA2B,CAAC,sCAAsC,CAAC,CAAC;YACnH,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;YACzC,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;YAC/D,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;QAChH,CAAC;QACD,IAAI;YACF,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,MAAM,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC;gBACzD,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,cAAc,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;YACxJ,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;IACF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,0FAA0F;AAC1F,MAAM,mBAAmB,GAA0C,MAAM,CAAC,MAAM,CAC9E,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,oBAAoB,EAAE,GAAG,GAAG,CAAC,EAAE,2BAA2B,EAAE,CAAC,EAAE,CAAC,CAAC,CACxH,CAAC;AACF,IAAI,YAAuC,CAAC;AAE5C,6FAA6F;AAC7F,SAAS,gBAAgB;IACvB,YAAY,KAAK,6BAA6B,CAAC,EAAE,IAAI,EAAE,kCAAkC,EAAE,EAAE,mBAAmB,EAAE,qBAAqB,CAAC,CAAC;IACzI,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kCAAkC,CAAC,KAAoC;IACrF,gBAAgB,CAAC,KAAK,EAAE,oCAAoC,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACrF,MAAM,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,iBAAiB,EAAE,4BAA4B,EAAE,mBAAmB,CAAC,CAAC;IAC3G,OAAO,mBAAmB,CAAC,gBAAgB,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,qCAAqC,EAAE,yBAAyB,EAC7H,CAAC,oHAAoH,CAAC,CAAC,CAAC;AAC5H,CAAC;AAED,SAAS,YAAY,CAAC,KAA0B;IAC9C,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAClD,IAAI,MAAM,CAAC,IAAI,KAAK,qBAAqB,EAAE,CAAC;QAC1C,mBAAmB,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;QAC/C,OAAO,gBAAgB,EAAE,CAAC;IAC5B,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,oBAAoB;QAAE,MAAM,IAAI,yBAAyB,CAAC,8BAA8B,CAAC,CAAC;IAC9G,mBAAmB,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,wBAAwB,EAAE,iBAAiB,CAAC,EAAE,OAAO,CAAC,CAAC;IAC5F,MAAM,CAAC,GAAG,KAAqE,CAAC;IAChF,MAAM,GAAG,GAAG,6BAA6B,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC;IACpE,OAAO,6BAA6B,CAAC,CAAC,CAAC,sBAAsB,EAAE,CAAC,CAAC,eAAe,EAAE,qBAAqB,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;AAC5H,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,8BAA8B,CAAC,KAAgE;IAC7G,gBAAgB,CAAC,KAAK,EAAE,gCAAgC,EAAE,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1F,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,iBAAiB,EAAE,KAAK,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC;IAC1F,MAAM,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,WAAW,GAAG,CAAC,yBAAyB,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IAC9D,OAAO,KAAK,CAAC,aAAa;QACxB,CAAC,CAAC,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,WAAW,CAAC;QAC9F,CAAC,CAAC,gBAAgB,CAAC,KAAK,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,WAAW,CAAC,CAAC;AAChG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wCAAwC,CAAC,KAA0C;IACjG,gBAAgB,CAAC,KAAK,EAAE,0CAA0C,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;IACtF,MAAM,EAAE,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;IACjE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC;IAChE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,MAAM,IAAI,2BAA2B,CAAC,0DAA0D,CAAC,CAAC;IACzI,OAAO,mBAAmB,CAAC,EAAE,gCAAgC,EAAE,GAAG,EAAE,EAAE,iBAAiB,EAAE,yBAAyB,EAChH,CAAC,+FAA+F,CAAC,CAAC,CAAC;AACvG,CAAC;AAED,gHAAgH;AAChH,SAAS,WAAW,CAAC,CAAc;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC;IACnD,mGAAmG;IACnG,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;AACzC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CAAC,KAAoB,EAAE,MAA6B;IAC5E,MAAM,KAAK,GAAG,cAAc,CAAC;IAC7B,MAAM,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,GAAG,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,KAAK,CAAC;IAC/F,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC;IAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1B,MAAM,CAAC,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC7F,IAAI,IAAI,GAAG,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YAAC,SAAS,GAAG,KAAK,CAAC;YAAC,IAAI,GAAG,CAAC,CAAC;QAAC,CAAC;IACzD,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,sBAAsB,GAAG,CAAC,CAAC;IACpE,MAAM,WAAW,GAAG,CAAC,CAAc,EAA6B,EAAE;QAChE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;QAC/C,OAAO,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;IAC/F,CAAC,CAAC;IACF,IAAI,CAAS,EAAE,CAAS,EAAE,CAAS,CAAC;IACpC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACjC,+FAA+F;QAC/F,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAChB,MAAM,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QACtD,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,4FAA4F;YAC5F,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAChG,CAAC;QACD,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QACtC,CAAC,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;SAAM,CAAC;QACN,oGAAoG;QACpG,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;QAAC,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;QACzC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,GAAG,EAAE,CAAC;QAC9E,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QAC7B,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,CAAC;YAAE,MAAM;QACnB,IAAI,CAAC,GAAG,CAAC;YAAE,CAAC,GAAG,CAAC,CAAC;;YAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC;YAAE,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC;QACpF,CAAC,GAAG,IAAI,CAAC;QACT,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,SAAS;YAAE,MAAM;IACvB,CAAC;IACD,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAC1B,CAAC;AAQD;;;;;;;;GAQG;AACH,MAAM,UAAU,mCAAmC,CAAC,KAAsE;IACxH,gBAAgB,CAAC,KAAK,EAAE,qCAAqC,EAAE,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1F,MAAM,EAAE,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;IACjE,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;IACjD,IAAI,OAAO,KAAK,SAAS;QAAE,MAAM,IAAI,2BAA2B,CAAC,4EAA4E,CAAC,CAAC;IAC/I,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACtF,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAC9E,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,oCAAoC,EAAE,CAAC;QACzD,MAAM,IAAI,2BAA2B,CAAC,qHAAqH,CAAC,CAAC;IAC/J,CAAC;IACD,MAAM,KAAK,GAAG,EAAE,gCAAgC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC;IAC3D,MAAM,WAAW,GAAG,CAAC,oEAAoE,GAAG,KAAK,CAAC,KAAK,EAAE,uFAAuF,CAAC,CAAC;IAClM,OAAO,KAAK,CAAC,aAAa;QACxB,CAAC,CAAC,mBAAmB,CAAC,KAAK,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,WAAW,CAAC;QAC5F,CAAC,CAAC,gBAAgB,CAAC,KAAK,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,WAAW,CAAC,CAAC;AAC9F,CAAC;AAKD;;;;;;GAMG;AACH,MAAM,UAAU,mDAAmD,CAAC,KAKnE;IACC,gBAAgB,CAAC,KAAK,EAAE,qDAAqD,EAAE,CAAC,kCAAkC,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IACnJ,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACxC,MAAM,GAAG,GAAG,mBAAmB,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAClD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,oCAAoC;QAAE,MAAM,IAAI,2BAA2B,CAAC,6BAA6B,CAAC,CAAC;IAC/H,IAAI,KAAK,CAAC,UAAU,KAAK,WAAW,IAAI,KAAK,CAAC,UAAU,KAAK,cAAc;QAAE,MAAM,IAAI,yBAAyB,CAAC,8BAA8B,CAAC,CAAC;IACjJ,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,KAAK,cAAc;QAC/C,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,+BAA+B,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,+BAA+B,CAAC,OAAO,CAAC,EAAE;QACtK,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC;IAChB,MAAM,CAAC,GAAG,oBAAoB,CAAC,KAAK,CAAC,gCAAgC,EAAE,KAAK,EAAE,kCAAkC,CAAC,CAAC;IAClH,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAC,UAAU,KAAK,cAAc,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IACrH,MAAM,KAAK,GAAG,gBAAgB,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,GAAG,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,GAAG,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;IAC3F,8FAA8F;IAC9F,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,2BAA2B,CAAC,iGAAiG,CAAC,CAAC;IAC3I,CAAC;IACD,MAAM,WAAW,GAAG,CAAC,eAAe,GAAG,KAAK,CAAC,UAAU,GAAG,iDAAiD,GAAG,KAAK,CAAC,KAAK,GAAG,kBAAkB,CAAC,CAAC;IAChJ,MAAM,kBAAkB,GAAG,KAAK,CAAC,UAAU,KAAK,cAAc,IAAI,GAAG,KAAK,CAAC,CAAC;IAC5E,OAAO,KAAK,CAAC,aAAa,IAAI,CAAC,kBAAkB;QAC/C,CAAC,CAAC,mBAAmB,CAAC,KAAK,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,WAAW,CAAC;QACjG,CAAC,CAAC,gBAAgB,CAAC,KAAK,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,WAAW,CAAC,CAAC;AACnG,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Illuminant spectra and correlated-colour-temperature (CCT) helpers.\n *\n * - Planckian radiator: exact Planck law (BIPM Mise en pratique for the kelvin, Absolute Primary\n *   Radiometry 2018, Eq. 1, free) with the exact SI defining constants (h, c, k; BIPM SI Brochure\n *   9th ed. 2019), so c₂ = hc/k = 1.438776877…e-2 m·K (NIST CODATA 2022). Wavelength is the vacuum\n *   wavelength.\n * - CIE standard illuminant A: Planck's law relative to 560 nm with the CIE's defining constants\n *   c₂ = 1.435e-2 m·K and T = 2848 K (also CIE 15:2018 Eq. 4.1 / ISO/CIE 11664-2, paid):\n *   S_A(λ) = 100 (560/λ)^5 (exp(1.435e7/(2848·560)) − 1)/(exp(1.435e7/(2848 λ)) − 1)\n *   (≈ 2856 K with the exact c₂). Computed from the formula, not a copied table; it reproduces the\n *   free CIE 1 nm table (DOI 10.25039/CIE.DS.8jsxjrsn) to its six significant digits.\n * - CIE daylight: the CIE daylight-locus chromaticity polynomial and the M₁/M₂ weights (CIE 15:2018,\n *   paid; no free text of the formulas found). With three-decimal rounding they reproduce the free\n *   CIE D55 and D65 tables. The S₀/S₁/S₂ basis is a CIE dataset (CC BY-SA 4.0, not bundled);\n *   callers supply it.\n * - Planckian locus: the chromaticity of a Planckian radiator at T, computed by integrating Planck's\n *   law against colour-matching functions. The default uses the engine's analytic CIE 1931 fit with\n *   1 nm nodes from 360 to 830 nm (so it inherits that fit's approximation); callers may select\n *   tabulated CMFs and their own nodes. Valid 1000–100000 K.\n * - CCT from chromaticity: McCamy (1992) cubic (approximation), or a nearest-point\n *   search on the Planckian locus in the CIE 1960 UCS (CCT and signed Duv as defined in Smet et al.,\n *   LEUKOS 2023, free archival copy from the US DOE; also CIE 15:2018). Duv sign: positive above the\n *   locus (toward green), negative below (toward magenta), following Ohno, \"Calculation of CCT and Duv\n *   and Practical Conversion Formulae\", CORM 2011 slides (free), slide 5; the engine documents and\n *   tests it.\n * @see docs/COLORIMETRY.md for equations, coordinate/unit conventions and limits.\n */\n\nimport { approximationResult, calculatedResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport type { SpectralWavelengthRangeNanometers } from \"../core/spectral.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport {\n  COLORIMETRY_MODEL_VERSION,\n  integrateSampledXyz,\n  prepareColorMatchingFunctions,\n  prepareColorimetricSpectrum,\n  sampleColorimetricBasis,\n  type ColorMatchingFunctionsSource,\n  type ColorimetricQuadratureNode,\n  type ColorimetricSpectralSample,\n  type ColorimetricSpectrum\n} from \"./color-matching-functions.js\";\nimport {\n  chromaticityOfUv,\n  chromaticityOfXyz,\n  parseChromaticity,\n  requireFiniteNumber,\n  requirePositiveNumber,\n  requireRecordValue,\n  uvOfChromaticity,\n  type Cie1960UvChromaticity,\n  type CieXyChromaticity\n} from \"./colorimetry-math.js\";\nimport { rejectUnknownFields, requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\n/** Exact SI defining constants (BIPM SI Brochure, 9th edition, 2019). */\nexport const PLANCK_CONSTANT_JOULE_SECONDS = 6.62607015e-34;\nexport const SPEED_OF_LIGHT_METERS_PER_SECOND = 299_792_458;\nexport const BOLTZMANN_CONSTANT_JOULES_PER_KELVIN = 1.380649e-23;\n/** Second radiation constant c₂ = hc/k in m·K (derived from the exact constants). */\nexport const SECOND_RADIATION_CONSTANT_METER_KELVIN = (PLANCK_CONSTANT_JOULE_SECONDS * SPEED_OF_LIGHT_METERS_PER_SECOND) / BOLTZMANN_CONSTANT_JOULES_PER_KELVIN;\nconst FIRST_RADIATION_CONSTANT_RADIANCE = 2 * PLANCK_CONSTANT_JOULE_SECONDS * SPEED_OF_LIGHT_METERS_PER_SECOND ** 2;\n\n/** Temperature range of the Planckian-locus models, K. */\nexport const PLANCKIAN_LOCUS_RANGE_KELVIN = Object.freeze({ minimum: 1000, maximum: 100000 });\n/** CIE daylight-locus validity, K. */\nexport const CIE_DAYLIGHT_LOCUS_RANGE_KELVIN = Object.freeze({ minimum: 4000, maximum: 25000 });\n/**\n * Engine limit: no CCT beyond |Duv| = 0.05, the range over which Smet et al. (2023, free) evaluate CCT\n * methods for nominally white light (CIE 15:2018 §9.5, paid, gives the same limit).\n */\nexport const MAX_CORRELATED_COLOR_TEMPERATURE_DUV = 0.05;\n\n/**\n * Planck's law for blackbody spectral radiance per unit (vacuum) wavelength:\n * L(λ, T) = 2hc² / λ⁵ / (exp(hc/(λkT)) − 1). Returns W·m⁻²·sr⁻¹·nm⁻¹.\n */\nexport function calculatePlanckianSpectralRadiance(input: { temperatureKelvin: number; wavelengthNanometers: number }): number {\n  requireInputKeys(input, \"calculatePlanckianSpectralRadiance\", [\"temperatureKelvin\", \"wavelengthNanometers\"]);\n  const t = requirePositiveNumber(input.temperatureKelvin, \"temperatureKelvin\");\n  const nm = requirePositiveNumber(input.wavelengthNanometers, \"wavelengthNanometers\");\n  const lambda = nm * 1e-9;\n  const exponent = SECOND_RADIATION_CONSTANT_METER_KELVIN / (lambda * t);\n  // expm1 keeps precision in the Rayleigh–Jeans limit; overflow gives radiance 0.\n  const radiancePerMeter = FIRST_RADIATION_CONSTANT_RADIANCE / lambda ** 5 / Math.expm1(exponent);\n  return radiancePerMeter * 1e-9;\n}\n\n/** Planckian spectral radiance (W·m⁻²·sr⁻¹·nm⁻¹) as a function spectrum over the given range. */\nexport function createPlanckianSpectrum(input: { temperatureKelvin: number; wavelengthRangeNanometers: SpectralWavelengthRangeNanometers }): ColorimetricSpectrum {\n  requireInputKeys(input, \"createPlanckianSpectrum\", [\"temperatureKelvin\", \"wavelengthRangeNanometers\"]);\n  const temperatureKelvin = requirePositiveNumber(input.temperatureKelvin, \"temperatureKelvin\");\n  const range = requireRecordValue(input.wavelengthRangeNanometers, \"wavelengthRangeNanometers\");\n  rejectUnknownFields(range, [\"minimum\", \"maximum\"], \"wavelengthRangeNanometers\");\n  const spectrum: ColorimetricSpectrum = {\n    kind: \"function\",\n    wavelengthRangeNanometers: { minimum: range.minimum as number, maximum: range.maximum as number },\n    evaluate: (wavelengthNanometers) => calculatePlanckianSpectralRadiance({ temperatureKelvin, wavelengthNanometers })\n  };\n  prepareColorimetricSpectrum(spectrum, \"planckianSpectrum\");\n  return spectrum;\n}\n\n/** CIE illuminant A defining range (nm). */\nexport const CIE_ILLUMINANT_A_RANGE_NANOMETERS = Object.freeze({ minimum: 300, maximum: 830 });\n\n/**\n * CIE standard illuminant A relative SPD from its defining formula (100 at 560 nm),\n * with c₂ = 1.435e-2 m·K and T = 2848 K as in the standard (≈ 2856 K with the\n * current c₂). Valid 300–830 nm.\n */\nexport function calculateCieIlluminantARelativeSpectralPower(wavelengthNanometers: number): number {\n  const nm = requireFiniteNumber(wavelengthNanometers, \"wavelengthNanometers\");\n  if (nm < CIE_ILLUMINANT_A_RANGE_NANOMETERS.minimum || nm > CIE_ILLUMINANT_A_RANGE_NANOMETERS.maximum) {\n    throw new InvalidScientificInputError(\"CIE illuminant A is defined from 300 nm to 830 nm.\");\n  }\n  const c = 1.435e7 / 2848; // nm·K / K\n  return 100 * (560 / nm) ** 5 * (Math.expm1(c / 560) / Math.expm1(c / nm));\n}\n\n/** CIE illuminant A as a function spectrum over its defining range. */\nexport function createCieIlluminantASpectrum(): ColorimetricSpectrum {\n  return { kind: \"function\", wavelengthRangeNanometers: { ...CIE_ILLUMINANT_A_RANGE_NANOMETERS }, evaluate: calculateCieIlluminantARelativeSpectralPower };\n}\n\nfunction requireTemperatureIn(t: unknown, range: { minimum: number; maximum: number }, what: string): number {\n  const value = requirePositiveNumber(t, what);\n  if (value < range.minimum || value > range.maximum) {\n    throw new InvalidScientificInputError(what + \" must lie in [\" + range.minimum + \", \" + range.maximum + \"] K.\");\n  }\n  return value;\n}\n\nfunction daylightChromaticity(t: number): CieXyChromaticity {\n  const x = t <= 7000\n    ? -4.6070e9 / t ** 3 + 2.9678e6 / t ** 2 + 0.09911e3 / t + 0.244063\n    : -2.0064e9 / t ** 3 + 1.9018e6 / t ** 2 + 0.24748e3 / t + 0.237040;\n  return { x, y: -3.000 * x * x + 2.870 * x - 0.275 };\n}\n\nexport interface CieDaylightComponentWeights {\n  correlatedColorTemperatureKelvin: number;\n  chromaticity: CieXyChromaticity;\n  m1: number;\n  m2: number;\n  coefficientRounding: \"none\" | \"cie-three-decimals\";\n}\n\n/**\n * CIE daylight-locus chromaticity and S₁/S₂ weights for a CCT in 4000–25000 K\n * (CIE 15:2018 §4.1.2, paid; no free text of the formulas found). M₁, M₂ rounded to three decimals\n * reproduce the free CIE D55 and D65 tables (DOI 10.25039/CIE.DS.qewfb3kp, 10.25039/CIE.DS.hjfjmt59)\n * to their rounding; `coefficientRounding` makes that rounding explicit.\n * The temperature is used as given: D65's nominal 6500 K corresponds to 6504 K here.\n */\nexport function calculateCieDaylightComponentWeights(input: {\n  correlatedColorTemperatureKelvin: number;\n  coefficientRounding: \"none\" | \"cie-three-decimals\";\n}): CalculationResult<CieDaylightComponentWeights> {\n  requireInputKeys(input, \"calculateCieDaylightComponentWeights\", [\"correlatedColorTemperatureKelvin\", \"coefficientRounding\"]);\n  const t = requireTemperatureIn(input.correlatedColorTemperatureKelvin, CIE_DAYLIGHT_LOCUS_RANGE_KELVIN, \"correlatedColorTemperatureKelvin\");\n  if (input.coefficientRounding !== \"none\" && input.coefficientRounding !== \"cie-three-decimals\") {\n    throw new InvalidConfigurationError(\"coefficientRounding must be \\\"none\\\" or \\\"cie-three-decimals\\\".\");\n  }\n  const xy = daylightChromaticity(t);\n  const m = 0.0241 + 0.2562 * xy.x - 0.7341 * xy.y;\n  let m1 = (-1.3515 - 1.7703 * xy.x + 5.9114 * xy.y) / m;\n  let m2 = (0.0300 - 31.4424 * xy.x + 30.0717 * xy.y) / m;\n  if (input.coefficientRounding === \"cie-three-decimals\") {\n    m1 = Math.round(m1 * 1000) / 1000;\n    m2 = Math.round(m2 * 1000) / 1000;\n  }\n  return calculatedResult({ correlatedColorTemperatureKelvin: t, chromaticity: xy, m1, m2, coefficientRounding: input.coefficientRounding },\n    \"cie-daylight-locus\", COLORIMETRY_MODEL_VERSION, [\"CIE daylight-locus polynomial and M1/M2 weights, checked against the free CIE D55 and D65 datasets (no free formula text found); valid 4000–25000 K\"]);\n}\n\n/** Caller-supplied CIE daylight basis S₀, S₁, S₂ (tabulated; CIE dataset not bundled). */\nexport interface CieDaylightBasis {\n  s0: readonly ColorimetricSpectralSample[];\n  s1: readonly ColorimetricSpectralSample[];\n  s2: readonly ColorimetricSpectralSample[];\n  /** Caller identity of the basis dataset (for example a DOI). */\n  datasetId: string;\n}\n\n/**\n * Builds a CIE D-series relative SPD S(λ) = S₀ + M₁S₁ + M₂S₂ on the S₀ wavelengths from\n * caller-supplied basis tables (S₁, S₂ linearly interpolated; fail closed outside range).\n */\nexport function createCieDaylightSpectrum(input: {\n  correlatedColorTemperatureKelvin: number;\n  coefficientRounding: \"none\" | \"cie-three-decimals\";\n  basis: CieDaylightBasis;\n}): ColorimetricSpectrum {\n  requireInputKeys(input, \"createCieDaylightSpectrum\", [\"correlatedColorTemperatureKelvin\", \"coefficientRounding\", \"basis\"]);\n  const weights = calculateCieDaylightComponentWeights({\n    correlatedColorTemperatureKelvin: input.correlatedColorTemperatureKelvin,\n    coefficientRounding: input.coefficientRounding\n  }).value;\n  const basis = requireRecordValue(input.basis, \"basis\");\n  rejectUnknownFields(basis, [\"s0\", \"s1\", \"s2\", \"datasetId\"], \"basis\");\n  if (typeof basis.datasetId !== \"string\" || basis.datasetId.trim().length === 0) {\n    throw new InvalidConfigurationError(\"basis.datasetId must be a non-empty string.\");\n  }\n  const s0 = prepareColorimetricSpectrum({ kind: \"tabulated\", samples: input.basis.s0 }, \"basis.s0\");\n  const s1 = prepareColorimetricSpectrum({ kind: \"tabulated\", samples: input.basis.s1 }, \"basis.s1\");\n  const s2 = prepareColorimetricSpectrum({ kind: \"tabulated\", samples: input.basis.s2 }, \"basis.s2\");\n  const samples = input.basis.s0.map((sample) => {\n    const w = sample.wavelengthNanometers;\n    return { wavelengthNanometers: w, value: s0.evaluate(w) + weights.m1 * s1.evaluate(w) + weights.m2 * s2.evaluate(w) };\n  });\n  return { kind: \"tabulated\", samples };\n}\n\n/** Selects how the Planckian locus is evaluated. */\nexport type PlanckianLocusModel =\n  | {\n      /** Planck's law integrated against the engine's analytic CIE 1931 CMFs, 1 nm nodes 360–830 nm (the default). */\n      kind: \"planck-analytic-cmf\";\n    }\n  | {\n      kind: \"planck-integration\";\n      colorMatchingFunctions: ColorMatchingFunctionsSource;\n      quadratureNodes: readonly ColorimetricQuadratureNode[];\n    };\n\n/** Number of intervals of the coarse reciprocal-temperature scan that brackets the CCT search. */\nconst CCT_SCAN_STEPS = 200;\n/**\n * Convergence tolerance of the CCT root-find: it stops once a Newton (or bisection) step changes T by\n * at most this fraction of T (1e-6 K at 10000 K).\n */\nconst CCT_RELATIVE_TOLERANCE = 1e-10;\n\n/**\n * Locus uv and its first and second derivatives with respect to the reciprocal temperature x = 1/T\n * (K⁻¹), from the analytic derivatives of Planck's law integrated in the locus quadrature.\n */\ninterface LocusSample {\n  u: number;\n  v: number;\n  du: number;\n  dv: number;\n  d2u: number;\n  d2v: number;\n}\n\ninterface PreparedLocus {\n  range: { minimum: number; maximum: number };\n  approximation: boolean;\n  model: string;\n  chromaticity(t: number): CieXyChromaticity;\n  /** uv and its x = 1/T derivatives at reciprocal temperature x. */\n  sample(x: number): LocusSample;\n  /** CIE 1960 uv at the coarse scan temperatures; computed once per prepared locus. */\n  scan(): readonly Cie1960UvChromaticity[];\n}\n\n/**\n * Prepares a Planck-integration locus: the CMF values and 1/λ⁵ factors are sampled once, so each\n * temperature costs one exponential per node. Planck's constant factor 2hc² cancels in chromaticity.\n *\n * Derivatives: with x = 1/T, aᵢ = c₂/λᵢ and rᵢ = 1/(exp(aᵢx) − 1), Planck's law is proportional to\n * λᵢ⁻⁵ rᵢ, and exactly dr/dx = −a(r + r²) and d²r/dx² = a²(r + 3r² + 2r³) (differentiate\n * r = 1/(E − 1), E = exp(ax), and use E = 1 + 1/r). They are summed in the same quadrature as X, Y, Z.\n */\nfunction preparePlanckIntegrationLocus(cmfSource: ColorMatchingFunctionsSource, quadratureNodes: readonly ColorimetricQuadratureNode[], model: string): PreparedLocus {\n  const cmf = prepareColorMatchingFunctions(cmfSource);\n  const unit = prepareColorimetricSpectrum({ kind: \"function\", wavelengthRangeNanometers: cmf.wavelengthRangeNanometers, evaluate: () => 1 });\n  const basis = sampleColorimetricBasis(quadratureNodes, unit, cmf);\n  const n = basis.nodes.length;\n  const exponentPerKelvin = new Float64Array(n), inverseFifth = new Float64Array(n);\n  // Per-node constants of the derivative sums: weight × CMF × λ⁻⁵ for X, Y and Z.\n  const wx = new Float64Array(n), wy = new Float64Array(n), wz = new Float64Array(n);\n  for (let i = 0; i < n; i++) {\n    const lambda = basis.nodes[i]!.wavelengthNanometers * 1e-9;\n    exponentPerKelvin[i] = SECOND_RADIATION_CONSTANT_METER_KELVIN / lambda;\n    inverseFifth[i] = 1 / lambda ** 5;\n    const w = basis.weights[i]! * inverseFifth[i]!;\n    wx[i] = w * basis.xBar[i]!; wy[i] = w * basis.yBar[i]!; wz[i] = w * basis.zBar[i]!;\n  }\n  const factor = new Float64Array(n);\n  const range = PLANCKIAN_LOCUS_RANGE_KELVIN;\n  let scanCache: readonly Cie1960UvChromaticity[] | undefined;\n  const locus: PreparedLocus = {\n    range,\n    approximation: cmf.scientificStatus === \"approximation\",\n    model,\n    chromaticity(t: number): CieXyChromaticity {\n      // expm1 keeps precision at long wavelengths; overflow at short ones gives 0, as in Planck's law.\n      for (let i = 0; i < n; i++) factor[i] = inverseFifth[i]! / Math.expm1(exponentPerKelvin[i]! / t);\n      return chromaticityOfXyz(integrateSampledXyz(basis, factor));\n    },\n    sample(x: number): LocusSample {\n      let sx = 0, sy = 0, sz = 0, sx1 = 0, sy1 = 0, sz1 = 0, sx2 = 0, sy2 = 0, sz2 = 0;\n      for (let i = 0; i < n; i++) {\n        const a = exponentPerKelvin[i]!;\n        // An overflowing expm1 gives r = 0 and zero derivatives, the exact limit.\n        const r = 1 / Math.expm1(a * x), r2 = r * r;\n        const q1 = r + r2, k1 = -a * q1, k2 = a * a * (q1 + 2 * r2 * (1 + r));\n        const cx = wx[i]!, cy = wy[i]!, cz = wz[i]!;\n        sx += cx * r; sy += cy * r; sz += cz * r;\n        sx1 += cx * k1; sy1 += cy * k1; sz1 += cz * k1;\n        sx2 += cx * k2; sy2 += cy * k2; sz2 += cz * k2;\n      }\n      // u = 4X/d, v = 6Y/d, d = X + 15Y + 3Z; quotient rule: q' = (N' − q d')/d, q'' = (N'' − 2q'd' − q d'')/d.\n      const d = sx + 15 * sy + 3 * sz, d1 = sx1 + 15 * sy1 + 3 * sz1, d2 = sx2 + 15 * sy2 + 3 * sz2;\n      if (!(d > 0) || !Number.isFinite(d)) throw new InvalidScientificInputError(\"Chromaticity requires X + Y + Z > 0.\");\n      const u = (4 * sx) / d, v = (6 * sy) / d;\n      const du = (4 * sx1 - u * d1) / d, dv = (6 * sy1 - v * d1) / d;\n      return { u, v, du, dv, d2u: (4 * sx2 - 2 * du * d1 - u * d2) / d, d2v: (6 * sy2 - 2 * dv * d1 - v * d2) / d };\n    },\n    scan(): readonly Cie1960UvChromaticity[] {\n      if (scanCache === undefined) {\n        const lo = 1e6 / range.maximum, hi = 1e6 / range.minimum;\n        scanCache = Array.from({ length: CCT_SCAN_STEPS + 1 }, (_, i) => uvOfChromaticity(locus.chromaticity(1e6 / (lo + ((hi - lo) * i) / CCT_SCAN_STEPS))));\n      }\n      return scanCache;\n    }\n  };\n  return locus;\n}\n\n/** 1 nm nodes at 360, 361, …, 830 nm with Δλ = 1 nm (the CIE 15 summation convention). */\nconst DEFAULT_LOCUS_NODES: readonly ColorimetricQuadratureNode[] = Object.freeze(\n  Array.from({ length: 471 }, (_, i) => Object.freeze({ wavelengthNanometers: 360 + i, wavelengthMeasureNanometers: 1 }))\n);\nlet defaultLocus: PreparedLocus | undefined;\n\n/** The default locus, prepared on first use and shared (its scan cache is computed once). */\nfunction analyticCmfLocus(): PreparedLocus {\n  defaultLocus ??= preparePlanckIntegrationLocus({ kind: \"analytic-cie-1931-multi-lobe-fit\" }, DEFAULT_LOCUS_NODES, \"planck-analytic-cmf\");\n  return defaultLocus;\n}\n\n/**\n * Planckian-locus chromaticity at T (1000–100000 K): Planck's law integrated against the engine's\n * analytic CIE 1931 CMFs with 1 nm nodes from 360 to 830 nm. An approximation, because the CMFs are\n * an analytic fit; with tabulated CMFs use {@link calculatePlanckianChromaticity}.\n */\nexport function estimatePlanckianLocusChromaticity(input: { temperatureKelvin: number }): CalculationResult<CieXyChromaticity> {\n  requireInputKeys(input, \"estimatePlanckianLocusChromaticity\", [\"temperatureKelvin\"]);\n  const t = requireTemperatureIn(input.temperatureKelvin, PLANCKIAN_LOCUS_RANGE_KELVIN, \"temperatureKelvin\");\n  return approximationResult(analyticCmfLocus().chromaticity(t), \"planckian-locus-planck-analytic-cmf\", COLORIMETRY_MODEL_VERSION,\n    [\"Planck's law integrated against the engine's analytic CIE 1931 CMF fit, 1 nm nodes 360–830 nm; valid 1000–100000 K\"]);\n}\n\nfunction prepareLocus(model: PlanckianLocusModel): PreparedLocus {\n  const record = requireRecordValue(model, \"locus\");\n  if (record.kind === \"planck-analytic-cmf\") {\n    rejectUnknownFields(record, [\"kind\"], \"locus\");\n    return analyticCmfLocus();\n  }\n  if (record.kind !== \"planck-integration\") throw new InvalidConfigurationError(\"locus.kind is not supported.\");\n  rejectUnknownFields(record, [\"kind\", \"colorMatchingFunctions\", \"quadratureNodes\"], \"locus\");\n  const m = model as Extract<PlanckianLocusModel, { kind: \"planck-integration\" }>;\n  const cmf = prepareColorMatchingFunctions(m.colorMatchingFunctions);\n  return preparePlanckIntegrationLocus(m.colorMatchingFunctions, m.quadratureNodes, \"planck-integration-\" + cmf.sourceKind);\n}\n\n/** Planckian chromaticity at T using either locus model. */\nexport function calculatePlanckianChromaticity(input: { temperatureKelvin: number; locus: PlanckianLocusModel }): CalculationResult<CieXyChromaticity> {\n  requireInputKeys(input, \"calculatePlanckianChromaticity\", [\"temperatureKelvin\", \"locus\"]);\n  const locus = prepareLocus(input.locus);\n  const t = requireTemperatureIn(input.temperatureKelvin, locus.range, \"temperatureKelvin\");\n  const value = locus.chromaticity(t);\n  const assumptions = [\"Planckian locus model: \" + locus.model];\n  return locus.approximation\n    ? approximationResult(value, \"planckian-chromaticity\", COLORIMETRY_MODEL_VERSION, assumptions)\n    : calculatedResult(value, \"planckian-chromaticity\", COLORIMETRY_MODEL_VERSION, assumptions);\n}\n\n/**\n * McCamy (1992) cubic estimate of CCT from CIE 1931 xy:\n * n = (x − 0.3320)/(0.1858 − y), CCT = 449 n³ + 3525 n² + 6823.3 n + 5520.33.\n * An approximation that carries no Duv. Measured for this engine (October 17, 2026) on points of a\n * Planckian locus integrated from the CIE 1931 2° 1 nm table (360–830 nm, exact c₂): it deviates by up\n * 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\n * and 442 K at 12500 K. See docs/COLORIMETRY.md.\n */\nexport function estimateCorrelatedColorTemperatureMcCamy(input: { chromaticity: CieXyChromaticity }): CalculationResult<{ correlatedColorTemperatureKelvin: number }> {\n  requireInputKeys(input, \"estimateCorrelatedColorTemperatureMcCamy\", [\"chromaticity\"]);\n  const xy = parseChromaticity(input.chromaticity, \"chromaticity\");\n  const n = (xy.x - 0.3320) / (0.1858 - xy.y);\n  const cct = 449 * n ** 3 + 3525 * n ** 2 + 6823.3 * n + 5520.33;\n  if (!Number.isFinite(cct) || cct <= 0) throw new InvalidScientificInputError(\"Chromaticity is outside the McCamy approximation domain.\");\n  return approximationResult({ correlatedColorTemperatureKelvin: cct }, \"cct-mccamy-1992\", COLORIMETRY_MODEL_VERSION,\n    [\"McCamy (1992) cubic; intended for chromaticities near the Planckian locus, about 2000–12500 K\"]);\n}\n\n/** The \"above-locus\" unit normal at a sample: the increasing-T unit tangent (−du/dx, −dv/dx) turned by −90°. */\nfunction locusNormal(s: LocusSample): Cie1960UvChromaticity {\n  const len = Math.hypot(s.du, s.dv);\n  const tangent = { u: -s.du / len, v: -s.dv / len };\n  // u decreases as T rises, so turning the tangent by −90° points toward larger v (above the locus).\n  return { u: tangent.v, v: -tangent.u };\n}\n\n/**\n * Nearest locus point to `target` in CIE 1960 uv: the root of the derivative of the squared distance\n * F = (u − u₀)² + (v − v₀)². Roots of dF/dT and of dF/dx (x = 1/T) coincide, since dx/dT = −1/T² ≠ 0;\n * the root-find runs in x with g = ½ dF/dx = (u − u₀)u′ + (v − v₀)v′ and\n * g′ = u′² + v′² + (u − u₀)u″ + (v − v₀)v″ (analytic, see {@link preparePlanckIntegrationLocus}).\n * The cached coarse scan brackets the minimum; a Newton step falls back to bisection whenever it would\n * leave the bracket. Returns the root and the locus sample there, or undefined when the nearest point\n * lies beyond the model's range (by more than the tolerance).\n */\nfunction nearestLocusPoint(locus: PreparedLocus, target: Cie1960UvChromaticity): { x: number; sample: LocusSample } | undefined {\n  const steps = CCT_SCAN_STEPS;\n  const lo = 1e6 / locus.range.maximum, hi = 1e6 / locus.range.minimum, step = (hi - lo) / steps;\n  const gridX = (i: number): number => (lo + step * i) * 1e-6;\n  const scan = locus.scan();\n  const f = (i: number): number => (scan[i]!.u - target.u) ** 2 + (scan[i]!.v - target.v) ** 2;\n  let best = 0, bestValue = Infinity;\n  for (let i = 0; i <= steps; i++) {\n    const value = f(i);\n    if (value < bestValue) { bestValue = value; best = i; }\n  }\n  const tolerance = (x: number): number => CCT_RELATIVE_TOLERANCE * x;\n  const derivatives = (s: LocusSample): { g: number; gp: number } => {\n    const eu = s.u - target.u, ev = s.v - target.v;\n    return { g: eu * s.du + ev * s.dv, gp: s.du * s.du + s.dv * s.dv + eu * s.d2u + ev * s.d2v };\n  };\n  let a: number, b: number, x: number;\n  if (best === 0 || best === steps) {\n    // The scan minimum is a range limit: the nearest point is inside only if F still falls inward.\n    x = gridX(best);\n    const s = locus.sample(x), { g, gp } = derivatives(s);\n    if (best === 0 ? g >= 0 : g <= 0) {\n      // At the limit within the tolerance (one Newton step estimates the distance), or beyond it.\n      return g === 0 || (gp > 0 && Math.abs(g / gp) <= tolerance(x)) ? { x, sample: s } : undefined;\n    }\n    a = best === 0 ? x : gridX(steps - 1);\n    b = best === 0 ? gridX(1) : x;\n  } else {\n    // A discrete minimum between its neighbours brackets a local minimum; start at the parabola vertex.\n    a = gridX(best - 1); b = gridX(best + 1);\n    const fm = f(best - 1), fp = f(best + 1), curvature = fm - 2 * bestValue + fp;\n    x = gridX(best) + (curvature > 0 ? (step * 1e-6 * (fm - fp)) / (2 * curvature) : 0);\n  }\n  let s = locus.sample(x);\n  for (let i = 0; i < 100; i++) {\n    const { g, gp } = derivatives(s);\n    if (g === 0) break;\n    if (g < 0) a = x; else b = x;\n    let next = x - g / gp;\n    if (!(gp > 0) || !(next > a && next < b)) next = 0.5 * (a + b);\n    const converged = Math.abs(next - x) <= tolerance(next) || b - a <= tolerance(next);\n    x = next;\n    s = locus.sample(x);\n    if (converged) break;\n  }\n  return { x, sample: s };\n}\n\nexport interface CorrelatedColorTemperatureResult {\n  correlatedColorTemperatureKelvin: number;\n  /** Signed CIE 1960 uv distance from the locus; positive above (greenish), negative below (the engine's convention). */\n  duv: number;\n}\n\n/**\n * CCT and Duv of a chromaticity as the nearest point of the Planckian locus in the CIE\n * 1960 UCS (Smet et al. 2023; also CIE 15:2018). Finds the root of the analytic temperature derivative\n * of the squared uv distance (safeguarded Newton with bisection fallback, bracketed by a cached coarse\n * scan in reciprocal temperature), converged until a step changes T by at most 1e-10 of T. Throws\n * (fails closed) when the nearest point lies beyond the model's range, or when |Duv| > 0.05 (see\n * {@link MAX_CORRELATED_COLOR_TEMPERATURE_DUV}). Duv is positive above the locus (toward green) and\n * negative below it, the engine's documented sign convention.\n */\nexport function calculateCorrelatedColorTemperature(input: { chromaticity: CieXyChromaticity; locus: PlanckianLocusModel }): CalculationResult<CorrelatedColorTemperatureResult> {\n  requireInputKeys(input, \"calculateCorrelatedColorTemperature\", [\"chromaticity\", \"locus\"]);\n  const xy = parseChromaticity(input.chromaticity, \"chromaticity\");\n  const locus = prepareLocus(input.locus);\n  const target = uvOfChromaticity(xy);\n  const nearest = nearestLocusPoint(locus, target);\n  if (nearest === undefined) throw new InvalidScientificInputError(\"Chromaticity's nearest Planckian point lies outside the locus model range.\");\n  const t = Math.min(locus.range.maximum, Math.max(locus.range.minimum, 1 / nearest.x));\n  const point = nearest.sample, normal = locusNormal(point);\n  const duv = (target.u - point.u) * normal.u + (target.v - point.v) * normal.v;\n  if (Math.abs(duv) > MAX_CORRELATED_COLOR_TEMPERATURE_DUV) {\n    throw new InvalidScientificInputError(\"|Duv| exceeds 0.05; no CCT is reported this far from the Planckian locus (the range evaluated by Smet et al. 2023).\");\n  }\n  const value = { correlatedColorTemperatureKelvin: t, duv };\n  const assumptions = [\"Nearest point on the Planckian locus in CIE 1960 uv; locus model: \" + locus.model, \"Duv sign: positive above the locus (toward green), negative below (engine convention)\"];\n  return locus.approximation\n    ? approximationResult(value, \"cct-duv-locus-search\", COLORIMETRY_MODEL_VERSION, assumptions)\n    : calculatedResult(value, \"cct-duv-locus-search\", COLORIMETRY_MODEL_VERSION, assumptions);\n}\n\n/** Locus whose temperature defines a white for CCT + Duv. */\nexport type WhiteLocus = \"planckian\" | \"cie-daylight\";\n\n/**\n * Chromaticity for CCT and Duv: the locus point (Planckian or CIE daylight) offset by\n * Duv along the unit normal of the Planckian locus at the same temperature in the CIE\n * 1960 UCS. For `cie-daylight`, Duv = 0 returns the daylight-locus point itself.\n * Throws InvalidScientificInputError when the offset point is not a physical chromaticity\n * (x ≥ 0, y > 0, x + y ≤ 1), for example 2000 K with Duv +0.02 (x + y ≈ 1.06).\n */\nexport function calculateChromaticityFromCorrelatedColorTemperature(input: {\n  correlatedColorTemperatureKelvin: number;\n  duv: number;\n  whiteLocus: WhiteLocus;\n  locus: PlanckianLocusModel;\n}): CalculationResult<CieXyChromaticity> {\n  requireInputKeys(input, \"calculateChromaticityFromCorrelatedColorTemperature\", [\"correlatedColorTemperatureKelvin\", \"duv\", \"whiteLocus\", \"locus\"]);\n  const locus = prepareLocus(input.locus);\n  const duv = requireFiniteNumber(input.duv, \"duv\");\n  if (Math.abs(duv) > MAX_CORRELATED_COLOR_TEMPERATURE_DUV) throw new InvalidScientificInputError(\"|duv| must not exceed 0.05.\");\n  if (input.whiteLocus !== \"planckian\" && input.whiteLocus !== \"cie-daylight\") throw new InvalidConfigurationError(\"whiteLocus is not supported.\");\n  const range = input.whiteLocus === \"cie-daylight\"\n    ? { minimum: Math.max(locus.range.minimum, CIE_DAYLIGHT_LOCUS_RANGE_KELVIN.minimum), maximum: Math.min(locus.range.maximum, CIE_DAYLIGHT_LOCUS_RANGE_KELVIN.maximum) }\n    : locus.range;\n  const t = requireTemperatureIn(input.correlatedColorTemperatureKelvin, range, \"correlatedColorTemperatureKelvin\");\n  const normal = locusNormal(locus.sample(1 / t));\n  const base = uvOfChromaticity(input.whiteLocus === \"cie-daylight\" ? daylightChromaticity(t) : locus.chromaticity(t));\n  const value = chromaticityOfUv({ u: base.u + duv * normal.u, v: base.v + duv * normal.v });\n  // The same domain parseChromaticity enforces on input, so every result can be passed back in.\n  if (!(value.x >= 0) || !(value.y > 0) || !(value.x + value.y <= 1)) {\n    throw new InvalidScientificInputError(\"correlatedColorTemperatureKelvin and duv give a chromaticity outside x >= 0, y > 0, x + y <= 1.\");\n  }\n  const assumptions = [\"White locus: \" + input.whiteLocus + \"; Duv offset along the Planckian-locus normal (\" + locus.model + \") in CIE 1960 uv\"];\n  const exactDaylightPoint = input.whiteLocus === \"cie-daylight\" && duv === 0;\n  return locus.approximation && !exactDaylightPoint\n    ? approximationResult(value, \"chromaticity-from-cct-duv\", COLORIMETRY_MODEL_VERSION, assumptions)\n    : calculatedResult(value, \"chromaticity-from-cct-duv\", COLORIMETRY_MODEL_VERSION, assumptions);\n}\n"]}

package/dist/color/rgb-color-spaces.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Wide-gamut output primitives (standalone; output wiring belongs to the SDR/export stages):
+ * - RGB ↔ XYZ matrices derived numerically from primary and white chromaticities: RGB (1, 1, 1)
+ *   is the white (W3C CSS Color 4 §2, free), never copied matrices. They equal the CSS Color 4
+ *   sample-code matrices to about 1e-15 (test/colorimetry-output-and-camera.test.ts).
+ *   sRGB / BT.709: ITU-R BT.709-6 and W3C CSS Color 4 `srgb` (also IEC 61966-2-1:1999); Display P3:
+ *   P3 primaries with D65 white as specified for `display-p3` in W3C CSS Color 4 (also SMPTE EG 432-1:2010);
+ *   BT.2020: ITU-R BT.2020-2. All use D65 (0.3127, 0.3290).
+ * - Transfer functions: sRGB (W3C CSS Color 4; also IEC 61966-2-1; also Display P3), BT.709 OETF, BT.1886 EOTF
+ *   (ITU-R BT.1886). The BT.2100 PQ and HLG transfer functions are not part of 2.0 (owner decision,
+ *   2026-10-17: their patent holders offer only licence-on-request declarations; see THIRD_PARTY.md).
+ * Constants are the published values of those standards.
+ * @see docs/COLORIMETRY.md for equations, coordinate/unit conventions and limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type CieXyChromaticity, type CieXyzTristimulus, type ColorMatrix3x3 } from "./colorimetry-math.js";
+/** RGB primaries as CIE 1931 xy chromaticities. */
+export interface RgbPrimaryChromaticities {
+    red: CieXyChromaticity;
+    green: CieXyChromaticity;
+    blue: CieXyChromaticity;
+}
+export interface RgbToXyzMatrices {
+    /** Linear RGB (white = 1, 1, 1) → XYZ with white Y = 1. */
+    rgbToXyz: ColorMatrix3x3;
+    xyzToRgb: ColorMatrix3x3;
+    whiteXyz: CieXyzTristimulus;
+}
+/** Internal: derivation from primaries and white (see {@link calculateRgbToXyzMatrices}) without an envelope. */
+export declare function rgbToXyzMatrices(primaries: RgbPrimaryChromaticities, white: CieXyChromaticity): RgbToXyzMatrices;
+/**
+ * Derives RGB ↔ XYZ matrices from primaries and white chromaticity: columns are the primaries'
+ * XYZ (Y = 1) scaled so that RGB (1, 1, 1) maps to the white (W3C CSS Color 4, free; also SMPTE
+ * RP 177). The derivation is written out in docs/COLORIMETRY.md.
+ */
+export declare function calculateRgbToXyzMatrices(input: {
+    primaries: RgbPrimaryChromaticities;
+    whiteChromaticity: CieXyChromaticity;
+}): CalculationResult<RgbToXyzMatrices>;
+export type RgbColorSpaceId = "srgb" | "display-p3" | "rec709" | "rec2020";
+export type RgbTransferFunctionId = "srgb" | "bt709-oetf-bt1886-eotf" | "bt2020-oetf";
+export interface RgbColorSpaceDefinition extends RgbToXyzMatrices {
+    id: RgbColorSpaceId;
+    primaries: RgbPrimaryChromaticities;
+    whiteChromaticity: CieXyChromaticity;
+    /** Conventional non-linear (SDR) encoding of this space. */
+    transferFunction: RgbTransferFunctionId;
+    sources: readonly string[];
+}
+/** Resolves a named RGB colour space with numerically derived matrices (all D65). */
+export declare function resolveRgbColorSpace(id: RgbColorSpaceId): CalculationResult<RgbColorSpaceDefinition>;
+/** sRGB / Display P3 encoding (W3C CSS Color 4; also IEC 61966-2-1) of one linear component; negative values use the linear segment. */
+export declare function evaluateSrgbEncoding(linear: number): number;
+/** sRGB / Display P3 decoding of one non-linear component. */
+export declare function evaluateSrgbDecoding(encoded: number): number;
+/**
+ * ITU-R BT.709-6 / BT.2020-2 (10-bit) OETF: V = 4.5 L for L < 0.018, otherwise
+ * 1.099 L^0.45 − 0.099. Scene-referred camera encoding, not a display EOTF.
+ */
+export declare function evaluateBt709Oetf(sceneLinear: number): number;
+/** Inverse of the BT.709 OETF: L = V/4.5 for V < 0.081, otherwise ((V + 0.099)/1.099)^(1/0.45). */
+export declare function evaluateBt709InverseOetf(encoded: number): number;
+export interface Bt1886Eotf {
+    whiteLuminanceCdPerSquareMeter: number;
+    blackLuminanceCdPerSquareMeter: number;
+    /** a = (Lw^(1/γ) − Lb^(1/γ))^γ */
+    a: number;
+    /** b = Lb^(1/γ) / (Lw^(1/γ) − Lb^(1/γ)) */
+    b: number;
+    /** L = a · max(V + b, 0)^2.4 in cd/m². */
+    decode(signal: number): number;
+    /** Inverse: V = (L/a)^(1/2.4) − b. */
+    encode(luminanceCdPerSquareMeter: number): number;
+}
+/** Prepares the ITU-R BT.1886 reference EOTF (γ = 2.4) for a display's white and black luminance. */
+export declare function prepareBt1886Eotf(input: {
+    whiteLuminanceCdPerSquareMeter: number;
+    blackLuminanceCdPerSquareMeter: number;
+}): Bt1886Eotf;