@photivra/engine 2.8.0 → 2.8.1

package/dist/facade/simulate-capture.js

@@ -74,7 +74,7 @@ import { calculateSensorSpectralQuadrature } from "../sensor/spectral-quadrature
 import { createDiffractionLimitedPsfProfile } from "../optics/diffraction-psf-profile.js";
 import { createDiffractedPlanarProvider } from "./diffraction-provider.js";
 import { resolveGenericPrimeLens } from "../equipment/generic-prime-lenses.js";
-import { calculateEnvironmentSensorPhotoSignal } from "../sensor/environment-photo-signal.js";
+import { executeEnvironmentSensorPhotoSignal, planEnvironmentSensorPhotoSignal } from "../sensor/environment-photo-signal.js";
 import { calculateSiteEffectiveSaturationCode } from "../capture/raw-white-level.js";
 import { prepareSensorColorDevelopment } from "../color/sensor-color-development.js";
 import { resolveAntiAliasingSpatialKernel } from "../sensor/optical-stack.js";
@@ -142,6 +142,9 @@ const AHD_VALUE_REACH = 3;
 /** Anti-aliasing filter limits: split points, and the largest offset in sites (bounds the scene work and the convolution margin). */
 const AA_MAXIMUM_COMPONENTS = 16;
 const AA_MAXIMUM_OFFSET_SITES = 4;
+/** Channel responses kept across calls (`axisChannelResponse`): one entry per distinct sensor, exposure and optics state. */
+const CHANNEL_RESPONSE_CACHE_SIZE = 8;
+const channelResponseCache = new Map();
 /** Default birefringent separation in sites: the two-spot MTF |cos(π·f·d)| then has its first zero at Nyquist, f = 1/(2·pitch). */
 const AA_DEFAULT_SEPARATION_SITES = 1;
 /** Parses `sensor.antiAliasing` into engine point-splitting components (offsets in µm, +x right, +y down). */
