@photivra/engine 2.9.0 → 2.11.1

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";
@@ -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).
@@ -1011,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;
@@ -1039,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;
-                // The site's own record: the caller reads only the five RAW fields, so no copy without the realizations (#418).
-                return leanSensorSite(t, { photo: { expectedGeneratedElectronCount: photoE }, darkE: siteDark, total: siteTotal, x: sx, y: sy }, siteIndex, siteSeed);
+                // 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;
             }
         };
     }