@photivra/engine 2.19.0 → 2.21.0

package/docs/api/output-generic-lens-corrections.md

@@ -2,11 +2,44 @@
 
 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.
 
+## calculateChannelEffectiveDispersion
+
+#589: each channel's effective dispersion for the catalogue lenses' lateral colour, D̄_c = Σ w·D(λ) / Σ w with
+w = response_c(λ)·illuminant(λ) at the nodes and D the normalised Cauchy dispersion (`genericLensDispersion`: 0 at the
+Fraunhofer d line, F minus C = 1). Under lateral colour L·r·D(λ) a neutral surface's image in channel c moves by L·r·D̄_c, so
+blue minus red is L·r·(D̄_blue − D̄_red). Pass the result as `channelDispersion` to `createGenericLensCorrectionProfile`.
+`simulateCapture`'s `output.lensCorrections` computes it from the capture's own channels and reports it in its assumption.
+An approximation: a weighted mean over a neutral surface; a colored surface weights the band differently.
+
+```ts
+export function calculateChannelEffectiveDispersion(input: CalculateChannelEffectiveDispersionInput): CalculationResult<ChannelDispersion>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateChannelEffectiveDispersionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateChannelEffectiveDispersionInput {
+  /** Spectral nodes, nm, strictly increasing, within 300–1100 nm. */
+  wavelengthsNm: readonly number[];
+  /** Each channel's response at the nodes (any common linear unit, ≥ 0; for example electrons per unit spectral radiance). */
+  channelResponse: { red: readonly number[]; green: readonly number[]; blue: readonly number[] };
+  /** The illuminant's relative spectral power at the nodes (≥ 0; the scale cancels). */
+  illuminant: readonly number[];
+}
+```
+
 ## createGenericLensCorrectionProfile
 
 Builds the catalogue lens's generic correction profile for one camera state: a radial distortion map (the lens's own
