@photivra/engine 2.1.0 → 2.2.1

package/dist/facade/simulate-capture.js

@@ -43,21 +43,22 @@ import { estimateCie1931ColorMatchingFunctions } from "../color/color-matching-f
 import { createColorTemperatureWhiteBalanceIntent, resolveColorTemperatureWhiteBalance, resolveCustomWhiteBalance, resolveManualWhiteBalance, estimateAutoWhiteBalance } from "../color/white-balance.js";
 import { createCaptureWhiteBalanceIntent } from "../capture/simulated-capture.js";
 import { SENSOR_RAW_PRODUCER_NOISE_MODEL } from "../capture/sensor-raw-producer.js";
-import { calculateNativeRawPlan } from "../capture/native-raw.js";
+import { calculateNativeRawPlan, nativeRawMaximumProviderEvaluations, NATIVE_RAW_LIMITS } from "../capture/native-raw.js";
 import { createNativeEnvironmentRawTask } from "../capture/native-environment-raw.js";
 import { createNativeRawDevelopmentTask } from "../capture/native-raw-development.js";
 import { parseSdrRenderingProfile } from "../output/sdr-rendering.js";
-import { createPrintJpegTask } from "../output/print-jpeg.js";
+import { createPrintJpegTask, PRINT_JPEG_LIMITS } from "../output/print-jpeg.js";
 import { checkNativeRawIntegrity, prepareNativeRawDevelopment } from "../capture/native-raw-development.js";
 import { createRawPixelDeveloper, normalizedRawSite, rawSiteSaturated } from "../capture/raw-development-kernel.js";
 import { createAhdDemosaicTask } from "../processing/demosaic.js";
+import { PROCESSING_MAX_PIXELS } from "../processing/processing-task.js";
 import { renderSdrRunInto } from "../output/native-capture-sdr.js";
 import { prepareSdrPixelTone } from "../output/sdr-rendering.js";
 import { BUILT_IN_BAYER_DEMOSAIC_MODEL_VERSION as BUILT_IN_DEMOSAIC_VERSION, createBuiltInBayerDemosaicProfiles } from "../sensor/raw-reconstruction.js";
 import { transformOrientedRasterPointToNative } from "../output/capture-geometry.js";
 import { resolveCaptureColorModel } from "../color/capture-color.js";
 import { evaluateBt709Oetf, evaluateSrgbEncoding, resolveRgbColorSpace } from "../color/rgb-color-spaces.js";
-import { serializePngImage } from "../output/png-encoder.js";
+import { serializePngImage, PNG_ENCODER_LIMITS } from "../output/png-encoder.js";
 import { parseLensProjectionModel } from "../camera/lens-projection.js";
 import { prepareEnvironmentLensFieldMapping } from "../optics/sensor-environment-query.js";
 import { createRollingShutterCaptureExposureSchedule, resolveElectronicRollingShutterExposureSchedule } from "../sensor/readout-exposure-linkage.js";
@@ -69,7 +70,7 @@ import { resolveAntiAliasingSpatialKernel } from "../sensor/optical-stack.js";
 import { multiplyMatrices } from "../color/colorimetry-math.js";
 import { prepareRgbGamutMapping } from "../color/gamut-mapping.js";
 import { serializeNativeRawDng } from "../capture/native-raw-dng.js";
-import { resolveSensorReadoutRegime } from "../sensor/raw-readout.js";
+import { parseSensorReadoutConversionProfile, resolveSensorReadoutRegime } from "../sensor/raw-readout.js";
 import { resolveChartScene, CHART_SCENE_PRESETS } from "./chart-scenes.js";
 import { resolveCaptureIlluminant, calculateIlluminantIrradianceScale, buildPlanarSceneRadianceProvider, requireCallerScene, FACADE_SPECTRAL_RANGE_NANOMETERS, PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W } from "./scene-radiance.js";
 /** Version of how the facade builds requests. It changes whenever the same input would build a different request. */
