@photivra/engine 2.19.0 → 2.20.0

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,9 +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.19.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",