@photivra/engine 1.5.0 → 2.1.0

package/dist/color/color-difference.js

@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CIELAB / CIELCh(ab) conversions and colour-difference formulae.
+ *
+ * - CIELAB (W3C CSS Color 4 Lab; also CIE 15:2018 §8.2.1) with the exact rational constants ε = (6/29)³ and
+ *   κ = (29/3)³ in the linear segment.
+ * - ΔE*ab 1976: Euclidean CIELAB distance.
+ * - ΔE*94: asymmetric (first colour is the reference: S_L = 1, S_C = 1 + K₁C*₁, S_H = 1 + K₂C*₁). The
+ *   default is the formula's published reference conditions (k_L = k_C = k_H = 1, K₁ = 0.045,
+ *   K₂ = 0.015, often called "graphic arts"); callers may pass their own factors in `cie94Factors`.
+ *   The engine ships no other preset. The primary source, CIE 116-1995, is not free. The tests check
+ *   the closed forms for pure lightness, chroma and hue differences and the reference asymmetry.
+ * - CIEDE2000, implemented from the formula and implementation notes in Sharma, Wu & Dalal
+ *   (2005), Color Res. Appl. 30(1):21–30 (paper free at
+ *   https://hajim.rochester.edu/ece/sites/gsharma/ciede2000/; also CIE 142-2001, ISO/CIE 11664-6).
+ *   This includes the hue-angle averaging and the handling of the hue discontinuity. The tests check
+ *   its closed forms for pure lightness, chroma and hue differences (computed in the test), symmetry
+ *   and identity; the published test pairs are not used (their data file has no licence).
+ * @see docs/COLORIMETRY.md for equations, coordinate/unit conventions and limits.
+ */
+import { calculatedResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { COLORIMETRY_MODEL_VERSION } from "./color-matching-functions.js";
+import { parseWhiteXyz, parseXyz, requireFiniteNumber, requireFiniteResult, requireNonNegativeNumber, requirePositiveNumber, requireRecordValue } from "./colorimetry-math.js";
+import { rejectUnknownFields, requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+const EPSILON = (6 / 29) ** 3;
+const KAPPA = (29 / 3) ** 3;
+function f(t) {
+    return t > EPSILON ? Math.cbrt(t) : (KAPPA * t + 16) / 116;
+}
+function fInverse(t) {
+    return t > 6 / 29 ? t ** 3 : (116 * t - 16) / KAPPA;
+}
+/** Internal: XYZ → CIELAB with a validated white (no envelope). */
+export function cielabOfXyz(xyz, white) {
+    const fx = f(xyz.x / white.x), fy = f(xyz.y / white.y), fz = f(xyz.z / white.z);
+    return { lStar: 116 * fy - 16, aStar: 500 * (fx - fy), bStar: 200 * (fy - fz) };
+}
+/** Internal: CIELAB → XYZ. */
+export function xyzOfCielab(lab, white) {
+    const fy = (lab.lStar + 16) / 116, fx = fy + lab.aStar / 500, fz = fy - lab.bStar / 200;
+    return { x: white.x * fInverse(fx), y: white.y * fInverse(fy), z: white.z * fInverse(fz) };
+}
+function parseLab(value, path) {
+    const r = requireRecordValue(value, path);
+    rejectUnknownFields(r, ["lStar", "aStar", "bStar"], path);
+    return { lStar: requireFiniteNumber(r.lStar, path + ".lStar"), aStar: requireFiniteNumber(r.aStar, path + ".aStar"), bStar: requireFiniteNumber(r.bStar, path + ".bStar") };
+}
+function parseWhite(value) {
+    const w = parseWhiteXyz(value, "referenceWhiteXyz");
+    if (!(w.x > 0) || !(w.z > 0))
+        throw new InvalidScientificInputError("referenceWhiteXyz components must be greater than zero.");
+    return w;
+}
+/** CIE XYZ → CIELAB relative to a reference white (same XYZ scale). */
+export function calculateCielabFromXyz(input) {
+    requireInputKeys(input, "calculateCielabFromXyz", ["xyz", "referenceWhiteXyz"]);
+    const lab = cielabOfXyz(parseXyz(input.xyz, "xyz"), parseWhite(input.referenceWhiteXyz));
+    requireFiniteResult([lab.lStar, lab.aStar, lab.bStar], "CIELAB conversion");
+    return calculatedResult(lab, "cielab-1976", COLORIMETRY_MODEL_VERSION, ["CIELAB as defined in W3C CSS Color 4 (Lab) with exact (6/29)³ and (29/3)³ constants"]);
+}
+/** CIELAB → CIE XYZ relative to a reference white. */
+export function calculateXyzFromCielab(input) {
+    requireInputKeys(input, "calculateXyzFromCielab", ["lab", "referenceWhiteXyz"]);
+    const xyz = xyzOfCielab(parseLab(input.lab, "lab"), parseWhite(input.referenceWhiteXyz));
+    requireFiniteResult([xyz.x, xyz.y, xyz.z], "CIELAB inverse");
+    return calculatedResult(xyz, "cielab-1976-inverse", COLORIMETRY_MODEL_VERSION, ["CIELAB inverse as defined in W3C CSS Color 4 (Lab)"]);
+}
+/** Internal: CIELAB → LCh(ab). */
+export function cielchOfCielab(lab) {
+    const hue = (Math.atan2(lab.bStar, lab.aStar) * 180) / Math.PI;
+    return { lStar: lab.lStar, chromaStar: Math.hypot(lab.aStar, lab.bStar), hueDegrees: hue < 0 ? hue + 360 : hue };
+}
+/** Internal: LCh(ab) → CIELAB. */
+export function cielabOfCielch(lch) {
+    const h = (lch.hueDegrees * Math.PI) / 180;
+    return { lStar: lch.lStar, aStar: lch.chromaStar * Math.cos(h), bStar: lch.chromaStar * Math.sin(h) };
+}
+/** CIELAB → CIE LCh(ab): C*ab = √(a*² + b*²), h_ab = atan2(b*, a*) in degrees. */
+export function calculateCielchFromCielab(input) {
+    requireInputKeys(input, "calculateCielchFromCielab", ["lab"]);
+    return calculatedResult(cielchOfCielab(parseLab(input.lab, "lab")), "cielch-ab", COLORIMETRY_MODEL_VERSION);
+}
+/** CIE LCh(ab) → CIELAB. */
+export function calculateCielabFromCielch(input) {
+    requireInputKeys(input, "calculateCielabFromCielch", ["lch"]);
+    const r = requireRecordValue(input.lch, "lch");
+    rejectUnknownFields(r, ["lStar", "chromaStar", "hueDegrees"], "lch");
+    const lch = {
+        lStar: requireFiniteNumber(r.lStar, "lch.lStar"),
+        chromaStar: requireFiniteNumber(r.chromaStar, "lch.chromaStar"),
+        hueDegrees: requireFiniteNumber(r.hueDegrees, "lch.hueDegrees")
+    };
+    if (lch.chromaStar < 0)
+        throw new InvalidScientificInputError("lch.chromaStar must not be negative.");
+    return calculatedResult(cielabOfCielch(lch), "cielch-ab-inverse", COLORIMETRY_MODEL_VERSION);
+}
+/** CIE94 reference conditions (k_L = k_C = k_H = 1, K₁ = 0.045, K₂ = 0.015). */
+const CIE94_REFERENCE_FACTORS = { lightness: 1, chroma: 1, hue: 1, k1: 0.045, k2: 0.015 };
+const DEG = Math.PI / 180;
+/** Internal: ΔE*ab 1976. */
+export function deltaE76(a, b) {
+    return Math.hypot(a.lStar - b.lStar, a.aStar - b.aStar, a.bStar - b.bStar);
+}
+/** Internal: ΔE*94 with reference colour `reference`. */
+export function deltaE94(reference, sample, factors = CIE94_REFERENCE_FACTORS) {
+    const { lightness: kL, chroma: kC, hue: kH, k1, k2 } = factors;
+    const c1 = Math.hypot(reference.aStar, reference.bStar), c2 = Math.hypot(sample.aStar, sample.bStar);
+    const dL = reference.lStar - sample.lStar, dC = c1 - c2;
+    const da = reference.aStar - sample.aStar, db = reference.bStar - sample.bStar;
+    const dH2 = Math.max(0, da * da + db * db - dC * dC);
+    const sC = 1 + k1 * c1, sH = 1 + k2 * c1;
+    return Math.sqrt((dL / kL) ** 2 + (dC / (kC * sC)) ** 2 + dH2 / (kH * sH) ** 2);
+}
+function hueDegrees(b, a) {
+    if (a === 0 && b === 0)
+        return 0;
+    const h = Math.atan2(b, a) / DEG;
+    return h < 0 ? h + 360 : h;
+}
+/** Internal: CIEDE2000 (Sharma, Wu & Dalal 2005 implementation notes). */
+export function deltaE2000(lab1, lab2, k = { lightness: 1, chroma: 1, hue: 1 }) {
+    const pow25to7 = 25 ** 7;
+    const c1 = Math.hypot(lab1.aStar, lab1.bStar), c2 = Math.hypot(lab2.aStar, lab2.bStar);
+    const cBar7 = ((c1 + c2) / 2) ** 7;
+    const g = 0.5 * (1 - Math.sqrt(cBar7 / (cBar7 + pow25to7)));
+    const a1 = (1 + g) * lab1.aStar, a2 = (1 + g) * lab2.aStar;
+    const cp1 = Math.hypot(a1, lab1.bStar), cp2 = Math.hypot(a2, lab2.bStar);
+    const hp1 = hueDegrees(lab1.bStar, a1), hp2 = hueDegrees(lab2.bStar, a2);
+    const dL = lab2.lStar - lab1.lStar, dC = cp2 - cp1;
+    const chromaProduct = cp1 * cp2;
+    let dh = 0;
+    if (chromaProduct !== 0) {
+        dh = hp2 - hp1;
+        if (dh > 180)
+            dh -= 360;
+        else if (dh < -180)
+            dh += 360;
+    }
+    const dH = 2 * Math.sqrt(chromaProduct) * Math.sin((dh * DEG) / 2);
+    const lBar = (lab1.lStar + lab2.lStar) / 2, cBarP = (cp1 + cp2) / 2;
+    let hBar = hp1 + hp2;
+    if (chromaProduct !== 0) {
+        if (Math.abs(hp1 - hp2) <= 180)
+            hBar /= 2;
+        else
+            hBar = hBar < 360 ? (hBar + 360) / 2 : (hBar - 360) / 2;
+    }
+    const t = 1 - 0.17 * Math.cos((hBar - 30) * DEG) + 0.24 * Math.cos(2 * hBar * DEG) + 0.32 * Math.cos((3 * hBar + 6) * DEG) - 0.20 * Math.cos((4 * hBar - 63) * DEG);
+    const dTheta = 30 * Math.exp(-(((hBar - 275) / 25) ** 2));
+    const cBarP7 = cBarP ** 7;
+    const rC = 2 * Math.sqrt(cBarP7 / (cBarP7 + pow25to7));
+    const l50 = (lBar - 50) ** 2;
+    const sL = 1 + (0.015 * l50) / Math.sqrt(20 + l50), sC = 1 + 0.045 * cBarP, sH = 1 + 0.015 * cBarP * t;
+    const rT = -Math.sin(2 * dTheta * DEG) * rC;
+    const tl = dL / (k.lightness * sL), tc = dC / (k.chroma * sC), th = dH / (k.hue * sH);
+    return Math.sqrt(Math.max(0, tl * tl + tc * tc + th * th + rT * tc * th));
+}
+function parseCie94Factors(value) {
+    const r = requireRecordValue(value, "cie94Factors");
+    requireInputKeys(r, "calculateColorDifference cie94Factors", ["lightness", "chroma", "hue", "k1", "k2"]);
+    return {
+        lightness: requirePositiveNumber(r.lightness, "cie94Factors.lightness"),
+        chroma: requirePositiveNumber(r.chroma, "cie94Factors.chroma"),
+        hue: requirePositiveNumber(r.hue, "cie94Factors.hue"),
+        k1: requireNonNegativeNumber(r.k1, "cie94Factors.k1"),
+        k2: requireNonNegativeNumber(r.k2, "cie94Factors.k2")
+    };
+}
+/** Colour difference between two CIELAB colours with an explicit formula. */
+export function calculateColorDifference(input) {
+    requireInputKeys(input, "calculateColorDifference", ["reference", "sample", "formula", "parametricFactors", "cie94Factors"]);
+    const reference = parseLab(input.reference, "reference");
+    const sample = parseLab(input.sample, "sample");
+    let deltaE;
+    switch (input.formula) {
+        case "cie76":
+            deltaE = deltaE76(reference, sample);
+            break;
+        case "cie94":
+            deltaE = deltaE94(reference, sample, input.cie94Factors === undefined ? undefined : parseCie94Factors(input.cie94Factors));
+            break;
+        case "ciede2000": {
+            let k;
+            if (input.parametricFactors !== undefined) {
+                const r = requireRecordValue(input.parametricFactors, "parametricFactors");
+                requireInputKeys(r, "calculateColorDifference parametricFactors", ["lightness", "chroma", "hue"]);
+                k = { lightness: requirePositiveNumber(r.lightness, "parametricFactors.lightness"), chroma: requirePositiveNumber(r.chroma, "parametricFactors.chroma"), hue: requirePositiveNumber(r.hue, "parametricFactors.hue") };
+            }
+            deltaE = deltaE2000(reference, sample, k);
+            break;
+        }
+        default: throw new InvalidConfigurationError("formula is not supported.");
+    }
+    requireFiniteResult([deltaE], "Colour difference");
+    if (input.formula !== "ciede2000" && input.parametricFactors !== undefined) {
+        throw new InvalidScientificInputError("parametricFactors apply only to CIEDE2000.");
+    }
+    if (input.formula !== "cie94" && input.cie94Factors !== undefined) {
+        throw new InvalidScientificInputError("cie94Factors apply only to CIE94.");
+    }
+    return calculatedResult({ deltaE, formula: input.formula }, "color-difference-" + input.formula, COLORIMETRY_MODEL_VERSION);
+}
+//# sourceMappingURL=color-difference.js.map

package/dist/color/color-difference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-difference.js","sourceRoot":"","sources":["../../src/color/color-difference.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * CIELAB / CIELCh(ab) conversions and colour-difference formulae.\n *\n * - CIELAB (W3C CSS Color 4 Lab; also CIE 15:2018 §8.2.1) with the exact rational constants ε = (6/29)³ and\n *   κ = (29/3)³ in the linear segment.\n * - ΔE*ab 1976: Euclidean CIELAB distance.\n * - ΔE*94: asymmetric (first colour is the reference: S_L = 1, S_C = 1 + K₁C*₁, S_H = 1 + K₂C*₁). The\n *   default is the formula's published reference conditions (k_L = k_C = k_H = 1, K₁ = 0.045,\n *   K₂ = 0.015, often called \"graphic arts\"); callers may pass their own factors in `cie94Factors`.\n *   The engine ships no other preset. The primary source, CIE 116-1995, is not free. The tests check\n *   the closed forms for pure lightness, chroma and hue differences and the reference asymmetry.\n * - CIEDE2000, implemented from the formula and implementation notes in Sharma, Wu & Dalal\n *   (2005), Color Res. Appl. 30(1):21–30 (paper free at\n *   https://hajim.rochester.edu/ece/sites/gsharma/ciede2000/; also CIE 142-2001, ISO/CIE 11664-6).\n *   This includes the hue-angle averaging and the handling of the hue discontinuity. The tests check\n *   its closed forms for pure lightness, chroma and hue differences (computed in the test), symmetry\n *   and identity; the published test pairs are not used (their data file has no licence).\n * @see docs/COLORIMETRY.md for equations, coordinate/unit conventions and limits.\n */\n\nimport { calculatedResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { COLORIMETRY_MODEL_VERSION } from \"./color-matching-functions.js\";\nimport {\n  parseWhiteXyz,\n  parseXyz,\n  requireFiniteNumber,\n  requireFiniteResult,\n  requireNonNegativeNumber,\n  requirePositiveNumber,\n  requireRecordValue,\n  type CieXyzTristimulus\n} from \"./colorimetry-math.js\";\nimport { rejectUnknownFields, requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\n/** CIE 1976 L*a*b* coordinates. */\nexport interface CielabColor {\n  lStar: number;\n  aStar: number;\n  bStar: number;\n}\n\n/** CIE 1976 L*C*h(ab) coordinates; hue in degrees [0, 360). */\nexport interface CielchColor {\n  lStar: number;\n  chromaStar: number;\n  hueDegrees: number;\n}\n\nconst EPSILON = (6 / 29) ** 3;\nconst KAPPA = (29 / 3) ** 3;\n\nfunction f(t: number): number {\n  return t > EPSILON ? Math.cbrt(t) : (KAPPA * t + 16) / 116;\n}\nfunction fInverse(t: number): number {\n  return t > 6 / 29 ? t ** 3 : (116 * t - 16) / KAPPA;\n}\n\n/** Internal: XYZ → CIELAB with a validated white (no envelope). */\nexport function cielabOfXyz(xyz: CieXyzTristimulus, white: CieXyzTristimulus): CielabColor {\n  const fx = f(xyz.x / white.x), fy = f(xyz.y / white.y), fz = f(xyz.z / white.z);\n  return { lStar: 116 * fy - 16, aStar: 500 * (fx - fy), bStar: 200 * (fy - fz) };\n}\n\n/** Internal: CIELAB → XYZ. */\nexport function xyzOfCielab(lab: CielabColor, white: CieXyzTristimulus): CieXyzTristimulus {\n  const fy = (lab.lStar + 16) / 116, fx = fy + lab.aStar / 500, fz = fy - lab.bStar / 200;\n  return { x: white.x * fInverse(fx), y: white.y * fInverse(fy), z: white.z * fInverse(fz) };\n}\n\nfunction parseLab(value: unknown, path: string): CielabColor {\n  const r = requireRecordValue(value, path);\n  rejectUnknownFields(r, [\"lStar\", \"aStar\", \"bStar\"], path);\n  return { lStar: requireFiniteNumber(r.lStar, path + \".lStar\"), aStar: requireFiniteNumber(r.aStar, path + \".aStar\"), bStar: requireFiniteNumber(r.bStar, path + \".bStar\") };\n}\n\nfunction parseWhite(value: unknown): CieXyzTristimulus {\n  const w = parseWhiteXyz(value, \"referenceWhiteXyz\");\n  if (!(w.x > 0) || !(w.z > 0)) throw new InvalidScientificInputError(\"referenceWhiteXyz components must be greater than zero.\");\n  return w;\n}\n\n/** CIE XYZ → CIELAB relative to a reference white (same XYZ scale). */\nexport function calculateCielabFromXyz(input: { xyz: CieXyzTristimulus; referenceWhiteXyz: CieXyzTristimulus }): CalculationResult<CielabColor> {\n  requireInputKeys(input, \"calculateCielabFromXyz\", [\"xyz\", \"referenceWhiteXyz\"]);\n  const lab = cielabOfXyz(parseXyz(input.xyz, \"xyz\"), parseWhite(input.referenceWhiteXyz));\n  requireFiniteResult([lab.lStar, lab.aStar, lab.bStar], \"CIELAB conversion\");\n  return calculatedResult(lab, \"cielab-1976\", COLORIMETRY_MODEL_VERSION, [\"CIELAB as defined in W3C CSS Color 4 (Lab) with exact (6/29)³ and (29/3)³ constants\"]);\n}\n\n/** CIELAB → CIE XYZ relative to a reference white. */\nexport function calculateXyzFromCielab(input: { lab: CielabColor; referenceWhiteXyz: CieXyzTristimulus }): CalculationResult<CieXyzTristimulus> {\n  requireInputKeys(input, \"calculateXyzFromCielab\", [\"lab\", \"referenceWhiteXyz\"]);\n  const xyz = xyzOfCielab(parseLab(input.lab, \"lab\"), parseWhite(input.referenceWhiteXyz));\n  requireFiniteResult([xyz.x, xyz.y, xyz.z], \"CIELAB inverse\");\n  return calculatedResult(xyz, \"cielab-1976-inverse\", COLORIMETRY_MODEL_VERSION, [\"CIELAB inverse as defined in W3C CSS Color 4 (Lab)\"]);\n}\n\n/** Internal: CIELAB → LCh(ab). */\nexport function cielchOfCielab(lab: CielabColor): CielchColor {\n  const hue = (Math.atan2(lab.bStar, lab.aStar) * 180) / Math.PI;\n  return { lStar: lab.lStar, chromaStar: Math.hypot(lab.aStar, lab.bStar), hueDegrees: hue < 0 ? hue + 360 : hue };\n}\n\n/** Internal: LCh(ab) → CIELAB. */\nexport function cielabOfCielch(lch: CielchColor): CielabColor {\n  const h = (lch.hueDegrees * Math.PI) / 180;\n  return { lStar: lch.lStar, aStar: lch.chromaStar * Math.cos(h), bStar: lch.chromaStar * Math.sin(h) };\n}\n\n/** CIELAB → CIE LCh(ab): C*ab = √(a*² + b*²), h_ab = atan2(b*, a*) in degrees. */\nexport function calculateCielchFromCielab(input: { lab: CielabColor }): CalculationResult<CielchColor> {\n  requireInputKeys(input, \"calculateCielchFromCielab\", [\"lab\"]);\n  return calculatedResult(cielchOfCielab(parseLab(input.lab, \"lab\")), \"cielch-ab\", COLORIMETRY_MODEL_VERSION);\n}\n\n/** CIE LCh(ab) → CIELAB. */\nexport function calculateCielabFromCielch(input: { lch: CielchColor }): CalculationResult<CielabColor> {\n  requireInputKeys(input, \"calculateCielabFromCielch\", [\"lch\"]);\n  const r = requireRecordValue(input.lch, \"lch\");\n  rejectUnknownFields(r, [\"lStar\", \"chromaStar\", \"hueDegrees\"], \"lch\");\n  const lch = {\n    lStar: requireFiniteNumber(r.lStar, \"lch.lStar\"),\n    chromaStar: requireFiniteNumber(r.chromaStar, \"lch.chromaStar\"),\n    hueDegrees: requireFiniteNumber(r.hueDegrees, \"lch.hueDegrees\")\n  };\n  if (lch.chromaStar < 0) throw new InvalidScientificInputError(\"lch.chromaStar must not be negative.\");\n  return calculatedResult(cielabOfCielch(lch), \"cielch-ab-inverse\", COLORIMETRY_MODEL_VERSION);\n}\n\n/** Colour-difference formula. */\nexport type ColorDifferenceFormula = \"cie76\" | \"cie94\" | \"ciede2000\";\n\n/** CIEDE2000 parametric factors (default 1, 1, 1 for reference conditions). */\nexport interface Ciede2000ParametricFactors {\n  lightness: number;\n  chroma: number;\n  hue: number;\n}\n\n/**\n * CIE94 parametric factors k_L, k_C, k_H and weighting constants K₁, K₂ (S_C = 1 + K₁C*₁,\n * S_H = 1 + K₂C*₁). The default is the reference conditions: 1, 1, 1, 0.045, 0.015.\n */\nexport interface Cie94ParametricFactors {\n  /** k_L, greater than zero. */\n  lightness: number;\n  /** k_C, greater than zero. */\n  chroma: number;\n  /** k_H, greater than zero. */\n  hue: number;\n  /** K₁ in S_C = 1 + K₁C*₁; finite and not negative. */\n  k1: number;\n  /** K₂ in S_H = 1 + K₂C*₁; finite and not negative. */\n  k2: number;\n}\n\n/** CIE94 reference conditions (k_L = k_C = k_H = 1, K₁ = 0.045, K₂ = 0.015). */\nconst CIE94_REFERENCE_FACTORS: Cie94ParametricFactors = { lightness: 1, chroma: 1, hue: 1, k1: 0.045, k2: 0.015 };\n\nconst DEG = Math.PI / 180;\n\n/** Internal: ΔE*ab 1976. */\nexport function deltaE76(a: CielabColor, b: CielabColor): number {\n  return Math.hypot(a.lStar - b.lStar, a.aStar - b.aStar, a.bStar - b.bStar);\n}\n\n/** Internal: ΔE*94 with reference colour `reference`. */\nexport function deltaE94(reference: CielabColor, sample: CielabColor, factors: Cie94ParametricFactors = CIE94_REFERENCE_FACTORS): number {\n  const { lightness: kL, chroma: kC, hue: kH, k1, k2 } = factors;\n  const c1 = Math.hypot(reference.aStar, reference.bStar), c2 = Math.hypot(sample.aStar, sample.bStar);\n  const dL = reference.lStar - sample.lStar, dC = c1 - c2;\n  const da = reference.aStar - sample.aStar, db = reference.bStar - sample.bStar;\n  const dH2 = Math.max(0, da * da + db * db - dC * dC);\n  const sC = 1 + k1 * c1, sH = 1 + k2 * c1;\n  return Math.sqrt((dL / kL) ** 2 + (dC / (kC * sC)) ** 2 + dH2 / (kH * sH) ** 2);\n}\n\nfunction hueDegrees(b: number, a: number): number {\n  if (a === 0 && b === 0) return 0;\n  const h = Math.atan2(b, a) / DEG;\n  return h < 0 ? h + 360 : h;\n}\n\n/** Internal: CIEDE2000 (Sharma, Wu & Dalal 2005 implementation notes). */\nexport function deltaE2000(lab1: CielabColor, lab2: CielabColor, k: Ciede2000ParametricFactors = { lightness: 1, chroma: 1, hue: 1 }): number {\n  const pow25to7 = 25 ** 7;\n  const c1 = Math.hypot(lab1.aStar, lab1.bStar), c2 = Math.hypot(lab2.aStar, lab2.bStar);\n  const cBar7 = ((c1 + c2) / 2) ** 7;\n  const g = 0.5 * (1 - Math.sqrt(cBar7 / (cBar7 + pow25to7)));\n  const a1 = (1 + g) * lab1.aStar, a2 = (1 + g) * lab2.aStar;\n  const cp1 = Math.hypot(a1, lab1.bStar), cp2 = Math.hypot(a2, lab2.bStar);\n  const hp1 = hueDegrees(lab1.bStar, a1), hp2 = hueDegrees(lab2.bStar, a2);\n  const dL = lab2.lStar - lab1.lStar, dC = cp2 - cp1;\n  const chromaProduct = cp1 * cp2;\n  let dh = 0;\n  if (chromaProduct !== 0) {\n    dh = hp2 - hp1;\n    if (dh > 180) dh -= 360;\n    else if (dh < -180) dh += 360;\n  }\n  const dH = 2 * Math.sqrt(chromaProduct) * Math.sin((dh * DEG) / 2);\n  const lBar = (lab1.lStar + lab2.lStar) / 2, cBarP = (cp1 + cp2) / 2;\n  let hBar = hp1 + hp2;\n  if (chromaProduct !== 0) {\n    if (Math.abs(hp1 - hp2) <= 180) hBar /= 2;\n    else hBar = hBar < 360 ? (hBar + 360) / 2 : (hBar - 360) / 2;\n  }\n  const t = 1 - 0.17 * Math.cos((hBar - 30) * DEG) + 0.24 * Math.cos(2 * hBar * DEG) + 0.32 * Math.cos((3 * hBar + 6) * DEG) - 0.20 * Math.cos((4 * hBar - 63) * DEG);\n  const dTheta = 30 * Math.exp(-(((hBar - 275) / 25) ** 2));\n  const cBarP7 = cBarP ** 7;\n  const rC = 2 * Math.sqrt(cBarP7 / (cBarP7 + pow25to7));\n  const l50 = (lBar - 50) ** 2;\n  const sL = 1 + (0.015 * l50) / Math.sqrt(20 + l50), sC = 1 + 0.045 * cBarP, sH = 1 + 0.015 * cBarP * t;\n  const rT = -Math.sin(2 * dTheta * DEG) * rC;\n  const tl = dL / (k.lightness * sL), tc = dC / (k.chroma * sC), th = dH / (k.hue * sH);\n  return Math.sqrt(Math.max(0, tl * tl + tc * tc + th * th + rT * tc * th));\n}\n\nexport interface CalculateColorDifferenceInput {\n  /** Reference (standard) colour; ΔE94 is asymmetric in it. */\n  reference: CielabColor;\n  sample: CielabColor;\n  formula: ColorDifferenceFormula;\n  /** CIEDE2000 only; defaults to 1, 1, 1. */\n  parametricFactors?: Ciede2000ParametricFactors;\n  /** CIE94 only; all five fields are required when given. Defaults to the reference conditions 1, 1, 1, 0.045, 0.015. */\n  cie94Factors?: Cie94ParametricFactors;\n}\n\nfunction parseCie94Factors(value: unknown): Cie94ParametricFactors {\n  const r = requireRecordValue(value, \"cie94Factors\");\n  requireInputKeys(r, \"calculateColorDifference cie94Factors\", [\"lightness\", \"chroma\", \"hue\", \"k1\", \"k2\"]);\n  return {\n    lightness: requirePositiveNumber(r.lightness, \"cie94Factors.lightness\"),\n    chroma: requirePositiveNumber(r.chroma, \"cie94Factors.chroma\"),\n    hue: requirePositiveNumber(r.hue, \"cie94Factors.hue\"),\n    k1: requireNonNegativeNumber(r.k1, \"cie94Factors.k1\"),\n    k2: requireNonNegativeNumber(r.k2, \"cie94Factors.k2\")\n  };\n}\n\n/** Colour difference between two CIELAB colours with an explicit formula. */\nexport function calculateColorDifference(input: CalculateColorDifferenceInput): CalculationResult<{ deltaE: number; formula: ColorDifferenceFormula }> {\n  requireInputKeys(input, \"calculateColorDifference\", [\"reference\", \"sample\", \"formula\", \"parametricFactors\", \"cie94Factors\"]);\n  const reference = parseLab(input.reference, \"reference\");\n  const sample = parseLab(input.sample, \"sample\");\n  let deltaE: number;\n  switch (input.formula) {\n    case \"cie76\": deltaE = deltaE76(reference, sample); break;\n    case \"cie94\": deltaE = deltaE94(reference, sample, input.cie94Factors === undefined ? undefined : parseCie94Factors(input.cie94Factors)); break;\n    case \"ciede2000\": {\n      let k: Ciede2000ParametricFactors | undefined;\n      if (input.parametricFactors !== undefined) {\n        const r = requireRecordValue(input.parametricFactors, \"parametricFactors\");\n        requireInputKeys(r, \"calculateColorDifference parametricFactors\", [\"lightness\", \"chroma\", \"hue\"]);\n        k = { lightness: requirePositiveNumber(r.lightness, \"parametricFactors.lightness\"), chroma: requirePositiveNumber(r.chroma, \"parametricFactors.chroma\"), hue: requirePositiveNumber(r.hue, \"parametricFactors.hue\") };\n      }\n      deltaE = deltaE2000(reference, sample, k);\n      break;\n    }\n    default: throw new InvalidConfigurationError(\"formula is not supported.\");\n  }\n  requireFiniteResult([deltaE], \"Colour difference\");\n  if (input.formula !== \"ciede2000\" && input.parametricFactors !== undefined) {\n    throw new InvalidScientificInputError(\"parametricFactors apply only to CIEDE2000.\");\n  }\n  if (input.formula !== \"cie94\" && input.cie94Factors !== undefined) {\n    throw new InvalidScientificInputError(\"cie94Factors apply only to CIE94.\");\n  }\n  return calculatedResult({ deltaE, formula: input.formula }, \"color-difference-\" + input.formula, COLORIMETRY_MODEL_VERSION);\n}\n"]}

package/dist/color/color-matching-functions.d.ts

@@ -0,0 +1,168 @@
+/**
+ * CIE colour-matching functions (CMFs) and spectrum → CIE XYZ integration.
+ *
+ * Two CMF sources are supported:
+ * 1. The engine's own analytic APPROXIMATION of the CIE 1931 2° observer. Each of x̄, ȳ, z̄ is a sum
+ *    of split Gaussian lobes (a lobe has an amplitude, a centre, and separate widths below and above
+ *    the centre): three lobes for x̄, two each for ȳ and z̄. The engine fitted the coefficients itself
+ *    by non-negative least squares to the CIE 1931 2° table (DOI 10.25039/CIE.DS.xvudnb9b) at 1 nm
+ *    from 360 to 830 nm, with `scripts/fit-cie-1931-cmf.mjs`. The table is used only when the fit is
+ *    run and is not stored in the repository. Measured fit error (maximum absolute / RMS): x̄ 0.0122 /
+ *    0.00426, ȳ 0.00733 / 0.00265, z̄ 0.0221 / 0.00397; see docs/COLORIMETRY.md.
+ * 2. Caller-supplied tabulated CMFs, for example the official CIE datasets. The CIE
+ *    distributes those under CC BY-SA 4.0, so they are NOT bundled with this Apache-2.0
+ *    package. Tables are linearly interpolated. Outside their declared range they throw
+ *    (fail closed); there is no extrapolation.
+ *
+ * Integration uses explicit wavelength quadrature nodes `{wavelengthNanometers,
+ * wavelengthMeasureNanometers}`. Nodes from `calculateSensorSpectralQuadrature()` have the
+ * same shape and can be passed directly. X = k Σ S(λᵢ) R(λᵢ) x̄(λᵢ) Δλᵢ: a quadrature of the tristimulus
+ * integral X = ∫ L(λ) x̄(λ) dλ with stimulus L = S·R (Wyman, Sloan & Shirley 2013, JCGT 2(2), Eq. 1, free;
+ * also CIE 15:2018 §7.1). The normalization k and the quadrature nodes are explicit choices.
+ * @see docs/COLORIMETRY.md for equations, coordinate/unit conventions and limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import type { SpectralWavelengthRangeNanometers, SpectralWavelengthSample } from "../core/spectral.js";
+import { type CieXyChromaticity, type CieXyzTristimulus } from "./colorimetry-math.js";
+export declare const COLORIMETRY_MODEL_VERSION: "2.0.0";
+/** Upper bound on quadrature nodes per integration call. */
+export declare const MAX_COLORIMETRIC_QUADRATURE_NODES = 100000;
+/** Upper bound on samples in a caller-supplied tabulated spectrum or CMF table. */
+export declare const MAX_COLORIMETRIC_TABLE_SAMPLES = 100000;
+/** Wavelength domain over which the analytic CIE 1931 fit is accepted (the domain it was fitted on). */
+export declare const ANALYTIC_CIE_1931_CMF_DOMAIN_NANOMETERS: Readonly<SpectralWavelengthRangeNanometers>;
+/** One wavelength quadrature node; d-lambda is in nanometres. */
+export interface ColorimetricQuadratureNode {
+    wavelengthNanometers: number;
+    wavelengthMeasureNanometers: number;
+}
+/** One tabulated spectral value at one wavelength. */
+export interface ColorimetricSpectralSample extends SpectralWavelengthSample {
+    value: number;
+}
+/**
+ * A spectral distribution or spectral factor (reflectance, transmittance, relative SPD,
+ * sensitivity).
+ * - `tabulated` is the JSON form: strictly increasing wavelengths, linear interpolation, and an
+ *   error (fail closed) outside the table.
+ * - `function` is an in-process evaluator (for example a Planckian SPD). It must be finite over
+ *   its declared range.
+ */
+export type ColorimetricSpectrum = {
+    kind: "tabulated";
+    samples: readonly ColorimetricSpectralSample[];
+} | {
+    kind: "function";
+    wavelengthRangeNanometers: SpectralWavelengthRangeNanometers;
+    evaluate: (wavelengthNanometers: number) => number;
+};
+/** One tabulated colour-matching sample. */
+export interface TabulatedColorMatchingSample extends SpectralWavelengthSample {
+    xBar: number;
+    yBar: number;
+    zBar: number;
+}
+export type ColorimetricObserver = "cie-1931-2-degree" | "cie-1964-10-degree" | "caller-defined";
+/** Selects a colour-matching-function source. */
+export type ColorMatchingFunctionsSource = {
+    kind: "analytic-cie-1931-multi-lobe-fit";
+} | {
+    kind: "tabulated";
+    observer: ColorimetricObserver;
+    /** Caller identity for the dataset (for example a DOI); recorded in provenance. */
+    datasetId: string;
+    samples: readonly TabulatedColorMatchingSample[];
+};
+/** Validated, reusable colour-matching functions. */
+export interface PreparedColorMatchingFunctions {
+    observer: ColorimetricObserver;
+    sourceKind: ColorMatchingFunctionsSource["kind"];
+    datasetId: string;
+    scientificStatus: "approximation" | "caller-tabulated";
+    wavelengthRangeNanometers: SpectralWavelengthRangeNanometers;
+    /** x̄, ȳ, z̄ at one wavelength in nm; throws outside the declared range. */
+    evaluate(wavelengthNanometers: number): CieXyzTristimulus;
+}
+/**
+ * Evaluates the engine's multi-lobe analytic approximation of the CIE 1931 2° colour-matching
+ * functions at one wavelength (nm, standard-air wavelength as in the CIE tables). Approximation:
+ * see the module notes for the measured fit error. The values are non-negative over the domain.
+ */
+export declare function estimateCie1931ColorMatchingFunctions(wavelengthNanometers: number): CieXyzTristimulus;
+/**
+ * Validates a colour-matching-function source once for repeated evaluation.
+ * Tabulated values may be signed only for `caller-defined` observers; CIE observers
+ * require non-negative values.
+ */
+export declare function prepareColorMatchingFunctions(source: ColorMatchingFunctionsSource): PreparedColorMatchingFunctions;
+/** A validated spectrum ready for evaluation. */
+export interface PreparedColorimetricSpectrum {
+    wavelengthRangeNanometers: SpectralWavelengthRangeNanometers;
+    evaluate(wavelengthNanometers: number): number;
+}
+/** Validates a tabulated or functional spectrum (values must be finite; sign is not restricted). */
+export declare function prepareColorimetricSpectrum(spectrum: ColorimetricSpectrum, path?: string): PreparedColorimetricSpectrum;
+export interface CreateColorimetricMidpointQuadratureInput {
+    wavelengthRangeNanometers: SpectralWavelengthRangeNanometers;
+    /** Hard upper bound on each midpoint subinterval width, nm. */
+    maximumSubintervalWidthNanometers: number;
+}
+/**
+ * Builds deterministic uniform midpoint wavelength nodes covering the range. Every
+ * node carries its d-lambda measure in nm; the measures sum to the range width.
+ */
+export declare function createColorimetricMidpointQuadrature(input: CreateColorimetricMidpointQuadratureInput): ColorimetricQuadratureNode[];
+/** Validates explicit quadrature nodes (positive wavelengths and positive measures). */
+export declare function parseColorimetricQuadratureNodes(nodes: unknown): ColorimetricQuadratureNode[];
+/**
+ * Normalization of integrated tristimulus values.
+ * - `white-luminance-one`: k = 1 / Σ S ȳ Δλ, so the perfect reflecting diffuser (or the
+ *   illuminant itself) has Y = 1 (relative colorimetry with Y scaled to 1; also CIE 15:2018).
+ * - `scale`: X = factor · Σ …; for example 683.002 lm/W with spectral radiance in
+ *   W·m⁻²·sr⁻¹·nm⁻¹ yields luminance in cd/m² (the caller owns the unit semantics).
+ */
+export type TristimulusNormalization = {
+    kind: "white-luminance-one";
+} | {
+    kind: "scale";
+    factor: number;
+};
+export interface IntegrateSpectrumToXyzInput {
+    quadratureNodes: readonly ColorimetricQuadratureNode[];
+    /** Illuminant SPD or emitted spectral radiance S(λ). */
+    spectralDistribution: ColorimetricSpectrum;
+    /** Optional spectral reflectance/transmittance factor R(λ); omitted means R = 1. */
+    spectralFactor?: ColorimetricSpectrum;
+    colorMatchingFunctions: ColorMatchingFunctionsSource;
+    normalization: TristimulusNormalization;
+}
+export interface IntegratedSpectrumXyz {
+    xyz: CieXyzTristimulus;
+    /** Tristimulus values of S(λ) alone under the same normalization (the adopted white). */
+    whiteXyz: CieXyzTristimulus;
+    chromaticity: CieXyChromaticity | null;
+    normalizationFactor: number;
+    observer: ColorimetricObserver;
+    nodeCount: number;
+}
+/** Internal: per-node weights S·Δλ and CMF values; reused by matrix fitting. */
+export interface SampledColorimetricBasis {
+    nodes: readonly ColorimetricQuadratureNode[];
+    weights: Float64Array;
+    xBar: Float64Array;
+    yBar: Float64Array;
+    zBar: Float64Array;
+    cmf: PreparedColorMatchingFunctions;
+}
+export declare function sampleColorimetricBasis(quadratureNodes: readonly ColorimetricQuadratureNode[], spectralDistribution: PreparedColorimetricSpectrum, cmf: PreparedColorMatchingFunctions): SampledColorimetricBasis;
+export declare function sampleFactor(basis: SampledColorimetricBasis, factor: PreparedColorimetricSpectrum | undefined): Float64Array;
+export declare function integrateSampledXyz(basis: SampledColorimetricBasis, factor: Float64Array): CieXyzTristimulus;
+export declare function resolveNormalizationFactor(normalization: TristimulusNormalization, unnormalizedWhiteY: number): number;
+/**
+ * Integrates a spectrum (optionally multiplied by a reflectance/transmittance factor)
+ * against colour-matching functions with caller-explicit quadrature (the tristimulus integral of
+ * Wyman, Sloan & Shirley 2013, Eq. 1; also CIE 15:2018 §7).
+ * Provenance is `approximation` for the analytic CMF fit and `calculated` for
+ * caller-tabulated CMFs. Either way, the caller chooses the quadrature.
+ */
+export declare function integrateSpectrumToXyz(input: IntegrateSpectrumToXyzInput): CalculationResult<IntegratedSpectrumXyz>;