@@ -105,6 +106,12 @@ function sosReferenceLuminance(fNumber, shutterSeconds, iso) {
  */
 export const SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX = Math.PI * sosReferenceLuminance(DEFAULTS.fNumber, DEFAULTS.shutterSeconds, DEFAULTS.iso) /
     GREY_CARD_REFLECTANCE;
+/**
+ * Sensitive-aperture area (µm²) at which the tier's ISO signal chain applies unchanged: the default 6 µm square
+ * aperture with fill factor 1. At other areas the facade scales the electron-domain readout values by
+ * area / this reference, so the same focal-plane exposure H gives the same output code (see `isoAreaScaledReadout`).
+ */
+const ISO_REFERENCE_APERTURE_AREA_SQUARE_MICROMETERS = DEFAULTS.pixelPitchMicrometers * DEFAULTS.pixelPitchMicrometers;
 /** Demosaic border, native sites per side. */
 const MARGIN = 1;
 /**
@@ -184,6 +191,17 @@ const XYZ_TO_CAMERA = [[EQE_SCALE.red / EQE_SCALE.green, 0, 0], [0, 1, 0], [0, 0
 const DARK_CURRENT_ELECTRONS_PER_SECOND = 1;
 const OPERATING_TEMPERATURE_C = 20;
 function fail(message) { throw new InvalidConfigurationError(message); }
+/**
+ * The readout profile with every regime's charge-domain transfer scaled by `areaScale`: system conversion gain
+ * (e⁻ per code) and pre-ADC saturation (e⁻ equivalent) are multiplied by it, so codes per unit focal-plane exposure
+ * stay those of the reference aperture. Read noise stays in electrons per pixel; codes, black level, ADC and digital
+ * gain are unchanged. The result is re-checked by the readout parser.
+ */
+function isoAreaScaledReadout(profile, areaScale) {
+    return parseSensorReadoutConversionProfile({ ...profile, regimes: profile.regimes.map((regime) => ({ ...regime,
+            systemConversionGainElectronsPerCode: { ...regime.systemConversionGainElectronsPerCode, value: regime.systemConversionGainElectronsPerCode.value * areaScale },
+            preAdcSaturationElectronEquivalent: { ...regime.preAdcSaturationElectronEquivalent, value: regime.preAdcSaturationElectronEquivalent.value * areaScale } })) });
+}
 /** Diagnostic clock for the 2.1 stage timings: `performance.now()` where the host has it. Never affects output. */
 function clockMs() { return globalThis.performance?.now() ?? Date.now(); }
 function positive(value, name) {
@@ -343,8 +361,9 @@ async function developAhd(v, raw, repeatWidth, repeatHeight, width, height, at,
     const intent = v.plan.exposure.whiteBalanceIntent, gains = intent ? [intent.channelGains.red, intent.channelGains.green, intent.channelGains.blue] : [1, 1, 1];
     const m = v.color.normalizedCameraChannelsToXyz;
     const cameraToXyz = [0, 1, 2].map((r) => [0, 1, 2].map((c) => m[r][c] * gains[c]));
+    // A caller-raised pixel limit already bounds the raster, so its working memory is not capped again at the 1 GiB default.
     const task = createAhdDemosaicTask({ plane: { width: W, height: H, captureModeId: v.plan.frame.modeId, colorSamplingProfile: v.plan.frame.colorSamplingProfile, samples },
-        channelRoles: { red: "red", green: "green", blue: "blue" }, cameraToXyz }, { yieldControl: async () => { await host.yieldControl(); host.checkAbort(); } });
+        channelRoles: { red: "red", green: "green", blue: "blue" }, cameraToXyz, ...(v.plan.maximumPixels === undefined ? {} : { maximumWorkingBytes: Number.MAX_SAFE_INTEGER }) }, { yieldControl: async () => { await host.yieldControl(); host.checkAbort(); } });
     const demosaicStarted = clockMs();
     await task.run();
     host.onDemosaicMs?.(clockMs() - demosaicStarted);
@@ -551,9 +570,12 @@ export async function simulateCapture(options) {
     const diffractionObjectSpace = diffractionRadiusOption !== undefined && !rotating && !lensFieldMapping && !vignetting;
     // Output and sensor
     const outputOptions = allowKeys(top.output, "output", ["width", "height", "format", "toneCurve", "toneCurveParameters", "highlightMode", "whiteBalance", "jpegQuantizationStep",
-        "colorEncoding", "bitDepth", "gamutMapping", "demosaic", "borderHandling", "dng"]);
-    const width = integerIn(pick(outputOptions, "width", "output.width", DEFAULTS.width, "64 × 64 output pixels."), "output.width", 1, 4094);
-    const height = integerIn(pick(outputOptions, "height", "output.height", DEFAULTS.height, "64 × 64 output pixels."), "output.height", 1, 4094);
+        "colorEncoding", "bitDepth", "gamutMapping", "demosaic", "borderHandling", "dng", "maximumPixels"]);
+    // Opt-in large images: a caller-raised native pixel limit. Without it the 4094-pixel sides are unchanged.
+    const raisedPixels = outputOptions.maximumPixels === undefined ? undefined : integerIn(outputOptions.maximumPixels, "output.maximumPixels", 1, NATIVE_RAW_LIMITS.ceilingPixels);
+    const maximumSide = raisedPixels === undefined ? 4094 : NATIVE_RAW_LIMITS.maximumDimension;
+    const width = integerIn(pick(outputOptions, "width", "output.width", DEFAULTS.width, "64 × 64 output pixels."), "output.width", 1, maximumSide);
+    const height = integerIn(pick(outputOptions, "height", "output.height", DEFAULTS.height, "64 × 64 output pixels."), "output.height", 1, maximumSide);
     const format = pick(outputOptions, "format", "output.format", DEFAULTS.format, "8-bit sRGB samples.");
     if (!["srgb-8", "srgb-16", "jpeg", "png", "dng"].includes(format))
         fail("output.format must be srgb-8, srgb-16, jpeg, png or dng.");
