@photivra/engine 2.9.0 → 2.11.1

package/dist/facade/channel-response.d.ts

@@ -0,0 +1,15 @@
+import type { SceneRadianceEvaluationRequest, SceneRadianceEvaluationResult } from "../schema/scene-radiance.js";
+/**
+ * Electrons per unit spectral radiance at each node, sorted by wavelength, for an environment record with one temporal
+ * sample. The chain runs once with radiance 1 at every node; each node's value is its own rate term times the time step.
+ *
+ * Exact: the spatial reduction and the per-node rate are per spectral node, the spectral sum is a compensated sum of
+ * per-node terms and the temporal sum is rate × time step. An execution with radiance 1 at one node and 0 elsewhere (the
+ * earlier method, one execution per node) therefore adds +0 terms that leave the compensated sum unchanged and returns
+ * exactly `rate_n × integrationMeasureSeconds` (test/channel-response.test.ts compares both with Object.is).
+ *
+ * The environment record must be the engine's own (built by the caller, never shown to supplied code or changed after):
+ * it is planned as engine-owned data without a copy. Retention is photo-only, as on the capture path; photo values are
+ * identical for either retention.
+ */
+export declare function calculateChannelElectronsPerRadiance(environment: Record<string, unknown>, evaluateRadiance: (request: Readonly<SceneRadianceEvaluationRequest>) => SceneRadianceEvaluationResult, caller: string): Map<number, number>;