@@ -1313,13 +1316,16 @@ export async function runCapture(options, run, viewOption, renderView) {
     const yieldControl = createHostYield().yieldControl;
     const perSite = queriesPerSite * (diffraction && psf === diffractionPsf ? (2 * diffraction.kernelRadiusSamples + 1) ** 2 : 1);
     let diffractionMs = 0, demosaicMs, encodeMs;
-    const rawProvider = diffraction && diffractionObjectSpace ? createDiffractedPlanarProvider({ base: provider, psf: diffractionPsf.configuration.psf,
+    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.
-        ...(regionNative ? { window: regionNative } : {}),
+        ...(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));
     if (antiAliasing && perSite > 100_000)
         fail("sensor.antiAliasing with these options needs " + perSite + " scene queries per site; the environment admits at most 100000.");
     const evaluations = nativeWidth * nativeHeight * perSite;
@@ -1335,7 +1341,7 @@ export async function runCapture(options, run, viewOption, renderView) {
         //    is linear in the radiance node values and, for this planar scene, the same at every site (paraxial π/(4N_w²)).
         const cx = Math.floor(nativeWidth / 2) & ~1, cy = Math.floor(nativeHeight / 2) & ~1;
         const channelSites = { red: cy * nativeWidth + cx, green: cy * nativeWidth + Math.min(cx + 1, nativeWidth - 1), blue: Math.min(cy + 1, nativeHeight - 1) * nativeWidth + Math.min(cx + 1, nativeWidth - 1) };
-        const electronsPerRadiance = {};
+        const environments = {};
         for (const channel of CHANNELS) {
             if (channelAt(channelSites[channel] % nativeWidth, Math.floor(channelSites[channel] / nativeWidth)) !== channel)
                 fail(caller + " needs at least a 2 × 2 native raster.");
@@ -1346,13 +1352,36 @@ export async function runCapture(options, run, viewOption, renderView) {
             environment.temporalSampleCount = 1;
             delete environment.pupil;
             delete environment.lensFieldMapping;
-            const electrons = (radiance) => calculateEnvironmentSensorPhotoSignal({ ...environment,
-                evaluateRadiance: (request) => ({ ...provider.evaluateRadiance(request), spectralRadianceWattsPerSquareMeterSteradianNanometer: radiance(request.wavelengthNanometers) })
-            }).value
-                .photo.value.photoSignal.expectedGeneratedElectronCount;
-            const nodes = new Set();
-            electrons((nm) => { nodes.add(nm); return 1; });
-            electronsPerRadiance[channel] = new Map([...nodes].sort((a, b) => a - b).map((node) => [node, electrons((nm) => (nm === node ? 1 : 0))]));
+            delete environment.evaluateRadiance;
+            delete environment.evaluateApertureRadiance;
+            environments[channel] = environment;
+        }
+        // The responses are a function of these records alone (the radiance is replaced per node), and a request split into region
+        // tiles builds the same records for every tile, so they are kept across calls (the last CHANNEL_RESPONSE_CACHE_SIZE).
+        const key = JSON.stringify(CHANNELS.map((c) => environments[c]));
+        const copy = (responses) => Object.fromEntries(CHANNELS.map((c) => [c, new Map(responses[c])]));
+        const cached = channelResponseCache.get(key);
+        let electronsPerRadiance;
+        if (cached) {
+            channelResponseCache.delete(key);
+            channelResponseCache.set(key, cached);
+            electronsPerRadiance = copy(cached);
+        }
+        else {
+            electronsPerRadiance = {};
+            for (const channel of CHANNELS) {
+                // Planned once per channel and executed per spectral node: calculateEnvironmentSensorPhotoSignal is this plan and execution.
+                const photoPlan = planEnvironmentSensorPhotoSignal(environments[channel]);
+                const electrons = (radiance) => executeEnvironmentSensorPhotoSignal(photoPlan, (request) => ({ ...provider.evaluateRadiance(request), spectralRadianceWattsPerSquareMeterSteradianNanometer: radiance(request.wavelengthNanometers) })).value
+                    .photo.value.photoSignal.expectedGeneratedElectronCount;
+                const nodes = new Set();
+                electrons((nm) => { nodes.add(nm); return 1; });
+                electronsPerRadiance[channel] = new Map([...nodes].sort((a, b) => a - b).map((node) => [node, electrons((nm) => (nm === node ? 1 : 0))]));
+            }
+            // Callers get their own maps; the cached ones are never handed out.
+            channelResponseCache.set(key, copy(electronsPerRadiance));
+            if (channelResponseCache.size > CHANNEL_RESPONSE_CACHE_SIZE)
+                channelResponseCache.delete(channelResponseCache.keys().next().value);
         }
         const wavelengths = [...new Set(CHANNELS.flatMap((c) => [...electronsPerRadiance[c].keys()]))].sort((a, b) => a - b);
         // 2. Electrons → normalized RAW signal: (code − black)/(white − black) = e·d/(G·(W − B)) for the linear readout
@@ -1482,8 +1511,8 @@ export async function runCapture(options, run, viewOption, renderView) {
     };
     const rawTick = progress("raw", regionNative ? regionNative.height * Math.ceil(regionNative.width / tileWidth) : plan.tileCount);
     // #394: siteInput builds fresh site records per call and never changes them, so the native task plans them without a copy.
-    const rawCallbacks = { readTile: markInternalNativeTileReader(async (request) => { const tile = await readTile(request); rawTick(); return tile; }),
-        evaluateRadiance: rawProvider.evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl };
+    const rawCallbacks = () => ({ readTile: markInternalNativeTileReader(async (request) => { const tile = await readTile(request); rawTick(); return tile; }),
+        evaluateRadiance: rawProvider().evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl });
     // #394 step 2: an engine-built planar scene (chart preset or caller material scene; still, rectilinear, no distortion, vignetting,
     // pupil rays or caller PSF) takes its expected electrons from the tabulated signal, verified per CFA phase against the chain.
     const tabulatedScene = chart !== undefined || callerScene?.kind === "material-function";
@@ -1498,7 +1527,10 @@ export async function runCapture(options, run, viewOption, renderView) {
                 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" });
-        tabulated = await renderTabulatedNativeRaw({ input: environmentRaw, region: regionNative, siteInput, evaluateRadiance: rawProvider.evaluateRadiance,
+        // 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 });
+        tabulated = await renderTabulatedNativeRaw({ input: environmentRaw, region: regionNative, siteInput, evaluateRadiance: verificationProvider.evaluateRadiance,
             electrons: createDisplayViewExpectedSignal(signalInput), onTile: rawTick, tileWidth, yieldControl: () => yieldControl(), checkAbort });
     }
     let rawOutput;
@@ -1512,8 +1544,8 @@ export async function runCapture(options, run, viewOption, renderView) {
             "diagnostics.providerEvaluationCount counts those sites' evaluator calls and the table's scene lookups.");
     }
     else {
-        const rawTask = regionNative ? createNativeEnvironmentRawRegionTask(environmentRaw, regionNative, rawCallbacks) :
-            createNativeEnvironmentRawTask(environmentRaw, rawCallbacks);
+        const rawTask = regionNative ? createNativeEnvironmentRawRegionTask(environmentRaw, regionNative, rawCallbacks()) :
+            createNativeEnvironmentRawTask(environmentRaw, rawCallbacks());
         await runTask(rawTask);
         rawOutput = rawTask.takeOutput();
     }
@@ -1562,7 +1594,7 @@ export async function runCapture(options, run, viewOption, renderView) {
             // retained optical stage, and is faster: retaining the optical stage takes the first pass off the lean executor.
             const wbTask = createNativeEnvironmentRawTask(finalRawInput, {
                 readTile: markInternalNativeTileReader(async (request) => { const tile = await readTile(request); wbTick(); return tile; }),
-                evaluateRadiance: rawProvider.evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl
+                evaluateRadiance: rawProvider().evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl
             });
             await runTask(wbTask);
             rawOutput = wbTask.takeOutput();