@@ -628,6 +650,14 @@ export async function simulateCapture(options) {
         fail("output.demosaic \"ahd\" with mirror borders needs an output of at least 3 × 3 pixels.");
     // Geometry: the demosaic border (if any) on each side; output crop is the active area.
     const nativeWidth = width + 2 * margin, nativeHeight = height + 2 * margin;
+    if (raisedPixels !== undefined) {
+        if (nativeWidth > NATIVE_RAW_LIMITS.maximumDimension || nativeHeight > NATIVE_RAW_LIMITS.maximumDimension || nativeWidth * nativeHeight > raisedPixels) {
+            fail("output.maximumPixels (" + raisedPixels + ") must cover the native sensor raster of " + nativeWidth + " × " + nativeHeight +
+                " sites (the output plus the demosaic margin), at most " + NATIVE_RAW_LIMITS.maximumDimension + " per side.");
+        }
+        if (ahd && nativeWidth * nativeHeight > PROCESSING_MAX_PIXELS)
+            fail("output.demosaic \"ahd\" admits at most " + PROCESSING_MAX_PIXELS + " native sites.");
+    }
     const imagingArea = { widthMm: nativeWidth * pitch / 1000, heightMm: nativeHeight * pitch / 1000 };
     const geometry = { imagingArea, nativeRaster: { pixelWidth: nativeWidth, pixelHeight: nativeHeight }, orientation: "landscape",
         activeCaptureRect: { x: margin, y: margin, width, height }, outputRaster: { pixelWidth: width, pixelHeight: height } };
@@ -773,17 +803,31 @@ export async function simulateCapture(options) {
     fNumber = resolution.resolvedSettings.aperture ?? fNumber;
     shutterSeconds = resolution.resolvedSettings.shutterSeconds ?? shutterSeconds;
     const resolvedIso = resolution.resolvedSettings.iso ?? iso;
-    // Sensor readout for the ISO setting
+    // Sensor readout for the ISO setting. Standard output sensitivity S = 10/H (CIPA DC-004 §3.2) is defined at the
+    // output, independent of pixel size, while the collected charge is proportional to the sensitive-aperture area
+    // (EMVA 1288 Release 4.0, Eq. 3). The tier's signal chain is anchored to the 6 µm aperture; at another area the
+    // charge-domain readout scales with the area so the same H gives the same code. At 6 µm nothing is changed.
+    const areaScale = pitch * pitch / ISO_REFERENCE_APERTURE_AREA_SQUARE_MICROMETERS;
     const regimeByChannel = {};
     for (const channel of CHANNELS) {
         const asset = body.readout.find((a) => a.profile.channelId === channel) ?? fail("Camera readout lacks channel " + channel + ".");
         const chain = resolveGenericIsoSignalChain({ profile: body.signalChain, isoCapability: body.iso, requestedIsoSetting: { kind: "standard", exposureIndex: resolvedIso },
             captureModeId: IDS.mode, readoutProfile: asset.profile });
-        regimeByChannel[channel] = { readoutProfile: asset.profile, regimeId: chain.readout.regime.regimeId };
+        regimeByChannel[channel] = { readoutProfile: areaScale === 1 ? asset.profile : isoAreaScaledReadout(asset.profile, areaScale), regimeId: chain.readout.regime.regimeId };
     }
-    const baseRegime = body.readout[0].profile.regimes[0];
-    const capacityElectrons = Math.max(...body.readout[0].profile.regimes.map((r) => r.preAdcSaturationElectronEquivalent.value), baseRegime.preAdcSaturationElectronEquivalent.value);
+    const capacityRegimes = (areaScale === 1 ? body.readout[0].profile : isoAreaScaledReadout(body.readout[0].profile, areaScale)).regimes;
+    const baseRegime = capacityRegimes[0];
+    const capacityElectrons = Math.max(...capacityRegimes.map((r) => r.preAdcSaturationElectronEquivalent.value), baseRegime.preAdcSaturationElectronEquivalent.value);
     assume("sensor.capacityElectrons", "derived", capacityElectrons, "Physical charge capacity set to the body's largest declared pre-ADC saturation (its base-ISO saturation signal), so storage never clips before the declared readout white.");
+    if (areaScale !== 1) {
+        assume("sensor.isoAreaNormalization", "model", { referenceApertureAreaSquareMicrometers: ISO_REFERENCE_APERTURE_AREA_SQUARE_MICROMETERS,
+            apertureAreaSquareMicrometers: pitch * pitch, areaScale }, "Approximation. The tier's ISO signal chain is declared for a 6 µm square aperture. Standard output sensitivity S = 10/H (CIPA DC-004-2020 §3.2) is defined at the output, " +
+            "independent of pixel size, and the collected charge is proportional to the aperture area (EMVA 1288 Release 4.0, Eq. 3), so the system conversion gain (e⁻ per code) and the " +
+            "pre-ADC saturation of every ISO regime are multiplied by area / 36 µm² = " + areaScale + ". The same exposure gives the same output code at any pitch; per-pixel shot-noise SNR " +
+            "falls with smaller pixels. Read noise and dark current stay per pixel in electrons. The charge capacity follows the scaled base-ISO saturation, so it is proportional to " +
+            "the aperture area: a design consequence of holding the tier's ISO rating and highlight headroom fixed, not a measured full-well model (published sensor data grow less than " +
+            "proportionally with area across technologies).");
+    }
     assume("sensor.darkCurrent", "model", { electronsPerSecond: DARK_CURRENT_ELECTRONS_PER_SECOND, temperatureC: OPERATING_TEMPERATURE_C }, "Synthetic uniform dark current of 1 e⁻/s per site at 20 °C (the tier presets declare none); dark shot noise follows from it.");
     assume("sensor.spectralResponse", "model", { kind: "colorimetric-cmf-eqe", peakScale: EQE_SCALE }, "Idealized colorimetric sensor: channel EQE = a·{x̄, ȳ, z̄}(λ)·555/λ (the engine's analytic CIE 1931 fit), so RAW channels are proportional to CIE XYZ (Luther–Ives) and the camera matrix is diagonal. Not a real camera's response; CMF air wavelengths are used as vacuum wavelengths (difference about 0.03 %).");
     if (!antiAliasing)
@@ -894,7 +938,7 @@ export async function simulateCapture(options) {
             whiteBalanceIntent: intent, adoptedWhiteXyz: null,
             models: [{ profile: { id: "photivra-simulate-capture", version: SIMULATE_CAPTURE_FACADE_VERSION }, scientificStatus: "approximation", publicEvidenceIds: ["photivra:simulate-capture-facade"] }] },
         frameId: IDS.frame, modeId: IDS.mode, captureModeProfile, colorSamplingProfile, bindingProfile, exposureWindow,
-        maximumOutputBytes: nativeWidth * nativeHeight * 7, tileWidth
+        maximumOutputBytes: nativeWidth * nativeHeight * 7, tileWidth, ...(raisedPixels === undefined ? {} : { maximumPixels: raisedPixels })
     });
     const sceneBinding = { sceneStateId: IDS.sceneState, providerSceneId: IDS.scene, evidence };
     // Shared per-site environment pieces (identical objects for every site keep the native task's shared-state fast path).
