@photivra/engine 2.8.1 → 2.10.0

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { hypot3 } from "../core/portable-math.js";
 import { apertureRadianceQuery } from "../sensor/environment-photo-signal.js";
 import { createSensorEqeTemporalPhotoSignal } from "../sensor/temporal-photo-signal.js";
 import { isDeeplyFrozen } from "../core/internal-radiance-evaluator.js";
@@ -21,7 +22,7 @@ import { composeNativeEnvironmentSensorSite } from "./native-environment-optical
 import { calculateNativeRawSite, parseNativeRawProducerSite } from "./sensor-raw-producer.js";
 import { calculateSiteEffectiveSaturationCode } from "./raw-white-level.js";
 import { adcTransfer, resolveSensorReadoutRegime, samplePoisson } from "../sensor/raw-readout.js";
-import { createDeterministicUniformStream, deriveNativeSiteStreamSeedUint32, sampleDeterministicStandardNormal, NATIVE_SITE_CHARGE_STREAM_ID, NATIVE_SITE_READ_NOISE_STREAM_ID } from "../sensor/stochastic-seed.js";
+import { createResettableUniformStream, deriveNativeSiteStreamSeedUint32, sampleDeterministicStandardNormal, NATIVE_SITE_CHARGE_STREAM_ID, NATIVE_SITE_READ_NOISE_STREAM_ID } from "../sensor/stochastic-seed.js";
 import { evaluateParsedFixedPatternSite } from "../sensor/fixed-pattern-noise.js";
 /** Most distinct templates kept for one capture event. Any further distinct sites just run the full path. */
 const MAXIMUM_TEMPLATES = 64;
@@ -273,7 +274,7 @@ function geometry(t, k, frame, environment, index, access) {
                         if (!Number.isFinite(reference.z) || reference.z <= 0)
                             return undefined;
                         const rx = pd * (reference.x / reference.z), ry = pd * (reference.y / reference.z);
-                        const length = Math.hypot(rx, ry, pd);
+                        const length = hypot3(rx, ry, pd);
                         const ray = { x: rx / length, y: ry / length, z: pd / length };
                         // Build the parseSceneRadianceEvaluationRequest output directly. Every other field is a template constant already
                         // parsed for the template site. The sample ID is a public opaque ID (trimming cannot change it) and the time is
@@ -281,7 +282,7 @@ function geometry(t, k, frame, environment, index, access) {
                         const direction = { x: -ray.x, y: -ray.y, z: -ray.z };
                         if (!Number.isFinite(direction.x) || !Number.isFinite(direction.y) || !Number.isFinite(direction.z))
                             return undefined;
-                        const norm = Math.hypot(direction.x, direction.y, direction.z);
+                        const norm = hypot3(direction.x, direction.y, direction.z);
                         if (!Number.isFinite(norm) || Math.abs(norm - 1) > 1e-9)
                             return undefined;
                         // #394: the key the evaluator would read for this request (undefined where it would throw: the full path decides).
@@ -969,6 +970,12 @@ function sensorMatches(site, photo, x, y, t, memo) {
         photo.temporalSamples.length === t.photo.temporalSamples.length;
 }
 /** The sensor stage of calculateNativeRawSite, in the same operation order. Returns undefined when one of its checks would throw. */
+/**
+ * #418: the charge and read-noise streams of the site leanSensorSite is computing, reseeded for each site. leanSensorSite is
+ * synchronous and never re-entered, so one pair serves every call; reseeding sets exactly the state a new
+ * createDeterministicUniformStream would start from, so every draw is unchanged.
+ */
+const chargeStream = createResettableUniformStream(), readNoiseStream = createResettableUniformStream();
 function leanSensorSite(t, h, index, seed) {
     const ratio = h.total / t.capacity, headroom = t.capacity - h.total;
     if (!Number.isFinite(ratio) || !Number.isFinite(headroom))
@@ -979,19 +986,23 @@ function leanSensorSite(t, h, index, seed) {
     const darkMean = pattern === null ? h.darkE : h.darkE * pattern.darkCurrentFactor;
     if (!Number.isFinite(photoMean) || photoMean < 0 || !Number.isFinite(darkMean) || darkMean < 0)
         return undefined;
-    const random = createDeterministicUniformStream(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_CHARGE_STREAM_ID));
+    const random = chargeStream;
+    random.reset(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_CHARGE_STREAM_ID));
     const photoRealized = samplePoisson(photoMean, random), darkRealized = samplePoisson(darkMean, random);
     const realized = photoRealized + darkRealized + 0;
     if (!Number.isFinite(realized) || realized < 0)
         return undefined;
-    const readRandom = createDeterministicUniformStream(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_READ_NOISE_STREAM_ID));
+    const readRandom = readNoiseStream;
+    readRandom.reset(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_READ_NOISE_STREAM_ID));
     const regime = t.readout.regime, capacity = t.capacity;
     const afterPhysical = Math.min(realized, capacity), physicalSaturation = afterPhysical < realized;
