@photivra/engine 2.2.1 → 2.3.0

package/dist/facade/chart-scenes.js

@@ -8,19 +8,30 @@
  * 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.
  * The facade places the chart perpendicular to the optical axis at the subject distance and sizes it so
- * that this rectangle exactly fills the active capture (see `SimulateCaptureResult.assumptions`).
+ * that this rectangle exactly fills the active capture (see `SimulateCaptureResult.assumptions`), or, with
+ * `simulateCapture({ chartSize })` (2.3), at its physical size.
  *
  * The slanted edge follows the geometry described by P. D. Burns, "Slanted-Edge MTF for Digital Camera
  * and Scanner Analysis", IS&T PICS 2000 (free from imaging.org; also ISO 12233). It is a near-vertical
  * edge rotated by a few degrees (5 degrees by default), with a 4:1 light/dark reflectance ratio by
  * default. This is only a geometric description. No measured chart or ISO test procedure is copied.
+ *
+ * Chart elements (2.3) are generic, unbranded test-pattern primitives; each element's definition and
+ * source is given at its preset below. A `composite` chart lays out any of them in placement rectangles
+ * over a background, so an application can build its own layout from engine parts. Continuous patterns
+ * (sine star, zone plate, dead-leaves greys) are quantized to {@link CHART_CONTINUOUS_LEVELS} equal neutral
+ * 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 { 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",
-    "step-wedge", "grey-ramp", "checkerboard", "point-grid", "patches"]);
+    "step-wedge", "grey-ramp", "checkerboard", "point-grid", "patches", "dead-leaves", "bar-groups", "hyperbolic-wedge", "zone-plate",
+    "slanted-squares", "line-grid", "fiducial", "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 }),
@@ -30,7 +41,16 @@ export const CHART_SCENE_DEFAULTS = Object.freeze({
     "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 })
+    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,
+        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 }) })
 });
 function reflectance(value, name) {
     if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1)
@@ -66,6 +86,29 @@ function material(value, name) {
         reflectance(spectrum.evaluate(nm), name + " values");
     return { kind: "spectrum", spectrum };
 }
