@photivra/engine 2.7.0 → 2.8.1

package/dist/facade/simulate-capture.js

@@ -28,7 +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 { markInternalNativeTileReader, markInternalSceneRadianceEvaluator, registerInternalRadianceAccess } 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";
@@ -47,6 +47,9 @@ import { createColorTemperatureWhiteBalanceIntent, resolveColorTemperatureWhiteB
 import { createCaptureWhiteBalanceIntent } from "../capture/simulated-capture.js";
 import { SENSOR_RAW_PRODUCER_NOISE_MODEL } from "../capture/sensor-raw-producer.js";
 import { calculateNativeRawPlan, nativeRawMaximumProviderEvaluations, NATIVE_RAW_LIMITS } from "../capture/native-raw.js";
+import { renderTabulatedNativeRaw, TABULATED_RELATIVE_TOLERANCE } from "../capture/native-environment-tabulated.js";
+import { createDisplayViewExpectedSignal } from "./expected-signal.js";
+import { buildExpectedSignalInput } from "./expected-signal-setup.js";
 import { createNativeEnvironmentRawTask, createNativeEnvironmentRawRegionTask } from "../capture/native-environment-raw.js";
 import { createNativeRawDevelopmentTask } from "../capture/native-raw-development.js";
 import { parseSdrRenderingProfile } from "../output/sdr-rendering.js";
@@ -71,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";
@@ -80,7 +83,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 { resolveCaptureIlluminant, calculateIlluminantIrradianceScale, buildPlanarSceneRadianceProvider, requireCallerScene, FACADE_SPECTRAL_RANGE_NANOMETERS, resolveChartSizeOption, PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W } from "./scene-radiance.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";
 /** Default midpoint samples per axis of `sensor.pixelAperture: "box"`. */
@@ -139,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). */
@@ -920,8 +926,15 @@ export async function runCapture(options, run, viewOption, renderView) {
     // 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)
+    // #394: a caller material scene's evaluator is engine-built in the same way (its radiance comes from the validated materials;
+    // only materialAt, validated on every call, is the caller's).
+    const materialEvaluator = chart !== undefined || callerScene?.kind === "material-function";
+    if (materialEvaluator)
         markInternalSceneRadianceEvaluator(provider.evaluateRadiance);
+    // #394: its results are materialRadiance(material at the queried point, wavelength), so the lean executor may tabulate them.
+    const materialOfDirection = planarProviderMaterialOfDirection(provider);
+    if (materialEvaluator && materialOfDirection && provider.materialRadiance)
+        registerInternalRadianceAccess(provider.evaluateRadiance, { keyOfDirection: materialOfDirection, radianceOfKey: provider.materialRadiance, tabulated: true });
     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"]);
@@ -1303,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;
@@ -1325,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.");
@@ -1336,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
@@ -1471,12 +1510,45 @@ export async function runCapture(options, run, viewOption, renderView) {
         return () => { completed++; onProgress?.({ stage, completedTileCount: completed, totalTileCount: total }); };
     };
     const rawTick = progress("raw", regionNative ? regionNative.height * Math.ceil(regionNative.width / tileWidth) : plan.tileCount);
-    const rawCallbacks = { readTile: async (request) => { const tile = await readTile(request); rawTick(); return tile; },
-        evaluateRadiance: rawProvider.evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl };
-    const rawTask = regionNative ? createNativeEnvironmentRawRegionTask(environmentRaw, regionNative, rawCallbacks) :
-        createNativeEnvironmentRawTask(environmentRaw, rawCallbacks);
-    await runTask(rawTask);
-    let rawOutput = rawTask.takeOutput();
+    // #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 });
+    // #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";
+    let tabulated;
+    if (tabulatedScene && !pupil && !lensFieldMapping && !vignetting && !lensPsf && !rotating && (!diffraction || diffractionObjectSpace) && provider.chartMaterialAt && provider.materialRadiance) {
+        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,
+            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" });
+        // 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;
+    if (tabulated) {
+        rawOutput = { raw: tabulated.raw, providerEvaluationCount: tabulated.providerEvaluationCount };
+        // The verification's relative difference itself is not reported: it is a last-bits quantity, and captures use the JavaScript
+        // engine's own Math functions, so it differs between engines while the results are the same.
+        assume("raw.expectedSignal", "model", { method: "tabulated-expected-electrons", verificationSites: 4, tolerance: TABULATED_RELATIVE_TOLERANCE }, "Each native site's expected photo electrons are the tabulated sum over the pixel-aperture nodes, anti-aliasing spots, diffraction taps and spectral nodes (the display view's expected signal), " +
+            "the same quantity the environment chain computes for this still, rectilinear, distortion-free planar scene, formed in another order, so it can differ in the last bits. The sensor stage (dark charge, Poisson draws, " +
+            "read noise, ADC) is the native one with each site's own seeds. One site of each CFA phase ran the full chain: its readout was reproduced bit for bit and its electrons agreed within the tolerance. " +
+            "diagnostics.providerEvaluationCount counts those sites' evaluator calls and the table's scene lookups.");
+    }
+    else {
+        const rawTask = regionNative ? createNativeEnvironmentRawRegionTask(environmentRaw, regionNative, rawCallbacks()) :
+            createNativeEnvironmentRawTask(environmentRaw, rawCallbacks());
+        await runTask(rawTask);
+        rawOutput = rawTask.takeOutput();
+    }
     // Region (2.3): the region's sites, re-described by a plan of the region raster (active area = the region), for development.
     let developmentPlan = plan;
     if (region && regionNative) {
@@ -1510,14 +1582,23 @@ export async function runCapture(options, run, viewOption, renderView) {
             sampleSet: { imageStateId: "facade-pre-wb-raw", inputDomain: "relative-pre-wb-camera-linear-rgb", samples } });
         finalRawInput = { raw: buildRawInput(intentOf(whiteBalanceState)), sceneBinding, maximumProviderEvaluations: environmentRaw.maximumProviderEvaluations };
         const wbTick = progress("white-balance", plan.tileCount);
-        // A second lean RAW pass with the measured intent. It gives the same RAW as re-running the sensor stage on a
-        // retained optical stage, and is faster: retaining the optical stage takes the first pass off the lean executor.
-        const wbTask = createNativeEnvironmentRawTask(finalRawInput, {
-            readTile: async (request) => { const tile = await readTile(request); wbTick(); return tile; },
-            evaluateRadiance: rawProvider.evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl
-        });
-        await runTask(wbTask);
-        rawOutput = wbTask.takeOutput();
+        if (tabulated) {
+            // #394: the RAW codes do not depend on the white-balance intent (it is development metadata), so the tabulated RAW is
+            // kept with the plan of the measured intent instead of being rendered again.
+            rawOutput = { ...rawOutput, raw: { ...rawOutput.raw, plan: calculateNativeRawPlan(finalRawInput.raw) } };
+            for (let k = 0; k < plan.tileCount; k++)
+                wbTick();
+        }
+        else {
+            // A second lean RAW pass with the measured intent. It gives the same RAW as re-running the sensor stage on a
+            // 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
+            });
+            await runTask(wbTask);
+            rawOutput = wbTask.takeOutput();
+        }
     }
     const wbMs = Date.now() - wbStarted, devStarted = Date.now();
     const colorProfile = { schemaVersion: "0.1.0", profileId: IDS.spectral, profileVersion: SIMULATE_CAPTURE_FACADE_VERSION, colorSamplingProfileId: IDS.cfa,