@photivra/engine 1.4.0 → 2.0.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/host-yield.d.ts

@@ -0,0 +1,7 @@
+/** Mechanism chosen by {@link createHostYield}, for diagnostics and tests. */
+export type HostYieldMechanism = "scheduler.yield" | "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,23 @@
+// 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 scheduler = g.scheduler;
+    if (scheduler !== undefined && typeof scheduler.yield === "function") {
+        return { mechanism: "scheduler.yield", yieldControl: async () => { await scheduler.yield.call(scheduler); } };
+    }
+    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;AA2BtC,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,OAAe,UAAU;IACvD,MAAM,CAAC,GAAG,IAAoB,CAAC;IAC/B,MAAM,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;IAC9B,IAAI,SAAS,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACrE,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,KAAK,IAAmB,EAAE,GAAG,MAAM,SAAS,CAAC,KAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChI,CAAC;IACD,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. These yields are not\n * clamped. The first available mechanism is used:\n *\n * 1. `scheduler.yield()` (Prioritized Task Scheduling API), which also keeps the task's priority;\n * 2. 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 * 3. `setImmediate` (Node and some other non-browser hosts);\n * 4. `setTimeout(…, 0)` as the last resort.\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  scheduler?: { yield?: () => Promise<unknown> };\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 = \"scheduler.yield\" | \"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 scheduler = g.scheduler;\n  if (scheduler !== undefined && typeof scheduler.yield === \"function\") {\n    return { mechanism: \"scheduler.yield\", yieldControl: async (): Promise<void> => { await scheduler.yield!.call(scheduler); } };\n  }\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"]}

package/dist/facade/scene-radiance.d.ts

