@photivra/engine 2.19.0 → 2.20.0

package/docs/QUICK_START.md

@@ -48,6 +48,7 @@ the example above is [simulate-capture.mjs](examples/simulate-capture.mjs).
 | `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` |
+| `sensor` | 2.20 (#555, #535): the sensor characteristics used (pitch, peak QE, full well, read noise of each conversion gain and the dual-gain switch ISO, readout time, ADC bit depth, fixed-pattern noise), the calculated dynamic range (`dynamicRangeStops`, and per ISO setting) and, on exact requests, the mid-gray noise figure (`midGrey`); see [Sensor characteristics](#sensor-characteristics-555) |
 | `exposure` | Mode, resolved settings, EV100, `isoControl` (`"manual"` or `"automatic"`) and, with `iso: "auto"`, `autoIso` (how the ISO was chosen and what limited it), metered scene luminance, the deviation from the standard exposure in stops (`standardExposureDeviationStops`), the illuminance at which the settings give the standard exposure (`standardExposureIlluminanceLux`), from 2.14 the deviation from the standard exposure of an 18 % grey card under the scene's illuminance (`greyCardDeviationStops`, incident metering) 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) |
@@ -206,11 +207,13 @@ and every number is a labelled approximation.
   for the macro); an f-number or distance outside the lens's range is refused.
 - **Its character is rendered:** a field- and wavelength-dependent PSF (diffraction with the lens's Seidel aberrations, axial and
   lateral colour) through the environment PSF quadrature, its radial distortion, its vignetting and, for the fisheyes, the
