@photivra/engine 2.7.0 → 2.8.1

package/dist/capture/native-environment-lean.js

@@ -30,7 +30,7 @@ const REDUCTION_TOLERANCE = 1e-10;
 /** Disables the lean executor process-wide (internal; tests compare both paths). */
 let leanDisabled = false;
 /** Internal counters of lean work (tests assert the lean path actually runs). Not exported from the package. */
-export const nativeEnvironmentLeanStatistics = { plannedSites: 0, executedSites: 0, sensorSites: 0, psfFallbacks: 0 };
+export const nativeEnvironmentLeanStatistics = { plannedSites: 0, executedSites: 0, sensorSites: 0, psfFallbacks: 0, keySites: 0 };
 export function setNativeEnvironmentLeanExecutionEnabled(enabled) { leanDisabled = !enabled; }
 function isPlainRecord(value) {
     const prototype = Object.getPrototypeOf(value);
@@ -137,8 +137,12 @@ function siteOf(environment) {
     const site = plainChild(plainChild(plainChild(environment, "sensor"), "spatialSampling"), "site");
     return site;
 }
-/** Plans the site-dependent parts with the full planner's arithmetic. Returns undefined on any doubt, and the caller plans in full. */
-function geometry(t, k, frame, environment, index) {
+/**
+ * Plans the site-dependent parts with the full planner's arithmetic. Returns undefined on any doubt, and the caller plans in full.
+ * With `access` (#394: a verified key-mode template, no pupil or lens mapping), each tap keeps the key its request would read
+ * instead of the request.
+ */
+function geometry(t, k, frame, environment, index, access) {
     try {
         const x = index % frame.nativeWidth, y = Math.floor(index / frame.nativeWidth), site = siteOf(environment);
         // Object.is: a -0 coordinate would flow into the full path's outputs, so it takes the full path.
@@ -233,14 +237,22 @@ function geometry(t, k, frame, environment, index) {
             const displacement = { pitch: omega.pitch * time, yaw: omega.yaw * time, roll: omega.roll * time };
             const taps = [];
             for (let gi = 0; gi < S * P; gi++) {
+                // #394: without a PSF a key tap depends only on its spatial node (same point, direction, field and key at
+                // every spectral node), so groups after the first spectral node share the first one's tap.
+                if (access !== undefined && destinationFields !== undefined && gi >= P) {
+                    taps.push(taps[gi % P]);
+                    continue;
+                }
                 const s = Math.floor(gi / P), points = destinationFields === undefined ? tapPoints[gi] : undefined;
                 const tapCount = points === undefined ? 1 : points.length;
                 for (let pi = 0; pi < tapCount; pi++) {
-                    const point = points === undefined ? sources[gi % P] : points[pi], sampleId = `${id}-t${ti}-n${gi}-p${pi}`;
+                    const point = points === undefined ? sources[gi % P] : points[pi], sampleId = access === undefined ? `${id}-t${ti}-n${gi}-p${pi}` : "";
                     const apertureRays = pupil === undefined ? undefined : sensorApertureRayValues({ sourcePointNativeSensorMm: point, focalLengthMm,
                         nominalFNumber, angularVelocityRadPerSec: omega, timeSecondsFromOpeningReference: time }, pupil, k.parsedFocus).rays;
-                    let request, imagePointMm, distortionAreaFactor;
+                    let request, key, imagePointMm, distortionAreaFactor;
                     if (k.lensMapping !== undefined) {
+                        if (access !== undefined)
+                            return undefined;
                         // The full planner's own mapped query, with the same input; only its result envelope is not kept.
                         const query = calculateMappedSensorEnvironmentRadianceQuery({ ...motion, sourcePointNativeSensorMm: point, focalLengthMm, focus: k.focus,
                             timeSecondsFromOpeningReference: time, request: { schemaVersion: "0.1.0", sampleId, providerProfileId: base.providerProfileId, sceneId: base.sceneId,
@@ -272,15 +284,26 @@ function geometry(t, k, frame, environment, index) {
                         const norm = Math.hypot(direction.x, direction.y, direction.z);
                         if (!Number.isFinite(norm) || Math.abs(norm - 1) > 1e-9)
                             return undefined;
-                        request = Object.freeze({ schemaVersion: "0.1.0", sampleId, providerProfileId: base.providerProfileId,
-                            sceneId: base.sceneId, illuminationProfileId: base.illuminationProfileId, materialResponseProfileId: base.materialResponseProfileId,
-                            target: Object.freeze({ kind: "environment-direction", outgoingDirectionUnitVector: Object.freeze(direction) }),
-                            timeSecondsFromExposureStart: time, wavelengthNanometers: k.wavelengths[s],
-                            wavelengthBasis: base.wavelengthBasis });
+                        // #394: the key the evaluator would read for this request (undefined where it would throw: the full path decides).
+                        if (access !== undefined) {
+                            key = access.keyOfDirection(direction);
+                            if (key === undefined)
+                                return undefined;
+                        }
+                        else
+                            request = Object.freeze({ schemaVersion: "0.1.0", sampleId, providerProfileId: base.providerProfileId,
+                                sceneId: base.sceneId, illuminationProfileId: base.illuminationProfileId, materialResponseProfileId: base.materialResponseProfileId,
+                                target: Object.freeze({ kind: "environment-direction", outgoingDirectionUnitVector: Object.freeze(direction) }),
+                                timeSecondsFromExposureStart: time, wavelengthNanometers: k.wavelengths[s],
+                                wavelengthBasis: base.wavelengthBasis });
                     }
                     const f = destinationFields === undefined ? tapFields[gi][pi] : destinationFields[gi % P];
                     // Built without object spread (cheaper per tap); optional fields are added only when present.
-                    const leanTap = { request, sourcePointImagePlaneMm: imagePointMm, fieldThroughput: f.value, fieldFactor: f.factor, fieldValid: f.valid };
+                    const leanTap = { sourcePointImagePlaneMm: imagePointMm, fieldThroughput: f.value, fieldFactor: f.factor, fieldValid: f.valid };
+                    if (request !== undefined)
+                        leanTap.request = request;
+                    else
+                        leanTap.key = key;
                     if (apertureRays !== undefined)
                         leanTap.apertureRays = apertureRays;
                     if (distortionAreaFactor !== undefined)
@@ -291,7 +314,7 @@ function geometry(t, k, frame, environment, index) {
             instants.push({ time, taps });
         }
         return { lean: true, template: t, index, owned: environment, count: k.count, site: { x, y }, start, end, duration, instants,
-            ...(k.psf === undefined ? {} : { kernels }) };
+            ...(k.psf === undefined ? {} : { kernels }), ...(access === undefined ? {} : { keyTaps: true }) };
     }
     catch {
         return undefined;
@@ -610,7 +633,45 @@ function executionConstants(k, environment, plan, result, self) {
     const mine = photo(k, c, values, environment, full.site, full.startOffsetSecondsFromOpeningReference, full.endOffsetSecondsFromOpeningReference, full.localExposureDurationSeconds, plan.instants.map(i => i.time));
     return mine && sameData(mine, full, new WeakMap()) ? c : undefined;
 }
-export function createNativeEnvironmentLeanExecutor(frame) {
+/** #394: the evaluator's radiance for a key at spectral node s (tabulated keys from the template's table, computed once). */
+function keyRadiance(t, k, access, key, s) {
+    // Untabulated keys (lattice sites) are read from the evaluator's own lookup on each use.
+    if (!access.tabulated)
+        return access.radianceOfKey(key, k.wavelengths[s]);
+    const table = t.radiance, row = table[key] ??= new Float64Array(k.spectralCount).fill(NaN);
+    let value = row[s];
+    if (Number.isNaN(value)) {
+        value = access.radianceOfKey(key, k.wavelengths[s]);
+        row[s] = value;
+    }
+    return value;
+}
+/**
+ * #394: true when the key taps of the template's own site give, tap by tap in callback order, exactly the radiance of each
+ * evaluation of its full execution. Only then do its sites take radiances from the key lookup.
+ */
+function keyModeReproduced(t, k, access, self, result) {
+    if (!self || self.keyTaps !== true || k.pupilCount !== 1 || self.instants.length !== result.value.instants.length)
+        return false;
+    const S = k.spectralCount, P = k.spatialCount;
+    for (let ti = 0; ti < self.instants.length; ti++) {
+        const evaluations = result.value.instants[ti].evaluations, taps = self.instants[ti].taps;
+        if (evaluations.length !== taps.length)
+            return false;
+        for (let gi = 0; gi < S * P; gi++)
+            for (let i = k.tapOffsets[gi]; i < k.tapOffsets[gi + 1]; i++) {
+                const key = taps[i].key;
+                if (key === undefined || !Object.is(keyRadiance(t, k, access, key, Math.floor(gi / P)), evaluations[i].result.spectralRadianceWattsPerSquareMeterSteradianNanometer))
+                    return false;
+            }
+    }
+    return true;
+}
+/**
+ * Creates the per-event lean executor. With `access` (#394: the key lookup of an engine-built evaluator), a template whose own
+ * site verifies it plans its sites as key taps and takes their radiances from the lookup.
+ */
+export function createNativeEnvironmentLeanExecutor(frame, access) {
     const templates = [];
     const candidates = new Map();
     const memo = new WeakMap();
@@ -651,7 +712,7 @@ export function createNativeEnvironmentLeanExecutor(frame) {
                 return templates.length < MAXIMUM_TEMPLATES ? "candidate" : undefined;
             if (t.disabled || !t.consts || t.executionVerified === false)
                 return undefined;
-            const leanPlan = geometry(t, t.consts, frame, environment, index);
+            const leanPlan = geometry(t, t.consts, frame, environment, index, t.keyMode === true ? access : undefined);
             if (leanPlan)
                 nativeEnvironmentLeanStatistics.plannedSites++;
             return leanPlan;
@@ -688,19 +749,81 @@ export function createNativeEnvironmentLeanExecutor(frame) {
                     return;
                 t.execution = c;
                 t.executionVerified = true;
+                // #394: key taps need no pupil and no lens mapping (the evaluator then reads one plane point per tap).
+                if (access !== undefined && t.consts.lensMapping === undefined && t.environment.pupil === undefined) {
+                    t.radiance = [];
+                    t.keyMode = keyModeReproduced(t, t.consts, access, geometry(t, t.consts, frame, t.environment, index, access), result);
+                    if (!t.keyMode)
+                        delete t.radiance;
+                }
             }
             catch {
                 // Unverified: sites of this template run the full path.
             }
         },
-        execute(plan, evaluate, aperture, fullPlan, internalEvaluator = false) {
+        execute(plan, evaluate, aperture, fullPlan, internalEvaluator = false, countEvaluations) {
             const t = plan.template, c = t.execution, k = t.consts;
             if (t.executionVerified !== true || !c || !k)
                 return undefined;
             const environment = plan.owned, optics = environment.optics;
             const S = k.spectralCount, P = k.spatialCount, kernels = plan.kernels;
+            if (plan.keyTaps === true) {
+                // #394: every tap's radiance from the evaluator's key lookup, with tapIrradiance's arithmetic. A tap that would
+                // need the full irradiance function returns undefined before anything is counted: the caller runs the site in full.
+                if (t.keyMode !== true || !access || !countEvaluations)
+                    return undefined;
+                const values = [], times = [], instantTaps = [];
+                for (const instant of plan.instants) {
+                    const v = new Float64Array(S * P), tapValues = [];
+                    if (kernels === undefined) {
+                        // One tap per group.
+                        for (let gi = 0; gi < S * P; gi++) {
+                            const tap = instant.taps[gi], s = Math.floor(gi / P);
+                            const irradiance = keyRadiance(t, k, access, tap.key, s) * (c.acceptance[s] * tap.fieldFactor);
+                            if (!tap.fieldValid || !Number.isFinite(irradiance) || irradiance < 0)
+                                return undefined;
+                            let integrated = 0;
+                            integrated += irradiance * 1;
+                            v[gi] = integrated;
+                        }
+                        values.push(v);
+                        times.push(instant.time);
+                        continue;
+                    }
+                    for (let gi = 0; gi < S * P; gi++) {
+                        const first = k.tapOffsets[gi], s = Math.floor(gi / P), groupValues = new Float64Array(k.tapOffsets[gi + 1] - first);
+                        for (let pi = 0; pi < groupValues.length; pi++) {
+                            const tap = instant.taps[first + pi];
+                            const irradiance = keyRadiance(t, k, access, tap.key, s) * (c.acceptance[s] * tap.fieldFactor);
+                            if (!tap.fieldValid || !Number.isFinite(irradiance) || irradiance < 0)
+                                return undefined;
+                            let integrated = 0;
+                            integrated += irradiance * 1;
+                            groupValues[pi] = integrated;
+                        }
+                        tapValues.push(groupValues);
+                        v[gi] = kernels === undefined ? groupValues[0] : psfSum(kernels[gi], groupValues);
+                    }
+                    values.push(v);
+                    instantTaps.push(tapValues);
+                    times.push(instant.time);
+                }
+                // The evaluations the full path would count (and its abort check), then the PSF checks after each instant's taps.
+                countEvaluations(plan.count);
+                let full;
+                if (kernels !== undefined)
+                    for (let ti = 0; ti < values.length; ti++) {
+                        if (!psfChecksPass(k, c, instantTaps[ti], values[ti]))
+                            values[ti] = fullPsfInstant(full ??= fullPlan(), ti, instantTaps[ti]);
+                    }
+                nativeEnvironmentLeanStatistics.executedSites++;
+                nativeEnvironmentLeanStatistics.keySites++;
+                return photo(k, c, values, environment, plan.site, plan.start, plan.end, plan.duration, times) ??
+                    createSensorEqeTemporalPhotoSignal(fullPhotoInput(k, values, environment, times)).value.photoSignal;
+            }
             /** One tap: its callbacks in order, each result validated, the pupil sum, then the distortion area factor once. */
-            const tapIrradiance = (tap, s) => {
+            const tapIrradiance = (leanTap, s) => {
+                const tap = leanTap;
                 let integrated = 0;
                 const support = tap.apertureRays ?? [undefined];
                 for (const ray of support) {
@@ -888,6 +1011,42 @@ function chargeTotal(photoE, darkE) {
     }
     return sum;
 }
+/**
+ * #394: a sensor template from one fully parsed and computed site (`calculateNativeRawSite`), as the lean sensor stage builds
+ * its templates; undefined unless the lean arithmetic reproduces that site's dark and total charge, both charge realizations,
+ * its codes and its flags bit for bit. Its `compute` then gives `calculateNativeRawSite`'s outputs for any site of the same
+ * readout inputs (same CFA channel, dark current, capacity, readout regime and fixed-pattern profile).
+ */
+export function createVerifiedNativeSiteReadout(parsed, result, whiteCode, photo, x, y, index, seed) {
+    try {
+        const readout = resolveSensorReadoutRegime({ profile: parsed.readoutProfile, regimeId: parsed.regimeId });
+        const t = { darkRate: parsed.charge.darkCharge.darkCurrentElectronsPerSecond,
+            capacity: result.capacity.value.physicalChargeCapacityElectrons, readout, pattern: parsed.fixedPatternNoise, whiteCode };
+        const darkE = t.darkRate * photo.localExposureDurationSeconds, total = chargeTotal(photo.expectedGeneratedElectronCount, darkE);
+        const r = result.readout.value, realization = result.realization.value, out = leanSensorSite(t, { photo, darkE, total, x, y }, index, seed);
+        if (!out || !Object.is(darkE, parsed.charge.darkCharge.expectedDarkElectronCount) || !Object.is(total, result.accumulatedCharge.value.totalExpectedStoredElectronCount) ||
+            !Object.is(out.photoRealized, realization.photoRealizedElectronCount) || !Object.is(out.darkRealized, realization.darkRealizedElectronCount) ||
+            realization.additionalComponents.length !== 0 || out.rawCode !== r.rawCode || out.blackLevelCode !== r.blackLevelCode || out.digitalSaturationCode !== r.digitalSaturationCode ||
+            out.flags !== (Number(r.physicalScalarSaturationApplied) | Number(r.preAdcSaturationApplied) << 1 | Number(r.digitalSaturationApplied) << 2))
+            return undefined;
+        return {
+            compute(photoE, duration, sx, sy, siteIndex, siteSeed) {
+                // The parse-phase predicates of the full path (claim()): finite non-negative dark and total charge.
+                const siteDark = t.darkRate * duration;
+                if (!Number.isFinite(photoE) || photoE < 0 || !Number.isFinite(siteDark) || siteDark < 0)
+                    return undefined;
+                const siteTotal = chargeTotal(photoE, siteDark);
+                if (!Number.isFinite(siteTotal) || siteTotal < 0)
+                    return undefined;
+                const o = leanSensorSite(t, { photo: { expectedGeneratedElectronCount: photoE }, darkE: siteDark, total: siteTotal, x: sx, y: sy }, siteIndex, siteSeed);
+                return o && { rawCode: o.rawCode, blackLevelCode: o.blackLevelCode, digitalSaturationCode: o.digitalSaturationCode, flags: o.flags, whiteCode: o.whiteCode };
+            }
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 export function createNativeEnvironmentSensorLean(frame, producerFrame, nativeWindow) {
     const enabled = !leanDisabled && nativeWindow !== undefined && frame.identityBinding && frame.repeatWidth > 0 && frame.repeatHeight > 0;
     const templates = [], handles = new WeakMap(), memo = new WeakMap();