@photivra/engine 2.10.0 → 2.11.1

package/dist/facade/simulate-capture.js

@@ -72,7 +72,8 @@ import { createRollingShutterCaptureExposureSchedule, resolveElectronicRollingSh
 import { calculateCaptureExposureWindows } from "../sensor/exposure-window.js";
 import { calculateSensorSpectralQuadrature } from "../sensor/spectral-quadrature.js";
 import { createDiffractionLimitedPsfProfile } from "../optics/diffraction-psf-profile.js";
-import { registerDiffractionPsfKey } from "../optics/site-diffraction-kernel.js";
+import { registerDiffractionPsfKey, siteDiffractionKernel } from "../optics/site-diffraction-kernel.js";
+import { convolveSiteKernels, createDefocusDiscSiteKernel, requireDefocusDiscKernelRadius, resolveDefocusDisc } from "../optics/defocus-disc-kernel.js";
 import { createDiffractedPlanarProvider } from "./diffraction-provider.js";
 import { resolveGenericPrimeLens } from "../equipment/generic-prime-lenses.js";
 import { calculateChannelElectronsPerRadiance } from "./channel-response.js";
@@ -84,6 +85,7 @@ import { prepareRgbGamutMapping } from "../color/gamut-mapping.js";
 import { serializeNativeRawDng } from "../capture/native-raw-dng.js";
 import { parseSensorReadoutConversionProfile, resolveSensorReadoutRegime } from "../sensor/raw-readout.js";
 import { resolveChartScene, chartMaterialInputs, CHART_SCENE_PRESETS } from "./chart-scenes.js";
+import { resolveChartMaterialLayers } from "./chart-material-layers.js";
 import { resolveCaptureIlluminant, calculateIlluminantIrradianceScale, buildPlanarSceneRadianceProvider, requireCallerScene, FACADE_SPECTRAL_RANGE_NANOMETERS, resolveChartSizeOption, PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W, planarProviderMaterialOfDirection } from "./scene-radiance.js";
 /** Version of how the facade builds requests. It changes whenever the same input would build a different request. */
 export const SIMULATE_CAPTURE_FACADE_VERSION = "1.0.0";
@@ -94,7 +96,7 @@ export const SIMULATE_CAPTURE_BOX_APERTURE_DEFAULT_SAMPLES = 4;
  * a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.temporalSampleCount` a count above 1.
  */
 export const SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
-    "lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
+    "lens.diffraction", "lens.defocus", "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"]);
 /**
@@ -665,6 +667,53 @@ export function parseDisplayViewOption(value, frameWidth, frameHeight) {
     }
     return { width, height, samplesPerAxis, bitDepth: format === "srgb-8" ? 8 : 16, format: format, ...(region ? { region } : {}) };
 }
+/**
+ * `lens.defocus` (#492): resolves the geometric defocus disc at the resolved f-number on the site pitch and records it.
+ * In focus (c = 0) no kernel exists and nothing else changes (undefined). The capture (step 2a) applies the disc as an
+ * object-space convolution and the display view (step 2b) as a site kernel in its expected-signal tables, and both get it
+ * back; the ideal reference, which has no camera effects, only records it.
+ */
+function resolveDefocusOption(input) {
+    const { run, assume, focalLengthMm, fNumber, focusDistanceM, subjectDistanceM, pitch } = input;
+    const disc = resolveDefocusDisc({ focalLengthMm, aperture: fNumber, focusDistanceM, subjectDistanceM, pitchMicrometers: pitch });
+    const size = disc.diameterMicrometers + " µm (" + disc.diameterSites + " sites of " + pitch + " µm)";
+    let radius;
+    try {
+        radius = requireDefocusDiscKernelRadius(disc.diameterSites);
+    }
+    catch (error) {
+        fail("lens.defocus: the blur circle is " + size + ". " + error.message);
+    }
+    const value = { model: "geometric-disc", scientificStatus: "approximation", diameterMicrometers: disc.diameterMicrometers, diameterSites: disc.diameterSites,
+        kernelRadiusSites: disc.diameterSites === 0 ? null : radius, fNumber, focusDistanceM, subjectDistanceM, samplePitchMicrometers: pitch,
+        defocusCircleModel: { id: "thin-lens-defocus-circle", version: "1.1.0" } };
+    const model = "Geometric defocus of the flat scene plane (an approximation): the thin-lens blur circle of an ideal uniform circular pupil, " +
+        "c = f²·|s − d| / (N·d·(s − f)) (calculateDefocusCircle 1.1.0), as a uniform disc sampled on the site lattice (exact disc area in each site's cell). " +
+        "No diffraction of the defocused wave, aberrations or pupil vignetting. ";
+    if (disc.diameterSites === 0) {
+        assume("lens.defocus", "model", value, model + "In focus (lens.focusDistanceM equals subjectDistanceM): the disc has zero diameter, so no defocus kernel is applied.");
+        return undefined;
+    }
+    if (run === "ideal-reference") {
+        assume("lens.defocus", "model", value, model + "Resolved but not applied: the ideal reference has no camera effects.");
+        return undefined;
+    }
+    // The display view (#492, step 2b): a site kernel in its expected-signal tables (simulate-display-view.ts).
+    if (run === "display-view") {
+        assume("lens.defocus", "model", { ...value, execution: "expected-signal-site-kernel", combinedWithDiffraction: input.diffraction }, model +
+            "Applied in the display view's expected-signal tables as a site kernel on the lattice" + (input.diffraction ? " (with lens.diffraction, each spectral node's " +
+            "diffraction kernel convolved with the disc, a further approximation)" : "") + "; see the view.defocus assumption.");
+        return disc;
+    }
+    // The capture (#492, step 2a): an object-space convolution of the scene radiance on the site lattice.
+    assume("lens.defocus", "model", { ...value, execution: "object-space-convolution", combinedWithDiffraction: input.diffraction }, model +
+        "Applied as an object-space convolution: the scene radiance on the site lattice is convolved with the disc, the same kernel at every spectral node, " +
+        "and each site query is answered with the result (for a flat scene and a still, distortion-free rectilinear camera every disc point a site sees is the scene point of another site). " +
+        (input.diffraction ? "With lens.diffraction, each spectral node's diffraction kernel is convolved with the disc and applied as one kernel. That is a further approximation: " +
+            "the defocused wave PSF of a circular pupil is not exactly the in-focus Airy pattern convolved with the geometric disc. " : "") +
+        "The disc kernel is a sampling of the disc on the site lattice; lens.pupilSampling (ray-sampled, no diffraction) is the independent reference.");
+    return disc;
+}
 /** 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");
 /**
@@ -701,7 +750,7 @@ export async function runCapture(options, run, viewOption, renderView) {
         preset = parseCallerCameraPreset(cameraOption);
     const body = preset.body, lens = preset.lens;
     // Lens
-    const lensOptions = allowKeys(top.lens, "lens", ["focalLengthMm", "fNumber", "focusDistanceM", "pupilSampling", "projection", "distortion", "vignetting", "psf", "diffraction", "prime"]);
+    const lensOptions = allowKeys(top.lens, "lens", ["focalLengthMm", "fNumber", "focusDistanceM", "pupilSampling", "projection", "distortion", "vignetting", "psf", "diffraction", "prime", "defocus"]);
     // Generic prime (2.3): resolved on the simulated frame's size, which the output and sensor sections validate again below.
     let prime;
     if (lensOptions.prime !== undefined) {
@@ -734,7 +783,9 @@ export async function runCapture(options, run, viewOption, renderView) {
         fail("The " + prime.lensId + " focuses no closer than " + prime.minimumFocusDistanceM + " m (max(0.10 m, f·(1 + 1/0.15))); subjectDistanceM and lens.focusDistanceM must be at least that.");
     let pupil;
     if (lensOptions.pupilSampling === undefined)
-        assume("lens.pupilSampling", "default", null, "No pupil sampling: each scene query follows the central (chief) ray, so defocus and depth of field are not rendered. Enable lens.pupilSampling for an ideal circular pupil.");
+        assume("lens.pupilSampling", "default", null, lensOptions.defocus === undefined ?
+            "No pupil sampling: each scene query follows the central (chief) ray, so defocus and depth of field are not rendered. Enable lens.pupilSampling for an ideal circular pupil." :
+            "No pupil sampling: each scene query follows the central (chief) ray; defocus of the scene plane is the lens.defocus option's (see the lens.defocus assumption).");
     else {
         const p = allowKeys(lensOptions.pupilSampling, "lens.pupilSampling", ["radialSamples", "angularSamples"]);
         // The environment pupil contract admits 4..64 azimuthal midpoints and at most 256 rays.
@@ -800,6 +851,18 @@ export async function runCapture(options, run, viewOption, renderView) {
         if (pupil)
             fail("lens.diffraction cannot be combined with lens.pupilSampling: the environment contract does not mix a sampled PSF with pupil rays.");
     }
+    // Defocus (#492): validated here, resolved once the f-number is.
+    let defocusModel;
+    if (lensOptions.defocus !== undefined) {
+        const record = allowKeys(lensOptions.defocus, "lens.defocus", ["model"]);
+        if (record.model !== "geometric-disc")
+            fail("lens.defocus.model must be \"geometric-disc\".");
+        if (pupil)
+            fail("lens.defocus cannot be combined with lens.pupilSampling: the pupil rays already render defocus, so it would be counted twice.");
+        if (lensPsf)
+            fail("lens.defocus cannot be combined with lens.psf: a caller PSF declares its own defocus, so it could be counted twice.");
+        defocusModel = "geometric-disc";
+    }
     // Motion (2.0): constant camera rotation and the shutter type.
     const motionOptions = allowKeys(top.motion, "motion", ["angularVelocityRadPerSec", "shutter", "rollingShutterSkewSeconds"]);
     const angular = { pitch: 0, yaw: 0, roll: 0 };
@@ -915,7 +978,7 @@ export async function runCapture(options, run, viewOption, renderView) {
     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.");
+            unsupported("lens.pupilSampling", "pupil rays move each query off the site lattice the expected-signal tables use; lens.defocus renders the defocus of the scene plane on the lattice.");
         if (lensFieldMapping)
             unsupported("lens.projection or lens.distortion", "the expected signal assumes the ideal rectilinear, distortion-free mapping of the site lattice.");
         if (vignetting)
@@ -1066,10 +1129,14 @@ export async function runCapture(options, run, viewOption, renderView) {
     const illuminant = resolveCaptureIlluminant(illuminantOption);
     const illuminanceLux = positive(pick(top, "illuminanceLux", "illuminanceLux", SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX, "π·10·N²/(0.65·t·S·0.18) lux at f/8, 1/125 s, ISO 100 (CIPA DC-004 standard output sensitivity H = 10/S and camera equation H = 0.65·L·t/N²): an 18 % grey card then gets the reference exposure for the default settings. It does not follow the caller's exposure settings."), "illuminanceLux");
     const irradianceScale = calculateIlluminantIrradianceScale(illuminant.shape, illuminanceLux);
-    let chart, callerScene;
+    let chart, callerScene, materialLayers;
     const sceneRecord = sceneOption;
     if ("kind" in sceneRecord) {
-        callerScene = requireCallerScene(sceneOption);
+        // #491: a declared material-layers scene is its callerScene (the same validation, materials, digest and bytes as passing that scene);
+        // the resolved layers are kept for the display view's GPU renderer.
+        if (sceneRecord.kind === "material-layers")
+            materialLayers = resolveChartMaterialLayers({ scene: sceneOption, aspect: chartSize ? chartSize.heightM / chartSize.widthM : aspect });
+        callerScene = requireCallerScene(materialLayers ? materialLayers.callerScene : sceneOption);
     }
     else {
         chart = resolveChartScene({ scene: sceneOption, aspect: chartSize ? chartSize.heightM / chartSize.widthM : aspect });
@@ -1192,6 +1259,19 @@ export async function runCapture(options, run, viewOption, renderView) {
     fNumber = resolution.resolvedSettings.aperture ?? fNumber;
     shutterSeconds = resolution.resolvedSettings.shutterSeconds ?? shutterSeconds;
     const resolvedIso = resolution.resolvedSettings.iso ?? iso;
+    const defocusDisc = defocusModel === undefined ? undefined :
+        resolveDefocusOption({ run, assume, focalLengthMm, fNumber, focusDistanceM, subjectDistanceM, pitch, diffraction: diffractionRadiusOption !== undefined });
+    // #492: the capture applies the disc as an object-space convolution, which needs every disc point a site sees to be another site's scene point.
+    if (defocusDisc) {
+        const reason = rotating ? "camera rotation (motion.angularVelocityRadPerSec)" : lensFieldMapping ? "lens.projection or lens.distortion" : vignetting ? "lens.vignetting" : undefined;
+        if (reason !== undefined)
+            fail("simulateCapture does not support lens.defocus out of focus with " + reason + ": the defocus disc is applied as an object-space convolution " +
+                "on the site lattice, and " + reason + " moves the scene points the sites see off that lattice. Set lens.focusDistanceM equal to subjectDistanceM, or omit one of the two options.");
+    }
+    // #492: the disc on the site lattice (radius 0 for a disc inside one cell: the identity, still applied).
+    const defocusKernel = defocusDisc && !displayView ? createDefocusDiscSiteKernel(defocusDisc.diameterSites) ?? undefined : undefined;
+    // The display view's disc (#492, step 2b): its expected-signal tables apply it (simulate-display-view.ts).
+    const displayViewDefocus = displayView ? defocusDisc : undefined;
     // Sensor readout for the ISO setting. Standard output sensitivity S = 10/H (CIPA DC-004 §3.2) is defined at the
     // output, independent of pixel size, while the collected charge is proportional to the sensitive-aperture area
     // (EMVA 1288 Release 4.0, Eq. 3). The tier's signal chain is anchored to the 6 µm aperture; at another area the
@@ -1407,7 +1487,8 @@ export async function runCapture(options, run, viewOption, renderView) {
             uncertainty: { kind: "not-quantified", limitation: "Analytic planar scene." },
             fidelity: { spectral: "wavelength-resolved", material: "spectral-data", visibility: "resolved", directTransport: "approximation", indirectTransport: "not-modeled" },
             wavelengthChangingTransportModeled: false, volumetricTransportModeled: false, polarizationModeled: false, evidence, limitations: ["Engine-authored planar chart or caller scene function.",
-                ...(diffractionObjectSpace ? ["Radiance is the scene radiance convolved with the lens diffraction PSF mapped onto the scene plane (object-space convolution, request.diffraction)."] : [])] }
+                ...(diffractionObjectSpace ? ["Radiance is the scene radiance convolved with the lens diffraction PSF mapped onto the scene plane (object-space convolution, request.diffraction)."] : []),
+                ...(defocusKernel ? ["Radiance is the scene radiance convolved with the geometric defocus disc mapped onto the scene plane (object-space convolution, lens.defocus)."] : [])] }
     };
     const lensId = lensExposure.profileId;
     const opticsProfile = { schemaVersion: "0.1.0", profileId: lensId + ":facade-transmission", profileVersion: SIMULATE_CAPTURE_FACADE_VERSION, lensProfileId: lensId,
@@ -1430,9 +1511,11 @@ export async function runCapture(options, run, viewOption, renderView) {
             maximumSubintervalWidthNanometers: spectralStep }]));
     // Diffraction (2.1): Airy kernels at the resolved f-number on the site pitch, one per spectral node of the sensor quadrature.
     let diffraction, diffractionPsf;
+    // The spectral nodes of the sensor quadrature, over all channels, ascending.
+    const quadratureWavelengths = () => [...new Set(CHANNELS.flatMap((channelId) => calculateSensorSpectralQuadrature({ ...spectralSamplingByChannel[channelId], colorSamplingProfile,
+            spectralResponseProfile: spectralResponseProfiles[channelId] }).value.nodes.map((node) => node.wavelengthNanometers)))].sort((a, b) => a - b);
     if (diffractionRadiusOption !== undefined) {
-        const wavelengths = [...new Set(CHANNELS.flatMap((channelId) => calculateSensorSpectralQuadrature({ ...spectralSamplingByChannel[channelId], colorSamplingProfile,
-                spectralResponseProfile: spectralResponseProfiles[channelId] }).value.nodes.map((node) => node.wavelengthNanometers)))].sort((a, b) => a - b);
+        const wavelengths = quadratureWavelengths();
         const lambdaN = wavelengths[wavelengths.length - 1] / 1000 * fNumber * imageDistanceMm / focalLengthMm;
         // The environment resolves the PSF at each pre-filter source point, up to the largest split offset outside the imaging area.
         const aaReachMm = antiAliasing ? Math.max(...antiAliasing.components.map((c) => Math.max(Math.abs(c.offsetMicrometers.x), Math.abs(c.offsetMicrometers.y)))) / 1000 : 0;
@@ -1463,9 +1546,36 @@ export async function runCapture(options, run, viewOption, renderView) {
                 "Applied through the environment PSF quadrature (one scene query per kernel tap), because camera rotation, a lens field mapping or vignetting moves the taps off the site lattice. ") +
             "No defocus, aberration or pupil clipping; " + (boxAperture ? "the pixel aperture is integrated as declared by sensor.pixelAperture." : "the sensor pixel aperture is still point-sampled at the site centre."));
     }
+    // #492: each spectral node's kernel for lens.defocus out of focus: the disc, or with lens.diffraction (always on the object-space path here)
+    // the node's diffraction kernel convolved with the disc, radius R_diffraction + R_defocus (built on first use, kept for the request).
+    let defocusSiteKernels;
+    if (defocusKernel) {
+        if (diffraction) {
+            const diffractionRadius = diffraction.kernelRadiusSamples, combined = new Map(), profileWavelengths = diffraction.profile.axes.wavelengthNm;
+            const radius = diffractionRadius + defocusKernel.radius;
+            // At most 32 + 64 = 96 sites (the two caps). Neither the expected-signal table nor the provider's own gather (diffraction-provider.ts)
+            // uses the public 32-site limit of calculateIrradianceConvolution; the combination costs at most about 0.1 s per spectral node
+            // (measured, docs/QUICK_START.md "Optics"), so no tighter limit applies.
+            const psfConfiguration = diffractionPsf.configuration.psf;
+            defocusSiteKernels = { radius, wavelengthsNm: profileWavelengths, at(wavelengthNm) {
+                    let kernel = combined.get(wavelengthNm);
+                    if (!kernel) {
+                        if (!profileWavelengths.includes(wavelengthNm))
+                            fail("simulateCapture: a spectral node has no diffraction kernel.");
+                        kernel = convolveSiteKernels(siteDiffractionKernel(psfConfiguration, wavelengthNm, pitch, diffractionRadius, "simulateCapture: diffraction kernels must sample the site pitch exactly."), diffractionRadius, defocusKernel.weights, defocusKernel.radius);
+                        combined.set(wavelengthNm, kernel);
+                    }
+                    return kernel;
+                } };
+        }
+        else
+            defocusSiteKernels = { radius: defocusKernel.radius, wavelengthsNm: quadratureWavelengths(), at: () => defocusKernel.weights };
+    }
     const psf = lensPsf ?? (diffractionObjectSpace ? { kind: "not-applied", evidence,
         limitation: "No environment PSF: lens diffraction is applied upstream by the scene provider as an object-space convolution (request.diffraction)." } : undefined) ??
-        diffractionPsf ?? { kind: "not-applied", evidence, limitation: "No lens PSF (point optics)." };
+        diffractionPsf ?? (defocusSiteKernels ? { kind: "not-applied", evidence,
+        limitation: "No environment PSF: lens defocus is applied upstream by the scene provider as an object-space convolution (lens.defocus)." } : undefined) ??
+        { kind: "not-applied", evidence, limitation: "No lens PSF (point optics)." };
     const pupilRecord = pupil ? { kind: "ideal-uniform-circular-pupil", radialSampleCount: pupil.radialSamples, angularSampleCount: pupil.angularSamples, evidence,
         limitation: "Ideal uniform circular pupil; finite ray sampling, no convergence claim." } : undefined;
     const chargeSamplingProfile = { schemaVersion: "0.1.0", profileId: IDS.chargeSampling, completenessProfileId: IDS.completeness, scientificStatus: "approximation",
@@ -1502,14 +1612,19 @@ export async function runCapture(options, run, viewOption, renderView) {
     const readTile = async (request) => ({ ...request, sites: Array.from({ length: request.width }, (_, j) => siteInput(request.y * nativeWidth + request.x + j)) });
     const yieldControl = createHostYield().yieldControl;
     const perSite = queriesPerSite * (diffraction && psf === diffractionPsf ? (2 * diffraction.kernelRadiusSamples + 1) ** 2 : 1);
-    let diffractionMs = 0, demosaicMs, encodeMs;
-    const diffractedProvider = (window) => 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.
+    let diffractionMs = 0, defocusMs = 0, demosaicMs, encodeMs;
+    const diffractedProvider = (window) => defocusSiteKernels ? createDiffractedPlanarProvider({ base: provider, siteKernels: defocusSiteKernels.at,
+        wavelengthsNm: defocusSiteKernels.wavelengthsNm, kernelRadius: defocusSiteKernels.radius, nativeWidth, nativeHeight, outputWidth: width,
+        sitePitchMicrometers: pitch, distanceM: subjectDistanceM, metresPerFrameUnit, onConvolution: (ms) => { defocusMs += ms; },
         ...(window ? { window } : {}),
-        // 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;
+        ...(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 }))) } : {}) }) :
+        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.
+            ...(window ? { window } : {}),
+            // 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;
     // Built on first use: a capture that takes the tabulated path (#394 step 2) never queries it, and its kernels cost a setup.
     let rawProviderBuilt;
     const rawProvider = () => (rawProviderBuilt ??= diffractedProvider(regionNative));
@@ -1584,7 +1699,7 @@ export async function runCapture(options, run, viewOption, renderView) {
     // 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, fastReport, 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 });
+        return await renderView({ ahd, fastReport, antiAliasing, aspect, assume, assumptions, axisChannelResponse, boxSamples, buildProvider, callerScene, chart, materialLayers, chartReport, chartSize, diffraction, defocus: displayViewDefocus, 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();
@@ -1709,12 +1824,20 @@ export async function runCapture(options, run, viewOption, renderView) {
         const { electronsPerRadiance, wavelengths } = axisChannelResponse("simulateCapture");
         const perNode = CHANNELS.map((c) => Float64Array.from(wavelengths, (nm) => electronsPerRadiance[c].get(nm) ?? 0));
         const sceneMaterials = chart ? chart.materials : callerScene.materials, materialRadiance = provider.materialRadiance;
-        const { signalInput } = buildExpectedSignalInput({ nativeWidth, nativeHeight, width, wavelengths, perNode, apertureNodes: apertureNodeOffsets(boxSamples), boxSamples, antiAliasing, pitch,
-            diffraction: diffraction ? { radius: diffraction.kernelRadiusSamples, psf: diffractionPsf.configuration.psf, profileWavelengths: diffraction.profile.axes.wavelengthNm } : undefined,
+        const { signalInput: builtSignalInput } = buildExpectedSignalInput({ nativeWidth, nativeHeight, width, wavelengths, perNode, apertureNodes: apertureNodeOffsets(boxSamples), boxSamples, antiAliasing, pitch,
+            diffraction: diffraction && !defocusSiteKernels ? { radius: diffraction.kernelRadiusSamples, psf: diffractionPsf.configuration.psf, profileWavelengths: diffraction.profile.axes.wavelengthNm } : undefined,
             materials: { materialAt: provider.chartMaterialAt, whiteRadiance: (nm) => irradianceScale * illuminant.shape.evaluate(nm) / Math.PI,
                 list: [...sceneMaterials.map((m, index) => (m.kind === "neutral" ? { neutral: m.reflectance } : { radiance: (nm) => materialRadiance(index, nm) })),
                     ...(chartSize ? [{ neutral: chartSize.surroundReflectance }] : [])] },
             radianceAt: provider.radianceAt, imagingArea, focalLengthMm, focusDistanceM, subjectDistanceM, metresPerFrameUnit, caller: "simulateCapture" });
+        // #492: with lens.defocus the table convolves the lattice radiance with each node's defocus (or combined) kernel, on the
+        // lattice formula, exactly as the object-space provider does.
+        let signalInput = builtSignalInput;
+        if (defocusSiteKernels) {
+            const lattice = { ...builtSignalInput };
+            delete lattice.queryPoint;
+            signalInput = { ...lattice, kernels: { radius: defocusSiteKernels.radius, perNode: wavelengths.map((nm) => defocusSiteKernels.at(nm)) } };
+        }
         // The verification reads only the region's top-left 2 × 2 block, so its diffraction convolves only that block's lattice; the
         // window never changes a value (see diffraction-provider.ts), so the chain it runs is the whole render's.
         const verificationProvider = diffractedProvider({ x: regionNative?.x ?? 0, y: regionNative?.y ?? 0, width: 2, height: 2 });
@@ -1926,7 +2049,7 @@ export async function runCapture(options, run, viewOption, renderView) {
     }
     const ranOptions = new Set([...(pupil ? ["lens.pupilSampling"] : []), ...(projection !== undefined ? ["lens.projection"] : []),
         ...(distortion ? ["lens.distortion"] : []), ...(vignetting ? ["lens.vignetting"] : []), ...(lensPsf ? ["lens.psf"] : []),
-        ...(diffraction ? ["lens.diffraction"] : []), ...(antiAliasing ? ["sensor.antiAliasing"] : []), ...(boxAperture ? ["sensor.pixelAperture.box"] : []),
+        ...(diffraction ? ["lens.diffraction"] : []), ...(defocusSiteKernels ? ["lens.defocus"] : []), ...(antiAliasing ? ["sensor.antiAliasing"] : []), ...(boxAperture ? ["sensor.pixelAperture.box"] : []),
         ...(temporalSampleCount > 1 ? ["sensor.temporalSampleCount"] : []), ...(rotating ? ["motion.rotation"] : []),
         ...(rollingSchedule ? ["motion.shutter.rolling"] : []), ...(mirrorBorder ? ["output.borderHandling.mirror"] : []), ...(region ? ["output.region"] : []),
         ...(needsAuto ? ["output.whiteBalance.auto"] : []), ...(ahd ? ["output.demosaic.ahd"] : []),
@@ -1946,7 +2069,7 @@ export async function runCapture(options, run, viewOption, renderView) {
             framedWidthM: 2 * metresPerFrameUnit, framedHeightM: 2 * metresPerFrameUnit * aspect, ...(chartReport ? { chart: chartReport } : {}), sourceSha256 },
         diagnostics: { providerEvaluationCount, highlight: developed.highlight, rendering: developed.diagnostics, ...(gamutMappingDiagnostics ? { gamutMapping: gamutMappingDiagnostics } : {}),
             timingsMs: { raw: rawMs, whiteBalance: wbMs, development: devMs, jpeg: jpegMs, total: Date.now() - started,
-                ...(diffraction && diffractionObjectSpace ? { diffraction: diffractionMs } : {}), ...(demosaicMs === undefined ? {} : { demosaic: demosaicMs }),
+                ...(diffraction && diffractionObjectSpace && !defocusSiteKernels ? { diffraction: diffractionMs } : {}), ...(defocusSiteKernels ? { defocus: defocusMs } : {}), ...(demosaicMs === undefined ? {} : { demosaic: demosaicMs }),
                 ...(encodeMs === undefined ? {} : { encode: encodeMs }) },
             options: Object.freeze(SIMULATE_CAPTURE_COST_OPTIONS.filter((option) => ranOptions.has(option))), fast: fastReport },
         provenance: { scientificStatus: "approximation", cameraPresetId: preset.presetId, cameraPresetVersion: preset.presetVersion,
@@ -1954,7 +2077,8 @@ export async function runCapture(options, run, viewOption, renderView) {
             composedContracts: ["resolveGenericEquipmentExposureCapabilities", "meterRelativeExposure", "createExposureMeterTargetFromMeteringResult",
                 "resolve" + (mode === "manual" ? "Manual" : mode === "aperture-priority" ? "AperturePriority" : mode === "shutter-priority" ? "ShutterPriority" : "ProgramAuto") + "ExposureMode",
                 ...(rollingSchedule ? ["resolveElectronicRollingShutterExposureSchedule", "createRollingShutterCaptureExposureSchedule"] : []),
-                ...(diffraction ? ["createDiffractionLimitedPsfProfile", ...(diffractionObjectSpace ? ["resolveLensPsfConvolutionKernels", "calculateIrradianceConvolution"] : [])] : []),
+                ...(diffraction ? ["createDiffractionLimitedPsfProfile", ...(diffractionObjectSpace ? ["resolveLensPsfConvolutionKernels", ...(defocusSiteKernels ? [] : ["calculateIrradianceConvolution"])] : [])] : []),
+                ...(defocusSiteKernels ? ["calculateDefocusCircle", "defocus disc site kernel (object-space convolution)"] : []),
                 ...(antiAliasing ? ["resolveAntiAliasingSpatialKernel"] : []), "resolveGenericIsoSignalChain", "createNativeEnvironmentRawTask", ...(needsAuto ? ["estimateAutoWhiteBalance"] : []),
                 ...(builtInDemosaic ? ["createBuiltInBayerDemosaicProfiles"] : []), ...(ahd ? ["createAhdDemosaicTask"] : []),
                 ...(ahd ? ["native RAW development operator (colour, after AHD)", ...(linearPath ? ["resolveRgbColorSpace", ...(perceptual ? ["prepareRgbGamutMapping"] : [])] : ["SDR rendering kernel"])] : linearPath ? ["native RAW development operator (linear, pre-clip)", "resolveRgbColorSpace", ...(perceptual ? ["prepareRgbGamutMapping"] : [])] : ["createNativeRawDevelopmentTask"]),