@photivra/engine 2.17.0 → 2.19.0

package/docs/QUICK_START.md

@@ -104,6 +104,7 @@ modelling choices (such as "no lens PSF") as `kind: "model"`.
 | `output.exposureCompensationStops` | 0 | #556: a development exposure push, −2 to +5 stops, on the RAW before white balance (see [Development exposure push](#development-exposure-push-556)). |
 | `output.diffractionCorrection` | off | #552: `{ wavelengthNm?, regularization?, maximumGain?, kernelRadiusPixels? }`, a bounded deconvolution of the diffraction blur; needs `lens.diffraction`. It never restores detail beyond the diffraction cut-off (see [Sharpening and diffraction correction](#sharpening-and-diffraction-correction-552)). |
 | `output.sharpening` | off | #552: `{ radiusPixels?, amount?, threshold? }`, an unsharp mask after the tone curve; sRGB output only (see [Sharpening and diffraction correction](#sharpening-and-diffraction-correction-552)). |
+| `output.lensCorrections` | off | #570, with `lens.catalogue`: `{ distortion?, lateralColor?, vignetting? }`, the lens's own corrections on the developed JPEG, PNG and samples; the DNG is never corrected. Works with `output.region` (see [Generic lens catalogue](#generic-lens-catalogue-549)). |
 | `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 | 0.5–1000 (2.5; 0.5–100 before). The sensor is `width × pitch` wide (see [Geometry](#geometry)); the ISO readout scales with the pixel area (see [ISO and pixel size](#iso-and-pixel-size)). Above 100 µm the capture is a downsized view of a whole frame (see [Whole-frame views](#whole-frame-views-25)). |
@@ -116,7 +117,7 @@ modelling choices (such as "no lens PSF") as `kind: "model"`.
 | `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. |
