@photivra/engine 2.20.0 → 2.22.0

package/dist/facade/quality-kit.js

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 2.22.0 (#594): the CPU full-quality code, one module that the capture and the display view load on demand (`loadQualityKit`,
+ * src/facade/on-demand-kits.ts) where they parse a request that asks for it, so a bundler that splits dynamic imports puts all of
+ * it in one chunk outside the default path. Only re-exports: the code, its results and its bounds are those of the modules named.
+ *
+ * - Diffraction (2.1): the Airy profile, its site kernels and their convolution.
+ * - The capture's AHD demosaic (`output.demosaic: "ahd"`).
+ * - `lens.defocus` beyond the geometric disc (owner, 2026-11-10): the bokeh shapes, the cat's eye and their field zones, the
+ *   lattice of a disc above the direct radius (#564) and the image-space provider (lens projection and distortion).
+ * - The display view's coupled rendering steps (#593, #601: luminance tone curves, reconstruct, desaturation) and the neighbor
+ *   highlight reconstruction (#602).
+ */
+export { createDiffractionLimitedPsfProfile } from "../optics/diffraction-psf-profile.js";
+export { registerDiffractionPsfKey, siteDiffractionKernel } from "../optics/site-diffraction-kernel.js";
+export { createAhdDemosaicTask } from "../processing/demosaic.js";
+export { createDefocusBokehSiteKernel, resolveDefocusBokehOptions } from "../optics/defocus-bokeh-kernel.js";
+export { planDefocusBokehZones } from "./defocus-bokeh-zones.js";
+export { LARGE_DEFOCUS_CACHE_BYTES, createLargeDefocusNodeLattice } from "./large-defocus-lattice.js";
+export { calculateDefocusFieldVariation, createDefocusImageSpaceProvider, prepareDefocusImageSpaceGeometry } from "./defocus-image-space-provider.js";
+export { createDisplayViewCoupledRendering } from "./display-view-rendering.js";
+export * as neighborHighlights from "../color/neighbor-highlight-reconstruction.js";
+//# sourceMappingURL=quality-kit.js.map

package/dist/facade/quality-kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-kit.js","sourceRoot":"","sources":["../../src/facade/quality-kit.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,kCAAkC,EAAE,MAAM,sCAAsC,CAAC;AAC1F,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AACxG,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAC7G,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,yBAAyB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AACtG,OAAO,EAAE,8BAA8B,EAAE,+BAA+B,EAAE,gCAAgC,EAAE,MAAM,mCAAmC,CAAC;AACtJ,OAAO,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,KAAK,kBAAkB,MAAM,+CAA+C,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * 2.22.0 (#594): the CPU full-quality code, one module that the capture and the display view load on demand (`loadQualityKit`,\n * src/facade/on-demand-kits.ts) where they parse a request that asks for it, so a bundler that splits dynamic imports puts all of\n * it in one chunk outside the default path. Only re-exports: the code, its results and its bounds are those of the modules named.\n *\n * - Diffraction (2.1): the Airy profile, its site kernels and their convolution.\n * - The capture's AHD demosaic (`output.demosaic: \"ahd\"`).\n * - `lens.defocus` beyond the geometric disc (owner, 2026-11-10): the bokeh shapes, the cat's eye and their field zones, the\n *   lattice of a disc above the direct radius (#564) and the image-space provider (lens projection and distortion).\n * - The display view's coupled rendering steps (#593, #601: luminance tone curves, reconstruct, desaturation) and the neighbor\n *   highlight reconstruction (#602).\n */\n\nexport { createDiffractionLimitedPsfProfile } from \"../optics/diffraction-psf-profile.js\";\nexport { registerDiffractionPsfKey, siteDiffractionKernel } from \"../optics/site-diffraction-kernel.js\";\nexport { createAhdDemosaicTask } from \"../processing/demosaic.js\";\nexport { createDefocusBokehSiteKernel, resolveDefocusBokehOptions } from \"../optics/defocus-bokeh-kernel.js\";\nexport { planDefocusBokehZones } from \"./defocus-bokeh-zones.js\";\nexport { LARGE_DEFOCUS_CACHE_BYTES, createLargeDefocusNodeLattice } from \"./large-defocus-lattice.js\";\nexport { calculateDefocusFieldVariation, createDefocusImageSpaceProvider, prepareDefocusImageSpaceGeometry } from \"./defocus-image-space-provider.js\";\nexport { createDisplayViewCoupledRendering } from \"./display-view-rendering.js\";\nexport * as neighborHighlights from \"../color/neighbor-highlight-reconstruction.js\";\n"]}

package/dist/facade/quality-paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Loads the engine's on-demand full-quality code now instead of at the first request that needs it (#594): the CPU Quality kit
+ * (diffraction, the capture's AHD demosaic, `lens.defocus` beyond the geometric disc, the image-space provider of lens projection,
+ * distortion and vignetting, the display view's coupled tone, reconstruct and desaturation steps, the neighbor highlight
+ * reconstruction), the opt-in kit (`sensor.profile`, `illumination`, `motion.subject`) and the display view's GPU full-quality code
+ * (the Quality passes behind `prepareDisplayView(…, { gpu: "auto" | "require" })`), together with the GPU session it builds on.
+ *
+ * Optional: without it, the first request that needs the code loads it. Safe to call at any time and from any number of places:
+ * concurrent calls share one load, and a call after it loaded resolves at once and loads nothing. It changes no result. If the
+ * load fails (for example a chunk download error) the promise rejects with `ImageKernelExecutionError` reason
+ * `quality-code-unavailable`; nothing is remembered, so a later call or request tries again, and a render in the meantime runs
+ * the CPU reference, labelled with that reason. A bundler that splits dynamic imports keeps this code out of the first load
+ * whether or not this function is imported.
+ *
+ * @example
+ * ```ts
+ * import { prepareQualityPaths } from "@photivra/engine";
+ * // The user opened Export, where full-quality renders follow: fetch their code while they choose a format.
+ * void prepareQualityPaths().catch(() => undefined); // a failed preload is retried by the render that needs the code
+ * ```
+ */
+export declare function prepareQualityPaths(): Promise<void>;

package/dist/facade/quality-paths.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 2.22.0 (#594): the optional preload of the engine's on-demand full-quality code. The Quality paths load automatically at the
+ * first request that needs them; this loads them ahead of time, so that request does not wait for the download.
+ */
+import { ImageKernelExecutionError } from "../gpu/image-kernel-execution.js";
+import { optInKit, qualityKit } from "./on-demand-kits.js";
+let pending = null;
+/**
+ * Loads the engine's on-demand full-quality code now instead of at the first request that needs it (#594): the CPU Quality kit
+ * (diffraction, the capture's AHD demosaic, `lens.defocus` beyond the geometric disc, the image-space provider of lens projection,
+ * distortion and vignetting, the display view's coupled tone, reconstruct and desaturation steps, the neighbor highlight
+ * reconstruction), the opt-in kit (`sensor.profile`, `illumination`, `motion.subject`) and the display view's GPU full-quality code
+ * (the Quality passes behind `prepareDisplayView(…, { gpu: "auto" | "require" })`), together with the GPU session it builds on.
+ *
+ * Optional: without it, the first request that needs the code loads it. Safe to call at any time and from any number of places:
+ * concurrent calls share one load, and a call after it loaded resolves at once and loads nothing. It changes no result. If the
+ * load fails (for example a chunk download error) the promise rejects with `ImageKernelExecutionError` reason
+ * `quality-code-unavailable`; nothing is remembered, so a later call or request tries again, and a render in the meantime runs
+ * the CPU reference, labelled with that reason. A bundler that splits dynamic imports keeps this code out of the first load
+ * whether or not this function is imported.
+ *
+ * @example
+ * ```ts
+ * import { prepareQualityPaths } from "@photivra/engine";
+ * // The user opened Export, where full-quality renders follow: fetch their code while they choose a format.
+ * void prepareQualityPaths().catch(() => undefined); // a failed preload is retried by the render that needs the code
+ * ```
+ */
+export function prepareQualityPaths() {
+    if (!pending) {
+        const load = Promise.all([qualityKit.load(), optInKit.load(),
+            import("../gpu/display-view-gpu-renderer.js").then((renderer) => renderer.prepareDisplayViewQualityGpu())]).then(() => undefined, (error) => {
+            if (error instanceof ImageKernelExecutionError)
+                throw error;
+            throw new ImageKernelExecutionError("quality-code-unavailable", "the engine's full-quality code could not be loaded: " + (error instanceof Error ? error.message : String(error)));
+        });
+        pending = load;
+        load.catch(() => { if (pending === load)
+            pending = null; });
+    }
+    return pending;
+}
+//# sourceMappingURL=quality-paths.js.map

package/dist/facade/quality-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality-paths.js","sourceRoot":"","sources":["../../src/facade/quality-paths.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;GAGG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE3D,IAAI,OAAO,GAAyB,IAAI,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,GAAkB,OAAO,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,QAAQ,CAAC,IAAI,EAAE;YACzE,MAAM,CAAC,qCAAqC,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,4BAA4B,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,KAAc,EAAE,EAAE;YACrJ,IAAI,KAAK,YAAY,yBAAyB;gBAAE,MAAM,KAAK,CAAC;YAC5D,MAAM,IAAI,yBAAyB,CAAC,0BAA0B,EAAE,sDAAsD,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACrL,CAAC,CAAC,CAAC;QACH,OAAO,GAAG,IAAI,CAAC;QACf,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * 2.22.0 (#594): the optional preload of the engine's on-demand full-quality code. The Quality paths load automatically at the\n * first request that needs them; this loads them ahead of time, so that request does not wait for the download.\n */\n\nimport { ImageKernelExecutionError } from \"../gpu/image-kernel-execution.js\";\nimport { optInKit, qualityKit } from \"./on-demand-kits.js\";\n\nlet pending: Promise<void> | null = null;\n\n/**\n * Loads the engine's on-demand full-quality code now instead of at the first request that needs it (#594): the CPU Quality kit\n * (diffraction, the capture's AHD demosaic, `lens.defocus` beyond the geometric disc, the image-space provider of lens projection,\n * distortion and vignetting, the display view's coupled tone, reconstruct and desaturation steps, the neighbor highlight\n * reconstruction), the opt-in kit (`sensor.profile`, `illumination`, `motion.subject`) and the display view's GPU full-quality code\n * (the Quality passes behind `prepareDisplayView(…, { gpu: \"auto\" | \"require\" })`), together with the GPU session it builds on.\n *\n * Optional: without it, the first request that needs the code loads it. Safe to call at any time and from any number of places:\n * concurrent calls share one load, and a call after it loaded resolves at once and loads nothing. It changes no result. If the\n * load fails (for example a chunk download error) the promise rejects with `ImageKernelExecutionError` reason\n * `quality-code-unavailable`; nothing is remembered, so a later call or request tries again, and a render in the meantime runs\n * the CPU reference, labelled with that reason. A bundler that splits dynamic imports keeps this code out of the first load\n * whether or not this function is imported.\n *\n * @example\n * ```ts\n * import { prepareQualityPaths } from \"@photivra/engine\";\n * // The user opened Export, where full-quality renders follow: fetch their code while they choose a format.\n * void prepareQualityPaths().catch(() => undefined); // a failed preload is retried by the render that needs the code\n * ```\n */\nexport function prepareQualityPaths(): Promise<void> {\n  if (!pending) {\n    const load: Promise<void> = Promise.all([qualityKit.load(), optInKit.load(),\n      import(\"../gpu/display-view-gpu-renderer.js\").then((renderer) => renderer.prepareDisplayViewQualityGpu())]).then(() => undefined, (error: unknown) => {\n      if (error instanceof ImageKernelExecutionError) throw error;\n      throw new ImageKernelExecutionError(\"quality-code-unavailable\", \"the engine's full-quality code could not be loaded: \" + (error instanceof Error ? error.message : String(error)));\n    });\n    pending = load;\n    load.catch(() => { if (pending === load) pending = null; });\n  }\n  return pending;\n}\n"]}

package/dist/facade/representative-light-sources.d.ts

@@ -0,0 +1,72 @@
+import type { ColorimetricSpectrum } from "../color/color-matching-functions.js";
+import type { CaptureIlluminant } from "./scene-radiance.js";
+/** Identity of the built-in light-source set. */
+export declare const REPRESENTATIVE_LIGHT_SOURCE_SET_ID = "photivra-representative-light-sources";
+/** Version of the set's spectra; a change to any spectrum changes it. */
+export declare const REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION = "1.0.0";
+/** Domain of every spectrum, nm (the CIE 1931 observer's domain; the capture facade uses 380–780 nm of it). */
+export declare const REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS: Readonly<{
+    minimum: 360;
+    maximum: 830;
+}>;
+/** The source ids, in set order. */
+export declare const REPRESENTATIVE_LIGHT_SOURCE_IDS: readonly ["tri-phosphor-fluorescent-4000k", "white-led-low-rendering-4000k", "white-led-high-rendering-4000k", "warm-white-led-2700k"];
+export type RepresentativeLightSourceId = (typeof REPRESENTATIVE_LIGHT_SOURCE_IDS)[number];
+/** One Gaussian band a·exp(−½((λ − μ)/σ)²) of a source spectrum. */
+export interface RepresentativeLightSourceBand {
+    kind: "gaussian";
+    /** What the band represents, for example "blue pump" or "green phosphor line". */
+    role: string;
+    amplitude: number;
+    centerNanometers: number;
+    standardDeviationNanometers: number;
+}
+/** One built-in source: its id, name, design reason and spectrum definition. */
+export interface RepresentativeLightSource {
+    sourceId: RepresentativeLightSourceId;
+    /** Photivra's descriptive name, for example "White LED, high color rendering, 4000 K". */
+    name: string;
+    family: "fluorescent" | "led";
+    /** The CCT the spectrum was designed for, K (its computed CCT is within 1 K of it, Duv within 0.0001; docs/LIGHT_SOURCES.md). */
+    nominalCorrelatedColorTemperatureKelvin: number;
+    /** Always "representative, not a named product". */
+    label: "representative, not a named product";
+    /** One sentence: what the source represents and why it is built this way. */
+    reason: string;
+    /** The constant b (a low continuum), relative units. */
+    base: number;
+    bands: readonly RepresentativeLightSourceBand[];
+}
+export interface RepresentativeLightSourceSet {
+    setId: typeof REPRESENTATIVE_LIGHT_SOURCE_SET_ID;
+    setVersion: typeof REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION;
+    wavelengthRangeNanometers: {
+        readonly minimum: number;
+        readonly maximum: number;
+    };
+    sources: readonly RepresentativeLightSource[];
+}
+/**
+ * The built-in representative light sources: Photivra's own parametric spectra of a tri-phosphor fluorescent tube and
+ * three white LEDs (low and high color rendering at 4000 K, warm at 2700 K). A static, deeply frozen engine contract.
+ * Each is "representative, not a named product"; docs/LIGHT_SOURCES.md gives every formula and the reasons for it.
+ */
+export declare function getRepresentativeLightSourceSet(): RepresentativeLightSourceSet;
+/**
+ * A source's relative spectral power distribution S(λ) = b + Σ aₖ·exp(−½((λ − μₖ)/σₖ)²) as a function spectrum on
+ * 360–830 nm (relative units; values memoized per wavelength). Pass it to a capture as
+ * `illuminant: { kind: "spectrum", spectrum }`; for color work use `sensor.spectralStepNanometers: 5` or finer
+ * (docs/LIGHT_SOURCES.md, "Quadrature"). Throws `InvalidScientificInputError` outside 360–830 nm.
+ */
+export declare function createRepresentativeLightSourceSpectrum(input: {
+    sourceId: RepresentativeLightSourceId;
+}): ColorimetricSpectrum;
+/**
+ * A capture illuminant for a source: `{ kind: "spectrum", spectrum, label }` with the spectrum of
+ * {@link createRepresentativeLightSourceSpectrum} and the label "<name> (representative, not a named product)".
+ */
+export declare function createRepresentativeLightSourceIlluminant(input: {
+    sourceId: RepresentativeLightSourceId;
+}): Extract<CaptureIlluminant, {
+    kind: "spectrum";
+}>;

package/dist/facade/representative-light-sources.js

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Representative light sources (#557): four relative spectral power distributions designed by Photivra for indoor
+ * light presets, so that two lights at the same correlated color temperature (CCT) can render colors differently.
+ *
+ * Every spectrum is an engine-defined analytic function of wavelength, not measured or copied data: a constant plus a
+ * sum of Gaussian bands,
+ *
+ *   S(λ) = b + Σₖ aₖ·exp(−½·((λ − μₖ)/σₖ)²),
+ *
+ * with λ in nanometers on 360–830 nm (the CIE 1931 observer's domain), in relative units (the capture facade scales an
+ * illuminant to its lux). Each source's band shapes were chosen by Photivra to represent a kind of lamp; two amplitudes
+ * (or one amplitude and one band center) were then solved so the chromaticity lies on the Planckian locus at the stated
+ * CCT, and rounded (amplitudes to 0.001, wavelengths to 0.1 nm). Those rounded values are the definition. The CCT and
+ * Duv of every rounded spectrum are checked with the engine's own `calculateCorrelatedColorTemperature` and
+ * `estimateCorrelatedColorTemperatureMcCamy` (docs/LIGHT_SOURCES.md, test/representative-light-sources.test.ts).
+ *
+ * These are representative constructions, not named products: no CIE, IES or manufacturer spectral data, names or
+ * tables are used. The bands are wider than the emission lines of real fluorescent phosphors so that the 5 nm sensor
+ * quadrature recommended for color work integrates them; real lamps of each kind vary widely.
+ *
+ * The exponentials use the portable `portableExp`, so a spectrum's values have the same bits in every JavaScript
+ * engine, in captures and in the display view alike.
+ *
+ * The module is not reached by `simulateCapture` itself: an application passes a spectrum as
+ * `illuminant: { kind: "spectrum", spectrum }` (or {@link createRepresentativeLightSourceIlluminant}), so bundles that
+ * do not use the sources do not contain them.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { portableExp } from "../core/portable-math.js";
+/** Identity of the built-in light-source set. */
+export const REPRESENTATIVE_LIGHT_SOURCE_SET_ID = "photivra-representative-light-sources";
+/** Version of the set's spectra; a change to any spectrum changes it. */
+export const REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION = "1.0.0";
+/** Domain of every spectrum, nm (the CIE 1931 observer's domain; the capture facade uses 380–780 nm of it). */
+export const REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS = /* @__PURE__ */ Object.freeze({ minimum: 360, maximum: 830 });
+/** The source ids, in set order. */
+export const REPRESENTATIVE_LIGHT_SOURCE_IDS = /* @__PURE__ */ Object.freeze([
+    "tri-phosphor-fluorescent-4000k", "white-led-low-rendering-4000k", "white-led-high-rendering-4000k", "warm-white-led-2700k"
+]);
+const LABEL = "representative, not a named product";
+/* Photivra's design (docs/LIGHT_SOURCES.md, "The spectra"); the solved values were rounded and are the definition. */
+const ROWS = [
+    ["tri-phosphor-fluorescent-4000k", "Tri-phosphor fluorescent, 4000 K", "fluorescent", 4000,
+        "Three narrow emission bands in the blue, green and red on a low continuum, the construction of a tri-phosphor fluorescent tube, which leaves gaps between the bands.",
+        0.02, [["blue phosphor band", 0.285, 450, 6], ["green phosphor line", 1, 544, 3.5], ["red phosphor line", 1.02, 611, 3.5]]],
+    ["white-led-low-rendering-4000k", "White LED, low color rendering, 4000 K", "led", 4000,
+        "A blue pump peak and one broad yellow phosphor band, the simplest white LED, which is weak in the cyan and the deep red.",
+        0, [["blue pump", 1.123, 450, 9], ["yellow phosphor", 1, 579.1, 50]]],
+    ["white-led-high-rendering-4000k", "White LED, high color rendering, 4000 K", "led", 4000,
+        "A blue pump with a green and a red phosphor band that fill the cyan and the red, a white LED built for high color rendering at the same CCT as the low-rendering one.",
+        0, [["blue pump", 1.306, 450, 9], ["green phosphor", 1, 530, 35], ["red phosphor", 1.264, 630, 40]]],
+    ["warm-white-led-2700k", "Warm white LED, 2700 K", "led", 2700,
+        "The same pump and two-phosphor construction with more red phosphor and less pump, a warm white LED for home lighting.",
+        0, [["blue pump", 0.795, 450, 9], ["green phosphor", 1, 540, 38], ["red phosphor", 2.133, 630, 40]]]
+];
+const SET = /* @__PURE__ */ (() => Object.freeze({
+    setId: REPRESENTATIVE_LIGHT_SOURCE_SET_ID,
+    setVersion: REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION,
+    wavelengthRangeNanometers: REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS,
+    sources: Object.freeze(ROWS.map(([sourceId, name, family, cct, reason, base, bands]) => Object.freeze({
+        sourceId, name, family, nominalCorrelatedColorTemperatureKelvin: cct, label: LABEL, reason, base,
+        bands: Object.freeze(bands.map(([role, amplitude, centerNanometers, standardDeviationNanometers]) => Object.freeze({ kind: "gaussian", role, amplitude, centerNanometers, standardDeviationNanometers })))
+    })))
+}))();
+/**
+ * The built-in representative light sources: Photivra's own parametric spectra of a tri-phosphor fluorescent tube and
+ * three white LEDs (low and high color rendering at 4000 K, warm at 2700 K). A static, deeply frozen engine contract.
+ * Each is "representative, not a named product"; docs/LIGHT_SOURCES.md gives every formula and the reasons for it.
+ */
+export function getRepresentativeLightSourceSet() {
+    return SET;
+}
+function findSource(input, functionName) {
+    requireInputKeys(input, functionName, ["sourceId"]);
+    const id = input.sourceId;
+    const source = typeof id === "string" ? SET.sources.find((s) => s.sourceId === id) : undefined;
+    if (!source)
+        throw new InvalidConfigurationError("sourceId must be one of the built-in representative light sources (REPRESENTATIVE_LIGHT_SOURCE_IDS).");
+    return source;
+}
+/** Most wavelengths whose values one spectrum keeps (a capture uses a few hundred). */
+const CACHE_LIMIT = 4096;
+/**
+ * A source's relative spectral power distribution S(λ) = b + Σ aₖ·exp(−½((λ − μₖ)/σₖ)²) as a function spectrum on
+ * 360–830 nm (relative units; values memoized per wavelength). Pass it to a capture as
+ * `illuminant: { kind: "spectrum", spectrum }`; for color work use `sensor.spectralStepNanometers: 5` or finer
+ * (docs/LIGHT_SOURCES.md, "Quadrature"). Throws `InvalidScientificInputError` outside 360–830 nm.
+ */
+export function createRepresentativeLightSourceSpectrum(input) {
+    const source = findSource(input, "createRepresentativeLightSourceSpectrum");
+    const range = REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS, cache = new Map();
+    return {
+        kind: "function",
+        wavelengthRangeNanometers: { minimum: range.minimum, maximum: range.maximum },
+        evaluate(nm) {
+            const hit = cache.get(nm);
+            if (hit !== undefined)
+                return hit;
+            if (typeof nm !== "number" || !(nm >= range.minimum && nm <= range.maximum)) {
+                throw new InvalidScientificInputError("Representative light source " + source.sourceId + " is defined on 360–830 nm.");
+            }
+            let value = source.base;
+            for (const band of source.bands) {
+                const z = (nm - band.centerNanometers) / band.standardDeviationNanometers;
+                value += band.amplitude * portableExp(-0.5 * z * z);
+            }
+            if (cache.size < CACHE_LIMIT)
+                cache.set(nm, value);
+            return value;
+        }
+    };
+}
+/**
+ * A capture illuminant for a source: `{ kind: "spectrum", spectrum, label }` with the spectrum of
+ * {@link createRepresentativeLightSourceSpectrum} and the label "<name> (representative, not a named product)".
+ */
+export function createRepresentativeLightSourceIlluminant(input) {
+    const source = findSource(input, "createRepresentativeLightSourceIlluminant");
+    return { kind: "spectrum", spectrum: createRepresentativeLightSourceSpectrum({ sourceId: source.sourceId }), label: source.name + " (" + LABEL + ")" };
+}
+//# sourceMappingURL=representative-light-sources.js.map

package/dist/facade/representative-light-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"representative-light-sources.js","sourceRoot":"","sources":["../../src/facade/representative-light-sources.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Representative light sources (#557): four relative spectral power distributions designed by Photivra for indoor\n * light presets, so that two lights at the same correlated color temperature (CCT) can render colors differently.\n *\n * Every spectrum is an engine-defined analytic function of wavelength, not measured or copied data: a constant plus a\n * sum of Gaussian bands,\n *\n *   S(λ) = b + Σₖ aₖ·exp(−½·((λ − μₖ)/σₖ)²),\n *\n * with λ in nanometers on 360–830 nm (the CIE 1931 observer's domain), in relative units (the capture facade scales an\n * illuminant to its lux). Each source's band shapes were chosen by Photivra to represent a kind of lamp; two amplitudes\n * (or one amplitude and one band center) were then solved so the chromaticity lies on the Planckian locus at the stated\n * CCT, and rounded (amplitudes to 0.001, wavelengths to 0.1 nm). Those rounded values are the definition. The CCT and\n * Duv of every rounded spectrum are checked with the engine's own `calculateCorrelatedColorTemperature` and\n * `estimateCorrelatedColorTemperatureMcCamy` (docs/LIGHT_SOURCES.md, test/representative-light-sources.test.ts).\n *\n * These are representative constructions, not named products: no CIE, IES or manufacturer spectral data, names or\n * tables are used. The bands are wider than the emission lines of real fluorescent phosphors so that the 5 nm sensor\n * quadrature recommended for color work integrates them; real lamps of each kind vary widely.\n *\n * The exponentials use the portable `portableExp`, so a spectrum's values have the same bits in every JavaScript\n * engine, in captures and in the display view alike.\n *\n * The module is not reached by `simulateCapture` itself: an application passes a spectrum as\n * `illuminant: { kind: \"spectrum\", spectrum }` (or {@link createRepresentativeLightSourceIlluminant}), so bundles that\n * do not use the sources do not contain them.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { portableExp } from \"../core/portable-math.js\";\nimport type { ColorimetricSpectrum } from \"../color/color-matching-functions.js\";\nimport type { CaptureIlluminant } from \"./scene-radiance.js\";\n\n/** Identity of the built-in light-source set. */\nexport const REPRESENTATIVE_LIGHT_SOURCE_SET_ID = \"photivra-representative-light-sources\";\n/** Version of the set's spectra; a change to any spectrum changes it. */\nexport const REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION = \"1.0.0\";\n/** Domain of every spectrum, nm (the CIE 1931 observer's domain; the capture facade uses 380–780 nm of it). */\nexport const REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS = /* @__PURE__ */ Object.freeze({ minimum: 360, maximum: 830 });\n\n/** The source ids, in set order. */\nexport const REPRESENTATIVE_LIGHT_SOURCE_IDS = /* @__PURE__ */ Object.freeze([\n  \"tri-phosphor-fluorescent-4000k\", \"white-led-low-rendering-4000k\", \"white-led-high-rendering-4000k\", \"warm-white-led-2700k\"\n] as const);\nexport type RepresentativeLightSourceId = (typeof REPRESENTATIVE_LIGHT_SOURCE_IDS)[number];\n\n/** One Gaussian band a·exp(−½((λ − μ)/σ)²) of a source spectrum. */\nexport interface RepresentativeLightSourceBand {\n  kind: \"gaussian\";\n  /** What the band represents, for example \"blue pump\" or \"green phosphor line\". */\n  role: string;\n  amplitude: number;\n  centerNanometers: number;\n  standardDeviationNanometers: number;\n}\n\n/** One built-in source: its id, name, design reason and spectrum definition. */\nexport interface RepresentativeLightSource {\n  sourceId: RepresentativeLightSourceId;\n  /** Photivra's descriptive name, for example \"White LED, high color rendering, 4000 K\". */\n  name: string;\n  family: \"fluorescent\" | \"led\";\n  /** The CCT the spectrum was designed for, K (its computed CCT is within 1 K of it, Duv within 0.0001; docs/LIGHT_SOURCES.md). */\n  nominalCorrelatedColorTemperatureKelvin: number;\n  /** Always \"representative, not a named product\". */\n  label: \"representative, not a named product\";\n  /** One sentence: what the source represents and why it is built this way. */\n  reason: string;\n  /** The constant b (a low continuum), relative units. */\n  base: number;\n  bands: readonly RepresentativeLightSourceBand[];\n}\n\nexport interface RepresentativeLightSourceSet {\n  setId: typeof REPRESENTATIVE_LIGHT_SOURCE_SET_ID;\n  setVersion: typeof REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION;\n  wavelengthRangeNanometers: { readonly minimum: number; readonly maximum: number };\n  sources: readonly RepresentativeLightSource[];\n}\n\nconst LABEL = \"representative, not a named product\" as const;\ntype BandRow = readonly [role: string, amplitude: number, centerNanometers: number, standardDeviationNanometers: number];\n/* Photivra's design (docs/LIGHT_SOURCES.md, \"The spectra\"); the solved values were rounded and are the definition. */\nconst ROWS: readonly (readonly [RepresentativeLightSourceId, string, \"fluorescent\" | \"led\", number, string, number, readonly BandRow[]])[] = [\n  [\"tri-phosphor-fluorescent-4000k\", \"Tri-phosphor fluorescent, 4000 K\", \"fluorescent\", 4000,\n    \"Three narrow emission bands in the blue, green and red on a low continuum, the construction of a tri-phosphor fluorescent tube, which leaves gaps between the bands.\",\n    0.02, [[\"blue phosphor band\", 0.285, 450, 6], [\"green phosphor line\", 1, 544, 3.5], [\"red phosphor line\", 1.02, 611, 3.5]]],\n  [\"white-led-low-rendering-4000k\", \"White LED, low color rendering, 4000 K\", \"led\", 4000,\n    \"A blue pump peak and one broad yellow phosphor band, the simplest white LED, which is weak in the cyan and the deep red.\",\n    0, [[\"blue pump\", 1.123, 450, 9], [\"yellow phosphor\", 1, 579.1, 50]]],\n  [\"white-led-high-rendering-4000k\", \"White LED, high color rendering, 4000 K\", \"led\", 4000,\n    \"A blue pump with a green and a red phosphor band that fill the cyan and the red, a white LED built for high color rendering at the same CCT as the low-rendering one.\",\n    0, [[\"blue pump\", 1.306, 450, 9], [\"green phosphor\", 1, 530, 35], [\"red phosphor\", 1.264, 630, 40]]],\n  [\"warm-white-led-2700k\", \"Warm white LED, 2700 K\", \"led\", 2700,\n    \"The same pump and two-phosphor construction with more red phosphor and less pump, a warm white LED for home lighting.\",\n    0, [[\"blue pump\", 0.795, 450, 9], [\"green phosphor\", 1, 540, 38], [\"red phosphor\", 2.133, 630, 40]]]\n];\n\nconst SET: RepresentativeLightSourceSet = /* @__PURE__ */ ((): RepresentativeLightSourceSet => Object.freeze({\n  setId: REPRESENTATIVE_LIGHT_SOURCE_SET_ID,\n  setVersion: REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION,\n  wavelengthRangeNanometers: REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS,\n  sources: Object.freeze(ROWS.map(([sourceId, name, family, cct, reason, base, bands]) => Object.freeze({\n    sourceId, name, family, nominalCorrelatedColorTemperatureKelvin: cct, label: LABEL, reason, base,\n    bands: Object.freeze(bands.map(([role, amplitude, centerNanometers, standardDeviationNanometers]) =>\n      Object.freeze({ kind: \"gaussian\" as const, role, amplitude, centerNanometers, standardDeviationNanometers })))\n  })))\n}))();\n\n/**\n * The built-in representative light sources: Photivra's own parametric spectra of a tri-phosphor fluorescent tube and\n * three white LEDs (low and high color rendering at 4000 K, warm at 2700 K). A static, deeply frozen engine contract.\n * Each is \"representative, not a named product\"; docs/LIGHT_SOURCES.md gives every formula and the reasons for it.\n */\nexport function getRepresentativeLightSourceSet(): RepresentativeLightSourceSet {\n  return SET;\n}\n\nfunction findSource(input: unknown, functionName: string): RepresentativeLightSource {\n  requireInputKeys(input, functionName, [\"sourceId\"]);\n  const id = (input as { sourceId?: unknown }).sourceId;\n  const source = typeof id === \"string\" ? SET.sources.find((s) => s.sourceId === id) : undefined;\n  if (!source) throw new InvalidConfigurationError(\"sourceId must be one of the built-in representative light sources (REPRESENTATIVE_LIGHT_SOURCE_IDS).\");\n  return source;\n}\n\n/** Most wavelengths whose values one spectrum keeps (a capture uses a few hundred). */\nconst CACHE_LIMIT = 4096;\n\n/**\n * A source's relative spectral power distribution S(λ) = b + Σ aₖ·exp(−½((λ − μₖ)/σₖ)²) as a function spectrum on\n * 360–830 nm (relative units; values memoized per wavelength). Pass it to a capture as\n * `illuminant: { kind: \"spectrum\", spectrum }`; for color work use `sensor.spectralStepNanometers: 5` or finer\n * (docs/LIGHT_SOURCES.md, \"Quadrature\"). Throws `InvalidScientificInputError` outside 360–830 nm.\n */\nexport function createRepresentativeLightSourceSpectrum(input: { sourceId: RepresentativeLightSourceId }): ColorimetricSpectrum {\n  const source = findSource(input, \"createRepresentativeLightSourceSpectrum\");\n  const range = REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS, cache = new Map<number, number>();\n  return {\n    kind: \"function\",\n    wavelengthRangeNanometers: { minimum: range.minimum, maximum: range.maximum },\n    evaluate(nm: number): number {\n      const hit = cache.get(nm);\n      if (hit !== undefined) return hit;\n      if (typeof nm !== \"number\" || !(nm >= range.minimum && nm <= range.maximum)) {\n        throw new InvalidScientificInputError(\"Representative light source \" + source.sourceId + \" is defined on 360–830 nm.\");\n      }\n      let value = source.base;\n      for (const band of source.bands) {\n        const z = (nm - band.centerNanometers) / band.standardDeviationNanometers;\n        value += band.amplitude * portableExp(-0.5 * z * z);\n      }\n      if (cache.size < CACHE_LIMIT) cache.set(nm, value);\n      return value;\n    }\n  };\n}\n\n/**\n * A capture illuminant for a source: `{ kind: \"spectrum\", spectrum, label }` with the spectrum of\n * {@link createRepresentativeLightSourceSpectrum} and the label \"<name> (representative, not a named product)\".\n */\nexport function createRepresentativeLightSourceIlluminant(input: { sourceId: RepresentativeLightSourceId }): Extract<CaptureIlluminant, { kind: \"spectrum\" }> {\n  const source = findSource(input, \"createRepresentativeLightSourceIlluminant\");\n  return { kind: \"spectrum\", spectrum: createRepresentativeLightSourceSpectrum({ sourceId: source.sourceId }), label: source.name + \" (\" + LABEL + \")\" };\n}\n"]}

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

@@ -5,6 +5,7 @@ import type { EvidenceProvenance } from "../core/evidence-provenance.js";
 import type { SensorApertureRay } from "../optics/sensor-aperture-rays.js";
 import { type ChartReflectance, type ChartScene, type ResolvedChartScene } from "./chart-scenes.js";
 import { type ChartMaterialLayerScene } from "./chart-material-layers.js";
+import type { ResolvedMixedIllumination } from "./mixed-illumination.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. */
@@ -101,6 +102,128 @@ export interface CallerMaterialScene {
 }
 /** Most materials a {@link CallerMaterialScene} may list. */
 export declare const CALLER_MATERIAL_SCENE_MAX_MATERIALS = 65536;
+/**
+ * 2.21 (#581): an image the caller supplies, for an {@link ImagePlaneScene}. `data` holds `width × height` pixels row by row
+ * from the top, `channels` (3: RGB, 4: RGBA) samples each, in the encoding's type: `srgb-8` Uint8Array or Uint8ClampedArray
+ * (canvas `ImageData.data`), `srgb-16` Uint16Array, `linear-srgb` Float32Array. sRGB primaries and white (IEC 61966-2-1) in
+ * every encoding; `srgb-8` and `srgb-16` are decoded with the sRGB transfer function, `linear-srgb` is already linear and is
+ * clipped to [0, 1] (the clipped samples are counted). Alpha is linear coverage over the paper. The array is read, never
+ * changed or kept beyond the call.
+ */
+export interface ImagePlaneImage {
+    width: number;
+    height: number;
+    channels: 3 | 4;
+    encoding: "srgb-8" | "srgb-16" | "linear-srgb";
+    data: Uint8Array | Uint8ClampedArray | Uint16Array | Float32Array;
+}
+/**
+ * 2.21 (#581): a photo as a flat matte print on the scene plane, lit by the request's illuminant like a chart. Each pixel's
+ * color becomes a reflectance spectrum through the engine's print reflectance lattice (docs/IMAGE_PLANE.md): an
+ * approximation, a print of an image that was already processed, clipped and blurred by the camera that took it. The print's
+ * physical size is `chartSize` (its height defaults to the image's aspect); without it the print is fitted inside the frame,
+ * centered, on the 18 % surround.
+ */
+export interface ImagePlaneScene {
+    kind: "image-plane";
+    sceneId: string;
+    image: ImagePlaneImage;
+    /** The paper and the deepest ink: reflectances of sRGB white and black, 0 ≤ black < white ≤ 1. Defaults 0.90 and 0.01. */
+    paper?: {
+        whiteReflectance?: number;
+        blackReflectance?: number;
+    };
+    /** How the print is reconstructed between pixel centers. Default `bilinear` (the pixels' spectra, bilinearly weighted). */
+    interpolation?: "bilinear" | "nearest";
+    /** Opt-in raised pixel limit: an integer up to the full-resolution ceiling. Default 24 000 000 pixels. */
+    maximumPixels?: number;
+}
+/**
+ * Internal (#581): what a pixel's signals are integrated from (`ResolvedImagePlaneScene.pixelSignals`): the lattice's node spectra at
+ * the N spectral nodes (node k's reflectance at λ_n at k·N + n), the white radiance and the channel responses per node.
+ */
+export interface ImagePlaneSpectralNodes {
+    count: number;
+    nodeSpectra: Float64Array;
+    whiteRadiance: Float64Array;
+    response: readonly Float64Array[];
+}
+/**
+ * Internal (#581): an image-plane print as the tabulated expected signal's scene (`ResolvedImagePlaneScene.signalScene`): its radiance
+ * per node, the direct path's signal (each pixel's Σ_n A_c(λ_n)·L_n integrated from its reconstructed spectrum, `pixelSignals`, then
+ * interpolated between pixels), and (for the GPU module) the scene, its spectral nodes and the surround's channel signals.
+ */
+export interface ImagePlaneSignalScene {
+    kind: "radiance";
+    radianceAt(u: number, v: number, nm: number): number;
+    signalAt(u: number, v: number, c: number): number;
+    image: {
+        scene: ResolvedImagePlaneScene;
+        nodes: ImagePlaneSpectralNodes;
+        surround: readonly [number, number, number];
+        whiteRadiance: Float64Array;
+        surroundReflectance: number;
+        /** #597: under mixed light, its parts and the print's half width in metres (print-local cu = ±1 at ±halfWidthM); no `signalAt` then. */
+        light?: {
+            layout: ResolvedMixedIllumination | null;
+            halfWidthM: number;
+        };
+    };
+}
+/** #597: an image-plane print under mixed light: the lit radiance only (every site integrates it), and the print for the GPU pass. */
+export interface ImagePlaneLitScene {
+    kind: "radiance";
+    radianceAt(u: number, v: number, nm: number): number;
+    image: ImagePlaneSignalScene["image"];
+}
+/**
+ * Internal (#581): a validated image-plane scene (src/facade/image-plane.ts, a lazily loaded module), placed on a print of
+ * aspect `aspect` (height / width). Print-local coordinates are the chart's: cu = ±1 at the print's left and right edges, cv up
+ * on the same scale, ±aspect at its top and bottom.
+ */
+export interface ResolvedImagePlaneScene {
+    kind: "image-plane";
+    sceneId: string;
+    width: number;
+    height: number;
+    aspect: number;
+    channels: 3 | 4;
+    encoding: ImagePlaneImage["encoding"];
+    interpolation: "bilinear" | "nearest";
+    paperWhiteReflectance: number;
+    paperBlackReflectance: number;
+    maximumPixels: number;
+    /** `linear-srgb` samples (color and alpha) clipped to [0, 1]; 0 for the integer encodings. */
+    clippedSampleCount: number;
+    /** SHA-256 of the image data's bytes, hex. */
+    dataSha256: string;
+    /** The print's reflectance at a print-local point and wavelength (nm, 380–780). */
+    reflectanceAt(cu: number, cv: number, nm: number): number;
+    /**
+     * One pixel's three channel signals Σ_n A_c(λ_n)·ρ_n·W_n, integrated from its reconstructed spectrum ρ_n (its cell's node spectra
+     * blended, then the paper) at the time of use, into `out[at..at + 2]`. No per-channel values of the lattice nodes are formed.
+     */
+    pixelSignals(index: number, nodes: ImagePlaneSpectralNodes, out: Float64Array, at: number): void;
+    /** The print at a print-local point in node values (`nodeValues[k]` of node k, `neutral` of the flat reflectance 1). */
+    sampleAt(cu: number, cv: number, nodeValues: Float64Array, neutral: number): number;
+    /** One pixel (row-major index) in node values. */
+    pixelValue(index: number, nodeValues: Float64Array, neutral: number): number;
+    /** One pixel's lattice cell (its base node r·25 + g·5 + b, returned) and its fractions within the cell per channel (written to `out[0..2]`). */
+    pixelLattice(index: number, out: Float64Array): number;
+    /** Every lattice node's reflectance at one wavelength (nm, 380–780). */
+    nodeReflectances(nm: number): Float64Array;
+    /**
+     * The print placed on the plane (frame point → print-local cu = u·scale/half, cv = v·scale/half; outside |cu| ≤ 1, |cv| ≤ aspect the
+     * surround) as the expected signal's scene at these nodes, responses and white radiance (see `ImagePlaneSignalScene`). #597: with
+     * `light` (mixed lighting; null when its parts are not given), the lit print: `radianceAt` only, no per-pixel signals.
+     */
+    signalScene(wavelengths: readonly number[], perNode: readonly Float64Array[], whiteRadiance: Float64Array, radianceAt: (u: number, v: number, nm: number) => number, scale: number, half: number, surroundReflectance: number): ImagePlaneSignalScene;
+    signalScene(wavelengths: readonly number[], perNode: readonly Float64Array[], whiteRadiance: Float64Array, radianceAt: (u: number, v: number, nm: number) => number, scale: number, half: number, surroundReflectance: number, light: ResolvedMixedIllumination | null | undefined): ImagePlaneSignalScene | ImagePlaneLitScene;
+    /** The scene's form in the facade's source digest (the image's SHA-256 and shape, the paper, the interpolation, the lattice version). */
+    digestForm: Readonly<Record<string, unknown>>;
+    /** The result's `scene.parameters`: the image, paper and interpolation, the clipped samples and the image's SHA-256. */
+    parameters: Readonly<Record<string, unknown>>;
+}
 /** Internal: a validated material scene with its materials prepared (and the caller inputs, for the scene digest). */
 export interface ResolvedCallerMaterialScene {
     kind: "material-function";
@@ -110,7 +233,7 @@ export interface ResolvedCallerMaterialScene {
     materialAt(point: Readonly<SceneMaterialPoint>): number;
 }
 /** Internal: a validated caller scene. */
-export type ResolvedCallerScene = CallerReflectanceScene | CallerRadianceScene | ResolvedCallerMaterialScene;
+export type ResolvedCallerScene = CallerReflectanceScene | CallerRadianceScene | ResolvedCallerMaterialScene | ResolvedImagePlaneScene;
 export interface PlanarSceneGeometry {
     distanceM: number;
     /** Metres per frame unit on the plane (half the framed width). */
@@ -131,8 +254,11 @@ export interface PlanarSceneRadianceProvider {
     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;
+    /**
+     * Spectral radiance at a plane point (frame units), the same value the callbacks return. #551: a moving subject's provider
+     * reads it at time `t` (seconds from the first opening, default 0); a still scene ignores it.
+     */
+    radianceAt(u: number, v: number, wavelengthNanometers: number, t?: number): number;
     /**
      * 2.3, chart scenes only: the chart material at a plane point (frame units), or `materials.length` for the
      * surround of a fixed-size chart; `materialRadiance` gives that material's spectral radiance, the same value
@@ -140,6 +266,12 @@ export interface PlanarSceneRadianceProvider {
      */
     chartMaterialAt?(u: number, v: number): number;
     materialRadiance?(material: number, wavelengthNanometers: number): number;
+    /**
+     * 2.21 (#581), image-plane scenes only: the tabulated expected signal's scene at these spectral nodes and channel responses, its
+     * radiance per node and, for the direct path, Σ_n A_c(λ_n)·L(λ_n) integrated from each pixel's reconstructed spectrum
+     * (`ResolvedImagePlaneScene.pixelSignals`, the surround's reflectance times the neutral signal outside the print).
+     */
+    imageSignalScene?(wavelengths: readonly number[], perNode: readonly Float64Array[]): ImagePlaneSignalScene | ImagePlaneLitScene;
 }
 /** Internal (#394): the material lookup of a provider built by {@link buildPlanarSceneRadianceProvider}, if it has one. */
 export declare function planarProviderMaterialOfDirection(provider: PlanarSceneRadianceProvider): ((direction: Readonly<{
@@ -171,6 +303,14 @@ export declare function buildPlanarSceneRadianceProvider(input: {
      * radiance instead of failing; the plane fills the forward hemisphere only. Omitted: such a query fails, as before.
      */
     zeroBeyondHorizon?: true;
+    /**
+     * #550, mixed illumination: the plane's spectral irradiance at a plane point, given in chart units (chart-local with a fixed-size
+     * chart, frame units without) and in metres from the optical axis, used instead of `irradianceScale`·S(λ). The provider then has no material access (the radiance at a point is
+     * no longer a function of its material alone), so every renderer reads `radianceAt`. A radiance-function scene is refused.
+     */
+    irradianceAt?: (u: number, v: number, xM: number, yM: number, wavelengthNanometers: number) => number;
+    /** #597: the illumination's parts behind `irradianceAt`, which an image-plane print hands to the GPU's image-plane pass. */
+    illumination?: ResolvedMixedIllumination;
 }): PlanarSceneRadianceProvider;
 /** 2.3: a chart's physical size on the scene plane (`simulateCapture` `chartSize`, `createPlanarSceneRadianceProvider` `chartSize`). */
 export interface ChartSizeOption {
@@ -199,7 +339,8 @@ export declare function resolveChartSizeOption(value: unknown, frameAspect: numb
  * provider `providerProfileId`.
  */
 export declare function createPlanarSceneRadianceProvider(input: {
-    scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
+    /** An `image-plane` scene (#581) is refused: it is taken by the facade's capture and display-view functions, which load its module. */
+    scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene | ImagePlaneScene;
     illuminant: CaptureIlluminant;
     illuminanceLux: number;
     distanceM: number;