@photivra/engine 2.4.1 → 2.6.0

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",
@@ -120,6 +121,10 @@ export const SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX = Math.PI * sosReferenceLu
  * aperture with fill factor 1. At other areas the facade scales the electron-domain readout values by
  * area / this reference, so the same focal-plane exposure H gives the same output code (see `isoAreaScaledReadout`).
  */
+/** 2.5: the largest accepted pixel pitch, µm (44 mm ÷ 48 pixels ≈ 917 µm, a whole full-frame or larger sensor at a small output). */
+const SIMULATE_CAPTURE_PIXEL_PITCH_MAXIMUM_MICROMETERS = 1000;
+/** Pitches above this, µm, are larger than any camera photosite: the capture is a downsized whole-frame view (assumption sensor.wholeFrameView). */
+const SIMULATE_CAPTURE_PHOTOSITE_PITCH_MAXIMUM_MICROMETERS = 100;
 const ISO_REFERENCE_APERTURE_AREA_SQUARE_MICROMETERS = DEFAULTS.pixelPitchMicrometers * DEFAULTS.pixelPitchMicrometers;
 /** Demosaic border, native sites per side. */
 const MARGIN = 1;
@@ -177,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++)
@@ -193,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
@@ -202,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",
@@ -226,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.");
@@ -280,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++) {
@@ -291,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 }];
@@ -466,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
@@ -478,10 +489,30 @@ 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;
+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: the request path shared by {@link simulateCapture}, {@link simulateIdealReference} and the display view, whose renderer is passed in. */
+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"]);
@@ -687,8 +718,8 @@ async function runCapture(options, idealReference) {
         fail("output.jpegQuantizationStep applies only to output.format \"jpeg\".");
     const sensorOptions = allowKeys(top.sensor, "sensor", ["pixelPitchMicrometers", "spectralStepNanometers", "temporalSampleCount", "noiseSeed", "antiAliasing", "pixelAperture"]);
     const pitch = positive(pick(sensorOptions, "pixelPitchMicrometers", "sensor.pixelPitchMicrometers", DEFAULTS.pixelPitchMicrometers, "6 µm pixels (about a 24 MP full-frame sensor). The simulated sensor is width × pitch wide, so small images are a central crop of a large sensor, not a downscaled full frame."), "sensor.pixelPitchMicrometers");
-    if (pitch < 0.5 || pitch > 100)
-        fail("sensor.pixelPitchMicrometers must be 0.5-100.");
+    if (pitch < 0.5 || pitch > SIMULATE_CAPTURE_PIXEL_PITCH_MAXIMUM_MICROMETERS)
+        fail("sensor.pixelPitchMicrometers must be 0.5-" + SIMULATE_CAPTURE_PIXEL_PITCH_MAXIMUM_MICROMETERS + ".");
     const spectralStep = positive(pick(sensorOptions, "spectralStepNanometers", "sensor.spectralStepNanometers", DEFAULTS.spectralStepNanometers, "Spectral midpoint quadrature over 380-780 nm with subintervals of at most 20 nm."), "sensor.spectralStepNanometers");
     if (spectralStep < 1 || spectralStep > 100)
         fail("sensor.spectralStepNanometers must be 1-100.");
@@ -710,6 +741,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 ? 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
@@ -748,13 +802,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 };
@@ -843,10 +901,16 @@ async function runCapture(options, idealReference) {
         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"]);
@@ -947,6 +1011,15 @@ async function runCapture(options, idealReference) {
             "the aperture area: a design consequence of holding the tier's ISO rating and highlight headroom fixed, not a measured full-well model (published sensor data grow less than " +
             "proportionally with area across technologies).");
     }
+    // Whole-frame views (2.5): a pitch above 100 µm is larger than any camera photosite, so the capture is a downsized view of a frame width × pitch wide.
+    if (pitch > SIMULATE_CAPTURE_PHOTOSITE_PITCH_MAXIMUM_MICROMETERS) {
+        assume("sensor.wholeFrameView", "model", { pixelPitchMicrometers: pitch, frameWidthMm: width * pitch / 1000, frameHeightMm: height * pitch / 1000 }, "A pixel pitch above 100 µm is larger than any camera photosite, so each output pixel stands for a " + pitch + " µm square of a " + width * pitch / 1000 + " × " + height * pitch / 1000 +
+            " mm frame: a downsized view of the whole frame, with the framing, crop factor, generic prime and minimum focus of that frame. Its signal is the charge of the whole square " +
+            "(sensor.isoAreaNormalization), so its shot noise is that of all the real photosites in the square summed or averaged (Poisson counts add), and the image brightness is the " +
+            "same as at any other pitch. Read noise and dark current are applied once per output pixel, not once per real photosite, so in deep shadows the noise is lower than a real " +
+            "sensor's binned output. This is the noise of a binned, downsized view, not the real sensor's per-pixel noise. A point pixel aperture samples one point of each square; " +
+            "use sensor.pixelAperture box (or sensor.antiAliasing) to average scene detail finer than the pitch.");
+    }
     assume("sensor.darkCurrent", "model", { electronsPerSecond: DARK_CURRENT_ELECTRONS_PER_SECOND, temperatureC: OPERATING_TEMPERATURE_C }, "Synthetic uniform dark current of 1 e⁻/s per site at 20 °C (the tier presets declare none); dark shot noise follows from it.");
     assume("sensor.spectralResponse", "model", { kind: "colorimetric-cmf-eqe", peakScale: EQE_SCALE }, "Idealized colorimetric sensor: channel EQE = a·{x̄, ȳ, z̄}(λ)·555/λ (the engine's analytic CIE 1931 fit), so RAW channels are proportional to CIE XYZ (Luther–Ives) and the camera matrix is diagonal. Not a real camera's response; CMF air wavelengths are used as vacuum wavelengths (difference about 0.03 %).");
     if (boxAperture) {
@@ -1007,7 +1080,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") {
@@ -1015,17 +1088,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"]);
@@ -1223,6 +1295,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)
@@ -1232,13 +1306,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²)).
@@ -1247,7 +1317,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." };
@@ -1275,6 +1345,20 @@ 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)]));