@photivra/engine 1.5.0 → 2.1.0

package/dist/facade/chart-scenes.js

@@ -0,0 +1,232 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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.
+ *
+ * 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`).
+ *
+ * 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.
+ * @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";
+export const CHART_SCENE_PRESETS = Object.freeze(["uniform", "slanted-edge", "siemens-star",
+    "step-wedge", "grey-ramp", "checkerboard", "point-grid", "patches"]);
+/** 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 })
+});
+function reflectance(value, name) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1)
+        throw new InvalidConfigurationError(name + " must be a reflectance in [0, 1].");
+    return value;
+}
+function integerIn(value, name, minimum, maximum) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum)
+        throw new InvalidConfigurationError(name + " must be an integer from " + minimum + " to " + maximum + ".");
+    return value;
+}
+function finiteIn(value, name, minimum, maximum, open = false) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum || (open && (value === minimum || value === maximum)))
+        throw new InvalidConfigurationError(name + " is outside its supported range.");
+    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 });
+function material(value, name) {
+    if (typeof value === "number")
+        return { kind: "neutral", reflectance: reflectance(value, name) };
+    let spectrum;
+    try {
+        spectrum = prepareColorimetricSpectrum(value, name);
+    }
+    catch (error) {
+        throw new InvalidConfigurationError(name + " must be a neutral reflectance or a valid reflectance spectrum: " + (error instanceof Error ? error.message : "invalid"));
+    }
+    const range = spectrum.wavelengthRangeNanometers;
+    if (range.minimum > CHART_SPECTRAL_RANGE_NANOMETERS.minimum || range.maximum < CHART_SPECTRAL_RANGE_NANOMETERS.maximum)
+        throw new InvalidConfigurationError(name + " must cover 380-780 nm.");
+    for (let nm = CHART_SPECTRAL_RANGE_NANOMETERS.minimum; nm <= CHART_SPECTRAL_RANGE_NANOMETERS.maximum; nm += 5)
+        reflectance(spectrum.evaluate(nm), name + " values");
+    return { kind: "spectrum", spectrum };
+}
+/**
+ * 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.
+ */
+export function resolveChartScene(input) {
+    requireInputObject(input, "resolveChartScene input");
+    for (const key of Object.keys(input))
+        if (key !== "scene" && key !== "aspect")
+            throw new InvalidConfigurationError("resolveChartScene input has unknown field \"" + key + "\".");
+    const { scene, aspect } = input;
+    requireInputObject(scene, "chart scene");
+    if (typeof aspect !== "number" || !Number.isFinite(aspect) || aspect <= 0)
+        throw new InvalidConfigurationError("Chart aspect must be positive.");
+    const preset = scene.preset;
+    if (typeof preset !== "string" || !CHART_SCENE_PRESETS.includes(preset))
+        throw new InvalidConfigurationError("Unknown chart preset.");
+    const record = scene;
+    const defaults = CHART_SCENE_DEFAULTS[preset];
+    const allowed = ["preset", ...Object.keys(defaults), ...(preset === "patches" ? ["patches", "columns"] : [])];
+    for (const key of Object.keys(record))
+        if (!allowed.includes(key))
+            throw new InvalidConfigurationError("Unknown chart parameter: " + key + ".");
+    const defaulted = [];
+    const get = (key) => { if (record[key] === undefined) {
+        if (key in defaults)
+            defaulted.push(key);
+        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;
+        } });
+    switch (preset) {
+        case "uniform": {
+            const raw = get("reflectance"), m = material(raw, "reflectance");
+            return done({ reflectance: typeof raw === "number" ? raw : "caller-spectrum" }, [m], () => 0);
+        }
+        case "slanted-edge": {
+            const angle = finiteIn(get("angleDegrees"), "angleDegrees", -45, 45, true), dark = neutral("darkReflectance"), light = neutral("lightReflectance");
+            const t = angle * Math.PI / 180, c = Math.cos(t), s = Math.sin(t);
+            // Edge through the frame centre along (sin t, cos t); the light side is to the right.
+            return done({ angleDegrees: angle, darkReflectance: dark, lightReflectance: light }, [{ kind: "neutral", reflectance: dark }, { kind: "neutral", reflectance: light }], (u, v) => (u * c - v * s >= 0 ? 1 : 0));
+        }
+        case "siemens-star": {
+            const cycles = integerIn(get("cycles"), "cycles", 2, 360), radius = finiteIn(get("radiusFraction"), "radiusFraction", 0, 1, false);
+            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) => {
+                if (u * u + v * v > r * r)
+                    return 2;
+                const phase = Math.atan2(v, u) / (2 * Math.PI) + 0.5; // [0, 1]
+                return Math.floor(phase * 2 * cycles) % 2 === 0 ? 1 : 0;
+            });
+        }
+        case "step-wedge": {
+            const steps = integerIn(get("steps"), "steps", 2, 64), lo = neutral("minimumReflectance"), hi = neutral("maximumReflectance"), spacing = get("spacing");
+            if (spacing !== "equal-density" && spacing !== "linear")
+                throw new InvalidConfigurationError("spacing must be equal-density or linear.");
+            if (!(hi > lo) || (spacing === "equal-density" && lo <= 0))
+                throw new InvalidConfigurationError("Step wedge needs 0 < minimum < maximum reflectance.");
+            const values = calculateStepWedgeReflectances({ steps, minimumReflectance: lo, maximumReflectance: hi, spacing });
+            return done({ steps, minimumReflectance: lo, maximumReflectance: hi, spacing, stepReflectances: values }, values.map((reflectanceValue) => ({ kind: "neutral", reflectance: reflectanceValue })), (u) => Math.min(steps - 1, Math.max(0, Math.floor((u + 1) / 2 * steps))));
+        }
+        case "grey-ramp": {
+            const lo = neutral("minimumReflectance"), hi = neutral("maximumReflectance");
+            if (!(hi > lo))
+                throw new InvalidConfigurationError("Grey ramp needs minimum < maximum reflectance.");
+            // A continuous ramp is stored as 1024 neutral levels. The step size (< 0.1 % of the range) is far below sensor noise.
+            const levels = 1024, materials = Array.from({ length: levels }, (_, i) => ({ kind: "neutral", reflectance: lo + (hi - lo) * (i + 0.5) / levels }));
+            return done({ minimumReflectance: lo, maximumReflectance: hi, representation: "1024 equal neutral levels" }, materials, (u) => Math.min(levels - 1, Math.max(0, Math.floor((u + 1) / 2 * levels))));
+        }
+        case "checkerboard": {
+            const across = integerIn(get("squaresAcross"), "squaresAcross", 2, 256), dark = neutral("darkReflectance"), light = neutral("lightReflectance"), size = 2 / across;
+            return done({ squaresAcross: across, darkReflectance: dark, lightReflectance: light }, [{ kind: "neutral", reflectance: dark }, { kind: "neutral", reflectance: light }], (u, v) => ((Math.floor((u + 1) / size) + Math.floor((aspect - v) / size)) % 2 === 0 ? 1 : 0));
+        }
+        case "point-grid": {
+            const columns = integerIn(get("columns"), "columns", 1, 256), rows = integerIn(get("rows"), "rows", 1, 256);
+            const radius = finiteIn(get("radius"), "radius", 0, 1, true), point = neutral("pointReflectance"), background = neutral("backgroundReflectance");
+            const centers = calculatePointGridCenters({ columns, rows, aspect });
+            const cellW = 2 / columns, cellH = 2 * aspect / rows;
+            return done({ columns, rows, radius, pointReflectance: point, backgroundReflectance: background }, [{ kind: "neutral", reflectance: background }, { kind: "neutral", reflectance: point }], (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 c = centers[j * columns + i];
+                return (u - c.u) ** 2 + (v - c.v) ** 2 <= radius * radius ? 1 : 0;
+            });
+        }
+        case "patches": {
+            const list = record.patches;
+            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 = [];
+            for (const [index, patch] of list.entries()) {
+                requireInputObject(patch, "patches[" + index + "]");
+                const p = patch;
+                for (const key of Object.keys(p))
+                    if (key !== "patchId" && key !== "reflectance")
+                        throw new InvalidConfigurationError("Unknown patch field: " + key + ".");
+                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(material(p.reflectance, "patches[" + index + "].reflectance"));
+            }
+            const columnsRaw = record.columns === undefined ? Math.ceil(Math.sqrt(list.length)) : record.columns;
+            if (record.columns === undefined)
+                defaulted.push("columns");
+            const columns = integerIn(columnsRaw, "columns", 1, list.length), rows = Math.ceil(list.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 });
+            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;
+            });
+        }
+    }
+}
+/**
+ * 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.
+ */
+export function calculateStepWedgeReflectances(input) {
+    requireInputKeys(input, "calculateStepWedgeReflectances", ["steps", "minimumReflectance", "maximumReflectance", "spacing"]);
+    const steps = integerIn(input.steps, "steps", 2, 64), lo = reflectance(input.minimumReflectance, "minimumReflectance"), hi = reflectance(input.maximumReflectance, "maximumReflectance");
+    if (input.spacing !== "equal-density" && input.spacing !== "linear")
+        throw new InvalidConfigurationError("spacing must be equal-density or linear.");
+    if (!(hi > lo) || (input.spacing === "equal-density" && lo <= 0))
+        throw new InvalidConfigurationError("Step wedge needs 0 < minimum < maximum reflectance.");
+    return Array.from({ length: steps }, (_, k) => {
+        if (k === steps - 1)
+            return hi;
+        const t = k / (steps - 1);
+        return input.spacing === "linear" ? lo + (hi - lo) * t : lo * (hi / lo) ** t;
+    });
+}
+/** Centres (frame units) of a point grid: one disk centred in each of columns × rows equal cells, row-major from the top-left. */
+export function calculatePointGridCenters(input) {
+    requireInputKeys(input, "calculatePointGridCenters", ["columns", "rows", "aspect"]);
+    const columns = integerIn(input.columns, "columns", 1, 256), rows = integerIn(input.rows, "rows", 1, 256);
+    if (typeof input.aspect !== "number" || !Number.isFinite(input.aspect) || input.aspect <= 0)
+        throw new InvalidConfigurationError("aspect must be positive.");
+    const out = [];
+    for (let j = 0; j < rows; j++)
+        for (let i = 0; i < columns; i++)
+            out.push({ u: -1 + (i + 0.5) * 2 / columns, v: input.aspect - (j + 0.5) * 2 * input.aspect / rows });
+    return out;
+}
+//# sourceMappingURL=chart-scenes.js.map

package/dist/facade/chart-scenes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-scenes.js","sourceRoot":"","sources":["../../src/facade/chart-scenes.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Procedural test charts for the capture facade, written for this engine. Every chart is a flat,\n * Lambertian (matte) reflectance pattern, defined by formulas in normalized frame coordinates. No\n * third-party chart data (for example ColorChecker reflectances) is bundled. Coloured patches use\n * spectra that the caller supplies.\n *\n * Frame coordinates: `u` runs from -1 (left edge of the framed chart) to +1 (right edge); `v` points up\n * and has the same scale, so it runs from -aspect to +aspect where aspect = height/width of the frame.\n * The facade places the chart perpendicular to the optical axis at the subject distance and sizes it so\n * that this rectangle exactly fills the active capture (see `SimulateCaptureResult.assumptions`).\n *\n * The slanted edge follows the geometry described by P. D. Burns, \"Slanted-Edge MTF for Digital Camera\n * and Scanner Analysis\", IS&T PICS 2000 (free from imaging.org; also ISO 12233). It is a near-vertical\n * edge rotated by a few degrees (5 degrees by default), with a 4:1 light/dark reflectance ratio by\n * default. This is only a geometric description. No measured chart or ISO test procedure is copied.\n * @see docs/QUICK_START.md for the chart catalogue and their analytic definitions.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { prepareColorimetricSpectrum, type ColorimetricSpectrum, type PreparedColorimetricSpectrum } from \"../color/color-matching-functions.js\";\nimport { requireInputObject, requireInputKeys } from \"../core/record-validation.js\";\n\n/** A neutral (spectrally flat) reflectance in [0, 1], or a caller reflectance spectrum (values in [0, 1]). */\nexport type ChartReflectance = number | ColorimetricSpectrum;\n\nexport interface UniformChartScene { preset: \"uniform\"; reflectance?: ChartReflectance }\nexport interface SlantedEdgeChartScene {\n  preset: \"slanted-edge\";\n  /** Clockwise tilt of the edge from vertical, degrees, in (-45, 45). Default 5. */\n  angleDegrees?: number;\n  /** Left (dark) side reflectance. Default 0.15. */\n  darkReflectance?: number;\n  /** Right (light) side reflectance. Default 0.6 (4:1 with the default dark side). */\n  lightReflectance?: number;\n}\nexport interface SiemensStarChartScene {\n  preset: \"siemens-star\";\n  /** Light/dark sector pairs around the star, 2..360. Default 36. */\n  cycles?: number;\n  /** Star radius as a fraction of the frame half-height, (0, 1]. Default 0.9. */\n  radiusFraction?: number;\n  darkReflectance?: number;\n  lightReflectance?: number;\n  /** Reflectance outside the star. Default 0.18. */\n  backgroundReflectance?: number;\n}\nexport interface StepWedgeChartScene {\n  preset: \"step-wedge\";\n  /** Number of equal-width vertical steps from left (minimum) to right (maximum), 2..64. Default 11. */\n  steps?: number;\n  minimumReflectance?: number;\n  maximumReflectance?: number;\n  /** `equal-density` (geometric, default) or `linear` reflectance spacing. */\n  spacing?: \"equal-density\" | \"linear\";\n}\nexport interface GreyRampChartScene {\n  preset: \"grey-ramp\";\n  /** Continuous ramp, linear in reflectance from left (minimum) to right (maximum). */\n  minimumReflectance?: number;\n  maximumReflectance?: number;\n}\nexport interface CheckerboardChartScene {\n  preset: \"checkerboard\";\n  /** Squares across the frame width, 2..256. Default 8. */\n  squaresAcross?: number;\n  darkReflectance?: number;\n  lightReflectance?: number;\n}\nexport interface PointGridChartScene {\n  preset: \"point-grid\";\n  /** Grid columns and rows of small disks centred in equal cells. Defaults 5 × 3. */\n  columns?: number;\n  rows?: number;\n  /** Disk radius in frame units (fraction of the frame half-width). Default 0.01. */\n  radius?: number;\n  pointReflectance?: number;\n  backgroundReflectance?: number;\n}\nexport interface PatchChartScene {\n  preset: \"patches\";\n  /** Caller reflectance per patch, row-major; the facade bundles no colour-chart data. 1..1024 patches. */\n  patches: readonly { patchId: string; reflectance: ChartReflectance }[];\n  /** Patches per row. Default ceil(sqrt(patch count)). */\n  columns?: number;\n  /** Gap between patches as a fraction of the cell size, [0, 0.5). Default 0.1. */\n  gapFraction?: number;\n  backgroundReflectance?: number;\n}\nexport type ChartScene = UniformChartScene | SlantedEdgeChartScene | SiemensStarChartScene | StepWedgeChartScene |\n  GreyRampChartScene | CheckerboardChartScene | PointGridChartScene | PatchChartScene;\nexport type ChartScenePresetId = ChartScene[\"preset\"];\nexport const CHART_SCENE_PRESETS: readonly ChartScenePresetId[] = Object.freeze([\"uniform\", \"slanted-edge\", \"siemens-star\",\n  \"step-wedge\", \"grey-ramp\", \"checkerboard\", \"point-grid\", \"patches\"] as const);\n\n/** Engine-chosen chart parameters, each reported when the caller omitted it. */\nexport const CHART_SCENE_DEFAULTS = Object.freeze({\n  uniform: Object.freeze({ reflectance: 0.18 }),\n  \"slanted-edge\": Object.freeze({ angleDegrees: 5, darkReflectance: 0.15, lightReflectance: 0.6 }),\n  \"siemens-star\": Object.freeze({ cycles: 36, radiusFraction: 0.9, darkReflectance: 0.05, lightReflectance: 0.8, backgroundReflectance: 0.18 }),\n  \"step-wedge\": Object.freeze({ steps: 11, minimumReflectance: 0.03, maximumReflectance: 0.9, spacing: \"equal-density\" as const }),\n  \"grey-ramp\": Object.freeze({ minimumReflectance: 0.03, maximumReflectance: 0.9 }),\n  checkerboard: Object.freeze({ squaresAcross: 8, darkReflectance: 0.05, lightReflectance: 0.8 }),\n  \"point-grid\": Object.freeze({ columns: 5, rows: 3, radius: 0.01, pointReflectance: 0.9, backgroundReflectance: 0.02 }),\n  patches: Object.freeze({ gapFraction: 0.1, backgroundReflectance: 0.18 })\n});\n\n/** A validated chart: every parameter resolved, plus which ones came from {@link CHART_SCENE_DEFAULTS}. */\nexport interface ResolvedChartScene {\n  preset: ChartScenePresetId;\n  /** Fully resolved parameters (spectra are reported as `\"caller-spectrum\"`). */\n  parameters: Readonly<Record<string, unknown>>;\n  /** Names of parameters filled from defaults. */\n  defaultedParameters: readonly string[];\n  /** Frame aspect (height / width) the chart was resolved for. */\n  aspect: number;\n  /**\n   * Material index at a frame point (u right, v up). The index points into `materials`, starting at 0.\n   * Points outside the framed rectangle still evaluate (the pattern continues as defined), so blur and\n   * small framing differences stay well defined.\n   */\n  materialAt(u: number, v: number): number;\n  /** Reflectance materials: a neutral number or a prepared caller spectrum. */\n  materials: readonly ({ kind: \"neutral\"; reflectance: number } | { kind: \"spectrum\"; spectrum: PreparedColorimetricSpectrum })[];\n  /** Reflectance in [0, 1] at a frame point and wavelength (nm). */\n  reflectanceAt(u: number, v: number, wavelengthNanometers: number): number;\n}\n\nfunction reflectance(value: unknown, name: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value < 0 || value > 1) throw new InvalidConfigurationError(name + \" must be a reflectance in [0, 1].\");\n  return value;\n}\nfunction integerIn(value: unknown, name: string, minimum: number, maximum: number): number {\n  if (typeof value !== \"number\" || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new InvalidConfigurationError(name + \" must be an integer from \" + minimum + \" to \" + maximum + \".\");\n  return value;\n}\nfunction finiteIn(value: unknown, name: string, minimum: number, maximum: number, open = false): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value < minimum || value > maximum || (open && (value === minimum || value === maximum)))\n    throw new InvalidConfigurationError(name + \" is outside its supported range.\");\n  return value;\n}\n/** Wavelength range every chart spectrum must cover (the facade's sensor quadrature range). */\nexport const CHART_SPECTRAL_RANGE_NANOMETERS = Object.freeze({ minimum: 380, maximum: 780 });\nfunction material(value: unknown, name: string): ResolvedChartScene[\"materials\"][number] {\n  if (typeof value === \"number\") return { kind: \"neutral\", reflectance: reflectance(value, name) };\n  let spectrum: PreparedColorimetricSpectrum;\n  try { spectrum = prepareColorimetricSpectrum(value as ColorimetricSpectrum, name); } catch (error) {\n    throw new InvalidConfigurationError(name + \" must be a neutral reflectance or a valid reflectance spectrum: \" + (error instanceof Error ? error.message : \"invalid\"));\n  }\n  const range = spectrum.wavelengthRangeNanometers;\n  if (range.minimum > CHART_SPECTRAL_RANGE_NANOMETERS.minimum || range.maximum < CHART_SPECTRAL_RANGE_NANOMETERS.maximum)\n    throw new InvalidConfigurationError(name + \" must cover 380-780 nm.\");\n  for (let nm = CHART_SPECTRAL_RANGE_NANOMETERS.minimum; nm <= CHART_SPECTRAL_RANGE_NANOMETERS.maximum; nm += 5) reflectance(spectrum.evaluate(nm), name + \" values\");\n  return { kind: \"spectrum\", spectrum };\n}\n\n/**\n * Validates a chart description and resolves every default. `aspect` is the frame height/width. Unknown\n * fields are rejected so that a mistyped parameter never silently falls back to a default.\n */\nexport function resolveChartScene(input: { scene: ChartScene; aspect: number }): ResolvedChartScene {\n  requireInputObject(input, \"resolveChartScene input\");\n  for (const key of Object.keys(input)) if (key !== \"scene\" && key !== \"aspect\") throw new InvalidConfigurationError(\"resolveChartScene input has unknown field \\\"\" + key + \"\\\".\");\n  const { scene, aspect } = input;\n  requireInputObject(scene, \"chart scene\");\n  if (typeof aspect !== \"number\" || !Number.isFinite(aspect) || aspect <= 0) throw new InvalidConfigurationError(\"Chart aspect must be positive.\");\n  const preset = (scene as { preset?: unknown }).preset;\n  if (typeof preset !== \"string\" || !(CHART_SCENE_PRESETS as readonly string[]).includes(preset)) throw new InvalidConfigurationError(\"Unknown chart preset.\");\n  const record = scene as unknown as Record<string, unknown>;\n  const defaults = CHART_SCENE_DEFAULTS[preset as ChartScenePresetId] as Record<string, unknown>;\n  const allowed = [\"preset\", ...Object.keys(defaults), ...(preset === \"patches\" ? [\"patches\", \"columns\"] : [])];\n  for (const key of Object.keys(record)) if (!allowed.includes(key)) throw new InvalidConfigurationError(\"Unknown chart parameter: \" + key + \".\");\n  const defaulted: string[] = [];\n  const get = (key: string): unknown => { if (record[key] === undefined) { if (key in defaults) defaulted.push(key); return defaults[key]; } return record[key]; };\n  const neutral = (key: string): number => reflectance(get(key), key);\n  const done = (parameters: Record<string, unknown>, materials: ResolvedChartScene[\"materials\"], materialAt: (u: number, v: number) => number): ResolvedChartScene =>\n    Object.freeze({ preset: preset as ChartScenePresetId, parameters: Object.freeze(parameters), defaultedParameters: Object.freeze(defaulted), aspect, materials: Object.freeze(materials), materialAt,\n      reflectanceAt(u: number, v: number, nm: number): number {\n        const m = materials[materialAt(u, v)]!;\n        if (m.kind === \"neutral\") return m.reflectance;\n        const value = m.spectrum.evaluate(nm);\n        if (!(value >= 0 && value <= 1)) throw new InvalidConfigurationError(\"Chart reflectance spectrum left [0, 1].\");\n        return value;\n      } });\n  switch (preset as ChartScenePresetId) {\n    case \"uniform\": {\n      const raw = get(\"reflectance\"), m = material(raw, \"reflectance\");\n      return done({ reflectance: typeof raw === \"number\" ? raw : \"caller-spectrum\" }, [m], () => 0);\n    }\n    case \"slanted-edge\": {\n      const angle = finiteIn(get(\"angleDegrees\"), \"angleDegrees\", -45, 45, true), dark = neutral(\"darkReflectance\"), light = neutral(\"lightReflectance\");\n      const t = angle * Math.PI / 180, c = Math.cos(t), s = Math.sin(t);\n      // Edge through the frame centre along (sin t, cos t); the light side is to the right.\n      return done({ angleDegrees: angle, darkReflectance: dark, lightReflectance: light },\n        [{ kind: \"neutral\", reflectance: dark }, { kind: \"neutral\", reflectance: light }], (u, v) => (u * c - v * s >= 0 ? 1 : 0));\n    }\n    case \"siemens-star\": {\n      const cycles = integerIn(get(\"cycles\"), \"cycles\", 2, 360), radius = finiteIn(get(\"radiusFraction\"), \"radiusFraction\", 0, 1, false);\n      if (radius === 0) throw new InvalidConfigurationError(\"radiusFraction must be positive.\");\n      const dark = neutral(\"darkReflectance\"), light = neutral(\"lightReflectance\"), background = neutral(\"backgroundReflectance\"), r = radius * aspect;\n      return done({ cycles, radiusFraction: radius, darkReflectance: dark, lightReflectance: light, backgroundReflectance: background },\n        [{ kind: \"neutral\", reflectance: dark }, { kind: \"neutral\", reflectance: light }, { kind: \"neutral\", reflectance: background }], (u, v) => {\n          if (u * u + v * v > r * r) return 2;\n          const phase = Math.atan2(v, u) / (2 * Math.PI) + 0.5; // [0, 1]\n          return Math.floor(phase * 2 * cycles) % 2 === 0 ? 1 : 0;\n        });\n    }\n    case \"step-wedge\": {\n      const steps = integerIn(get(\"steps\"), \"steps\", 2, 64), lo = neutral(\"minimumReflectance\"), hi = neutral(\"maximumReflectance\"), spacing = get(\"spacing\");\n      if (spacing !== \"equal-density\" && spacing !== \"linear\") throw new InvalidConfigurationError(\"spacing must be equal-density or linear.\");\n      if (!(hi > lo) || (spacing === \"equal-density\" && lo <= 0)) throw new InvalidConfigurationError(\"Step wedge needs 0 < minimum < maximum reflectance.\");\n      const values = calculateStepWedgeReflectances({ steps, minimumReflectance: lo, maximumReflectance: hi, spacing });\n      return done({ steps, minimumReflectance: lo, maximumReflectance: hi, spacing, stepReflectances: values },\n        values.map((reflectanceValue) => ({ kind: \"neutral\" as const, reflectance: reflectanceValue })),\n        (u) => Math.min(steps - 1, Math.max(0, Math.floor((u + 1) / 2 * steps))));\n    }\n    case \"grey-ramp\": {\n      const lo = neutral(\"minimumReflectance\"), hi = neutral(\"maximumReflectance\");\n      if (!(hi > lo)) throw new InvalidConfigurationError(\"Grey ramp needs minimum < maximum reflectance.\");\n      // A continuous ramp is stored as 1024 neutral levels. The step size (< 0.1 % of the range) is far below sensor noise.\n      const levels = 1024, materials = Array.from({ length: levels }, (_, i) => ({ kind: \"neutral\" as const, reflectance: lo + (hi - lo) * (i + 0.5) / levels }));\n      return done({ minimumReflectance: lo, maximumReflectance: hi, representation: \"1024 equal neutral levels\" }, materials,\n        (u) => Math.min(levels - 1, Math.max(0, Math.floor((u + 1) / 2 * levels))));\n    }\n    case \"checkerboard\": {\n      const across = integerIn(get(\"squaresAcross\"), \"squaresAcross\", 2, 256), dark = neutral(\"darkReflectance\"), light = neutral(\"lightReflectance\"), size = 2 / across;\n      return done({ squaresAcross: across, darkReflectance: dark, lightReflectance: light },\n        [{ kind: \"neutral\", reflectance: dark }, { kind: \"neutral\", reflectance: light }],\n        (u, v) => ((Math.floor((u + 1) / size) + Math.floor((aspect - v) / size)) % 2 === 0 ? 1 : 0));\n    }\n    case \"point-grid\": {\n      const columns = integerIn(get(\"columns\"), \"columns\", 1, 256), rows = integerIn(get(\"rows\"), \"rows\", 1, 256);\n      const radius = finiteIn(get(\"radius\"), \"radius\", 0, 1, true), point = neutral(\"pointReflectance\"), background = neutral(\"backgroundReflectance\");\n      const centers = calculatePointGridCenters({ columns, rows, aspect });\n      const cellW = 2 / columns, cellH = 2 * aspect / rows;\n      return done({ columns, rows, radius, pointReflectance: point, backgroundReflectance: background },\n        [{ kind: \"neutral\", reflectance: background }, { kind: \"neutral\", reflectance: point }], (u, v) => {\n          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)));\n          const c = centers[j * columns + i]!;\n          return (u - c.u) ** 2 + (v - c.v) ** 2 <= radius * radius ? 1 : 0;\n        });\n    }\n    case \"patches\": {\n      const list = record.patches;\n      if (!Array.isArray(list) || list.length < 1 || list.length > 1024) throw new InvalidConfigurationError(\"patches must list 1 to 1024 caller reflectances.\");\n      const ids = new Set<string>();\n      const materials: ResolvedChartScene[\"materials\"][number][] = [];\n      for (const [index, patch] of list.entries()) {\n        requireInputObject(patch, \"patches[\" + index + \"]\");\n        const p = patch as Record<string, unknown>;\n        for (const key of Object.keys(p)) if (key !== \"patchId\" && key !== \"reflectance\") throw new InvalidConfigurationError(\"Unknown patch field: \" + key + \".\");\n        if (typeof p.patchId !== \"string\" || p.patchId.trim() === \"\" || ids.has(p.patchId)) throw new InvalidConfigurationError(\"Each patch needs a unique non-empty patchId.\");\n        ids.add(p.patchId);\n        materials.push(material(p.reflectance, \"patches[\" + index + \"].reflectance\"));\n      }\n      const columnsRaw = record.columns === undefined ? Math.ceil(Math.sqrt(list.length)) : record.columns;\n      if (record.columns === undefined) defaulted.push(\"columns\");\n      const columns = integerIn(columnsRaw, \"columns\", 1, list.length), rows = Math.ceil(list.length / columns);\n      const gap = finiteIn(get(\"gapFraction\"), \"gapFraction\", 0, 0.5), background = neutral(\"backgroundReflectance\");\n      if (gap >= 0.5) throw new InvalidConfigurationError(\"gapFraction must be below 0.5.\");\n      const backgroundIndex = materials.length;\n      materials.push({ kind: \"neutral\", reflectance: background });\n      const cellW = 2 / columns, cellH = 2 * aspect / rows;\n      return done({ patchIds: list.map((p: { patchId: string }) => p.patchId), columns, rows, gapFraction: gap, backgroundReflectance: background }, materials, (u, v) => {\n        const fx = (u + 1) / cellW, fy = (aspect - v) / cellH, i = Math.floor(fx), j = Math.floor(fy);\n        if (i < 0 || j < 0 || i >= columns || j >= rows) return backgroundIndex;\n        const index = j * columns + i, x = fx - i, y = fy - j;\n        if (index >= list.length || x < gap / 2 || x > 1 - gap / 2 || y < gap / 2 || y > 1 - gap / 2) return backgroundIndex;\n        return index;\n      });\n    }\n  }\n}\n\n/**\n * Step reflectances of a step wedge. `equal-density` spaces optical density D = -log10(R) evenly, which\n * gives geometric reflectance steps, as on a photographic step tablet. `linear` spaces reflectance evenly.\n */\nexport function calculateStepWedgeReflectances(input: { steps: number; minimumReflectance: number; maximumReflectance: number;\n  spacing: \"equal-density\" | \"linear\" }): number[] {\n  requireInputKeys(input, \"calculateStepWedgeReflectances\", [\"steps\", \"minimumReflectance\", \"maximumReflectance\", \"spacing\"]);\n  const steps = integerIn(input.steps, \"steps\", 2, 64), lo = reflectance(input.minimumReflectance, \"minimumReflectance\"), hi = reflectance(input.maximumReflectance, \"maximumReflectance\");\n  if (input.spacing !== \"equal-density\" && input.spacing !== \"linear\") throw new InvalidConfigurationError(\"spacing must be equal-density or linear.\");\n  if (!(hi > lo) || (input.spacing === \"equal-density\" && lo <= 0)) throw new InvalidConfigurationError(\"Step wedge needs 0 < minimum < maximum reflectance.\");\n  return Array.from({ length: steps }, (_, k) => {\n    if (k === steps - 1) return hi;\n    const t = k / (steps - 1);\n    return input.spacing === \"linear\" ? lo + (hi - lo) * t : lo * (hi / lo) ** t;\n  });\n}\n\n/** Centres (frame units) of a point grid: one disk centred in each of columns × rows equal cells, row-major from the top-left. */\nexport function calculatePointGridCenters(input: { columns: number; rows: number; aspect: number }): { u: number; v: number }[] {\n  requireInputKeys(input, \"calculatePointGridCenters\", [\"columns\", \"rows\", \"aspect\"]);\n  const columns = integerIn(input.columns, \"columns\", 1, 256), rows = integerIn(input.rows, \"rows\", 1, 256);\n  if (typeof input.aspect !== \"number\" || !Number.isFinite(input.aspect) || input.aspect <= 0) throw new InvalidConfigurationError(\"aspect must be positive.\");\n  const out: { u: number; v: number }[] = [];\n  for (let j = 0; j < rows; j++) for (let i = 0; i < columns; i++) out.push({ u: -1 + (i + 0.5) * 2 / columns, v: input.aspect - (j + 0.5) * 2 * input.aspect / rows });\n  return out;\n}\n"]}

