@photivra/engine 2.12.0 → 2.14.0

package/dist/facade/chart-scenes.js

@@ -2,8 +2,9 @@
 /**
  * Procedural test charts for the capture facade, written for this engine. Every chart is a flat,
  * Lambertian (matte) reflectance pattern, defined by formulas in normalized frame coordinates. No
- * third-party chart data (for example ColorChecker reflectances) is bundled. Coloured patches use
- * spectra that the caller supplies.
+ * third-party chart data (for example ColorChecker reflectances) is bundled. Colored patches use
+ * spectra that the caller supplies or, from 2.14, Photivra's own analytic color patches
+ * (`color-patches.ts`, docs/COLOR_PATCHES.md).
  *
  * Frame coordinates: `u` runs from -1 (left edge of the framed chart) to +1 (right edge); `v` points up
  * and has the same scale, so it runs from -aspect to +aspect where aspect = height/width of the frame.
@@ -23,35 +24,37 @@
  * levels, like the grey ramp: the step (below 0.1 % of the range) is far below sensor noise.
  * @see docs/QUICK_START.md for the chart catalogue and their analytic definitions.
  */
-import { portablePow } from "../core/portable-math.js";
+import { portableExp, portablePow } from "../core/portable-math.js";
 import { InvalidConfigurationError } from "../core/configuration-error.js";
 import { prepareColorimetricSpectrum } from "../color/color-matching-functions.js";
 import { requireInputObject, requireInputKeys } from "../core/record-validation.js";
 import { createDeterministicUniformStream } from "../sensor/stochastic-seed.js";
-export const CHART_SCENE_PRESETS = Object.freeze(["uniform", "slanted-edge", "siemens-star",
+import { COLOR_PATCH_IDS, COLOR_PATCH_SET_ID, COLOR_PATCH_SET_VERSION, findColorPatch, prepareColorPatchSpectrum } from "./color-patches.js";
+export const CHART_SCENE_PRESETS = /* @__PURE__ */ Object.freeze(["uniform", "slanted-edge", "siemens-star",
     "step-wedge", "grey-ramp", "checkerboard", "point-grid", "patches", "dead-leaves", "bar-groups", "hyperbolic-wedge", "zone-plate",
-    "slanted-squares", "line-grid", "fiducial", "composite"]);
+    "slanted-squares", "line-grid", "fiducial", "color-patches", "composite"]);
 /** Neutral levels that represent a continuous pattern (grey ramp; 2.3 sine star, zone plate and dead-leaves greys). */
 export const CHART_CONTINUOUS_LEVELS = 1024;
 /** Engine-chosen chart parameters, each reported when the caller omitted it. */