-  equisolid projection (beyond 90° there is no scene, so the 8 mm's circle is black outside). Flare, focus breathing and the bokeh
-  shape are reported in the assumption `lens.catalogue.character`, not rendered.
+  equisolid projection (beyond 90° there is no scene, so the 8 mm's circle is black outside). Flare and focus breathing are
+  reported in the assumption `lens.catalogue.character`, not rendered.
 - **Professional lenses are better** where the owner's table says so: sharper centres and corners, less coma, lateral colour,
   distortion and vignetting, better close focus and focus consistency. The measurements are in the catalogue page.
-- **Combinations:** `lens.defocus` convolves the disc into the lens's PSF (a combined kernel up to 16 sites in radius);
+- **Combinations:** `lens.defocus` convolves the lens's own bokeh kernel (#567: its blades, its W040 and, on the fast wides
+  and normals, a cat's eye, which is lens.catalogue's exact method: on when the request resolves to exact (`fast: false`, the
+  default for DNG, JPEG and PNG), off on fast requests, since it would slow the fast method 2–3.5×; [Bokeh](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md#bokeh-567)) into the lens's PSF (a combined kernel up to 16 sites in radius);
   `lens.focusScatter: { seed, shotIndex? }` moves the focus by a seeded autofocus error (`simulateGenericLensFocusError`), off
   by default. `prime`, `focalLengthMm`, `projection`, `distortion`, `vignetting`, `psf`, `diffraction` and `pupilSampling` are
   set by the lens and refused with it. The display view renders `lens.catalogue` since #569, with the PSF taken per field zone
@@ -460,6 +463,73 @@ large-pixel sensor may therefore saturate earlier, and a real small-pixel sensor
 given a higher base ISO. When the pitch is not 6 µm, the assumption `sensor.isoAreaNormalization`
 records the area ratio and this approximation.
 
+### Sensor characteristics (#555)
+
+Each characteristic of the body's sensor can be set on its own under `sensor`. All are off by
+default: a request that sets none is byte-identical to 2.19.0, and every value set is listed in the
+assumption `sensor.characteristics`. The figures under the result's `sensor` are calculated from
+them; they are results, not settings.
+
+```ts
+const r = await simulateCapture({ scene: { preset: "uniform" }, sensor: {
+  pixelPitchMicrometers: 4,
+  peakQuantumEfficiency: 0.8,                       // green EQE at 555 nm, 0.05–0.9 (default 0.5)
+  fullWell: { electrons: 50_000, link: "none" },    // or linked to pixel area (the default)
+  readNoise: { lowGainElectrons: 3, highGainElectrons: 1.2, highGainFromIso: 640 },
+  readoutSeconds: 0.012,                            // rolling-shutter skew
+  adcBitDepth: 16,                                  // 12, 14 or 16
+  fixedPatternNoise: true                           // the body's synthetic pattern (advanced)
+}, fast: false });                                  // fast: false computes the mid-gray noise figure
+r.sensor.dynamicRangeStops; r.sensor.midGrey?.snrDecibels;
+```
+
+| Option | Range | Default | Effect |
+| --- | --- | --- | --- |
+| `peakQuantumEfficiency` | 0.05–0.9 | 0.5 | Multiplies every channel's EQE curve by value / 0.5: the curves keep their shape and the colour matrix, and the collected charge scales in proportion. 0.9 keeps the blue channel's peak below 1. |
+| `fullWell` | 100–1e10 e⁻ at the pitch | the body's base-ISO saturation at 6 µm, × pitch²/36 µm² | The charge at the RAW white level at base ISO (the saturation capacity of EMVA 1288 Release 4.0). `link: "pixel-area"` (default) scales `electrons`, the full well at `referencePixelPitchMicrometers` (default 6), by (pitch / reference)²; `link: "none"` uses it at any pitch. |
+| `readNoise` | 0–100 e⁻; switch ISO 100–1e7 | the body's (tiers: 2/1.1, 3/1.4 and 6/2.5 e⁻, switch at ISO 800) | Read noise of the low and the high conversion gain, and `highGainFromIso`, the ISO from which the high gain is used. A switch above the body's top ISO keeps the low gain throughout. |
+| `readoutSeconds` | 1e-6–1 s | the body's (8, 15, 30 ms) | The rolling shutter's top-to-bottom skew (`motion.shutter: "rolling"`; `motion.rollingShutterSkewSeconds` still overrides it). |
+| `adcBitDepth` | 12, 14, 16 | the body's (consumer 12, others 14) | The black level scales by 2^Δbits (1 024 at 14 bits → 4 096 at 16), the saturation code is 2^bits − 1 and the conversion gain follows, so the same charge reaches the same fraction of the code range. A 16-bit RAW writes a 16-bit DNG with white level 65 535. |
+| `fixedPatternNoise` | `true`/`false` | `false` | The body's synthetic fixed-pattern profile (PRNU, DSNU, hot pixels, row and column offsets), the same pattern in every capture. Not available in `simulateDisplayView`, which refuses it. |
+
+How the full well and the ISO rating interact (an approximation, recorded in the assumption): the
+facade keeps each ISO setting's readout regime, so the full well is reached at the white level of
+base ISO and every regime's conversion gain and pre-ADC saturation scale with it (`chargeScale`).
+The output per unit focal-plane exposure H then changes by 2^`sensitivityOffsetStops` =
+QE scale × (pixel area / 36 µm²) × (body full well / full well): the body's rating S = 10/H (CIPA
+DC-004-2020 §3.2) still holds only when that is 1, as it is for a linked full well and the default
+QE. A higher QE makes the same exposure brighter; a larger unlinked full well makes it darker and
+gives more highlight headroom. The high conversion gain's smaller charge storage is not modelled
+when the switch ISO is lowered. The assumption notes a full well outside 200–10 000 e⁻ per µm² of
+pixel area as unusual for the pitch; that is a design range around the tiers' 556–1 667 e⁻/µm² and
+published values such as about 4 000 e⁻/µm² at 2 µm and 1 400 e⁻/µm² at 5.2 µm (Farrell, Xiao &
+Kavusi, *Proc. SPIE* 6069, 2006, Table 1), not a published bound.
+
+**Dynamic range** (`sensor.dynamicRangeStops` at the capture's ISO, `sensor.dynamicRangeByIso` for
+every ISO setting of the body): engineering dynamic range log₂(S_sat / σ_floor). S_sat is the charge
+at the RAW white level (the full well over the analog gain, limited by the charge capacity and the
+ADC range) and σ_floor = √(σ_read² + σ_q²), the temporal dark noise of EMVA 1288 Release 4.0 without
+dark current, with σ_q the ADC quantization (1/12 code², plus 1/12 code² of rounding after a digital
+gain) in electrons. With no read noise the range is limited by the ADC alone: log₂((white − black)·√12).
+The Professional tier gives 14.7 stops at ISO 100, 12.7 at ISO 800 (high gain) and 9.7 at ISO 6400;
+the Consumer tier 11.7, 10.0 and 7.0.
+
+**Noise figure** (#535, `sensor.midGrey`): computed only when the request resolves to exact (`fast:
+false`, the default for DNG, JPEG and PNG exports; about 0.3 ms); a fast request (the sRGB default)
+omits it. The expected signal-to-noise ratio of an 18 % Lambertian
+gray patch under the request's illuminant and illuminance, at the capture's exposure, ISO and
+sensor, from the engine's own noise model (a model figure, not a measurement). It is the green
+channel next to the optical axis (no vignetting, PSF or motion). `signalElectrons` S is the patch's
+expected charge; `noiseElectrons` splits the noise into photon shot √S, read, dark-current shot
+√(D·t) with D = 1 e⁻/s, ADC quantization and, with `fixedPatternNoise`, the fixed pattern
+√((PRNU·S)² + (DSNU·D·t)² + row² + column²) (hot pixels excluded; a spatial noise, the same in every
+capture), added in quadrature as `total`. `snr` = S / total and `snrDecibels` = 20·log₁₀(snr).
+`clipped` is true when the patch reaches the white level, where the figure no longer describes
+the image. With the defaults (Professional, f/8, 1/125 s, ISO 100, 21 481 lux) S ≈ 7 842 e⁻ and the
+SNR is 88.5 (38.9 dB); at ISO 6400 with 1/64 of the light, S ≈ 123 e⁻ and the SNR is 11.0 (20.8 dB):
+the photon shot noise grows as √S, so less light means more noise whatever the ISO. The display view
+reports the same `sensor` record as its capture.
+
 ## Exposure
 
 The facade meters the scene like a reflected-light meter:
@@ -1093,6 +1163,18 @@ The optics options feed only what the environment site contract accepts:
     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.
+  - Ties on chart boundaries (2.20.0, #565): the per-tap quadrature reads each tap's scene point at its site-lattice point, as
+    the object-space convolution, the out-of-focus capture and the display view do, so a tap exactly on a chart boundary (a
+    Siemens star's spokes through lattice points) resolves to the same material on every path. With camera rotation under
+    `motion.shutter: "rolling"` every row has its own instants, so the lattice is read once per instant; there reading the
+    lattice is `lens.diffraction`'s exact method and keeping each tap's own point its fast method; the lattice costs about
+    1.2× the time (dead leaves 48 × 32 at f/8: 4.0–4.1 s against 4.8–5.0 s; a Siemens star 32 × 24 at f/16: 6.8 s against
+    8.1–8.2 s; November 9, 2026, Apple M5 Pro, Node 24.19.0). The format default decides (2.20.0): fast for sRGB samples, exact for
+    DNG, JPEG and PNG; `lens.diffraction: { kind, fast }` or the top-level `fast` wins, and the fast method reports
+    `diagnostics.fast.applied["lens.diffraction"]: true` and the assumption `fast.lens.diffraction`. The two readings differ
+    only at such ties. Region renders joined into one frame (`serializeSimulatedCaptureDngFromParts`,
+    `simulateCaptureFromParts`) match the whole-frame render only if every part resolves `fast` the same way: give the parts
+    and the whole request the same `fast` (a part rendered fast is refused by an exact join).
   - The convolution runs in 32-row bands and computes only each band's own values, not the 2R rows and
     columns of padding around it (#419; the values are bit-identical to the full-grid convolution's). On a
     function scene with the Quality options at 1 µm and f/16 (R 32), 96 × 72, `diagnostics.timingsMs.diffraction`
@@ -1423,9 +1505,9 @@ lens: { focalLengthMm: 50, fNumber: 4, focusDistanceM: 1.4, defocus: { model: "g
   combined with `lens.diffraction` (every zone would need its own combined kernel per node). Above a kernel radius of 64
   sites it is refused: #564's run convolution takes one kernel per request, and extending it to one kernel per zone is left
   for later. `simulateDisplayView` and `prepareDisplayView` refuse it; they render `blades` and `sphericalAberration`.
-- **With `lens.catalogue` (#549)** the three options are refused by name. The catalogue lens folds a plain disc into its
-  own PSF, so they would otherwise be dropped. Feeding a catalogue lens's spherical aberration and character into the
-  bokeh kernel is a follow-up ([#567](https://github.com/Photivra/photivra/issues/567)), not a 2.17.0 feature.
+- **With `lens.catalogue` (#549)** the three options are refused by name: since 2.20.0 (#567) the catalogue lens sets
+  all three itself (its blades, its own W040 and, on the fast wides and normals, a cat's eye) and folds that kernel into
+  its PSF ([Lens catalogue, Bokeh](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md#bokeh-567)).
 - **Sampling.** Without spherical aberration each site's weight is the exact area of the projected open pupil (a convex
   polygon; circles and blade arcs are 1024-gons scaled to their true area, within 5e-6 of the radius of the true curve)
   inside the site's cell, divided by its area (`"exact-polygon-cell-area"`). With it the pupil is sampled on a square grid

package/docs/USAGE.md

@@ -7147,6 +7147,7 @@ See [Print planning](https://github.com/Photivra/photivra/blob/main/docs/PRINT_P
 
 - `calculatePrintPlan()` says whether the native sampling is enough, and gives a compatible minimum file raster.
 - `calculatePrintSizeLimit()` distinguishes finite, unbounded and unavailable sampling limits.
+- `calculatePrintSizeLimitWithBlurAndNoise()` (2.20.0) gives the largest print at a viewing distance that still looks sharp and clean, counting blur and noise as well as pixels, and names the limiting factor ([Print size limit with blur and noise](https://github.com/Photivra/photivra/blob/main/docs/PRINT_PLANNING.md#print-size-limit-with-blur-and-noise)). An approximation.
 - Print quality and delivery are not assessed.
 
 The [regional Print detail diagnostic](https://github.com/Photivra/photivra/blob/main/docs/PRINT_DETAIL_ASSESSMENT.md) measures one declared, coherent sinusoidal fundamental in a selected linear-luminance ROI, and records the exact pipeline stage it measured. Its [validation protocol](https://github.com/Photivra/photivra/blob/main/docs/PRINT_DETAIL_VALIDATION.md) and [capability ledger](https://github.com/Photivra/photivra/blob/main/docs/validation/print-detail-capabilities.json) separate mathematical conformance from the still-blocked qualification of acquired images, renderers and perceived quality.
@@ -7516,10 +7517,12 @@ console.log(calculateGeometricFocusBreathing({
 `GENERIC_LENS_CATALOGUE` lists the engine's 30 generic primes (17 professional, 13 consumer, "PV 50 1.2 Pro", "PV 50 1.8"; Photivra's
 own designs, not real products). `resolveGenericLens` resolves one for a sensor, an f-number and a focus distance: its focal length
 (scaled by the crop factor), aperture range, close focus, projection and its character, Seidel aberrations, axial and lateral
-colour, distortion and vignetting profiles, flare, breathing and focus scatter, each a labelled approximation.
+colour, distortion and vignetting profiles, flare, breathing, focus scatter and its bokeh (`character.bokeh`, #567: the options of
+`lens.defocus` and `calculateDefocusBokehKernel`), each a labelled approximation.
 `simulateGenericLensFocusError` draws a seeded autofocus error; `createGenericLensCorrectionProfile` builds the lens's generic
 correction profile for `resolveLensCorrectionPlan`, which `simulateCapture` applies to its developed image with
-`output.lensCorrections` (#570; never to the RAW or the DNG). `simulateCapture` renders a catalogue lens with `lens.catalogue`
+`output.lensCorrections` (#570; never to the RAW or the DNG), and which a DNG can carry for RAW editors as optional DNG opcodes with
+`output.dng.lensCorrectionOpcodes` (#587; the RAW codes unchanged). `simulateCapture` renders a catalogue lens with `lens.catalogue`
 ([quick start](QUICK_START.md#generic-lens-catalogue-549)); `fast: true` (or `lens: { catalogue: { kind, fast: true } }`) takes its
 fast method (#568), a labeled approximation that blends the PSF over a field grid, for interactive captures. Equations, tables and the
 chart measurements: [LENS_CATALOGUE.md](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md).
@@ -8085,3 +8088,63 @@ console.log(share.print?.blurOnPrintMm); // 0.25 mm on the print
 - Equal shares of the frame diagonal look the same when images are shown at the same size. `calculateBlurShareOfFrame()` does not judge whether a blur is visible.
 
 See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#sensor-equivalence-f-number-area-and-blur-share).
+
+## Aperture diameter and cropping to match a longer lens
+
+`calculateApertureDiameter()` gives the entrance-pupil diameter in millimetres, focal length ÷ f-number (exact by the definition of the f-number, ideal lens focused at infinity). `calculateCropToMatchFocalLength()` gives the centred crop that makes an image from a shorter lens match a longer lens's framing from the same position, and the pixels it leaves:
+
+```ts
+import { calculateApertureDiameter, calculateCropToMatchFocalLength } from "@photivra/engine";
+
+console.log(calculateApertureDiameter({ focalLengthMm: 50, fNumber: 2 }).value.entrancePupilDiameterMm); // 25
+console.log(calculateApertureDiameter({ focalLengthMm: 50, fNumber: 4 }).value.entrancePupilDiameterMm); // 12.5
+
+const crop = calculateCropToMatchFocalLength({
+  focalLengthMm: 50,
+  targetFocalLengthMm: 100,
+  pixelWidth: 6000,
+  pixelHeight: 4000
+}).value;
+
+console.log(crop.cropFactor); // 2
+console.log(crop.pixelWidth, crop.pixelHeight); // 3000 2000
+console.log(crop.megapixels, crop.sourceMegapixels); // 6 24
+```
+
+- The aperture diameter is the entrance pupil (the aperture stop seen from the front of the lens), not the diaphragm's opening. Close focus (working f-number `N·(1 + m/P)`, pupil magnification `P`) is not modelled.
+- The crop factor `target ÷ focal length` is exact for ideal rectilinear lenses focused at infinity; at close focus the matching factor is larger, `F·(d − f)/(f·(d − F))` at object distance `d` (thin lens), which is not applied. The crop is `calculateCenteredCrop()`'s (aspect ratio kept to whole pixels), and `targetFocalLengthMm` must be at least `focalLengthMm`.
+
+See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#aperture-entrance-pupil-diameter).
+
+## Which limits detail: the lens or the sensor
+
+`calculateDetailLimit()` (model `detail-limit` 1.0.0, #575) answers "would a sharper lens or a denser sensor help?" for given settings. It returns the optics' resolution (MTF50 in cycles/mm, from diffraction, the lens's aberrations and any defocus), the sampling's (the Nyquist frequency 1/(2p) and, with a Bayer filter, the red and blue sites' 1/(4p)), the system MTF50, and which one limits:
+
+```ts
+import { calculateDetailLimit } from "@photivra/engine";
+
+const sensor = { widthMm: 36, heightMm: 24, pixelWidth: 6000 }; // 6 µm pixels
+
+const stoppedDown = calculateDetailLimit({ sensor, lens: { kind: "ideal", focalLengthMm: 50 }, fNumber: 22 }).value;
+console.log(stoppedDown.limitedBy, stoppedDown.limitingFactor); // "lens" "diffraction"
+console.log(stoppedDown.optics.mtf50CyclesPerMm); // ≈ 33.4, against a Nyquist frequency of ≈ 83.3
+console.log(stoppedDown.diffractionLimitedFNumber); // ≈ 8.8: from here on diffraction limits on this sensor
+
+const wideOpen = calculateDetailLimit({ sensor, lens: { kind: "catalogue", lensId: "pv-50-1.2-pro" }, fNumber: 4 }).value;
+console.log(wideOpen.limitedBy, wideOpen.limitingFactor); // "sensor" "pixel-pitch"
+
+const outOfFocus = calculateDetailLimit({
+  sensor,
+  lens: { kind: "ideal", focalLengthMm: 50 },
+  fNumber: 2,
+  focus: { focusDistanceM: 3, subjectDistanceM: 2.5 }
+}).value;
+console.log(outOfFocus.limitingFactor); // "defocus"
+```
+
+- The sensor limits when the optics still pass 50 % contrast at the Nyquist frequency (`opticsToNyquistRatio ≥ 1`): a denser sensor would record finer detail. Otherwise the lens limits, through `"diffraction"` when its RMS wavefront error is within λ/14 (the Maréchal criterion), else `"aberrations"` or `"defocus"`, whichever is larger. This rule is an approximation; the MTF values are the exact scalar OTF of the stated wavefront at one wavelength (550 nm unless `wavelengthNm` is given).
+- `lens.catalogue` lenses use their generic Seidel aberrations at `fieldPosition` (0 the center, 1 the corner), so corners are softer; `lens.ideal` has none.
+- Tangential and sagittal MTF50 are both reported; the decision uses the lower one.
+- Demosaicing, sharpening, noise and motion are not included.
+
+See [Physics Foundation](https://github.com/Photivra/photivra/blob/main/docs/PHYSICS_FOUNDATION.md#which-limits-detail-the-lens-or-the-sensor).

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

@@ -82,5 +82,11 @@ export interface SerializeNativeRawDngInput {
   capturedAtUtc?: string;
   /** Optional (2.4) caller text: description, software, copyright, comment (see the module notes). If omitted, no text is added. */
   textMetadata?: OutputTextMetadata;
+  /**
+   * Optional (#587) OpcodeList3 (tag 51022) bytes, for example `createDngLensCorrectionOpcodes(...).opcodeList3`: a big-endian DNG
+   * opcode list (DNG 1.3.0.0+, "Opcode List Processing") that readers apply to the demosaiced stage-3 image. Only its framing is
+   * checked (count, per-opcode headers and parameter sizes filling the bytes exactly). The RAW codes are unchanged. If omitted, no tag.
+   */
+  opcodeList3?: Uint8Array;
 }
 ```

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.19.0" as const
+ENGINE_API_VERSION = "2.20.0" as const
 ```

package/docs/api/equipment-generic-lens-catalogue.md

@@ -69,7 +69,7 @@ export interface GenericLensCatalogueEntry {
   note: string;
   /**
    * A short plain-English summary of the lens's character (at most 40 characters, US spelling), written from its adjustments and
-   * `note`, for lists and pickers. It describes only what the catalogue models (bokeh shape is not modeled: the defocus is a disc).
+   * `note`, for lists and pickers. It describes the lens's sharpness, color, distortion and falloff, not its bokeh (the same rule for every lens of a set).
    */
   summary: string;
 }
@@ -102,6 +102,11 @@ export interface GenericLensCharacter {
   breathing: { fieldOfViewChange: number; atMinimumFocus: number };
   /** Standard deviation of the autofocus error as a fraction of the depth of focus 2·N·c. */
   focusScatterDepthOfFocusFraction: number;
+  /**
+   * Bokeh character (#567) at this f-number, focus and sensor, as the options of `lens.defocus` and `calculateDefocusBokehKernel`
+   * (#553): blades, the resolved W040 as `sphericalAberration` (µm at this f-number) and, for fast wides and normals, `catsEye`.
+   */
+  bokeh: DefocusBokehOptions;
 }
 ```
 
@@ -127,7 +132,7 @@ export interface GenericLensCharacterValues {
   distortionMagnitude: number;
   /** Corner fall-off in stops that stays when stopped down (natural vignetting). */
   naturalVignettingStops: number;
-  /** Extra corner fall-off in stops at the widest aperture (optical vignetting); gone two stops down. */
+  /** Extra corner fall-off in stops at the widest aperture (optical vignetting); gone four stops down (N = 4·N0). */
   opticalVignettingStops: number;
   /** Veiling glare: the fraction of the image's mean irradiance spread as a uniform veil. */
   veilingGlareFraction: number;

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.19.0",
-  "engineApiVersion": "2.19.0",
+  "packageVersion": "2.20.0",
+  "engineApiVersion": "2.20.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -77,6 +77,11 @@
       "source": "src/sensor/optical-stack.ts",
       "kind": "type"
     },
+    {
+      "name": "ApertureDiameter",
+      "source": "src/optics/aperture-diameter.ts",
+      "kind": "type"
+    },
     {
       "name": "AperturePriorityAutoIsoExposureModeResolution",
       "source": "src/exposure/exposure-mode-resolver.ts",
@@ -362,6 +367,16 @@
       "source": "src/optics/diffraction.ts",
       "kind": "type"
     },
+    {
+      "name": "calculateApertureDiameter",
+      "source": "src/optics/aperture-diameter.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateApertureDiameterInput",
+      "source": "src/optics/aperture-diameter.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateAtmosphericHaze",
       "source": "src/optics/atmospheric-haze.ts",
@@ -582,6 +597,16 @@
       "source": "src/color/illuminants.ts",
       "kind": "runtime"
     },
+    {
+      "name": "calculateCropToMatchFocalLength",
+      "source": "src/output/crop-to-match-focal-length.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateCropToMatchFocalLengthInput",
+      "source": "src/output/crop-to-match-focal-length.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateDefocusBokehKernel",
       "source": "src/optics/defocus-bokeh-kernel.ts",
@@ -632,6 +657,16 @@
       "source": "src/optics/depth-of-field.ts",
       "kind": "type"
     },
+    {
+      "name": "calculateDetailLimit",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateDetailLimitInput",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
     {
       "name": "calculatedResult",
       "source": "src/core/calculation-result.ts",
@@ -1152,6 +1187,11 @@
       "source": "src/output/print-plan.ts",
       "kind": "runtime"
     },
+    {
+      "name": "calculatePrintSizeLimitWithBlurAndNoise",
+      "source": "src/output/print-size-blur-noise.ts",
+      "kind": "runtime"
+    },
     {
       "name": "calculateProcessedSensorRaw",
       "source": "src/capture/photographic-export.ts",
@@ -2752,6 +2792,11 @@
       "source": "src/optics/zernike-wavefront.ts",
       "kind": "type"
     },
+    {
+      "name": "CropToMatchFocalLength",
+      "source": "src/output/crop-to-match-focal-length.ts",
+      "kind": "type"
+    },
     {
       "name": "DeadLeavesChartScene",
       "source": "src/facade/chart-scenes.ts",
@@ -2822,6 +2867,56 @@
       "source": "src/optics/depth-of-field.ts",
       "kind": "type"
     },
+    {
+      "name": "DETAIL_LIMIT_LIMITS",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "DetailLimit",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DetailLimitBasis",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DetailLimitCatalogueLens",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DetailLimitedBy",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DetailLimitIdealLens",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DetailLimitingFactor",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DetailLimitOptics",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DetailLimitSampling",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
+    {
+      "name": "DetailLimitSystem",
+      "source": "src/optics/detail-limit.ts",
+      "kind": "type"
+    },
     {
       "name": "DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS",
       "source": "src/optics/diffraction-psf-profile.ts",
@@ -5967,6 +6062,11 @@
       "source": "src/output/print-region-statistics.ts",
       "kind": "runtime"
     },
+    {
+      "name": "PrintBlurInput",
+      "source": "src/output/print-size-blur-noise.ts",
+      "kind": "type"
+    },
     {
       "name": "PrintContrastReference",
       "source": "src/output/print-contrast-reference.ts",
@@ -5992,6 +6092,11 @@
       "source": "src/output/print-plan.ts",
       "kind": "type"
     },
+    {
+      "name": "PrintImageMm",
+      "source": "src/output/print-size-blur-noise.ts",
+      "kind": "type"
+    },
     {
       "name": "PrintJpegInput",
       "source": "src/output/print-jpeg.ts",
@@ -6047,6 +6152,11 @@
       "source": "src/output/print-plan.ts",
       "kind": "type"
     },
+    {
+      "name": "PrintNoiseInput",
+      "source": "src/output/print-size-blur-noise.ts",
+      "kind": "type"
+    },
     {
       "name": "PrintPlan",
       "source": "src/output/print-plan.ts",
@@ -6112,6 +6222,11 @@
       "source": "src/output/print-plan.ts",
       "kind": "type"
     },
+    {
+      "name": "PrintSharpCleanCriterion",
+      "source": "src/output/print-size-blur-noise.ts",
+      "kind": "type"
+    },
     {
       "name": "PrintSinusoidalMeasurement",
       "source": "src/output/print-detail.ts",
@@ -6132,6 +6247,16 @@
       "source": "src/output/print-plan.ts",
       "kind": "type"
     },
+    {
+      "name": "PrintSizeLimitWithBlurAndNoise",
+      "source": "src/output/print-size-blur-noise.ts",
+      "kind": "type"
+    },
+    {
+      "name": "PrintSizeLimitWithBlurAndNoiseInput",
+      "source": "src/output/print-size-blur-noise.ts",
+      "kind": "type"
+    },
     {
       "name": "PROCESSED_SENSOR_RAW_MODEL_VERSION",
       "source": "src/capture/photographic-export.ts",
@@ -8512,6 +8637,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "runtime"
     },
+    {
+      "name": "SIMULATE_CAPTURE_FAST_METHODS",
+      "source": "src/facade/fast-methods.ts",
+      "kind": "runtime"
+    },
     {
       "name": "SIMULATE_CAPTURE_FAST_OPTIONS",
       "source": "src/facade/simulate-capture.ts",
@@ -8602,6 +8732,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureFastMethod",
+      "source": "src/facade/fast-methods.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureFastOption",
       "source": "src/facade/simulate-capture.ts",
@@ -8642,6 +8777,11 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureNoiseComponents",
+      "source": "src/sensor/sensor-characteristics.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureOptions",
       "source": "src/facade/simulate-capture.ts",
@@ -8672,6 +8812,16 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "SimulateCaptureSensorCharacteristics",
+      "source": "src/sensor/sensor-characteristics.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateCaptureSensorReport",
+      "source": "src/sensor/sensor-characteristics.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureSharpening",
       "source": "src/facade/simulate-capture.ts",

package/docs/api/facade-display-view-gpu.md

@@ -81,13 +81,16 @@ export type DisplayViewGpuMode = "off" | "auto" | "require";
 
 ```ts
 export interface PrepareDisplayViewOptions {
-  /** See {@link DisplayViewGpuMode}. Default `"off"`. */
+  /**
+   * See {@link DisplayViewGpuMode}. 2.20.0: default `"auto"` when the request resolves to fast (`fast` omitted or true: the
+   * display view's default) and `"off"` when it is exact (`fast: false`); an explicit value wins.
+   */
   gpu?: DisplayViewGpuMode;
   /**
    * Where the device comes from, with `gpu: "auto"` or `"require"`: a WebGPU entry point (a worker's `navigator.gpu`), or an
    * `ImageKernelAccelerator` whose device the view shares (the accelerator keeps ownership; `dispose()` of the prepared view
    * leaves it alone). Without it the engine acquires a device from `globalThis.navigator.gpu` and owns it until `dispose()`.
-   * Refused with `gpu: "off"`.
+   * Refused when `gpu` is or defaults to `"off"`.
    */
   gpuDevice?: unknown;
 }