package/dist/facade/diffraction-provider.d.ts

@@ -0,0 +1,30 @@
+import type { ResolveLensSampledPsfInput } from "../optics/lens-psf-profile.js";
+import type { PlanarSceneRadianceProvider } from "./scene-radiance.js";
+export interface DiffractedPlanarProviderInput {
+    base: PlanarSceneRadianceProvider;
+    /** The optical state of the sampled PSF, as for `resolveLensSampledPsf`, without field point and wavelength. */
+    psf: Omit<ResolveLensSampledPsfInput, "fieldPointMm" | "wavelengthNm">;
+    /** Spectral nodes the environment queries (the profile's wavelength nodes). */
+    wavelengthsNm: readonly number[];
+    kernelRadius: number;
+    nativeWidth: number;
+    nativeHeight: number;
+    /** Output (active) width in sites: frame units are 2/outputWidth per site. */
+    outputWidth: number;
+    sitePitchMicrometers: number;
+    /** Planar geometry of the base provider, to map query directions to plane points exactly as it does. */
+    distanceM: number;
+    metresPerFrameUnit: number;
+    /**
+     * Offsets of the query points from the site centres, in sites (+x right, +y down): the anti-aliasing split
+     * offsets with their sign reversed (the environment queries q − a). Default: one zero offset.
+     */
+    queryOffsetsSites?: readonly {
+        x: number;
+        y: number;
+    }[];
+    /** Called with the duration in ms of each band convolution (diagnostics only; never changes values). */
+    onConvolution?: (milliseconds: number) => void;
+}
+/** Internal (not exported from the package): the base provider with diffraction applied as an object-space convolution. */
+export declare function createDiffractedPlanarProvider(input: DiffractedPlanarProviderInput): PlanarSceneRadianceProvider;