-export const CHART_SCENE_DEFAULTS = Object.freeze({
-    uniform: Object.freeze({ reflectance: 0.18 }),
-    "slanted-edge": Object.freeze({ angleDegrees: 5, darkReflectance: 0.15, lightReflectance: 0.6 }),
-    "siemens-star": Object.freeze({ cycles: 36, radiusFraction: 0.9, darkReflectance: 0.05, lightReflectance: 0.8, backgroundReflectance: 0.18 }),
-    "step-wedge": Object.freeze({ steps: 11, minimumReflectance: 0.03, maximumReflectance: 0.9, spacing: "equal-density" }),
-    "grey-ramp": Object.freeze({ minimumReflectance: 0.03, maximumReflectance: 0.9 }),
-    checkerboard: Object.freeze({ squaresAcross: 8, darkReflectance: 0.05, lightReflectance: 0.8 }),
-    "point-grid": Object.freeze({ columns: 5, rows: 3, radius: 0.01, pointReflectance: 0.9, backgroundReflectance: 0.02 }),
-    patches: Object.freeze({ gapFraction: 0.1, backgroundReflectance: 0.18 }),
-    "dead-leaves": Object.freeze({ radiusMinimum: 0.01, radiusMaximum: 0.5, minimumReflectance: 0.2, maximumReflectance: 0.6, seed: 1 }),
-    "bar-groups": Object.freeze({ lineWidthsPerPictureHeight: Object.freeze([100, 200, 400, 800]), numerals: true, darkReflectance: 0.05, lightReflectance: 0.8 }),
-    "hyperbolic-wedge": Object.freeze({ orientation: "horizontal", lineCount: 5, minimumLineWidthsPerPictureHeight: 100,
+export const CHART_SCENE_DEFAULTS = /* @__PURE__ */ Object.freeze({
+    uniform: /* @__PURE__ */ Object.freeze({ reflectance: 0.18 }),
+    "slanted-edge": /* @__PURE__ */ Object.freeze({ angleDegrees: 5, darkReflectance: 0.15, lightReflectance: 0.6 }),
+    "siemens-star": /* @__PURE__ */ Object.freeze({ cycles: 36, radiusFraction: 0.9, darkReflectance: 0.05, lightReflectance: 0.8, backgroundReflectance: 0.18 }),
+    "step-wedge": /* @__PURE__ */ Object.freeze({ steps: 11, minimumReflectance: 0.03, maximumReflectance: 0.9, spacing: "equal-density" }),
+    "grey-ramp": /* @__PURE__ */ Object.freeze({ minimumReflectance: 0.03, maximumReflectance: 0.9 }),
+    checkerboard: /* @__PURE__ */ Object.freeze({ squaresAcross: 8, darkReflectance: 0.05, lightReflectance: 0.8 }),
+    "point-grid": /* @__PURE__ */ Object.freeze({ columns: 5, rows: 3, radius: 0.01, pointReflectance: 0.9, backgroundReflectance: 0.02 }),
+    patches: /* @__PURE__ */ Object.freeze({ gapFraction: 0.1, backgroundReflectance: 0.18 }),
+    "dead-leaves": /* @__PURE__ */ Object.freeze({ radiusMinimum: 0.01, radiusMaximum: 0.5, minimumReflectance: 0.2, maximumReflectance: 0.6, seed: 1 }),
+    "bar-groups": /* @__PURE__ */ Object.freeze({ lineWidthsPerPictureHeight: /* @__PURE__ */ Object.freeze([100, 200, 400, 800]), numerals: true, darkReflectance: 0.05, lightReflectance: 0.8 }),
+    "hyperbolic-wedge": /* @__PURE__ */ Object.freeze({ orientation: "horizontal", lineCount: 5, minimumLineWidthsPerPictureHeight: 100,
         maximumLineWidthsPerPictureHeight: 1000, darkReflectance: 0.05, lightReflectance: 0.8 }),
-    "zone-plate": Object.freeze({ radiusFraction: 0.9, maximumCyclesPerPictureHeight: 200, darkReflectance: 0.1, lightReflectance: 0.7, backgroundReflectance: 0.18 }),
-    "slanted-squares": Object.freeze({ columns: 3, rows: 2, sizeFraction: 0.5, angleDegrees: 5, darkReflectance: 0.15, lightReflectance: 0.6 }),
-    "line-grid": Object.freeze({ spacing: 1 / 3, lineWidth: 0.01, lineReflectance: 0.42, backgroundReflectance: 0.6 }),
-    fiducial: Object.freeze({ radiusFraction: 0.8, ringFraction: 0.18, inverted: false, darkReflectance: 0.05, lightReflectance: 0.8, backgroundReflectance: 0.18 }),
-    composite: Object.freeze({ background: Object.freeze({ preset: "uniform", reflectance: 0.18 }) })
+    "zone-plate": /* @__PURE__ */ Object.freeze({ radiusFraction: 0.9, maximumCyclesPerPictureHeight: 200, darkReflectance: 0.1, lightReflectance: 0.7, backgroundReflectance: 0.18 }),
+    "slanted-squares": /* @__PURE__ */ Object.freeze({ columns: 3, rows: 2, sizeFraction: 0.5, angleDegrees: 5, darkReflectance: 0.15, lightReflectance: 0.6 }),
+    "line-grid": /* @__PURE__ */ Object.freeze({ spacing: 1 / 3, lineWidth: 0.01, lineReflectance: 0.42, backgroundReflectance: 0.6 }),
+    fiducial: /* @__PURE__ */ Object.freeze({ radiusFraction: 0.8, ringFraction: 0.18, inverted: false, darkReflectance: 0.05, lightReflectance: 0.8, backgroundReflectance: 0.18 }),
+    "color-patches": /* @__PURE__ */ Object.freeze({ patchIds: COLOR_PATCH_IDS, gapFraction: 0.1, backgroundReflectance: 0.18 }),
+    composite: /* @__PURE__ */ Object.freeze({ background: /* @__PURE__ */ Object.freeze({ preset: "uniform", reflectance: 0.18 }) })
 });
 function reflectance(value, name) {
     if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1)
@@ -69,11 +72,23 @@ function finiteIn(value, name, minimum, maximum, open = false) {
     return value;
 }
 /** Wavelength range every chart spectrum must cover (the facade's sensor quadrature range). */
-export const CHART_SPECTRAL_RANGE_NANOMETERS = Object.freeze({ minimum: 380, maximum: 780 });
-/** Internal: validates a chart reflectance input (a neutral number or a reflectance spectrum covering 380–780 nm) as a material. */
-export function resolveChartMaterial(value, name) {
+export const CHART_SPECTRAL_RANGE_NANOMETERS = /* @__PURE__ */ Object.freeze({ minimum: 380, maximum: 780 });
+/**
+ * Internal: validates a chart reflectance input (a neutral number, a reflectance spectrum covering 380–780 nm or a
+ * built-in color patch) as a material.
+ */
+export function resolveChartMaterial(value, name, exp) {
     if (typeof value === "number")
         return { kind: "neutral", reflectance: reflectance(value, name) };
+    if (typeof value === "object" && value !== null && value.kind === "color-patch") {
+        for (const key of Object.keys(value))
+            if (key !== "kind" && key !== "patchId")
+                throw new InvalidConfigurationError(name + " has unknown field \"" + key + "\".");
+        const patch = findColorPatch(value.patchId);
+        if (!patch)
+            throw new InvalidConfigurationError(name + ".patchId must be one of the built-in color patches (COLOR_PATCH_IDS).");
+        return { kind: "spectrum", spectrum: prepareColorPatchSpectrum(patch, exp) };
+    }
     let spectrum;
     try {
         spectrum = prepareColorimetricSpectrum(value, name);
@@ -88,6 +103,26 @@ export function resolveChartMaterial(value, name) {
         reflectance(spectrum.evaluate(nm), name + " values");
     return { kind: "spectrum", spectrum };
 }
+/** How a uniform chart reports its reflectance: the number, the color-patch record, or `"caller-spectrum"`. */
+function reflectanceReport(raw) {
+    if (typeof raw === "number")
+        return raw;
+    const record = raw;
+    return record.kind === "color-patch" ? { kind: "color-patch", patchId: record.patchId } : "caller-spectrum";
+}
+/** Material at a point of a row-major patch grid (`patches`, 2.14 `color-patches`): a patch index or `backgroundIndex`. */
+function patchGridMaterialAt(columns, rows, count, gap, aspect, backgroundIndex) {
+    const cellW = 2 / columns, cellH = 2 * aspect / rows;
+    return (u, v) => {
+        const fx = (u + 1) / cellW, fy = (aspect - v) / cellH, i = Math.floor(fx), j = Math.floor(fy);
+        if (i < 0 || j < 0 || i >= columns || j >= rows)
+            return backgroundIndex;
+        const index = j * columns + i, x = fx - i, y = fy - j;
+        if (index >= count || x < gap / 2 || x > 1 - gap / 2 || y < gap / 2 || y > 1 - gap / 2)
+            return backgroundIndex;
+        return index;
+    };
+}
 /** Raw caller spectrum inputs per material (undefined for neutral materials), for the facade's scene digest. */
 const MATERIAL_INPUTS = new WeakMap();
 /**
@@ -136,12 +171,13 @@ export function resolveChartScene(input) {
 }
 /**
  * Internal (not exported from the package): {@link resolveChartScene} with the step wedge's geometric levels computed
- * with the portable power (`portablePow`, within 1 ulp) instead of `**`, whose last bit differs between JavaScript
- * engines. Every other value, the geometry and the material order are the same. The display view uses its materials.
+ * with the portable power (`portablePow`, within 1 ulp) instead of `**`, and (2.14) the built-in color patches with the
+ * portable exponential (`portableExp`) instead of `Math.exp`, whose last bits differ between JavaScript engines. Every
+ * other value, the geometry and the material order are the same. The display view uses its materials.
  */
 export function resolvePortableChartScene(input) {
     requireInputObject(input, "resolveChartScene input");
-    return resolveScene(input.scene, input.aspect, { pictureHeight: 2 * input.aspect, nested: false, pow: portablePow });
+    return resolveScene(input.scene, input.aspect, { pictureHeight: 2 * input.aspect, nested: false, pow: portablePow, exp: portableExp });
 }
 function resolveScene(scene, aspect, context) {
     requireInputObject(scene, "chart scene");
@@ -152,7 +188,7 @@ function resolveScene(scene, aspect, context) {
         throw new InvalidConfigurationError("A composite chart cannot contain another composite.");
     const record = scene;
     const defaults = CHART_SCENE_DEFAULTS[preset];
-    const extra = preset === "patches" ? ["patches", "columns"] : preset === "composite" ? ["elements"] : preset === "siemens-star" ? ["profile"] : [];
+    const extra = preset === "patches" ? ["patches", "columns"] : preset === "color-patches" ? ["columns"] : preset === "composite" ? ["elements"] : preset === "siemens-star" ? ["profile"] : [];
     const allowed = ["preset", ...Object.keys(defaults), ...extra];
     for (const key of Object.keys(record))
         if (!allowed.includes(key))
@@ -183,8 +219,8 @@ function resolveScene(scene, aspect, context) {
     };
     switch (preset) {
         case "uniform": {
-            const raw = get("reflectance"), m = resolveChartMaterial(raw, "reflectance");
-            return done({ reflectance: typeof raw === "number" ? raw : "caller-spectrum" }, [m], () => 0, [typeof raw === "number" ? undefined : raw], { kind: "uniform" });
+            const raw = get("reflectance"), m = resolveChartMaterial(raw, "reflectance", context.exp);
+            return done({ reflectance: reflectanceReport(raw) }, [m], () => 0, [typeof raw === "number" ? undefined : raw], { kind: "uniform" });
         }
         case "slanted-edge": {
             const angle = finiteIn(get("angleDegrees"), "angleDegrees", -45, 45, true), dark = neutral("darkReflectance"), light = neutral("lightReflectance");
@@ -270,7 +306,7 @@ function resolveScene(scene, aspect, context) {
                 if (typeof p.patchId !== "string" || p.patchId.trim() === "" || ids.has(p.patchId))
                     throw new InvalidConfigurationError("Each patch needs a unique non-empty patchId.");
                 ids.add(p.patchId);
-                materials.push(resolveChartMaterial(p.reflectance, "patches[" + index + "].reflectance"));
+                materials.push(resolveChartMaterial(p.reflectance, "patches[" + index + "].reflectance", context.exp));
                 inputs.push(typeof p.reflectance === "number" ? undefined : p.reflectance);
             }
             const columnsRaw = record.columns === undefined ? Math.ceil(Math.sqrt(list.length)) : record.columns;
@@ -284,15 +320,35 @@ function resolveScene(scene, aspect, context) {
             materials.push({ kind: "neutral", reflectance: background });
             inputs.push(undefined);
             const cellW = 2 / columns, cellH = 2 * aspect / rows;
-            return done({ patchIds: list.map((p) => p.patchId), columns, rows, gapFraction: gap, backgroundReflectance: background }, materials, (u, v) => {
-                const fx = (u + 1) / cellW, fy = (aspect - v) / cellH, i = Math.floor(fx), j = Math.floor(fy);
-                if (i < 0 || j < 0 || i >= columns || j >= rows)
-                    return backgroundIndex;
-                const index = j * columns + i, x = fx - i, y = fy - j;
-                if (index >= list.length || x < gap / 2 || x > 1 - gap / 2 || y < gap / 2 || y > 1 - gap / 2)
-                    return backgroundIndex;
-                return index;
-            }, inputs, { kind: "patches", columns, rows, count: list.length, gap, cellW, cellH, backgroundIndex });
+            return done({ patchIds: list.map((p) => p.patchId), columns, rows, gapFraction: gap, backgroundReflectance: background }, materials, patchGridMaterialAt(columns, rows, list.length, gap, aspect, backgroundIndex), inputs, { kind: "patches", columns, rows, count: list.length, gap, cellW, cellH, backgroundIndex });
+        }
+        case "color-patches": {
+            const ids = get("patchIds");
+            if (!Array.isArray(ids) || ids.length < 1 || ids.length > COLOR_PATCH_IDS.length)
+                throw new InvalidConfigurationError("patchIds must list 1 to " + COLOR_PATCH_IDS.length + " built-in color patch ids.");
+            const seen = new Set(), materials = [], inputs = [];
+            for (const [index, id] of ids.entries()) {
+                if (!findColorPatch(id))
+                    throw new InvalidConfigurationError("patchIds[" + index + "] must be one of the built-in color patches (COLOR_PATCH_IDS).");
+                if (seen.has(id))
+                    throw new InvalidConfigurationError("patchIds[" + index + "] repeats " + JSON.stringify(id) + ".");
+                seen.add(id);
+                const input = Object.freeze({ kind: "color-patch", patchId: id });
+                materials.push(resolveChartMaterial(input, "patchIds[" + index + "]", context.exp));
+                inputs.push(input);
+            }
+            const columnsRaw = record.columns === undefined ? Math.min(6, ids.length) : record.columns;
+            if (record.columns === undefined)
+                defaulted.push("columns");
+            const columns = integerIn(columnsRaw, "columns", 1, ids.length), rows = Math.ceil(ids.length / columns);
+            const gap = finiteIn(get("gapFraction"), "gapFraction", 0, 0.5), background = neutral("backgroundReflectance");
+            if (gap >= 0.5)
+                throw new InvalidConfigurationError("gapFraction must be below 0.5.");
+            const backgroundIndex = materials.length;
+            materials.push({ kind: "neutral", reflectance: background });
+            inputs.push(undefined);
+            const cellW = 2 / columns, cellH = 2 * aspect / rows;
+            return done({ patchSet: COLOR_PATCH_SET_ID, patchSetVersion: COLOR_PATCH_SET_VERSION, patchIds: [...ids], columns, rows, gapFraction: gap, backgroundReflectance: background }, materials, patchGridMaterialAt(columns, rows, ids.length, gap, aspect, backgroundIndex), inputs, { kind: "patches", columns, rows, count: ids.length, gap, cellW, cellH, backgroundIndex });
         }
         case "dead-leaves": {
             const rMin = finiteIn(get("radiusMinimum"), "radiusMinimum", DEAD_LEAVES_MINIMUM_RADIUS, 2), rMax = finiteIn(get("radiusMaximum"), "radiusMaximum", 0, 2, true);
@@ -410,7 +466,8 @@ function resolveScene(scene, aspect, context) {
             const list = record.elements;
             if (!Array.isArray(list) || list.length < 1 || list.length > 256)
                 throw new InvalidConfigurationError("elements must list 1 to 256 chart elements.");
-            const nested = { pictureHeight: context.pictureHeight, nested: true, ...(context.pow ? { pow: context.pow } : {}) };
+            const portable = { ...(context.pow ? { pow: context.pow } : {}), ...(context.exp ? { exp: context.exp } : {}) };
+            const nested = { pictureHeight: context.pictureHeight, nested: true, ...portable };
             const background = resolveScene(get("background"), aspect, nested);
             const materials = [...background.materials], inputs = [...chartMaterialInputs(background)];
             for (const key of background.defaultedParameters)
@@ -430,7 +487,7 @@ function resolveScene(scene, aspect, context) {
                 if (e.mask === undefined)
                     defaulted.push("elements." + index + ".placement.mask");
                 // The element's own frame: u = ±1 across its width; frequencies keep the composite's picture height.
-                const chart = resolveScene(e.scene, height / width, { pictureHeight: context.pictureHeight * 2 / width, nested: true, ...(context.pow ? { pow: context.pow } : {}) });
+                const chart = resolveScene(e.scene, height / width, { pictureHeight: context.pictureHeight * 2 / width, nested: true, ...portable });
                 for (const key of chart.defaultedParameters)
                     defaulted.push("elements." + index + ".parameters." + key);
                 const offset = materials.length;
@@ -574,7 +631,7 @@ function barGroupLayout(list, numerals, aspect, pictureHeight) {
 /** Engine-drawn seven-segment numerals: a 0.6 × 1 cell per digit (baseline at 0, y up), stroke 0.16, advance 0.82. */
 export const NUMERAL_WIDTH = 0.6, NUMERAL_ADVANCE = 0.82;
 /** Internal: segment rectangles [x0, y0, x1, y1] of the seven-segment numerals and the segments each digit lights. */
-export const SEGMENTS = Object.freeze({
+export const SEGMENTS = /* @__PURE__ */ Object.freeze({
     a: [0.08, 0.84, 0.52, 1], b: [0.44, 0.5, 0.6, 1], c: [0.44, 0, 0.6, 0.5], d: [0.08, 0, 0.52, 0.16], e: [0, 0, 0.16, 0.5], f: [0, 0.5, 0.16, 1], g: [0.08, 0.42, 0.52, 0.58]
 });
 export const DIGIT_SEGMENTS = ["abcdef", "bc", "abged", "abgcd", "fgbc", "afgcd", "afgedc", "abc", "abcdefg", "abcdfg"];