-    const sampled = regime.readNoiseComponents.map(component => component.rmsElectrons.value === 0 ? 0 :
-        sampleDeterministicStandardNormal(readRandom) * component.rmsElectrons.value);
+    // The components' draws and their sum in one loop: the same draws, added to 0 in the same order as before (#418).
+    const components = regime.readNoiseComponents;
     let totalReadNoise = 0;
-    for (const value of sampled)
-        totalReadNoise = totalReadNoise + value;
+    for (let k = 0; k < components.length; k++) {
+        const rms = components[k].rmsElectrons.value;
+        totalReadNoise = totalReadNoise + (rms === 0 ? 0 : sampleDeterministicStandardNormal(readRandom) * rms);
+    }
     const afterReadNoise = afterPhysical + totalReadNoise + (pattern === null ? 0 : pattern.readoutOffsetElectrons);
     const threshold = regime.preAdcSaturationElectronEquivalent.value;
     const afterPreAdc = Math.min(afterReadNoise, threshold), preAdcSaturation = afterReadNoise > threshold;
@@ -1001,6 +1012,84 @@ function leanSensorSite(t, h, index, seed) {
         flags: Number(physicalSaturation) | Number(preAdcSaturation) << 1 | Number(quantized >= digitalSaturationCode) << 2,
         whiteCode: t.whiteCode, photoRealized, darkRealized };
 }
