@photivra/engine 2.0.0 → 2.2.0

package/docs/QUICK_START.md

@@ -50,7 +50,7 @@ the example above is [simulate-capture.mjs](examples/simulate-capture.mjs).
 | `request` | The complete underlying request: `environmentRaw` (the native environment RAW input), `siteInput(index)` (rebuilds the physical input of any sensor site), `development` (the RAW development input) and `whiteBalanceState` |
 | `exposure` | Mode, resolved settings, EV100, metered scene luminance and the exposure-mode resolver's full output |
 | `scene` | Chart parameters, illuminant, distance, framed size and the scene's SHA-256 digest (it covers caller illuminant and reflectance spectra; see `sourceSha256`) |
-| `diagnostics` | Radiance query count, highlight and rendering counters, and timings |
+| `diagnostics` | Radiance query count, highlight and rendering counters, per-stage timings (`timingsMs`) and, from 2.1, the opt-ins that ran (`options`); see [Cost of each option](#cost-of-each-option) |
 | `provenance` | Status (`approximation`), camera preset identity, evidence, the composed contracts in order, and limitations |
 | `assumptions` | Every default, derived value and fixed modelling choice, each with an explanation |
 
@@ -71,6 +71,7 @@ modelling choices (such as "no lens PSF") as `kind: "model"`.
 | `lens.distortion` | none | `{ kind: "radial", profile }` or `{ kind: "brown-conrady", profile }`. |
 | `lens.vignetting` | none | An `IlluminationVignettingProfile` (radial relative illumination). |
 | `lens.psf` | none | A `{ kind: "sampled-local", configuration }` sampled lens PSF, passed to the environment contract unchanged. |
+| `lens.diffraction` | off | 2.1: `"circular-aperture"` or `{ aperture: "circular-aperture", kernelRadiusSamples }`: diffraction blur of an ideal lens at the resolved f-number (see [Optics](#optics)). |
 | `exposure.mode` | `"manual"` | Also `"aperture-priority"`, `"shutter-priority"`, `"program"`. |
 | `exposure.iso` | 100 | Selects the body's ISO readout regime (gain and read noise). |
 | `exposure.shutterSeconds` | 1/125 | Used in `manual` and `shutter-priority`. |
@@ -79,31 +80,34 @@ modelling choices (such as "no lens PSF") as `kind: "model"`.
 | `subjectDistanceM` | 5 | Distance of the scene plane. |
 | `illuminant` | Planckian 6500 K | Also `"cie-a"`, `{ kind: "planckian", temperatureKelvin }`, `{ kind: "daylight", correlatedColorTemperatureKelvin, basis }` or `{ kind: "spectrum", spectrum }`. |
 | `illuminanceLux` | 21 481 (π·80 000/11.7) | See [Exposure](#exposure). |
-| `output.width`, `output.height` | 64 × 64 | Output pixels. The sensor has one extra site on each side for demosaicing (see `output.borderHandling`). |
+| `output.width`, `output.height` | 64 × 64 | Output pixels, 1–4094 each. The sensor has one extra site on each side for demosaicing (see `output.borderHandling`). |
+| `output.maximumPixels` | off | Opt-in large images (2.2): the most native sensor sites the capture may allocate, up to `NATIVE_RAW_LIMITS.ceilingPixels` (2^27). Sides may then reach 16 384 sites including the margin (see [Large images](#large-images)). |
 | `output.format` | `"srgb-8"` | Also `"srgb-16"`, `"jpeg"`, `"png"` and `"dng"` (see [Output formats](#output-formats)). |
 | `output.colorEncoding` | `"srgb"` | PNG only: also `"display-p3"` and `"rec2020"`. |
 | `output.bitDepth` | 8 | PNG only: 8 or 16. |
 | `output.gamutMapping` | `"clip"` | PNG only: or `"perceptual"`. |
 | `output.dng.capturedAtUtc` | none | DNG only: capture time for the date tags. |
-| `output.demosaic` | the 1.0 bilinear kernels | `"bilinear"` (see [Demosaic](#demosaic)). |
+| `output.demosaic` | the 1.0 bilinear kernels | `"bilinear"` or, from 2.1, `"ahd"` (see [Demosaic](#demosaic)). |
 | `output.borderHandling` | `"margin"` | Or `"mirror"`. |
 | `output.toneCurve` | `"identity"` | Any `SdrToneCurve`, for example `"positive-reinhard-per-channel"`. |
 | `output.toneCurveParameters` | none | Required by the luminance curves (`extended-reinhard-luminance`, `naka-rushton-luminance`); the facade invents no curve parameters. |
 | `output.highlightMode` | `"clip"` | Or `"reconstruct"`. |
 | `output.whiteBalance` | `"scene-illuminant"` | Also `"auto"`, `"none"`, `{ kelvin, tint? }` and `{ channelGains }`. |
 | `output.jpegQuantizationStep` | 2 | JPEG only: constant step 1–255, not a manufacturer quality scale. |
-| `sensor.pixelPitchMicrometers` | 6 | The sensor is `width × pitch` wide (see [Geometry](#geometry)). |
+| `sensor.pixelPitchMicrometers` | 6 | 0.5–100. The sensor is `width × pitch` wide (see [Geometry](#geometry)); the ISO readout scales with the pixel area (see [ISO and pixel size](#iso-and-pixel-size)). |
 | `sensor.spectralStepNanometers` | 20 | Spectral quadrature over 380–780 nm. |
 | `sensor.temporalSampleCount` | 1, or 8 when the camera rotates | Midpoints across each site's exposure window. |
 | `sensor.noiseSeed` | 1 | Output is deterministic for a given seed. |
+| `sensor.antiAliasing` | off | 2.1: an optical low-pass (anti-aliasing) filter: `{ kind: "four-spot", separationSites? }`, `{ kind: "two-spot", axis, separationSites? }` or `{ kind: "point-splitting", components }` (see [Anti-aliasing filter](#anti-aliasing-filter)). |
 | `motion.angularVelocityRadPerSec` | still | `{ pitch?, yaw?, roll? }` in rad/s (see [Motion](#motion)). |
 | `motion.shutter` | `"global"` | Or `"rolling"`. |
 | `motion.rollingShutterSkewSeconds` | the body's readout skew | Rolling only. |
-| `signal`, `onProgress` | none | An `AbortSignal` cancels the running task; `onProgress` reports `raw`, `white-balance`, `development` and `jpeg` tiles. The last event of each stage has `completedTileCount === totalTileCount`. |
+| `signal`, `onProgress` | none | An `AbortSignal` cancels the running task; `onProgress` reports `raw`, `white-balance`, `development` and `jpeg` tiles. The last event of each stage has `completedTileCount === totalTileCount`. The capture yields to the host about every 8 ms with a `MessageChannel` message (else `setImmediate`, else `setTimeout`), so other queued tasks run in between: an abort sent from another task, such as a Web Worker `message` event, takes effect at the next yield. |
 
 Unknown fields are rejected, so a typo never silently falls back to a default.
 
-Every option added in 2.0 (PNG, demosaic, optics and motion) is opt-in. With none of them given, the
+Every option added in 2.0 (PNG, demosaic, optics and motion) and in 2.1 (`lens.diffraction`,
+`output.demosaic: "ahd"`, `sensor.antiAliasing`) is opt-in. With none of them given, the
 request, RAW, samples and JPEG are byte-identical to the 1.0 facade at the same illuminance, and a
 test checks that. (The default illuminance changed before release; see [Exposure](#exposure).)
 
@@ -118,6 +122,39 @@ pixels is therefore a 0.38 mm crop of a large sensor, not a downscaled full fram
 signal per pixel, and so the noise and the ISO behaviour, physically consistent with the tier's
 sensor values.
 
+### ISO and pixel size
+
+The tier's ISO signal chain (conversion gain, saturation signal and read noise per ISO setting) is
+declared for the default 6 µm pixel. At other pitches the facade keeps the ISO calibration
+independent of pixel size, so the same exposure gives the same image brightness at any pitch:
+
+- Standard output sensitivity S = 10/H (CIPA DC-004-2020 §3.2) is defined by the camera's output
+  for a focal-plane exposure H; it does not depend on pixel size.
+- The charge a pixel collects is proportional to its area: the photon count is μp = A·E·t/(hν)
+  (EMVA Standard 1288 Release 4.0 Linear, §2.1, Eq. 3, free).
+- So the facade multiplies the system conversion gain (e⁻ per code) and the pre-ADC saturation
+  signal of every ISO regime by the area ratio pitch²/36 µm². Codes, black level, ADC and digital gain
+  are unchanged. At 6 µm the ratio is exactly 1 and nothing is changed (byte-identical to 2.1.0).
+- Read noise (in e⁻) and the synthetic dark current (1 e⁻/s) stay per pixel.
+
+What you see: brightness stays the same, and per-pixel noise rises as pixels shrink, because a
+smaller pixel collects fewer electrons for the same exposure (shot-noise SNR = √N_e). At f/8, 1/125 s,
+ISO 100 on an 18 % grey card, the 8-bit sRGB mean is 101.2 at 30, 6 and 3 µm, and the green standard
+deviation is 0.18, 0.93 and 1.83 codes. Below about 1 µm the 8-bit sRGB mean falls slightly (about 1 code at 0.55 µm)
+although the linear RAW mean is unchanged (within 0.3 %): strong noise passed through the concave
+sRGB curve lowers the mean of the encoded values.
+
+The charge capacity follows the scaled base-ISO saturation signal (see `sensor.capacityElectrons`),
+so it is proportional to pixel area: 60 000 e⁻ at 6 µm, 15 000 e⁻ at 3 µm, 1 500 000 e⁻ at 30 µm.
+This is a consequence of holding the tier's ISO rating and its half stop of highlight headroom fixed,
+**not a measured full-well model**. Published sensor data show full-well capacity growing with pixel
+size but less than in proportion to area across process generations (for example about 16 000 e⁻ at
+2 µm and 37 500 e⁻ at 5.2 µm in Farrell, Xiao & Kavusi, *Proc. SPIE* 6069, 2006, Table 1; Chen et al.,
+*Proc. SPIE* 3965, 2000, model the photodiode capacitance as roughly linear in pixel side). A real
+large-pixel sensor may therefore saturate earlier, and a real small-pixel sensor would usually be
+given a higher base ISO. When the pitch is not 6 µm, the assumption `sensor.isoAreaNormalization`
+records the area ratio and this approximation.
+
 ## Exposure
 
 The facade meters the scene like a reflected-light meter:
@@ -217,14 +254,15 @@ These choices appear in `assumptions` as `kind: "model"` entries:
   lens capability. By default no PSF (point-spread function) or diffraction, vignetting, distortion,
   lateral colour or stray light is applied. The tier's optical data exist only at f/4 and 5 m, and
   the facade does not extrapolate them. Vignetting, distortion and PSF are applied only from profiles
-  you supply.
+  you supply; diffraction of an ideal lens only with `lens.diffraction` (2.1).
 - **Sensor.** Square pixels with a fill factor of 1 and no anti-aliasing filter. A global
   electronic shutter unless `motion.shutter` is `"rolling"`. A synthetic uniform dark current of
-  1 e⁻/s at 20 °C (the tiers declare none). The charge capacity equals the body's base-ISO saturation signal.
+  1 e⁻/s at 20 °C (the tiers declare none). The charge capacity equals the body's base-ISO saturation signal,
+  scaled with pixel area away from 6 µm (see [ISO and pixel size](#iso-and-pixel-size)).
 - **Demosaic.** Bilinear RGGB interpolation through the existing linear-kernel contract, unless
-  `output.demosaic` selects a built-in kernel. (Demosaicing fills in the two missing colours at each
+  `output.demosaic` selects a built-in kernel or AHD. (Demosaicing fills in the two missing colours at each
   pixel of a colour-filter mosaic.) Sharp edges without lens blur therefore show the usual zipper and
-  false-colour artefacts.
+  false-colour artefacts; `"ahd"` and `lens.diffraction` reduce them.
 - **Scene.** A planar Lambertian surface: radiance = reflectance × irradiance / π, with illuminance
   from K_m = 683 lm/W and the analytic ȳ. No shadows, inter-reflection, gloss or fluorescence.
 - **Rendering.** Linear sRGB with RAW white at display white, no exposure push, out-of-gamut
@@ -323,9 +361,23 @@ console.log(dng.width, dng.activeArea, dng.whiteLevel, dng.codes.length === shot
 
 ## Demosaic
 
-`output.demosaic` selects the built-in Bayer kernels of `createBuiltInBayerDemosaicProfiles`:
-`"bilinear"` (nearest same-channel averages; pixel-identical to the default). The Malvar–He–Cutler
-kernels are not in 2.0 (a patent is still in force; see
+`output.demosaic` selects:
+
+- `"bilinear"`: the built-in Bayer kernels of `createBuiltInBayerDemosaicProfiles` (nearest same-channel
+  averages; pixel-identical to the default).
+- `"ahd"` (2.1): adaptive homogeneity-directed demosaicing, `createAhdDemosaicTask` (after Hirakawa &
+  Parks, *IEEE Trans. Image Processing* 14(3), 2005). Green is interpolated along rows and along columns,
+  red and blue follow from colour differences, and each pixel takes the more homogeneous of the two
+  candidates in CIELAB. It is non-linear and edge-directed, so it shows much less zipper and false colour
+  on sharp edges than bilinear (mean false colour of a neutral 32 × 32 Siemens star: 138 instead of 209
+  8-bit codes; slanted edge: 5.3 instead of 11.4). The RAW sites are normalized and white-level clipped
+  exactly as in the native development, the homogeneity is measured on white-balanced colour, and the
+  native development's colour operator and SDR kernel follow. The paper's iterative median step is not
+  applied. With `"margin"` borders the sensor gets 5 extra sites per side (an AHD pixel depends on sites
+  up to 5 away); `request.development` keeps the bilinear kernels, which validate the development but do
+  not produce the pixels.
+
+The Malvar–He–Cutler kernels are not offered (a patent is still in force; see
 [PROCESSING.md](https://github.com/Photivra/photivra/blob/main/docs/PROCESSING.md)).
 
 `output.borderHandling` decides how edge pixels get their neighbours:
@@ -365,6 +417,25 @@ The optics options feed only what the environment site contract accepts:
   1 + r2·ρ² + r4·ρ⁴ + r6·ρ⁶, applied once at the physical sensor point before any PSF.
 - `lens.psf` is a caller sampled PSF passed through unchanged. Its focal length, f-number and focus
   must equal the resolved capture settings exactly, and it cannot be combined with pupil sampling.
+- `lens.diffraction` (2.1) adds the diffraction blur of an ideal lens at the capture's resolved
+  f-number, so stopping down now softens the image as well as darkening it.
+  - The engine builds the kernels (`createDiffractionLimitedPsfProfile`): the Airy pattern of a uniformly
+    lit circular pupil (scalar Fraunhofer diffraction), aberration-free and in focus, with pupil diameter
+    f/N and the thin-lens image distance (working f-number N·v/f). Each kernel holds the PSF energy of
+    site-sized cells, one kernel per spectral node.
+  - The kernel window reaches the third dark ring at the longest node by default (2, 4 and 7 sites at
+    f/4, f/8 and f/16 with 6 µm pixels); set `kernelRadiusSamples` (0–32) to change it. The Airy tail
+    outside the window (2–5 % of the energy with the default) is listed per wavelength in the
+    `lens.diffraction` assumption and put back by renormalizing each kernel to unit sum.
+  - It runs as an object-space convolution: the scene radiance on the site lattice is convolved once per
+    spectral node and the provider answers each site query with it. That is the same sum as the
+    environment PSF quadrature (one scene query per kernel tap) for this still, distortion-free planar
+    scene; a test checks it to 1e-12 per site. With camera rotation, a projection or distortion, or
+    vignetting, the per-tap quadrature runs instead (much slower). `request.diffraction` holds the profile,
+    the equivalent `sampled-local` PSF and which execution ran.
+  - Not modelled: defocus, aberrations, pupil clipping, a polygonal (bladed) aperture (the tiers declare
+    no blade count) and the pixel aperture (each site is still sampled at its centre). It cannot be
+    combined with `lens.psf` or `lens.pupilSampling`.
 
 The default frame is a 0.38 mm crop behind a 50 mm lens, a field of well under a degree. Projection
 and distortion effects therefore only become visible with larger pixels (or a custom lens). The
@@ -397,6 +468,65 @@ const lensy = await simulateCapture({
 console.log(lensy.request.siteInput(0).environment.lensFieldMapping, lensy.assumptions.find((a) => a.id === "lens.vignetting")?.kind);
 ```
 
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const stoppedDown = await simulateCapture({
+  scene: { preset: "siemens-star" },
+  lens: { fNumber: 16, diffraction: "circular-aperture" },
+  exposure: { shutterSeconds: 1 / 30 },
+  output: { width: 48, height: 48, demosaic: "ahd" }
+});
+console.log(stoppedDown.request.diffraction?.execution, stoppedDown.request.diffraction?.profile.maximumTruncatedEnergyFraction);
+```
+
+### Anti-aliasing filter
+
+`sensor.antiAliasing` (2.1) puts an optical low-pass filter in front of the sensor. Most real cameras
+with a Bayer sensor carry one; the generic tiers declare none, so it is off by default. It is modelled
+the way a birefringent quartz filter works: every image point is split into equally bright copies, and
+each site collects the light that would otherwise have landed at its centre minus each offset (the
+engine's `normalized-point-splitting-kernel` optical-stack response, resolved by
+`resolveAntiAliasingSpatialKernel`).
+
+- `{ kind: "four-spot", separationSites }`: two crossed plates, four spots at (±d/2, ±d/2) with weight
+  1/4 each. Its MTF is |cos(π·f_x·d)·cos(π·f_y·d)|. The most common filter in digital cameras.
+- `{ kind: "two-spot", axis: "horizontal" | "vertical", separationSites }`: one plate, two spots at
+  ±d/2 along the axis, MTF |cos(π·f·d)|.
+- `{ kind: "point-splitting", components }`: your own kernel, offsets in micrometres (+x right, +y
+  down) and positive weights that sum to 1; at most 16 components, each within 4 sites.
+- d = `separationSites` × pixel pitch, 0 < `separationSites` ≤ 4. The default 1 puts the first MTF
+  zero at the sensor's Nyquist frequency 1/(2·pitch): a four-spot filter one pixel wide cuts off at
+  Nyquist (Palum 2006). Above Nyquist the cosine rises again, so a lens (for example
+  `lens.diffraction`) is still needed to suppress the highest frequencies.
+
+Measured at f/8 on 128 × 128 neutral charts (mean false colour |R − G| + |B − G| in 8-bit codes):
+Siemens star 100.8 → 52.2 with bilinear and 68.7 → 25.1 with AHD; slanted edge 4.9 → 3.8 (bilinear).
+The price is sharpness: the slanted-edge 10–90 % width grows from 1.49 to 2.34 px (bilinear).
+
+Each site queries the scene once per spot, so the radiance work grows by the number of spots (4 for
+`four-spot`). With `lens.diffraction` the object-space convolution still applies: the taps around
+each split point lie on the site lattice shifted by its offset, so the engine convolves once per
+distinct sub-site shift (one half-site lattice for the default four-spot filter). A test checks it
+against the per-tap environment quadrature to 1e-12 per site.
+
+Approximations, listed in the `sensor.antiAliasing` assumption: the split is the same at every
+wavelength, field point and polarization (birefringence dispersion is ignored), the spots are exact
+points of equal weight for unpolarized light, and the filter's transmission, reflections and focus
+shift are not modelled. It is not a measured filter.
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const filtered = await simulateCapture({
+  scene: { preset: "siemens-star" },
+  sensor: { antiAliasing: { kind: "four-spot" } },
+  lens: { diffraction: "circular-aperture" },
+  output: { width: 48, height: 48, demosaic: "ahd" }
+});
+console.log(filtered.assumptions.find((a) => a.id === "sensor.antiAliasing")?.value);
+```
+
 ## Motion
 
 `motion.angularVelocityRadPerSec` rotates the camera at a constant rate during the exposure, in the
@@ -450,10 +580,147 @@ The 1000 × 1000 row is not a measurement. It multiplies the 256 × 256 CPU cost
 count. Before the lean executor, the same 64 × 64 capture took about 6.0 s of CPU on this host, and
 128 × 128 about 20.6 s. Development and encoding are a small part of the total.
 
+The 2.1 options, measured on the same kind of host (4-vCPU Intel Xeon 2.80 GHz, Node 24, median of three
+runs, slanted edge and Siemens star): at 48 × 48, default 0.38–0.45 s, `lens.diffraction` 0.49–0.71 s
+(f/4–f/16), `"ahd"` 0.48–0.63 s, both 0.60–0.87 s; at 128 × 128, default 2.1–2.3 s, diffraction
+2.5–3.4 s, AHD 2.4–2.5 s, both 2.8–4.0 s. The same diffraction through the per-tap environment quadrature
+took 13.1 s at 48 × 48, f/8. [Cost of each option](#cost-of-each-option) covers every opt-in.
+
 These numbers come from one run on one machine. They are not a performance claim. Small captures
 (up to about 128 × 128) take a few seconds. Use them while you explore, and render large images only
 when you need them.
 
+## Cost of each option
+
+Slow options are opt-in, so an application can decide which ones it can afford: a feature that is
+too slow for a phone today may be cheap on the next generation of hardware. The table gives the
+measured wall time of each opt-in that affects run time, relative to the default capture of the same
+size.
+
+**Method.** Slanted-edge chart, every other option at its default (f/8, 1/125 s, ISO 100, sRGB 8-bit,
+bilinear demosaic). One fresh Node process per row and size; one 16 × 16 warm-up capture, then three
+timed captures (`performance.now()` around `simulateCapture`), median reported. Built `dist`, Node
+24.21.0, 4-vCPU Intel Xeon 2.80 GHz, Linux, nothing else running. One run on one machine: not a
+performance claim, but the ratios carry over roughly.
+
+| Option | 48 × 48 | 128 × 128 | What it buys |
+| --- | --- | --- | --- |
+| default | 0.50 s (1×) | 2.49 s (1×) | Point optics, bilinear demosaic, sRGB samples |
+| `lens.diffraction: "circular-aperture"` | 0.65 s (1.3×) | 2.84 s (1.1×) | Aperture-dependent sharpness (Airy blur); convolution 0.38 s at 128 |
+| `output.demosaic: "ahd"` | 0.65 s (1.3×) | 2.60 s (1.0×) | About half the false colour on sharp edges; 5-site margin, demosaic 0.05 s at 128 |
+| `sensor.antiAliasing: { kind: "four-spot" }` | 0.94 s (1.9×) | 4.96 s (2.0×) | Optical low-pass filter: false colour halved again, at a cost in sharpness |
+| anti-aliasing + diffraction | 1.16 s (2.3×) | 6.02 s (2.4×) | Both, still on the fast convolution path |
+| anti-aliasing + diffraction + AHD | 1.42 s (2.8×) | 6.99 s (2.8×) | The most faithful still image of a planar chart |
+| `lens.pupilSampling` 1 × 4 rays | 1.79 s (3.6×) | 11.5 s (4.6×) | Defocus and depth of field, coarse |
+| `lens.pupilSampling` 2 × 8 rays | 5.20 s (10×) | 33.1 s (13×) | Defocus and depth of field, smoother bokeh |
+| `lens.psf` (caller 3 × 3 kernel) | 2.11 s (4.2×) | 12.4 s (5.0×) | Any sampled lens PSF; runs per tap, so cost grows with the kernel size (a 9 × 9 diffraction kernel took 13.1 s at 48 × 48) |
+| `motion` yaw 0.01 rad/s (8 temporal samples) | 1.70 s (3.4×) | 8.74 s (3.5×) | Motion blur; cost grows with `sensor.temporalSampleCount` |
+| rotation + `shutter: "rolling"` | 1.79 s (3.6×) | 9.24 s (3.7×) | Rolling-shutter skew of moving content |
+| `motion.shutter: "rolling"` (still camera) | 0.47 s (0.9×) | 2.51 s (1.0×) | Per-row exposure windows; no cost alone |
+| `output.format: "png"` | 0.50 s (1.0×) | 2.63 s (1.1×) | PNG file bytes; encode 16 ms at 128 |
+| `output.format: "jpeg"` | 0.52 s (1.0×) | 2.59 s (1.0×) | Baseline JPEG; encode 45 ms at 128 |
+| `output.format: "dng"` | 0.50 s (1.0×) | 2.27 s (0.9×) | Lossless CFA DNG of the RAW; encode 4 ms at 128 |
+| `output.highlightMode: "reconstruct"` | 0.50 s (1.0×) | 2.20 s (0.9×) | Near-clipped highlights blend smoothly toward neutral instead of clipping per channel; no measurable cost |
+| `output.whiteBalance: "auto"` | 0.77 s (1.6×) | 4.76 s (1.9×) | Grey-world white balance; renders the RAW a second time (2.24 s at 128) |
+
+Ratios below about 1.1× are within the run-to-run spread (the three default runs at 128 × 128 took
+2.23–2.50 s). The radiance work dominates: options that multiply the scene queries per site
+(anti-aliasing spots, pupil rays, PSF taps, temporal samples) multiply the run time by about the same
+factor, and output-side options cost almost nothing.
+
+### Measuring cost on the user's device
+
+From 2.1 every result says what ran and how long each stage took, so an application can decide on the
+user's own device which options to offer:
+
+- `diagnostics.options` lists the opt-ins that changed the work of the run, in the fixed order of
+  `SIMULATE_CAPTURE_COST_OPTIONS` (for example `["lens.diffraction", "sensor.antiAliasing",
+  "output.demosaic.ahd", "output.format.png"]`). It is empty when every default is used.
+- `diagnostics.timingsMs` has `raw`, `whiteBalance` (the second RAW pass of `whiteBalance: "auto"`),
+  `development` (includes DNG writing), `jpeg` and `total` in whole milliseconds, and, where the stage
+  ran, `diffraction` (the object-space convolution, part of `raw`), `demosaic` (the AHD demosaic, part
+  of `development`) and `encode` (PNG, JPEG or DNG serialization), with sub-millisecond resolution where
+  the host has `performance.now()`.
+
+Timings change from run to run, but nothing else does: they never enter the scene digest, the RAW,
+the samples or the encoded files, and a test checks that two runs differ only in `timingsMs`.
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const probe = await simulateCapture({ scene: { preset: "slanted-edge" }, output: { width: 32, height: 32, demosaic: "ahd" } });
+console.log(probe.diagnostics.options, probe.diagnostics.timingsMs.total, probe.diagnostics.timingsMs.demosaic);
+```
+
+## Large images
+
+By default a capture is at most 4094 × 4094 output pixels and every full-resolution stage admits at most
+24 000 000 pixels (PNG: 100 000 000). Large images are slow and memory-hungry, so from 2.2 they are an
+opt-in that the application decides on, for example after checking the device:
+
+- `simulateCapture`: `output.maximumPixels`, the most native sensor sites (output plus the demosaic margin
+  on each side) the capture may allocate. A 12 252 × 8 168 output with the default margin needs
+  12 254 × 8 170 = 100 115 180; passing `NATIVE_RAW_LIMITS.ceilingPixels` is simplest. Each side may then
+  reach 16 384 sites including the margin. `output.demosaic: "ahd"` still admits at most 2^26 = 67 108 864
+  native sites, checked before any work.
+- The stages directly: `maximumPixels` on `calculateNativeRawPlan` / `createNativeRawTask` (and so on every
+  native environment and development task built from that input), `createNativeCaptureSdrTask`,
+  `calculateIrradianceConvolution`, `calculateTemporalExposureSum`, `createPrintJpegTask` and
+  `serializePngImage`; `maximumRegionSites` on `simulatePackedSensorRaw`; `maximumQueries` on
+  `calculateChartRadianceBatch`.
+
+Each value must be an integer from 1 to the stage's ceiling (`ceilingPixels`, `ceilingRegionSites`,
+`ceilingQueries`), all 2^27 = 134 217 728 = 16 384 × 8 192. That covers 12 252 × 8 168 (100.07 MP) and
+11 552 × 8 664 (100.09 MP) sensors plus their margin with about a third to spare. It is also the size at
+which the pipeline's largest single array, the interleaved float64 RGB of the development (24 bytes per
+pixel), reaches 3 GiB: JavaScript engines cap an `ArrayBuffer` at about 4 GiB or less, so a higher ceiling
+could not be honoured anyway. The per-side limit (16 384) and every byte budget (`maximumOutputBytes` and
+similar) still apply. A raised native RAW limit raises the native environment whole-event query budget
+ceiling in proportion (2 000 000 000 per 24 000 000 pixels), and a raised Print JPEG limit raises its
+`maximumEncodedBytes` ceiling the same way (256 000 000 bytes per 24 000 000 pixels). Leaving the inputs out
+changes nothing: requests, plans and output bytes stay as they were.
+
+```ts
+import { NATIVE_RAW_LIMITS, simulateCapture } from "@photivra/engine";
+
+// The same capture with large images allowed; at 16 × 16 the output is identical to the default.
+const large = await simulateCapture({ scene: { preset: "slanted-edge" }, output: { width: 16, height: 16, maximumPixels: NATIVE_RAW_LIMITS.ceilingPixels } });
+console.log(large.plan.maximumPixels, large.plan.pixelCount);
+```
+
+**Measured cost.** One fresh Node process per stage and size (Node 24.21.0, 4-vCPU Intel Xeon 2.80 GHz,
+Linux, one run each, single thread). Synthetic inputs: a gradient with pseudo-random noise for the
+encoders, repeating patterns elsewhere; the PNG and JPEG times depend on the image content. *Peak
+memory* is the process's peak resident memory minus the idle runtime (about 125 MB), per pixel; it
+includes the stage's input and output arrays. Not a performance claim, but it shows how the cost grows.
+
+| Stage (as measured) | 1 MP | 24 MP | 100.07 MP | Per MP | Peak memory per pixel |
+| --- | --- | --- | --- | --- | --- |
+| Irradiance convolution, radius 2 (25 taps), float32 in | 0.32 s | 6.5 s | 27.7 s | 0.28 s | 12 B (4 in, 8 out) |
+| Temporal exposure sum, 8 nodes | 0.56 s | 9.7 s | 42.0 s | 0.42 s | 12 B (4 in, 8 out) |
+| Packed sensor RAW (`simulatePackedSensorRaw`) | 0.60 s | 11.9 s | 48.2 s | 0.48 s | 11 B measured; the all-zero dark plane was never touched, so count 16 B of input plus the output |
+| Chart radiance batch, one wavelength | 0.13 s | 2.6 s | 13.0 s | 0.13 s | 17 B (9 in, 8 out) |
+| PNG, 8-bit sRGB | 0.31 s | 2.7 s | 22.7 s | 0.23 s | 8 B (3 in) |
+| PNG, 16-bit sRGB | 0.57 s | 5.1 s | 40.7 s | 0.41 s | 15 B (6 in) |
+| Print JPEG, 1:1, quantization step 2 | 0.84 s | 19.5 s | 69.7 s | 0.70 s | 10 B (3 in; 2.6–2.9 B out) |
+| Native capture SDR, 8-bit (tiles from the caller) | 0.07 s | 1.6 s | 5.8 s | 0.06 s | 4 B (3 out) |
+| Native RAW DNG writer | 0.07 s | 1.7 s | 6.4 s | 0.06 s | 17 B (7 in, 2 out) |
+| Native RAW development to 8-bit sRGB | 0.34 s | 5.2 s | 20.5 s | 0.21 s | 10 B (7 in, 3 out) |
+| `simulateCapture`, default options, slanted edge, sRGB 8-bit | 129 s | — (16 MP: 1 973 s) | about 3.4 h (extrapolated) | 123–129 s | 34 B at 16 MP (fixed part about 360 MB) |
+
+**What this means for a 100 MP capture.** The full capture was measured at 0.26, 1, 4 and 16 MP: 133, 129, 125 and 123 s per MP, almost all of it
+the per-site RAW simulation. At that rate a 100 MP capture with default options takes about 12 300 s
+(3.4 h) on one core of this host; the options in [Cost of each option](#cost-of-each-option) multiply
+that. The 100 MP time is extrapolated, not measured. Memory: about 360 MB of fixed working state, then a
+peak during development of about 34 bytes per pixel (7 B packed RAW, 24 B float64 linear RGB, 3 B 8-bit
+samples), measured 541 MB above the idle runtime at 16 MP, so about 3.4 GB at 100 MP. JPEG and PNG
+encoding add their own rows above; `whiteBalance: "auto"` renders the RAW twice.
+
+Browsers are tighter than Node: a tab may have a few GB at most, a single `ArrayBuffer` may be limited
+to 2–4 GB, and mobile browsers kill tabs earlier. A 100 MP capture can therefore fail in a browser with a
+`RangeError` or an out-of-memory crash even where it runs in Node. Run large captures in a Web Worker,
+pass `signal` so they can be cancelled, and offer them only on devices that can afford them.
+
 ## Not available
 
 The facade offers no atmospheric haze or polarizer (see [Optics](#optics)), flash, video, HDR brackets
@@ -462,6 +729,11 @@ provided, for rights reasons.
 
 ## Sources
 
+- R. Palum, "Anti-Aliasing Filter Analysis for Digital Cameras", Proc. IS&T International Congress of
+  Imaging Science (ICIS '06), 2006, free at
+  <https://www.imaging.org/common/uploaded%20files/pdfs/Papers/2006/ICIS-0-736/33683.pdf>
+  (birefringent quartz four-spot filter; one pixel wide in each direction cuts off at Nyquist; its MTF
+  is the modulus of a cosine that returns to one at the sampling frequency).
 - CIPA DC-004-Translation-2020, *Sensitivity of Digital Cameras*, free at
   <https://www.cipa.jp/e/std/std-sec.html> (standard output sensitivity S = 10/H, §3.2; reference
   level tied to 18 % grey, §5.2 and Explanation 1, 2.2; focal-plane exposure H = 0.65·L·t/N², §5.5

package/docs/USAGE.md

@@ -1911,6 +1911,8 @@ console.log(metrics.value.sampling.pitchYMicrometers); // 6
 
 The returned X/Y sampling pitches are the geometric spacing of image samples. They are not photodiode active area, fill factor or a photon-collection model, and must not be used as those quantities.
 
+Passing such a pitch to `simulateCapture()` as `sensor.pixelPitchMicrometers` is a supported use, but the photon model then comes from the facade, not from this pitch: the facade declares its own sensor with sites at that spacing and a square sensitive aperture of the same side (fill factor 1, the `sensor.fillFactor` assumption), and scales its ISO readout with that aperture area (see [Quick start: ISO and pixel size](QUICK_START.md#iso-and-pixel-size)). A real sensor of the same pitch may have a smaller sensitive area, microlenses and a different full-well capacity.
+
 The existing `calculatePixelPitch()` API remains available for callers that only need horizontal pitch from sensor width and horizontal pixel count.
 
 ## Sensor architecture metadata
@@ -2428,7 +2430,7 @@ The site-center lattice is a distinct physical registration contract:
 - coordinates are `native-sensor-physical`: optical-axis origin, +X right, +Y down;
 - `pitchXMicrometers` and `pitchYMicrometers` are explicit evidence-backed site-center spacings;
 - the first site's center is explicitly registered relative to the physical imaging area's top-left edge;
-- the full declared lattice must fit inside the supplied physical imaging area.
+- the full declared lattice, and the sensitive aperture of every site, must fit inside the supplied physical imaging area. The test allows 8 ε (about 1.8 × 10⁻¹⁵) of the imaging extent for floating-point rounding: an imaging width given as `n · pitch / 1000` mm and a far aperture edge computed as `pitch/2 + (n − 1)·pitch + pitch/2` µm reach the same exact value by different rounded operations and can differ in the last bit. Any larger excess is rejected.
 
 Photivra does **not** derive this site pitch or origin from `NativeImageRaster`. The native effective raster and the colour-site lattice already have a structural binding, but physical placement is a separate fact.
 

package/docs/api/capture-native-raw.md

@@ -29,10 +29,10 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## NATIVE_RAW_LIMITS
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+`maximumPixels` is the default pixel limit; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`.
 
 ```ts
-NATIVE_RAW_LIMITS = Object.freeze({ maximumPixels: 24_000_000, maximumDimension: 16_384,
+NATIVE_RAW_LIMITS = Object.freeze({ maximumPixels: 24_000_000, ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS, maximumDimension: 16_384,
   tileWidth: 256, tileHeight: 1, outputBytesPerPixel: 7 })
 ```
 
@@ -76,6 +76,13 @@ export interface NativeRawInput {
   maximumOutputBytes: number;
   /** Optional tile width for execution, in native sites, 1–256. Default 256. It does not affect sampling. */
   tileWidth?: number;
+  /**
+   * Optional opt-in pixel limit for large sensors: an integer from 1 to `NATIVE_RAW_LIMITS.ceilingPixels`.
+   * Default `NATIVE_RAW_LIMITS.maximumPixels` (24 000 000). `maximumOutputBytes` still applies. A raised limit
+   * also raises the native environment tasks' whole-event query budget ceiling in proportion
+   * (2 000 000 000 per 24 000 000 pixels). It does not affect sampling.
+   */
+  maximumPixels?: number;
 }
 ```
 
@@ -115,6 +122,8 @@ export interface NativeRawPlan {
   tileCount: number;
   /** Present only when an execution tile width was given. Otherwise the plan keeps its earlier shape. */
   tileWidth?: number;
+  /** Present only when a pixel limit was given. Otherwise the plan keeps its earlier shape. */
+  maximumPixels?: number;
   upstreamRadiometryVerified: false;
   seedSchedule: "murmur3-capture-seed-native-index-stream-v2";
 }

package/docs/api/capture-packed-sensor-raw.md

@@ -14,11 +14,12 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## PACKED_SENSOR_RAW_LIMITS
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+`maximumRegionSites` is the default region limit; a request may raise it with its own `maximumRegionSites`, up to `ceilingRegionSites`.
 
 ```ts
 PACKED_SENSOR_RAW_LIMITS = Object.freeze({
   maximumRegionSites: 24_000_000,
+  ceilingRegionSites: FULL_RESOLUTION_CEILING_PIXELS,
   maximumNativeSites: 0xffffffff,
   maximumDimension: 65_535,
   maximumAdcBitDepth: 16,
@@ -103,6 +104,11 @@ export interface PackedSensorRawInput {
   fixedPatternNoise?: PackedSensorFixedPatternNoise;
   /** Optional (2.0), at most 8. */
   additionalChargeComponents?: readonly PackedSensorAdditionalChargeComponent[];
+  /**
+   * Optional opt-in region limit for large sensors: an integer from 1 to `PACKED_SENSOR_RAW_LIMITS.ceilingRegionSites`.
+   * Default `PACKED_SENSOR_RAW_LIMITS.maximumRegionSites` (24 000 000). It does not change the result.
+   */
+  maximumRegionSites?: number;
 }
 ```
 

package/docs/api/core-pixel-limits.md

@@ -0,0 +1,19 @@
+# core/pixel-limits.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.
+
+## FULL_RESOLUTION_CEILING_PIXELS
+
+Hard ceiling of an opt-in raised pixel limit: 2^27 = 134 217 728 pixels (16 384 × 8 192).
+
+```ts
+FULL_RESOLUTION_CEILING_PIXELS = 134_217_728
+```
+
+## FULL_RESOLUTION_DEFAULT_PIXELS
+
+Default pixel limit of the full-resolution stages.
+
+```ts
+FULL_RESOLUTION_DEFAULT_PIXELS = 24_000_000
+```

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.0.0" as const
+ENGINE_API_VERSION = "2.2.0" as const
 ```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.0.0",
-  "engineApiVersion": "2.0.0",
+  "packageVersion": "2.2.0",
+  "engineApiVersion": "2.2.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -2122,6 +2122,16 @@
       "source": "src/color/white-balance.ts",
       "kind": "type"
     },
+    {
+      "name": "createDiffractionLimitedPsfProfile",
+      "source": "src/optics/diffraction-psf-profile.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CreateDiffractionLimitedPsfProfileInput",
+      "source": "src/optics/diffraction-psf-profile.ts",
+      "kind": "type"
+    },
     {
       "name": "createDurandDorseyToneMappingTask",
       "source": "src/processing/tone-mapping.ts",
@@ -2437,6 +2447,26 @@
       "source": "src/optics/depth-of-field.ts",
       "kind": "type"
     },
+    {
+      "name": "DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS",
+      "source": "src/optics/diffraction-psf-profile.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "DIFFRACTION_LIMITED_PSF_PROFILE_MODEL",
+      "source": "src/optics/diffraction-psf-profile.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "DiffractionLimitedPsfProfile",
+      "source": "src/optics/diffraction-psf-profile.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DiffractionLimitedPsfWavelength",
+      "source": "src/optics/diffraction-psf-profile.ts",
+      "kind": "type"
+    },
     {
       "name": "DigitalGeometricTransform",
       "source": "src/output/geometric-transforms.ts",
@@ -3032,6 +3062,16 @@
       "source": "src/optics/front-of-lens-filter.ts",
       "kind": "type"
     },
+    {
+      "name": "FULL_RESOLUTION_CEILING_PIXELS",
+      "source": "src/core/pixel-limits.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "FULL_RESOLUTION_DEFAULT_PIXELS",
+      "source": "src/core/pixel-limits.ts",
+      "kind": "runtime"
+    },
     {
       "name": "FullAutoExposureModeResolution",
       "source": "src/exposure/exposure-mode-resolver.ts",
@@ -5242,6 +5282,11 @@
       "source": "src/output/print-contrast-reference.ts",
       "kind": "runtime"
     },
+    {
+      "name": "PRINT_JPEG_LIMITS",
+      "source": "src/output/print-jpeg.ts",
+      "kind": "runtime"
+    },
     {
       "name": "PRINT_JPEG_SCHEMA_VERSION",
       "source": "src/output/print-jpeg.ts",
@@ -7692,6 +7737,11 @@
       "source": "src/sensor/signal-noise.ts",
       "kind": "type"
     },
+    {
+      "name": "SIMULATE_CAPTURE_COST_OPTIONS",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "runtime"
+    },
     {
       "name": "SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX",
       "source": "src/facade/simulate-capture.ts",
@@ -7722,6 +7772,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureCostOption",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureDemosaic",
       "source": "src/facade/simulate-capture.ts",
@@ -7762,6 +7817,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureSensorAntiAliasing",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureWhiteBalance",
       "source": "src/facade/simulate-capture.ts",