@photivra/engine 1.5.0 → 2.1.0

package/docs/QUICK_START.md

@@ -0,0 +1,663 @@
+# Quick start: simulate a capture
+
+`simulateCapture()` takes a small description of a camera, a lens setting, an exposure and a
+scene, and returns a developed image. Behind it runs the engine's full physical pipeline: scene
+radiance → lens → spectral sensor response → charge and noise → RAW readout → RAW development →
+optional JPEG.
+
+`simulateCapture()` is a *facade*: one simple entry point in front of those existing contracts. It
+adds no physics of its own. It only builds the request for the existing contracts, runs them, and
+tells you every choice it made for you.
+
+This page covers the inputs, the defaults, the chart presets and the limits. The detailed contracts
+it composes are in [ENVIRONMENT_RAW_CAPTURE.md](https://github.com/Photivra/photivra/blob/main/docs/ENVIRONMENT_RAW_CAPTURE.md),
+[NATIVE_RAW_AND_PRINT.md](https://github.com/Photivra/photivra/blob/main/docs/NATIVE_RAW_AND_PRINT.md), [GENERIC_TIER_PRESETS.md](https://github.com/Photivra/photivra/blob/main/docs/GENERIC_TIER_PRESETS.md),
+[COLORIMETRY.md](https://github.com/Photivra/photivra/blob/main/docs/COLORIMETRY.md) and the [Usage Guide](USAGE.md).
+
+Calling the engine from an AI agent? [Using Photivra from an agent](AGENT_GUIDE.md) says which
+function fits each task, which units to pass and how to report results honestly.
+
+## The ten-line capture
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const capture = await simulateCapture({
+  camera: "professional",
+  lens: { fNumber: 8 },
+  exposure: { mode: "manual", iso: 100, shutterSeconds: 1 / 125 },
+  scene: { preset: "slanted-edge" },
+  output: { width: 16, height: 16, format: "srgb-8" }
+});
+console.log(capture.image.width, capture.image.samples.length, capture.exposure.settings);
+```
+
+`capture.image.samples` holds interleaved 8-bit sRGB values, row by row from the top-left. The scene
+is the only required input; every other field above is the default and could be left out.
+
+Without the facade, the same kind of result needs the 34-line
+[production-capture.mjs](examples/production-capture.mjs) plus its 4,613-line
+[production-request.json](examples/production-request.json) for a 2 × 2 capture. A runnable version of
+the example above is [simulate-capture.mjs](examples/simulate-capture.mjs).
+
+## What comes back
+
+| Field | Contents |
+| --- | --- |
+| `image` | `width`, `height`, `format`, `samples` (`Uint8Array` or `Uint16Array` RGB), `jpeg` bytes for the `jpeg` format, `png` bytes plus `colorEncoding` for the `png` format, and `dng` bytes for the `dng` format |
+| `raw` | The packed native RAW: codes, black levels, saturation flags and per-phase white levels |
+| `plan` | The native RAW plan the engine executed |
+| `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, 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 |
+
+Nothing is hidden: when you omit a field, an entry with `kind: "default"` names it and its value.
+Values the facade calculates (such as the framed chart size) appear as `kind: "derived"`, and fixed
+modelling choices (such as "no lens PSF") as `kind: "model"`.
+
+## Inputs and defaults
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `camera` | `"professional"` | A generic tier id (`"consumer"`, `"prosumer"`, `"professional"`) or a full `GenericEquipmentTierPreset` record. A record must have exactly the preset shape (unknown fields at the top level, in `body`, `lens` or `lens.matchedReference` are rejected) and each profile is re-checked by its own parser. Tier values are synthetic educational designs, not real cameras. |
+| `lens.focalLengthMm` | 50 | Must lie in the lens capability; the generic primes are 50 mm. |
+| `lens.fNumber` | 8 | Used in `manual` and `aperture-priority`; resolved automatically otherwise. Must lie in f/4–f/16. |
+| `lens.focusDistanceM` | the subject distance | |
+| `lens.pupilSampling` | off | `{ radialSamples, angularSamples }` traces an ideal circular pupil, which renders defocus. Off means one chief ray per sample. Angular samples 4–64, at most 256 rays. |
+| `lens.projection` | `"rectilinear"` | Any `LENS_PROJECTION_MODELS` value, for example `"fisheye-equisolid-angle"` (see [Optics](#optics)). |
+| `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`. |
+| `exposure.compensationStops` | 0 | Applied to the meter target. |
+| `scene` | required | A chart preset or a caller function (below). |
+| `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.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"` 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.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`. 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) 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).)
+
+## Geometry
+
+The scene is a plane perpendicular to the optical axis at `subjectDistanceM`. The facade sizes the
+chart so that it exactly fills the active frame. Chart coordinates use frame units: `u` runs from −1
+at the left edge to +1 at the right edge, and `v` points up on the same scale (±height/width).
+
+The simulated sensor has real pixels of `sensor.pixelPitchMicrometers`. A 64 × 64 capture with 6 µm
+pixels is therefore a 0.38 mm crop of a large sensor, not a downscaled full frame. This keeps the
+signal per pixel, and so the noise and the ISO behaviour, physically consistent with the tier's
+sensor values.
+
+## Exposure
+
+The facade meters the scene like a reflected-light meter:
+
+- It averages the scene luminance on a 16 × 16 grid with the body's metering profile.
+- It uses two relations from CIPA DC-004-2020 (free):
+  - standard output sensitivity S = 10/H (§3.2): the correct focal-plane exposure for ISO S is
+    H = 10/S lx·s;
+  - the camera equation H = 0.65·L·t/N² (§5.5 (4)), where 0.65 = τ·π/4 with lens transmittance
+    τ = 0.828 (Explanation 4).
+
+  N is the f-number, t the shutter time in seconds, L the scene luminance in cd/m² and S the ISO
+  setting. Together they give N²/t = 0.65·L·S/10.
+- The anchor is f/8, 1/125 s, ISO 100. It is correct for L = 10·N²/(0.65·t·S) =
+  10·64·125/(0.65·100) = 80 000/65 ≈ 1230.77 cd/m².
+- The meter target then goes through the engine's existing exposure-mode resolver.
+- In `program` mode, a generic program line written by the engine chooses the aperture and shutter.
+
+DC-004 ties the reference level to an 18 % grey (Explanation 1 and 2.2). The default illuminance
+puts an 18 % Lambertian grey card, whose luminance is L = 0.18·E/π, exactly at that luminance:
+
+```text
+E = π·L/0.18 = π·10·N²/(0.65·t·S·0.18)
+  = π·10·64·125/(0.65·100·0.18) = π·80 000/11.7 ≈ 21 480.98 lux
+```
+
+Before 2.0.0 was released, the default was π·K·N²/(t·S·0.18) ≈ 17 453.29 lux, with the
+reflected-light meter constant K = 12.5 cd·s/m² of a paid standard. The DC-004 relations are
+equivalent to K = 10/0.65 ≈ 15.38 cd·s/m², so the new default has 10/(0.65·12.5) ≈ 1.231 times
+(about 0.30 EV) more light.
+
+The light does not follow your settings. Changing the shutter in manual mode changes the image
+brightness, as on a real camera.
+
+With these defaults, the green RAW level of an 18 % grey card is about 13.1 % of RAW white. A 100 %
+reflector would then sit at about 73 % of white, roughly half a stop below clipping. DC-004 defines
+only the mid-grey reference level, not highlight headroom: this half stop is a property of the
+engine's generic tier presets, documented here, and the tier values were not tuned to get it.
+
+## Scene presets
+
+All charts are analytic patterns written by the engine; no third-party chart data is bundled. Each
+is a flat Lambertian reflector (it looks equally bright from every direction). Neutral reflectances
+are spectrally flat.
+
+| Preset | Parameters (defaults) | Definition |
+| --- | --- | --- |
+| `uniform` | `reflectance` (0.18) | One reflectance or caller spectrum everywhere. |
+| `slanted-edge` | `angleDegrees` (5), `darkReflectance` (0.15), `lightReflectance` (0.6) | An edge through the centre, tilted clockwise from vertical: light where u·cos θ − v·sin θ ≥ 0. The geometry follows the slanted-edge method described by Burns (2000), also used by ISO 12233 (a few degrees of slant, 4:1 contrast by default). |
+| `siemens-star` | `cycles` (36), `radiusFraction` (0.9), `darkReflectance` (0.05), `lightReflectance` (0.8), `backgroundReflectance` (0.18) | Alternating sectors of angular width π/cycles inside radius `radiusFraction` × frame half-height. |
+| `step-wedge` | `steps` (11), `minimumReflectance` (0.03), `maximumReflectance` (0.9), `spacing` (`equal-density`) | Equal-width vertical steps from left to right. Equal density spaces D = −log₁₀ R evenly; `linear` spaces R evenly. |
+| `grey-ramp` | `minimumReflectance` (0.03), `maximumReflectance` (0.9) | Reflectance linear in u, represented by 1024 equal levels. |
+| `checkerboard` | `squaresAcross` (8), `darkReflectance` (0.05), `lightReflectance` (0.8) | Square cells, light at the top-left. |
+| `point-grid` | `columns` (5), `rows` (3), `radius` (0.01), `pointReflectance` (0.9), `backgroundReflectance` (0.02) | Small disks centred in equal cells, for PSF and defocus inspection. |
+| `patches` | `patches` (required), `columns`, `gapFraction` (0.1), `backgroundReflectance` (0.18) | Caller reflectance per patch, row-major. Use it for a ColorChecker-like chart with reflectance data you are entitled to use; the engine does not ship such data because its licence is unclear. |
+
+`resolveChartScene()`, `calculateStepWedgeReflectances()` and `calculatePointGridCenters()` expose
+the same definitions for analysis code. `createPlanarSceneRadianceProvider()` turns any of these
+scenes into a provider for the native environment RAW contract.
+
+Instead of a chart you can pass a function. `{ kind: "reflectance-function", sceneId, evaluate }`
+receives a plane point (`xM`, `yM` in metres, `u`, `v` and `wavelengthNanometers`) and returns a
+reflectance in [0, 1], lit by the facade illuminant. `{ kind: "radiance-function", sceneId, evaluate }`
+returns absolute spectral radiance in W·m⁻²·sr⁻¹·nm⁻¹ and ignores the illuminant.
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const vignette = await simulateCapture({
+  scene: { kind: "reflectance-function", sceneId: "radial-falloff", evaluate: (p) => 0.8 / (1 + p.u * p.u + p.v * p.v) },
+  illuminant: "cie-a",
+  output: { width: 8, height: 8, whiteBalance: "auto" }
+});
+console.log(vignette.request.whiteBalanceState?.source);
+```
+
+## White balance
+
+| Value | Meaning |
+| --- | --- |
+| `"scene-illuminant"` | A custom white balance measured from a perfect white diffuser under the scene illuminant, like a grey-card setting. |
+| `"auto"` | Grey-world auto white balance (AWB) with the body's `neutral-priority` policy, over 2 × 2 block means of the RAW before white balance. The RAW is then rendered again with that setting, which repeats the radiance queries (`diagnostics.providerEvaluationCount` counts one pass). |
+| `"none"` | No white balance; development assumes a D65 adopted white. Scenes under other light keep their colour cast. |
+| `{ kelvin, tint? }` | A colour-temperature setting on the Planckian locus (tint as Duv). |
+| `{ channelGains }` | Manual channel gains. |
+
+## Modelling choices
+
+These choices appear in `assumptions` as `kind: "model"` entries:
+
+- **Sensor colour.** The facade uses an idealized colorimetric sensor. Channel quantum efficiency is
+  a·{x̄, ȳ, z̄}(λ)·555 nm/λ from the engine's own analytic fit of the CIE 1931 colour-matching
+  functions (an approximation; see Colorimetry). The λ factor converts the energy-based functions into a
+  photon-counting response. RAW channels are then proportional to CIE XYZ (the Luther–Ives
+  condition), and the camera matrix is diagonal. No real camera has this response.
+- **Lens.** The tier lens's spectrally flat transmission is used at every f-number and focus in the
+  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; 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.
+- **Demosaic.** Bilinear RGGB interpolation through the existing linear-kernel contract, unless
+  `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; `"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
+  components clipped, then the sRGB transfer function.
+
+## Output formats
+
+`output.format: "png"` writes a PNG with `serializePngImage`: 8- or 16-bit RGB, deterministic
+in-house zlib, and the colour encoding signalled in the file.
+
+| `colorEncoding` | Samples | PNG signalling |
+| --- | --- | --- |
+| `"srgb"` | Exactly the developed sRGB samples (the `srgb-8` / `srgb-16` output). | sRGB chunk (perceptual intent) with its prescribed gAMA/cHRM values |
+| `"display-p3"` | Linear colour converted to Display P3 primaries (W3C CSS Color 4 `display-p3`, D65), sRGB transfer. | cICP 12/13/0/1 |
+| `"rec2020"` | Linear colour converted to ITU-R BT.2020 primaries, BT.2020 OETF (the BT.709 curve). | cICP 9/1/0/1 |
+
+The BT.2100 PQ and HLG encodings are not part of 2.0: their patent holders offer only
+licence-on-request declarations (see the patent review in `THIRD_PARTY.md`).
+
+What is converted, and where:
+
+- The sRGB output path develops each pixel to linear sRGB/D65. That covers demosaic, a per-site clip
+  at the RAW white level, white balance, highlight mode, the camera→XYZ matrix and the XYZ→sRGB
+  matrix. It then clips each component to [0, 1].
+- The wide-gamut encodings use the same development operator but stop before that clip. So
+  colours outside sRGB survive, as negative or above-one sRGB components.
+- They convert that linear colour back to CIE XYZ and on to the target primaries (matrices from the
+  primaries and the D65 white, as in W3C CSS Color 4; see [Colorimetry](https://github.com/Photivra/photivra/blob/main/docs/COLORIMETRY.md)).
+- Gamut mapping then happens only once, in the target space. Components are clipped to [0, 1] for
+  Display P3 and Rec. 2020.
+- No perceptual gamut compression is applied by default (see `output.gamutMapping` below).
+- Tone curves other than `identity` are sRGB-only, and are refused with a wide-gamut encoding.
+
+- RAW white maps to display white. For extended range, merge a bracket with
+  `createHdrBracketMergeTask` (see [PROCESSING.md](https://github.com/Photivra/photivra/blob/main/docs/PROCESSING.md)).
+- No mDCV or cLLI metadata is written.
+- With the facade's colorimetric sensor, the wide-gamut colours are exact up to the spectral
+  quadrature (numerical integration over wavelength). With 5 nm spectral steps, a test reproduces an
+  out-of-sRGB green emitter's CIE 1931 xy chromaticity to within 0.004.
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const wide = await simulateCapture({
+  scene: { preset: "checkerboard" },
+  output: { width: 8, height: 8, format: "png", colorEncoding: "display-p3", bitDepth: 16 }
+});
+console.log(wide.image.colorEncoding, wide.image.png?.length, wide.diagnostics.rendering.gamutClippedLowSampleCount);
+
+const rec2020 = await simulateCapture({ scene: { preset: "uniform" }, output: { width: 4, height: 4, format: "png", colorEncoding: "rec2020", bitDepth: 16 } });
+console.log(rec2020.image.samples instanceof Uint16Array, rec2020.assumptions.find((a) => a.id === "output.colorEncoding.conversion")?.value);
+```
+
+`output.gamutMapping: "perceptual"` replaces the component clip for the PNG encodings (`srgb`,
+`display-p3`, `rec2020`) with `prepareRgbGamutMapping`:
+
+- CIELAB L* and hue are held.
+- Chroma above 90 % of the gamut-boundary chroma is compressed with a smooth knee that never reaches
+  the boundary (constant-lightness, constant-hue chroma reduction as in W3C CSS Color 4 §14, free; also
+  see Morovič 2008).
+- Hue is kept, whereas a component clip shifts it. The cost: saturated in-gamut colours above the knee
+  lose a little chroma, and CIELAB hue drifts for saturated blues.
+- `"clip"` (the default) leaves the output exactly as before.
+- `diagnostics.gamutMapping` counts the pixels the mapping changed.
+- It cannot be combined with tone curves.
+
+`output.format: "dng"` writes the packed native RAW itself with `serializeNativeRawDng`: a lossless,
+uncompressed 16-bit CFA DNG. `samples` are the developed 8-bit sRGB image and `image.dng` holds the file.
+The DNG states only what the capture has:
+
+| Tags | Source |
+| --- | --- |
+| Codes, CFAPattern, BlackLevel (2 × 2), WhiteLevel | The packed RAW codes, per-site black levels (they must repeat with the CFA tile) and the smallest per-phase effective white code |
+| ActiveArea, DefaultCropOrigin/Size, Orientation | The capture geometry (the demosaic border lies outside the active area) |
+| ColorMatrix1 (D65), ForwardMatrix1, AnalogBalance, AsShotNeutral | The facade's diagonal camera→XYZ profile and the capture's white-balance intent |
+| BaselineExposure | 0: the RAW white level maps to display white, as in the facade's development |
+| NoiseProfile | Each channel's readout regime: conversion gain ÷ digital gain and the combined read noise (Poisson, Gaussian and quantization only) |
+| ImageDescription | States that it is a simulated packed RAW with no linear master or rendering stored |
+
+- Saturation flags of sites whose code is below WhiteLevel have no DNG field. They are counted in the
+  assumptions.
+- `output.dng.capturedAtUtc` adds date tags. Without it, none are written.
+- The file round-trips through `parseDngRawImage` to identical codes and tags.
+- LibRaw 0.22.1 decodes identical codes. (It trims an odd ActiveArea origin to keep its Bayer
+  alignment.)
+- Pillow 12 reads every tag but has no CFA (colour filter array) decoder — for these files, as for any
+  CFA DNG.
+
+```ts
+import { parseDngRawImage, simulateCapture } from "@photivra/engine";
+
+const shot = await simulateCapture({ scene: { preset: "siemens-star" }, output: { width: 8, height: 8, format: "dng" } });
+const dng = parseDngRawImage({ bytes: shot.image.dng! });
+console.log(dng.width, dng.activeArea, dng.whiteLevel, dng.codes.length === shot.raw.codes.length);
+```
+
+## Demosaic
+
+`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:
+
+- `"margin"` (the default) renders the kernel's reach as extra sensor sites around the output: one site
+  for bilinear.
+- `"mirror"` renders exactly the output, and reads reflect-101 mirror images of the missing sites. The
+  engine first checks that every reflected site keeps its CFA colour. Mirror saves the radiance work for
+  the border, so small captures need no extra sites. Its edge pixels use mirrored neighbours rather than
+  rendered ones.
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const mirrored = await simulateCapture({
+  scene: { preset: "slanted-edge" },
+  output: { width: 8, height: 8, demosaic: "bilinear", borderHandling: "mirror" }
+});
+console.log(mirrored.plan.exposure.geometry.nativeRaster, mirrored.request.development.borderHandling);
+```
+
+## Optics
+
+The optics options feed only what the environment site contract accepts:
+
+- `lens.projection` and `lens.distortion` become the site's `lensFieldMapping`.
+  - Each sensor point is inverse-distorted, unprojected with the chosen ideal projection, and only then
+    turned into a scene ray.
+  - Irradiance is multiplied exactly once by the distortion area factor 1/det(J), where J is the
+    Jacobian of the mapping.
+  - At finite focus, a non-rectilinear projection is scaled by the thin-lens image distance (an
+    approximation).
+  - The chart is still sized with the rectilinear scale, so its edges move with the projection.
+  - Neither option can be combined with `lens.pupilSampling`, because ideal pupil rays assume the
+    rectilinear, distortion-free projection.
+- `lens.vignetting` becomes radial-illumination-vignetting field throughput,
+  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
+profiles are yours to supply: the tiers declare no vignetting, distortion or PSF away from their f/4
+reference.
+
+Atmospheric haze and polarizers are not offered, for two reasons:
+
+- The scene-radiance provider contract fixes `volumetricTransportModeled` and `polarizationModeled` to
+  false. Haze airlight added inside the provider would therefore be misdeclared.
+- With unpolarized scene light, a polarizer reduces to a uniform attenuation, with none of its glare or
+  sky effects.
+
+Use `calculateAtmosphericHaze` and the front-of-lens filter contracts directly (see
+[PHYSICS_FOUNDATION.md](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md)).
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const lensy = await simulateCapture({
+  scene: { preset: "point-grid" },
+  sensor: { pixelPitchMicrometers: 50 },
+  lens: {
+    projection: "fisheye-equisolid-angle",
+    distortion: { kind: "radial", profile: { normalizationRadiusMm: 0.5, maximumNormalizedRadius: 1, coefficients: { k1: -0.1, k2: 0, k3: 0 } } },
+    vignetting: { normalizationRadiusMm: 0.5, maximumNormalizedRadius: 1, coefficients: { r2: -0.3, r4: 0, r6: 0 } }
+  },
+  output: { width: 8, height: 8 }
+});
+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
+engine's pitch/yaw/roll convention ([SENSOR_ENVIRONMENT_QUERY.md](https://github.com/Photivra/photivra/blob/main/docs/SENSOR_ENVIRONMENT_QUERY.md)).
+
+- Every scene ray is rotated at each temporal midpoint of the site's exposure window. Motion blur is
+  therefore a midpoint quadrature (an average over sample times).
+- `sensor.temporalSampleCount` defaults to 8 when the camera rotates.
+- A yaw of ω rad/s moves the image by ω·f/pitch pixels per second (f = focal length).
+
+`motion.shutter: "rolling"` derives the exposure schedule from the body's rolling readout declaration,
+with `resolveElectronicRollingShutterExposureSchedule` (line reset/read linkage). A site at normalized
+scan position s integrates over [s·τ, s·τ + T], where τ is the skew and T the exposure time.
+
+- The default skew τ is the tier's full-frame data-readout time, applied unchanged across the simulated
+  frame. It is not scaled to the cropped sensor, because the engine never rescales a declared skew. A
+  small frame therefore shows the skew of a full-sensor readout.
+- Pass `rollingShutterSkewSeconds` to declare τ for the simulated frame yourself.
+- Each site's charge window follows its own exposure window.
+- Combined with rotation, a vertical edge shears by ω·f/pitch·τ pixels from the first row to the last.
+  A test checks this.
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const pan = await simulateCapture({
+  scene: { preset: "slanted-edge", angleDegrees: 0 },
+  motion: { angularVelocityRadPerSec: { yaw: 0.06 }, shutter: "rolling", rollingShutterSkewSeconds: 0.01 },
+  output: { width: 8, height: 8 }
+});
+console.log(pan.assumptions.find((a) => a.id === "sensor.shutter")?.value, pan.exposure.settings.shutterSeconds);
+```
+
+## Performance
+
+Almost all of the cost is engine time per sensor site; the facade itself adds little. Since 2.0, the
+native environment task runs most sites through a lean executor. It skips per-site re-validation that
+is provably redundant, and produces byte-identical output (described in the repository's
+`docs/NATIVE_RAW_AND_PRINT.md`).
+
+Measured on a 4-core Linux host running Node 24 (slanted edge, default settings and sRGB 8-bit output):
+
+| Output | Native sites | Wall time | CPU time | CPU per site |
+| --- | --- | --- | --- | --- |
+| 64 × 64 | 4 356 | 0.6 s | 0.87 s | 0.20 ms |
+| 128 × 128 | 16 900 | 1.6 s | 2.2 s | 0.13 ms |
+| 256 × 256 | 66 564 | 5.7 s | 6.9 s | 0.10 ms |
+| 1000 × 1000 | 1 004 004 | — | about 2 min (extrapolated) | — |
+
+The 1000 × 1000 row is not a measurement. It multiplies the 256 × 256 CPU cost per site by the site
+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);
+```
+
+## Not available
+
+The facade offers no atmospheric haze or polarizer (see [Optics](#optics)), flash, video, HDR brackets
+or processing operators. Those APIs are available directly. Real camera and lens presets are not
+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
+  and Explanation 4).
+- P. D. Burns, "Slanted-Edge MTF for Digital Camera and Scanner Analysis", Proc. IS&T PICS 2000,
+  free at <https://www.imaging.org/common/uploaded%20files/pdfs/Papers/2000/PICS-0-81/1621.pdf>
+  (slanted-edge geometry; also ISO 12233:2017).
+- BIPM, *The International System of Units*, 9th ed. (2019), free at
+  <https://www.bipm.org/en/publications/si-brochure> (K_cd = 683 lm/W, the definition of the candela).
+- BIPM, *Mise en pratique for the definition of the kelvin*, Absolute Primary Radiometry (2018),
+  Eq. (1), free at <https://www.bipm.org/utils/en/pdf/si-mep/MeP-K-2018_Absolute_Primary_Radiometry.pdf>
+  (Planck's law, used for the Planckian and illuminant A spectra). Illuminant A's defining constants
+  and the daylight polynomial come from CIE 015:2018 (paid); computed values are checked against the
+  free CIE datasets at <https://cie.co.at/data-tables> (see [Colorimetry](https://github.com/Photivra/photivra/blob/main/docs/COLORIMETRY.md)).
+- C. Wyman, P.-P. Sloan, P. Shirley, "Simple analytic approximations to the CIE XYZ color matching
+  functions", *Journal of Computer Graphics Techniques* 2(2), 2013 (the piecewise-Gaussian model form;
+  the engine fits its own coefficients to the CIE 1931 data, see Colorimetry).
+- R. Luther, "Aus dem Gebiet der Farbreizmetrik", *Zeitschrift für technische Physik* 8, 1927
+  (the Luther condition for colorimetric cameras).
+- W3C CSS Color Module Level 4 (`srgb` and `display-p3`; RGB↔XYZ matrices from primaries and white),
+  free at <https://www.w3.org/TR/css-color-4/>; ITU-R BT.709-6 and BT.2020-2 (primaries and luminance
+  coefficients), free at <https://www.itu.int/rec/R-REC-BT>; ITU-T H.273 (cICP code points); W3C PNG Specification, Third
+  Edition (2025).
+- Adobe DNG Specification 1.7.1.0 (2023); W3C CSS Color Module Level 4 §14 (free). Also see: J. Morovič,
+  *Color Gamut Mapping*, Wiley 2008, §10.
+- K. Miyamoto, "Fish eye lens", *JOSA* 54, 1964; J. Kannala, S. Brandt, *IEEE TPAMI* 28, 2006
+  (projections); A. E. Conrady, *MNRAS* 79, 1919; D. C. Brown, *Photogrammetric Engineering* 32, 1966
+  (distortion).
+- A. El Gamal, H. Eltoukhy, "CMOS image sensors", *IEEE Circuits and Devices Magazine* 21(3), 2005;
+  C.-K. Liang, L.-W. Chang, H. H. Chen, "Analysis and compensation of rolling shutter effect",
+  *IEEE TIP* 17(8), 2008 (rolling-shutter line timing).