package/dist/facade/diffraction-provider.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Fast execution of `simulateCapture`'s `lens.diffraction` (2.1): an object-space convolution in the scene
+ * provider, instead of one scene query per PSF tap in the environment PSF quadrature.
+ *
+ * The environment quadrature computes, at each site centre q and spectral node λ,
+ *   E(q, λ) = Σ_k K_λ(k)·T·L(s_k(q), λ),
+ * where s_k(q) is the tap's source point (`sensorPsfSourcePoint`), L the scene radiance at the plane point
+ * that source point sees, and T the radiance-to-irradiance factor. For the facade's planar scene seen
+ * through the ideal rectilinear projection with a still camera and no lens field mapping, field throughput or
+ * pupil rays:
+ * - T is the same at every sensor point (paraxial π/(4·N_w²), no cos⁴ term), and
+ * - with the kernel sampled on the site pitch, every source point is the centre of another site, so the plane
+ *   points form one regular lattice: u = (i + ½ − W/2)·2/w, v = −(j + ½ − H/2)·2/w (frame units, native
+ *   site (i, j), W×H native sites, w output width).
+ * So E(q, λ) = T·B(q, λ) with B = K_λ ⊛ L sampled on that lattice: the same sum, in a different floating-point
+ * order. B is computed once per spectral node with the engine's isoplanatic convolution
+ * (`calculateIrradianceConvolution`, kernels from `resolveLensPsfConvolutionKernels`, exact site sampling) over a
+ * grid that holds every source (the native raster plus the kernel radius on each side), in row bands. The
+ * provider then answers each site-centre query with B instead of L, and the environment request declares no
+ * PSF. Incoherent imaging is a linear superposition of intensity PSFs, so convolving radiance on the object
+ * plane and convolving irradiance on the image plane agree for a planar object and a space-invariant PSF
+ * (MIT OpenCourseWare 2.71, lecture 22, free; also see: Goodman, Introduction to Fourier Optics, 4th ed., §6.1).
+ *
+ * With an anti-aliasing point-splitting filter (2.1, `sensor.antiAliasing`) the environment queries the PSF taps
+ * around each pre-filter source point q − a (a = a split offset) instead of around q. Those taps lie on the site
+ * lattice shifted by a, so the same argument holds on each shifted lattice: B is computed once per distinct
+ * fractional shift (offsets that differ by whole sites share one lattice; the centred four-spot filter with a
+ * one-site separation needs a single half-site-shifted lattice) over the native raster widened by the largest
+ * offset, and the environment's spatial quadrature still forms the weighted split sum.
+ *
+ * A query that does not land on one of the lattices (within 1e-6 site) is refused rather than approximated: the
+ * facade uses this path only when the lattice argument above holds.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { calculateIrradianceConvolution } from "../optics/irradiance-convolution.js";
+import { resolveLensPsfConvolutionKernels } from "../optics/lens-psf-kernels.js";
+/** Rows of native sites per convolution band, and the bands kept. Banding changes memory only, never values. */
+const BAND_ROWS = 32;
+const CACHED_BANDS = 4;
+const LATTICE_TOLERANCE_SITES = 1e-6;
+/** Internal (not exported from the package): the base provider with diffraction applied as an object-space convolution. */
+export function createDiffractedPlanarProvider(input) {
+    const { base, wavelengthsNm, nativeWidth: W, nativeHeight: H, kernelRadius: R } = input;
+    const g = 2 / input.outputWidth, pitch = input.sitePitchMicrometers;
+    const index = new Map(wavelengthsNm.map((nm, i) => [nm, i]));
+    // One lattice per distinct fractional query offset; M extra sites per side hold the offset queries.
+    const offsets = input.queryOffsetsSites ?? [{ x: 0, y: 0 }];
+    const fraction = (value) => { const f = value - Math.floor(value); return f > 1 - LATTICE_TOLERANCE_SITES ? 0 : f < LATTICE_TOLERANCE_SITES ? 0 : f; };
+    const shifts = [];
+    for (const o of offsets) {
+        const f = { x: fraction(o.x), y: fraction(o.y) };
+        if (!shifts.some((s) => Math.abs(s.x - f.x) <= LATTICE_TOLERANCE_SITES && Math.abs(s.y - f.y) <= LATTICE_TOLERANCE_SITES))
+            shifts.push(f);
+    }
+    const M = Math.max(0, ...offsets.map((o) => Math.ceil(Math.max(Math.abs(o.x), Math.abs(o.y)) - LATTICE_TOLERANCE_SITES)));
+    const LW = W + 2 * M, LH = H + 2 * M;
+    // One kernel per wavelength, on the site grid, from the engine's own tap-to-site mapping (field point 0, 0).
+    const kernels = wavelengthsNm.map((wavelengthNm) => {
+        const k = resolveLensPsfConvolutionKernels({ schemaVersion: "0.1.0", psf: input.psf, spectralWeights: [{ wavelengthNm, weight: 1 }],
+            grid: { width: 1, height: 1, sitePitchMicrometers: { x: pitch, y: pitch }, opticalAxisSite: { x: 0.5, y: 0.5 } }, patchWidth: 1, patchHeight: 1,
+            kernelRadius: R }).value;
+        if (!k.exactSiteSampling || k.kernelRadius !== R)
+            throw new InvalidConfigurationError("Diffraction kernels must sample the site pitch exactly.");
+        return k.kernels;
+    });
+    const gridWidth = LW + 2 * R;
+    const now = () => globalThis.performance?.now() ?? Date.now();
+    const bands = new Map();
+    function band(b) {
+        const cached = bands.get(b);
+        if (cached) {
+            bands.delete(b);
+            bands.set(b, cached);
+            return cached;
+        }
+        const started = input.onConvolution ? now() : 0;
+        const y0 = b * BAND_ROWS, rows = Math.min(BAND_ROWS, LH - y0), gridHeight = rows + 2 * R;
+        const values = shifts.map((shift) => wavelengthsNm.map((nm, w) => {
+            const samples = new Float64Array(gridWidth * gridHeight);
+            for (let gy = 0; gy < gridHeight; gy++) {
+                const v = shift.y === 0 ? -(y0 + gy - R - M + 0.5 - H / 2) * g : -(y0 + gy - R - M + 0.5 + shift.y - H / 2) * g;
+                for (let gx = 0; gx < gridWidth; gx++)
+                    samples[gy * gridWidth + gx] = base.radianceAt(shift.x === 0 ? (gx - R - M + 0.5 - W / 2) * g : (gx - R - M + 0.5 + shift.x - W / 2) * g, v, nm);
+            }
+            const blurred = calculateIrradianceConvolution({ schemaVersion: "0.1.0", width: gridWidth, height: gridHeight, samples, kernelRadius: R,
+                patchWidth: gridWidth, patchHeight: gridHeight, kernels: kernels[w], boundary: "zero-outside-grid" }).values;
+            const out = new Float64Array(LW * rows);
+            for (let y = 0; y < rows; y++)
+                out.set(blurred.subarray((y + R) * gridWidth + R, (y + R) * gridWidth + R + LW), y * LW);
+            return out;
+        }));
+        bands.set(b, values);
+        if (bands.size > CACHED_BANDS)
+            bands.delete(bands.keys().next().value);
+        if (input.onConvolution)
+            input.onConvolution(now() - started);
+        return values;
+    }
+    function blurredAt(u, v, nm) {
+        const w = index.get(nm), fi = u / g - 0.5 + W / 2, fj = -v / g - 0.5 + H / 2;
+        if (w !== undefined)
+            for (let s = 0; s < shifts.length; s++) {
+                const shift = shifts[s], i = Math.round(fi - shift.x), j = Math.round(fj - shift.y);
+                if (Math.abs(fi - shift.x - i) > LATTICE_TOLERANCE_SITES || Math.abs(fj - shift.y - j) > LATTICE_TOLERANCE_SITES)
+                    continue;
+                if (i < -M || j < -M || i >= W + M || j >= H + M)
+                    break;
+                const lj = j + M;
+                return band(Math.floor(lj / BAND_ROWS))[s][w][(lj % BAND_ROWS) * LW + i + M];
+            }
+        throw new InvalidConfigurationError("Diffraction query is off the site lattice; the object-space convolution does not apply.");
+    }
+    const scale = input.metresPerFrameUnit, distance = input.distanceM;
+    return {
+        sceneId: base.sceneId, providerProfileId: base.providerProfileId, radianceAt: base.radianceAt,
+        evaluateRadiance(request) {
+            const result = base.evaluateRadiance(request), o = request.target.outgoingDirectionUnitVector;
+            const t = distance / -o.z;
+            return { ...result, spectralRadianceWattsPerSquareMeterSteradianNanometer: blurredAt(-o.x * t / scale, -o.y * t / scale, request.wavelengthNanometers) };
+        },
+        evaluateApertureRadiance() {
+            throw new InvalidConfigurationError("Diffraction by object-space convolution does not take pupil rays.");
+        }
+    };
+}
+//# sourceMappingURL=diffraction-provider.js.map