@@ -985,7 +1029,10 @@ export async function simulateCapture(options) {
         const lambdaN = wavelengths[wavelengths.length - 1] / 1000 * fNumber * imageDistanceMm / focalLengthMm;
         // The environment resolves the PSF at each pre-filter source point, up to the largest split offset outside the imaging area.
         const aaReachMm = antiAliasing ? Math.max(...antiAliasing.components.map((c) => Math.max(Math.abs(c.offsetMicrometers.x), Math.abs(c.offsetMicrometers.y)))) / 1000 : 0;
-        const kernelRadiusSamples = diffractionRadiusOption ?? Math.min(32, Math.max(1, Math.ceil(AIRY_THIRD_ZERO_PER_LAMBDA_N * lambdaN / pitch)));
+        // The default reach is capped at the 32-site convolution limit; a capped window ends inside the third dark ring, and the
+        // larger tail energy outside it is listed per wavelength like any other (2.2.1 states the cap in the explanation).
+        const thirdRingSites = Math.max(1, Math.ceil(AIRY_THIRD_ZERO_PER_LAMBDA_N * lambdaN / pitch));
+        const kernelRadiusSamples = diffractionRadiusOption ?? Math.min(32, thirdRingSites);
         diffraction = createDiffractionLimitedPsfProfile({ aperture: "circular", focalLengthMm, apertureFNumber: fNumber, focus: { kind: "finite", distanceM: focusDistanceM },
             wavelengthsNm: wavelengths, samplePitchMicrometers: pitch, kernelRadiusSamples, fieldHalfExtentMm: aaReachMm === 0 ? { x: imagingArea.widthMm / 2, y: imagingArea.heightMm / 2 } :
                 { x: imagingArea.widthMm / 2 + aaReachMm, y: imagingArea.heightMm / 2 + aaReachMm },
@@ -998,7 +1045,8 @@ export async function simulateCapture(options) {
             truncatedEnergyByWavelength: diffraction.wavelengths.map((w) => ({ wavelengthNm: w.wavelengthNm, truncatedEnergyFraction: w.truncatedEnergyFraction })),
             execution: diffractionObjectSpace ? "object-space-convolution" : "environment-psf-quadrature" }, "Scalar Fraunhofer diffraction of an ideal, aberration-free circular pupil (Airy pattern, createDiffractionLimitedPsfProfile) at the resolved f-number, in focus, with D = f/N and the thin-lens image distance (working f-number N·v/f). " +
             "One kernel per spectral node, binned into site-sized cells over a " + (2 * kernelRadiusSamples + 1) + " × " + (2 * kernelRadiusSamples + 1) + " window" +
-            (diffractionRadiusOption === null ? " (reaching the third dark ring at the longest node)" : "") + "; the Airy tail energy outside it (listed per wavelength) is put back by unit-sum renormalization. " +
+            (diffractionRadiusOption !== null ? "" : thirdRingSites > 32 ? " (capped at 32 sites; the third dark ring at the longest node needs " + thirdRingSites + ")" :
+                " (reaching the third dark ring at the longest node)") + "; the Airy tail energy outside it (listed per wavelength) is put back by unit-sum renormalization. " +
             (diffractionObjectSpace ? "Applied as an object-space convolution: the scene radiance on the site lattice is convolved once per spectral node (calculateIrradianceConvolution) and the provider answers each site query with it, so the site inputs declare no PSF; this equals the per-tap environment PSF quadrature for this still, distortion-free planar scene (request.diffraction.psf). " :
                 "Applied through the environment PSF quadrature (one scene query per kernel tap), because camera rotation, a lens field mapping or vignetting moves the taps off the site lattice. ") +
             "No defocus, aberration or pupil clipping; the sensor pixel aperture is still point-sampled at the site centre.");
@@ -1054,7 +1102,7 @@ export async function simulateCapture(options) {
     // The native task admits at most 100 000 radiance queries per tile.
     const tileWidth = Math.max(1, Math.min(256, Math.floor(100_000 / perSite)));
     const environmentRaw = { raw: buildRawInput(intentOf(whiteBalanceState)), sceneBinding,
-        maximumProviderEvaluations: Math.min(2_000_000_000, Math.max(nativeWidth * nativeHeight, evaluations)) };
+        maximumProviderEvaluations: Math.min(nativeRawMaximumProviderEvaluations(raisedPixels === undefined ? {} : { maximumPixels: raisedPixels }), Math.max(nativeWidth * nativeHeight, evaluations)) };
     async function runTask(task) {
         const onAbort = () => task.cancel();
         signal?.addEventListener("abort", onAbort, { once: true });
@@ -1214,7 +1262,9 @@ export async function simulateCapture(options) {
         // The encoder reads every pixel once, in source tiles of at most 256 × 32 aligned to the crop origin.
         const reads = Math.ceil(height / 32) * Math.ceil(width / 256), jpegTick = progress("jpeg", reads);
         const jpegTask = createPrintJpegTask({ source, crop: { x: 0, y: 0, width, height }, outputWidth: width, outputHeight: height, quantizationStep: jpegStep,
-            maximumEncodedBytes: Math.max(65536, width * height * 6), maximumProviderReads: reads }, {
+            maximumEncodedBytes: Math.max(65536, width * height * 6), maximumProviderReads: reads,
+            // The JPEG records its admission plan, so the raised limit is passed (and recorded) only when the image needs it.
+            ...(raisedPixels === undefined || width * height <= PRINT_JPEG_LIMITS.maximumPixels ? {} : { maximumPixels: raisedPixels }) }, {
             readTile: async (request) => {
                 jpegTick();
                 const out = new Uint8Array(request.width * request.height * 3);
@@ -1233,7 +1283,8 @@ export async function simulateCapture(options) {
     let png;
     if (format === "png") {
         const pngStarted = clockMs();
-        png = serializePngImage({ width, height, bitDepth: pngBitDepth, samples: developed.integerSamples, colourEncoding: pngColourEncoding(colorEncoding) });
+        png = serializePngImage({ width, height, bitDepth: pngBitDepth, samples: developed.integerSamples, colourEncoding: pngColourEncoding(colorEncoding),
+            ...(raisedPixels === undefined || width * height <= PNG_ENCODER_LIMITS.maximumPixels ? {} : { maximumPixels: raisedPixels }) });
         encodeMs = clockMs() - pngStarted;
         assume("output.png", "model", { encoder: "serializePngImage", bitDepth: pngBitDepth, colourEncoding: pngColourEncoding(colorEncoding) }, "Deterministic PNG (8/16-bit RGB, in-house zlib) with the colour encoding signalled in the file: the sRGB chunk for sRGB, otherwise a cICP chunk with ITU-T H.273 primaries/transfer code points. No mastering-display (mDCV) or content-light-level (cLLI) metadata is written.");
     }