@photivra/engine 2.0.0 → 2.1.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`. |
@@ -85,7 +86,7 @@ modelling choices (such as "no lens PSF") as `kind: "model"`.
 | `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. |
@@ -96,14 +97,16 @@ modelling choices (such as "no lens PSF") as `kind: "model"`.
 | `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).)
 
@@ -217,14 +220,14 @@ 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.
 - **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 +326,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 +382,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 +433,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 +545,78 @@ 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);
+```
+
 ## Not available
 
 The facade offers no atmospheric haze or polarizer (see [Optics](#optics)), flash, video, HDR brackets
@@ -462,6 +625,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/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.1.0" as const
 ```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.0.0",
-  "engineApiVersion": "2.0.0",
+  "packageVersion": "2.1.0",
+  "engineApiVersion": "2.1.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",
@@ -7692,6 +7722,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 +7757,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 +7802,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",

package/docs/api/facade-simulate-capture.md

@@ -2,6 +2,18 @@
 
 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.
 
+## SIMULATE_CAPTURE_COST_OPTIONS
+
+Options reported in `diagnostics.options` (2.1), in this order, when they ran: the ones that change how much work
+a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.temporalSampleCount` a count above 1.
+
+```ts
+SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
+  "lens.diffraction", "sensor.antiAliasing", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror",
+  "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
+  "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
+```
+
 ## SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX
 
 Default illuminance, lux: an 18 % Lambertian grey card (L = 0.18·E/π) then gets exactly the CIPA DC-004 standard
@@ -70,12 +82,22 @@ PQ and HLG (BT.2100) are not part of 2.0; see THIRD_PARTY.md.
 export type SimulateCaptureColorEncoding = "srgb" | "display-p3" | "rec2020";
 ```
 
+## SimulateCaptureCostOption
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureCostOption = typeof SIMULATE_CAPTURE_COST_OPTIONS[number];
+```
+
 ## SimulateCaptureDemosaic
 
-Built-in Bayer demosaic kernels (`createBuiltInBayerDemosaicProfiles`).
+Demosaic. `bilinear`: the built-in Bayer kernels (`createBuiltInBayerDemosaicProfiles`). `ahd` (2.1): adaptive
+homogeneity-directed demosaicing (`createAhdDemosaicTask`, after Hirakawa & Parks 2005), a non-linear
+edge-directed method that reduces zipper and false colour on sharp edges.
 
 ```ts
-export type SimulateCaptureDemosaic = "bilinear";
+export type SimulateCaptureDemosaic = "bilinear" | "ahd";
 ```
 
 ## SimulateCaptureExposureMode
@@ -139,6 +161,13 @@ export interface SimulateCaptureOptions {
      * focus must equal the resolved capture settings exactly. Not combinable with pupilSampling.
      */
     psf?: Extract<CalculateEnvironmentSensorPhotoSignalInput["psf"], { kind: "sampled-local" }>;
+    /**
+     * Opt-in (2.1) diffraction blur of an ideal, aberration-free, in-focus lens with a circular pupil at the
+     * capture's resolved f-number: the engine builds the Airy kernels (`createDiffractionLimitedPsfProfile`)
+     * on the site pitch. `kernelRadiusSamples` (0–32) sets the kernel window; default: the third dark ring at
+     * the longest spectral node. Not combinable with `psf` or `pupilSampling`. Default off.
+     */
+    diffraction?: SimulateCaptureLensDiffraction;
   };
   exposure?: {
     /** Default "manual". */
@@ -201,6 +230,11 @@ export interface SimulateCaptureOptions {
     temporalSampleCount?: number;
     /** Noise seed (uint32). Default 1. */
     noiseSeed?: number;
+    /**
+     * Opt-in (2.1) optical anti-aliasing filter (birefringent point splitting, `SimulateCaptureSensorAntiAliasing`).
+     * Multiplies the scene queries by the number of split points. Default off (the tiers declare no filter).
+     */
+    antiAliasing?: SimulateCaptureSensorAntiAliasing;
   };
   /** Aborting cancels the running task; the promise rejects with a domain error and returns no partial image. */
   signal?: AbortSignal;
@@ -262,6 +296,14 @@ export interface SimulateCaptureResult {
     siteInput(nativeIndex: number): SimulateEnvironmentSensorRawFrameInput["sites"][number];
     development: Omit<NativeRawDevelopmentInput, "raw">;
     whiteBalanceState: ResolvedWhiteBalanceState | null;
+    /**
+     * Present with lens.diffraction (2.1): the engine-built Airy profile, the equivalent environment sampled PSF
+     * selection, and how it was applied. With `object-space-convolution` the site inputs declare no PSF and the
+     * provider answers with the PSF-convolved radiance; putting `psf` into each site input and using the plain
+     * scene provider gives the same expected signal (to float rounding) through the per-tap environment quadrature.
+     */
+    diffraction?: { profile: DiffractionLimitedPsfProfile; psf: Extract<CalculateEnvironmentSensorPhotoSignalInput["psf"], { kind: "sampled-local" }>;
+      execution: "object-space-convolution" | "environment-psf-quadrature" };
   };
   exposure: {
     mode: SimulateCaptureExposureMode;
@@ -295,7 +337,20 @@ export interface SimulateCaptureResult {
     rendering: SdrRenderingResult["diagnostics"];
     /** Present with output.gamutMapping "perceptual": pixels whose chroma or lightness the mapping changed. */
     gamutMapping?: { method: "cielab-hue-preserving-chroma-compression"; kneeFraction: number; adjustedPixelCount: number; lightnessClippedPixelCount: number };
-    timingsMs: { raw: number; whiteBalance: number; development: number; jpeg: number; total: number };
+    /**
+     * Wall-clock milliseconds per stage. `raw`, `whiteBalance` (the second RAW pass of auto white balance), `development`
+     * (includes DNG writing), `jpeg` and `total` are whole milliseconds (`Date.now()`). Since 2.1, where a stage ran:
+     * `diffraction` (the object-space convolution of `lens.diffraction`; part of `raw` and `whiteBalance`), `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 vary from run to run and never enter any digest or output byte.
+     */
+    timingsMs: { raw: number; whiteBalance: number; development: number; jpeg: number; total: number; diffraction?: number; demosaic?: number; encode?: number };
+    /**
+     * 2.1: the opt-in options that changed the work of this run, in a fixed order (see `SIMULATE_CAPTURE_COST_OPTIONS`).
+     * Empty for a capture with every default. With `timingsMs` it lets an application measure each option's cost on
+     * the user's device.
+     */
+    options: readonly SimulateCaptureCostOption[];
   };
   provenance: {
     scientificStatus: "approximation";
@@ -310,6 +365,24 @@ export interface SimulateCaptureResult {
 }
 ```
 
+## SimulateCaptureSensorAntiAliasing
+
+Optical anti-aliasing (low-pass) filter (2.1), modelled as birefringent point splitting: each image point is
+split into equally bright copies (the engine's `normalized-point-splitting-kernel` optical-stack response).
+- `four-spot`: two crossed birefringent plates; copies at (±d/2, ±d/2), weight 1/4 each, MTF |cos(π·f_x·d)·cos(π·f_y·d)|.
+- `two-spot`: one plate splitting along `axis`; copies at ±d/2, weight 1/2 each, MTF |cos(π·f·d)|.
+- `point-splitting`: the engine contract itself, offsets in micrometres (+x right, +y down) and positive weights
+  summing to 1 (at most 16 components, each within 4 sites).
+d = `separationSites` × pixel pitch, 0 < separationSites ≤ 4, default 1 (first MTF zero at the sensor's Nyquist
+frequency 1/(2·pitch)).
+
+```ts
+export type SimulateCaptureSensorAntiAliasing =
+  | { kind: "four-spot"; separationSites?: number }
+  | { kind: "two-spot"; axis: "horizontal" | "vertical"; separationSites?: number }
+  | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[] };
+```
+
 ## SimulateCaptureWhiteBalance
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.

package/docs/api/optics-diffraction-psf-profile.md

@@ -0,0 +1,96 @@
+# optics/diffraction-psf-profile.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.
+
+## createDiffractionLimitedPsfProfile
+
+Creates a sampled lens PSF profile for an ideal diffraction-limited lens with a circular pupil: one
+unit-sum Airy kernel per wavelength on one shared (2R+1)² grid, with the truncated energy reported per
+wavelength. The profile declares the given focal length, f-number and focus exactly, and the field axes
+±`fieldHalfExtentMm` with the same kernel at every field node.
+
+```ts
+export function createDiffractionLimitedPsfProfile(input: CreateDiffractionLimitedPsfProfileInput): CalculationResult<DiffractionLimitedPsfProfile>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateDiffractionLimitedPsfProfileInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateDiffractionLimitedPsfProfileInput {
+  /** Only `circular` in 2.1.0 (polygon pupils: `calculateIdealPolygonDiffractionPsf` gives point densities). */
+  aperture: "circular";
+  focalLengthMm: number;
+  apertureFNumber: number;
+  focus: FocusPlane;
+  /** Strictly increasing wavelengths, nm, in the medium of propagation (no air/vacuum conversion is applied). 1–64. */
+  wavelengthsNm: readonly number[];
+  /** Square sample pitch of every kernel, µm. */
+  samplePitchMicrometers: number;
+  /** Kernel half-width in samples; each kernel is (2R + 1)². 0–32. */
+  kernelRadiusSamples: number;
+  /** Half-extent of the image field over which the on-axis PSF is declared (profile field axes ±x, ±y), mm. */
+  fieldHalfExtentMm: { x: number; y: number };
+  profileId: string;
+}
+```
+
+## DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS
+
+Input limits: at most 64 wavelengths, kernel radius 0–32 samples (the irradiance-convolution limit).
+
+```ts
+DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS = Object.freeze({ maximumWavelengths: 64, maximumKernelRadiusSamples: 32 })
+```
+
+## DIFFRACTION_LIMITED_PSF_PROFILE_MODEL
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+DIFFRACTION_LIMITED_PSF_PROFILE_MODEL = Object.freeze({
+  modelId: "photivra-diffraction-limited-circular-pupil-psf" as const, modelVersion: "1.0.0" as const })
+```
+
+## DiffractionLimitedPsfProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DiffractionLimitedPsfProfile {
+  profile: LensSampledPsfProfile;
+  model: typeof DIFFRACTION_LIMITED_PSF_PROFILE_MODEL;
+  pupilDiameterMm: number;
+  pupilToImageDistanceMm: number;
+  workingFNumber: number;
+  kernelRadiusSamples: number;
+  samplePitchMicrometers: number;
+  wavelengths: readonly DiffractionLimitedPsfWavelength[];
+  /** Largest truncated energy over the wavelengths. */
+  maximumTruncatedEnergyFraction: number;
+  quadrature: { method: "polar-frequency-domain-trapezoid-gauss-legendre"; maximumRadialNodes: number; maximumAngularNodes: number };
+}
+```
+
+## DiffractionLimitedPsfWavelength
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DiffractionLimitedPsfWavelength {
+  wavelengthNm: number;
+  /** f_c = 1/(λ·N_w), cycles per µm. */
+  cutoffFrequencyCyclesPerMicrometer: number;
+  /** 1.21967·λ·N_w, µm. */
+  firstZeroRadiusMicrometers: number;
+  /** Σ of the cell energies inside the window before renormalization (of a total of 1). */
+  capturedEnergyFraction: number;
+  /** 1 − capturedEnergyFraction: the Airy tail energy outside the window, put back by renormalization. */
+  truncatedEnergyFraction: number;
+  /** Fraction of the renormalized kernel in the centre sample. */
+  centreSampleFraction: number;
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",
@@ -35,7 +35,8 @@
     "dist/schema",
     "dist/sensor",
     "dist/simulation",
-    "dist/stabilization","dist/processing",
+    "dist/stabilization",
+    "dist/processing",
     "!dist/capture/browser-native-reference-*",
     "!dist/schema/camera.js",
     "!dist/schema/camera.js.map",