+/** Raw caller spectrum inputs per material (undefined for neutral materials), for the facade's scene digest. */
+const MATERIAL_INPUTS = new WeakMap();
+/**
+ * Internal (not exported from the package): the caller input behind each material of a resolved chart, in
+ * material order (`undefined` for an engine neutral). The facade hashes caller spectra from these inputs.
+ */
+export function chartMaterialInputs(chart) {
+    return MATERIAL_INPUTS.get(chart) ?? chart.materials.map(() => undefined);
+}
+const neutralMaterials = (values) => values.map((reflectanceValue) => ({ kind: "neutral", reflectance: reflectanceValue }));
+/** CHART_CONTINUOUS_LEVELS equal neutral levels between `from` and `to` (level i at from + (to − from)(i + ½)/levels). */
+function continuousMaterials(from, to) {
+    return Array.from({ length: CHART_CONTINUOUS_LEVELS }, (_, i) => ({ kind: "neutral", reflectance: from + (to - from) * (i + 0.5) / CHART_CONTINUOUS_LEVELS }));
+}
+/** The level index of a continuous value between `from` and `to`. */
+function continuousLevel(value, from, to) {
+    return Math.min(CHART_CONTINUOUS_LEVELS - 1, Math.max(0, Math.floor((value - from) / (to - from) * CHART_CONTINUOUS_LEVELS)));
+}
+function booleanParameter(value, name) {
+    if (typeof value !== "boolean")
+        throw new InvalidConfigurationError(name + " must be true or false.");
+    return value;
+}
 /**
  * Validates a chart description and resolves every default. `aspect` is the frame height/width. Unknown
  * fields are rejected so that a mistyped parameter never silently falls back to a default.
@@ -79,12 +122,19 @@ export function resolveChartScene(input) {
     requireInputObject(scene, "chart scene");
     if (typeof aspect !== "number" || !Number.isFinite(aspect) || aspect <= 0)
         throw new InvalidConfigurationError("Chart aspect must be positive.");
+    return resolveScene(scene, aspect, { pictureHeight: 2 * aspect, nested: false });
+}
+function resolveScene(scene, aspect, context) {
+    requireInputObject(scene, "chart scene");
     const preset = scene.preset;
     if (typeof preset !== "string" || !CHART_SCENE_PRESETS.includes(preset))
         throw new InvalidConfigurationError("Unknown chart preset.");
+    if (preset === "composite" && context.nested)
+        throw new InvalidConfigurationError("A composite chart cannot contain another composite.");
     const record = scene;
     const defaults = CHART_SCENE_DEFAULTS[preset];
-    const allowed = ["preset", ...Object.keys(defaults), ...(preset === "patches" ? ["patches", "columns"] : [])];
+    const extra = preset === "patches" ? ["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))
             throw new InvalidConfigurationError("Unknown chart parameter: " + key + ".");
@@ -95,20 +145,26 @@ export function resolveChartScene(input) {
         return defaults[key];
     } return record[key]; };
     const neutral = (key) => reflectance(get(key), key);
-    const done = (parameters, materials, materialAt) => Object.freeze({ preset: preset, parameters: Object.freeze(parameters), defaultedParameters: Object.freeze(defaulted), aspect, materials: Object.freeze(materials), materialAt,
-        reflectanceAt(u, v, nm) {
-            const m = materials[materialAt(u, v)];
-            if (m.kind === "neutral")
-                return m.reflectance;
-            const value = m.spectrum.evaluate(nm);
-            if (!(value >= 0 && value <= 1))
-                throw new InvalidConfigurationError("Chart reflectance spectrum left [0, 1].");
-            return value;
-        } });
+    const done = (parameters, materials, materialAt, inputs) => {
+        const chart = Object.freeze({ preset: preset, parameters: Object.freeze(parameters), defaultedParameters: Object.freeze(defaulted), aspect,
+            materials: Object.freeze(materials), materialAt,
+            reflectanceAt(u, v, nm) {
+                const m = materials[materialAt(u, v)];
+                if (m.kind === "neutral")
+                    return m.reflectance;
+                const value = m.spectrum.evaluate(nm);
+                if (!(value >= 0 && value <= 1))
+                    throw new InvalidConfigurationError("Chart reflectance spectrum left [0, 1].");
+                return value;
+            } });
+        if (inputs)
+            MATERIAL_INPUTS.set(chart, Object.freeze([...inputs]));
+        return chart;
+    };
     switch (preset) {
         case "uniform": {
             const raw = get("reflectance"), m = material(raw, "reflectance");
-            return done({ reflectance: typeof raw === "number" ? raw : "caller-spectrum" }, [m], () => 0);
+            return done({ reflectance: typeof raw === "number" ? raw : "caller-spectrum" }, [m], () => 0, [typeof raw === "number" ? undefined : raw]);
         }
         case "slanted-edge": {
             const angle = finiteIn(get("angleDegrees"), "angleDegrees", -45, 45, true), dark = neutral("darkReflectance"), light = neutral("lightReflectance");
@@ -121,7 +177,26 @@ export function resolveChartScene(input) {
             if (radius === 0)
                 throw new InvalidConfigurationError("radiusFraction must be positive.");
             const dark = neutral("darkReflectance"), light = neutral("lightReflectance"), background = neutral("backgroundReflectance"), r = radius * aspect;
-            return done({ cycles, radiusFraction: radius, darkReflectance: dark, lightReflectance: light, backgroundReflectance: background }, [{ kind: "neutral", reflectance: dark }, { kind: "neutral", reflectance: light }, { kind: "neutral", reflectance: background }], (u, v) => {
+            const profile = record.profile;
+            if (profile !== undefined && profile !== "bar" && profile !== "sine")
+                throw new InvalidConfigurationError("profile must be bar or sine.");
+            const parameters = { cycles, radiusFraction: radius, darkReflectance: dark, lightReflectance: light, backgroundReflectance: background };
+            if (profile === "sine") {
+                // Sinusoidal star (2.3): zero crossings at the bar star's sector edges, light where the bar star is light.
+                if (dark === light)
+                    throw new InvalidConfigurationError("A sine star needs different dark and light reflectances.");
+                const mid = (dark + light) / 2, amp = (light - dark) / 2, materials = continuousMaterials(dark, light);
+                materials.push({ kind: "neutral", reflectance: background });
+                return done({ ...parameters, profile, representation: CHART_CONTINUOUS_LEVELS + " equal neutral levels" }, materials, (u, v) => {
+                    if (u * u + v * v > r * r)
+                        return CHART_CONTINUOUS_LEVELS;
+                    const phase = Math.atan2(v, u) / (2 * Math.PI) + 0.5;
+                    return continuousLevel(mid + amp * Math.sin(2 * Math.PI * cycles * phase), dark, light);
+                });
+            }
+            if (profile === "bar")
+                parameters.profile = profile;
+            return done(parameters, [{ kind: "neutral", reflectance: dark }, { kind: "neutral", reflectance: light }, { kind: "neutral", reflectance: background }], (u, v) => {
                 if (u * u + v * v > r * r)
                     return 2;
                 const phase = Math.atan2(v, u) / (2 * Math.PI) + 0.5; // [0, 1]
@@ -165,7 +240,7 @@ export function resolveChartScene(input) {
             if (!Array.isArray(list) || list.length < 1 || list.length > 1024)
                 throw new InvalidConfigurationError("patches must list 1 to 1024 caller reflectances.");
             const ids = new Set();
-            const materials = [];
+            const materials = [], inputs = [];
             for (const [index, patch] of list.entries()) {
                 requireInputObject(patch, "patches[" + index + "]");
                 const p = patch;
@@ -176,6 +251,7 @@ export function resolveChartScene(input) {
                     throw new InvalidConfigurationError("Each patch needs a unique non-empty patchId.");
                 ids.add(p.patchId);
                 materials.push(material(p.reflectance, "patches[" + index + "].reflectance"));
+                inputs.push(typeof p.reflectance === "number" ? undefined : p.reflectance);
             }
             const columnsRaw = record.columns === undefined ? Math.ceil(Math.sqrt(list.length)) : record.columns;
             if (record.columns === undefined)
@@ -186,6 +262,7 @@ export function resolveChartScene(input) {
                 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({ 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);
@@ -195,10 +272,359 @@ export function resolveChartScene(input) {
                 if (index >= list.length || x < gap / 2 || x > 1 - gap / 2 || y < gap / 2 || y > 1 - gap / 2)
                     return backgroundIndex;
                 return index;
+            }, inputs);
+        }
+        case "dead-leaves": {
+            const rMin = finiteIn(get("radiusMinimum"), "radiusMinimum", DEAD_LEAVES_MINIMUM_RADIUS, 2), rMax = finiteIn(get("radiusMaximum"), "radiusMaximum", 0, 2, true);
+            if (!(rMax > rMin))
+                throw new InvalidConfigurationError("radiusMaximum must exceed radiusMinimum.");
+            const lo = neutral("minimumReflectance"), hi = neutral("maximumReflectance"), seed = integerIn(get("seed"), "seed", 0, 0xffffffff);
+            if (hi < lo)
+                throw new InvalidConfigurationError("Dead leaves need minimum ≤ maximum reflectance.");
+            const leaves = generateDeadLeaves(rMin, rMax, seed, aspect);
+            return done({ radiusMinimum: rMin, radiusMaximum: rMax, minimumReflectance: lo, maximumReflectance: hi, seed, diskCount: leaves.diskCount,
+                radiusDensity: "proportional-to-r^-3", representation: CHART_CONTINUOUS_LEVELS + " equal neutral levels" }, continuousMaterials(lo, hi), leaves.levelAt);
+        }
+        case "bar-groups": {
+            const lws = get("lineWidthsPerPictureHeight");
+            if (!Array.isArray(lws) || lws.length < 1 || lws.length > 32)
+                throw new InvalidConfigurationError("lineWidthsPerPictureHeight must list 1 to 32 frequencies.");
+            const list = lws.map((lw, i) => integerIn(lw, "lineWidthsPerPictureHeight[" + i + "]", 1, 100_000));
+            const numerals = booleanParameter(get("numerals"), "numerals"), dark = neutral("darkReflectance"), light = neutral("lightReflectance");
+            const layout = barGroupLayout(list, numerals, aspect, context.pictureHeight);
+            return done({ lineWidthsPerPictureHeight: list, numerals, darkReflectance: dark, lightReflectance: light }, neutralMaterials([dark, light]), (u, v) => {
+                for (const g of layout) {
+                    if (u < g.cell.u0 || u > g.cell.u1)
+                        continue;
+                    const b = g.verticalBars, h = g.horizontalBars;
+                    if (u >= b.u0 && u < b.u1 && v >= b.v0 && v <= b.v1)
+                        return Math.floor((u - b.u0) / g.lineWidth) % 2 === 0 ? 0 : 1;
+                    if (u >= h.u0 && u <= h.u1 && v > h.v0 && v <= h.v1)
+                        return Math.floor((h.v1 - v) / g.lineWidth) % 2 === 0 ? 0 : 1;
+                    if (g.label && numeralInk(g.label, u, v))
+                        return 0;
+                    return 1;
+                }
+                return 1;
+            });
+        }
+        case "hyperbolic-wedge": {
+            const orientation = get("orientation");
+            if (orientation !== "horizontal" && orientation !== "vertical")
+                throw new InvalidConfigurationError("orientation must be horizontal or vertical.");
+            const lines = integerIn(get("lineCount"), "lineCount", 1, 50);
+            const lw0 = finiteIn(get("minimumLineWidthsPerPictureHeight"), "minimumLineWidthsPerPictureHeight", 0, 1e6, true);
+            const lw1 = finiteIn(get("maximumLineWidthsPerPictureHeight"), "maximumLineWidthsPerPictureHeight", 0, 1e6, true);
+            if (!(lw1 > lw0))
+                throw new InvalidConfigurationError("maximumLineWidthsPerPictureHeight must exceed minimumLineWidthsPerPictureHeight.");
+            const dark = neutral("darkReflectance"), light = neutral("lightReflectance"), ph = context.pictureHeight;
+            const across = orientation === "horizontal" ? 2 * aspect : 2;
+            if ((2 * lines - 1) * ph / lw0 > across)
+                throw new InvalidConfigurationError("The wedge's " + (2 * lines - 1) + " line widths at " + lw0 + " LW/PH do not fit across the chart.");
+            return done({ orientation, lineCount: lines, minimumLineWidthsPerPictureHeight: lw0, maximumLineWidthsPerPictureHeight: lw1, darkReflectance: dark, lightReflectance: light }, neutralMaterials([dark, light]), (u, v) => {
+                const s = orientation === "horizontal" ? (u + 1) / 2 : (v + aspect) / (2 * aspect), y = orientation === "horizontal" ? v : u;
+                if (s < 0 || s > 1)
+                    return 1;
+                const w = ph / (lw0 + (lw1 - lw0) * s), half = (2 * lines - 1) * w / 2;
+                if (y < -half || y >= half)
+                    return 1;
+                return Math.floor((y + half) / w) % 2 === 0 ? 0 : 1;
+            });
+        }
+        case "zone-plate": {
+            const radius = finiteIn(get("radiusFraction"), "radiusFraction", 0, 1, false);
+            if (radius === 0)
+                throw new InvalidConfigurationError("radiusFraction must be positive.");
+            const fMax = finiteIn(get("maximumCyclesPerPictureHeight"), "maximumCyclesPerPictureHeight", 0, 1e6, true);
+            const dark = neutral("darkReflectance"), light = neutral("lightReflectance"), background = neutral("backgroundReflectance");
+            if (dark === light)
+                throw new InvalidConfigurationError("A zone plate needs different dark and light reflectances.");
+            // Local frequency of cos(π·k·r²) is k·r cycles per frame unit: k·R = fMax / PH at the rim.
+            const r = radius * aspect, k = fMax / context.pictureHeight / r, mid = (dark + light) / 2, amp = (light - dark) / 2;
+            const materials = continuousMaterials(dark, light);
+            materials.push({ kind: "neutral", reflectance: background });
+            return done({ radiusFraction: radius, maximumCyclesPerPictureHeight: fMax, darkReflectance: dark, lightReflectance: light, backgroundReflectance: background,
+                representation: CHART_CONTINUOUS_LEVELS + " equal neutral levels" }, materials, (u, v) => {
+                const r2 = u * u + v * v;
+                if (r2 > r * r)
+                    return CHART_CONTINUOUS_LEVELS;
+                return continuousLevel(mid + amp * Math.cos(Math.PI * k * r2), dark, light);
+            });
+        }
+        case "slanted-squares": {
+            const columns = integerIn(get("columns"), "columns", 1, 64), rows = integerIn(get("rows"), "rows", 1, 64);
+            const size = finiteIn(get("sizeFraction"), "sizeFraction", 0, 1, true), angle = finiteIn(get("angleDegrees"), "angleDegrees", -45, 45, true);
+            const dark = neutral("darkReflectance"), light = neutral("lightReflectance");
+            const t = angle * Math.PI / 180, c = Math.cos(t), s = Math.sin(t);
+            if (size * (Math.abs(c) + Math.abs(s)) > 1)
+                throw new InvalidConfigurationError("The rotated squares must stay inside their cells: sizeFraction·(|cos θ| + |sin θ|) ≤ 1.");
+            const cellW = 2 / columns, cellH = 2 * aspect / rows, half = size * Math.min(cellW, cellH) / 2;
+            return done({ columns, rows, sizeFraction: size, angleDegrees: angle, darkReflectance: dark, lightReflectance: light }, neutralMaterials([dark, light]), (u, v) => {
+                const i = Math.min(columns - 1, Math.max(0, Math.floor((u + 1) / cellW))), j = Math.min(rows - 1, Math.max(0, Math.floor((aspect - v) / cellH)));
+                const du = u - (-1 + (i + 0.5) * cellW), dv = v - (aspect - (j + 0.5) * cellH);
+                const x = du * c - dv * s, y = du * s + dv * c;
+                return Math.abs(x) <= half && Math.abs(y) <= half ? 0 : 1;
+            });
+        }
+        case "line-grid": {
+            const spacing = finiteIn(get("spacing"), "spacing", 0, 2, true), width = finiteIn(get("lineWidth"), "lineWidth", 0, spacing, true);
+            const line = neutral("lineReflectance"), background = neutral("backgroundReflectance"), half = width / 2;
+            return done({ spacing, lineWidth: width, lineReflectance: line, backgroundReflectance: background }, neutralMaterials([background, line]), (u, v) => (Math.abs(u - spacing * Math.round(u / spacing)) <= half || Math.abs(v - spacing * Math.round(v / spacing)) <= half ? 1 : 0));
+        }
+        case "fiducial": {
+            const radius = finiteIn(get("radiusFraction"), "radiusFraction", 0, 1, false), ring = finiteIn(get("ringFraction"), "ringFraction", 0, 1, true);
+            if (radius === 0)
+                throw new InvalidConfigurationError("radiusFraction must be positive.");
+            const inverted = booleanParameter(get("inverted"), "inverted"), dark = neutral("darkReflectance"), light = neutral("lightReflectance"), background = neutral("backgroundReflectance");
+            const r = radius * aspect, inner = r * (1 - ring);
+            return done({ radiusFraction: radius, ringFraction: ring, inverted, darkReflectance: dark, lightReflectance: light, backgroundReflectance: background }, neutralMaterials([dark, light, background]), (u, v) => {
+                const r2 = u * u + v * v;
+                if (r2 > r * r)
+                    return 2;
+                if (r2 > inner * inner)
+                    return 0;
+                return ((u >= 0) === (v >= 0)) !== inverted ? 0 : 1;
             });
         }
+        case "composite": {
+            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 };
+            const background = resolveScene(get("background"), aspect, nested);
+            const materials = [...background.materials], inputs = [...chartMaterialInputs(background)];
+            for (const key of background.defaultedParameters)
+                defaulted.push("background.parameters." + key);
+            const elements = list.map((value, index) => {
+                const name = "elements[" + index + "]";
+                requireInputObject(value, name);
+                const e = value;
+                for (const key of Object.keys(e))
+                    if (!["scene", "centerU", "centerV", "width", "height", "mask"].includes(key))
+                        throw new InvalidConfigurationError("Unknown " + name + " field: " + key + ".");
+                const cu = finiteIn(e.centerU, name + ".centerU", -1e6, 1e6), cv = finiteIn(e.centerV, name + ".centerV", -1e6, 1e6);
+                const width = finiteIn(e.width, name + ".width", 0, 1e6, true), height = finiteIn(e.height, name + ".height", 0, 1e6, true);
+                const mask = e.mask === undefined ? "rectangle" : e.mask;
+                if (mask !== "rectangle" && mask !== "ellipse")
+                    throw new InvalidConfigurationError(name + ".mask must be rectangle or ellipse.");
+                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 });
+                for (const key of chart.defaultedParameters)
+                    defaulted.push("elements." + index + ".parameters." + key);
+                const offset = materials.length;
+                materials.push(...chart.materials);
+                inputs.push(...chartMaterialInputs(chart));
+                return { chart, offset, cu, cv, hw: width / 2, hh: height / 2, scale: 2 / width, ellipse: mask === "ellipse",
+                    report: { preset: chart.preset, placement: { centerU: cu, centerV: cv, width, height, mask }, parameters: chart.parameters } };
+            });
+            return done({ background: { preset: background.preset, parameters: background.parameters }, elements: elements.map((e) => e.report) }, materials, (u, v) => {
+                for (let i = elements.length - 1; i >= 0; i--) {
+                    const e = elements[i], du = u - e.cu, dv = v - e.cv;
+                    if (du < -e.hw || du > e.hw || dv < -e.hh || dv > e.hh)
+                        continue;
+                    if (e.ellipse && (du / e.hw) ** 2 + (dv / e.hh) ** 2 > 1)
+                        continue;
+                    return e.offset + e.chart.materialAt(du * e.scale, dv * e.scale);
+                }
+                return background.materialAt(u, v);
+            }, inputs);
+        }
     }
 }
+/** Smallest dead-leaves disk radius, frame units: bounds the lookup grid and the disk count. */
+const DEAD_LEAVES_MINIMUM_RADIUS = 0.002;
+/** Dead-leaves work limits: lookup cells and disks. */
+const DEAD_LEAVES_MAXIMUM_CELLS = 4_194_304, DEAD_LEAVES_MAXIMUM_DISKS = 4_000_000;
+/** The covered margin around the chart, frame units; beyond it the texture is its mean grey. */
+const DEAD_LEAVES_MARGIN = 0.1;
+/**
+ * Dead-leaves disks, drawn front to back: disk n lies under disks 0..n−1. Each disk is listed in the lookup
+ * cells it overlaps that are not yet covered; a cell is closed as soon as one disk covers it entirely, so no
+ * later disk can show in it. Drawing stops when every cell is closed (the domain is fully covered), which is
+ * the backward perfect simulation of the stationary model (Kendall and Thönnes 1999). Deterministic: the
+ * engine's xorshift32 stream, and only correctly rounded operations (+ − × ÷ and √) on the drawn values.
+ */
+function generateDeadLeaves(rMin, rMax, seed, aspect) {
+    const u0 = -1 - DEAD_LEAVES_MARGIN, v0 = -aspect - DEAD_LEAVES_MARGIN, width = 2 + 2 * DEAD_LEAVES_MARGIN, height = 2 * aspect + 2 * DEAD_LEAVES_MARGIN;
+    const cell = Math.max(rMin, Math.sqrt(width * height / DEAD_LEAVES_MAXIMUM_CELLS));
+    const nx = Math.ceil(width / cell), ny = Math.ceil(height / cell), cells = nx * ny;
+    if (!(cells <= DEAD_LEAVES_MAXIMUM_CELLS))
+        throw new InvalidConfigurationError("Dead leaves: the chart aspect is too extreme for the lookup grid.");
+    const closed = new Uint8Array(cells), head = new Int32Array(cells).fill(-1), tail = new Int32Array(cells).fill(-1);
+    let next = new Int32Array(1 << 16), entryDisk = new Int32Array(1 << 16), entries = 0;
+    let X = new Float64Array(1 << 14), Y = new Float64Array(1 << 14), R2 = new Float64Array(1 << 14), level = new Uint16Array(1 << 14);
+    const a = 1 / (rMin * rMin), b = 1 / (rMax * rMax), random = createDeterministicUniformStream(seed);
+    let open = cells, n = 0;
+    while (open > 0) {
+        if (n >= DEAD_LEAVES_MAXIMUM_DISKS)
+            throw new InvalidConfigurationError("Dead leaves need more than " + DEAD_LEAVES_MAXIMUM_DISKS + " disks; raise radiusMinimum.");
+        // Inverse CDF of the density ∝ r⁻³ on [rMin, rMax]: r = (rMin⁻² − U·(rMin⁻² − rMax⁻²))^(−1/2).
+        const r = 1 / Math.sqrt(a - random.next() * (a - b));
+        const x = u0 - rMax + random.next() * (width + 2 * rMax), y = v0 - rMax + random.next() * (height + 2 * rMax);
+        const grey = Math.min(CHART_CONTINUOUS_LEVELS - 1, Math.floor(random.next() * CHART_CONTINUOUS_LEVELS));
+        if (n === X.length) {
+            const grow = (old, make) => { const out = make(old.length * 2); out.set(old); return out; };
+            X = grow(X, (l) => new Float64Array(l));
+            Y = grow(Y, (l) => new Float64Array(l));
+            R2 = grow(R2, (l) => new Float64Array(l));
+            level = grow(level, (l) => new Uint16Array(l));
+        }
+        X[n] = x;
+        Y[n] = y;
+        R2[n] = r * r;
+        level[n] = grey;
+        const i0 = Math.max(0, Math.floor((x - r - u0) / cell)), i1 = Math.min(nx - 1, Math.floor((x + r - u0) / cell));
+        const j0 = Math.max(0, Math.floor((y - r - v0) / cell)), j1 = Math.min(ny - 1, Math.floor((y + r - v0) / cell));
+        for (let j = j0; j <= j1; j++) {
+            const cy0 = v0 + j * cell, cy1 = cy0 + cell, ny0 = Math.max(cy0, Math.min(y, cy1)) - y;
+            for (let i = i0; i <= i1; i++) {
+                const c = j * nx + i;
+                if (closed[c])
+                    continue;
+                const cx0 = u0 + i * cell, cx1 = cx0 + cell, nx0 = Math.max(cx0, Math.min(x, cx1)) - x;
+                if (nx0 * nx0 + ny0 * ny0 > r * r)
+                    continue;
+                if (entries === next.length) {
+                    const grownNext = new Int32Array(entries * 2), grownDisk = new Int32Array(entries * 2);
+                    grownNext.set(next);
+                    grownDisk.set(entryDisk);
+                    next = grownNext;
+                    entryDisk = grownDisk;
+                }
+                entryDisk[entries] = n;
+                next[entries] = -1;
+                if (tail[c] < 0)
+                    head[c] = entries;
+                else
+                    next[tail[c]] = entries;
+                tail[c] = entries++;
+                const fx = Math.max(Math.abs(cx0 - x), Math.abs(cx1 - x)), fy = Math.max(Math.abs(cy0 - y), Math.abs(cy1 - y));
+                if (fx * fx + fy * fy <= r * r) {
+                    closed[c] = 1;
+                    open--;
+                }
+            }
+        }
+        n++;
+    }
+    const mean = CHART_CONTINUOUS_LEVELS / 2;
+    return { diskCount: n, levelAt(u, v) {
+            const i = Math.floor((u - u0) / cell), j = Math.floor((v - v0) / cell);
+            if (i < 0 || j < 0 || i >= nx || j >= ny)
+                return mean;
+            for (let e = head[j * nx + i]; e >= 0; e = next[e]) {
+                const d = entryDisk[e], dx = u - X[d], dy = v - Y[d];
+                if (dx * dx + dy * dy <= R2[d])
+                    return level[d];
+            }
+            return mean;
+        } };
+}
+/**
+ * Bar-group layout in the chart's own frame: G equal columns (80 % group, 20 % gap), rows from the top
+ * 40 % vertical bars, 40 % horizontal bars, 20 % numerals (50 %/50 % without numerals), each row inset by
+ * 5 % of its height. A group is five line widths (three dark bars, two light gaps) centred in its cell.
+ */
+function barGroupLayout(list, numerals, aspect, pictureHeight) {
+    const H = 2 * aspect, weights = numerals ? [0.4, 0.4, 0.2] : [0.5, 0.5], column = 2 / list.length;
+    const rows = [];
+    let top = aspect;
+    for (const w of weights) {
+        const h = H * w;
+        rows.push({ v0: top - h + 0.05 * h, v1: top - 0.05 * h });
+        top -= h;
+    }
+    return list.map((lw, i) => {
+        const w = pictureHeight / lw, u0 = -1 + i * column + 0.1 * column, u1 = u0 + 0.8 * column, uc = (u0 + u1) / 2;
+        const r0 = rows[0], r1 = rows[1], vc = (r1.v0 + r1.v1) / 2;
+        if (5 * w > u1 - u0 || 5 * w > r1.v1 - r1.v0)
+            throw new InvalidConfigurationError("The bar group at " + lw + " LW/PH (five line widths) does not fit its cell; use fewer groups or higher frequencies.");
+        const group = { lineWidthsPerPictureHeight: lw, lineWidth: w, cell: { u0, u1 },
+            verticalBars: { u0: uc - 2.5 * w, v0: r0.v0, u1: uc + 2.5 * w, v1: r0.v1 }, horizontalBars: { u0, v0: vc - 2.5 * w, u1, v1: vc + 2.5 * w } };
+        if (numerals) {
+            const r2 = rows[2], text = String(lw), units = text.length * NUMERAL_ADVANCE - (NUMERAL_ADVANCE - NUMERAL_WIDTH);
+            const height = Math.min(r2.v1 - r2.v0, (u1 - u0) / units);
+            group.label = { text, u0: uc - units * height / 2, v0: (r2.v0 + r2.v1) / 2 - height / 2, height };
+        }
+        return group;
+    });
+}
+/** Engine-drawn seven-segment numerals: a 0.6 × 1 cell per digit (baseline at 0, y up), stroke 0.16, advance 0.82. */
+const NUMERAL_WIDTH = 0.6, NUMERAL_ADVANCE = 0.82;
+const SEGMENTS = 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]
+});
+const DIGIT_SEGMENTS = ["abcdef", "bc", "abged", "abgcd", "fgbc", "afgcd", "afgedc", "abc", "abcdefg", "abcdfg"];
+function numeralInk(label, u, v) {
+    const x = (u - label.u0) / label.height, y = (v - label.v0) / label.height;
+    if (y < 0 || y > 1 || x < 0)
+        return false;
+    const k = Math.floor(x / NUMERAL_ADVANCE);
+    if (k >= label.text.length)
+        return false;
+    const cx = x - k * NUMERAL_ADVANCE;
+    for (const s of DIGIT_SEGMENTS[label.text.charCodeAt(k) - 48]) {
+        const [x0, y0, x1, y1] = SEGMENTS[s];
+        if (cx >= x0 && cx <= x1 && y >= y0 && y <= y1)
+            return true;
+    }
+    return false;
+}
+/** Element placements of a resolved chart with a frame map to the chart's frame units (one identity entry for a plain preset). */
+function chartElements(chart) {
+    if (chart.preset !== "composite")
+        return [{ index: null, preset: chart.preset, parameters: chart.parameters, aspect: chart.aspect,
+                pictureHeight: 2 * chart.aspect, toFrame: (u, v) => ({ u, v }), scale: 1 }];
+    const elements = chart.parameters.elements;
+    return elements.map((e, index) => {
+        const p = e.placement, s = p.width / 2;
+        return { index, preset: e.preset, parameters: e.parameters, aspect: p.height / p.width, pictureHeight: 2 * chart.aspect / s,
+            toFrame: (u, v) => ({ u: p.centerU + u * s, v: p.centerV + v * s }), scale: s };
+    });
+}
+const mapRectangle = (r, toFrame) => {
+    const a = toFrame(r.u0, r.v0), b = toFrame(r.u1, r.v1);
+    return { u0: a.u, v0: a.v, u1: b.u, v1: b.v };
+};
+/**
+ * The bar groups of a `bar-groups` chart, or of every `bar-groups` element of a composite, in the chart's
+ * frame units (2.3). `aspect` is the chart's height / width, as for {@link resolveChartScene}.
+ */
+export function calculateBarGroupTargets(input) {
+    requireInputKeys(input, "calculateBarGroupTargets", ["scene", "aspect"]);
+    const chart = resolveChartScene({ scene: input.scene, aspect: input.aspect });
+    return chartElements(chart).filter((e) => e.preset === "bar-groups").flatMap((e) => barGroupLayout(e.parameters.lineWidthsPerPictureHeight, e.parameters.numerals, e.aspect, e.pictureHeight).map((g) => ({
+        elementIndex: e.index, lineWidthsPerPictureHeight: g.lineWidthsPerPictureHeight, cyclesPerPictureHeight: g.lineWidthsPerPictureHeight / 2,
+        lineWidth: g.lineWidth * e.scale, verticalBars: mapRectangle(g.verticalBars, e.toFrame), horizontalBars: mapRectangle(g.horizontalBars, e.toFrame)
+    })));
+}
+/**
+ * Squares and edges of a `slanted-squares` chart, or of every `slanted-squares` element of a composite, in
+ * the chart's frame units (2.3), for slanted-edge regions of interest (Burns, PICS 2000). Directions are unit
+ * vectors along each edge (u right, v up).
+ */
+export function calculateSlantedSquareEdges(input) {
+    requireInputKeys(input, "calculateSlantedSquareEdges", ["scene", "aspect"]);
+    const chart = resolveChartScene({ scene: input.scene, aspect: input.aspect });
+    return chartElements(chart).filter((e) => e.preset === "slanted-squares").flatMap((e) => {
+        const p = e.parameters;
+        const t = p.angleDegrees * Math.PI / 180, c = Math.cos(t), s = Math.sin(t), cellW = 2 / p.columns, cellH = 2 * e.aspect / p.rows;
+        const half = p.sizeFraction * Math.min(cellW, cellH) / 2, out = [];
+        // Local square axes rotated clockwise by t: x̂ = (cos t, −sin t), ŷ = (sin t, cos t) in (u, v).
+        const xAxis = { u: c, v: -s }, yAxis = { u: s, v: c };
+        for (let j = 0; j < p.rows; j++)
+            for (let i = 0; i < p.columns; i++) {
+                const cu = -1 + (i + 0.5) * cellW, cv = e.aspect - (j + 0.5) * cellH, at = (x, y) => e.toFrame(cu + x * xAxis.u + y * yAxis.u, cv + x * xAxis.v + y * yAxis.v);
+                const length = 2 * half * e.scale;
+                out.push({ elementIndex: e.index, center: e.toFrame(cu, cv), side: length, angleDegrees: p.angleDegrees, darkReflectance: p.darkReflectance, lightReflectance: p.lightReflectance,
+                    edges: [{ side: "left", midpoint: at(-half, 0), direction: yAxis, length }, { side: "right", midpoint: at(half, 0), direction: yAxis, length },
+                        { side: "top", midpoint: at(0, half), direction: xAxis, length }, { side: "bottom", midpoint: at(0, -half), direction: xAxis, length }] });
+            }
+        return out;
+    });
+}
 /**
  * Step reflectances of a step wedge. `equal-density` spaces optical density D = -log10(R) evenly, which
  * gives geometric reflectance steps, as on a photographic step tablet. `linear` spaces reflectance evenly.