@photivra/engine 2.5.0 → 2.7.0

package/dist/facade/simulate-capture.d.ts

@@ -1,9 +1,11 @@
 import type { EvidenceProvenance } from "../core/evidence-provenance.js";
 import { type GenericEquipmentTier, type GenericEquipmentTierPreset } from "../equipment/generic-tier-assets.js";
-import { type ResolvedWhiteBalanceState } from "../color/white-balance.js";
+import { resolveColorTemperatureWhiteBalance, type ResolvedWhiteBalanceState } from "../color/white-balance.js";
+import { type CaptureWhiteBalanceIntent } from "../capture/simulated-capture.js";
 import { type NativeRawOutput, type NativeRawPlan } from "../capture/native-raw.js";
 import { type NativeEnvironmentRawInput } from "../capture/native-environment-raw.js";
 import { type NativeRawDevelopmentInput, type RawHighlightDiagnostics } from "../capture/native-raw-development.js";
+import type { RawFrameReconstructionPhaseProfile } from "../capture/raw-frame-reconstruction.js";
 import { type SdrToneCurve, type SdrToneCurveParameters, type SdrRenderingResult } from "../output/sdr-rendering.js";
 import type { RawHighlightMode } from "../color/sensor-color-development.js";
 import type { SimulateEnvironmentSensorRawFrameInput } from "../capture/environment-raw-producer.js";
@@ -12,11 +14,12 @@ import { type LensProjectionModel } from "../camera/lens-projection.js";
 import type { RadialDistortionProfile } from "../optics/radial-distortion.js";
 import type { BrownConradyDistortionProfile } from "../optics/brown-conrady-distortion.js";
 import type { IlluminationVignettingProfile } from "../optics/illumination-vignetting.js";
+import type { CalculateSensorPsfIrradianceQuadratureInput } from "../optics/sensor-psf-quadrature.js";
 import type { CalculateEnvironmentSensorPhotoSignalInput } from "../sensor/environment-photo-signal.js";
 import { type DiffractionLimitedPsfProfile } from "../optics/diffraction-psf-profile.js";
 import { type AntiAliasingPointSplitComponent } from "../sensor/optical-stack.js";
-import { type ChartScene } from "./chart-scenes.js";
-import { type ChartSizeOption, type CaptureIlluminant, type CallerRadianceScene, type CallerReflectanceScene } from "./scene-radiance.js";
+import { type ChartScene, type ResolvedChartScene } from "./chart-scenes.js";
+import { type ChartSizeOption, type CaptureIlluminant, type CallerMaterialScene, type CallerRadianceScene, type CallerReflectanceScene, type ResolvedCallerScene, type PlanarSceneRadianceProvider, type ResolvedCaptureIlluminant } from "./scene-radiance.js";
 /** Version of how the facade builds requests. It changes whenever the same input would build a different request. */
 export declare const SIMULATE_CAPTURE_FACADE_VERSION: "1.0.0";
 export type SimulateCaptureExposureMode = "manual" | "aperture-priority" | "shutter-priority" | "program";
@@ -160,7 +163,7 @@ export interface SimulateCaptureOptions {
         compensationStops?: number;
     };
     /** Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card) or a caller reflectance/radiance function. */
-    scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
+    scene: ChartScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
     /** Distance from the camera to the scene plane in metres. Default 5. */
     subjectDistanceM?: number;
     /**
@@ -227,7 +230,9 @@ export interface SimulateCaptureOptions {
          * the whole render: framing, metering, exposure, noise seeds (absolute native site indices), rolling-shutter row
          * timing, diffraction and demosaic all use the whole frame. Use it to tile a large frame across workers or to
          * render a 100 % crop. `result.image` is the region; `result.region` reports it. Not combinable with
-         * `whiteBalance: "auto"`, whose statistics would come from the region only.
+         * `whiteBalance: "auto"`, whose statistics would come from the region only. From 2.6 the diffraction convolution
+         * covers only the region plus the kernel and filter reach, so a small region of a large frame costs about as much
+         * as a capture of the region's size.
          */
         region?: {
             x: number;
@@ -451,12 +456,38 @@ export interface SimulateCaptureResult {
     };
     assumptions: readonly SimulateCaptureAssumption[];
 }
+export declare const FACADE_EVIDENCE: readonly EvidenceProvenance[];
 /**
  * Default illuminance, lux: an 18 % Lambertian grey card (L = 0.18·E/π) then gets exactly the CIPA DC-004 standard
  * output sensitivity reference exposure H = 10/S at f/8, 1/125 s, ISO 100:
  * E = π·10·N²/(0.65·t·S·0.18) = π·80 000/11.7 ≈ 21 480.98 lux.
  */
 export declare const SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX: number;
+interface ParsedAntiAliasing {
+    kind: SimulateCaptureSensorAntiAliasing["kind"];
+    separationSites?: number;
+    axis?: "horizontal" | "vertical";
+    components: AntiAliasingPointSplitComponent[];
+}
+/** Midpoint nodes of an N × N rule over a square photosite, as offsets from its centre in sites (+x right, +y down). */
+export declare function apertureNodeOffsets(n: number): {
+    x: number;
+    y: number;
+}[];
+export declare const CHANNELS: readonly ["red", "green", "blue"];
+type Channel = typeof CHANNELS[number];
+export declare const CAMERA_TO_XYZ: readonly (readonly number[])[];
+/** Synthetic dark current per site at the operating temperature, e⁻/s. */
+export declare const DARK_CURRENT_ELECTRONS_PER_SECOND = 1;
+export declare function fail(message: string): never;
+type ReadoutProfile = GenericEquipmentTierPreset["body"]["readout"][number]["profile"];
+/** Diagnostic clock for the 2.1 stage timings: `performance.now()` where the host has it. Never affects output. */
+export declare function clockMs(): number;
+export declare function allowKeys(value: unknown, name: string, keys: readonly string[]): Record<string, unknown>;
+/** The white balance measured from a perfect white diffuser under the scene illuminant ("scene-illuminant"). */
+export declare function sceneIlluminantWhiteBalance(illuminant: ResolvedCaptureIlluminant): ResolvedWhiteBalanceState;
+/** Bilinear RGGB demosaic as explicit linear neighbourhood kernels (weights sum to one per output channel). */
+export declare function bilinearPhaseProfiles(): RawFrameReconstructionPhaseProfile[];
 /**
  * Simulates one still capture of a planar scene and returns the developed image, the packed RAW, the full
  * underlying request/plan, provenance and every assumption made. See docs/QUICK_START.md.
@@ -524,5 +555,202 @@ export interface IdealReferenceResult {
     /** The capture request's assumptions, then `reference.kind`, `reference.excludes`, `reference.exposure` and `reference.sampling`. */
     assumptions: readonly SimulateCaptureAssumption[];
 }
