@photivra/engine 2.17.0 → 2.19.0

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.17.0",
-  "engineApiVersion": "2.17.0",
+  "packageVersion": "2.19.0",
+  "engineApiVersion": "2.19.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -282,6 +282,16 @@
       "source": "src/sensor/local-exposure-binding.ts",
       "kind": "type"
     },
+    {
+      "name": "BlurShareOfFrame",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
+    {
+      "name": "BlurShareOfPrint",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "BOLTZMANN_CONSTANT_JOULES_PER_KELVIN",
       "source": "src/color/illuminants.ts",
@@ -367,6 +377,16 @@
       "source": "src/facade/chart-scenes.ts",
       "kind": "runtime"
     },
+    {
+      "name": "calculateBlurShareOfFrame",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateBlurShareOfFrameInput",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateBrownConradyDistortionMapping",
       "source": "src/optics/brown-conrady-distortion.ts",
@@ -712,6 +732,16 @@
       "source": "src/camera/field-of-view.ts",
       "kind": "type"
     },
+    {
+      "name": "calculateFilteredExposureTime",
+      "source": "src/exposure/filtered-exposure-time.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateFilteredExposureTimeInput",
+      "source": "src/exposure/filtered-exposure-time.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateFlashGuideNumber",
       "source": "src/exposure/flash-ttl.ts",
@@ -1287,6 +1317,16 @@
       "source": "src/sensor/eqe-temporal-exposure.ts",
       "kind": "type"
     },
+    {
+      "name": "calculateSensorEquivalence",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "CalculateSensorEquivalenceInput",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "calculateSensorFixedPatternSite",
       "source": "src/sensor/fixed-pattern-noise.ts",
@@ -2957,6 +2997,16 @@
       "source": "src/capture/environment-raw-producer.ts",
       "kind": "type"
     },
+    {
+      "name": "EquivalenceExactness",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
+    {
+      "name": "EquivalenceValueBasis",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "EquivalentFocalLength35Mm",
       "source": "src/camera/equivalent-focal-length.ts",
@@ -3277,6 +3327,21 @@
       "source": "src/camera/field-of-view.ts",
       "kind": "type"
     },
+    {
+      "name": "FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS",
+      "source": "src/exposure/filtered-exposure-time.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "FilteredExposureDialSetting",
+      "source": "src/exposure/filtered-exposure-time.ts",
+      "kind": "type"
+    },
+    {
+      "name": "FilteredExposureTime",
+      "source": "src/exposure/filtered-exposure-time.ts",
+      "kind": "type"
+    },
     {
       "name": "FixedMultiFrameCaptureAcquisition",
       "source": "src/sensor/capture-mode.ts",
@@ -3544,7 +3609,7 @@
     },
     {
       "name": "GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM",
-      "source": "src/output/generic-lens-corrections.ts",
+      "source": "src/output/developed-lens-corrections.ts",
       "kind": "runtime"
     },
     {
@@ -3557,6 +3622,16 @@
       "source": "src/equipment/generic-lens-catalogue.ts",
       "kind": "runtime"
     },
+    {
+      "name": "GENERIC_ND_FILTER_PROFILES",
+      "source": "src/optics/generic-nd-filter-presets.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "GENERIC_ND_FILTER_STOPS",
+      "source": "src/optics/generic-nd-filter-presets.ts",
+      "kind": "runtime"
+    },
     {
       "name": "GENERIC_PRIME_EQUIVALENT_FOCAL_LENGTHS_MM",
       "source": "src/equipment/generic-prime-lenses.ts",
@@ -3707,6 +3782,11 @@
       "source": "src/equipment/generic-lens-catalogue.ts",
       "kind": "type"
     },
+    {
+      "name": "GenericNdFilterStops",
+      "source": "src/optics/generic-nd-filter-presets.ts",
+      "kind": "type"
+    },
     {
       "name": "GenericOpticalEvidence",
       "source": "src/optics/profile-contract.ts",
@@ -3892,6 +3972,11 @@
       "source": "src/facade/chart-scenes.ts",
       "kind": "type"
     },
+    {
+      "name": "IDEAL_LENS_LIMITS",
+      "source": "src/equipment/ideal-lens.ts",
+      "kind": "runtime"
+    },
     {
       "name": "IdealApertureGeometry",
       "source": "src/optics/aperture.ts",
@@ -7827,6 +7912,21 @@
       "source": "src/sensor/eqe-electron-rate.ts",
       "kind": "type"
     },
+    {
+      "name": "SensorEquivalence",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SensorEquivalenceFieldOfView",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SensorEquivalenceQuantity",
+      "source": "src/camera/sensor-equivalence.ts",
+      "kind": "type"
+    },
     {
       "name": "SensorExpectedReadoutSignal",
       "source": "src/sensor/raw-readout.ts",
@@ -8512,6 +8612,21 @@
       "source": "src/facade/simulate-capture.ts",
       "kind": "type"
     },
+    {
+      "name": "simulateCaptureFromParts",
+      "source": "src/facade/develop-joined-parts.ts",
+      "kind": "runtime"
+    },
+    {
+      "name": "SimulateCaptureLensCatalogueRecord",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
+    {
+      "name": "SimulateCaptureLensCorrections",
+      "source": "src/facade/simulate-capture.ts",
+      "kind": "type"
+    },
     {
       "name": "SimulateCaptureLensDistortion",
       "source": "src/facade/simulate-capture.ts",

package/docs/api/exposure-filtered-exposure-time.md

@@ -0,0 +1,105 @@
+# exposure/filtered-exposure-time.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.
+
+## calculateFilteredExposureTime
+
+Shutter time that keeps the same exposure after adding front-of-lens filters, such as a
+neutral-density (ND) filter: t / T, with T the combined transmittance of the filter profiles.
+Aperture and ISO are unchanged.
+
+Exact under the linear sensor model (exposure H = E·t); film reciprocity failure is not modelled.
+Nominal filters vary: a "10-stop" or ND1000 (OD 3.0, 9.97 stops) filter transmits roughly, not
+exactly, its rating, so the result is only as good as the profile. The envelope is an
+approximation whenever any profile's `scientificStatus` is `"approximation"`.
+
+Example: 1/125 s with `GENERIC_ND_FILTER_PROFILES[10]` (exactly 2^-10) gives 1024/125 = 8.192 s;
+on a third-stop dial, 8 s.
+
+```ts
+export function calculateFilteredExposureTime(
+  input: CalculateFilteredExposureTimeInput
+): CalculationResult<FilteredExposureTime>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateFilteredExposureTimeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateFilteredExposureTimeInput {
+  /** Shutter time without the filter, in seconds. */
+  shutterSeconds: number;
+  /**
+   * One front-of-lens filter profile, or several in light-path order (scene side first), as
+   * accepted by `composeFrontOfLensFilterTransmission`.
+   */
+  filter: FrontOfLensFilterProfile | readonly FrontOfLensFilterProfile[];
+  /**
+   * Optional shutter dial, in seconds (for example `GENERIC_THIRD_STOP_SHUTTER_SECONDS`). When
+   * given, the result also reports the nearest dial value (nearest in stops, the shorter on a tie).
+   */
+  shutterDialSeconds?: readonly number[];
+  /** Wavelength at which the filters are resolved. Defaults to 550 nm. Neutral filters do not depend on it. */
+  wavelengthNanometers?: number;
+  /** Wavelength basis; defaults to the first filter profile's basis and must match every profile. */
+  wavelengthBasis?: Exclude<SpectralWavelengthBasis, "unspecified">;
+  /** Incident polarization, which matters only when a polarizer is in the stack. Omitted means unpolarized. */
+  incidentPolarization?: LinearPolarizationState;
+}
+```
+
+## FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS
+
+Wavelength used when the caller gives none: 550 nm, near the photopic peak. Neutral filters do not depend on it.
+
+```ts
+FILTERED_EXPOSURE_DEFAULT_WAVELENGTH_NANOMETERS = 550 as const
+```
+
+## FilteredExposureDialSetting
+
+The dial value nearest the exact filtered shutter time.
+
+```ts
+export interface FilteredExposureDialSetting {
+  /** Nearest dial value in seconds. */
+  shutterSeconds: number;
+  /**
+   * log2(dial / exact filtered time): exposure of the dial setting relative to the unfiltered
+   * exposure, in stops. Positive is brighter (longer), negative darker.
+   */
+  exposureErrorStops: number;
+  /** `"maximum"` when the exact time is longer than every dial value (use bulb for the exact time), `"minimum"` when shorter than every one. */
+  clamped: false | "minimum" | "maximum";
+  /** How the dial value was chosen. */
+  quantizationPolicy: "nearest-log2-shorter-on-tie";
+}
+```
+
+## FilteredExposureTime
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FilteredExposureTime {
+  /** Shutter time without the filter, in seconds. */
+  shutterSeconds: number;
+  /** Shutter time that gives the same exposure with the filter: shutterSeconds / linearTransmissionFactor. */
+  filteredShutterSeconds: number;
+  /** Combined intensity transmittance T of the filter stack, in (0, 1]. */
+  linearTransmissionFactor: number;
+  /** Combined attenuation −log2 T, in stops. */
+  attenuationStops: number;
+  /** Shutter multiplier 1/T = 2^attenuationStops. */
+  exposureFactor: number;
+  /** Wavelength at which the filters were resolved, in nanometres. */
+  wavelengthNanometers: number;
+  /** The filter-stack transmission this result is based on, with each filter's identity and evidence. */
+  filterTransmission: ComposedFrontOfLensFilterTransmission;
+  /** Nearest shutter-dial value; present only when `shutterDialSeconds` was given. */
+  dial?: FilteredExposureDialSetting;
+}
+```

package/docs/api/facade-develop-joined-parts.md

@@ -0,0 +1,32 @@
+# facade/develop-joined-parts.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.
+
+## simulateCaptureFromParts
+
+Develops the whole frame of `options` from the packed RAW of region renders of the same request (#571), so a capture can
+render its RAW in parallel parts and still take the development steps that filter across the whole image:
+`output.diffractionCorrection` and `output.sharpening`, which a region render refuses, and `output.lensCorrections` (#570), which
+runs on the whole developed frame here exactly as in `simulateCapture(options)`. The parts are joined exactly as
+{@link serializeSimulatedCaptureDngFromParts } joins them (they must cover every native site and agree where they overlap),
+and the joined RAW is the whole render's RAW, so the result's `image` (samples and JPEG or PNG bytes), `raw` codes and
+`plan` are those of `simulateCapture(options)`, bit for bit.
+
+`options` is the whole request (no `output.region`), with the development options it should have; render the parts with
+the same request plus `output.region`, without `output.diffractionCorrection`, `output.sharpening` and `output.dng`, and with a
+fixed white balance in place of `"auto"` (none of these change the RAW codes; auto white balance is measured here over the
+joined frame). A part may keep or drop `output.lensCorrections` (a corrected region only widens its `region.nativeRect`).
+Any `output.format` serves for a part.
+
+`onProgress` reports the `white-balance` (with auto white balance), `development`, `diffraction-correction`, `sharpening` and
+`jpeg` stages, the detail stages once per output row, so a host can show "Applying sharpening to the whole image". The lens
+corrections report no stage of their own: they run between `diffraction-correction` and `sharpening`.
+No `raw` stage is reported: no RAW is rendered. What differs from the whole render's result: `diagnostics.providerEvaluationCount`
+is 0, `diagnostics.timingsMs` are this call's, `diagnostics.fast` and the `raw.*` assumptions of how the RAW was rendered are
+not repeated (they are in the parts' results), and a `parts` assumption records the join.
+
+```ts
+export async function simulateCaptureFromParts(options: SimulateCaptureOptions, parts: readonly SimulateCaptureDngPart[]): Promise<SimulateCaptureResult>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.

package/docs/api/facade-simulate-capture.md

@@ -144,7 +144,7 @@ a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.tempor
 SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
   "lens.diffraction", "lens.defocus", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
   "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
-  "output.diffractionCorrection", "output.sharpening", "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
+  "output.diffractionCorrection", "output.sharpening", "output.lensCorrections", "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
 
 ## SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX
@@ -173,7 +173,7 @@ the record form with `fast` and is reported in `diagnostics.fast.applied` when i
 whether or not it has a fast method yet; one without runs exact and reports `false`.
 
 ```ts
-SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
+SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
 ```
 
 ## SIMULATE_CAPTURE_METERING_MODES
@@ -459,6 +459,30 @@ export interface SimulateCaptureFastReport {
 }
 ```
 
+## SimulateCaptureLensCatalogueRecord
+
+`lens.catalogue` as a record (#568): the lens id as `kind` and the `fast` override (see {@link SimulateCaptureOptions.fast}).
+
+```ts
+export interface SimulateCaptureLensCatalogueRecord { kind: string; fast?: boolean }
+```
+
+## SimulateCaptureLensCorrections
+
+`output.lensCorrections` (#570): which of the catalogue lens's generic corrections (`createGenericLensCorrectionProfile`) the
+development applies. Each is off unless set to true.
+
+```ts
+export interface SimulateCaptureLensCorrections {
+  /** Radial distortion r_d = r(1 + k1ρ²), inverted by resampling: it stretches the corners and lowers their resolution. */
+  distortion?: boolean;
+  /** Lateral colour: each channel rescaled by 1/(1 + L·D(λ_c)) into register; axial (longitudinal) colour stays. */
+  lateralColor?: boolean;
+  /** Vignetting: a gain 1/E(ρ) at each pixel's source point; corner noise rises with the signal, the SNR does not. */
+  vignetting?: boolean;
+}
+```
+
 ## SimulateCaptureLensDistortion
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -514,6 +538,19 @@ export interface SimulateCaptureOptions {
      * focus distance below its minimum focus distance, is rejected. Not combinable with `focalLengthMm`.
      */
     prime?: number;
+    /**
+     * Opt-in (#576): an ideal lens, an aberration-free thin lens of this physical focal length (1–4000 mm) on whatever sensor the
+     * frame is (output width × height × pixel pitch; no crop-factor scaling), at any `fNumber` from f/0.5 to f/128
+     * (`IDEAL_LENS_LIMITS`; beyond them the request is refused). It replaces the tier lens's focal length and f-number range (the
+     * transmission is kept); shutter priority and program may choose any aperture in that range. Recorded in the `lens.ideal`
+     * assumption. Its blur is that of `defocus`, `diffraction` and `vignetting`, the same models as with `prime`. It focuses at any
+     * distance beyond the focal length (no minimum focus distance; `subjectDistanceM` must be at least twice the focal length, as for
+     * every lens). Works in `simulateCapture` and the display view. Not combinable with `prime`, `catalogue` or `focalLengthMm`.
+     * Optional `widestFNumber` and `narrowestFNumber` (within `IDEAL_LENS_LIMITS`, widest ≤ narrowest; each defaults to its bound)
+     * narrow the range: `fNumber` must lie in it, and shutter priority and program choose apertures only in it (program limits its
+     * line to a range that does not hold f/4–f/16, #583). Default off.
+     */
+    ideal?: { focalLengthMm: number; widestFNumber?: number; narrowestFNumber?: number };
     /**
      * Opt-in (#549): a lens of the generic lens catalogue by id (`GENERIC_LENS_IDS`, for example "pv-50-1.2-pro" or "pv-50-1.8";
      * docs/LENS_CATALOGUE.md). Like `prime`, its focal length is the full-frame equivalent ÷ the simulated frame's diagonal crop
@@ -522,9 +559,12 @@ export interface SimulateCaptureOptions {
      * colour, at the resolved f-number and focus) through the environment PSF quadrature, its radial distortion, its vignetting
      * and, for the fisheyes, the equisolid projection. Flare, focus breathing and bokeh shape are not rendered. Not combinable
      * with `prime`, `focalLengthMm`, `projection`, `distortion`, `vignetting`, `psf`, `diffraction` or `pupilSampling` (the
-     * lens sets them); `defocus` convolves the disc into the lens's PSF. Not offered by the display view. Default off.
+     * lens sets them); `defocus` convolves the disc into the lens's PSF. The display view renders it with the PSF taken per field zone (#569; docs/DISPLAY_VIEW.md). Default off.
+     * #568: the record form `{ kind: <lens id>, fast }` overrides the top-level `fast` flag for this option; the fast method
+     * blends the PSF between exactly resolved kernels on a field grid and tabulates each site's expected signal
+     * (docs/LENS_CATALOGUE.md, "Fast method").
      */
-    catalogue?: string;
+    catalogue?: string | SimulateCaptureLensCatalogueRecord;
     /**
      * Opt-in (#549), with `catalogue` only: a seeded autofocus error (`simulateGenericLensFocusError`). The focus distance becomes
      * the sampled one for (seed, shotIndex), reported in the `lens.focusScatter` assumption; it is visible with `defocus`. Default off.
@@ -715,6 +755,16 @@ export interface SimulateCaptureOptions {
      * (not the wide-gamut or perceptual PNG paths); not combinable with `region`. The DNG's RAW codes are not changed. Default off.
      */
     sharpening?: SimulateCaptureSharpening;
+    /**
+     * Opt-in (#570), with `lens.catalogue`: the lens's generic corrections (see {@link SimulateCaptureLensCorrections}) on the
+     * developed linear colour, after demosaic, colour, white balance and `diffractionCorrection`, before the tone curve; for the JPEG,
+     * PNG and samples. The RAW and the DNG are never corrected. To keep the output size with no missing pixels, the corrected image is
+     * magnified by the smallest factor 1/m ≥ 1 that keeps every pixel's source inside the frame (recorded in the
+     * `output.lensCorrections` assumption). Works with `region`: a region develops the frame pixels its corrected pixels read
+     * (`region.nativeRect`, `raw` and `plan` describe that rectangle) and its pixels are the whole render's. All off (or omitted):
+     * the development is unchanged.
+     */
+    lensCorrections?: SimulateCaptureLensCorrections;
   };
   /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
   motion?: SimulateCaptureMotion;
@@ -748,12 +798,12 @@ export interface SimulateCaptureOptions {
    * Exact or fast (#395). `false` or omitted: every option runs its exact method, the engine reference. `true`: each option
    * listed in {@link SIMULATE_CAPTURE_FAST_OPTIONS} runs its fast method where it has one, a measured, bounded approximation of
    * the exact one; an option without a fast method runs exact. An option's own record `fast` overrides this for that option
-   * only. `diagnostics.fast` reports what was requested and what ran. No option has a fast method yet, so every result is exact.
+   * only. `diagnostics.fast` reports what was requested and what ran. `lens.catalogue` has a fast method (#568); the other options run exact.
    */
   fast?: boolean;
   /** Aborting cancels the running task; the promise rejects with a domain error and returns no partial image. */
   signal?: AbortSignal;
-  /** Called after each committed RAW, development or JPEG tile. Cannot change output. */
+  /** Called after each committed RAW, development, detail or JPEG tile (see {@link SimulateCaptureProgress}). Cannot change output. */
   onProgress?: (progress: SimulateCaptureProgress) => void;
 }
 ```
@@ -776,11 +826,15 @@ export type SimulateCapturePixelAperture = "point" | "box" | { kind: "box"; samp
 
 ## SimulateCaptureProgress
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+One progress event of `onProgress`. Stages run in this order: `raw`, `white-balance` (with auto white balance), `development`
+(rows), then, when requested, `diffraction-correction` and `sharpening` (#571: one event per output row of the whole image;
+each stage's last event has `completedTileCount === totalTileCount`), then `jpeg`. `output.lensCorrections` (#570) runs between
+`diffraction-correction` and `sharpening` and reports no stage of its own. {@link simulateCaptureFromParts }
+reports no `raw` stage: its RAW comes from the parts.
 
 ```ts
 export interface SimulateCaptureProgress {
-  stage: "raw" | "white-balance" | "development" | "jpeg";
+  stage: "raw" | "white-balance" | "development" | "diffraction-correction" | "sharpening" | "jpeg";
   completedTileCount: number;
   totalTileCount: 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-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

@@ -28,12 +28,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/llms.txt

@@ -24,8 +24,11 @@
 - [resolveGenericLens()](https://github.com/Photivra/photivra/blob/main/docs/api/equipment-generic-lens-catalogue.md#resolvegenericlens): one of the 30 generic catalogue lenses ("PV 50 1.2 Pro") on a sensor, with its approximated optical character; `simulateCapture` renders it with `lens.catalogue`
 - [calculateFieldOfView()](https://github.com/Photivra/photivra/blob/main/docs/api/camera-field-of-view.md#calculatefieldofview): angle of view from focal length and sensor size
 - [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
 - [calculateCenteredCrop()](https://github.com/Photivra/photivra/blob/main/docs/api/output-crop.md#calculatecenteredcrop): pixels left after a centred crop
 - [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)
 - [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.17.0",
+  "version": "2.19.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",