@photivra/engine 2.18.0 → 2.20.0

package/docs/api/optics-detail-limit.md

@@ -0,0 +1,203 @@
+# optics/detail-limit.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.
+
+## calculateDetailLimit
+
+Which limits detail for given settings: the lens (diffraction at this f-number, aberrations, defocus) or the sensor's pixel
+pitch. Returns the optics' resolution (MTF50 and the diffraction cut-off, cycles/mm), the sampling's (Nyquist frequency
+and, with a Bayer filter, the red and blue sites'), the system MTF50 (optics × pixel aperture), the f-number from which
+diffraction limits on this sensor, and which one limits.
+
+The sensor limits when the optics still pass 50 % contrast at the Nyquist frequency 1/(2p); otherwise the lens does,
+through diffraction when its wavefront error is within the Maréchal criterion (RMS ≤ λ/14), else through aberrations or
+defocus. The optics MTF is the exact scalar OTF of the stated wavefront at one wavelength; the decision rule and the
+catalogue lenses' wavefronts are approximations.
+
+Example: an ideal 50 mm lens at f/22 on a 36 × 24 mm, 6000-pixel-wide sensor (6 µm) is limited by diffraction (optics
+MTF50 ≈ 33 cycles/mm against a Nyquist frequency of ≈ 83); at f/4 the pixel pitch limits.
+
+```ts
+export function calculateDetailLimit(input: CalculateDetailLimitInput): CalculationResult<DetailLimit>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateDetailLimitInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateDetailLimitInput {
+  /** Active imaging area and horizontal pixel count; pitch = widthMm / pixelWidth. */
+  sensor: {
+    widthMm: number;
+    heightMm: number;
+    pixelWidth: number;
+    /** Default `"bayer"`. `"none"`: every site records full detail (a monochrome sensor). */
+    colorFilterArray?: "bayer" | "none";
+  };
+  lens: DetailLimitIdealLens | DetailLimitCatalogueLens;
+  /** f-number set on the lens. */
+  fNumber: number;
+  /**
+   * Focus and subject distances from the lens in meters. Omitted: focused at infinity, subject in focus. `subjectDistanceM`
+   * omitted: the subject is at the focus distance.
+   */
+  focus?: { focusDistanceM: number; subjectDistanceM?: number };
+  /** Field height as a fraction of the half-diagonal, 0 (center, default) to 1 (corner). Only aberrations depend on it. */
+  fieldPosition?: number;
+  /** Wavelength in nanometres, 380–780. Default 550. */
+  wavelengthNm?: number;
+}
+```
+
+## DETAIL_LIMIT_LIMITS
+
+Limits of `calculateDetailLimit`: the wavelength range and the largest wavefront (sum of the magnitudes of its terms, in
+waves) whose transfer function is integrated. Beyond it the blur is geometric and the quadrature would grow without
+bound; use `calculateDefocusCircle` for such a blur.
+
+```ts
+DETAIL_LIMIT_LIMITS = Object.freeze({ minimumWavelengthNm: 380, maximumWavelengthNm: 780, maximumWavefrontWaves: 64 })
+```
+
+## DetailLimit
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DetailLimit {
+  /** The lens or the sensor. */
+  limitedBy: DetailLimitedBy;
+  /** Diffraction, aberrations or defocus (the lens), or the pixel pitch (the sensor). */
+  limitingFactor: DetailLimitingFactor;
+  /** Optics MTF50 / Nyquist frequency: at least 1 when the sensor limits. */
+  opticsToNyquistRatio: number;
+  fNumber: number;
+  wavelengthNm: number;
+  /** Physical focal length used (the catalogue lens's on this sensor), mm. */
+  focalLengthMm: number;
+  fieldPosition: number;
+  optics: DetailLimitOptics;
+  sampling: DetailLimitSampling;
+  system: DetailLimitSystem;
+  /**
+   * The f-number at which an aberration-free lens in focus has its MTF50 at the Nyquist frequency (2·p·0.40397/λ at
+   * infinity focus): from it on, diffraction limits detail on this sensor whatever the lens.
+   */
+  diffractionLimitedFNumber: number;
+  basis: Readonly<Record<"optics" | "sampling" | "system" | "limitedBy", DetailLimitBasis>>;
+}
+```
+
+## DetailLimitBasis
+
+Whether a quantity is exact under its stated conditions or an approximation.
+
+```ts
+export interface DetailLimitBasis { kind: "exact" | "approximation"; statement: string }
+```
+
+## DetailLimitCatalogueLens
+
+A generic catalogue lens (`GENERIC_LENS_IDS`), resolved for the sensor as `resolveGenericLens` does.
+
+```ts
+export interface DetailLimitCatalogueLens {
+  kind: "catalogue";
+  lensId: string;
+}
+```
+
+## DetailLimitedBy
+
+Which component limits detail.
+
+```ts
+export type DetailLimitedBy = "lens" | "sensor";
+```
+
+## DetailLimitIdealLens
+
+A lens with no aberrations (diffraction only).
+
+```ts
+export interface DetailLimitIdealLens {
+  kind: "ideal";
+  /** Physical focal length in millimeters (for the working f-number and the defocus of a subject off the focus distance). */
+  focalLengthMm: number;
+}
+```
+
+## DetailLimitingFactor
+
+What limits it: the lens's diffraction, aberrations or defocus, or the sensor's pixel pitch.
+
+```ts
+export type DetailLimitingFactor = "diffraction" | "aberrations" | "defocus" | "pixel-pitch";
+```
+
+## DetailLimitOptics
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DetailLimitOptics {
+  /** Working f-number N_w = N·v/f (thin-lens image distance v; N at infinity focus). */
+  workingFNumber: number;
+  /** Diffraction cut-off 1/(λ·N_w) in cycles/mm: no optics passes detail beyond it. */
+  cutoffCyclesPerMm: number;
+  /** Frequency where the optics' MTF falls to 0.5, the lower of the two directions, cycles/mm. */
+  mtf50CyclesPerMm: number;
+  /** MTF50 for detail along the radius from the image center (tangential), cycles/mm. */
+  tangentialMtf50CyclesPerMm: number;
+  /** MTF50 for detail across the radius (sagittal), cycles/mm. Equal to the tangential value at the center. */
+  sagittalMtf50CyclesPerMm: number;
+  /** MTF50 of an aberration-free lens in focus at the same working f-number (0.40397·cut-off), cycles/mm. */
+  diffractionMtf50CyclesPerMm: number;
+  /** Optics MTF at the sensor's Nyquist frequency (lower direction). */
+  mtfAtNyquist: number;
+  /** RMS wavefront error in waves at the wavelength: of the aberrations, of the defocus, and of both together. */
+  rmsWavefrontErrorWaves: { aberrations: number; defocus: number; total: number };
+  /** Whether the total RMS wavefront error is within the Maréchal criterion λ/14. */
+  withinMarechalCriterion: boolean;
+  /** Geometric blur-circle diameter of the defocus on the sensor, mm (0 in focus). */
+  defocusBlurDiameterMm: number;
+}
+```
+
+## DetailLimitSampling
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DetailLimitSampling {
+  colorFilterArray: "bayer" | "none";
+  /** Pixel pitch in micrometres: widthMm / pixelWidth. */
+  pixelPitchMicrometers: number;
+  /** 1/(2p), cycles/mm: the finest detail the pixel grid records without aliasing (Bayer green sites too, along rows and columns). */
+  nyquistCyclesPerMm: number;
+  /** Bayer only: 1/(4p), the Nyquist frequency of the red and blue sites. Null without a color filter array. */
+  redBlueNyquistCyclesPerMm: number | null;
+  /** Pixel aperture MTF at the Nyquist frequency: sinc(1/2) = 2/π. */
+  pixelApertureMtfAtNyquist: number;
+  /** Frequency where the pixel aperture MTF falls to 0.5 (0.60335/p), cycles/mm: beyond the Nyquist frequency. */
+  pixelApertureMtf50CyclesPerMm: number;
+}
+```
+
+## DetailLimitSystem
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DetailLimitSystem {
+  /** MTF50 of optics × pixel aperture (lower direction), cycles/mm. Detail above the Nyquist frequency aliases. */
+  mtf50CyclesPerMm: number;
+  /** The same in line pairs per picture height (cycles/mm × heightMm). */
+  mtf50LinePairsPerPictureHeight: number;
+  /** System MTF at the Nyquist frequency (lower direction). */
+  mtfAtNyquist: number;
+}
+```

package/docs/api/optics-generic-nd-filter-presets.md

@@ -0,0 +1,34 @@
+# optics/generic-nd-filter-presets.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.
+
+## GENERIC_ND_FILTER_PROFILES
+
+Frozen generic ND filter profiles keyed by stops: `GENERIC_ND_FILTER_PROFILES[10]` transmits
+exactly 1/1024. Spectrally flat over 380–780 nm (air), idealized (`scientificStatus:
+"approximation"`), unbranded. 1/125 s with the 10-stop preset gives 1024/125 ≈ 8.19 s in
+`calculateFilteredExposureTime`.
+
+```ts
+GENERIC_ND_FILTER_PROFILES: Readonly<Record<GenericNdFilterStops, FrontOfLensFilterProfile>> = freezeOwnedData({
+  3: idealNdProfile(3),
+  6: idealNdProfile(6),
+  10: idealNdProfile(10)
+})
+```
+
+## GENERIC_ND_FILTER_STOPS
+
+Attenuations, in stops, of the generic ND presets.
+
+```ts
+GENERIC_ND_FILTER_STOPS = Object.freeze([3, 6, 10] as const)
+```
+
+## GenericNdFilterStops
+
+One of the generic ND preset attenuations: 3, 6 or 10 stops.
+
+```ts
+export type GenericNdFilterStops = (typeof GENERIC_ND_FILTER_STOPS)[number];
+```

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

@@ -200,7 +200,9 @@ Kernel interpolation between regular-grid nodes.
 - `rotationally-symmetric-radial-field-centroid-aligned`: for a rotationally symmetric lens. Nodes
   are declared only along the +X field axis (fieldYmm = [0], fieldXmm >= 0). A query at field
   (x, y) is interpolated, with centroid alignment, at radius hypot(x, y). The kernel is then
-  rotated by atan2(y, x) about its centre. The sample pitch must be square.
+  rotated by atan2(y, x) about its centre, with the kernel row index increasing with image +Y (the
+  convention the environment PSF quadrature applies), so an asymmetric kernel points the same way
+  as in the 2-D grid modes. The sample pitch must be square.
 Shifts and rotations use bilinear resampling. This smooths the kernel slightly (by at most about
 one sample). Samples outside the kernel are zero, and the result is renormalised to unit energy.
 

package/docs/api/output-crop-to-match-focal-length.md

@@ -0,0 +1,67 @@
+# output/crop-to-match-focal-length.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.
+
+## calculateCropToMatchFocalLength
+
+The centred crop that makes an image from a shorter lens match a longer lens's framing from the
+same position: crop factor target ÷ focal length, and the pixels and megapixels left.
+
+Exact for ideal rectilinear lenses focused at infinity, to whole pixels (the crop is
+`calculateCenteredCrop`'s, which keeps the aspect ratio). At close focus the matching factor is
+larger, F·(d − f)/(f·(d − F)) at object distance d (thin lens); that, distortion and focus
+breathing are not modelled. The crop has the longer lens's framing and perspective but fewer
+pixels: it records no more detail than the cropped part of the shorter lens's image.
+
+Example: a 24 MP (6000 × 4000) image at 50 mm cropped to match 100 mm: factor 2, 3000 × 2000,
+6 MP.
+
+```ts
+export function calculateCropToMatchFocalLength(
+  input: CalculateCropToMatchFocalLengthInput
+): CalculationResult<CropToMatchFocalLength>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCropToMatchFocalLengthInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCropToMatchFocalLengthInput {
+  /** Focal length the image was taken with, in millimetres. */
+  focalLengthMm: number;
+  /** Longer focal length whose framing the crop should match, in millimetres. At least `focalLengthMm`. */
+  targetFocalLengthMm: number;
+  /** Image width in pixels (for example the sensor's output width). */
+  pixelWidth: number;
+  /** Image height in pixels. */
+  pixelHeight: number;
+}
+```
+
+## CropToMatchFocalLength
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CropToMatchFocalLength {
+  /** Focal length supplied by the caller, in millimetres. */
+  focalLengthMm: number;
+  /** Target focal length supplied by the caller, in millimetres. */
+  targetFocalLengthMm: number;
+  /** Linear crop factor targetFocalLengthMm / focalLengthMm (1 means no crop). */
+  cropFactor: number;
+  /** Width left after the centred crop, in pixels (as `calculateCenteredCrop`). */
+  pixelWidth: number;
+  /** Height left after the centred crop, in pixels. */
+  pixelHeight: number;
+  /** Pixels left, in millions. */
+  megapixels: number;
+  /** Megapixels of the uncropped image. */
+  sourceMegapixels: number;
+  /** Fraction of the original pixel area retained, about 1 / cropFactor². */
+  retainedAreaFraction: number;
+}
+```

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

@@ -0,0 +1,12 @@
+# output/developed-lens-corrections.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.
+
+## GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM
+
+Effective wavelengths of the red, green and blue channels for the lateral-colour map, nm: a generic approximation of where
+a camera's channel responses peak, not a measured camera.
+
+```ts
+GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM: Readonly<Record<LensCorrectionChannel, number>> = Object.freeze({ red: 610, green: 540, blue: 465 })
+```

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

@@ -6,7 +6,9 @@ The package and root API versions are recorded once in [Navigation](../API_REFER
 
 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`.
+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;
@@ -28,12 +30,3 @@ export interface CreateGenericLensCorrectionProfileInput {
   state: OpticalProfileState;
 }
 ```
-
-## GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM
-
-Effective wavelengths of the red, green and blue channels for the lateral-colour map, nm: a generic approximation of where
-a camera's channel responses peak, not a measured camera.
-
-```ts
-GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM: Readonly<Record<LensCorrectionChannel, number>> = Object.freeze({ red: 610, green: 540, blue: 465 })
-```

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-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

@@ -26,8 +26,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.18.0",
+  "version": "2.20.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",