@photivra/engine 2.5.0 → 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",
@@ -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.");
@@ -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,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"]);
@@ -714,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
@@ -752,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 };
@@ -847,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"]);
@@ -1020,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") {
@@ -1028,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"]);
@@ -1236,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)
@@ -1245,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²)).
@@ -1260,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." };
@@ -1288,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)]));