@photivra/engine 2.20.0 → 2.21.0

package/docs/api/equipment-sensor-profiles.md

@@ -0,0 +1,86 @@
+# equipment/sensor-profiles.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## resolveSensorProfile
+
+The profile record with this id (for `sensor.profile`); a clear error listing the ids otherwise.
+
+```ts
+export function resolveSensorProfile(id: unknown): SensorProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SENSOR_PROFILE_IDS
+
+The profile ids, in catalogue order.
+
+```ts
+SENSOR_PROFILE_IDS: readonly string[] = Object.freeze(SENSOR_PROFILES.map((p) => p.id))
+```
+
+## SENSOR_PROFILES
+
+The catalogue, in the issue's order. Frozen.
+
+```ts
+SENSOR_PROFILES: readonly SensorProfile[] = Object.freeze(([
+  { id: "full-frame-24mp-bsi-2020s", name: "Full frame 24 MP BSI, 2020s", marketTag: "consumer", architecture: "back-illuminated",
+    sensorWidthMm: 36.07, sensorHeightMm: 24.01, pixelsWide: 6072, pixelsHigh: 4042, pixelPitchMicrometers: 5.94, peakQuantumEfficiency: .8,
+    fullWellElectrons: 100000, readNoise: { lowGainElectrons: 6.4, highGainElectrons: 1.1, highGainFromIso: 500 }, highGainFullWellElectrons: 20000,
+    adcBitDepth: 14, baseIso: 100, maximumIso: 51200, maximumAnalogGain: 64, readoutSeconds: .05, fixedPattern: BSI,
+    goodFor: ["landscape", "portrait", "travel"], description: "Large pixels and a deep full well for wide dynamic range at base ISO; a moderate readout shows some rolling-shutter skew.",
+    fixedLenses: null, provenance: { ...sourced("S1", "pixels", "pixelPitchMicrometers", "peakQuantumEfficiency", "fullWellElectrons", "readNoise", "adcBitDepth"),
+      sensorSize: "derived", architecture: "published S1", highGainFromIso: "derived S1", highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "full-frame-45mp-stacked-2020s", name: "Full frame 45 MP stacked, 2020s", marketTag: "professional", architecture: "stacked",
+    sensorWidthMm: 36, sensorHeightMm: 24, pixelsWide: 8256, pixelsHigh: 5504, pixelPitchMicrometers: 4.36, peakQuantumEfficiency: .8,
+    fullWellElectrons: 69000, readNoise: { lowGainElectrons: 3.5, highGainElectrons: 1.5, highGainFromIso: 250 }, highGainFullWellElectrons: 22080,
+    adcBitDepth: 14, baseIso: 80, maximumIso: 25600, maximumAnalogGain: 64, readoutSeconds: .005, fixedPattern: BSI,
+    goodFor: ["landscape", "studio", "wildlife"], description: "High resolution with a fast stacked readout: fine detail for landscape and studio work, little rolling-shutter skew for action.",
+    fixedLenses: null, provenance: { pixelPitchMicrometers: "derived", fullWellElectrons: "design (S2 scaled by pixel area)", readNoise: "design (S2)", highGainFromIso: "design (S2)",
+      highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "full-frame-24mp-stacked-sports-2020s", name: "Full frame 24 MP stacked (sports), 2020s", marketTag: "professional", architecture: "stacked",
+    sensorWidthMm: 36, sensorHeightMm: 24, pixelsWide: 6000, pixelsHigh: 4000, pixelPitchMicrometers: 6, peakQuantumEfficiency: .8,
+    fullWellElectrons: 80000, readNoise: { lowGainElectrons: 3, highGainElectrons: 1, highGainFromIso: 400 }, highGainFullWellElectrons: 25000,
+    adcBitDepth: 14, baseIso: 125, maximumIso: 102400, maximumAnalogGain: 64, readoutSeconds: .0025, fixedPattern: BSI,
+    goodFor: ["sports", "wildlife", "journalism"], description: "The fastest readout and low high-gain read noise: almost no rolling-shutter skew and clean high ISO, at a moderate resolution.",
+    fixedLenses: null, provenance: { pixelPitchMicrometers: "derived", highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "full-frame-24mp-fsi-2010s", name: "Full frame 24 MP front-illuminated, 2010s", marketTag: "professional", architecture: "front-illuminated",
+    sensorWidthMm: 36.01, sensorHeightMm: 24.07, pixelsWide: 6032, pixelsHigh: 4032, pixelPitchMicrometers: 5.97, peakQuantumEfficiency: .53,
+    fullWellElectrons: 76000, readNoise: { lowGainElectrons: 4, highGainElectrons: 4, highGainFromIso: null }, highGainFullWellElectrons: null,
+    adcBitDepth: 14, baseIso: 80, maximumIso: 25600, maximumAnalogGain: 64, readoutSeconds: .08, fixedPattern: FSI,
+    goodFor: ["portrait", "landscape", "journalism"], description: "An older professional sensor: lower QE and one conversion gain, so a modern consumer BSI sensor beats it at high ISO; slow readout.",
+    fixedLenses: null, provenance: { ...sourced("S3", "pixels", "pixelPitchMicrometers", "peakQuantumEfficiency", "fullWellElectrons", "adcBitDepth"),
+      sensorSize: "derived", architecture: "derived S4", baseIso: "derived" } },
+  { id: "aps-c-24mp-fsi-2020s", name: "APS-C 24 MP front-illuminated, 2020s", marketTag: "consumer", architecture: "front-illuminated",
+    sensorWidthMm: 23.55, sensorHeightMm: 15.73, pixelsWide: 6024, pixelsHigh: 4024, pixelPitchMicrometers: 3.91, peakQuantumEfficiency: .55,
+    fullWellElectrons: 36000, readNoise: { lowGainElectrons: 2.7, highGainElectrons: 2.7, highGainFromIso: null }, highGainFullWellElectrons: null,
+    adcBitDepth: 14, baseIso: 80, maximumIso: 25600, maximumAnalogGain: 64, readoutSeconds: .06, fixedPattern: FSI,
+    goodFor: ["travel", "family", "learning"], description: "A smaller, front-illuminated sensor: less light per pixel, a slower readout and more rolling-shutter skew.",
+    fixedLenses: null, provenance: { ...sourced("S5", "pixels", "pixelPitchMicrometers", "architecture", "fullWellElectrons", "readNoise", "adcBitDepth"), sensorSize: "derived", baseIso: "derived" } },
+  { id: "aps-c-26mp-bsi-2020s", name: "APS-C 26 MP BSI, 2020s", marketTag: "professional", architecture: "back-illuminated",
+    sensorWidthMm: 23.49, sensorHeightMm: 15.7, pixelsWide: 6248, pixelsHigh: 4176, pixelPitchMicrometers: 3.76, peakQuantumEfficiency: .8,
+    fullWellElectrons: 50000, readNoise: { lowGainElectrons: 3.3, highGainElectrons: 1, highGainFromIso: 250 }, highGainFullWellElectrons: 16000,
+    adcBitDepth: 14, baseIso: 80, maximumIso: 25600, maximumAnalogGain: 64, readoutSeconds: .025, fixedPattern: BSI,
+    goodFor: ["wildlife", "sports", "travel"], description: "A BSI APS-C sensor with dual conversion gain whose readout beats the consumer full-frame profile's.",
+    fixedLenses: null, provenance: { ...sourced("S6", "pixels", "pixelPitchMicrometers", "peakQuantumEfficiency", "fullWellElectrons", "readNoise"), sensorSize: "derived",
+      architecture: "published S6", highGainFromIso: "design (S7)", highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "medium-format-100mp-bsi-16bit", name: "Medium format 100 MP BSI, 16-bit", marketTag: "professional", architecture: "back-illuminated",
+    sensorWidthMm: 43.856, sensorHeightMm: 32.9, pixelsWide: 11656, pixelsHigh: 8750, pixelPitchMicrometers: 3.76, peakQuantumEfficiency: .8,
+    fullWellElectrons: 50300, readNoise: { lowGainElectrons: 3.3, highGainElectrons: 1, highGainFromIso: 250 }, highGainFullWellElectrons: 16096,
+    adcBitDepth: 16, baseIso: 80, maximumIso: 12800, maximumAnalogGain: 64, readoutSeconds: .25, fixedPattern: BSI,
+    goodFor: ["studio", "landscape", "portrait"], description: "A large sensor with 100 MP and a 16-bit RAW; a slow readout makes its electronic shutter unsuited to motion.",
+    fixedLenses: null, provenance: { ...sourced("S7", "pixels", "pixelPitchMicrometers", "sensorSize", "fullWellElectrons", "readNoise", "adcBitDepth"), architecture: "published S8",
+      highGainFromIso: "derived S7", highGainFullWellElectrons: "derived", baseIso: "derived" } },
+  { id: "phone-50mp-stacked", name: "Phone, large, 50 MP stacked", marketTag: "consumer", architecture: "stacked",
+    sensorWidthMm: 9.844, sensorHeightMm: 7.431, pixelsWide: 8192, pixelsHigh: 6144, pixelPitchMicrometers: 1.197, peakQuantumEfficiency: .75,
+    fullWellElectrons: 8600, readNoise: { lowGainElectrons: 3, highGainElectrons: 1.4, highGainFromIso: 160 }, highGainFullWellElectrons: 2150,
+    adcBitDepth: 12, baseIso: 40, maximumIso: 6400, maximumAnalogGain: 64, readoutSeconds: 1 / 30,
+    fixedPattern: { prnu: .008, dsnu: .3, hotPixelFraction: 2e-4, hotPixelMultiplier: 50, rowElectrons: .2, columnElectrons: .2 },
+    goodFor: ["everyday", "travel", "family"], description: "A large phone sensor: tiny pixels with a small full well, so less dynamic range and more noise per pixel; simulated as a single frame (no multi-frame stacking).",
+    fixedLenses: "phone", provenance: { ...sourced("S9", "pixels", "pixelPitchMicrometers", "sensorSize", "architecture", "adcBitDepth"), fullWellElectrons: "design (S10 scaled by pixel area)",
+      readNoise: "high gain published S10, low gain design", highGainFullWellElectrons: "derived", readoutSeconds: "derived S9 (1 / full-resolution frame rate)",
+      fixedPattern: "PRNU, row and column published S10; the rest design", baseIso: "derived" } }
+] satisfies SensorProfile[]).map((p) => Object.freeze(p)))
+```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.20.0",
-  "engineApiVersion": "2.20.0",
+  "packageVersion": "2.21.0",
+  "engineApiVersion": "2.21.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -512,6 +512,16 @@
       "source": "src/output/crop.ts",
       "kind": "type"
     },
+    {
+      "name": "calculateChannelEffectiveDispersion",
+      "source": "src/output/generic-lens-corrections.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateChannelEffectiveDispersionInput",
+      "source": "src/output/generic-lens-corrections.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateChartFraming",
       "source": "src/facade/subject-framing.ts",
@@ -972,6 +982,16 @@
       "source": "src/optics/lateral-chromatic-aberration.ts",
       "kind": "type"
     },
+    {
+      "name": "calculateLateralColorFringe",
+      "source": "src/optics/generic-lens-lateral-color.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateLateralColorFringeInput",
+      "source": "src/optics/generic-lens-lateral-color.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateLensComplexPupilPsf",
       "source": "src/optics/complex-pupil-psf.ts",
@@ -1952,6 +1972,11 @@
       "source": "src/processing/demosaic.ts",
       "kind": "type"
     },
+    {
+      "name": "ChannelDispersion",
+      "source": "src/output/developed-lens-corrections.ts",
+      "kind": "type"
+    },
     {
       "name": "ChannelSeparationVectorMm",
       "source": "src/optics/lateral-chromatic-aberration.ts",
@@ -2692,6 +2717,16 @@
       "source": "src/processing/tone-mapping.ts",
       "kind": "runtime"
     },
+    {
+      "name": "createRepresentativeLightSourceIlluminant",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "createRepresentativeLightSourceSpectrum",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "runtime"
+    },
     {
       "name": "createRollingShutterCaptureExposureSchedule",
       "source": "src/sensor/readout-exposure-linkage.ts",
@@ -3247,6 +3282,16 @@
       "source": "src/capture/photographic-export.ts",
       "kind": "type"
     },
+    {
+      "name": "EXPOSURE_BUILD_UP_MAXIMUM_FRACTIONS",
+      "source": "src/facade/exposure-build-up.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "EXPOSURE_BUILD_UP_STREAM_BASE",
+      "source": "src/facade/exposure-build-up.ts",
+      "kind": "runtime"
+    },
     {
       "name": "EXPOSURE_DURATION_CONTROL_VERSION",
       "source": "src/exposure/exposure-duration-control.ts",
@@ -3997,6 +4042,11 @@
       "source": "src/optics/psf-foundation.ts",
       "kind": "runtime"
     },
+    {
+      "name": "getRepresentativeLightSourceSet",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "runtime"
+    },
     {
       "name": "getWebGpuEnabled",
       "source": "src/gpu/webgpu-switch.ts",
@@ -4247,6 +4297,11 @@
       "source": "src/gpu/image-kernel-execution.ts",
       "kind": "type"
     },
+    {
+      "name": "ImagePlaneImage",
+      "source": "src/facade/scene-radiance.ts",
+      "kind": "type"
+    },
     {
       "name": "ImagePlaneMetricPointMm",
       "source": "src/output/capture-geometry.ts",
@@ -4257,6 +4312,11 @@
       "source": "src/motion/camera-rotation.ts",
       "kind": "type"
     },
+    {
+      "name": "ImagePlaneScene",
+      "source": "src/facade/scene-radiance.ts",
+      "kind": "type"
+    },
     {
       "name": "ImagingAreaMetrics",
       "source": "src/sensor/sensor-geometry.ts",
@@ -4487,6 +4547,16 @@
       "source": "src/optics/lateral-chromatic-aberration.ts",
       "kind": "type"
     },
+    {
+      "name": "LateralColorDisplacement",
+      "source": "src/optics/generic-lens-lateral-color.ts",
+      "kind": "type"
+    },
+    {
+      "name": "LateralColorFringe",
+      "source": "src/optics/generic-lens-lateral-color.ts",
+      "kind": "type"
+    },
     {
       "name": "LayeredColorSamplingLayout",
       "source": "src/sensor/color-sampling.ts",
@@ -4847,6 +4917,31 @@
       "source": "src/exposure/metering-temporal.ts",
       "kind": "type"
     },
+    {
+      "name": "MixedIllumination",
+      "source": "src/facade/mixed-illumination.ts",
+      "kind": "type"
+    },
+    {
+      "name": "MixedIlluminationBlend",
+      "source": "src/facade/mixed-illumination.ts",
+      "kind": "type"
+    },
+    {
+      "name": "MixedIlluminationPoint",
+      "source": "src/facade/mixed-illumination.ts",
+      "kind": "type"
+    },
+    {
+      "name": "MixedIlluminationPointSource",
+      "source": "src/facade/mixed-illumination.ts",
+      "kind": "type"
+    },
+    {
+      "name": "MixedIlluminationSource",
+      "source": "src/facade/mixed-illumination.ts",
+      "kind": "type"
+    },
     {
       "name": "MonochromeColorSamplingLayout",
       "source": "src/sensor/color-sampling.ts",
@@ -6012,6 +6107,11 @@
       "source": "src/composition/image-formation-plan.ts",
       "kind": "type"
     },
+    {
+      "name": "prepareImagePlaneScenes",
+      "source": "src/facade/image-plane-enable.ts",
+      "kind": "runtime"
+    },
     {
       "name": "prepareRgbGamutMapping",
       "source": "src/color/gamut-mapping.ts",
@@ -6067,6 +6167,11 @@
       "source": "src/output/print-size-blur-noise.ts",
       "kind": "type"
     },
+    {
+      "name": "PrintContainLayout",
+      "source": "src/output/print-plan.ts",
+      "kind": "type"
+    },
     {
       "name": "PrintContrastReference",
       "source": "src/output/print-contrast-reference.ts",
@@ -6092,6 +6197,11 @@
       "source": "src/output/print-plan.ts",
       "kind": "type"
     },
+    {
+      "name": "PrintFit",
+      "source": "src/output/print-plan.ts",
+      "kind": "type"
+    },
     {
       "name": "PrintImageMm",
       "source": "src/output/print-size-blur-noise.ts",
@@ -6727,6 +6837,46 @@
       "source": "src/composition/image-formation-plan.ts",
       "kind": "type"
     },
+    {
+      "name": "REPRESENTATIVE_LIGHT_SOURCE_IDS",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "REPRESENTATIVE_LIGHT_SOURCE_SET_ID",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "REPRESENTATIVE_LIGHT_SOURCE_SET_VERSION",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "REPRESENTATIVE_LIGHT_SOURCE_WAVELENGTH_RANGE_NANOMETERS",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "RepresentativeLightSource",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "type"
+    },
+    {
+      "name": "RepresentativeLightSourceBand",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "type"
+    },
+    {
+      "name": "RepresentativeLightSourceId",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "type"
+    },
+    {
+      "name": "RepresentativeLightSourceSet",
+      "source": "src/facade/representative-light-sources.ts",
+      "kind": "type"
+    },
     {
       "name": "RequestedFlashSyncMode",
       "source": "src/exposure/flash.ts",
@@ -7242,6 +7392,11 @@
       "source": "src/schema/illumination-spectral.ts",
       "kind": "runtime"
     },
+    {
+      "name": "resolveSensorProfile",
+      "source": "src/equipment/sensor-profiles.ts",
+      "kind": "runtime"
+    },
     {
       "name": "resolveSensorRawReconstruction",
       "source": "src/sensor/raw-reconstruction.ts",
@@ -7787,6 +7942,21 @@
       "source": "src/sensor/fixed-pattern-noise.ts",
       "kind": "runtime"
     },
+    {
+      "name": "SENSOR_PROFILE_IDS",
+      "source": "src/equipment/sensor-profiles.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "SENSOR_PROFILE_ISO_ANCHOR",
+      "source": "src/equipment/sensor-profile-body.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "SENSOR_PROFILES",
+      "source": "src/equipment/sensor-profiles.ts",
+      "kind": "runtime"
+    },
     {
       "name": "SENSOR_RAW_CAPTURE_SAMPLE_VERSION",
       "source": "src/sensor/raw-reconstruction.ts",
@@ -8147,6 +8317,16 @@
       "source": "src/sensor/physical-charge-capacity.ts",
       "kind": "type"
     },
+    {
+      "name": "SensorProfile",
+      "source": "src/equipment/sensor-profile-body.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SensorProfileValueKind",
+      "source": "src/equipment/sensor-profile-body.ts",
+      "kind": "type"
+    },
     {
       "name": "SensorPsfIrradianceQuadrature",
       "source": "src/optics/sensor-psf-quadrature.ts",
@@ -8827,6 +9007,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureSubjectMotion",
+      "source": "src/motion/subject-motion.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureWhiteBalance",
       "source": "src/facade/simulate-capture.ts",
@@ -8867,6 +9052,26 @@
       "source": "src/capture/environment-raw-producer.ts",
       "kind": "type"
     },
+    {
+      "name": "simulateExposureBuildUp",
+      "source": "src/facade/exposure-build-up.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "SimulateExposureBuildUpFrame",
+      "source": "src/facade/exposure-build-up.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateExposureBuildUpOptions",
+      "source": "src/facade/exposure-build-up.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateExposureBuildUpResult",
+      "source": "src/facade/exposure-build-up.ts",
+      "kind": "type"
+    },
     {
       "name": "simulateGenericLensFocusError",
       "source": "src/equipment/generic-lens-catalogue.ts",

package/docs/api/facade-exposure-build-up.md

@@ -0,0 +1,105 @@
+# facade/exposure-build-up.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## EXPOSURE_BUILD_UP_MAXIMUM_FRACTIONS
+
+The most fractions one build-up takes.
+
+```ts
+EXPOSURE_BUILD_UP_MAXIMUM_FRACTIONS = 64
+```
+
+## EXPOSURE_BUILD_UP_STREAM_BASE
+
+The first stream ID of the build-up's per-site random streams (`deriveNativeSiteStreamSeedUint32`): fraction j's photo split,
+dark split and readout use streams base + 3j, + 3j + 1 and + 3j + 2 (j = 0 … 63). The whole exposure keeps the ordinary
+streams 0 (charge) and 1 (read noise).
+
+```ts
+EXPOSURE_BUILD_UP_STREAM_BASE = 0x42550000
+```
+
+## simulateExposureBuildUp
+
+Renders fractions of one exposure as one accumulating process (#534), the way a camera's live readout of a long exposure
+would show the light building up. Each fraction is read out and developed as its own photo.
+
+The model: photon and dark-charge arrivals at a site are Poisson processes (photon shot noise: EMVA 1288 Release 4.0,
+section 2, free), with any rate over time. Given the count n over [0, t] of a Poisson process with mean Λ(t), its arrival
+times are n independent times with distribution Λ(s)/Λ(t) on [0, t], so its count over [0, s] is Binomial(n, Λ(s)/Λ(t))
+(R. G. Gallager, Discrete Stochastic Processes, chapter 2, sections 2.4 and 2.5, MIT OpenCourseWare 6.262, free).
+
+The method: the whole exposure is `simulateCapture(options)` itself, with its ordinary draws and seeds. Each earlier fraction
+fⱼ is a capture of the same request in manual mode at the whole exposure's resolved f-number and ISO and the shutter fⱼ·t,
+so its expected signal at every site is integrated from the spectrum over the window [0, fⱼ·t] by the capture itself (the
+camera rotation, `motion.subject` and mixed lighting included, and each row's own window with a rolling shutter). Its
+counts are not drawn anew: going down the fractions, each site's photo and dark counts are N(fⱼ) ~ Binomial(N(fⱼ₊₁), λ(fⱼ) /
+λ(fⱼ₊₁)), with λ the site's expected mean in each render (after PRNU and DSNU). So every fraction's counts are Poisson with
+that fraction's own mean (the mean and variance of `simulateCapture` at fⱼ·t), they never decrease from one fraction to the
+next, and two fractions' counts covary by the earlier one's mean. Fixed-pattern noise is the sensor's own and the same in
+every fraction. Each fraction's charge is clipped at the full well, then read once: its own read noise (dual gain as the ISO
+selects), pre-ADC and ADC saturation and quantization at the ADC bit depth.
+
+The windows are nested, so the true means never decrease; the capture's temporal midpoint quadrature can still put an
+earlier fraction's estimate above a later one's at a site (motion blur). There the split takes probability 1 (the count is
+kept), and the `exposure.buildUp` assumption counts those sites (`nonMonotoneSites`): an approximation of the quadrature,
+not of the binomial law. Raise `sensor.temporalSampleCount` to remove them.
+
+Cost: one capture per fraction, plus about 64 bytes per native site for the chain. Exact or fast: the request's own `fast`
+(and the format default) applies to every fraction; the build-up adds no fast method, so with `fast: false` (the calculator's
+setting) every fraction is an exact capture. On screen only: formats "srgb-8" and "srgb-16" (a fraction's JPEG, PNG or DNG
+is refused). A fraction's realization depends on the whole `fractions` list (each step of the chain has its own streams);
+the same request and list always give the same frames.
+
+```ts
+export async function simulateExposureBuildUp(options: SimulateCaptureOptions, buildUp: SimulateExposureBuildUpOptions): Promise<SimulateExposureBuildUpResult>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## SimulateExposureBuildUpFrame
+
+One readout of a build-up.
+
+```ts
+export interface SimulateExposureBuildUpFrame {
+  /** The fraction of the exposure collected. */
+  fraction: number;
+  /** fraction × the request's shutter time, in s. */
+  elapsedSeconds: number;
+  /**
+   * The fraction developed as its own photo. At fraction 1 it is `simulateCapture(options)` itself, byte for byte. Below 1 it is
+   * the result of the fraction's capture (manual, the whole exposure's f-number and ISO, shutter fraction·t: its `image`, `raw`,
+   * `plan` and `request`), with the build-up's counts, the `exposure.buildUp` assumption, and the whole exposure's `exposure` and
+   * `sensor` reports (the camera's settings and noise figure, not the elapsed part's).
+   */
+  result: SimulateCaptureResult;
+}
+```
+
+## SimulateExposureBuildUpOptions
+
+The build-up to render with {@link simulateExposureBuildUp}.
+
+```ts
+export interface SimulateExposureBuildUpOptions {
+  /**
+   * Fractions of `exposure.shutterSeconds` to read out, strictly increasing, each above 0 and at most 1 (1 to 64 of them), for
+   * example `[0.2, 0.4, 0.6, 0.8, 1]`. A fraction of 1 is the whole exposure: `simulateCapture` of the request.
+   */
+  fractions: readonly number[];
+}
+```
+
+## SimulateExposureBuildUpResult
+
+The readouts of {@link simulateExposureBuildUp}, in the order of `fractions`.
+
+```ts
+export interface SimulateExposureBuildUpResult {
+  /** The whole exposure's shutter time, in s. */
+  shutterSeconds: number;
+  frames: readonly SimulateExposureBuildUpFrame[];
+}
+```

package/docs/api/facade-fast-methods.md

@@ -21,9 +21,13 @@ SIMULATE_CAPTURE_FAST_METHODS: readonly SimulateCaptureFastMethod[] = Object.fre
     exact: "one zone per site: the PSF at each site centre", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "resolveFast(catalogueFast, fastTop)" }, report: { applied: "lens.catalogue", assumption: "view.lensPsf" } },
   { id: "lens.diffraction/rolling-shutter-taps", override: "lens.diffraction", methods: "fast-and-exact", runs: ["simulateCapture"],
-    fast: "#565: under rolling-shutter rotation, each PSF tap reads the scene at its own source point",
+    fast: "#565: under rolling-shutter rotation (#551: or subject motion), each PSF tap reads the scene at its own source point",
     exact: "each tap reads the scene at its site-lattice point (ties on chart boundaries resolve as on the lattice)", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "resolveFast(diffractionFast, fastTop)" }, report: { applied: "lens.diffraction", assumption: "fast.lens.diffraction" } },
+  { id: "lens.catalogue/rolling-shutter-taps", override: "lens.catalogue", methods: "fast-and-exact", runs: ["simulateCapture"],
+    fast: "#588: under rolling-shutter rotation, each catalogue PSF tap reads the scene at its own source point",
+    exact: "each tap reads the scene at its site-lattice point (ties on chart boundaries resolve as on the lattice)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(catalogueFast, fastTop)" }, report: { applied: "lens.catalogue", assumption: "fast.lens.catalogue" } },
   { id: "output.demosaic.ahd/view-low-signal-correction", override: "output.demosaic", methods: "fast-and-exact", runs: ["simulateDisplayView", "prepareDisplayView"],
     fast: "(H3) 2048 draws per correction state, applied where a pixel's linear noise exceeds 0.01",
     exact: "8192 draws per state, at the same 0.01 threshold", followsFormatDefault: true,
@@ -40,6 +44,10 @@ SIMULATE_CAPTURE_FAST_METHODS: readonly SimulateCaptureFastMethod[] = Object.fre
   { id: "sensor.midGrey", override: "fast", methods: "fast-and-exact", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
     fast: "#535: the mid-gray noise figure is not computed (about 0.3 ms)", exact: "result.sensor.midGrey is computed", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "fastTop ? undefined : 0" }, report: { field: "sensor.midGrey" } },