+| `signal`, `onProgress` | none | An `AbortSignal` cancels the running task; `onProgress` reports `raw`, `white-balance`, `development`, `diffraction-correction` and `sharpening` (#571: output rows, with those options) 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.
 
@@ -212,10 +213,22 @@ and every number is a labelled approximation.
 - **Combinations:** `lens.defocus` convolves the disc 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 refuses `lens.catalogue`.
+  set by the lens and refused with it. The display view renders `lens.catalogue` since #569, with the PSF taken per field zone
+  ([Display view, Catalogue lenses](https://github.com/Photivra/photivra/blob/main/docs/DISPLAY_VIEW.md#catalogue-lenses-569)).
 - **Cost:** one scene query per kernel tap through the lens field mapping, like `lens.distortion`: a 48 × 48 region of a full frame
   at 6 µm takes about 1 s with *PV 50 1.2 Pro* and 6 s with *PV 50 1.8* (Apple M5 Pro), against 0.01 s with `lens.prime`. Render
   regions, or use a coarser `sensor.spectralStepNanometers`.
+- **Lens corrections (#570):** `output: { lensCorrections: { distortion: true, lateralColor: true, vignetting: true } }` applies the
+  lens's generic correction profile (`createGenericLensCorrectionProfile`) to the developed linear colour, each correction
+  switched on separately, as cameras do for their JPEGs. The RAW and the DNG are never corrected. The image keeps its size and is
+  magnified just enough to have no missing pixels (`magnification` in the `output.lensCorrections` assumption, 1 for the barrel
+  wide angles); vignetting is corrected to a flat field. Regions and parts are byte-identical to the whole frame. The costs are
+  real: stretched corners lose resolution and brightened corners are noisier
+  ([DIGITAL_OPTICS_FOUNDATION.md](https://github.com/Photivra/photivra/blob/main/docs/DIGITAL_OPTICS_FOUNDATION.md#lens-corrections-in-the-development-570)).
+- **Fast method (#568):** `fast: true` (or `lens: { catalogue: { kind: "pv-50-1.8", fast: true } }`) blends the PSF over a field
+  grid and tabulates each site's signal, a labeled approximation within 2.3e-4 of the frame's peak signal of the exact method
+  (measured): a 768 × 512 whole full frame renders within 2× of the same `lens.prime` capture. It needs a still camera, site-center
+  queries and a chart or material scene; elsewhere the exact method runs (`diagnostics.fast` says which ran).
 
 ```ts
 import { resolveGenericLens, simulateCapture } from "@photivra/engine";
@@ -233,6 +246,60 @@ const capture = await simulateCapture({
 console.log(capture.assumptions.find((a) => a.id === "lens.catalogue.character")?.value);
 ```
 
+### Ideal lens at any focal length and f-number (#576)
+
+`lens.ideal: { focalLengthMm }` is a plain ideal lens: an aberration-free thin lens named by its **physical** focal length, on
+whatever sensor the frame is (output width × height × pixel pitch). Unlike `lens.prime` and `lens.catalogue` it is not scaled by
+the crop factor, so a 50 mm lens is 50 mm on full frame and on APS-C, as when a full-frame lens is mounted on a smaller sensor
+(narrower field of view, the same blur in millimetres).
+
+- **Any f-number within the bounds:** `lens.fNumber` from f/0.5 to f/128, focal lengths from 1 to 4000 mm (`IDEAL_LENS_LIMITS`).
+  f/0.5 is the physical limit of a lens in air (the sine condition: N = 1/(2·sin θ′) ≥ 0.5); the others are engine bounds. Values
+  beyond them are refused by name. Shutter priority and program may choose any aperture in that range (in dim light, wider
+  than real lenses open).
+- **An optional f-number range:** `lens.ideal: { focalLengthMm, widestFNumber, narrowestFNumber }` (either or both, within
+  `IDEAL_LENS_LIMITS`, the widest no larger than the narrowest; each defaults to its bound) narrows that range like a real
+  lens's: `lens.fNumber` must lie in it, and shutter priority and program choose apertures only in it. The assumption then
+  records the range (`{ lensId, focalLengthMm, widestFNumber, narrowestFNumber }`); without it nothing changes. A range without
+  f/8 takes the reference exposure at its aperture nearest f/8 (the same N²/t). Where that shutter would be shorter than the
+  body's shortest (a range narrower than about f/1, such as f/0.5–f/0.9), the anchor takes the shortest shutter instead, a lower
+  N²/t that the meter and the exposure modes measure from, so the exposure is the same (#585; refused in every mode before 2.19.0).
+- **Program with a range (#583):** program follows the engine's program line (f/16 1/2000 s … f/8 1/125 s … f/4 1.024 s). A
+  range that holds f/4–f/16 keeps it unchanged. Otherwise the line's f/4 and f/16 move to the range (each clamped to it): the
+  same shape, with the aperture held at the range's end and the shutter taking up the stops (the same N²/t, so the same
+  exposure), still from 1/2000 s to 1.024 s. Beyond the line's ends the resolver holds them, as before (with `iso: "auto"` the
+  ISO rises in dim light; with a fixed ISO the capture is under- or overexposed and `exposure.standardExposureDeviationStops`
+  says by how much). For example f/8–f/32 gives f/16 1/2000 s … f/16 1/125 s … f/8 1/125 s … f/8 1.024 s. The
+  `exposure.programLine` assumption then records the limited line (profile id `"facade-generic-program-line-lens-range"`, with its `nodes`). The same
+  applies to the `lens.prime` and `lens.catalogue` ranges that do not hold f/4–f/16 (the 800 mm and 1200 mm-equivalent primes;
+  *PV 800 5.6 Pro*, *PV 1200 8 Pro*, *PV 200 5.6*, *PV 300 5.6*, *PV 400 5.6*, *PV 500 5.6*, *PV 600 6.3* and *PV 800 9*),
+  which program refused before 2.19.0. An approximation: a generic line, not a manufacturer's program.
+- **The same blur models as `lens.prime`:** `lens.defocus` (the thin-lens blur circle of `calculateDefocusCircle`), `lens.diffraction`
+  (the Airy pattern) and `lens.vignetting` (a caller profile). Without them the ideal lens renders sharp and evenly lit. It focuses
+  at any distance beyond the focal length (no minimum focus distance; the subject must be at least twice the focal length away, as
+  for every lens).
+- **Capture and display view:** `simulateCapture`, `simulateDisplayView` and `prepareDisplayView` take it. It replaces the tier
+  lens's focal length and f-number range (its transmission is kept) and is recorded in the `lens.ideal` assumption
+  (`{ lensId: "ideal-50mm", focalLengthMm: 50 }`). At the same focal length and f-number it renders the same pixels as the tier
+  lens (`lens.focalLengthMm`) and the generic prime.
+- **Not combinable** with `lens.prime`, `lens.catalogue` or `lens.focalLengthMm`.
+
+A 50 mm f/1.8 lens on APS-C (23.5 × 15.6 mm: 235 × 156 pixels at 100 µm):
+
+```ts
+import { simulateCapture } from "@photivra/engine";
+
+const capture = await simulateCapture({
+  scene: { preset: "siemens-star" },
+  output: { width: 235, height: 156 },
+  sensor: { pixelPitchMicrometers: 100 },
+  subjectDistanceM: 3,
+  lens: { ideal: { focalLengthMm: 50 }, fNumber: 1.8, focusDistanceM: 2.5, defocus: { model: "geometric-disc" } },
+  exposure: { mode: "aperture-priority" }
+});
+console.log(capture.assumptions.find((a) => a.id === "lens.defocus")?.value); // diameterMicrometers 94.5 on any sensor
+```
+
 ### Fitting a chart to the frame (2.3)
 
 `calculateSubjectDistanceForFraming({ sensor, focalLengthMm | equivalentFocalLengthMm, chart, fit? })`
@@ -485,7 +552,7 @@ Exposure compensation applies to the meter target first, as with a numeric ISO.
 | `manual` | Your aperture and shutter; the ISO makes up the exposure (`resolveManualExposureMode`, automatic ISO). |
 | `aperture-priority` | Your aperture. The shutter follows the meter at the lowest ISO, but no slower than `exposure.autoIso.slowestPreferredShutterSeconds` (required; seconds within the body's shutter range, or `"auto"`, see below); the ISO makes up the rest. At the Auto ISO maximum, `afterMaximumIso` decides: `"allow-slower-shutter"` (the default) lengthens the shutter to reach the target, `"hold-preferred-shutter"` keeps it and leaves the exposure under target (`resolveAperturePriorityAutoIsoExposureMode`). |
 | `shutter-priority` | Your shutter. The aperture is chosen at the lowest ISO, no wider than the target needs, so it stops at the widest aperture; the ISO makes up the rest (`resolveShutterPriorityExposureMode`, policy `minimum-iso-aperture-first`). |
-| `program` | The generic program line at the lowest ISO; beyond the line's end (f/4, 1.024 s) the ISO rises (`resolveProgramAutoExposureMode`, automatic ISO). With `exposure.autoIso.slowestPreferredShutterSeconds` (optional, a number or `"auto"`, #504) the line's shutter is held at it before the ISO rises, and `afterMaximumIso` applies as in aperture priority, never past the line's own shutter. |
+| `program` | The generic program line (limited to the lens's f-number range, #583) at the lowest ISO; beyond the line's end (f/4, 1.024 s) the ISO rises (`resolveProgramAutoExposureMode`, automatic ISO). With `exposure.autoIso.slowestPreferredShutterSeconds` (optional, a number or `"auto"`, #504) the line's shutter is held at it before the ISO rises, and `afterMaximumIso` applies as in aperture priority, never past the line's own shutter. |
 
 The result says what happened. `exposure.settings.iso` is the ISO used and `exposure.isoControl` is `"automatic"`.
 `exposure.autoIso` reports `idealIsoBeforeConstraints`, the Auto ISO range (`autoIsoMinimum`, `autoIsoMaximum`),
@@ -923,10 +990,14 @@ console.log(result.diagnostics.detail); // { diffractionCorrection: {...}, sharp
   noise; it adds no detail. Not with a wide-gamut `output.colorEncoding` or `output.gamutMapping: "perceptual"`.
 - **Reported:** the `output.diffractionCorrection` and `output.sharpening` assumptions (settings, cut-off, measured filter
   response, defaults used), `diagnostics.detail` (ringing, clipping and halo counts) and `diagnostics.options`.
-- **Not combinable** with `output.region`; not offered by `simulateDisplayView` or `simulateIdealReference`. The DNG holds the
-  RAW codes and is unchanged; only `image.samples` (and the JPEG or PNG made from them) change.
-- **Cost:** both stages hold the whole developed image, as AHD does. At 256 × 256 on an Apple M5 Pro (Node.js 24.19.0) the
+- **Not combinable** with `output.region`; not offered by `simulateDisplayView` or `simulateIdealReference`. A capture rendered
+  in region parts takes them through `simulateCaptureFromParts` (#571, [Developing a capture rendered in parts](#developing-a-capture-rendered-in-parts-571)).
+  The DNG holds the RAW codes and is unchanged; only `image.samples` (and the JPEG or PNG made from them) change.
+- **Cost:** both stages need the whole developed image, as AHD does. At 256 × 256 on an Apple M5 Pro (Node.js 24.19.0) the
   development took 8 ms by default, 15 ms with sharpening and 18–20 ms with diffraction correction (R = 3–5), one run each.
+  Since #571 they run row by row in place, with the same sums in the same order (the same bytes as 2.18.0): one developed
+  image in memory instead of up to six, and `onProgress` reports each output row as the `diffraction-correction` and
+  `sharpening` stages. At 24 MP see [Developing a capture rendered in parts](#developing-a-capture-rendered-in-parts-571).
 
 The trade-offs of these and the lens corrections (corner resolution after distortion correction, corner noise after
 vignetting correction, residual longitudinal CA, halo overshoot, nothing beyond the cut-off) are measured in
@@ -1817,6 +1888,65 @@ const dng = await serializeSimulatedCaptureDngFromParts(dngFrame, parts);
 console.log(dng.bytes.length);
 ```
 
+### Developing a capture rendered in parts (#571)
+
+`simulateCaptureFromParts(options, parts)` develops the whole frame of `options` from region renders of the same
+request. It joins the parts' RAW exactly as `serializeSimulatedCaptureDngFromParts` does (the same parts, the same checks),
+then develops the joined RAW as `simulateCapture(options)` would, including the steps that filter across the whole image and
+that a region refuses: `output.diffractionCorrection` and `output.sharpening`. The joined RAW is the whole render's RAW, so the
+result's `image.samples`, JPEG or PNG bytes, `raw` and `plan` are those of the whole-frame capture, bit for bit. Pass the
+whole request (no `output.region`); render the parts with the same request plus `output.region`, without the detail stages,
+`output.dng` and auto white balance (none changes the RAW codes; auto white balance is measured here over the joined frame).
+`output.lensCorrections` (#570) is honored as in the whole-frame capture, bit for bit; a part may keep or drop it (a corrected
+region only widens its `region.nativeRect`). The corrections run on the whole developed frame and hold a second developed
+image while they resample it.
+
+`onProgress` reports `development`, then `diffraction-correction` and `sharpening` once per output row of the whole image
+(each stage ends with `completedTileCount === totalTileCount`), then `jpeg`; no `raw` stage, since no RAW is rendered. A host
+can show these as "Applying diffraction correction to the whole image" and "Applying sharpening to the whole image". The
+lens corrections run between the two and report no stage of their own.
+`signal` cancels the step. In the result, `diagnostics.providerEvaluationCount` is 0, `diagnostics.timingsMs` are this call's
+(`raw` is the join), `diagnostics.fast` and the `raw.*` assumptions of how the RAW was rendered are in the parts' results
+instead, and a `parts` assumption records the join.
+
+```ts
+import { simulateCaptureFromParts, simulateCapture, type SimulateCaptureDngPart, type SimulateCaptureOptions } from "@photivra/engine";
+
+const whole: SimulateCaptureOptions = { scene: { preset: "slanted-edge" }, lens: { fNumber: 16, diffraction: "circular-aperture" },
+  output: { width: 96, height: 64, format: "jpeg", diffractionCorrection: {}, sharpening: {} } };
+// Two strips rendered without the whole-image stages (in an application, in separate Web Workers).
+const parts: SimulateCaptureDngPart[] = await Promise.all([0, 32].map(async (y) => {
+  const part = await simulateCapture({ ...whole, output: { width: 96, height: 64, region: { x: 0, y, width: 96, height: 32 } } });
+  return { raw: part.raw, region: part.region! };
+}));
+const developed = await simulateCaptureFromParts({ ...whole, onProgress: ({ stage, completedTileCount, totalTileCount }) => {
+  if (stage === "sharpening") console.log("Applying sharpening to the whole image", completedTileCount / totalTileCount);
+} }, parts);
+console.log(developed.image.jpeg!.length); // the bytes of simulateCapture(whole).image.jpeg
+```
+
+Tests compare the result with the whole-frame capture byte for byte: JPEG with both stages, 16-bit sRGB with a thresholded
+mask, AHD with auto white balance, a development push and the four-spot filter, Display P3 PNG with diffraction correction,
+DNG with both stages, no stage at all, and a catalogue lens with all three lens corrections and sharpening (parts rendered
+with and without the corrections); and the row-by-row stages against whole-image passes on odd sizes.
+
+**Measured at 24 MP** (6000 × 4000 at 6 µm, slanted edge at f/8 with `lens.diffraction`, 8 parts; Apple M5 Pro, Node.js 24.19.0,
+one thread, a shared machine, two runs; `node scripts/benchmark-joined-development.mjs`):
+
+| Step | Time | Peak memory (process) |
+| --- | --- | --- |
+| Join and develop, no detail stage | 1.9–2.2 s (join 0.13–0.15 s) | 532–551 MiB |
+| … with sharpening (σ = 1) | 3.3–3.7 s (sharpening 1.9–2.1 s) | 1,080 MiB |
+| … with diffraction correction (R = 3, the default) | 3.7–3.9 s (correction 2.0 s) | 1,079–1,080 MiB |
+| … with both | 5.1–5.4 s (development 1.2 s, correction 2.0–2.1 s, sharpening 1.7–1.8 s) | 1,079 MiB |
+| Whole `simulateCapture` with both, for comparison | 10.0–10.4 s (RAW 4.8–4.9 s) | 924 MiB |
+
+The peak includes the parts' RAW read back (7 bytes per native site) and the joined RAW. The detail stages' share is the one
+developed image in 64-bit floats (24 bytes per pixel, 549 MiB at 24 MP), held as before by AHD and the wide-gamut paths. In
+2.18.0 the stages held up to six such images: the same whole capture with both stages peaked at 3,670 MB (resident set
+sampled every 50 ms). The extra pass therefore costs about 5 s on one worker after the parts, against about 10 s to render
+the whole frame again on one worker.
+
 ### A Print JPEG written in strips
 
 At 1:1 (output size equal to the crop), a Print JPEG's rows can be coded on separate workers.

package/docs/USAGE.md

@@ -374,6 +374,8 @@ The actual focal length stays the physical optical quantity used by projection a
 - Focus distance is not part of conventional 35 mm-equivalent focal length. A later digital/output crop and the output resolution are also excluded.
 - If a product wants to describe the final digital framing, it should label it as output framing. It should not silently replace the optical focal length or the capture-equivalent focal length.
 
+To render a lens by its physical focal length on any sensor, give `simulateCapture()` or the display view `lens.ideal: { focalLengthMm }` with any `lens.fNumber` within `IDEAL_LENS_LIMITS` (f/0.5–f/128, 1–4000 mm; optional `widestFNumber` and `narrowestFNumber` narrow the f-number range for the automatic exposure modes; in program the engine's program line is limited to that range, #583): an aberration-free thin lens that is not scaled by the crop factor, unlike `lens.prime` (see docs/QUICK_START.md, "Ideal lens at any focal length and f-number").
+
 `calculateImagingAreaMetrics()` provides the same canonical diagonal crop-factor calculation, independent of raster density, so other engine modules do not need to repeat that formula.
 
 ## Focus-breathing projection
@@ -1056,6 +1058,30 @@ T_stack = T_1 * T_2 * ... * T_n
 
 The stack keeps each filter's identity and evidence. The combined numeric uncertainty is deliberately reported as **not propagated**, unless it is established whether the filters' errors are correlated or independent. Each filter's own uncertainty stays attached to that filter.
 
+### Exposure time with an ND filter
+
+`calculateFilteredExposureTime({ shutterSeconds, filter, shutterDialSeconds? })` (model `filtered-exposure-time` 1.0.0, #578) gives the shutter time that keeps the same exposure at the same f-number and ISO after adding one filter or a stack (`filter` takes one profile or an array in light-path order): `filteredShutterSeconds = shutterSeconds / T`, with `T` the stack's combined transmittance from `composeFrontOfLensFilterTransmission()`. It also returns `attenuationStops`, `exposureFactor` (`1/T`) and the full `filterTransmission`. With a `shutterDialSeconds` list (for example `GENERIC_THIRD_STOP_SHUTTER_SECONDS`) it adds `dial`: the nearest dial value in stops (the shorter on a tie), its exposure error in stops, and `clamped: "maximum"` when the exact time is longer than the longest dial value (use bulb).
+
+- Exact under the linear sensor model (exposure `H = E·t`); film reciprocity failure is not modelled.
+- Nominal filters vary: a "10-stop" filter (`T = 2^-10`) gives 1/125 s → 8.19 s, an ND1000 (OD 3.0, 9.97 stops) gives exactly 8 s. The result is only as good as the profile, and is an approximation whenever a profile is.
+- Generic presets: `GENERIC_ND_FILTER_PROFILES[3]`, `[6]` and `[10]` (keys in `GENERIC_ND_FILTER_STOPS`) are frozen, unbranded, spectrally flat profiles over 380–780 nm with a transmittance of exactly 2^-N (1/8, 1/64, 1/1024). They are idealized (`scientificStatus: "approximation"`, uncertainty not quantified), and any function that takes a front-of-lens filter profile accepts them. For other filters, build a profile with `parseFrontOfLensFilterProfile()`.
+- Filters are resolved at 550 nm unless `wavelengthNanometers` is given; neutral filters do not depend on it. `incidentPolarization` matters only with a polarizer in the stack.
+
+```ts
+import {
+  GENERIC_ND_FILTER_PROFILES,
+  GENERIC_THIRD_STOP_SHUTTER_SECONDS,
+  calculateFilteredExposureTime
+} from "@photivra/engine";
+
+const { value } = calculateFilteredExposureTime({
+  shutterSeconds: 1 / 125,
+  filter: GENERIC_ND_FILTER_PROFILES[10],
+  shutterDialSeconds: GENERIC_THIRD_STOP_SHUTTER_SECONDS
+});
+console.log(value.filteredShutterSeconds.toFixed(2), value.dial?.shutterSeconds); // 8.19 8
+```
+
 ### Spectral boundary
 
 Spectral filter data stays wavelength-resolved all the way through the [scene-radiance-to-sensor bridge](#scene-radiance-to-sensor-irradiance). Photivra does not turn a spectral filter into an undocumented RGB tint.
@@ -5525,6 +5551,20 @@ All modes:
 
 Flash-aware behaviour, safety shift and the program behaviour of named cameras are separate work.
 
+### The capture facade's program line and the lens's f-number range (#583)
+
+`simulateCapture()` and the display view in `exposure.mode: "program"` use an engine-authored generic line (f/16 1/2000 s … f/8
+1/125 s … f/4 1.024 s, assumption `exposure.programLine`). `resolveProgramAutoExposureMode()` refuses a line whose apertures leave
+the capability range, so with a lens range that does not hold f/4–f/16 (`lens.ideal` `widestFNumber`/`narrowestFNumber`,
+`lens.prime`, `lens.catalogue`) the facade limits the line to the range first: the line's f/4 and f/16 are clamped to the range, giving the same shape with
+the aperture held at the range's end and the shutter keeping each point's exposure (t/N², camera equation H = 0.65·L·t/N²),
+still from 1/2000 s to 1.024 s. Where both lines run, the limited line's aperture is the old one clamped in log2 to the range.
+Beyond the line's ends the resolver holds them as before. A range that holds f/4–f/16, or no range, keeps the line and its
+bytes. The limited line is recorded as its profile (id `"facade-generic-program-line-lens-range"`), with node stops measured from the
+capture's exposure anchor (f/8, 1/125 s; the same N²/t at the range's aperture nearest f/8; or, #585, that aperture at the
+body's shortest shutter when the same N²/t would need a shorter one). An approximation of a generic
+program, not a manufacturer's.
+
 ## Program Auto and Full Auto exposure
 
 Program Auto and Full Auto exposure both need a declared, versioned **program line**: a curve that says which aperture and shutter to use at each brightness level. The engine does not invent one "correct" aperture/shutter pair.
@@ -7478,9 +7518,11 @@ own designs, not real products). `resolveGenericLens` resolves one for a sensor,
 (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.
 `simulateGenericLensFocusError` draws a seeded autofocus error; `createGenericLensCorrectionProfile` builds the lens's generic
-correction profile for `resolveLensCorrectionPlan`. `simulateCapture` renders a catalogue lens with `lens.catalogue`
-([quick start](QUICK_START.md#generic-lens-catalogue-549)). Equations, tables and the chart measurements:
-[LENS_CATALOGUE.md](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md).
+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`
+([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).
 
 ```ts
 import { GENERIC_LENS_CATALOGUE, resolveGenericLens, simulateGenericLensFocusError } from "@photivra/engine";
@@ -7739,6 +7781,12 @@ console.log(star.assumptions.filter((a) => a.kind === "default").map((a) => a.id
 console.log(star.request.siteInput(0).environment.optics.nominalFNumber);
 ```
 
+A capture can render its RAW in parallel parts (`output.region`, one call per part). `serializeSimulatedCaptureDngFromParts()`
+writes the whole frame's DNG from the parts, and `simulateCaptureFromParts()` (#571) develops the whole frame from them,
+including the whole-image stages `output.diffractionCorrection` and `output.sharpening` that a region refuses, with the same
+bytes as a whole-frame `simulateCapture()` and per-row progress (`diffraction-correction`, `sharpening`). See
+[Quick start, Developing a capture rendered in parts](QUICK_START.md#developing-a-capture-rendered-in-parts-571).
+
 ### Color charts (2.14)
 
 The engine's own [color patches](https://github.com/Photivra/photivra/blob/main/docs/COLOR_PATCHES.md) are reflectance spectra lit by the capture's illuminant. Draw the
@@ -7999,3 +8047,41 @@ import { simulateCapture } from "@photivra/engine";
 const rolling = await simulateCapture({ scene: { preset: "checkerboard" }, motion: { angularVelocityRadPerSec: { pitch: 0.02 }, shutter: "rolling" }, output: { width: 6, height: 6 } });
 console.log(rolling.request.siteInput(7 * 8).charge.completenessProfile.startOffsetSecondsFromOpeningReference);
 ```
+
+## Equivalent f-number, sensor area and blur as a share of the frame
+
+`calculateSensorEquivalence()` says what a lens on one sensor corresponds to on a 36 × 24 mm frame (or on a `reference` you pass). Call it once per sensor to fill a lens table:
+
+```ts
+import { calculateBlurShareOfFrame, calculateSensorEquivalence } from "@photivra/engine";
+
+const apsC = calculateSensorEquivalence({
+  sensor: { widthMm: 23.5, heightMm: 15.6 },
+  focalLengthMm: 50,
+  fNumber: 2
+}).value;
+
+console.log(apsC.cropFactor); // ≈ 1.53
+console.log(apsC.equivalentFocalLengthMm); // ≈ 76.7 (framing)
+console.log(apsC.equivalentFNumber); // ≈ 3.07 (depth of field, blur and total light; not exposure)
+console.log(apsC.exposureFNumber); // 2 (exposure does not change with sensor size)
+console.log(apsC.areaRatio); // ≈ 0.42 of the full-frame area
+console.log(apsC.totalLightDifferenceStops); // ≈ -1.24 stops at the same f-number and shutter
+console.log(apsC.basis.equivalentFNumber.kind); // "approximation"
+
+const share = calculateBlurShareOfFrame({
+  blurCircleMm: 0.03,
+  sensor: { widthMm: 36, heightMm: 24 },
+  print: { widthMm: 300, heightMm: 200 }
+}).value;
+
+console.log(share.shareOfDiagonal); // ≈ 0.00069 of the frame diagonal
+console.log(share.print?.blurOnPrintMm); // 0.25 mm on the print
+```
+
+- `basis` gives, for every number, `kind: "exact"` or `"approximation"` and the conditions. Crop factor, equivalent focal length, area ratio, total-light difference, entrance pupil and angles of view are exact under their stated conditions.
+- The equivalent f-number (crop factor × f-number) assumes the same framing, subject distance and output size. It is a thin-lens approximation that is exact only when the focus distance is much greater than the focal length; at close focus the blur shares match at `k·N·(s − f)/(s − k·f)`.
+- Exposure uses the f-number on the lens. Equivalence never changes shutter, ISO or exposure.
+- 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).

package/docs/api/camera-sensor-equivalence.md

@@ -0,0 +1,209 @@
+# camera/sensor-equivalence.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.
+
+## BlurShareOfFrame
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BlurShareOfFrame {
+  /** Blur-circle diameter on the sensor in millimetres. */
+  blurCircleMm: number;
+  /** Sensor diagonal in millimetres. */
+  frameDiagonalMm: number;
+  /** Blur diameter / frame diagonal. Equal shares look the same at the same output size. */
+  shareOfDiagonal: number;
+  /** Blur diameter / frame width. */
+  shareOfWidth: number;
+  /** Blur diameter / frame height. */
+  shareOfHeight: number;
+  /** Blur on the print; present only when a print size was given. */
+  print?: BlurShareOfPrint;
+}
+```
+
+## BlurShareOfPrint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BlurShareOfPrint {
+  /** Linear enlargement from sensor to print: the smaller of the long-side and short-side ratios. */
+  enlargement: number;
+  /** Blur-circle diameter on the print in millimetres: blurCircleMm × enlargement. */
+  blurOnPrintMm: number;
+  /** Size of the printed image in millimetres (equal to the print when the aspect ratios match). */
+  imageLongSideMm: number;
+  imageShortSideMm: number;
+}
+```
+
+## calculateBlurShareOfFrame
+
+A blur circle on the sensor as a share of the frame (diagonal, width and height) and, when a
+print size is given, its diameter on that print.
+
+Equal shares of the diagonal look the same when the images are shown at the same size, which
+is how "same framing" comparisons across sensor sizes are stated. Every value is an exact ratio
+or scaling; whether a blur is visible depends on viewing distance and acuity, which this
+function does not judge.
+
+```ts
+export function calculateBlurShareOfFrame(
+  input: CalculateBlurShareOfFrameInput
+): CalculationResult<BlurShareOfFrame>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateBlurShareOfFrameInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateBlurShareOfFrameInput {
+  /** Blur-circle diameter on the sensor in millimetres (for example from calculateDefocusCircle). Zero is allowed. */
+  blurCircleMm: number;
+  /** Physical active imaging area of the sensor. */
+  sensor: SensorImagingArea;
+  /**
+   * Optional print size. The whole frame is enlarged to fit inside it without cropping, long side
+   * to long side.
+   */
+  print?: { widthMm: number; heightMm: number };
+}
+```
+
+## calculateSensorEquivalence
+
+Equivalence of a lens (focal length, f-number) on one sensor against a reference format,
+36 × 24 mm by default: crop factor, equivalent focal length, equivalent f-number for depth of
+field, blur and total light, the unchanged f-number for exposure, sensor area ratio, total-light
+difference in stops and the angles of view.
+
+Call it once per sensor for a lens table. Every quantity carries a `basis` entry saying whether it
+is exact under its stated conditions or an approximation. The equivalent f-number is an
+approximation (exact when the focus distance is much greater than the focal length) and never an
+exposure setting: exposure uses `exposureFNumber`, the f-number on the lens.
+
+Example: 50 mm f/2 on a 23.5 × 15.6 mm sensor gives crop factor ≈ 1.53, ≈ 77 mm and ≈ f/3.1.
+
+```ts
+export function calculateSensorEquivalence(
+  input: CalculateSensorEquivalenceInput
+): CalculationResult<SensorEquivalence>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSensorEquivalenceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSensorEquivalenceInput {
+  /** Physical active imaging area of the sensor the lens is used on. */
+  sensor: SensorImagingArea;
+  /** Physical focal length of the lens in millimetres. */
+  focalLengthMm: number;
+  /** f-number set on the lens (N = focal length / entrance-pupil diameter). */
+  fNumber: number;
+  /** Format to compare against. Defaults to the 36 × 24 mm frame. */
+  reference?: SensorImagingArea;
+}
+```
+
+## EquivalenceExactness
+
+Whether a value is exact under its stated conditions or an approximation.
+
+```ts
+export type EquivalenceExactness = "exact" | "approximation";
+```
+
+## EquivalenceValueBasis
+
+How one equivalence quantity was obtained, and under which conditions it holds.
+
+```ts
+export interface EquivalenceValueBasis {
+  /** `"exact"` under the stated conditions, or `"approximation"`. */
+  kind: EquivalenceExactness;
+  /** Plain statement of the definition and its conditions. */
+  statement: string;
+}
+```
+
+## SensorEquivalence
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorEquivalence {
+  /** Physical focal length supplied by the caller, in millimetres. */
+  focalLengthMm: number;
+  /** f-number supplied by the caller. */
+  fNumber: number;
+  /** Sensor active imaging area used. */
+  sensor: SensorImagingArea;
+  /** Reference format used (36 × 24 mm unless the caller passed one). */
+  reference: SensorImagingArea;
+  /** Sensor diagonal in millimetres. */
+  sensorDiagonalMm: number;
+  /** Reference diagonal in millimetres. */
+  referenceDiagonalMm: number;
+  /** Diagonal crop factor: reference diagonal / sensor diagonal. Greater than 1 for a smaller sensor. */
+  cropFactor: number;
+  /** Focal length on the reference format with the same diagonal angle of view: cropFactor × focalLengthMm. */
+  equivalentFocalLengthMm: number;
+  /**
+   * f-number on the reference format that gives the same depth of field, background blur and total
+   * light for the same framing and output size: cropFactor × fNumber. Not an exposure setting.
+   */
+  equivalentFNumber: number;
+  /** f-number that sets exposure (image brightness): the f-number on the lens, unchanged by sensor size. */
+  exposureFNumber: number;
+  /** Entrance-pupil diameter f/N in millimetres; the equivalent lens has the same diameter. */
+  entrancePupilDiameterMm: number;
+  /** Sensor area / reference area. Less than 1 for a smaller sensor. */
+  areaRatio: number;
+  /**
+   * log2(areaRatio): total light collected by the sensor relative to the reference at the same
+   * f-number, shutter time and scene, in stops. Negative for a smaller sensor.
+   */
+  totalLightDifferenceStops: number;
+  /** Angles of view of this lens on the sensor (the equivalent lens gives the same diagonal angle). */
+  fieldOfView: SensorEquivalenceFieldOfView;
+  /** Exact or approximated, with the conditions, for every quantity above. */
+  basis: Readonly<Record<SensorEquivalenceQuantity, EquivalenceValueBasis>>;
+}
+```
+
+## SensorEquivalenceFieldOfView
+
+Angles of view of an ideal rectilinear lens focused at infinity, in degrees.
+
+```ts
+export interface SensorEquivalenceFieldOfView {
+  horizontalDegrees: number;
+  verticalDegrees: number;
+  diagonalDegrees: number;
+}
+```
+
+## SensorEquivalenceQuantity
+
+Quantities of a sensor equivalence result that carry an exactness statement.
+
+```ts
+export type SensorEquivalenceQuantity =
+  | "cropFactor"
+  | "equivalentFocalLengthMm"
+  | "equivalentFNumber"
+  | "exposureFNumber"
+  | "entrancePupilDiameterMm"
+  | "areaRatio"
+  | "totalLightDifferenceStops"
+  | "fieldOfView";
+```

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

package/docs/api/equipment-ideal-lens.md

@@ -0,0 +1,26 @@
+# equipment/ideal-lens.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.
+
+## IDEAL_LENS_LIMITS
+
+Ideal lens (#576): the bounds of `simulateCapture`'s and the display view's `lens.ideal`, a plain aberration-free thin lens
+named by its physical focal length, on any sensor. Its blur is that of the options the request gives, the same models as with
+`lens.prime`: `lens.defocus` (the thin-lens blur circle, `calculateDefocusCircle`), `lens.diffraction` (the Airy pattern of a
+circular pupil) and `lens.vignetting` (a caller profile). Without them it renders sharp and evenly lit.
+
+- `fNumber.minimum` 0.5 is a physical limit: a lens in air that satisfies the Abbe sine condition (aplanatic) has
+  N = 1/(2·n·sin θ′) with n = 1 and sin θ′ ≤ 1, so N ≥ 0.5 (the sine condition: Born & Wolf, *Principles of Optics*, 7th ed.;
+  Kingslake & Johnson, *Lens Design Fundamentals*, 2nd ed.). The engine's thin-lens defocus and scalar Airy diffraction
+  are paraxial models, so near f/0.5 they are approximations further from a real lens than at f/2.
+- `fNumber.maximum` 128 and both focal-length bounds are engine bounds, not physical limits: 1 mm is shorter than phone
+  camera lenses, 4000 mm longer than photographic lenses, and f/128 beyond large-format lenses' smallest stops.
+- The ideal lens's f-number range is the whole of `fNumber`: manual and aperture priority take any `lens.fNumber` in it, and
+  shutter priority and program may choose any aperture in it (in dim light, wider than real lenses open).
+
+```ts
+IDEAL_LENS_LIMITS = Object.freeze({
+  focalLengthMm: Object.freeze({ minimum: 1, maximum: 4000 }),
+  fNumber: Object.freeze({ minimum: 0.5, maximum: 128 })
+})
+```