package/dist/facade/channel-response.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Internal (#443): one channel's expected photo electrons per unit spectral radiance at each spectral node, from one
+ * execution of the environment photo-signal chain. Used by the facade's `axisChannelResponse` (display view, ideal
+ * reference and the capture's tabulated RAW path).
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { executeEnvironmentSensorPhotoSignal, planEnvironmentSensorPhotoSignal } from "../sensor/environment-photo-signal.js";
+/**
+ * Electrons per unit spectral radiance at each node, sorted by wavelength, for an environment record with one temporal
+ * sample. The chain runs once with radiance 1 at every node; each node's value is its own rate term times the time step.
+ *
+ * Exact: the spatial reduction and the per-node rate are per spectral node, the spectral sum is a compensated sum of
+ * per-node terms and the temporal sum is rate × time step. An execution with radiance 1 at one node and 0 elsewhere (the
+ * earlier method, one execution per node) therefore adds +0 terms that leave the compensated sum unchanged and returns
+ * exactly `rate_n × integrationMeasureSeconds` (test/channel-response.test.ts compares both with Object.is).
+ *
+ * The environment record must be the engine's own (built by the caller, never shown to supplied code or changed after):
+ * it is planned as engine-owned data without a copy. Retention is photo-only, as on the capture path; photo values are
+ * identical for either retention.
+ */
+export function calculateChannelElectronsPerRadiance(environment, evaluateRadiance, caller) {
+    const plan = planEnvironmentSensorPhotoSignal(environment, "engine-owned", "photo-only");
+    const result = executeEnvironmentSensorPhotoSignal(plan, (request) => ({ ...evaluateRadiance(request), spectralRadianceWattsPerSquareMeterSteradianNanometer: 1 }), undefined, "photo-only");
+    const samples = result.value.photo.value.exposure.value.samples;
+    if (samples.length !== 1)
+        throw new InvalidConfigurationError(caller + ": the channel response expects one temporal sample.");
+    const sample = samples[0];
+    return new Map(sample.stages.electronRate.value.perWavelength
+        .map((node) => [node.wavelengthNanometers, node.expectedGeneratedElectronRatePerSecond * sample.integrationMeasureSeconds])
+        .sort((a, b) => a[0] - b[0]));
+}
+//# sourceMappingURL=channel-response.js.map

package/dist/facade/channel-response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-response.js","sourceRoot":"","sources":["../../src/facade/channel-response.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;GAIG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,OAAO,EAAE,mCAAmC,EAAE,gCAAgC,EAAE,MAAM,uCAAuC,CAAC;AAM9H;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oCAAoC,CAAC,WAAoC,EACvF,gBAAsG,EAAE,MAAc;IACtH,MAAM,IAAI,GAAG,gCAAgC,CAAC,WAAmC,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;IACjH,MAAM,MAAM,GAAG,mCAAmC,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CACnE,CAAC,EAAE,GAAG,gBAAgB,CAAC,OAAO,CAAC,EAAE,qDAAqD,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IACzH,MAAM,OAAO,GAAI,MAAM,CAAC,KAAoC,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC;IAChG,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,yBAAyB,CAAC,MAAM,GAAG,qDAAqD,CAAC,CAAC;IAC9H,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;IAC3B,OAAO,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,aAAa;SAC1D,GAAG,CAAC,CAAC,IAAI,EAAoB,EAAE,CAAC,CAAC,IAAI,CAAC,oBAAoB,EAAE,IAAI,CAAC,sCAAsC,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC;SAC5I,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClC,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Internal (#443): one channel's expected photo electrons per unit spectral radiance at each spectral node, from one\n * execution of the environment photo-signal chain. Used by the facade's `axisChannelResponse` (display view, ideal\n * reference and the capture's tabulated RAW path).\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport type { SceneRadianceEvaluationRequest, SceneRadianceEvaluationResult } from \"../schema/scene-radiance.js\";\nimport { executeEnvironmentSensorPhotoSignal, planEnvironmentSensorPhotoSignal } from \"../sensor/environment-photo-signal.js\";\n\ntype PlanInput = Parameters<typeof planEnvironmentSensorPhotoSignal>[0];\ninterface PerNodeExposure { photo: { value: { exposure: { value: { samples: readonly { integrationMeasureSeconds: number;\n  stages: { electronRate: { value: { perWavelength: readonly { wavelengthNanometers: number; expectedGeneratedElectronRatePerSecond: number }[] } } } }[] } } } } }\n\n/**\n * Electrons per unit spectral radiance at each node, sorted by wavelength, for an environment record with one temporal\n * sample. The chain runs once with radiance 1 at every node; each node's value is its own rate term times the time step.\n *\n * Exact: the spatial reduction and the per-node rate are per spectral node, the spectral sum is a compensated sum of\n * per-node terms and the temporal sum is rate × time step. An execution with radiance 1 at one node and 0 elsewhere (the\n * earlier method, one execution per node) therefore adds +0 terms that leave the compensated sum unchanged and returns\n * exactly `rate_n × integrationMeasureSeconds` (test/channel-response.test.ts compares both with Object.is).\n *\n * The environment record must be the engine's own (built by the caller, never shown to supplied code or changed after):\n * it is planned as engine-owned data without a copy. Retention is photo-only, as on the capture path; photo values are\n * identical for either retention.\n */\nexport function calculateChannelElectronsPerRadiance(environment: Record<string, unknown>,\n  evaluateRadiance: (request: Readonly<SceneRadianceEvaluationRequest>) => SceneRadianceEvaluationResult, caller: string): Map<number, number> {\n  const plan = planEnvironmentSensorPhotoSignal(environment as unknown as PlanInput, \"engine-owned\", \"photo-only\");\n  const result = executeEnvironmentSensorPhotoSignal(plan, (request) =>\n    ({ ...evaluateRadiance(request), spectralRadianceWattsPerSquareMeterSteradianNanometer: 1 }), undefined, \"photo-only\");\n  const samples = (result.value as unknown as PerNodeExposure).photo.value.exposure.value.samples;\n  if (samples.length !== 1) throw new InvalidConfigurationError(caller + \": the channel response expects one temporal sample.\");\n  const sample = samples[0]!;\n  return new Map(sample.stages.electronRate.value.perWavelength\n    .map((node): [number, number] => [node.wavelengthNanometers, node.expectedGeneratedElectronRatePerSecond * sample.integrationMeasureSeconds])\n    .sort((a, b) => a[0] - b[0]));\n}\n"]}

package/dist/facade/chart-material-layers.d.ts

@@ -0,0 +1,115 @@
+import { type ChartReflectance, type ChartScene, type ResolvedChartScene } from "./chart-scenes.js";
+import type { CallerMaterialScene } from "./scene-radiance.js";
+/** A filled polygon: rings as flat [x0, y0, x1, y1, …] in mask units (y down), non-zero winding over all rings. */
+export interface ChartMaskPolygon {
+    kind: "polygon";
+    rings: readonly (readonly number[])[];
+}
+/** A stroked circle: the points at distance innerRadius ≤ d ≤ outerRadius from the centre, mask units. */
+export interface ChartMaskAnnulus {
+    kind: "annulus";
+    centerX: number;
+    centerY: number;
+    innerRadius: number;
+    outerRadius: number;
+}
+export type ChartMaskShape = ChartMaskPolygon | ChartMaskAnnulus;
+/** A shape mask printed over the chart: its box [0, unitsWidth] × [0, unitsHeight] (y down) fills `rectangle` (frame units, v up). */
+export interface ChartMaskLayer {
+    kind: "shape-mask";
+    rectangle: {
+        u0: number;
+        v0: number;
+        u1: number;
+        v1: number;
+    };
+    unitsWidth: number;
+    unitsHeight: number;
+    /** 1 to 4096 shapes, in order; the ink material where any contains the point. */
+    shapes: readonly ChartMaskShape[];
+    backgroundReflectance: ChartReflectance;
+    inkReflectance: ChartReflectance;
+}
+/** A chart under 1 to 16 shape-mask layers, as data; `resolveChartMaterialLayers` evaluates it. */
+export interface ChartMaterialLayerScene {
+    kind: "material-layers";
+    sceneId: string;
+    chart: ChartScene;
+    layers: readonly ChartMaskLayer[];
+}
+/** The cell index grain of every layer: cells across and down the mask box. */
+export declare const CHART_MASK_INDEX_GRAIN: Readonly<{
+    cellsX: 64;
+    cellsY: 16;
+}>;
+/** Limits of a declared scene. */
+export declare const CHART_MATERIAL_LAYER_LIMITS: Readonly<{
+    maximumLayers: 16;
+    maximumShapes: 4096;
+    maximumRings: 256;
+    maximumEdges: 65536;
+}>;
+/** Internal: a shape with its bounding box and flattened edges (polygon) or squared radii (annulus). */
+export type ResolvedChartMaskShape = {
+    kind: "polygon";
+    box: readonly [number, number, number, number];
+    edges: Float64Array;
+} | {
+    kind: "annulus";
+    box: readonly [number, number, number, number];
+    centerX: number;
+    centerY: number;
+    inner2: number;
+    outer2: number;
+};
+export interface ResolvedChartMaskLayer {
+    rectangle: {
+        u0: number;
+        v0: number;
+        u1: number;
+        v1: number;
+    };
+    unitsWidth: number;
+    unitsHeight: number;
+    /** Mask units per frame unit: unitsWidth / (u1 − u0) and unitsHeight / (v1 − v0). */
+    scaleX: number;
+    scaleY: number;
+    shapes: readonly ResolvedChartMaskShape[];
+    cellsX: number;
+    cellsY: number;
+    cellWidth: number;
+    cellHeight: number;
+    /** Per cell (row by row), the shape indices whose bounding box meets the cell grown by one cell. */
+    cells: readonly Uint32Array[];
+    backgroundMaterial: number;
+    inkMaterial: number;
+    /** Whether a point in mask units is ink (through the cell index). */
+    containsUnits(x: number, y: number): boolean;
+}
+export interface ResolvedChartMaterialLayers {
+    kind: "material-layers";
+    sceneId: string;
+    /** The chart under the layers; its materials come first in `materials`. */
+    chart: ResolvedChartScene;
+    layers: readonly ResolvedChartMaskLayer[];
+    materials: ResolvedChartScene["materials"];
+    /** Internal: the caller input behind each material (undefined for an engine neutral), for the scene digest. */
+    materialInputs: readonly unknown[];
+    /** Material index at a frame point (u right, v up): the topmost layer whose rectangle holds the point, else the chart. */
+    materialAt(u: number, v: number): number;
+    /** The same scene as a caller material scene for `simulateCapture` and the display view (chart-local coordinates when the chart has a size). */
+    callerScene: CallerMaterialScene;
+}
+/** Non-zero winding over the edges (x0, y0, x1, y1), as the reference evaluates it; the GPU runs the same comparisons. */
+export declare function polygonWinding(edges: Float64Array, x: number, y: number): number;
+/** Whether a resolved shape contains a point in mask units (the full test, without the cell index). */
+export declare function shapeContains(shape: ResolvedChartMaskShape, x: number, y: number): boolean;
+/**
+ * Validates a declared material scene and resolves its chart (in a frame of `aspect` = height / width) and its
+ * layers. `materialAt` is the float64 reference the GPU stage is checked against, and `callerScene` is the same
+ * scene for `simulateCapture`'s `scene` option.
+ */
+export declare function resolveChartMaterialLayers(input: {
+    scene: ChartMaterialLayerScene;
+    aspect: number;
+}): ResolvedChartMaterialLayers;

package/dist/facade/chart-material-layers.js

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Declared material scenes (#477): an engine chart under shape-mask layers, given as data rather than as a
+ * `materialAt` function, so that both the float64 reference and the `webgpu-f32` chart stage can evaluate
+ * them. An application that prints a label on a chart (a logo and a line of text as filled polygons and
+ * stroked rings, in the label's own units) describes it here; the engine holds no label of its own.
+ *
+ * A layer maps its mask box, [0, unitsWidth] × [0, unitsHeight] with y down, onto a frame rectangle. Inside
+ * that rectangle the layer decides the material: the ink material where any of its shapes contains the
+ * point, its background material elsewhere. Later layers cover earlier ones, and the chart shows outside
+ * every layer. Shapes are polygons under the non-zero winding rule (several rings per shape; a stroked
+ * polyline is its rectangles as rings of one orientation) and annuli (stroked circles).
+ *
+ * Each layer carries a cell index of {@link CHART_MASK_INDEX_GRAIN} cells over its box: a cell lists the
+ * shapes whose bounding box meets the cell grown by one cell on every side, so `containsUnits` tests only
+ * those. A computed cell can be off by one from the true one only through the rounding of one subtraction
+ * and one multiplication, far less than a cell (the grain is checked against the coordinates' magnitude
+ * when the layer is resolved), and a shape left out of a cell's list lies a whole cell away from any point
+ * that resolves to it, so the indexed test gives the full test's answer at every point. The GPU uses the same
+ * index (docs/WEBGPU.md, "Scene radiance on the GPU").
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { requireInputKeys, requireInputObject } from "../core/record-validation.js";
+import { resolveChartScene, resolveChartMaterial, chartMaterialInputs } from "./chart-scenes.js";
+/** The cell index grain of every layer: cells across and down the mask box. */
+export const CHART_MASK_INDEX_GRAIN = Object.freeze({ cellsX: 64, cellsY: 16 });
+/** Limits of a declared scene. */
+export const CHART_MATERIAL_LAYER_LIMITS = Object.freeze({ maximumLayers: 16, maximumShapes: 4096, maximumRings: 256, maximumEdges: 65_536 });
+const SCENE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/u;
+const finite = (value, name) => {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        throw new InvalidConfigurationError(name + " must be a finite number.");
+    return value;
+};
+/** The smallest cell the one-cell margin covers: the rounding of (x − 0)·scale is a few units in the last place of the coordinates. */
+const minimumCell = (extent) => Math.max(extent, Number.MIN_VALUE) * 2 ** -20;
+function resolvePolygon(shape, name) {
+    const rings = shape.rings;
+    if (!Array.isArray(rings) || rings.length < 1 || rings.length > CHART_MATERIAL_LAYER_LIMITS.maximumRings)
+        throw new InvalidConfigurationError(name + " needs 1 to 256 rings.");
+    let count = 0;
+    for (const ring of rings) {
+        if (!Array.isArray(ring) || ring.length < 6 || ring.length % 2 !== 0)
+            throw new InvalidConfigurationError(name + " rings need at least three (x, y) vertices.");
+        count += ring.length / 2;
+    }
+    if (count > CHART_MATERIAL_LAYER_LIMITS.maximumEdges)
+        throw new InvalidConfigurationError(name + " has more than 65536 edges.");
+    const edges = new Float64Array(4 * count);
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity, e = 0;
+    for (const ring of rings) {
+        const n = ring.length / 2;
+        for (let k = 0; k < n; k++) {
+            const x0 = finite(ring[2 * k], name + " vertex"), y0 = finite(ring[2 * k + 1], name + " vertex");
+            const next = k + 1 === n ? 0 : k + 1, x1 = finite(ring[2 * next], name + " vertex"), y1 = finite(ring[2 * next + 1], name + " vertex");
+            edges[e++] = x0;
+            edges[e++] = y0;
+            edges[e++] = x1;
+            edges[e++] = y1;
+            minX = Math.min(minX, x0);
+            minY = Math.min(minY, y0);
+            maxX = Math.max(maxX, x0);
+            maxY = Math.max(maxY, y0);
+        }
+    }
+    return { kind: "polygon", box: [minX, minY, maxX, maxY], edges };
+}
+/** Non-zero winding over the edges (x0, y0, x1, y1), as the reference evaluates it; the GPU runs the same comparisons. */
+export function polygonWinding(edges, x, y) {
+    let winding = 0;
+    for (let k = 0; k < edges.length; k += 4) {
+        const x0 = edges[k], y0 = edges[k + 1], x1 = edges[k + 2], y1 = edges[k + 3];
+        const side = (x1 - x0) * (y - y0) - (x - x0) * (y1 - y0);
+        if (y0 <= y) {
+            if (y1 > y && side > 0)
+                winding++;
+        }
+        else if (y1 <= y && side < 0)
+            winding--;
+    }
+    return winding;
+}
+/** Whether a resolved shape contains a point in mask units (the full test, without the cell index). */
+export function shapeContains(shape, x, y) {
+    const b = shape.box;
+    if (!(x >= b[0] && x <= b[2] && y >= b[1] && y <= b[3]))
+        return false;
+    if (shape.kind === "annulus") {
+        const d2 = (x - shape.centerX) * (x - shape.centerX) + (y - shape.centerY) * (y - shape.centerY);
+        return d2 >= shape.inner2 && d2 <= shape.outer2;
+    }
+    return polygonWinding(shape.edges, x, y) !== 0;
+}
+function resolveLayer(value, name, aspect, materials, inputs) {
+    requireInputObject(value, name);
+    const layer = value;
+    for (const key of Object.keys(layer)) {
+        if (!["kind", "rectangle", "unitsWidth", "unitsHeight", "shapes", "backgroundReflectance", "inkReflectance"].includes(key))
+            throw new InvalidConfigurationError("Unknown " + name + " field: " + key + ".");
+    }
+    if (layer.kind !== "shape-mask")
+        throw new InvalidConfigurationError(name + ".kind must be shape-mask.");
+    requireInputObject(layer.rectangle, name + ".rectangle");
+    const r = layer.rectangle;
+    for (const key of Object.keys(r))
+        if (!["u0", "v0", "u1", "v1"].includes(key))
+            throw new InvalidConfigurationError("Unknown " + name + ".rectangle field: " + key + ".");
+    const u0 = finite(r.u0, name + ".rectangle.u0"), v0 = finite(r.v0, name + ".rectangle.v0"), u1 = finite(r.u1, name + ".rectangle.u1"), v1 = finite(r.v1, name + ".rectangle.v1");
+    if (!(u1 > u0 && v1 > v0) || Math.max(Math.abs(u0), Math.abs(u1)) > 1e6 || Math.max(Math.abs(v0), Math.abs(v1)) > 1e6 * Math.max(1, aspect)) {
+        throw new InvalidConfigurationError(name + ".rectangle needs u0 < u1 and v0 < v1 within 10^6 frame units.");
+    }
+    const unitsWidth = finite(layer.unitsWidth, name + ".unitsWidth"), unitsHeight = finite(layer.unitsHeight, name + ".unitsHeight");
+    if (!(unitsWidth > 0 && unitsHeight > 0 && unitsWidth <= 1e9 && unitsHeight <= 1e9))
+        throw new InvalidConfigurationError(name + " units must be positive and at most 10^9.");
+    const list = layer.shapes;
+    if (!Array.isArray(list) || list.length < 1 || list.length > CHART_MATERIAL_LAYER_LIMITS.maximumShapes)
+        throw new InvalidConfigurationError(name + ".shapes must list 1 to 4096 shapes.");
+    const shapes = list.map((shape, index) => {
+        const label = name + ".shapes[" + index + "]";
+        requireInputObject(shape, label);
+        const s = shape;
+        if (s.kind === "polygon") {
+            for (const key of Object.keys(s))
+                if (key !== "kind" && key !== "rings")
+                    throw new InvalidConfigurationError("Unknown " + label + " field: " + key + ".");
+            return resolvePolygon(s, label);
+        }
+        if (s.kind !== "annulus")
+            throw new InvalidConfigurationError(label + ".kind must be polygon or annulus.");
+        for (const key of Object.keys(s))
+            if (!["kind", "centerX", "centerY", "innerRadius", "outerRadius"].includes(key))
+                throw new InvalidConfigurationError("Unknown " + label + " field: " + key + ".");
+        const cx = finite(s.centerX, label + ".centerX"), cy = finite(s.centerY, label + ".centerY");
+        const inner = finite(s.innerRadius, label + ".innerRadius"), outer = finite(s.outerRadius, label + ".outerRadius");
+        if (!(inner >= 0 && outer > inner))
+            throw new InvalidConfigurationError(label + " needs 0 ≤ innerRadius < outerRadius.");
+        return { kind: "annulus", box: [cx - outer, cy - outer, cx + outer, cy + outer], centerX: cx, centerY: cy, inner2: inner * inner, outer2: outer * outer };
+    });
+    for (const shape of shapes) {
+        if (!shape.box.every((c) => Math.abs(c) <= 1e9))
+            throw new InvalidConfigurationError(name + " shape coordinates must stay within 10^9 units.");
+    }
+    const backgroundMaterial = materials.length;
+    materials.push(resolveChartMaterial(layer.backgroundReflectance, name + ".backgroundReflectance"));
+    inputs.push(typeof layer.backgroundReflectance === "number" ? undefined : layer.backgroundReflectance);
+    const inkMaterial = materials.length;
+    materials.push(resolveChartMaterial(layer.inkReflectance, name + ".inkReflectance"));
+    inputs.push(typeof layer.inkReflectance === "number" ? undefined : layer.inkReflectance);
+    // The cell index over the mask box; the grain must stay large against the coordinates' rounding (see the header).
+    const { cellsX, cellsY } = CHART_MASK_INDEX_GRAIN, cellWidth = unitsWidth / cellsX, cellHeight = unitsHeight / cellsY;
+    const extentX = Math.max(unitsWidth, ...shapes.map((s) => Math.max(Math.abs(s.box[0]), Math.abs(s.box[2]))));
+    const extentY = Math.max(unitsHeight, ...shapes.map((s) => Math.max(Math.abs(s.box[1]), Math.abs(s.box[3]))));
+    if (!(cellWidth > minimumCell(extentX) && cellHeight > minimumCell(extentY)))
+        throw new InvalidConfigurationError(name + ": the shapes extend too far beyond the mask box for its cell index.");
+    const cells = [];
+    for (let j = 0; j < cellsY; j++) {
+        for (let i = 0; i < cellsX; i++) {
+            const x0 = (i - 1) * cellWidth, x1 = (i + 2) * cellWidth, y0 = (j - 1) * cellHeight, y1 = (j + 2) * cellHeight, listed = [];
+            shapes.forEach((s, k) => { if (s.box[0] <= x1 && s.box[2] >= x0 && s.box[1] <= y1 && s.box[3] >= y0)
+                listed.push(k); });
+            cells.push(Uint32Array.from(listed));
+        }
+    }
+    const scaleX = unitsWidth / (u1 - u0), scaleY = unitsHeight / (v1 - v0);
+    return Object.freeze({ rectangle: Object.freeze({ u0, v0, u1, v1 }), unitsWidth, unitsHeight, scaleX, scaleY, shapes: Object.freeze(shapes), cellsX, cellsY, cellWidth, cellHeight,
+        cells: Object.freeze(cells), backgroundMaterial, inkMaterial,
+        containsUnits(x, y) {
+            let i = Math.floor(x / cellWidth), j = Math.floor(y / cellHeight);
+            if (!(i > 0))
+                i = 0;
+            else if (i >= cellsX)
+                i = cellsX - 1;
+            if (!(j > 0))
+                j = 0;
+            else if (j >= cellsY)
+                j = cellsY - 1;
+            const list = cells[j * cellsX + i];
+            for (let k = 0; k < list.length; k++)
+                if (shapeContains(shapes[list[k]], x, y))
+                    return true;
+            return false;
+        } });
+}
+/**
+ * Validates a declared material scene and resolves its chart (in a frame of `aspect` = height / width) and its
+ * layers. `materialAt` is the float64 reference the GPU stage is checked against, and `callerScene` is the same
+ * scene for `simulateCapture`'s `scene` option.
+ */
+export function resolveChartMaterialLayers(input) {
+    requireInputKeys(input, "resolveChartMaterialLayers", ["scene", "aspect"]);
+    const { scene, aspect } = input;
+    requireInputObject(scene, "scene");
+    const record = scene;
+    for (const key of Object.keys(record))
+        if (!["kind", "sceneId", "chart", "layers"].includes(key))
+            throw new InvalidConfigurationError("Unknown scene field: " + key + ".");
+    if (record.kind !== "material-layers")
+        throw new InvalidConfigurationError("scene.kind must be material-layers.");
+    if (typeof record.sceneId !== "string" || !SCENE_ID.test(record.sceneId))
+        throw new InvalidConfigurationError("A material-layers scene needs a public sceneId.");
+    if (typeof aspect !== "number" || !Number.isFinite(aspect) || aspect <= 0)
+        throw new InvalidConfigurationError("Chart aspect must be positive.");
+    const chart = resolveChartScene({ scene: record.chart, aspect });
+    const list = record.layers;
+    if (!Array.isArray(list) || list.length < 1 || list.length > CHART_MATERIAL_LAYER_LIMITS.maximumLayers)
+        throw new InvalidConfigurationError("layers must list 1 to 16 shape-mask layers.");
+    const materials = [...chart.materials], inputs = [...chartMaterialInputs(chart)];
+    const layers = list.map((layer, index) => resolveLayer(layer, "layers[" + index + "]", aspect, materials, inputs));
+    const materialAt = (u, v) => {
+        for (let l = layers.length - 1; l >= 0; l--) {
+            const layer = layers[l], r = layer.rectangle;
+            if (u < r.u0 || u > r.u1 || v < r.v0 || v > r.v1)
+                continue;
+            return layer.containsUnits((u - r.u0) * layer.scaleX, (r.v1 - v) * layer.scaleY) ? layer.inkMaterial : layer.backgroundMaterial;
+        }
+        return chart.materialAt(u, v);
+    };
+    const callerMaterials = materials.map((m, k) => (m.kind === "neutral" ? m.reflectance : inputs[k]));
+    const callerScene = Object.freeze({ kind: "material-function", sceneId: record.sceneId, materials: Object.freeze(callerMaterials),
+        materialAt: (p) => materialAt(p.chartU ?? p.u, p.chartV ?? p.v) });
+    return Object.freeze({ kind: "material-layers", sceneId: record.sceneId, chart, layers: Object.freeze(layers), materials: Object.freeze(materials),
+        materialInputs: Object.freeze(inputs), materialAt, callerScene });
+}
+//# sourceMappingURL=chart-material-layers.js.map

package/dist/facade/chart-material-layers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-material-layers.js","sourceRoot":"","sources":["../../src/facade/chart-material-layers.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Declared material scenes (#477): an engine chart under shape-mask layers, given as data rather than as a\n * `materialAt` function, so that both the float64 reference and the `webgpu-f32` chart stage can evaluate\n * them. An application that prints a label on a chart (a logo and a line of text as filled polygons and\n * stroked rings, in the label's own units) describes it here; the engine holds no label of its own.\n *\n * A layer maps its mask box, [0, unitsWidth] × [0, unitsHeight] with y down, onto a frame rectangle. Inside\n * that rectangle the layer decides the material: the ink material where any of its shapes contains the\n * point, its background material elsewhere. Later layers cover earlier ones, and the chart shows outside\n * every layer. Shapes are polygons under the non-zero winding rule (several rings per shape; a stroked\n * polyline is its rectangles as rings of one orientation) and annuli (stroked circles).\n *\n * Each layer carries a cell index of {@link CHART_MASK_INDEX_GRAIN} cells over its box: a cell lists the\n * shapes whose bounding box meets the cell grown by one cell on every side, so `containsUnits` tests only\n * those. A computed cell can be off by one from the true one only through the rounding of one subtraction\n * and one multiplication, far less than a cell (the grain is checked against the coordinates' magnitude\n * when the layer is resolved), and a shape left out of a cell's list lies a whole cell away from any point\n * that resolves to it, so the indexed test gives the full test's answer at every point. The GPU uses the same\n * index (docs/WEBGPU.md, \"Scene radiance on the GPU\").\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { requireInputKeys, requireInputObject } from \"../core/record-validation.js\";\nimport { resolveChartScene, resolveChartMaterial, chartMaterialInputs, type ChartReflectance, type ChartScene, type ResolvedChartScene } from \"./chart-scenes.js\";\nimport type { CallerMaterialScene, SceneMaterialPoint } from \"./scene-radiance.js\";\n\n/** A filled polygon: rings as flat [x0, y0, x1, y1, …] in mask units (y down), non-zero winding over all rings. */\nexport interface ChartMaskPolygon { kind: \"polygon\"; rings: readonly (readonly number[])[] }\n/** A stroked circle: the points at distance innerRadius ≤ d ≤ outerRadius from the centre, mask units. */\nexport interface ChartMaskAnnulus { kind: \"annulus\"; centerX: number; centerY: number; innerRadius: number; outerRadius: number }\nexport type ChartMaskShape = ChartMaskPolygon | ChartMaskAnnulus;\n/** A shape mask printed over the chart: its box [0, unitsWidth] × [0, unitsHeight] (y down) fills `rectangle` (frame units, v up). */\nexport interface ChartMaskLayer {\n  kind: \"shape-mask\";\n  rectangle: { u0: number; v0: number; u1: number; v1: number };\n  unitsWidth: number;\n  unitsHeight: number;\n  /** 1 to 4096 shapes, in order; the ink material where any contains the point. */\n  shapes: readonly ChartMaskShape[];\n  backgroundReflectance: ChartReflectance;\n  inkReflectance: ChartReflectance;\n}\n/** A chart under 1 to 16 shape-mask layers, as data; `resolveChartMaterialLayers` evaluates it. */\nexport interface ChartMaterialLayerScene { kind: \"material-layers\"; sceneId: string; chart: ChartScene; layers: readonly ChartMaskLayer[] }\n\n/** The cell index grain of every layer: cells across and down the mask box. */\nexport const CHART_MASK_INDEX_GRAIN = Object.freeze({ cellsX: 64, cellsY: 16 });\n/** Limits of a declared scene. */\nexport const CHART_MATERIAL_LAYER_LIMITS = Object.freeze({ maximumLayers: 16, maximumShapes: 4096, maximumRings: 256, maximumEdges: 65_536 });\n\n/** Internal: a shape with its bounding box and flattened edges (polygon) or squared radii (annulus). */\nexport type ResolvedChartMaskShape =\n  | { kind: \"polygon\"; box: readonly [number, number, number, number]; edges: Float64Array }\n  | { kind: \"annulus\"; box: readonly [number, number, number, number]; centerX: number; centerY: number; inner2: number; outer2: number };\nexport interface ResolvedChartMaskLayer {\n  rectangle: { u0: number; v0: number; u1: number; v1: number };\n  unitsWidth: number;\n  unitsHeight: number;\n  /** Mask units per frame unit: unitsWidth / (u1 − u0) and unitsHeight / (v1 − v0). */\n  scaleX: number;\n  scaleY: number;\n  shapes: readonly ResolvedChartMaskShape[];\n  cellsX: number;\n  cellsY: number;\n  cellWidth: number;\n  cellHeight: number;\n  /** Per cell (row by row), the shape indices whose bounding box meets the cell grown by one cell. */\n  cells: readonly Uint32Array[];\n  backgroundMaterial: number;\n  inkMaterial: number;\n  /** Whether a point in mask units is ink (through the cell index). */\n  containsUnits(x: number, y: number): boolean;\n}\nexport interface ResolvedChartMaterialLayers {\n  kind: \"material-layers\";\n  sceneId: string;\n  /** The chart under the layers; its materials come first in `materials`. */\n  chart: ResolvedChartScene;\n  layers: readonly ResolvedChartMaskLayer[];\n  materials: ResolvedChartScene[\"materials\"];\n  /** Internal: the caller input behind each material (undefined for an engine neutral), for the scene digest. */\n  materialInputs: readonly unknown[];\n  /** Material index at a frame point (u right, v up): the topmost layer whose rectangle holds the point, else the chart. */\n  materialAt(u: number, v: number): number;\n  /** The same scene as a caller material scene for `simulateCapture` and the display view (chart-local coordinates when the chart has a size). */\n  callerScene: CallerMaterialScene;\n}\n\nconst SCENE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/u;\nconst finite = (value: unknown, name: string): number => {\n  if (typeof value !== \"number\" || !Number.isFinite(value)) throw new InvalidConfigurationError(name + \" must be a finite number.\");\n  return value;\n};\n/** The smallest cell the one-cell margin covers: the rounding of (x − 0)·scale is a few units in the last place of the coordinates. */\nconst minimumCell = (extent: number): number => Math.max(extent, Number.MIN_VALUE) * 2 ** -20;\n\nfunction resolvePolygon(shape: ChartMaskPolygon, name: string): ResolvedChartMaskShape {\n  const rings = shape.rings;\n  if (!Array.isArray(rings) || rings.length < 1 || rings.length > CHART_MATERIAL_LAYER_LIMITS.maximumRings) throw new InvalidConfigurationError(name + \" needs 1 to 256 rings.\");\n  let count = 0;\n  for (const ring of rings) {\n    if (!Array.isArray(ring) || ring.length < 6 || ring.length % 2 !== 0) throw new InvalidConfigurationError(name + \" rings need at least three (x, y) vertices.\");\n    count += ring.length / 2;\n  }\n  if (count > CHART_MATERIAL_LAYER_LIMITS.maximumEdges) throw new InvalidConfigurationError(name + \" has more than 65536 edges.\");\n  const edges = new Float64Array(4 * count);\n  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity, e = 0;\n  for (const ring of rings) {\n    const n = ring.length / 2;\n    for (let k = 0; k < n; k++) {\n      const x0 = finite(ring[2 * k], name + \" vertex\"), y0 = finite(ring[2 * k + 1], name + \" vertex\");\n      const next = k + 1 === n ? 0 : k + 1, x1 = finite(ring[2 * next], name + \" vertex\"), y1 = finite(ring[2 * next + 1], name + \" vertex\");\n      edges[e++] = x0; edges[e++] = y0; edges[e++] = x1; edges[e++] = y1;\n      minX = Math.min(minX, x0); minY = Math.min(minY, y0); maxX = Math.max(maxX, x0); maxY = Math.max(maxY, y0);\n    }\n  }\n  return { kind: \"polygon\", box: [minX, minY, maxX, maxY], edges };\n}\n\n/** Non-zero winding over the edges (x0, y0, x1, y1), as the reference evaluates it; the GPU runs the same comparisons. */\nexport function polygonWinding(edges: Float64Array, x: number, y: number): number {\n  let winding = 0;\n  for (let k = 0; k < edges.length; k += 4) {\n    const x0 = edges[k]!, y0 = edges[k + 1]!, x1 = edges[k + 2]!, y1 = edges[k + 3]!;\n    const side = (x1 - x0) * (y - y0) - (x - x0) * (y1 - y0);\n    if (y0 <= y) {\n      if (y1 > y && side > 0) winding++;\n    } else if (y1 <= y && side < 0) winding--;\n  }\n  return winding;\n}\n/** Whether a resolved shape contains a point in mask units (the full test, without the cell index). */\nexport function shapeContains(shape: ResolvedChartMaskShape, x: number, y: number): boolean {\n  const b = shape.box;\n  if (!(x >= b[0] && x <= b[2] && y >= b[1] && y <= b[3])) return false;\n  if (shape.kind === \"annulus\") {\n    const d2 = (x - shape.centerX) * (x - shape.centerX) + (y - shape.centerY) * (y - shape.centerY);\n    return d2 >= shape.inner2 && d2 <= shape.outer2;\n  }\n  return polygonWinding(shape.edges, x, y) !== 0;\n}\n\nfunction resolveLayer(value: unknown, name: string, aspect: number, materials: ResolvedChartScene[\"materials\"][number][], inputs: unknown[]): ResolvedChartMaskLayer {\n  requireInputObject(value, name);\n  const layer = value as Record<string, unknown>;\n  for (const key of Object.keys(layer)) {\n    if (![\"kind\", \"rectangle\", \"unitsWidth\", \"unitsHeight\", \"shapes\", \"backgroundReflectance\", \"inkReflectance\"].includes(key)) throw new InvalidConfigurationError(\"Unknown \" + name + \" field: \" + key + \".\");\n  }\n  if (layer.kind !== \"shape-mask\") throw new InvalidConfigurationError(name + \".kind must be shape-mask.\");\n  requireInputObject(layer.rectangle, name + \".rectangle\");\n  const r = layer.rectangle as Record<string, unknown>;\n  for (const key of Object.keys(r)) if (![\"u0\", \"v0\", \"u1\", \"v1\"].includes(key)) throw new InvalidConfigurationError(\"Unknown \" + name + \".rectangle field: \" + key + \".\");\n  const u0 = finite(r.u0, name + \".rectangle.u0\"), v0 = finite(r.v0, name + \".rectangle.v0\"), u1 = finite(r.u1, name + \".rectangle.u1\"), v1 = finite(r.v1, name + \".rectangle.v1\");\n  if (!(u1 > u0 && v1 > v0) || Math.max(Math.abs(u0), Math.abs(u1)) > 1e6 || Math.max(Math.abs(v0), Math.abs(v1)) > 1e6 * Math.max(1, aspect)) {\n    throw new InvalidConfigurationError(name + \".rectangle needs u0 < u1 and v0 < v1 within 10^6 frame units.\");\n  }\n  const unitsWidth = finite(layer.unitsWidth, name + \".unitsWidth\"), unitsHeight = finite(layer.unitsHeight, name + \".unitsHeight\");\n  if (!(unitsWidth > 0 && unitsHeight > 0 && unitsWidth <= 1e9 && unitsHeight <= 1e9)) throw new InvalidConfigurationError(name + \" units must be positive and at most 10^9.\");\n  const list = layer.shapes;\n  if (!Array.isArray(list) || list.length < 1 || list.length > CHART_MATERIAL_LAYER_LIMITS.maximumShapes) throw new InvalidConfigurationError(name + \".shapes must list 1 to 4096 shapes.\");\n  const shapes = list.map((shape: unknown, index: number): ResolvedChartMaskShape => {\n    const label = name + \".shapes[\" + index + \"]\";\n    requireInputObject(shape, label);\n    const s = shape as Record<string, unknown>;\n    if (s.kind === \"polygon\") {\n      for (const key of Object.keys(s)) if (key !== \"kind\" && key !== \"rings\") throw new InvalidConfigurationError(\"Unknown \" + label + \" field: \" + key + \".\");\n      return resolvePolygon(s as unknown as ChartMaskPolygon, label);\n    }\n    if (s.kind !== \"annulus\") throw new InvalidConfigurationError(label + \".kind must be polygon or annulus.\");\n    for (const key of Object.keys(s)) if (![\"kind\", \"centerX\", \"centerY\", \"innerRadius\", \"outerRadius\"].includes(key)) throw new InvalidConfigurationError(\"Unknown \" + label + \" field: \" + key + \".\");\n    const cx = finite(s.centerX, label + \".centerX\"), cy = finite(s.centerY, label + \".centerY\");\n    const inner = finite(s.innerRadius, label + \".innerRadius\"), outer = finite(s.outerRadius, label + \".outerRadius\");\n    if (!(inner >= 0 && outer > inner)) throw new InvalidConfigurationError(label + \" needs 0 ≤ innerRadius < outerRadius.\");\n    return { kind: \"annulus\", box: [cx - outer, cy - outer, cx + outer, cy + outer], centerX: cx, centerY: cy, inner2: inner * inner, outer2: outer * outer };\n  });\n  for (const shape of shapes) {\n    if (!shape.box.every((c) => Math.abs(c) <= 1e9)) throw new InvalidConfigurationError(name + \" shape coordinates must stay within 10^9 units.\");\n  }\n  const backgroundMaterial = materials.length;\n  materials.push(resolveChartMaterial(layer.backgroundReflectance, name + \".backgroundReflectance\"));\n  inputs.push(typeof layer.backgroundReflectance === \"number\" ? undefined : layer.backgroundReflectance);\n  const inkMaterial = materials.length;\n  materials.push(resolveChartMaterial(layer.inkReflectance, name + \".inkReflectance\"));\n  inputs.push(typeof layer.inkReflectance === \"number\" ? undefined : layer.inkReflectance);\n  // The cell index over the mask box; the grain must stay large against the coordinates' rounding (see the header).\n  const { cellsX, cellsY } = CHART_MASK_INDEX_GRAIN, cellWidth = unitsWidth / cellsX, cellHeight = unitsHeight / cellsY;\n  const extentX = Math.max(unitsWidth, ...shapes.map((s) => Math.max(Math.abs(s.box[0]), Math.abs(s.box[2]))));\n  const extentY = Math.max(unitsHeight, ...shapes.map((s) => Math.max(Math.abs(s.box[1]), Math.abs(s.box[3]))));\n  if (!(cellWidth > minimumCell(extentX) && cellHeight > minimumCell(extentY))) throw new InvalidConfigurationError(name + \": the shapes extend too far beyond the mask box for its cell index.\");\n  const cells: Uint32Array[] = [];\n  for (let j = 0; j < cellsY; j++) {\n    for (let i = 0; i < cellsX; i++) {\n      const x0 = (i - 1) * cellWidth, x1 = (i + 2) * cellWidth, y0 = (j - 1) * cellHeight, y1 = (j + 2) * cellHeight, listed: number[] = [];\n      shapes.forEach((s, k) => { if (s.box[0] <= x1 && s.box[2] >= x0 && s.box[1] <= y1 && s.box[3] >= y0) listed.push(k); });\n      cells.push(Uint32Array.from(listed));\n    }\n  }\n  const scaleX = unitsWidth / (u1 - u0), scaleY = unitsHeight / (v1 - v0);\n  return Object.freeze({ rectangle: Object.freeze({ u0, v0, u1, v1 }), unitsWidth, unitsHeight, scaleX, scaleY, shapes: Object.freeze(shapes), cellsX, cellsY, cellWidth, cellHeight,\n    cells: Object.freeze(cells), backgroundMaterial, inkMaterial,\n    containsUnits(x: number, y: number): boolean {\n      let i = Math.floor(x / cellWidth), j = Math.floor(y / cellHeight);\n      if (!(i > 0)) i = 0; else if (i >= cellsX) i = cellsX - 1;\n      if (!(j > 0)) j = 0; else if (j >= cellsY) j = cellsY - 1;\n      const list = cells[j * cellsX + i]!;\n      for (let k = 0; k < list.length; k++) if (shapeContains(shapes[list[k]!]!, x, y)) return true;\n      return false;\n    } });\n}\n\n/**\n * Validates a declared material scene and resolves its chart (in a frame of `aspect` = height / width) and its\n * layers. `materialAt` is the float64 reference the GPU stage is checked against, and `callerScene` is the same\n * scene for `simulateCapture`'s `scene` option.\n */\nexport function resolveChartMaterialLayers(input: { scene: ChartMaterialLayerScene; aspect: number }): ResolvedChartMaterialLayers {\n  requireInputKeys(input, \"resolveChartMaterialLayers\", [\"scene\", \"aspect\"]);\n  const { scene, aspect } = input;\n  requireInputObject(scene, \"scene\");\n  const record = scene as unknown as Record<string, unknown>;\n  for (const key of Object.keys(record)) if (![\"kind\", \"sceneId\", \"chart\", \"layers\"].includes(key)) throw new InvalidConfigurationError(\"Unknown scene field: \" + key + \".\");\n  if (record.kind !== \"material-layers\") throw new InvalidConfigurationError(\"scene.kind must be material-layers.\");\n  if (typeof record.sceneId !== \"string\" || !SCENE_ID.test(record.sceneId)) throw new InvalidConfigurationError(\"A material-layers scene needs a public sceneId.\");\n  if (typeof aspect !== \"number\" || !Number.isFinite(aspect) || aspect <= 0) throw new InvalidConfigurationError(\"Chart aspect must be positive.\");\n  const chart = resolveChartScene({ scene: record.chart as ChartScene, aspect });\n  const list = record.layers;\n  if (!Array.isArray(list) || list.length < 1 || list.length > CHART_MATERIAL_LAYER_LIMITS.maximumLayers) throw new InvalidConfigurationError(\"layers must list 1 to 16 shape-mask layers.\");\n  const materials: ResolvedChartScene[\"materials\"][number][] = [...chart.materials], inputs: unknown[] = [...chartMaterialInputs(chart)];\n  const layers = list.map((layer: unknown, index: number) => resolveLayer(layer, \"layers[\" + index + \"]\", aspect, materials, inputs));\n  const materialAt = (u: number, v: number): number => {\n    for (let l = layers.length - 1; l >= 0; l--) {\n      const layer = layers[l]!, r = layer.rectangle;\n      if (u < r.u0 || u > r.u1 || v < r.v0 || v > r.v1) continue;\n      return layer.containsUnits((u - r.u0) * layer.scaleX, (r.v1 - v) * layer.scaleY) ? layer.inkMaterial : layer.backgroundMaterial;\n    }\n    return chart.materialAt(u, v);\n  };\n  const callerMaterials = materials.map((m, k) => (m.kind === \"neutral\" ? m.reflectance : inputs[k] as ChartReflectance));\n  const callerScene: CallerMaterialScene = Object.freeze({ kind: \"material-function\" as const, sceneId: record.sceneId, materials: Object.freeze(callerMaterials),\n    materialAt: (p: Readonly<SceneMaterialPoint>) => materialAt(p.chartU ?? p.u, p.chartV ?? p.v) });\n  return Object.freeze({ kind: \"material-layers\" as const, sceneId: record.sceneId, chart, layers: Object.freeze(layers), materials: Object.freeze(materials),\n    materialInputs: Object.freeze(inputs), materialAt, callerScene });\n}\n"]}

package/dist/facade/chart-radiance-batch.d.ts

@@ -1,4 +1,5 @@
 import { type ChartScene, type ResolvedChartScene } from "./chart-scenes.js";
+import { type ChartMaterialLayerScene, type ResolvedChartMaterialLayers } from "./chart-material-layers.js";
 import { type CaptureIlluminant, type ResolvedCaptureIlluminant } from "./scene-radiance.js";
 export declare const CHART_RADIANCE_BATCH_SCHEMA_VERSION: "0.1.0";
 /** `maximumQueries` is the default batch limit; a request may raise it with its own `maximumQueries`, up to `ceilingQueries`. */
@@ -10,8 +11,8 @@ export declare const CHART_RADIANCE_BATCH_LIMITS: Readonly<{
 }>;
 export interface ChartRadianceBatchInput {
     schemaVersion: typeof CHART_RADIANCE_BATCH_SCHEMA_VERSION;
-    /** An engine chart preset (caller scene functions are not supported here). */
-    scene: ChartScene;
+    /** An engine chart preset, or (#477) a declared `material-layers` scene: a chart under shape-mask layers. Caller scene functions are not supported here. */
+    scene: ChartScene | ChartMaterialLayerScene;
     illuminant: CaptureIlluminant;
     illuminanceLux: number;
     /** Frame height / width. */
@@ -32,7 +33,12 @@ export interface ChartRadianceBatchInput {
 }
 /** Validated plan with the resolved chart, illuminant and irradiance scale. Arrays are borrowed. */
 export interface ChartRadianceBatchPlan {
+    /** The resolved chart; with a `material-layers` scene, the chart under the layers. */
     chart: ResolvedChartScene;
+    /** The resolved layers of a `material-layers` scene, or null for a chart preset. */
+    layers: ResolvedChartMaterialLayers | null;
+    /** Every material a query can resolve to: the chart's, then each layer's background and ink. */
+    materials: ResolvedChartScene["materials"];
     illuminant: ResolvedCaptureIlluminant;
     irradianceScale: number;
     queryCount: number;

package/dist/facade/chart-radiance-batch.js

@@ -19,6 +19,7 @@ import { InvalidConfigurationError } from "../core/configuration-error.js";
 import { requireAllowlistedRecord } from "../core/record-validation.js";
 import { FULL_RESOLUTION_CEILING_PIXELS, resolveRaisedLimit } from "../core/pixel-limits.js";
 import { resolveChartScene } from "./chart-scenes.js";
+import { resolveChartMaterialLayers } from "./chart-material-layers.js";
 import { buildPlanarSceneRadianceProvider, calculateIlluminantIrradianceScale, resolveCaptureIlluminant, tabulatedSpectrum } from "./scene-radiance.js";
 export const CHART_RADIANCE_BATCH_SCHEMA_VERSION = "0.1.0";
 /** `maximumQueries` is the default batch limit; a request may raise it with its own `maximumQueries`, up to `ceilingQueries`. */
@@ -31,7 +32,11 @@ export function calculateChartRadianceBatchPlan(input) {
         throw new InvalidConfigurationError("Unsupported chart radiance batch schema.");
     if (typeof r.aspect !== "number" || !(r.aspect > 0 && r.aspect <= Number.MAX_VALUE))
         throw new InvalidConfigurationError("aspect must be positive.");
-    const chart = resolveChartScene({ scene: r.scene, aspect: r.aspect });
+    const sceneRecord = r.scene;
+    const layers = sceneRecord !== null && typeof sceneRecord === "object" && sceneRecord.kind === "material-layers"
+        ? resolveChartMaterialLayers({ scene: r.scene, aspect: r.aspect }) : null;
+    const chart = layers ? layers.chart : resolveChartScene({ scene: r.scene, aspect: r.aspect });
+    const materials = layers ? layers.materials : chart.materials;
     const illuminant = resolveCaptureIlluminant(r.illuminant);
     const irradianceScale = calculateIlluminantIrradianceScale(illuminant.shape, r.illuminanceLux);
     const L = CHART_RADIANCE_BATCH_LIMITS, points = r.points;
@@ -63,19 +68,21 @@ export function calculateChartRadianceBatchPlan(input) {
         throw new InvalidConfigurationError("channelWeights must hold 1 to 4 rows of one finite weight per wavelength.");
     }
     // The provider's own radiance function: chart reflectance × scaled illuminant / π, in its float64 order.
-    const provider = buildPlanarSceneRadianceProvider({ scene: chart, sceneId: "chart-radiance-batch", providerProfileId: "chart-radiance-batch", illuminant,
+    const providerScene = layers ? { kind: "material-function", sceneId: layers.sceneId, materials: layers.materials, materialInputs: layers.materialInputs,
+        materialAt: (point) => layers.materialAt(point.u, point.v) } : chart;
+    const provider = buildPlanarSceneRadianceProvider({ scene: providerScene, sceneId: "chart-radiance-batch", providerProfileId: "chart-radiance-batch", illuminant,
         irradianceScale, geometry: { distanceM: 1, metresPerFrameUnit: 1 }, evidence: [], limitations: [] });
     const channelWeights = weights === undefined ? null : weights.map(row => Object.freeze([...row]));
     const nm = Object.freeze([...wavelengths]);
     const shapeAt = tabulatedSpectrum(illuminant.shape);
     const materialRadiance = (material, wavelength) => {
-        const m = chart.materials[material];
+        const m = materials[material];
         const reflectance = m.kind === "neutral" ? m.reflectance : m.spectrum.evaluate(wavelength);
         if (m.kind === "spectrum" && !(reflectance >= 0 && reflectance <= 1))
             throw new InvalidConfigurationError("Chart reflectance spectrum left [0, 1].");
         return reflectance * irradianceScale * shapeAt(wavelength) / Math.PI;
     };
-    return Object.freeze({ chart, illuminant, irradianceScale, queryCount, columns: channelWeights === null ? 1 : channelWeights.length,
+    return Object.freeze({ chart, layers, materials, illuminant, irradianceScale, queryCount, columns: channelWeights === null ? 1 : channelWeights.length,
         mode: channelWeights === null ? "radiance" : "spectral-integral", wavelengthsNanometers: nm, channelWeights, materialRadiance,
         queryValue(p, w, query, column) {
             const u = p[2 * query], v = p[2 * query + 1];