@photivra/engine 2.17.0 → 2.19.0

package/CHANGELOG.md

@@ -1,6 +1,121 @@
 # Changelog
 
-## 2.17.0 — unreleased (prepared November 7, 2026)
+## 2.19.0 — unreleased (prepared November 9, 2026)
+
+A minor release of six issues: exposure time with an ND filter and generic ND presets (#578), the program line within the lens's f-number range (#583), very fast `lens.ideal` ranges (#585), developing a capture rendered in parts (#571), lens corrections in the development (#570) and the sampled-PSF orientation fix (#566). See the [2.19.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_19_0.md).
+
+- **New:** `calculateFilteredExposureTime` and the generic ND presets `GENERIC_ND_FILTER_PROFILES` / `GENERIC_ND_FILTER_STOPS` (#578); `simulateCaptureFromParts` (#571); `output.lensCorrections` (#570); the progress stages `"diffraction-correction"` and `"sharpening"` (#571).
+- **Changed:** program mode limits the generic program line to a lens range that does not hold f/4–f/16 instead of refusing it (#583); a `lens.ideal` range narrower than about f/1 now resolves in every exposure mode (#585).
+- **Breaking fix (#566):** the rotationally symmetric `LensSampledPsfProfile` interpolation no longer mirrors asymmetric kernels in y (caller-supplied profiles in that mode only; no built-in lens uses it).
+- **Root exports:** 10 new, 1,850 → 1,860 (runtime exports 626 → 631): 8 from #578 (4 runtime), 1 from #571 (runtime), 1 from #570 (type). `GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM` moves module (same value, still a root export).
+- **Why minor:** new root exports and opt-in options; requests that 2.18.0 refused now resolve (#583, #585). #566 changes results only for caller-supplied profiles in the rotationally symmetric mode, a breaking fix the owner decided to ship in a minor release (2026-11-07, confirmed 2026-11-09). Nothing is removed, and no default changes.
+- **Integration (this release):** `simulateCaptureFromParts` honors `output.lensCorrections` exactly as the whole-frame capture does (byte-identical; a part may keep or drop the option); the lens corrections run between the `diffraction-correction` and `sharpening` progress stages and report no stage of their own. 285 private copies of the same field checks and helpers in the domain parsers (for example `requireRecord` in 44 modules) now share one export each, and 35 identical private helpers found in two modules each are shared too; messages, error classes and results are unchanged.
+- **Bundle:** the app's capture-worker shape (every chunk of `NATIVE_RAW_LIMITS`, `prepareDisplayView`, `serializeSimulatedCaptureDngFromParts`, `simulateCapture`, `simulateIdealReference`) is 351,775 B gzip (2.18.0: 351,859 B; limit 352,000 B, not raised). The six parts merged measured 353,811 B; sharing the duplicated helpers saved 2,036 B.
+
+### #566 LensSampledPsfProfile rotationally symmetric mode mirrors asymmetric PSFs in y
+
+- **Breaking fix (owner decision 2026-11-07; confirmed 2026-11-09: a breaking fix, as this entry states):** the `rotationally-symmetric-radial-field-centroid-aligned` interpolation of `LensSampledPsfProfile` rotated each kernel as if its row index ran towards image −Y, while the environment PSF quadrature (`sensorPsfSourcePoint`) applies the row index as image +Y. At field azimuth θ the kernel was therefore turned to −θ: the y mirror of the intended kernel. It now rotates with the quadrature's convention, so an asymmetric kernel renders with the same orientation as a 2-D grid node declared at that field point.
+- **Which results change:** only caller-supplied profiles that use this interpolation mode, at field points off the horizontal axis (`fieldYmm ≠ 0`), with a kernel that is not rotationally symmetric (a radial shift such as lateral color, radial elongation, coma, a decentered blur). Their `resolveLensSampledPsf` kernels (and the internal `resolveLensSampledPsfKernel`), and every capture, display view, RAW and convolution kernel built from them (`simulateCapture`, the native environment paths, `calculateSensorPsfIrradianceQuadrature`, `resolveLensPsfConvolutionKernels`), stop being mirrored in y. Kernels on the horizontal axis and rotationally symmetric kernels are unchanged (at θ = 0 and π the old and new rotations agree; a rotationally symmetric kernel is invariant). No built-in lens uses this mode (the generic lens catalogue uses the 2-D grid mode), so every hash lock holds. No API, schema or `src/gpu` change; the model id is unchanged.
+- **Tests** (`test/lens-psf-interpolation.test.ts`): an asymmetric kernel (a radially shifted core plus a blob to the counter-clockwise side) resolved in the rotationally symmetric mode and as an exact 2-D grid node, at (±6, ±6) mm in all four quadrants; the light of a point source, placed through `sensorPsfSourcePoint`, has the declared radial (2.25 samples) and across-radius (0.6 samples) moments in both modes, the kernels differ by L1 < 0.25 (bilinear resampling) and the rotated kernel is far from the grid kernel's y mirror (L1 > 1). The test fails on 2.18.0. The test helpers now build kernels with the row index increasing with image +Y; the existing four-orientation rotation test, which used the old convention in its helpers, is unchanged otherwise.
+- **Docs:** docs/PSF_FOUNDATION.md states the row convention of the rotation; docs/LENS_CATALOGUE.md drops the caveat; API reference regenerated (`LensSampledPsfInterpolation`).
+
+### #578 Exposure time with an ND filter
+
+- **New: `calculateFilteredExposureTime({ shutterSeconds, filter, shutterDialSeconds?, wavelengthNanometers?, wavelengthBasis?, incidentPolarization? })`** (model `filtered-exposure-time` 1.0.0, for the app's Guide page on ND filters and the calculator's ND table): the shutter time that keeps the same exposure at the same f-number and ISO after adding front-of-lens filters, `shutterSeconds / T`, with `T` from the existing filter profiles through `composeFrontOfLensFilterTransmission` (one profile or a stack). Returns `filteredShutterSeconds`, `linearTransmissionFactor`, `attenuationStops`, `exposureFactor`, the full `filterTransmission` and, with a dial list, `dial` (nearest value in stops, shorter on a tie, its exposure error in stops, and `clamped` outside the dial). 1/125 s with a 10-stop filter gives 1024/125 ≈ 8.19 s, 8 s on `GENERIC_THIRD_STOP_SHUTTER_SECONDS`; an ND1000 (OD 3.0) gives 8 s. Exact under the linear sensor model (H = E·t, CIPA DC-004-2020 §5.5, EMVA 1288 §2); reciprocity failure is not modelled; nominal filters vary, and the envelope is an approximation whenever a profile is. Filters are resolved at 550 nm by default (neutral filters do not depend on it).
+- **New: generic ND presets `GENERIC_ND_FILTER_PROFILES[3 | 6 | 10]` and `GENERIC_ND_FILTER_STOPS`** (owner decision 2026-11-09): frozen, unbranded front-of-lens filter profiles (`generic-nd-3-stop`, `generic-nd-6-stop`, `generic-nd-10-stop`) that transmit exactly 2^-N (1/8, 1/64, 1/1024; "N-stop" means exactly 2^-N), spectrally flat (`neutral-linear-transmission`) over 380–780 nm in air, and marked idealized (`scientificStatus: "approximation"`, uncertainty not quantified, evidence note "Idealized"). 1/125 s with the 10-stop preset gives exactly 8.192 s, 8 s on the third-stop dial.
+- **Root exports:** 8 new (4 runtime): `calculateFilteredExposureTime`, `FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS`, `GENERIC_ND_FILTER_PROFILES`, `GENERIC_ND_FILTER_STOPS` and the types `CalculateFilteredExposureTimeInput`, `FilteredExposureTime`, `FilteredExposureDialSetting`, `GenericNdFilterStops`. Pure function and constant data; no capture, RAW or bundle change.
+- **Docs and tests:** docs/PHYSICS_FOUNDATION.md ("Exposure time with an ND filter"), docs/USAGE.md (with a runnable example; later USAGE.md fragment indices in docs/validation/documentation-fragments.json shift by one), docs/AGENT_GUIDE.md, llms.txt, API reference task index; `test/filtered-exposure-time.test.ts` (including exact preset values, flatness, freezing and parser round trip).
+
+### #583 Program mode: the program line follows the lens's f-number range
+
+- **Changed (requests that 2.18.0 refused now resolve):** in `exposure.mode: "program"`, `simulateCapture`, `simulateDisplayView` and `prepareDisplayView` limit the engine's generic program line (f/16 1/2000 s … f/8 1/125 s … f/4 1.024 s) to the lens's f-number range when the range does not hold f/4–f/16, where 2.18.0 refused it ("Program-line aperture lies outside the resolved equipment capability range."). This lifts the 2.18.0 limitation for `lens.ideal` `widestFNumber`/`narrowestFNumber` (#576; deferred to 2.19.0 by the owner on 2026-11-09), and applies equally to the `lens.prime` and `lens.catalogue` ranges that do not hold the line: the 800 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*.
+  - **Model (an approximation; a generic line, not a manufacturer's program):** the line's f/4 and f/16 are clamped to the range, giving the same shape: 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 aperture is the old line's clamped in log2 to the range; beyond the line's ends the resolver holds them as before (Auto ISO raises the ISO; a fixed ISO under- or overexposes, reported by `standardExposureDeviationStops`). 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 records a limited line's profile (id `"facade-generic-program-line-lens-range"`, with its nodes) (`defaultProgramLine` in `src/facade/simulate-capture.ts`).
+  - **Unchanged:** requests with no range, and every lens whose range holds f/4–f/16, keep the line, its assumption and their bytes (pinned SHA-256 digests of samples, RAW codes, exposure and assumptions from 3f9d65b for the tier lens, Auto ISO, `lens.ideal` without and with a holding range, `lens.prime: 50` and `pv-50-1.8`). No root export added; no `src/gpu` change. The app's capture-worker shape measured 351,989 B gzip with this part alone (2.18.0: 351,859 B; limit 352,000 B, not raised).
+  - **Owner decision (2026-11-09):** keep the line's 1/2000–1.024 s span; the limited line applies to `lens.prime` and `lens.catalogue` ranges as well as `lens.ideal`.
+  - **Tests:** `test/program-line-lens-range.test.ts` (byte pins; the limited line equals the old line clamped to the range at the same exposure at 201 points for ten ranges, from 1/2000 s to 1.024 s; program resolves within the range for seven ideal ranges at 5, 2000 and 200,000 lx; the 800 mm prime and *PV 800 9*); `test/ideal-lens.test.ts` updated (the refusal is now an exposure).
+  - **Docs:** docs/QUICK_START.md ("Program with a range"), docs/USAGE.md ("The capture facade's program line and the lens's f-number range").
+
+### #585 lens.ideal: a range narrower than about f/1 is refused in every exposure mode
+
+- **Fix (requests that 2.18.0 refused now resolve):** a `lens.ideal` range whose narrowest f-number N0 is below about f/1 (for example f/0.5–f/0.9) was refused in every exposure mode ("referenceExposure.shutterSeconds lies outside the resolved equipment capability range."): #569's exposure anchor at the range's aperture nearest f/8 with the same N²/t needs t = 1/125 s × (N0/8)², shorter than the body's shortest shutter (1/9877 s at f/0.9 against 1/8000 s). The anchor now takes the body's shortest shutter when that t is shorter, a lower N²/t. The anchor is only where the stops are measured from (CIPA DC-004 reference luminance from the camera equation at the anchor, the meter's relative signals and the resolvers all use it), so exposures are the same as with an f/8 anchor: aperture and shutter priority at f/0.7 and 1/4000 s resolve the open ideal lens's settings to 1e-12. The #583 program line's node stops are measured from the anchor. The `exposure.referenceExposure` explanation says "the shortest shutter at f/N0" in that case. Owner decision 2026-11-09: fix in 2.19.0.
+  - **Unchanged:** every request that resolved before gives the same bytes (SHA-256 pins of samples, RAW codes, exposure and assumptions for ten requests, including anchors off f/8 at f/9 and f/4 and a fixed f/1 lens). The app's capture-worker shape measures 351,990 B gzip (limit 352,000 B, not raised); the fix's code was paid for by sharing the range clamp between the anchor, the program line and the f-number check, and by a shorter program-line node table.
+  - **Tests:** `test/program-line-lens-range.test.ts` (f/0.5–f/0.9 in program with fixed and Auto ISO, aperture priority, shutter priority and manual; the pins).
+  - **Docs:** docs/QUICK_START.md ("An optional f-number range"), docs/USAGE.md.
+
+### #571 Develop joined parts: whole-image sharpening and diffraction correction
+
+- **New: `simulateCaptureFromParts(options, parts)`** (#571, for Photivra/apps#253's "Applying … to the whole image" step): develops the whole frame of `options` from region renders of the same request (the `SimulateCaptureDngPart` records `serializeSimulatedCaptureDngFromParts` takes, joined by the same code with the same checks), including `output.diffractionCorrection` and `output.sharpening`, which a region refuses. The joined RAW is the whole render's RAW, so `image.samples`, the JPEG or PNG bytes, `raw` and `plan` equal `simulateCapture(options)` bit for bit. Differences, documented: `diagnostics.providerEvaluationCount` is 0, `timingsMs` are the call's own (`raw` is the join), `diagnostics.fast` and the `raw.*` assumptions stay in the parts' results, and a new `parts` assumption (`{ partCount }`) records the join.
+- **Progress:** `SimulateCaptureProgress.stage` gains `"diffraction-correction"` and `"sharpening"`, one event per output row of the whole image (last event `completedTileCount === totalTileCount`), reported by `simulateCapture` too when those options are on; the stages yield to the host about every 8 ms, so `signal` now cancels them. `simulateCaptureFromParts` reports no `raw` stage. Code with an exhaustive `switch` over `stage` sees two new values.
+- **Memory:** the detail stages run row by row in place (`correctDiffractionInPlace`: an (R + 1)-row ring; `renderSdrWithUnsharpMaskInPlace`: each row encoded in place by the native SDR kernel, which takes `maximum` 0 for unquantized output, and a (2r + 1)-row ring of the horizontal pass), with the same sums in the same order: one developed image in memory instead of up to six. At 24 MP the whole `simulateCapture` with both stages peaked at 924 MiB (2.18.0: 3,670 MB, resident set sampled every 50 ms). Captures, files, diagnostics and assumptions of every request without `simulateCaptureFromParts` are unchanged (byte comparison of six detail requests against 2.18.0's build: JPEG, 16-bit, thresholded mask, Display P3 PNG, AHD with auto white balance and a push, a 3 × 2 image with σ = 8).
+- **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, shared machine, two runs; `node scripts/benchmark-joined-development.mjs`): join and develop 1.9–2.2 s and 532–551 MiB peak without a detail stage; with sharpening 3.3–3.7 s, with diffraction correction (R = 3) 3.7–3.9 s, 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–1,080 MiB peak each; the whole-frame `simulateCapture` with both took 10.0–10.4 s. The peak includes the parts' RAW and the joined RAW (7 bytes per native site each) and one 64-bit developed image (549 MiB).
+- **Root exports:** 1 new (runtime), 1,850 → 1,851: `simulateCaptureFromParts` (new module `src/facade/develop-joined-parts.ts`), named in the `simulate*` family of docs/API_STYLE.md (orchestration returning a `SimulateCaptureResult`), since "develop" is not one of the documented verb families. Messages of the parts join now read "Part k: …" and "The parts …" (were "DNG part k: …" and "The DNG parts …").
+- **Decisions (coordinator, 2026-11-09):** the name `simulateCaptureFromParts`; the extra Native performance workflow run that the change to `src/output/native-capture-sdr.ts` triggers is accepted; the two new progress stages count as additive (code with an exhaustive `switch` over `stage` must add them).
+- **Bundle (part branch):** the app's capture-worker shape was 351,929 B gzip (2.18.0: 351,852 B; limit 352,000 B, unchanged); with `simulateCaptureFromParts` added to the worker's imports, 351,937 B. The row-by-row stages add about 250 B; reusing the native SDR kernel for the unsharp mask's encoding and sharing the facade's row-progress and wide-gamut encoding code save about 170 B.
+- **Tests:** `test/simulate-capture-develop-parts.test.ts` (whole frame against joined parts byte for byte on six requests: JPEG with both stages, 16-bit with a thresholded mask, AHD with auto white balance, a push and the four-spot filter, Display P3 PNG with correction, DNG with both stages, no stage; progress order and rows; refusals and abort; the in-place stages against whole-image passes on odd sizes, R up to 16 on a 12 × 20 image).
+- **Docs:** docs/QUICK_START.md ("Developing a capture rendered in parts (#571)", the `onProgress` row, the sharpening section), docs/USAGE.md; API reference regenerated.
+
+### #570 Development option: apply lens corrections to the JPEG
+
+- **New: `output.lensCorrections: { distortion?, lateralColor?, vignetting? }`** (#570, for Photivra/apps#253 story 3.1), with `lens.catalogue`: the lens's generic correction profile (`createGenericLensCorrectionProfile`, #549) applied to the developed linear colour (after demosaic, colour, white balance and `diffractionCorrection`; before the tone curve and `sharpening`), for the JPEG, PNG and `image.samples`. Each correction is off unless `true`; all off (or omitted) develops byte for byte as before. **The RAW and the DNG are never corrected** (tested: identical DNG bytes).
+  - **Model** (labelled approximation, the new `output.lensCorrections` assumption): inverse mapping s = q(1 + k1|q|²/R²), q = m·a_c·p, bilinear, one resampling per channel; the image keeps its size and is magnified by 1/m, the smallest that leaves no missing pixel (1 for the barrel wide angles, 1.017 for *PV 300 5.6*). Vignetting is corrected to a flat field with det J/E at the source point, E the lens's relative illumination and 1/det J its distortion's area factor, which the capture applies (flat to 0.03 %; E alone would leave a *PV 16 2.8* corner about 18 % bright). The kernel matches `calculateLensCorrectedCapture` to 1e-12 for distortion and lateral colour.
+  - **Regions and parts:** byte-identical to the whole frame (barrel, pincushion with fill, AHD 16-bit PNG). A region develops the frame pixels its corrected pixels read (`developedRect`; `region.nativeRect`, `raw` and `plan` describe that rectangle).
+  - **Trade-offs measured through the option** (#552's): distortion correction × 0.706 corner detail (centre × 0.998); vignetting correction raises corner signal × 2.44 and noise × 2.50 (SNR unchanged).
+  - **Not offered** by `simulateDisplayView` or `simulateIdealReference` (refused by name); refused without `lens.catalogue`.
+  - **Cost:** about 1.3 s per 24 MP frame on one thread (Apple M5 Pro), loaded with the catalogue chunk on demand.
+  - **API:** one new root type, `SimulateCaptureLensCorrections`; `SIMULATE_CAPTURE_COST_OPTIONS` gains `"output.lensCorrections"`. `GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM` now lives in `src/output/developed-lens-corrections.ts` (same value, still a root export).
+  - **Owner decisions (2026-11-09):** zoom to fill (no missing pixels, no change of output size); the vignetting correction includes the distortion's area factor (the correction profile's own vignetting component, which holds E only, is follow-up #584); the display view refuses `output.lensCorrections` for now; the region rectangles (`developedRect` in the assumption; `region.nativeRect`, `raw` and `plan` for the developed rectangle) are accepted as they are.
+  - **Bundle:** on its own the part grew the app's capture-worker shape by 1,735 B gzip (entry +756 B, catalogue chunk +979 B), over the 352,000 B limit; the integration's shared helpers bring the release under it (see the 2.19.0 summary). The limit is not raised.
+  - **Docs and tests:** docs/DIGITAL_OPTICS_FOUNDATION.md ("Lens corrections in the development"), docs/QUICK_START.md, docs/USAGE.md; `test/simulate-capture-lens-corrections.test.ts`.
+
+## 2.18.0 — published November 9, 2026
+
+A minor release of four issues: equivalence numbers for teaching (#573), an ideal lens at any physical focal length and f-number (#576), catalogue lenses in the display view (#569) and fast catalogue lens captures (#568). Captures, RAW codes, files and assumptions are the same as 2.17.0 for every request that 2.17.0 renders and that uses none of the new options (every hash lock holds).
+- **New:** `calculateSensorEquivalence` and `calculateBlurShareOfFrame` (#573); `lens.ideal: { focalLengthMm, widestFNumber?, narrowestFNumber? }` and `IDEAL_LENS_LIMITS` (#576; the optional f-number range added at the owner's request, 2026-11-09); `simulateDisplayView` and `prepareDisplayView` render `lens.catalogue` (#569); a fast method for `lens.catalogue` behind `fast` or `lens.catalogue: { kind, fast }` (#568).
+- **Fixes** (requests that 2.17.0 refused): `subjectDistanceM` may equal twice the focal length, so the Macro's 1:1 close focus renders (#569); a lens whose range excludes f/8 (*PV 800 9*, f/9–f/32) takes the reference exposure at the aperture of its range nearest f/8 with the same N²/t, where every request with it failed (#569).
+- **Root exports:** 13 new, 1,837 → 1,850 (runtime exports 623 → 626): 11 from #573 (2 runtime), 1 from #576 (runtime), 1 from #568 (type). #569 adds none.
+- **Why minor:** new root exports and new opt-in options; requests that 2.17.0 refused now render (the display view with `lens.catalogue`, a subject at twice the focal length, *PV 800 9*). Nothing is removed or changed incompatibly, and no default changes. No `src/gpu` change.
+- **Bundle:** the app's capture-worker shape (every chunk of `NATIVE_RAW_LIMITS`, `prepareDisplayView`, `serializeSimulatedCaptureDngFromParts`, `simulateCapture`, `simulateIdealReference`) is 351,859 B gzip (2.17.0: 347,775 B): #568's lazily loaded fast catalogue code +2,907 B, #569's display-view catalogue PSF +550 B, the entry +397 B (the three parts' option handling), the ideal lens's f-number range +147 B. The integration saves 19 B (one closure for the tabulated paths' tables; unused grid axes removed). `test/capture-bundle.test.ts`'s limit is raised from 348,000 to 352,000 B (owner-approved 2026-11-09 for engine 2.18.0, #568's fast catalogue chunk). The display view adds 45,807 B minified and 18,128 B gzip to a capture bundle (2.17.0: 45,791 B and 18,159 B; budgets 46,500 B and 18,550 B, unchanged).
+- **Moved to 2.19.0:** #570, #571 and #566 (the owner's decision of 2026-11-09 to publish these four parts now; #566's breaking orientation fix, decided for 2.18.0 on 2026-11-07, moves with them).
+
+### #573 Equivalence for teaching: equivalent f-number, sensor area ratio and blur as a share of the frame
+
+- **New: `calculateSensorEquivalence({ sensor, focalLengthMm, fNumber, reference? })`** (model `sensor-equivalence` 1.0.0): for a lens on one sensor against 36 × 24 mm (or a `reference`), the crop factor, equivalent focal length, equivalent f-number (k·N, for depth of field, background blur and total light at the same framing and output size), the unchanged exposure f-number, entrance-pupil diameter, sensor area ratio, total-light difference in stops at the same f-number and shutter, and horizontal, vertical and diagonal angles of view. A `basis` record states, for every value, `"exact"` or `"approximation"` and its conditions; the equivalent f-number is a thin-lens approximation, exact only when the focus distance is much greater than the focal length (the exact thin-lens factor k·N·(s − f)/(s − k·f) is stated and tested). 50 mm f/2 on 23.5 × 15.6 mm gives ≈ 76.7 mm and ≈ f/3.07. With the default reference the crop factor and equivalent focal length are bit-identical to `calculateEquivalentFocalLength35Mm`.
+- **New: `calculateBlurShareOfFrame({ blurCircleMm, sensor, print? })`** (model `blur-share-of-frame` 1.0.0): a blur-circle diameter as a share of the frame diagonal, width and height, and with a print size, the enlargement (whole frame fitted, long side to long side) and the blur on the print.
+- **Root exports:** 11 new (2 runtime): the two functions and the types `CalculateSensorEquivalenceInput`, `SensorEquivalence`, `SensorEquivalenceFieldOfView`, `SensorEquivalenceQuantity`, `EquivalenceExactness`, `EquivalenceValueBasis`, `CalculateBlurShareOfFrameInput`, `BlurShareOfFrame`, `BlurShareOfPrint`. Pure functions; no capture, RAW or bundle change.
+- **Docs and tests:** docs/PHYSICS_FOUNDATION.md ("Sensor equivalence: f-number, area and blur share"), docs/USAGE.md, docs/AGENT_GUIDE.md, llms.txt, API reference task index; `test/sensor-equivalence.test.ts` (hand-checked values, the thin-lens check of the approximation, validation).
+
+### #576 Ideal lens at any physical focal length and f-number (capture and display view)
+
+- **New: `lens.ideal: { focalLengthMm }` (#576, for Photivra/apps#246, #250 and #251).** An ideal lens, an aberration-free thin lens named by its physical focal length, on whatever sensor the simulated frame is (no crop-factor scaling, unlike `lens.prime` and `lens.catalogue`), at any `lens.fNumber` from f/0.5 to f/128 and focal lengths of 1–4000 mm. f/0.5 is the physical limit of an aplanatic lens in air (the sine condition, N = 1/(2·sin θ′)); the other bounds are engine bounds. Values beyond them are refused by name (`lens.ideal.focalLengthMm must be 1–4000 mm (IDEAL_LENS_LIMITS).`, `lens.fNumber 0.45 is outside the ideal-50mm range f/0.5–f/128.`).
+  - **Model:** it replaces the tier lens's focal length and f-number range, as `lens.prime` does (the tier lens's transmission is kept); its blur is that of `lens.defocus`, `lens.diffraction` and `lens.vignetting`, the same models. No minimum focus distance beyond the thin-lens limits (subject at least twice the focal length away, with #569). Shutter priority and program may choose any aperture in f/0.5–f/128. Recorded in the new `lens.ideal` assumption (`{ lensId: "ideal-50mm", focalLengthMm: 50 }`).
+  - **Optional f-number range (owner, 2026-11-09):** `lens.ideal.widestFNumber` and `narrowestFNumber`, within `IDEAL_LENS_LIMITS` and widest ≤ narrowest (each defaults to its bound), narrow the range like a real lens's: `lens.fNumber` must lie in it and shutter priority chooses apertures only in it (1/4000 s, ISO 100 in 2000 lx: wider than f/1.4 over the whole range, f/1.4 with `widestFNumber: 1.4`). Program follows the engine's program line (f/4–f/16) and refuses a range that does not hold it, as for `lens.prime` and `lens.catalogue`. The assumption records the range only when given, so requests without it are unchanged. Refused: `lens.ideal.widestFNumber and narrowestFNumber must be f-numbers in f/0.5–f/128 (IDEAL_LENS_LIMITS), the widest no larger than the narrowest.`
+  - **Where:** `simulateCapture`, `simulateDisplayView` and `prepareDisplayView` (it goes through the shared request path). Not combinable with `lens.prime`, `lens.catalogue` or `lens.focalLengthMm`.
+  - **Tests** (`test/ideal-lens.test.ts`): 50 mm f/1.8 focused at 2.5 m with an edge at 3 m on full frame (7200 × 4800) and APS-C 23.5 × 15.6 mm (4700 × 3120) at 5 µm: the blur is `calculateDefocusCircle`'s 94.48 µm on both; the display view of the defocused edge equals the view of the disc's closed-form edge-spread function within 2.2e-14, and the capture equals the capture of that closed form byte for byte. Same pixels as the tier lens (`lens.focalLengthMm: 50`, f/4; with defocus and diffraction) and as the 50 mm-equivalent prime on a 36 × 24 mm frame at f/1.8. Bounds, every exposure mode and refusals.
+  - **API:** new root export `IDEAL_LENS_LIMITS` (runtime). `SimulateCaptureOptions.lens` gains `ideal`. The f-number range check of `lens.prime` and `lens.catalogue` now shares one code path (same messages).
+  - **Compatibility:** requests without `lens.ideal` give the same captures, RAW codes, files and assumptions. No `src/gpu` change.
+  - **Docs:** docs/QUICK_START.md ("Ideal lens at any focal length and f-number"), docs/USAGE.md, docs/AGENT_GUIDE.md; API reference regenerated.
+
+### #569 Display view: render catalogue lenses
+
+- **New: the display view renders `lens.catalogue` (#569, for Photivra/apps#251 and #252).** `simulateDisplayView` and `prepareDisplayView` accept the 30 generic catalogue lenses at every f-number of each lens's range and down to its close focus, with `lens.defocus` and `lens.focusScatter`, where 2.17.0 refused `lens.catalogue`. The lens's distortion, vignetting and fisheye projection go through #563's lens signal; its PSF is taken per field zone.
+  - **Model (an approximation, the new `view.lensPsf` assumption):** the native raster is cut into square zones of ⌈max(W, H) / 64⌉ sites (94 on 6000 × 4000; one site on frames of at most 64 sites a side), and every site of a zone takes the PSF the capture's own resolver gives at the zone's centre, at each spectral node; every tap reads the scene through the lens with its own field factor, as the capture's environment PSF quadrature does. Catalogue fisheyes see zero radiance beyond 90°, as in the capture. `createDisplayViewLensPsf` in `src/facade/display-view-lens-signal.ts`, loaded on demand; the zones' tables are the expected signal's own (`buildTables`, now exported internally).
+  - **Accuracy** (per site, against the capture's own site record and PSF quadrature): ≤ 2e-15 with one-site zones; 2.5e-3 with the box aperture, four-spot filter and defocus (the capture resolves the PSF at each query point); on a whole 6 µm full frame at most 0.66 % per site and 1.2e-4 on average over four hard lenses; all 30 lenses at their widest and narrowest f-number at close focus within 1 %. A slanted edge against the box-downsized capture is within the rectilinear test's 0.6-code RMS and 3-code maximum. Siemens-star boundary ties behave as with `lens.diffraction` (#565).
+  - **Cost** on the app's request (24 MP, 2028 × 1352 in 96 × 96 parts, one thread, loaded host): part medians 0.2–0.8 s for most lenses (1.9 s for the Macro at f/22) against 50–80 ms without a lens; 1.9–39× the no-lens view per display pixel (docs/DISPLAY_VIEW.md, "Catalogue lenses"). The CPU renders these requests; `gpu: "auto"` falls back, labelled `unsupported-on-backend`. `scripts/benchmark-display-view.mjs` gains `LENS=catalogue:<id>[:open|:<f-number>]`.
+  - **Capture fixes** (only requests that failed before change): `subjectDistanceM` may equal twice the focal length (the Macro's 1:1 close focus was refused); a lens whose range excludes f/8 (*PV 800 9*) takes the reference exposure at the aperture of its range nearest f/8 (its widest for *PV 800 9*) with the same N²/t, where every request with it failed.
+  - **Unchanged:** every request without `lens.catalogue` gives the same bytes; no root export is added; no `src/gpu` change. `lensGeometry`'s image-space mapping (#548) now honours `outsideImageCircle: "backward-ray"`, which only catalogue fisheyes set.
+  - **Docs and tests:** docs/DISPLAY_VIEW.md ("Catalogue lenses"), docs/LENS_CATALOGUE.md, docs/QUICK_START.md; `test/display-view-lens-catalogue.test.ts`.
+
+### #568 Fast catalogue lens captures for interactive use
+
+- **New: a fast method for `lens.catalogue` (#568, for Photivra/apps#251).** `fast: true` on a `simulateCapture` request, or the record form `lens: { catalogue: { kind: "<lens id>", fast }, fNumber }` (whose `fast` overrides the top-level flag), renders a catalogue lens from tabulated expected electrons instead of the environment PSF quadrature's per-tap scene queries. It is the first option with a fast method under the #395 convention: `lens.catalogue` joins `SIMULATE_CAPTURE_FAST_OPTIONS`, and without the flag the exact method runs unchanged.
+  - **Approximation (labeled):** the catalogue PSF is resolved exactly on a field grid (at least 4 cells between neighboring profile field nodes, more where the node kernels' centroids move by over 0.05 site per cell) and each site takes the bilinear blend of its four grid points' kernels instead of its own; distortion, vignetting and the fisheye projection are the exact method's. Reported in `diagnostics.fast` (`applied: { "lens.catalogue": true }`, `assurance: "approximation-with-a-priori-bound"`), the new `fast.lens.catalogue` assumption and `raw.expectedSignal` (method `tabulated-expected-electrons-catalogue-psf-field-grid`). One site per CFA phase runs the exact chain at run time and must agree within 0.5 %, or the exact method runs.
+  - **Accuracy against the exact method:** without the blend the sum equals the exact chain's within 1e-9; with it, site by site within 2.3e-4 of the frame's peak and 2.0e-3 of the site's own value (tested bounds 1e-3 and 5e-3); on the #549 charts the edge rise within 0.010 px, coma within 0.0001 px, lateral color within 0.003 px, distortion and vignetting unchanged (tested bounds 0.02 px and 0.005 stops).
+  - **Cost** (Apple M5 Pro, Node 24.19.0, one thread; Siemens star, whole full frame, f/8, PV 50 1.8 against `lens.prime` 50): 768 × 512 renders in 0.209 s against 0.145 s (1.44×; the issue's target was 2×) and 185 s with the exact method; 384 × 256 in 0.084 s (exact 47.5 s). `node scripts/benchmark-catalogue-capture.mjs` reproduces it (docs/LENS_CATALOGUE.md, "Fast method").
+  - **Where:** a still camera, site-center queries (no anti-aliasing filter or box pixel aperture) and a chart or material scene, in whole frames and regions, with or without `lens.defocus`; elsewhere the exact method runs and `applied` is `false`. The display view renders `lens.catalogue` with #569's per-zone PSF and never takes the fast method (`applied` is `false` there).
+  - **API:** one new root type export, `SimulateCaptureLensCatalogueRecord`; `SimulateCaptureOptions.lens.catalogue` also takes the record; `SIMULATE_CAPTURE_FAST_OPTIONS` gains `lens.catalogue`. Internal: `renderTabulatedNativeRaw` takes an optional verification tolerance.
+  - **Compatibility:** every request without `fast: true` (or the record's `fast`) renders byte-identically to 2.17.0. A request that already passed `fast: true` with `lens.catalogue` now takes the fast method.
+
+## 2.17.0 — published November 8, 2026
 
 A minor release of four issues: large defocus discs (#564), bokeh character (#553), lens projection, distortion, vignetting and rotation in the display view (#563), and the generic lens catalogue (#549). Captures, RAW codes, files and assumptions are the same as 2.16.0 for every request that 2.16.0 renders and that uses none of the new options (every hash lock holds).
 - **New:** `lens.defocus` up to a kernel radius of 512 sites (#564); `lens.defocus.blades`, `sphericalAberration` and `catsEye` and `calculateDefocusBokehKernel` (#553); the display view with `lens.projection`, `lens.distortion`, `lens.vignetting` and global-shutter rotation (#563); `lens.catalogue`, `lens.focusScatter` and the 30-lens `GENERIC_LENS_CATALOGUE`, each lens with a short `summary` (#549).

package/CITATION.cff

@@ -9,7 +9,7 @@ abstract: "An open TypeScript engine for the science and mathematics of photogra
 repository-code: "https://github.com/photivra/photivra"
 url: "https://photivra.com"
 license: "Apache-2.0"
-version: "2.17.0"
+version: "2.19.0"
 keywords:
   - photography
   - camera optics

package/README.md

@@ -32,10 +32,10 @@ The source is licensed under Apache-2.0.
 
 ## Quick start
 
-Install the published ESM package below. The [2.17.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_17_0.md) and [changelog](https://github.com/Photivra/photivra/blob/main/CHANGELOG.md) describe the current release:
+Install the published ESM package below. The [2.19.0 release record](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_2_19_0.md) and [changelog](https://github.com/Photivra/photivra/blob/main/CHANGELOG.md) describe the current release:
 
 ```sh
-npm install @photivra/engine@2.17.0
+npm install @photivra/engine@2.19.0
 ```
 
 Simulate a photograph of a test chart with a generic camera, then read the developed sRGB pixels:
@@ -75,7 +75,7 @@ console.log(horizontal.provenance);
 
 Start with the [Developer Guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Then use the [Usage Guide](https://github.com/Photivra/photivra/blob/main/docs/USAGE.md) and the [API reference](https://github.com/Photivra/photivra/blob/main/docs/API_REFERENCE.md), which is generated from the package exports.
 
-Repository `main` may describe newer, unreleased work. For the stable contract, use the docs bundled in the published package, or the exact `v2.17.0` tag.
+Repository `main` may describe newer, unreleased work. For the stable contract, use the docs bundled in the published package, or the exact `v2.19.0` tag.
 
 ## Documentation
 
@@ -363,13 +363,13 @@ The application can then use those results, while the photography calculations t
 
 ## Status
 
-- Repository package version: `2.17.0` (release candidate prepared November 7, 2026; publication is separate)
-- Engine API contract: `2.17.0`
+- Repository package version: `2.19.0` (release candidate prepared November 9, 2026; publication is separate)
+- Engine API contract: `2.19.0`
 - Versioned generic tier reference assets: [GENERIC_TIER_PRESETS.md](https://github.com/Photivra/photivra/blob/main/docs/GENERIC_TIER_PRESETS.md).
 - Composed POC simulation API contract: `1.0.0`
 - Stability: 1.0 root-package compatibility policy; bounded scientific models and independent POC contract
 
-From 1.0.1, the package version and `ENGINE_API_VERSION` are equal. New captures/plans record 2.17.0; existing archives keep their original creator identities. Schema, model and POC contract versions stay independent.
+From 1.0.1, the package version and `ENGINE_API_VERSION` are equal. New captures/plans record 2.19.0; existing archives keep their original creator identities. Schema, model and POC contract versions stay independent.
 
 A breaking change to the root contracts now needs a new package major version. Additive and corrective changes follow [compatibility and migration](https://github.com/Photivra/photivra/blob/main/docs/RELEASE_1_3_0.md). A 1.0 package is not a claim of calibrated physical accuracy.
 

package/SECURITY.md

@@ -4,7 +4,7 @@ Please do not open a public issue that contains vulnerability details.
 
 ## Supported versions
 
-The published 1.0.0 release started the 1.x root-package compatibility line, and 2.0.0 started the 2.x line. The current release is **2.16.0**, published on November 7, 2026 (see [CHANGELOG.md](CHANGELOG.md)).
+The published 1.0.0 release started the 1.x root-package compatibility line, and 2.0.0 started the 2.x line. The current release is **2.18.0**, published on November 9, 2026 (see [CHANGELOG.md](CHANGELOG.md)).
 
 Security fixes target the current maintained development and release line. Do not assume that older 1.x releases, snapshots or pre-1.0 releases will receive fixes.
 

package/dist/camera/sensor-equivalence.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Format equivalence for teaching: what a lens of focal length f at f-number N on one sensor
+ * corresponds to on a reference format (36 × 24 mm by default), and how large a blur circle is
+ * as a share of the frame or of a print.
+ *
+ * With the diagonal crop factor k = referenceDiagonal / sensorDiagonal:
+ * - equivalent focal length k·f (same diagonal angle of view; exact by the diagonal convention);
+ * - equivalent f-number k·N for depth of field, background blur and total light (same framing,
+ *   same output size). It keeps the entrance-pupil diameter f/N unchanged. It is an
+ *   approximation: in the thin-lens defocus-circle equation it is exact only when the focus
+ *   distance is much greater than the focal length;
+ * - the f-number for exposure stays N: image illuminance depends on N, not on the sensor size;
+ * - sensor area ratio and the total-light difference in stops at the same f-number and shutter.
+ *
+ * Sources (free): thin-lens defocus-circle diameter f²|s − d|/(N d (s − f)) and f-number N = f/D,
+ * Greivenkamp, OPTI-502 course notes, sec. 12 (Objectives),
+ * https://wp.optics.arizona.edu/jgreivenkamp/wp-content/uploads/sites/11/2019/08/502-12-Objectives.pdf;
+ * image illuminance proportional to 1/N², sec. 11 (Radiative transfer),
+ * https://wp.optics.arizona.edu/jgreivenkamp/wp-content/uploads/sites/11/2019/08/502-11-Radiative-Transfer.pdf.
+ * @see docs/PHYSICS_FOUNDATION.md "Sensor equivalence" for the derivation, the exact and
+ * approximated quantities, and support limits.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type SensorImagingArea } from "../sensor/sensor-geometry.js";
+/** Whether a value is exact under its stated conditions or an approximation. */
+export type EquivalenceExactness = "exact" | "approximation";
+/** How one equivalence quantity was obtained, and under which conditions it holds. */
+export interface EquivalenceValueBasis {
+    /** `"exact"` under the stated conditions, or `"approximation"`. */
+    kind: EquivalenceExactness;
+    /** Plain statement of the definition and its conditions. */
+    statement: string;
+}
+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;
+}
+/** Angles of view of an ideal rectilinear lens focused at infinity, in degrees. */
+export interface SensorEquivalenceFieldOfView {
+    horizontalDegrees: number;
+    verticalDegrees: number;
+    diagonalDegrees: number;
+}
+/** Quantities of a sensor equivalence result that carry an exactness statement. */
+export type SensorEquivalenceQuantity = "cropFactor" | "equivalentFocalLengthMm" | "equivalentFNumber" | "exposureFNumber" | "entrancePupilDiameterMm" | "areaRatio" | "totalLightDifferenceStops" | "fieldOfView";
+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>>;
+}
+/**
+ * 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.
+ *
+ * @param input Sensor active area, focal length, f-number and optional reference format.
+ * @returns The equivalence numbers with a per-quantity exactness statement.
+ */
+export declare function calculateSensorEquivalence(input: CalculateSensorEquivalenceInput): CalculationResult<SensorEquivalence>;
+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;
+    };
+}
+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;
+}
+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;
+}
+/**
+ * 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.
+ *
+ * @param input Blur diameter in millimetres, sensor active area and optional print size.
+ * @returns Shares of the frame, and the blur on the print when a print is given.
+ */
+export declare function calculateBlurShareOfFrame(input: CalculateBlurShareOfFrameInput): CalculationResult<BlurShareOfFrame>;

package/dist/camera/sensor-equivalence.js

@@ -0,0 +1,208 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Format equivalence for teaching: what a lens of focal length f at f-number N on one sensor
+ * corresponds to on a reference format (36 × 24 mm by default), and how large a blur circle is
+ * as a share of the frame or of a print.
+ *
+ * With the diagonal crop factor k = referenceDiagonal / sensorDiagonal:
+ * - equivalent focal length k·f (same diagonal angle of view; exact by the diagonal convention);
+ * - equivalent f-number k·N for depth of field, background blur and total light (same framing,
+ *   same output size). It keeps the entrance-pupil diameter f/N unchanged. It is an
+ *   approximation: in the thin-lens defocus-circle equation it is exact only when the focus
+ *   distance is much greater than the focal length;
+ * - the f-number for exposure stays N: image illuminance depends on N, not on the sensor size;
+ * - sensor area ratio and the total-light difference in stops at the same f-number and shutter.
+ *
+ * Sources (free): thin-lens defocus-circle diameter f²|s − d|/(N d (s − f)) and f-number N = f/D,
+ * Greivenkamp, OPTI-502 course notes, sec. 12 (Objectives),
+ * https://wp.optics.arizona.edu/jgreivenkamp/wp-content/uploads/sites/11/2019/08/502-12-Objectives.pdf;
+ * image illuminance proportional to 1/N², sec. 11 (Radiative transfer),
+ * https://wp.optics.arizona.edu/jgreivenkamp/wp-content/uploads/sites/11/2019/08/502-11-Radiative-Transfer.pdf.
+ * @see docs/PHYSICS_FOUNDATION.md "Sensor equivalence" for the derivation, the exact and
+ * approximated quantities, and support limits.
+ */
+import { approximationResult, calculatedResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
+import { portableHypot, portableLog2 } from "../core/portable-math.js";
+import { requireInputKeys, requireInputObject } from "../core/record-validation.js";
+import { calculateImagingAreaMetrics } from "../sensor/sensor-geometry.js";
+/** The default equivalence reference: the 36 × 24 mm frame. */
+const REFERENCE_FULL_FRAME = Object.freeze({ widthMm: 36, heightMm: 24 });
+const SENSOR_EQUIVALENCE_BASIS = Object.freeze({
+    cropFactor: Object.freeze({
+        kind: "exact",
+        statement: "Ratio of the reference diagonal to the sensor diagonal (diagonal convention)."
+    }),
+    equivalentFocalLengthMm: Object.freeze({
+        kind: "exact",
+        statement: "Same diagonal angle of view on the reference format, for an ideal rectilinear lens focused at infinity. " +
+            "Horizontal and vertical angles match too only when the aspect ratios match."
+    }),
+    equivalentFNumber: Object.freeze({
+        kind: "approximation",
+        statement: "Same depth of field and background blur as a share of the frame, at the same subject distance, framing and output size, " +
+            "and the same entrance-pupil diameter (so the same total light at the same shutter time). In the thin-lens defocus equation it is exact " +
+            "only when the focus distance s is much greater than the focal length f; with focal lengths in the ratio cropFactor, the blur shares match " +
+            "at cropFactor·N·(s − f)/(s − cropFactor·f). " +
+            "Total light matches exactly only when the aspect ratios match. It does not set exposure."
+    }),
+    exposureFNumber: Object.freeze({
+        kind: "exact",
+        statement: "Image illuminance is proportional to 1/N², independent of sensor size (ideal lens; transmission, vignetting and " +
+            "close-focus bellows factor excluded). Equivalence never changes the exposure setting."
+    }),
+    entrancePupilDiameterMm: Object.freeze({
+        kind: "exact",
+        statement: "Entrance-pupil diameter D = f/N by the definition of the f-number. The equivalent lens (cropFactor·f at cropFactor·N) has the same D."
+    }),
+    areaRatio: Object.freeze({
+        kind: "exact",
+        statement: "Product of width and height of the sensor divided by that of the reference."
+    }),
+    totalLightDifferenceStops: Object.freeze({
+        kind: "exact",
+        statement: "log2 of the area ratio: at the same f-number, shutter time and scene the image illuminance is the same, so total light scales " +
+            "with area (uniform illuminance; vignetting excluded)."
+    }),
+    fieldOfView: Object.freeze({
+        kind: "exact",
+        statement: "2·atan(dimension / 2f) for an ideal rectilinear lens focused at infinity; distortion and focus breathing excluded."
+    })
+});
+function requireImagingArea(area, label) {
+    requireInputObject(area, label);
+    requireInputKeys(area, label, ["widthMm", "heightMm"]);
+    const record = area;
+    requirePositiveFinite(`${label}.widthMm`, record.widthMm);
+    requirePositiveFinite(`${label}.heightMm`, record.heightMm);
+}
+/** √((rw² + rh²)/(w² + h²)), with only correctly rounded operations when nothing overflows (portable). */
+function diagonalRatio(reference, sensor) {
+    const referenceSquared = reference.widthMm * reference.widthMm + reference.heightMm * reference.heightMm;
+    const sensorSquared = sensor.widthMm * sensor.widthMm + sensor.heightMm * sensor.heightMm;
+    const ratio = referenceSquared / sensorSquared;
+    return Number.isFinite(referenceSquared) && Number.isFinite(sensorSquared) && sensorSquared > 0 && ratio > 0 && Number.isFinite(ratio)
+        ? Math.sqrt(ratio)
+        : portableHypot(reference.widthMm, reference.heightMm) / portableHypot(sensor.widthMm, sensor.heightMm);
+}
+function rectilinearAngleDegrees(dimensionMm, focalLengthMm) {
+    return (2 * Math.atan(dimensionMm / (2 * focalLengthMm)) * 180) / Math.PI;
+}
+/**
+ * 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.
+ *
+ * @param input Sensor active area, focal length, f-number and optional reference format.
+ * @returns The equivalence numbers with a per-quantity exactness statement.
+ */
+export function calculateSensorEquivalence(input) {
+    requireInputKeys(input, "calculateSensorEquivalence", ["sensor", "focalLengthMm", "fNumber", "reference"]);
+    requireImagingArea(input.sensor, "sensor");
+    requirePositiveFinite("focalLengthMm", input.focalLengthMm);
+    requirePositiveFinite("fNumber", input.fNumber);
+    if (input.reference !== undefined)
+        requireImagingArea(input.reference, "reference");
+    const sensor = { widthMm: input.sensor.widthMm, heightMm: input.sensor.heightMm };
+    const reference = input.reference === undefined
+        ? { ...REFERENCE_FULL_FRAME }
+        : { widthMm: input.reference.widthMm, heightMm: input.reference.heightMm };
+    // The default reference reuses the canonical 35 mm crop factor, so it is bit-identical to
+    // calculateEquivalentFocalLength35Mm and calculateImagingAreaMetrics.
+    const cropFactor = input.reference === undefined
+        ? calculateImagingAreaMetrics(sensor).value.cropFactor35Mm
+        : diagonalRatio(reference, sensor);
+    const areaRatio = (sensor.widthMm / reference.widthMm) * (sensor.heightMm / reference.heightMm);
+    const sensorDiagonalMm = portableHypot(sensor.widthMm, sensor.heightMm);
+    if (!(areaRatio > 0) || !Number.isFinite(areaRatio)) {
+        throw new InvalidScientificInputError("sensor and reference areas must differ by a ratio that is a finite number greater than zero.");
+    }
+    return approximationResult({
+        focalLengthMm: input.focalLengthMm,
+        fNumber: input.fNumber,
+        sensor,
+        reference,
+        sensorDiagonalMm,
+        referenceDiagonalMm: portableHypot(reference.widthMm, reference.heightMm),
+        cropFactor,
+        equivalentFocalLengthMm: input.focalLengthMm * cropFactor,
+        equivalentFNumber: input.fNumber * cropFactor,
+        exposureFNumber: input.fNumber,
+        entrancePupilDiameterMm: input.focalLengthMm / input.fNumber,
+        areaRatio,
+        totalLightDifferenceStops: portableLog2(areaRatio),
+        fieldOfView: {
+            horizontalDegrees: rectilinearAngleDegrees(sensor.widthMm, input.focalLengthMm),
+            verticalDegrees: rectilinearAngleDegrees(sensor.heightMm, input.focalLengthMm),
+            diagonalDegrees: rectilinearAngleDegrees(sensorDiagonalMm, input.focalLengthMm)
+        },
+        basis: SENSOR_EQUIVALENCE_BASIS
+    }, "sensor-equivalence", "1.0.0", [
+        "Crop factor and equivalence are diagonal-based against the reference format (36 × 24 mm unless given).",
+        "Equivalent f-number concerns depth of field, background blur and total light for the same framing and output size; it is not an exposure setting.",
+        "Equivalent f-number is a thin-lens approximation, exact when the focus distance is much greater than the focal length.",
+        "Exposure f-number is the f-number on the lens: image illuminance does not depend on sensor size.",
+        "Ideal rectilinear lens focused at infinity; distortion, vignetting, transmission and focus breathing excluded.",
+        "Physical focal length and f-number are not changed; see basis for each quantity."
+    ]);
+}
+/**
+ * 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.
+ *
+ * @param input Blur diameter in millimetres, sensor active area and optional print size.
+ * @returns Shares of the frame, and the blur on the print when a print is given.
+ */
+export function calculateBlurShareOfFrame(input) {
+    requireInputKeys(input, "calculateBlurShareOfFrame", ["blurCircleMm", "sensor", "print"]);
+    if (typeof input.blurCircleMm !== "number" || !Number.isFinite(input.blurCircleMm) || input.blurCircleMm < 0) {
+        throw new InvalidScientificInputError("blurCircleMm must be a finite number greater than or equal to zero.");
+    }
+    requireImagingArea(input.sensor, "sensor");
+    if (input.print !== undefined)
+        requireImagingArea(input.print, "print");
+    const { widthMm, heightMm } = input.sensor;
+    const blurCircleMm = input.blurCircleMm;
+    const frameDiagonalMm = portableHypot(widthMm, heightMm);
+    let print;
+    if (input.print !== undefined) {
+        const sensorLong = Math.max(widthMm, heightMm), sensorShort = Math.min(widthMm, heightMm);
+        const printLong = Math.max(input.print.widthMm, input.print.heightMm), printShort = Math.min(input.print.widthMm, input.print.heightMm);
+        const enlargement = Math.min(printLong / sensorLong, printShort / sensorShort);
+        if (!(enlargement > 0) || !Number.isFinite(enlargement)) {
+            throw new InvalidScientificInputError("print enlargement must be a finite number greater than zero.");
+        }
+        print = {
+            enlargement,
+            blurOnPrintMm: blurCircleMm * enlargement,
+            imageLongSideMm: sensorLong * enlargement,
+            imageShortSideMm: sensorShort * enlargement
+        };
+    }
+    return calculatedResult({
+        blurCircleMm,
+        frameDiagonalMm,
+        shareOfDiagonal: blurCircleMm / frameDiagonalMm,
+        shareOfWidth: blurCircleMm / widthMm,
+        shareOfHeight: blurCircleMm / heightMm,
+        ...(print === undefined ? {} : { print })
+    }, "blur-share-of-frame", "1.0.0", [
+        "Shares are exact ratios of the blur diameter to the active frame's diagonal, width and height.",
+        "A print shows the whole frame enlarged to fit inside it without cropping, long side to long side.",
+        "Visibility of the blur depends on viewing distance and acuity; no acceptability criterion is applied."
+    ]);
+}
+//# sourceMappingURL=sensor-equivalence.js.map