@@ -0,0 +1,117 @@
+import { type ColorimetricSpectrum, type PreparedColorimetricSpectrum } from "../color/color-matching-functions.js";
+import { type CieDaylightBasis } from "../color/illuminants.js";
+import type { SceneRadianceEvaluationRequest, SceneRadianceEvaluationResult } from "../schema/scene-radiance.js";
+import type { EvidenceProvenance } from "../core/evidence-provenance.js";
+import type { SensorApertureRay } from "../optics/sensor-aperture-rays.js";
+import { type ChartScene, type ResolvedChartScene } from "./chart-scenes.js";
+/** CIE maximum luminous efficacy for photopic vision, lm/W. */
+export declare const PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W = 683;
+/** Wavelength range of every facade spectrum and of the facade sensor quadrature, nm. */
+export declare const FACADE_SPECTRAL_RANGE_NANOMETERS: Readonly<{
+    minimum: 380;
+    maximum: 780;
+}>;
+/**
+ * Illuminant choices. CIE D65 is not bundled: its S0/S1/S2 basis tables must come from the caller
+ * (`daylight`). `planckian` is Planck's law; `cie-a` is CIE illuminant A from its defining formula.
+ */
+export type CaptureIlluminant = "cie-a" | {
+    kind: "planckian";
+    temperatureKelvin: number;
+} | {
+    kind: "cie-a";
+} | {
+    kind: "daylight";
+    correlatedColorTemperatureKelvin: number;
+    basis: CieDaylightBasis;
+} | {
+    kind: "spectrum";
+    spectrum: ColorimetricSpectrum;
+    label?: string;
+};
+export interface ResolvedCaptureIlluminant {
+    /** Short public description, for example "planckian-6500K". */
+    id: string;
+    description: string;
+    /** Relative spectral shape (arbitrary scale) over at least 380-780 nm. */
+    shape: PreparedColorimetricSpectrum;
+    /** Original spectrum, for colorimetric white-balance calculations. */
+    spectrum: ColorimetricSpectrum;
+}
+export declare function resolveCaptureIlluminant(value: CaptureIlluminant): ResolvedCaptureIlluminant;
+/**
+ * Factor k such that k·S(λ) (W·m⁻²·nm⁻¹) gives `illuminanceLux` on the plane: E_v = 683 ∫ k S ȳ dλ,
+ * integrated with the 1 nm trapezoid rule over 380-780 nm (ȳ outside this range is below 4e-5 of its peak).
+ */
+export declare function calculateIlluminantIrradianceScale(shape: PreparedColorimetricSpectrum, illuminanceLux: number): number;
+/** A point of the scene plane passed to caller scene functions. */
+export interface ScenePlanePoint {
+    /** Metres on the plane, from the optical axis: +x right, +y up (as seen from the camera). */
+    xM: number;
+    yM: number;
+    /** The same point in frame units (u = ±1 at the left/right frame edges, v up on the same scale). */
+    u: number;
+    v: number;
+    wavelengthNanometers: number;
+}
+/** Caller Lambertian reflectance (in [0, 1]) lit by the facade illuminant. */
+export interface CallerReflectanceScene {
+    kind: "reflectance-function";
+    sceneId: string;
+    evaluate(point: Readonly<ScenePlanePoint>): number;
+}
+/** Caller absolute spectral radiance in W·m⁻²·sr⁻¹·nm⁻¹; the facade illuminant is not used. */
+export interface CallerRadianceScene {
+    kind: "radiance-function";
+    sceneId: string;
+    evaluate(point: Readonly<ScenePlanePoint>): number;
+}
+export interface PlanarSceneGeometry {
+    distanceM: number;
+    /** Metres per frame unit on the plane (half the framed width). */
+    metresPerFrameUnit: number;
+}
+export interface PlanarSceneRadianceProvider {
+    sceneId: string;
+    providerProfileId: string;
+    evaluateRadiance(request: Readonly<SceneRadianceEvaluationRequest>): SceneRadianceEvaluationResult;
+    evaluateApertureRadiance(request: Readonly<SceneRadianceEvaluationRequest>, ray: Readonly<SensorApertureRay>): SceneRadianceEvaluationResult;
+    /** Spectral radiance at a plane point (frame units), the same value the callbacks return. */
+    radianceAt(u: number, v: number, wavelengthNanometers: number): number;
+}
+/**
+ * Wraps a chart or caller scene as a provider for the native environment RAW task. `irradianceScale` is
+ * from {@link calculateIlluminantIrradianceScale}; caller radiance scenes ignore the illuminant.
+ */
+export declare function buildPlanarSceneRadianceProvider(input: {
+    scene: ResolvedChartScene | CallerReflectanceScene | CallerRadianceScene;
+    sceneId: string;
+    providerProfileId: string;
+    illuminant: ResolvedCaptureIlluminant;
+    irradianceScale: number;
+    geometry: PlanarSceneGeometry;
+    evidence: readonly EvidenceProvenance[];
+    limitations: readonly string[];
+}): PlanarSceneRadianceProvider;
+/**
+ * Public scene-preset provider. Places an engine chart (or a caller reflectance or radiance function) on
+ * a plane `distanceM` in front of the camera and `framedWidthM` wide (frame units u = ±1 at its edges),
+ * lit by `illuminant` at `illuminanceLux`. The returned `evaluateRadiance` and `evaluateApertureRadiance`
+ * follow the native environment RAW provider contract. They answer requests for scene `sceneId` and
+ * provider `providerProfileId`.
+ */
+export declare function createPlanarSceneRadianceProvider(input: {
+    scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
+    illuminant: CaptureIlluminant;
+    illuminanceLux: number;
+    distanceM: number;
+    framedWidthM: number;
+    /** Frame height / width. */
+    aspect: number;
+    sceneId: string;
+    providerProfileId: string;
+}): PlanarSceneRadianceProvider & {
+    chart: ResolvedChartScene | null;
+};
+/** Validates a caller scene function record. */
+export declare function requireCallerScene(value: unknown): CallerReflectanceScene | CallerRadianceScene;