+function flatSensorStage(t) {
+    const regime = t.readout.regime;
+    return { darkRate: t.darkRate, capacity: t.capacity, pattern: t.pattern, whiteCode: t.whiteCode, regime, adcMaximumCode: t.readout.adcMaximumCode,
+        inlDefined: regime.adc.integralNonLinearity !== undefined, gain: regime.systemConversionGainElectronsPerCode.value, black: regime.adc.blackLevelCode,
+        digitalGain: regime.adc.digitalGain, digitalSaturationCode: regime.adc.digitalSaturationCode, threshold: regime.preAdcSaturationElectronEquivalent.value,
+        rms: Float64Array.from(regime.readNoiseComponents, (component) => component.rmsElectrons.value), darkMean: NaN, darkThreshold: NaN,
+        out: { rawCode: 0, blackLevelCode: 0, digitalSaturationCode: 0, flags: 0, whiteCode: 0 } };
+}
+/** Writes the site's outputs into `f.out`; false where leanSensorSite returns undefined. */
+function flatSensorSite(f, photoE, darkE, total, x, y, index, seed) {
+    const ratio = total / f.capacity, headroom = f.capacity - total;
+    if (!Number.isFinite(ratio) || !Number.isFinite(headroom))
+        return false;
+    const pattern = f.pattern === undefined ? null : evaluateParsedFixedPatternSite(f.pattern, { x, y });
+    const photoMean = pattern === null ? photoE : photoE * pattern.photoResponseGainFactor;
+    const darkMean = pattern === null ? darkE : darkE * pattern.darkCurrentFactor;
+    if (!Number.isFinite(photoMean) || photoMean < 0 || !Number.isFinite(darkMean) || darkMean < 0)
+        return false;
+    const random = chargeStream;
+    random.reset(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_CHARGE_STREAM_ID));
+    const photoRealized = samplePoisson(photoMean, random);
+    let darkRealized;
+    if (darkMean > 0 && darkMean < 30) {
+        // samplePoisson's branch for 0 < mean < 30 (Knuth's product of uniforms) with its threshold Math.exp(−mean) kept while the
+        // mean repeats: the same draws from the same stream. (createPoissonSampler would also do this, but it brings the
+        // portable-math functions into capture-only bundles.)
+        if (darkMean !== f.darkMean) {
+            f.darkMean = darkMean;
+            f.darkThreshold = Math.exp(-darkMean);
+        }
+        const threshold = f.darkThreshold;
+        let product = 1, count = 0;
+        do {
+            count += 1;
+            product *= random.next();
+        } while (product > threshold);
+        darkRealized = count - 1;
+    }
+    else
+        darkRealized = samplePoisson(darkMean, random);
+    const realized = photoRealized + darkRealized + 0;
+    if (!Number.isFinite(realized) || realized < 0)
+        return false;
+    const readRandom = readNoiseStream;
+    readRandom.reset(deriveNativeSiteStreamSeedUint32(seed, index, NATIVE_SITE_READ_NOISE_STREAM_ID));
+    const capacity = f.capacity;
+    const afterPhysical = Math.min(realized, capacity), physicalSaturation = afterPhysical < realized;
+    const rmsAll = f.rms;
+    let totalReadNoise = 0;
+    for (let k = 0; k < rmsAll.length; k++) {
+        const rms = rmsAll[k];
+        totalReadNoise = totalReadNoise + (rms === 0 ? 0 : sampleDeterministicStandardNormal(readRandom) * rms);
+    }
+    const afterReadNoise = afterPhysical + totalReadNoise + (pattern === null ? 0 : pattern.readoutOffsetElectrons);
+    const threshold = f.threshold;
+    const afterPreAdc = Math.min(afterReadNoise, threshold), preAdcSaturation = afterReadNoise > threshold;
+    let quantized;
+    if (f.inlDefined)
+        quantized = adcTransfer(f.regime, f.adcMaximumCode, afterPreAdc).quantized;
+    else {
+        // adcTransfer without integral non-linearity: ideal = e/G + black, plus the zero INL offset, rounded half up (Math.round + 0),
+        // then with a digital gain the ADC clamp and the gain's own rounding about the black level.
+        const ideal = afterPreAdc / f.gain + f.black, quantizedAdc = Math.round(ideal + 0) + 0, digitalGain = f.digitalGain;
+        if (digitalGain === undefined)
+            quantized = quantizedAdc;
+        else {
+            const adcCode = Math.max(0, Math.min(quantizedAdc, f.adcMaximumCode));
+            quantized = Math.round((adcCode - f.black) * digitalGain + f.black) + 0;
+        }
+    }
+    const digitalSaturationCode = f.digitalSaturationCode, out = f.out;
+    out.rawCode = Math.max(0, Math.min(quantized, digitalSaturationCode));
+    out.blackLevelCode = f.black;
+    out.digitalSaturationCode = digitalSaturationCode;
+    out.flags = Number(physicalSaturation) | Number(preAdcSaturation) << 1 | Number(quantized >= digitalSaturationCode) << 2;
+    out.whiteCode = f.whiteCode;
+    return true;
+}
 /** The Kahan (compensated) total that composeSensorAccumulatedCharge computes, for photo and dark charge only. */
 function chargeTotal(photoE, darkE) {
     let sum = 0, correction = 0;
@@ -1029,17 +1118,22 @@ export function createVerifiedNativeSiteReadout(parsed, result, whiteCode, photo
             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;
+        // #449: the flat stage must reproduce the verification site too.
+        const flat = flatSensorStage(t), fo = flat.out;
+        if (!flatSensorSite(flat, photo.expectedGeneratedElectronCount, darkE, total, x, y, index, seed) || fo.rawCode !== out.rawCode || fo.blackLevelCode !== out.blackLevelCode ||
+            fo.digitalSaturationCode !== out.digitalSaturationCode || fo.flags !== out.flags || fo.whiteCode !== out.whiteCode)
+            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;
+                const siteDark = flat.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 };
+                // One record for every site (#449): the caller copies the five RAW fields before its next call.
+                return flatSensorSite(flat, photoE, siteDark, siteTotal, sx, sy, siteIndex, siteSeed) ? fo : undefined;
             }
         };
     }