-r_d = r(1 + k1ρ²), read at each ideal destination point), per-channel lateral-colour scales 1 + L·D(λ_channel), and the
-relative-illumination gain at the state's aperture (strength 1). The result passes `parseGenericLensCorrectionProfile`.
+r_d = r(1 + k1ρ²), read at each ideal destination point), per-channel lateral-colour scales 1 + L·D̄_channel (`channelDispersion`,
+by default D at the generic channel wavelengths), and the relative-illumination gain at the state's aperture (strength 1). From
+profile version 1.1.0 (#584) the vignetting component (version 1.1.0) carries the distortion's area factor
+(`distortionAreaFactor`): its gain is det J(ρ_i)/E(ρ_s) at the capture's sensor point, so it flattens a flat-field capture. The
+result passes `parseGenericLensCorrectionProfile`.
 
 ```ts
 export function createGenericLensCorrectionProfile(input: CreateGenericLensCorrectionProfileInput): GenericLensCorrectionProfile;
@@ -26,5 +59,10 @@ export interface CreateGenericLensCorrectionProfileInput {
   activeImagingArea: { widthMm: number; heightMm: number };
   /** The exact camera state the profile applies to: its focal length must be the lens's on this sensor, its aperture in range. */
   state: OpticalProfileState;
+  /**
+   * #589: each channel's effective dispersion (`calculateChannelEffectiveDispersion` for the camera's channels and the light).
+   * Default: D at {@link GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM} (610, 540 and 465 nm), a generic approximation.
+   */
+  channelDispersion?: ChannelDispersion;
 }
 ```

package/docs/api/output-lens-corrections.md

@@ -31,7 +31,9 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 ## calculatePeripheralIlluminationCorrection
 
 Applies a gain after capture and reports the variance before clipping. It does not rewrite
-the photon or SNR (signal-to-noise ratio) history of the capture.
+the photon or SNR (signal-to-noise ratio) history of the capture. The gain is T^(−strength), T the relative illumination at
+`imagePointMm`: E(ρ) of the component's profile, divided by det J(ρ_i) when the component has a `distortionAreaFactor` (#584;
+then `imagePointMm` is the capture's sensor point, where the capture applied both).
 
 ```ts
 export function calculatePeripheralIlluminationCorrection(input: {
@@ -77,6 +79,14 @@ export interface IlluminationLensCorrection extends CorrectionComponentIdentity
   kind: "peripheral-illumination";
   profile: IlluminationVignettingProfile;
   strength: number;
+  /**
+   * Optional (#584): the capture's radial distortion r_d = r(1 + k1ρ² + k2ρ⁴ + k3ρ⁶), whose area factor 1/det J the capture also
+   * multiplied into the irradiance (det J = (1 + k1ρ_i² + k2ρ_i⁴ + k3ρ_i⁶)(1 + 3k1ρ_i² + 5k2ρ_i⁴ + 7k3ρ_i⁶) at the ideal point ρ_i that
+   * the lens images to the sensor point). With it, the relative illumination corrected is E(ρ_s)/det J(ρ_i), evaluated at the
+   * capture's sensor (source) point, so strength 1 flattens a flat field. It holds whether or not the distortion itself is corrected.
+   * Without it the gain is 1/E alone, as before.
+   */
+  distortionAreaFactor?: RadialDistortionProfile;
 }
 ```
 

package/docs/api/output-print-plan.md

@@ -42,14 +42,44 @@ export function parsePrintPlanInput(value: unknown): PrintPlanInput;
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## PrintContainLayout
+
+The layout of a `contain` fit, in millimetres. The printed image itself is the plan's `printedImageMm`.
+
+```ts
+export interface PrintContainLayout {
+  /** The paper as placed: after the quarter turn when `paperRotated`. */
+  paperMm: { width: number; height: number };
+  paperRotated: boolean;
+  /** Unprinted border on each side of the centered image; zero when the paper has the image's aspect ratio. */
+  bordersMm: { left: number; right: number; top: number; bottom: number };
+}
+```
+
 ## PrintedImageSize
 
 The flat printed image area. It excludes paper margins, borders and canvas wraps.
+With a `contain` fit it is instead the paper, or the printable area of it, that the image is fitted inside.
 
 ```ts
 export interface PrintedImageSize { width: number; height: number; unit: PrintLength["unit"] }
 ```
 
+## PrintFit
+
+How the printed image relates to `printedImage`.
+- `confirmed-native-aspect`: `printedImage` is the printed image itself and must already have the native aspect ratio,
+ within the stated relative error.
+- `contain`: `printedImage` is the paper. The image keeps the native aspect ratio and is scaled to the largest size that
+ fits inside it, centered; the rest is unprinted border. `match-image` turns the paper a quarter turn when its
+ orientation (portrait or landscape) differs from the image's; `as-given` keeps it. Layout only: nothing is cropped or resampled.
+
+```ts
+export type PrintFit =
+  | { kind: "confirmed-native-aspect"; maximumRelativeAspectError: number }
+  | { kind: "contain"; paperOrientation: "as-given" | "match-image" };
+```
+
 ## PrintLength
 
 A physical length. Not to be confused with image pixels or printer dots.
@@ -90,6 +120,8 @@ export interface PrintPlan {
   alternatives: { maximumImageMmAtCurrentDistance: { width: number; height: number }; minimumViewingDistanceMmAtCurrentSize: number | null } | null;
   capturedDetailAssessment: "unassessed";
   deliveryAssessment: "unassessed";
+  /** Present only with a `contain` fit; null when the native raster is unknown. */
+  contain?: PrintContainLayout | null;
 }
 ```
 
@@ -103,7 +135,7 @@ export interface PrintPlanInput {
   printedImage: PrintedImageSize;
   viewingDistance: PrintLength;
   sampling: PrintSamplingCriterion;
-  fit: { kind: "confirmed-native-aspect"; maximumRelativeAspectError: number };
+  fit: PrintFit;
   provider?: PrintProviderConstraints;
 }
 ```
@@ -156,6 +188,8 @@ export interface PrintSizeLimit {
   maximumImageMm: { width: number; height: number } | null;
   reasons: string[];
   referencePlan: PrintPlan;
+  /** Present only with a `contain` fit: the paper that holds `maximumImageMm` with the same layout (borders scale with it). */
+  maximumPaperMm?: { width: number; height: number } | null;
 }
 ```
 

package/docs/api/output-print-size-blur-noise.md

@@ -0,0 +1,115 @@
+# output/print-size-blur-noise.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.
+
+## calculatePrintSizeLimitWithBlurAndNoise
+
+Calculates the largest print, at a fixed viewing distance, at which the capture still looks sharp and clean, and names
+the factor that limits it: pixels, blur or noise. An approximation throughout; the equations are exact under its model.
+
+With θ the criterion angle, d the viewing distance, s = 2 d tan(θ/2) the length θ covers on the print, N_w the raster
+width in pixels, b the blur diameter in pixels and SNR_px the per-pixel SNR (print width W, height in proportion):
+- pixels: a print pixel (W / N_w) may cover at most s, so W ≤ N_w·s (as `calculatePrintPlan` with
+ `angular-pixel-pitch`, before its whole-pixel rounding);
+- blur: the blur on the print (b·W / N_w) may cover at most s, so W ≤ N_w·s / b: the criterion of an acceptable circle
+ of confusion with the eye's resolution as the limit;
+- noise: the eye averages the (W / N_w) wide pixels inside s, so the visible SNR is SNR_px·(N_w·s / W) while a pixel is
+ smaller than s (the mean of n independent values has 1/√n of their standard deviation); W ≤ N_w·s·SNR_px / SNR_min,
+ and noise never limits when SNR_px ≥ SNR_min.
+One arcminute is normal (20/20) acuity under optimal conditions (Z. Alomar, K. D. Bojikian, "Visual Acuity Testing in
+Adults", EyeWiki, American Academy of Ophthalmology, https://eyewiki.aao.org/Visual_Acuity_Testing_in_Adults, last edited
+June 16, 2026); the SNR threshold has no default and is the caller's. Blur parts add in root-sum-square, which is exact
+for Gaussian spots (variances of independent displacements add: C. M. Grinstead, J. L. Snell, "Introduction to
+Probability", 2nd rev. ed., AMS 1997, sec. 6.2, free under the GNU FDL) and an approximation for discs and Airy patterns.
+
+```ts
+export function calculatePrintSizeLimitWithBlurAndNoise(value: PrintSizeLimitWithBlurAndNoiseInput): CalculationResult<PrintSizeLimitWithBlurAndNoise>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PrintBlurInput
+
+The capture's blur at the sensor plane, as blur-spot diameters in millimetres.
+`components` combines the parts by root-sum-square (an approximation, see the docs); `measured-total` is one measured diameter.
+A zero component is allowed and means that part is left out. Engine helpers give the parts: `calculateDefocusCircle` (defocus),
+`calculateAiryDisk` (diffraction, micrometres), `calculateProjectedMotionBlur` (motion length).
+
+```ts
+export type PrintBlurInput =
+  | { kind: "components"; lensMm?: number; defocusMm?: number; diffractionMm?: number; motionMm?: number }
+  | { kind: "measured-total"; diameterMm: number };
+```
+
+## PrintImageMm
+
+A print size in millimetres at the raster's aspect ratio.
+
+```ts
+export interface PrintImageMm { width: number; height: number }
+```
+
+## PrintNoiseInput
+
+The noise of one pixel of the printed raster, for the tone the caller cares about (for example mid-gray).
+`shot-and-read-noise` uses the engine's noise model (`calculateSignalToNoise`: Poisson shot noise plus RMS read noise);
+`pixel-snr` is a per-pixel signal-to-noise ratio the caller already has. `capture-noise-figure` (2.20.0) takes a capture's own
+mid-gray noise figure (#535: `result.sensor.midGrey` of a `simulateCapture` with `fast: false`), whose SNR S/σ_total counts photon
+shot, read, dark-current, quantization and any fixed-pattern noise; it is one sensor site's, so it applies as the pixel SNR when one
+printed pixel is one capture pixel. A clipped figure (the patch at white) is refused.
+
+```ts
+export type PrintNoiseInput =
+  | { kind: "shot-and-read-noise"; signalElectrons: number; readNoiseElectrons: number }
+  | { kind: "pixel-snr"; snrLinear: number }
+  | { kind: "capture-noise-figure"; midGrey: NonNullable<SimulateCaptureSensorReport["midGrey"]> };
+```
+
+## PrintSharpCleanCriterion
+
+What "looks sharp and clean" means: the smallest angle the viewer resolves, and the lowest signal-to-noise ratio the viewer
+accepts after the eye averages over that angle. Both are the caller's choice; one arcminute is normal (20/20) acuity.
+
+```ts
+export interface PrintSharpCleanCriterion {
+  kind: "visual-resolution";
+  arcminutes: number;
+  minimumVisibleSnr: number;
+}
+```
+
+## PrintSizeLimitWithBlurAndNoise
+
+Result. Each factor's own limit is the largest print it allows on its own; null means that factor never limits.
+`limitingFactor` names the smallest; on a tie the order is pixels, blur, noise.
+
+```ts
+export interface PrintSizeLimitWithBlurAndNoise {
+  engineApiVersion: string;
+  status: "finite" | "no-positive-size";
+  limitingFactor: "pixels" | "blur" | "noise";
+  maximumImageMm: PrintImageMm;
+  limits: { pixels: PrintImageMm; blur: PrintImageMm | null; noise: PrintImageMm | null };
+  viewingDistanceMm: number;
+  /** The criterion angle as a length on the print at the viewing distance: 2 d tan(θ/2). */
+  resolvedSpotMm: number;
+  blur: { diameterMm: number; diameterPixels: number; largestComponent: "lens" | "defocus" | "diffraction" | "motion" | "measured-total" | null };
+  noise: { pixelSnr: number; visibleSnrAtMaximum: number };
+}
+```
+
+## PrintSizeLimitWithBlurAndNoiseInput
+
+Input. The raster is the retained image that is printed (after any crop), with square pixels; `pixelPitchMm` is the
+sensor length one of those pixels covers. The print keeps the raster's aspect ratio. The viewing distance is fixed.
+
+```ts
+export interface PrintSizeLimitWithBlurAndNoiseInput {
+  raster: RasterDimensions;
+  pixelPitchMm: number;
+  viewingDistance: PrintLength;
+  criterion: PrintSharpCleanCriterion;
+  blur: PrintBlurInput;
+  noise: PrintNoiseInput;
+}
+```

package/docs/api/sensor-sensor-characteristics.md

@@ -0,0 +1,105 @@
+# sensor/sensor-characteristics.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.
+
+## SimulateCaptureNoiseComponents
+
+One RMS noise component of the mid-grey figure, e⁻ (input-referred).
+
+```ts
+export interface SimulateCaptureNoiseComponents {
+  /** Photon shot noise √S (Poisson). */
+  photonShot: number;
+  /** Read noise of the capture's readout regime. */
+  read: number;
+  /** Dark-current shot noise √(D·t), D = 1 e⁻/s at 20 °C. */
+  darkCurrent: number;
+  /** ADC quantization, one code (and one more after a digital gain) as a uniform 1/12 code² variance, in e⁻. */
+  quantization: number;
+  /** With `sensor.fixedPatternNoise`: √((PRNU·S)² + (DSNU·D·t)² + row² + column²), hot pixels excluded; a spatial, not temporal, noise. */
+  fixedPattern?: number;
+  /** √ of the sum of the squares. */
+  total: number;
+}
+```
+
+## SimulateCaptureSensorCharacteristics
+
+#555: sensor characteristics a capture can set one at a time (`simulateCapture({ sensor })`). Each is off by default: an
+omitted field keeps the camera body's value, and a request with none of them is byte-identical to one before 2.20.0.
+Every value set is listed in the result's `assumptions`.
+
+```ts
+export interface SimulateCaptureSensorCharacteristics {
+  /**
+   * Peak external quantum efficiency of the green channel (its value at 555 nm), 0.05–0.9. Default 0.5, the facade's
+   * idealized sensor. Every channel's EQE curve is multiplied by `peakQuantumEfficiency / 0.5`, so the curves keep their
+   * shape (and the colour matrix is unchanged) and the collected charge scales in proportion.
+   */
+  peakQuantumEfficiency?: number;
+  /**
+   * Full-well capacity: the charge, e⁻, that reaches the RAW white level at base ISO. Default: the body's base-ISO saturation
+   * at 6 µm, scaled by the pixel area (the `sensor.isoAreaNormalization` approximation). `link` `"pixel-area"` (default)
+   * scales `electrons`, the full well at `referencePixelPitchMicrometers` (default 6), by (pitch / reference)²; `"none"`
+   * uses `electrons` at any pitch. The result is 100 e⁻ to 1e10 e⁻.
+   */
+  fullWell?: { electrons: number; link?: "pixel-area" | "none"; referencePixelPitchMicrometers?: number };
+  /**
+   * Read noise, RMS e⁻ (0–100), of the low and the high conversion gain, and the dual-gain switch: the ISO setting from
+   * which the high conversion gain is used (any ISO from 100; above the body's highest ISO, the low gain is used throughout).
+   * An omitted field keeps the body's value. Needs readout regimes that declare their exposure index (the tiers do).
+   */
+  readNoise?: { lowGainElectrons?: number; highGainElectrons?: number; highGainFromIso?: number };
+  /** Readout time, s (1e-6 to 1): the rolling shutter's top-to-bottom skew. Default: the body's (tiers 8, 15 and 30 ms). */
+  readoutSeconds?: number;
+  /**
+   * ADC bit depth: 12, 14 or 16. Default: the body's (consumer 12, the others 14). The black level scales with the code range
+   * (×2^Δbits), and the conversion gain follows so the same charge reaches the same fraction of the range.
+   */
+  adcBitDepth?: 12 | 14 | 16;
+  /**
+   * Opt-in (advanced): the body's synthetic fixed-pattern noise profile (PRNU, DSNU, hot pixels, row and column offsets; EMVA
+   * 1288 Release 4.0 non-uniformities), the same pattern in every capture. Default false. Not in `simulateDisplayView`.
+   */
+  fixedPatternNoise?: boolean;
+}
+```
+
+## SimulateCaptureSensorReport
+
+#555, #535: the capture's sensor characteristics as used, and the figures calculated from them (reported, not settable).
+Model figures from the engine's own noise model, not measurements.
+
+```ts
+export interface SimulateCaptureSensorReport {
+  pixelPitchMicrometers: number;
+  /** The green channel's peak EQE (at 555 nm). */
+  peakQuantumEfficiency: number;
+  /** Full-well capacity, e⁻: the base-ISO saturation charge (`sensor.capacityElectrons`). */
+  fullWellElectrons: number;
+  /** Read noise, RMS e⁻, of each conversion gain, and the ISO from which the high gain is used (null: one gain throughout). */
+  readNoise: { lowGainElectrons: number; highGainElectrons: number; highGainFromIso: number | null };
+  /** The body's rolling readout skew, s (null when it declares no rolling readout). */
+  readoutSeconds: number | null;
+  /** ADC bit depth of the capture's readout regime. */
+  adcBitDepth: number;
+  fixedPatternNoise: boolean;
+  /**
+   * Engineering dynamic range at the capture's ISO, stops: log₂(S_sat / σ_floor), with S_sat the charge at the RAW white
+   * level (full well over the analog gain, limited by the charge capacity and the ADC range) and σ_floor the read noise and
+   * ADC quantization added in quadrature (the temporal dark noise of EMVA 1288 Release 4.0 without dark current). An ideal
+   * noiseless readout is limited by the ADC alone: log₂((white − black)·√12) for unit digital gain.
+   */
+  dynamicRangeStops: number;
+  /** The same per ISO setting of the body, in its order. */
+  dynamicRangeByIso: readonly { iso: number; stops: number }[];
+  /**
+   * #535: the expected signal-to-noise ratio of an 18 % Lambertian grey patch under the request's illuminant and illuminance
+   * at the capture's exposure, ISO and sensor, on the green channel next to the optical axis (no vignetting, PSF or motion).
+   * `snr` = S/σ_total and `snrDecibels` = 20·log₁₀(snr). `clipped`: S is at or above the white level, where the RAW clips and
+   * the figure no longer describes the image. Computed only when the request resolves to exact (`fast: false`, the default for
+   * DNG, JPEG and PNG exports; omitted for a fast request).
+   */
+  midGrey?: { reflectance: 0.18; channel: "green"; signalElectrons: number; noiseElectrons: SimulateCaptureNoiseComponents; snr: number; snrDecibels: number; clipped: boolean };
+}
+```

package/llms.txt

@@ -7,6 +7,8 @@
 - [Agent guide](https://github.com/Photivra/photivra/blob/main/docs/AGENT_GUIDE.md): which function to call, units, reading results, errors and limits
 - [Quick start](https://github.com/Photivra/photivra/blob/main/docs/QUICK_START.md): `simulateCapture()` inputs, defaults, chart presets and output formats
 - [Color patches](https://github.com/Photivra/photivra/blob/main/docs/COLOR_PATCHES.md): the built-in color chart patches (`color-patches` preset, `{ kind: "color-patch", patchId }`), their spectra and CIELAB
+- [Image-plane scene](https://github.com/Photivra/photivra/blob/main/docs/IMAGE_PLANE.md): a photo as a flat print in front of the camera (`{ kind: "image-plane" }`), its input, placement, print reflectance lattice and accuracy
+- [Light sources](https://github.com/Photivra/photivra/blob/main/docs/LIGHT_SOURCES.md): representative fluorescent and LED spectra designed by Photivra (`createRepresentativeLightSourceIlluminant`), their CCT and color rendering
 - [Usage guide](https://github.com/Photivra/photivra/blob/main/docs/USAGE.md): worked examples for every public area
 - [API reference](https://github.com/Photivra/photivra/blob/main/docs/API_REFERENCE.md): every root export, with a task-to-function index
 
@@ -26,9 +28,13 @@
 - [calculateEquivalentFocalLength35Mm()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-equivalent-focal-length.md#calculateequivalentfocallength35mm): crop factor and 35 mm-equivalent focal length
 - [calculateSensorEquivalence()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-sensor-equivalence.md#calculatesensorequivalence): equivalent focal length and f-number, sensor area ratio and angles of view of a lens on one sensor, each marked exact or approximated
 - [calculateBlurShareOfFrame()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-sensor-equivalence.md#calculateblurshareofframe): a blur circle as a share of the frame diagonal, or its size on a print
+- [calculatePrintSizeLimitWithBlurAndNoise()](https://github.com/Photivra/photivra/blob/main/docs/api/output-print-size-blur-noise.md#calculateprintsizelimitwithblurandnoise): the largest print at a viewing distance that still looks sharp and clean, counting blur and noise as well as pixels (an approximation)
 - [calculateCenteredCrop()](https://github.com/Photivra/photivra/blob/main/docs/api/output-crop.md#calculatecenteredcrop): pixels left after a centred crop
+- [calculateCropToMatchFocalLength()](https://github.com/Photivra/photivra/blob/main/docs/api/output-crop-to-match-focal-length.md#calculatecroptomatchfocallength): crop factor and pixels left when cropping a shorter lens's image to match a longer focal length
+- [calculateApertureDiameter()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-aperture-diameter.md#calculateaperturediameter): entrance-pupil (aperture) diameter in mm, focal length ÷ f-number
 - [calculateProjectedMotionBlur()](https://github.com/Photivra/photivra/blob/main/docs/api/motion-projected-motion.md#calculateprojectedmotionblur): how far a moving subject smears on the sensor during the shutter time
 - [calculateFilteredExposureTime()](https://github.com/Photivra/photivra/blob/main/docs/api/exposure-filtered-exposure-time.md#calculatefilteredexposuretime): shutter time that keeps the same exposure with an ND (or any front-of-lens) filter, and the nearest shutter-dial value; `GENERIC_ND_FILTER_PROFILES` gives idealized 3-, 6- and 10-stop filters (exactly 2^-N)
+- [calculateDetailLimit()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-detail-limit.md#calculatedetaillimit): which limits detail for given settings, the lens (diffraction, aberrations, defocus) or the sensor's pixel pitch, with the optics MTF50, the Nyquist frequency and the system MTF50
 - [calculateAiryDisk()](https://github.com/Photivra/photivra/blob/main/docs/api/optics-diffraction.md#calculateairydisk): diffraction spot size from f-number and wavelength
 - [calculateSignalToNoise()](https://github.com/Photivra/photivra/blob/main/docs/api/sensor-signal-noise.md#calculatesignaltonoise): expected SNR from signal and read noise in electrons
 - [calculateChromaticityFromCorrelatedColorTemperature()](https://github.com/Photivra/photivra/blob/main/docs/api/color-illuminants.md#calculatechromaticityfromcorrelatedcolortemperature): white point for a colour temperature in kelvin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.19.0",
+  "version": "2.21.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",