package/dist/facade/diffraction-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diffraction-provider.js","sourceRoot":"","sources":["../../src/facade/diffraction-provider.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AAIjF,gHAAgH;AAChH,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,YAAY,GAAG,CAAC,CAAC;AACvB,MAAM,uBAAuB,GAAG,IAAI,CAAC;AA0BrC,2HAA2H;AAC3H,MAAM,UAAU,8BAA8B,CAAC,KAAoC;IACjF,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC;IACxF,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,oBAAoB,CAAC;IACpE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,oGAAoG;IACpG,MAAM,OAAO,GAAG,KAAK,CAAC,iBAAiB,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAU,EAAE,GAAG,MAAM,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvK,MAAM,MAAM,GAA+B,EAAE,CAAC;IAC9C,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,uBAAuB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,uBAAuB,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5I,CAAC;IACD,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,uBAAuB,CAAC,CAAC,CAAC,CAAC;IAC1H,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrC,6GAA6G;IAC7G,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,YAAY,EAAE,EAAE;QACjD,MAAM,CAAC,GAAG,gCAAgC,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,eAAe,EAAE,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;YACjI,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,oBAAoB,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,eAAe,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC;YAC/I,YAAY,EAAE,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,CAAC,CAAC,iBAAiB,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC;YAAE,MAAM,IAAI,yBAAyB,CAAC,yDAAyD,CAAC,CAAC;QACjJ,OAAO,CAAC,CAAC,OAAO,CAAC;IACnB,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,GAAW,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE,GAAG,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACtE,MAAM,KAAK,GAAG,IAAI,GAAG,EAA4B,CAAC;IAClD,SAAS,IAAI,CAAC,CAAS;QACrB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,MAAM,EAAE,CAAC;YAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAAC,OAAO,MAAM,CAAC;QAAC,CAAC;QACrE,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,UAAU,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QACzF,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE;YAC/D,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,SAAS,GAAG,UAAU,CAAC,CAAC;YACzD,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,UAAU,EAAE,EAAE,EAAE,EAAE,CAAC;gBACvC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;gBAChH,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,SAAS,EAAE,EAAE,EAAE;oBAAE,OAAO,CAAC,EAAE,GAAG,SAAS,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1L,CAAC;YACD,MAAM,OAAO,GAAG,8BAA8B,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;gBACrI,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAE,EAAE,QAAQ,EAAE,mBAAmB,EAAE,CAAC,CAAC,MAAM,CAAC;YAChH,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;YACxC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE;gBAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;YACxH,OAAO,GAAG,CAAC;QACb,CAAC,CAAC,CAAC,CAAC;QACJ,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACrB,IAAI,KAAK,CAAC,IAAI,GAAG,YAAY;YAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC,CAAC;QACxE,IAAI,KAAK,CAAC,aAAa;YAAE,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC;QAC9D,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,SAAS,SAAS,CAAC,CAAS,EAAE,CAAS,EAAE,EAAU;QACjD,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7E,IAAI,CAAC,KAAK,SAAS;YAAE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACrF,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,uBAAuB,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,uBAAuB;oBAAE,SAAS;gBAC3H,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;oBAAE,MAAM;gBACxD,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;gBACjB,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAE,CAAC,CAAC,EAAE,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC,CAAE,CAAC;YAClF,CAAC;QACD,MAAM,IAAI,yBAAyB,CAAC,yFAAyF,CAAC,CAAC;IACjI,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,kBAAkB,EAAE,QAAQ,GAAG,KAAK,CAAC,SAAS,CAAC;IACnE,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU;QAC7F,gBAAgB,CAAC,OAAiD;YAChE,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,CAAC,GAAI,OAAO,CAAC,MAA+E,CAAC,2BAA2B,CAAC;YACxK,MAAM,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1B,OAAO,EAAE,GAAG,MAAM,EAAE,qDAAqD,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,oBAAoB,CAAC,EAAE,CAAC;QAC3J,CAAC;QACD,wBAAwB;YACtB,MAAM,IAAI,yBAAyB,CAAC,mEAAmE,CAAC,CAAC;QAC3G,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Fast execution of `simulateCapture`'s `lens.diffraction` (2.1): an object-space convolution in the scene\n * provider, instead of one scene query per PSF tap in the environment PSF quadrature.\n *\n * The environment quadrature computes, at each site centre q and spectral node λ,\n *   E(q, λ) = Σ_k K_λ(k)·T·L(s_k(q), λ),\n * where s_k(q) is the tap's source point (`sensorPsfSourcePoint`), L the scene radiance at the plane point\n * that source point sees, and T the radiance-to-irradiance factor. For the facade's planar scene seen\n * through the ideal rectilinear projection with a still camera and no lens field mapping, field throughput or\n * pupil rays:\n * - T is the same at every sensor point (paraxial π/(4·N_w²), no cos⁴ term), and\n * - with the kernel sampled on the site pitch, every source point is the centre of another site, so the plane\n *   points form one regular lattice: u = (i + ½ − W/2)·2/w, v = −(j + ½ − H/2)·2/w (frame units, native\n *   site (i, j), W×H native sites, w output width).\n * So E(q, λ) = T·B(q, λ) with B = K_λ ⊛ L sampled on that lattice: the same sum, in a different floating-point\n * order. B is computed once per spectral node with the engine's isoplanatic convolution\n * (`calculateIrradianceConvolution`, kernels from `resolveLensPsfConvolutionKernels`, exact site sampling) over a\n * grid that holds every source (the native raster plus the kernel radius on each side), in row bands. The\n * provider then answers each site-centre query with B instead of L, and the environment request declares no\n * PSF. Incoherent imaging is a linear superposition of intensity PSFs, so convolving radiance on the object\n * plane and convolving irradiance on the image plane agree for a planar object and a space-invariant PSF\n * (MIT OpenCourseWare 2.71, lecture 22, free; also see: Goodman, Introduction to Fourier Optics, 4th ed., §6.1).\n *\n * With an anti-aliasing point-splitting filter (2.1, `sensor.antiAliasing`) the environment queries the PSF taps\n * around each pre-filter source point q − a (a = a split offset) instead of around q. Those taps lie on the site\n * lattice shifted by a, so the same argument holds on each shifted lattice: B is computed once per distinct\n * fractional shift (offsets that differ by whole sites share one lattice; the centred four-spot filter with a\n * one-site separation needs a single half-site-shifted lattice) over the native raster widened by the largest\n * offset, and the environment's spatial quadrature still forms the weighted split sum.\n *\n * A query that does not land on one of the lattices (within 1e-6 site) is refused rather than approximated: the\n * facade uses this path only when the lattice argument above holds.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport type { SceneRadianceEvaluationRequest, SceneRadianceEvaluationResult } from \"../schema/scene-radiance.js\";\nimport { calculateIrradianceConvolution } from \"../optics/irradiance-convolution.js\";\nimport { resolveLensPsfConvolutionKernels } from \"../optics/lens-psf-kernels.js\";\nimport type { ResolveLensSampledPsfInput } from \"../optics/lens-psf-profile.js\";\nimport type { PlanarSceneRadianceProvider } from \"./scene-radiance.js\";\n\n/** Rows of native sites per convolution band, and the bands kept. Banding changes memory only, never values. */\nconst BAND_ROWS = 32;\nconst CACHED_BANDS = 4;\nconst LATTICE_TOLERANCE_SITES = 1e-6;\n\nexport interface DiffractedPlanarProviderInput {\n  base: PlanarSceneRadianceProvider;\n  /** The optical state of the sampled PSF, as for `resolveLensSampledPsf`, without field point and wavelength. */\n  psf: Omit<ResolveLensSampledPsfInput, \"fieldPointMm\" | \"wavelengthNm\">;\n  /** Spectral nodes the environment queries (the profile's wavelength nodes). */\n  wavelengthsNm: readonly number[];\n  kernelRadius: number;\n  nativeWidth: number;\n  nativeHeight: number;\n  /** Output (active) width in sites: frame units are 2/outputWidth per site. */\n  outputWidth: number;\n  sitePitchMicrometers: number;\n  /** Planar geometry of the base provider, to map query directions to plane points exactly as it does. */\n  distanceM: number;\n  metresPerFrameUnit: number;\n  /**\n   * Offsets of the query points from the site centres, in sites (+x right, +y down): the anti-aliasing split\n   * offsets with their sign reversed (the environment queries q − a). Default: one zero offset.\n   */\n  queryOffsetsSites?: readonly { x: number; y: number }[];\n  /** Called with the duration in ms of each band convolution (diagnostics only; never changes values). */\n  onConvolution?: (milliseconds: number) => void;\n}\n\n/** Internal (not exported from the package): the base provider with diffraction applied as an object-space convolution. */\nexport function createDiffractedPlanarProvider(input: DiffractedPlanarProviderInput): PlanarSceneRadianceProvider {\n  const { base, wavelengthsNm, nativeWidth: W, nativeHeight: H, kernelRadius: R } = input;\n  const g = 2 / input.outputWidth, pitch = input.sitePitchMicrometers;\n  const index = new Map(wavelengthsNm.map((nm, i) => [nm, i]));\n  // One lattice per distinct fractional query offset; M extra sites per side hold the offset queries.\n  const offsets = input.queryOffsetsSites ?? [{ x: 0, y: 0 }];\n  const fraction = (value: number): number => { const f = value - Math.floor(value); return f > 1 - LATTICE_TOLERANCE_SITES ? 0 : f < LATTICE_TOLERANCE_SITES ? 0 : f; };\n  const shifts: { x: number; y: number }[] = [];\n  for (const o of offsets) {\n    const f = { x: fraction(o.x), y: fraction(o.y) };\n    if (!shifts.some((s) => Math.abs(s.x - f.x) <= LATTICE_TOLERANCE_SITES && Math.abs(s.y - f.y) <= LATTICE_TOLERANCE_SITES)) shifts.push(f);\n  }\n  const M = Math.max(0, ...offsets.map((o) => Math.ceil(Math.max(Math.abs(o.x), Math.abs(o.y)) - LATTICE_TOLERANCE_SITES)));\n  const LW = W + 2 * M, LH = H + 2 * M;\n  // One kernel per wavelength, on the site grid, from the engine's own tap-to-site mapping (field point 0, 0).\n  const kernels = wavelengthsNm.map((wavelengthNm) => {\n    const k = resolveLensPsfConvolutionKernels({ schemaVersion: \"0.1.0\", psf: input.psf, spectralWeights: [{ wavelengthNm, weight: 1 }],\n      grid: { width: 1, height: 1, sitePitchMicrometers: { x: pitch, y: pitch }, opticalAxisSite: { x: 0.5, y: 0.5 } }, patchWidth: 1, patchHeight: 1,\n      kernelRadius: R }).value;\n    if (!k.exactSiteSampling || k.kernelRadius !== R) throw new InvalidConfigurationError(\"Diffraction kernels must sample the site pitch exactly.\");\n    return k.kernels;\n  });\n  const gridWidth = LW + 2 * R;\n  const now = (): number => globalThis.performance?.now() ?? Date.now();\n  const bands = new Map<number, Float64Array[][]>();\n  function band(b: number): Float64Array[][] {\n    const cached = bands.get(b);\n    if (cached) { bands.delete(b); bands.set(b, cached); return cached; }\n    const started = input.onConvolution ? now() : 0;\n    const y0 = b * BAND_ROWS, rows = Math.min(BAND_ROWS, LH - y0), gridHeight = rows + 2 * R;\n    const values = shifts.map((shift) => wavelengthsNm.map((nm, w) => {\n      const samples = new Float64Array(gridWidth * gridHeight);\n      for (let gy = 0; gy < gridHeight; gy++) {\n        const v = shift.y === 0 ? -(y0 + gy - R - M + 0.5 - H / 2) * g : -(y0 + gy - R - M + 0.5 + shift.y - H / 2) * g;\n        for (let gx = 0; gx < gridWidth; gx++) samples[gy * gridWidth + gx] = base.radianceAt(shift.x === 0 ? (gx - R - M + 0.5 - W / 2) * g : (gx - R - M + 0.5 + shift.x - W / 2) * g, v, nm);\n      }\n      const blurred = calculateIrradianceConvolution({ schemaVersion: \"0.1.0\", width: gridWidth, height: gridHeight, samples, kernelRadius: R,\n        patchWidth: gridWidth, patchHeight: gridHeight, kernels: kernels[w]!, boundary: \"zero-outside-grid\" }).values;\n      const out = new Float64Array(LW * rows);\n      for (let y = 0; y < rows; y++) out.set(blurred.subarray((y + R) * gridWidth + R, (y + R) * gridWidth + R + LW), y * LW);\n      return out;\n    }));\n    bands.set(b, values);\n    if (bands.size > CACHED_BANDS) bands.delete(bands.keys().next().value!);\n    if (input.onConvolution) input.onConvolution(now() - started);\n    return values;\n  }\n  function blurredAt(u: number, v: number, nm: number): number {\n    const w = index.get(nm), fi = u / g - 0.5 + W / 2, fj = -v / g - 0.5 + H / 2;\n    if (w !== undefined) for (let s = 0; s < shifts.length; s++) {\n      const shift = shifts[s]!, i = Math.round(fi - shift.x), j = Math.round(fj - shift.y);\n      if (Math.abs(fi - shift.x - i) > LATTICE_TOLERANCE_SITES || Math.abs(fj - shift.y - j) > LATTICE_TOLERANCE_SITES) continue;\n      if (i < -M || j < -M || i >= W + M || j >= H + M) break;\n      const lj = j + M;\n      return band(Math.floor(lj / BAND_ROWS))[s]![w]![(lj % BAND_ROWS) * LW + i + M]!;\n    }\n    throw new InvalidConfigurationError(\"Diffraction query is off the site lattice; the object-space convolution does not apply.\");\n  }\n  const scale = input.metresPerFrameUnit, distance = input.distanceM;\n  return {\n    sceneId: base.sceneId, providerProfileId: base.providerProfileId, radianceAt: base.radianceAt,\n    evaluateRadiance(request: Readonly<SceneRadianceEvaluationRequest>): SceneRadianceEvaluationResult {\n      const result = base.evaluateRadiance(request), o = (request.target as { outgoingDirectionUnitVector: { x: number; y: number; z: number } }).outgoingDirectionUnitVector;\n      const t = distance / -o.z;\n      return { ...result, spectralRadianceWattsPerSquareMeterSteradianNanometer: blurredAt(-o.x * t / scale, -o.y * t / scale, request.wavelengthNanometers) };\n    },\n    evaluateApertureRadiance(): SceneRadianceEvaluationResult {\n      throw new InvalidConfigurationError(\"Diffraction by object-space convolution does not take pupil rays.\");\n    }\n  };\n}\n"]}

package/dist/facade/host-yield.d.ts

@@ -0,0 +1,7 @@
+/** Mechanism chosen by {@link createHostYield}, for diagnostics and tests. */
+export type HostYieldMechanism = "message-channel" | "set-immediate" | "set-timeout";
+/** Returns a function that yields to the host event loop once per call, and the mechanism it uses. */
+export declare function createHostYield(host?: object): {
+    mechanism: HostYieldMechanism;
+    yieldControl: () => Promise<void>;
+};

package/dist/facade/host-yield.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Returns a function that yields to the host event loop once per call, and the mechanism it uses. */
+export function createHostYield(host = globalThis) {
+    const g = host;
+    const Channel = g.MessageChannel;
+    if (typeof Channel === "function") {
+        return { mechanism: "message-channel", yieldControl: () => new Promise((resolve) => {
+                const channel = new Channel();
+                channel.port1.onmessage = () => { channel.port1.close(); resolve(); };
+                channel.port2.postMessage(undefined);
+            }) };
+    }
+    const immediate = g.setImmediate;
+    if (typeof immediate === "function") {
+        return { mechanism: "set-immediate", yieldControl: () => new Promise((resolve) => { immediate.call(host, resolve); }) };
+    }
+    return { mechanism: "set-timeout", yieldControl: () => new Promise((resolve) => { setTimeout(resolve, 0); }) };
+}
+//# sourceMappingURL=host-yield.js.map

package/dist/facade/host-yield.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-yield.js","sourceRoot":"","sources":["../../src/facade/host-yield.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAsCtC,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,OAAe,UAAU;IACvD,MAAM,CAAC,GAAG,IAAoB,CAAC;IAC/B,MAAM,OAAO,GAAG,CAAC,CAAC,cAAc,CAAC;IACjC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBACvF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;gBAC9B,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,GAAS,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;gBAC5E,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;YACvC,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,CAAC,YAAY,CAAC;IACjC,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;QACpC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChI,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACvH,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Host yield for the capture facade's cooperative tasks. Browsers clamp nested `setTimeout(…, 0)` to\n * at least 4 ms (WHATWG HTML timers, nesting level above 5), so a task that yields every few\n * milliseconds through timers can sit idle for a large share of its run time. The first available\n * mechanism is used:\n *\n * 1. a `MessageChannel` message, a new task without the timer clamp (one channel per yield, closed after\n *    delivery, so no port keeps a Node process alive);\n * 2. `setImmediate` (Node and some other non-browser hosts);\n * 3. `setTimeout(…, 0)` as the last resort.\n *\n * Every yield must let tasks that are already queued run first, so that a caller's cancel message (for\n * example a Web Worker `message` event that aborts the capture's `AbortSignal`) is handled at the next\n * yield. A `MessageChannel` message is queued on the HTML posted message task source, the same source as\n * worker and port `message` events, and tasks from one source run in the order they were queued.\n *\n * `scheduler.yield()` is deliberately not used (engine 2.0.0 used it first). Its continuation inherits\n * the \"user-visible\" priority and gets a higher effective priority than ordinary tasks; the WICG\n * Prioritized Task Scheduling draft (§ \"Task and Continuation Priorities\", effective priority table;\n * § \"Event loop: processing model\" note) intends such continuations to run ahead of most other task\n * sources, and its explainer (\"Preventing Task Starvation by Continuations\") only bounds that by\n * duration. A capture that yields every 8 ms through `scheduler.yield()` therefore starved a worker's\n * cancel message until the capture finished (measured in Chromium).\n *\n * Only global feature detection is used; nothing is imported, so the browser package surface is unchanged.\n * The yield changes scheduling only, never results.\n */\n\ntype YieldGlobals = {\n  MessageChannel?: new () => { port1: { onmessage: ((event: unknown) => void) | null; close(): void }; port2: { postMessage(message: unknown): void } };\n  setImmediate?: (callback: () => void) => unknown;\n};\n\n/** Mechanism chosen by {@link createHostYield}, for diagnostics and tests. */\nexport type HostYieldMechanism = \"message-channel\" | \"set-immediate\" | \"set-timeout\";\n\n/** Returns a function that yields to the host event loop once per call, and the mechanism it uses. */\nexport function createHostYield(host: object = globalThis): { mechanism: HostYieldMechanism; yieldControl: () => Promise<void> } {\n  const g = host as YieldGlobals;\n  const Channel = g.MessageChannel;\n  if (typeof Channel === \"function\") {\n    return { mechanism: \"message-channel\", yieldControl: () => new Promise<void>((resolve) => {\n      const channel = new Channel();\n      channel.port1.onmessage = (): void => { channel.port1.close(); resolve(); };\n      channel.port2.postMessage(undefined);\n    }) };\n  }\n  const immediate = g.setImmediate;\n  if (typeof immediate === \"function\") {\n    return { mechanism: \"set-immediate\", yieldControl: () => new Promise<void>((resolve) => { immediate.call(host, resolve); }) };\n  }\n  return { mechanism: \"set-timeout\", yieldControl: () => new Promise<void>((resolve) => { setTimeout(resolve, 0); }) };\n}\n"]}