+  { id: "motion.subject/temporal-midpoints", override: "motion.subject", methods: "fast-and-exact", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
+    fast: "#551: with the default count and a still camera, one temporal midpoint per site of the subject's streak plus one, when that is fewer than 8",
+    exact: "the default 8 temporal midpoints (an explicit sensor.temporalSampleCount always wins)", followsFormatDefault: true,
+    resolver: { file: CAPTURE, call: "resolveFast(subjectFast, fastTop)" }, report: { applied: "motion.subject", assumption: "fast.motion.subject" } },
   { id: "lens.diffraction", override: "lens.diffraction", methods: "exact-only", runs: ["simulateCapture", "simulateDisplayView", "prepareDisplayView"],
     fast: "", exact: "the diffraction kernels (a fast method only under rolling-shutter rotation, above)", followsFormatDefault: true,
     resolver: { file: CAPTURE, call: "resolveFast(diffractionFast, fastTop)" }, report: { applied: "lens.diffraction" } },

package/docs/api/facade-image-plane-enable.md

@@ -0,0 +1,16 @@
+# facade/image-plane-enable.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## prepareImagePlaneScenes
+
+2.21 (#581): enables `{ kind: "image-plane" }` scenes (a photo as a flat print, docs/IMAGE_PLANE.md) in this JavaScript realm by
+loading their module (a lazy chunk of about 14 KB gzip with its lattice data). Call it once, in the worker that captures, before
+the first request with such a scene; later calls resolve at once. A request with an image-plane scene before it fails with a
+message saying so.
+
+```ts
+export async function prepareImagePlaneScenes(): Promise<void>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.

package/docs/api/facade-mixed-illumination.md

@@ -0,0 +1,67 @@
+# facade/mixed-illumination.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## MixedIllumination
+
+2.22 (#550), `simulateCapture` `illumination`: sources blended across the chart and point sources with inverse-square falloff
+(docs/MIXED_ILLUMINATION.md). It replaces `illuminant` and `illuminanceLux`. `sources` lists 1 to 8 sources (with two or more, a
+`blend` is required; one lights the whole plane); `points` lists 1 to 8 point sources; a request needs two or more sources or at least one point. Blend
+coordinates are chart-local with `chartSize` and frame units without it; (0, 0) is the frame center.
+
+```ts
+export interface MixedIllumination {
+  sources?: readonly MixedIlluminationSource[];
+  blend?: MixedIlluminationBlend;
+  points?: readonly MixedIlluminationPointSource[];
+}
+```
+
+## MixedIlluminationBlend
+
+How the sources blend across the chart. `linear-gradient` and `radial` map a point to a position t in [0, 1] (its projection
+onto `from` → `to`, clamped; or its distance from `center` over `radius`, clamped) and crossfade linearly between consecutive
+sources at their `stops` (one per source, non-decreasing in [0, 1]; default evenly spaced from 0 to 1): source 0 alone up to
+stops[0], the last source alone from its stop on, and two equal stops a hard edge (the later source from the stop on).
+`regions` gives each point the source of the first rectangle that contains it (bounds inclusive) and `outsideSource` elsewhere.
+
+```ts
+export type MixedIlluminationBlend =
+  | { kind: "linear-gradient"; from: MixedIlluminationPoint; to: MixedIlluminationPoint; stops?: readonly number[] }
+  | { kind: "radial"; center?: MixedIlluminationPoint; radius: number; stops?: readonly number[] }
+  | { kind: "regions"; regions: readonly { source: number; uMin: number; uMax: number; vMin: number; vMax: number }[]; outsideSource: number };
+```
+
+## MixedIlluminationPoint
+
+A point in chart coordinates (see {@link MixedIllumination}).
+
+```ts
+export interface MixedIlluminationPoint { u: number; v: number }
+```
+
+## MixedIlluminationPointSource
+
+2.22 (#550): a point light on the scene plane's front side: an illuminant spectrum, a position in metres (`xM`, `yM` on the plane
+from the optical axis, +x right and +y up as seen from the camera; `heightM` > 0 in front of the plane, toward the camera) and an
+intensity, either in candela or as the illuminance it gives at normal incidence at a reference distance (I = E·r²).
+
+```ts
+export interface MixedIlluminationPointSource {
+  illuminant: CaptureIlluminant;
+  position: { xM: number; yM: number; heightM: number };
+  intensity: { candela: number } | { illuminanceLux: number; distanceM: number };
+}
+```
+
+## MixedIlluminationSource
+
+One light source of a mixed illumination: an illuminant (as `simulateCapture` `illuminant` takes it) at an illuminance.
+
+```ts
+export interface MixedIlluminationSource {
+  illuminant: CaptureIlluminant;
+  /** Illuminance this source alone gives where its weight is 1, lux, (0, 1e7]. */
+  illuminanceLux: number;
+}
+```