+/** Default stratified samples per axis of a display view (`view.samplesPerAxis`): 16 × 16 sampled real pixels per display pixel with detail, 4 × 4 where it is uniform. */
+export declare const SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS = 16;
+/** The display size and sampling of {@link simulateDisplayView}. */
+export interface SimulateDisplayViewOptions {
+    /** Display pixels, 1 to the capture's output width and height. */
+    width: number;
+    height: number;
+    /** Stratified Monte Carlo samples per axis for each display pixel's expected value (1–32, default 8: 64 real pixels). */
+    samplesPerAxis?: number;
+    /** "srgb-8" (default) or "srgb-16". */
+    format?: "srgb-8" | "srgb-16";
+    /** Render only this rectangle of the display view, in display pixels; byte-identical to the same pixels of the whole view. */
+    region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Result of {@link simulateDisplayView}: the full-resolution capture resized for display, estimated; not a capture. */
+export interface DisplayViewResult {
+    kind: "display-view";
+    /** Human-readable label for a user interface. */
+    label: string;
+    facadeVersion: typeof SIMULATE_CAPTURE_FACADE_VERSION;
+    engineApiVersion: string;
+    /** The display view (or its region): interleaved sRGB samples, row by row from the top-left. */
+    image: {
+        width: number;
+        height: number;
+        format: "srgb-8" | "srgb-16";
+        samples: Uint8Array | Uint16Array;
+    };
+    /**
+     * The view: display size, the capture frame it shows (output pixels), real pixels per display pixel along each axis,
+     * the samples per axis and, with `view.region`, the rendered rectangle.
+     */
+    view: {
+        width: number;
+        height: number;
+        frameWidth: number;
+        frameHeight: number;
+        scaleX: number;
+        scaleY: number;
+        samplesPerAxis: number;
+        region?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    /** The resolved exposure of the capture this view shows. */
+    exposure: {
+        mode: SimulateCaptureExposureMode;
+        settings: {
+            fNumber: number;
+            shutterSeconds: number;
+            iso: number;
+        };
+        ev100: number;
+    };
+    scene: SimulateCaptureResult["scene"];
+    /**
+     * Work done: real pixels sampled, real-site expectations evaluated, scene queries, display pixels sampled in full (detail) or with
+     * a quarter of the samples per axis (uniform), display pixels whose value includes the AHD low-signal correction, and wall-clock
+     * milliseconds (diagnostic only; never affects the samples).
+     */
+    diagnostics: {
+        sampleCount: number;
+        siteEvaluations: number;
+        sceneLookups: number;
+        detailPixelCount: number;
+        uniformPixelCount: number;
+        ahdCorrectedPixelCount: number;
+        timingsMs: {
+            view: number;
+            total: number;
+        };
+    };
+    provenance: {
+        scientificStatus: "approximation";
+        cameraPresetId: string;
+        cameraPresetVersion: string;
+        evidence: readonly EvidenceProvenance[];
+        composedContracts: readonly string[];
+        limitations: readonly string[];
+    };
+    /** The capture request's assumptions, then `view.definition`, `view.estimation`, `view.noise`, `view.demosaic` and `view.source`. */
+    assumptions: readonly SimulateCaptureAssumption[];
+}
+/** Internal: the resolved request state that the display view's renderer (simulate-display-view.ts) reads. */
+export interface DisplayViewRunContext {
+    ahd: boolean;
+    antiAliasing: ParsedAntiAliasing | undefined;
+    aspect: number;
+    assume: (id: string, kind: SimulateCaptureAssumption["kind"], value: unknown, explanation: string) => void;
+    assumptions: SimulateCaptureAssumption[];
+    axisChannelResponse: (caller: string) => {
+        electronsPerRadiance: Record<Channel, Map<number, number>>;
+        wavelengths: number[];
+        relativePerElectron: Record<Channel, number>;
+    };
+    boxSamples: number;
+    buildProvider: (sceneIlluminant: ResolvedCaptureIlluminant, scale: number) => PlanarSceneRadianceProvider;
+    callerScene: ResolvedCallerScene | undefined;
+    chart: ResolvedChartScene | undefined;
+    chartReport: {
+        widthM: number;
+        heightM: number;
+        surroundReflectance: number;
+        frameWidthFraction: number;
+        frameHeightFraction: number;
+        magnification: number;
+        imageWidthMm: number;
+        imageHeightMm: number;
+        imageWidthPixels: number;
+        imageHeightPixels: number;
+    } | undefined;
+    chartSize: {
+        widthM: number;
+        heightM: number;
+        surroundReflectance: number;
+        defaulted: ("heightM" | "surroundReflectance")[];
+    } | undefined;
+    diffraction: DiffractionLimitedPsfProfile | undefined;
+    diffractionPsf: {
+        kind: "sampled-local";
+        configuration: Pick<CalculateSensorPsfIrradianceQuadratureInput, "psf" | "psfWavelengthBasis" | "spatialModel">;
+    } | undefined;
+    fNumber: number;
+    focalLengthMm: number;
+    focusDistanceM: number;
+    height: number;
+    highlightMode: RawHighlightMode;
+    illuminanceLux: number;
+    illuminant: ResolvedCaptureIlluminant;
+    illuminantOption: CaptureIlluminant;
+    imagingArea: {
+        widthMm: number;
+        heightMm: number;
+    };
+    intentOf: (state: ResolvedWhiteBalanceState | null) => CaptureWhiteBalanceIntent | null;
+    metresPerFrameUnit: number;
+    noiseSeed: number;
+    outputOptions: Record<string, unknown>;
+    parsedView: ParsedDisplayView | undefined;
+    pitch: number;
+    preset: GenericEquipmentTierPreset;
+    provider: PlanarSceneRadianceProvider;
+    regimeByChannel: Record<"red" | "green" | "blue", {
+        readoutProfile: ReadoutProfile;
+        regimeId: string;
+    }>;
+    resolvedIso: number;
+    sceneOption: unknown;
+    scenePreset: "composite" | "uniform" | "patches" | "slanted-edge" | "siemens-star" | "step-wedge" | "grey-ramp" | "checkerboard" | "point-grid" | "dead-leaves" | "bar-groups" | "hyperbolic-wedge" | "zone-plate" | "slanted-squares" | "line-grid" | "fiducial" | "reflectance-function" | "radiance-function" | "material-function";
+    shutterSeconds: number;
+    started: number;
+    subjectDistanceM: number;
+    toneCurve: SdrToneCurve;
+    whiteBalanceOption: SimulateCaptureWhiteBalance;
+    whiteBalanceState: ResolvedWhiteBalanceState | null;
+    width: number;
+    checkAbort: () => void;
+    margin: number;
+    mode: SimulateCaptureExposureMode;
+    nativeHeight: number;
+    nativeWidth: number;
+    sourceSha256: string;
+    yieldControl: () => Promise<void>;
+    /** The Kelvin white balance request, which the view resolves with the portable functions. */
+    kelvinWhiteBalanceInput: Parameters<typeof resolveColorTemperatureWhiteBalance>[0] | undefined;
+}
+export interface ParsedDisplayView {
+    width: number;
+    height: number;
+    samplesPerAxis: number;
+    bitDepth: 8 | 16;
+    format: "srgb-8" | "srgb-16";
+    region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Internal: validates a display view against the capture's output size and fills its defaults. */
+export declare function parseDisplayViewOption(value: unknown, frameWidth: number, frameHeight: number): ParsedDisplayView;
+/** Internal: passed as the view of a "display-view" run to resolve the request without a view (`prepareDisplayView`, #387). */
+export declare const DISPLAY_VIEW_WITHOUT_VIEW: unique symbol;
+/**
+ * Internal: the request path shared by {@link simulateCapture}, {@link simulateIdealReference} and the display view, whose renderer is
+ * passed in; for a display view the renderer's value is returned (a result, or a prepared view with DISPLAY_VIEW_WITHOUT_VIEW).
+ */
+export declare function runCapture(options: SimulateCaptureOptions, run: "capture" | "ideal-reference" | "display-view", viewOption?: unknown, renderView?: (context: DisplayViewRunContext) => Promise<unknown>): Promise<unknown>;
 /** Chart preset ids accepted by `simulateCapture({ scene: { preset } })`. */
 export declare const SIMULATE_CAPTURE_CHART_PRESETS: readonly ("composite" | "uniform" | "patches" | "slanted-edge" | "siemens-star" | "step-wedge" | "grey-ramp" | "checkerboard" | "point-grid" | "dead-leaves" | "bar-groups" | "hyperbolic-wedge" | "zone-plate" | "slanted-squares" | "line-grid" | "fiducial")[];
+export {};

package/dist/facade/simulate-capture.js

@@ -28,6 +28,7 @@
  * without it every encoded file is byte-identical to 2.3.
  * @see docs/QUICK_START.md
  */
+import { markInternalSceneRadianceEvaluator } from "../core/internal-radiance-evaluator.js";
 import { InvalidConfigurationError } from "../core/configuration-error.js";
 import { requireInputObject } from "../core/record-validation.js";
 import { ENGINE_API_VERSION } from "../core/version.js";
@@ -92,7 +93,7 @@ export const SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling"
     "lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
     "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
     "output.format.jpeg", "output.format.png", "output.format.dng"]);
-const FACADE_EVIDENCE = Object.freeze([Object.freeze({ sourceOrigin: "photivra",
+export const FACADE_EVIDENCE = Object.freeze([Object.freeze({ sourceOrigin: "photivra",
         sourceReference: "photivra:simulate-capture-facade", reuseStatus: "photivra-owned" })]);
 const DEFAULTS = Object.freeze({ camera: "professional", fNumber: 8, shutterSeconds: 1 / 125, iso: 100, compensationStops: 0,
     subjectDistanceM: 5, width: 64, height: 64, format: "srgb-8", toneCurve: "identity", highlightMode: "clip",
@@ -181,7 +182,7 @@ function parseAntiAliasing(value, pitch) {
     return fail("sensor.antiAliasing.kind must be four-spot, two-spot or point-splitting.");
 }
 /** Midpoint nodes of an N × N rule over a square photosite, as offsets from its centre in sites (+x right, +y down). */
-function apertureNodeOffsets(n) {
+export function apertureNodeOffsets(n) {
     const out = [];
     for (let j = 0; j < n; j++)
         for (let i = 0; i < n; i++)
@@ -197,7 +198,7 @@ const IDS = Object.freeze({ frame: "facade-frame", mode: "native-still", cfa: "p
     capture: "facade-capture", spectral: "facade-colorimetric-eqe", sampling: "facade-sampling", stack: "facade-no-aa", stackAa: "facade-aa",
     stationarity: "facade-stationarity", operatingState: "facade-operating-state", dark: "facade-dark", completeness: "facade-completeness",
     chargeSampling: "facade-charge-sampling", capacity: "facade-capacity" });
-const CHANNELS = ["red", "green", "blue"];
+export const CHANNELS = ["red", "green", "blue"];
 /**
  * Synthetic colorimetric sensor: channel EQE(λ) = a·cmf(λ)·(555 nm/λ), with cmf = x̄, ȳ, z̄. The λ factor turns
  * the energy-weighted CMF (colour-matching function) into a photon-counting response. So channel counts are
@@ -206,12 +207,12 @@ const CHANNELS = ["red", "green", "blue"];
  */
 const EQE_SCALE = Object.freeze({ red: 0.5, green: 0.5, blue: 0.25 });
 const CMF_KEY = Object.freeze({ red: "x", green: "y", blue: "z" });
-const CAMERA_TO_XYZ = Object.freeze([[EQE_SCALE.green / EQE_SCALE.red, 0, 0], [0, 1, 0], [0, 0, EQE_SCALE.green / EQE_SCALE.blue]].map((r) => Object.freeze(r)));
+export const CAMERA_TO_XYZ = Object.freeze([[EQE_SCALE.green / EQE_SCALE.red, 0, 0], [0, 1, 0], [0, 0, EQE_SCALE.green / EQE_SCALE.blue]].map((r) => Object.freeze(r)));
 const XYZ_TO_CAMERA = [[EQE_SCALE.red / EQE_SCALE.green, 0, 0], [0, 1, 0], [0, 0, EQE_SCALE.blue / EQE_SCALE.green]];
 /** Synthetic dark current per site at the operating temperature, e⁻/s. */
-const DARK_CURRENT_ELECTRONS_PER_SECOND = 1;
+export const DARK_CURRENT_ELECTRONS_PER_SECOND = 1;
 const OPERATING_TEMPERATURE_C = 20;
-function fail(message) { throw new InvalidConfigurationError(message); }
+export function fail(message) { throw new InvalidConfigurationError(message); }
 /** Where `output.metadata` goes in each file format (reported in the `output.metadata` assumption). */
 const TEXT_METADATA_LAYOUT = Object.freeze({
     jpeg: "XMP packet in APP1 (dc:description, xmp:CreatorTool, dc:rights, exif:UserComment), plus a COM segment holding the comment",
@@ -230,7 +231,7 @@ function isoAreaScaledReadout(profile, areaScale) {
             preAdcSaturationElectronEquivalent: { ...regime.preAdcSaturationElectronEquivalent, value: regime.preAdcSaturationElectronEquivalent.value * areaScale } })) });
 }
 /** Diagnostic clock for the 2.1 stage timings: `performance.now()` where the host has it. Never affects output. */
-function clockMs() { return globalThis.performance?.now() ?? Date.now(); }
+export function clockMs() { return globalThis.performance?.now() ?? Date.now(); }
 function positive(value, name) {
     if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
         fail(name + " must be a positive finite number.");
@@ -241,7 +242,7 @@ function integerIn(value, name, minimum, maximum) {
         fail(name + " must be an integer from " + minimum + " to " + maximum + ".");
     return value;
 }
-function allowKeys(value, name, keys) {
+export function allowKeys(value, name, keys) {
     if (value === undefined)
         return {};
     requireInputObject(value, name);
@@ -284,6 +285,12 @@ function luminanceOf(radiance) {
     }
     return PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W * sum;
 }
+/** The white balance measured from a perfect white diffuser under the scene illuminant ("scene-illuminant"). */
+export function sceneIlluminantWhiteBalance(illuminant) {
+    const xyz = illuminantXyz(illuminant), camera = XYZ_TO_CAMERA.map((row) => row[0] * xyz[0] + row[1] * xyz[1] + row[2] * xyz[2]);
+    return resolveCustomWhiteBalance({ stateId: "facade-wb-scene-illuminant", sampleSet: { imageStateId: "facade-white-diffuser",
+            inputDomain: "relative-pre-wb-camera-linear-rgb", samples: [{ sampleId: "white", red: camera[0], green: camera[1], blue: camera[2], weight: 1, clipped: false }] } });
+}
 function illuminantXyz(illuminant) {
     let x = 0, y = 0, z = 0;
     for (let nm = FACADE_SPECTRAL_RANGE_NANOMETERS.minimum; nm <= FACADE_SPECTRAL_RANGE_NANOMETERS.maximum; nm++) {
@@ -295,7 +302,7 @@ function illuminantXyz(illuminant) {
     return [x / y, 1, z / y];
 }
 /** Bilinear RGGB demosaic as explicit linear neighbourhood kernels (weights sum to one per output channel). */
-function bilinearPhaseProfiles() {
+export function bilinearPhaseProfiles() {
     const cross = [[1, 0], [-1, 0], [0, 1], [0, -1]], diagonal = [[1, 1], [1, -1], [-1, 1], [-1, -1]], horizontal = [[1, 0], [-1, 0]], vertical = [[0, 1], [0, -1]];
     const average = (offsets, channel) => offsets.map(([x, y]) => ({ offsetX: x, offsetY: y, sourceChannelId: channel, weight: 1 / offsets.length }));
     const self = (channel) => [{ offsetX: 0, offsetY: 0, sourceChannelId: channel, weight: 1 }];
@@ -470,7 +477,7 @@ function encodeSdrFromLinear(rgb, encoding, bitDepth, mapping) {
  * underlying request/plan, provenance and every assumption made. See docs/QUICK_START.md.
  */
 export async function simulateCapture(options) {
-    return await runCapture(options, false);
+    return await runCapture(options, "capture");
 }
 /**
  * The ideal reference of a capture request (2.3): the same scene, framing, chart size, output size, region and pixel
@@ -482,10 +489,36 @@ export async function simulateCapture(options) {
  * @see docs/QUICK_START.md, "Ideal reference".
  */
 export async function simulateIdealReference(options) {
-    return await runCapture(options, true);
+    return await runCapture(options, "ideal-reference");
+}
+/** Default stratified samples per axis of a display view (`view.samplesPerAxis`): 16 × 16 sampled real pixels per display pixel with detail, 4 × 4 where it is uniform. */
+export const SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS = 16;
+/** Internal: validates a display view against the capture's output size and fills its defaults. */
+export function parseDisplayViewOption(value, frameWidth, frameHeight) {
+    if (value === undefined)
+        fail("simulateDisplayView needs a view, for example { width: 384, height: 256 }.");
+    const v = allowKeys(value, "view", ["width", "height", "samplesPerAxis", "format", "region"]);
+    const width = integerIn(v.width, "view.width", 1, frameWidth), height = integerIn(v.height, "view.height", 1, frameHeight);
+    const samplesPerAxis = v.samplesPerAxis === undefined ? SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS : integerIn(v.samplesPerAxis, "view.samplesPerAxis", 1, 32);
+    const format = v.format === undefined ? "srgb-8" : v.format;
+    if (format !== "srgb-8" && format !== "srgb-16")
+        fail("view.format must be srgb-8 or srgb-16.");
+    let region;
+    if (v.region !== undefined) {
+        const r = allowKeys(v.region, "view.region", ["x", "y", "width", "height"]);
+        const x = integerIn(r.x, "view.region.x", 0, width - 1), y = integerIn(r.y, "view.region.y", 0, height - 1);
+        region = { x, y, width: integerIn(r.width, "view.region.width", 1, width - x), height: integerIn(r.height, "view.region.height", 1, height - y) };
+    }
+    return { width, height, samplesPerAxis, bitDepth: format === "srgb-8" ? 8 : 16, format: format, ...(region ? { region } : {}) };
 }
-async function runCapture(options, idealReference) {
-    const started = Date.now();
+/** Internal: passed as the view of a "display-view" run to resolve the request without a view (`prepareDisplayView`, #387). */
+export const DISPLAY_VIEW_WITHOUT_VIEW = Symbol("display view without view");
+/**
+ * Internal: the request path shared by {@link simulateCapture}, {@link simulateIdealReference} and the display view, whose renderer is
+ * passed in; for a display view the renderer's value is returned (a result, or a prepared view with DISPLAY_VIEW_WITHOUT_VIEW).
+ */
+export async function runCapture(options, run, viewOption, renderView) {
+    const started = Date.now(), idealReference = run === "ideal-reference", displayView = run === "display-view";
     requireInputObject(options, "simulateCapture options");
     const top = allowKeys(options, "simulateCapture options", ["camera", "lens", "exposure", "scene", "subjectDistanceM", "chartSize", "illuminant",
         "illuminanceLux", "output", "sensor", "motion", "signal", "onProgress"]);
@@ -714,6 +747,29 @@ async function runCapture(options, idealReference) {
         }
     }
     const boxAperture = sensorOptions.pixelAperture !== undefined && sensorOptions.pixelAperture !== "point";
+    // Display view: its own parameters, and the capture options it reproduces, checked before any scene work.
+    const parsedView = displayView && viewOption !== DISPLAY_VIEW_WITHOUT_VIEW ? parseDisplayViewOption(viewOption, width, height) : undefined;
+    if (displayView) {
+        const unsupported = (option, reason) => fail("simulateDisplayView does not support " + option + ": " + reason);
+        if (pupil)
+            unsupported("lens.pupilSampling", "defocus moves each query off the site lattice the expected-signal tables use.");
+        if (lensFieldMapping)
+            unsupported("lens.projection or lens.distortion", "the expected signal assumes the ideal rectilinear, distortion-free mapping of the site lattice.");
+        if (vignetting)
+            unsupported("lens.vignetting", "the expected signal assumes the same radiance-to-irradiance factor at every site.");
+        if (lensPsf)
+            unsupported("lens.psf", "only the engine-built diffraction kernels (lens.diffraction) are tabulated.");
+        if (rotating)
+            unsupported("motion.angularVelocityRadPerSec", "camera rotation moves the queries off the site lattice.");
+        if (outputOptions.region !== undefined)
+            unsupported("output.region", "pass the rectangle as view.region, in display pixels.");
+        if (outputOptions.whiteBalance === "auto")
+            unsupported("output.whiteBalance \"auto\"", "the capture measures it from its noisy full-resolution RAW; use \"scene-illuminant\" or a fixed white balance.");
+        if (outputOptions.toneCurve !== undefined && outputOptions.toneCurve !== "identity" && outputOptions.toneCurve !== "positive-reinhard-per-channel")
+            unsupported("output.toneCurve " + String(outputOptions.toneCurve), "luminance tone curves couple the channels; the view supports identity and positive-reinhard-per-channel.");
+        if (outputOptions.highlightMode === "reconstruct")
+            unsupported("output.highlightMode \"reconstruct\"", "the view supports the per-channel highlight clip.");
+    }
     const colorSamplingProfile = { schemaVersion: "0.1.0", profileId: IDS.cfa, evidence: FACADE_EVIDENCE, coordinateSystem: "native-sensor-color-sampling-site-index",
         layout: { kind: "periodic-mosaic", repeatWidthSites: 2, repeatHeightSites: 2, siteChannelIds: ["red", "green", "green", "blue"], anchor: "native-sensor-top-left-site" } };
     // Demosaic (2.0): built-in Bayer kernels and border handling. Omitted, the 1.0 bilinear kernels and a
@@ -752,13 +808,17 @@ async function runCapture(options, idealReference) {
     if (region && regionNative)
         assume("output.region", "model", { ...region, frameWidth: width, frameHeight: height, nativeRect: { ...regionNative } }, "Only this rectangle of the " + width + " × " + height + " frame is rendered. Framing, metering, exposure, diffraction kernels and every site's physics, noise seeds and exposure window (rolling-shutter row timing) are those of the whole frame (absolute native indices), " +
             "and the native rectangle includes the demosaic reach on each side (" + (margin > 0 ? margin : "mirror-border") + "), so the pixels are byte-identical to the same pixels of the whole render. " +
-            "With lens.diffraction the object-space convolution runs over whole-width bands of 32 native rows that the region touches.");
+            // 2.6: with lens.diffraction the convolution is limited to the region; the sentence of 2.3–2.5 is kept verbatim otherwise, so
+            // region results without diffraction stay byte-identical to 2.5.0.
+            (diffractionRadiusOption !== undefined ? "With lens.diffraction the object-space convolution (when it applies) covers only the lattice the region's native sites query (plus the kernel radius), in bands of at most 32 native rows; its values are the whole render's." :
+                "With lens.diffraction the object-space convolution runs over whole-width bands of 32 native rows that the region touches."));
     if (raisedPixels !== undefined) {
         if (nativeWidth > NATIVE_RAW_LIMITS.maximumDimension || nativeHeight > NATIVE_RAW_LIMITS.maximumDimension || nativeWidth * nativeHeight > raisedPixels) {
             fail("output.maximumPixels (" + raisedPixels + ") must cover the native sensor raster of " + nativeWidth + " × " + nativeHeight +
                 " sites (the output plus the demosaic margin), at most " + NATIVE_RAW_LIMITS.maximumDimension + " per side.");
         }
-        if (ahd && (regionNative ? regionNative.width * regionNative.height : nativeWidth * nativeHeight) > PROCESSING_MAX_PIXELS)
+        // The display view allocates no full-resolution raster, so the AHD working limit does not apply to it.
+        if (ahd && !displayView && (regionNative ? regionNative.width * regionNative.height : nativeWidth * nativeHeight) > PROCESSING_MAX_PIXELS)
             fail("output.demosaic \"ahd\" admits at most " + PROCESSING_MAX_PIXELS + " native sites.");
     }
     const imagingArea = { widthMm: nativeWidth * pitch / 1000, heightMm: nativeHeight * pitch / 1000 };
@@ -839,18 +899,29 @@ async function runCapture(options, idealReference) {
         illuminantRecord?.kind === "daylight" ? { basisDatasetId: illuminantRecord.basis?.datasetId, spectrum: spectrumDigestForm(illuminant.spectrum, illuminant.shape) } : undefined;
     const materialInputs = chart ? chartMaterialInputs(chart) : [];
     const sceneSpectra = chart ? chart.materials.flatMap((m, index) => m.kind !== "spectrum" ? [] : [{ material: index, spectrum: spectrumDigestForm(materialInputs[index], m.spectrum) }]) : [];
+    // 2.7: a material scene's materials enter the digest as data (neutral reflectances, and caller spectra as above).
+    const sceneMaterials = callerScene?.kind === "material-function" ? callerScene.materials.map((m, index) => (m.kind === "neutral" ? m.reflectance :
+        spectrumDigestForm(callerScene.materialInputs[index], m.spectrum))) : undefined;
     const sceneDescription = { facadeVersion: SIMULATE_CAPTURE_FACADE_VERSION, scene: chart ? { preset: chart.preset, parameters: chart.parameters } :
             { kind: callerScene.kind, sceneId: callerScene.sceneId }, illuminant: illuminant.id, illuminanceLux, subjectDistanceM, framedWidthM: 2 * metresPerFrameUnit, aspect,
         ...(chartSize ? { chartSize: { widthM: chartSize.widthM, heightM: chartSize.heightM, surroundReflectance: chartSize.surroundReflectance } } : {}),
-        ...(illuminantSpectrum === undefined ? {} : { illuminantSpectrum }), ...(sceneSpectra.length === 0 ? {} : { sceneSpectra }) };
-    if (callerScene)
+        ...(illuminantSpectrum === undefined ? {} : { illuminantSpectrum }), ...(sceneSpectra.length === 0 ? {} : { sceneSpectra }), ...(sceneMaterials ? { sceneMaterials } : {}) };
+    if (callerScene?.kind === "material-function")
+        assume("scene.digest", "model", "caller-function-not-hashed", "The source digest covers the caller's sceneId, its materials and the framing, not the body of the caller's materialAt function.");
+    else if (callerScene)
         assume("scene.digest", "model", "caller-function-not-hashed", "The source digest covers the caller's sceneId and the framing, not the body of the caller's evaluate function.");
     const sourceSha256 = await sha256Hex(JSON.stringify(sceneDescription, (_key, value) => (typeof value === "object" && value !== null && "evaluate" in value ? "caller-spectrum" : value)));
     checkAbort();
-    const provider = buildPlanarSceneRadianceProvider({ scene: chart ?? callerScene, sceneId: IDS.scene, providerProfileId: IDS.provider,
-        illuminant, irradianceScale, geometry: { distanceM: subjectDistanceM, metresPerFrameUnit,
+    const buildProvider = (sceneIlluminant, scale) => buildPlanarSceneRadianceProvider({ scene: chart ?? callerScene,
+        sceneId: IDS.scene, providerProfileId: IDS.provider, illuminant: sceneIlluminant, irradianceScale: scale, geometry: { distanceM: subjectDistanceM, metresPerFrameUnit,
             ...(chartSize ? { chart: { widthM: chartSize.widthM, heightM: chartSize.heightM, surroundReflectance: chartSize.surroundReflectance } } : {}) }, evidence: FACADE_EVIDENCE,
-        limitations: ["Planar Lambertian scene under uniform illumination; no shadows, inter-reflection, gloss or fluorescence."] });
+        limitations: Object.freeze(["Planar Lambertian scene under uniform illumination; no shadows, inter-reflection, gloss or fluorescence."]) });
+    const provider = buildProvider(illuminant, irradianceScale);
+    // 2.6: a chart preset's evaluator is engine-built end to end (its results: the schema's exact keys, constant fields,
+    // the request's identifiers, deep-frozen FACADE_EVIDENCE, UNCERTAINTY and limitations, and an engine-computed
+    // radiance), so the native task may skip re-parsing the fixed parts. Caller scenes keep the full validation.
+    if (chart)
+        markInternalSceneRadianceEvaluator(provider.evaluateRadiance);
     assume("model.scene-radiometry", "model", "lambertian-plane", "Radiance = reflectance × irradiance / π on one plane; illuminance from K_m = 683 lm/W and the engine's analytic CIE 1931 ȳ fit.");
     // Metering (CIPA DC-004 standard output sensitivity and camera equation) and exposure-mode resolution
     const exposureOptions = allowKeys(top.exposure, "exposure", ["mode", "iso", "shutterSeconds", "compensationStops"]);
@@ -1020,7 +1091,7 @@ async function runCapture(options, idealReference) {
     else
         assume("lens.projection", "model", projection, "Ideal " + projection + " projection through the environment lens field mapping. At finite focus its scale is the thin-lens image distance (an approximation); the chart is still sized with the rectilinear thin-lens scale, so its edges move with the projection.");
     // White balance
-    let whiteBalanceState = null, needsAuto = false;
+    let whiteBalanceState = null, needsAuto = false, kelvinWhiteBalanceInput;
     if (whiteBalanceOption === "none")
         whiteBalanceState = null;
     else if (whiteBalanceOption === "auto") {
@@ -1028,17 +1099,16 @@ async function runCapture(options, idealReference) {
             fail("output.region cannot be combined with output.whiteBalance \"auto\": grey-world statistics of a region differ from the whole frame's.");
         needsAuto = true;
     }
-    else if (whiteBalanceOption === "scene-illuminant") {
-        const xyz = illuminantXyz(illuminant), camera = XYZ_TO_CAMERA.map((row) => row[0] * xyz[0] + row[1] * xyz[1] + row[2] * xyz[2]);
-        whiteBalanceState = resolveCustomWhiteBalance({ stateId: "facade-wb-scene-illuminant", sampleSet: { imageStateId: "facade-white-diffuser",
-                inputDomain: "relative-pre-wb-camera-linear-rgb", samples: [{ sampleId: "white", red: camera[0], green: camera[1], blue: camera[2], weight: 1, clipped: false }] } });
-    }
+    else if (whiteBalanceOption === "scene-illuminant")
+        whiteBalanceState = sceneIlluminantWhiteBalance(illuminant);
     else if (typeof whiteBalanceOption === "object" && whiteBalanceOption !== null && "kelvin" in whiteBalanceOption) {
         const wb = allowKeys(whiteBalanceOption, "output.whiteBalance", ["kelvin", "tint"]);
         const intent = createColorTemperatureWhiteBalanceIntent({ intentId: "facade-wb-cct", colorTemperatureKelvin: positive(wb.kelvin, "output.whiteBalance.kelvin"),
             tint: wb.tint === undefined ? 0 : wb.tint });
-        whiteBalanceState = resolveColorTemperatureWhiteBalance({ stateId: "facade-wb-cct", intent, whiteLocus: "planckian", tintInterpretation: "duv-cie-1960-uv",
-            camera: { profileId: IDS.spectral, profileVersion: SIMULATE_CAPTURE_FACADE_VERSION, xyzToCameraRgb: XYZ_TO_CAMERA.map((r) => [...r]) } });
+        const kelvinInput = { stateId: "facade-wb-cct", intent, whiteLocus: "planckian", tintInterpretation: "duv-cie-1960-uv",
+            camera: { profileId: IDS.spectral, profileVersion: SIMULATE_CAPTURE_FACADE_VERSION, xyzToCameraRgb: XYZ_TO_CAMERA.map((r) => [...r]) } };
+        whiteBalanceState = resolveColorTemperatureWhiteBalance(kelvinInput);
+        kelvinWhiteBalanceInput = kelvinInput;
     }
     else if (typeof whiteBalanceOption === "object" && whiteBalanceOption !== null && "channelGains" in whiteBalanceOption) {
         allowKeys(whiteBalanceOption, "output.whiteBalance", ["channelGains"]);
@@ -1236,6 +1306,8 @@ async function runCapture(options, idealReference) {
     const rawProvider = diffraction && diffractionObjectSpace ? createDiffractedPlanarProvider({ base: provider, psf: diffractionPsf.configuration.psf,
         wavelengthsNm: diffraction.profile.axes.wavelengthNm, kernelRadius: diffraction.kernelRadiusSamples, nativeWidth, nativeHeight, outputWidth: width,
         sitePitchMicrometers: pitch, distanceM: subjectDistanceM, metresPerFrameUnit, onConvolution: (ms) => { diffractionMs += ms; },
+        // Region (2.6): convolve only the lattice the region's native sites query; the values are the whole render's.
+        ...(regionNative ? { window: regionNative } : {}),
         // The environment queries each site at each aperture node minus each split offset (sites, +x right, +y down).
         ...(antiAliasing || boxSamples > 1 ? { queryOffsetsSites: apertureNodeOffsets(boxSamples).flatMap((node) => (antiAliasing ? antiAliasing.components : [{ offsetMicrometers: { x: 0, y: 0 } }]).map((c) => ({ x: node.x - c.offsetMicrometers.x / pitch, y: node.y - c.offsetMicrometers.y / pitch }))) } : {}) }) : provider;
     if (antiAliasing && perSite > 100_000)
@@ -1245,13 +1317,9 @@ async function runCapture(options, idealReference) {
     const tileWidth = Math.max(1, Math.min(256, Math.floor(100_000 / perSite)));
     const environmentRaw = { raw: buildRawInput(intentOf(whiteBalanceState)), sceneBinding,
         maximumProviderEvaluations: Math.min(nativeRawMaximumProviderEvaluations(raisedPixels === undefined ? {} : { maximumPixels: raisedPixels }), Math.max(nativeWidth * nativeHeight, evaluations)) };
-    // Ideal reference (2.3): the scene without camera effects, at the capture's own exposure, white balance and encoding.
-    if (idealReference) {
-        const referenceStarted = clockMs();
-        if (format !== "srgb-8" && format !== "srgb-16" && format !== "png")
-            fail("simulateIdealReference supports output.format srgb-8, srgb-16 and png: a reference has no RAW (dng) and should not carry JPEG compression artefacts.");
-        if (needsAuto)
-            fail("simulateIdealReference cannot reproduce output.whiteBalance \"auto\": the capture measures it from its noisy RAW. Use \"scene-illuminant\" or a fixed white balance.");
+    // The facade's environment chain at a site next to the optical axis, shared by the ideal reference (2.3) and the display
+    // view: expected electrons per unit spectral radiance per channel and node, and the normalized RAW signal per electron.
+    function axisChannelResponse(caller) {
         // 1. Electrons per unit spectral radiance at each spectral node, per channel: the facade's own environment chain at a
         //    site next to the optical axis, with the ideal optics (no PSF, pupil, distortion, vignetting or motion). The signal
         //    is linear in the radiance node values and, for this planar scene, the same at every site (paraxial π/(4N_w²)).
@@ -1260,7 +1328,7 @@ async function runCapture(options, idealReference) {
         const electronsPerRadiance = {};
         for (const channel of CHANNELS) {
             if (channelAt(channelSites[channel] % nativeWidth, Math.floor(channelSites[channel] / nativeWidth)) !== channel)
-                fail("simulateIdealReference needs at least a 2 × 2 native raster.");
+                fail(caller + " needs at least a 2 × 2 native raster.");
             const environment = { ...siteInput(channelSites[channel]).environment };
             environment.psf = { kind: "not-applied", evidence, limitation: "Ideal reference: no lens PSF." };
             environment.fieldThroughput = { kind: "unity", evidence, limitation: "Ideal reference: no vignetting." };
@@ -1288,13 +1356,28 @@ async function runCapture(options, idealReference) {
                 systemConversionGainElectronsPerCode: gain, blackLevelCode: black, digitalSaturationCode: regime.adc.digitalSaturationCode, adcMaximumCode: 2 ** regime.adc.bitDepth - 1, digitalGain }, readoutProfile, regimeId);
             relativePerElectron[channel] = digitalGain / (gain * (white - black));
         }
+        return { electronsPerRadiance, wavelengths, relativePerElectron };
+    }
+    // Display view: the renderer that simulate-display-view.ts passes in reads this request's resolved state, so a bundle
+    // that only captures does not contain the display view.
+    if (displayView)
+        return await renderView({ ahd, antiAliasing, aspect, assume, assumptions, axisChannelResponse, boxSamples, buildProvider, callerScene, chart, chartReport, chartSize, diffraction, diffractionPsf, fNumber, focalLengthMm, focusDistanceM, height, highlightMode, illuminanceLux, illuminant, illuminantOption, imagingArea, intentOf, metresPerFrameUnit, noiseSeed, outputOptions, parsedView, pitch, preset, provider, regimeByChannel, resolvedIso, sceneOption, scenePreset, shutterSeconds, started, subjectDistanceM, toneCurve, whiteBalanceOption, whiteBalanceState, width, checkAbort, margin, mode, nativeHeight, nativeWidth, sourceSha256, yieldControl, kelvinWhiteBalanceInput });
+    // Ideal reference (2.3): the scene without camera effects, at the capture's own exposure, white balance and encoding.
+    if (idealReference) {
+        const referenceStarted = clockMs();
+        if (format !== "srgb-8" && format !== "srgb-16" && format !== "png")
+            fail("simulateIdealReference supports output.format srgb-8, srgb-16 and png: a reference has no RAW (dng) and should not carry JPEG compression artefacts.");
+        if (needsAuto)
+            fail("simulateIdealReference cannot reproduce output.whiteBalance \"auto\": the capture measures it from its noisy RAW. Use \"scene-illuminant\" or a fixed white balance.");
+        const { electronsPerRadiance, wavelengths, relativePerElectron } = axisChannelResponse("simulateIdealReference");
         // 3. Scene radiance per sample: chart materials once (and the fixed-size chart's surround), caller functions per sample.
         const signalOf = (radiance) => {
             const values = new Map(wavelengths.map((nm) => [nm, radiance(nm)]));
             return CHANNELS.map((c) => { let e = 0; for (const [nm, a] of electronsPerRadiance[c])
                 e += a * values.get(nm); return e * relativePerElectron[c]; });
         };
-        const materialSignals = provider.chartMaterialAt ? Array.from({ length: chart.materials.length + (chartSize ? 1 : 0) }, (_, m) => signalOf((nm) => provider.materialRadiance(m, nm))) : undefined;
+        const materialCount = chart ? chart.materials.length : callerScene?.kind === "material-function" ? callerScene.materials.length : 0;
+        const materialSignals = provider.chartMaterialAt ? Array.from({ length: materialCount + (chartSize ? 1 : 0) }, (_, m) => signalOf((nm) => provider.materialRadiance(m, nm))) : undefined;
         // 4. Pixels: the native sites of the output (or region) pixels, each centre-sampled or box-integrated like the capture.
         const x0 = (region ? region.x : 0) + margin, y0 = (region ? region.y : 0) + margin, n = boxSamples, unit = 2 / width;
         const referenceIntent = intentOf(whiteBalanceState), referenceGains = referenceIntent ? [referenceIntent.channelGains.red, referenceIntent.channelGains.green, referenceIntent.channelGains.blue] : null;