@photivra/engine 2.18.0 → 2.19.0

package/docs/USAGE.md

@@ -374,7 +374,7 @@ The actual focal length stays the physical optical quantity used by projection a
 - Focus distance is not part of conventional 35 mm-equivalent focal length. A later digital/output crop and the output resolution are also excluded.
 - If a product wants to describe the final digital framing, it should label it as output framing. It should not silently replace the optical focal length or the capture-equivalent focal length.
 
-To render a lens by its physical focal length on any sensor, give `simulateCapture()` or the display view `lens.ideal: { focalLengthMm }` with any `lens.fNumber` within `IDEAL_LENS_LIMITS` (f/0.5–f/128, 1–4000 mm; optional `widestFNumber` and `narrowestFNumber` narrow the f-number range for the automatic exposure modes): an aberration-free thin lens that is not scaled by the crop factor, unlike `lens.prime` (see docs/QUICK_START.md, "Ideal lens at any focal length and f-number").
+To render a lens by its physical focal length on any sensor, give `simulateCapture()` or the display view `lens.ideal: { focalLengthMm }` with any `lens.fNumber` within `IDEAL_LENS_LIMITS` (f/0.5–f/128, 1–4000 mm; optional `widestFNumber` and `narrowestFNumber` narrow the f-number range for the automatic exposure modes; in program the engine's program line is limited to that range, #583): an aberration-free thin lens that is not scaled by the crop factor, unlike `lens.prime` (see docs/QUICK_START.md, "Ideal lens at any focal length and f-number").
 
 `calculateImagingAreaMetrics()` provides the same canonical diagonal crop-factor calculation, independent of raster density, so other engine modules do not need to repeat that formula.
 
@@ -1058,6 +1058,30 @@ T_stack = T_1 * T_2 * ... * T_n
 
 The stack keeps each filter's identity and evidence. The combined numeric uncertainty is deliberately reported as **not propagated**, unless it is established whether the filters' errors are correlated or independent. Each filter's own uncertainty stays attached to that filter.
 
+### Exposure time with an ND filter
+
+`calculateFilteredExposureTime({ shutterSeconds, filter, shutterDialSeconds? })` (model `filtered-exposure-time` 1.0.0, #578) gives the shutter time that keeps the same exposure at the same f-number and ISO after adding one filter or a stack (`filter` takes one profile or an array in light-path order): `filteredShutterSeconds = shutterSeconds / T`, with `T` the stack's combined transmittance from `composeFrontOfLensFilterTransmission()`. It also returns `attenuationStops`, `exposureFactor` (`1/T`) and the full `filterTransmission`. With a `shutterDialSeconds` list (for example `GENERIC_THIRD_STOP_SHUTTER_SECONDS`) it adds `dial`: the nearest dial value in stops (the shorter on a tie), its exposure error in stops, and `clamped: "maximum"` when the exact time is longer than the longest dial value (use bulb).
+
+- Exact under the linear sensor model (exposure `H = E·t`); film reciprocity failure is not modelled.
+- Nominal filters vary: a "10-stop" filter (`T = 2^-10`) gives 1/125 s → 8.19 s, an ND1000 (OD 3.0, 9.97 stops) gives exactly 8 s. The result is only as good as the profile, and is an approximation whenever a profile is.
+- Generic presets: `GENERIC_ND_FILTER_PROFILES[3]`, `[6]` and `[10]` (keys in `GENERIC_ND_FILTER_STOPS`) are frozen, unbranded, spectrally flat profiles over 380–780 nm with a transmittance of exactly 2^-N (1/8, 1/64, 1/1024). They are idealized (`scientificStatus: "approximation"`, uncertainty not quantified), and any function that takes a front-of-lens filter profile accepts them. For other filters, build a profile with `parseFrontOfLensFilterProfile()`.
+- Filters are resolved at 550 nm unless `wavelengthNanometers` is given; neutral filters do not depend on it. `incidentPolarization` matters only with a polarizer in the stack.
+
+```ts
+import {
+  GENERIC_ND_FILTER_PROFILES,
+  GENERIC_THIRD_STOP_SHUTTER_SECONDS,
+  calculateFilteredExposureTime
+} from "@photivra/engine";
+
+const { value } = calculateFilteredExposureTime({
+  shutterSeconds: 1 / 125,
+  filter: GENERIC_ND_FILTER_PROFILES[10],
+  shutterDialSeconds: GENERIC_THIRD_STOP_SHUTTER_SECONDS
+});
+console.log(value.filteredShutterSeconds.toFixed(2), value.dial?.shutterSeconds); // 8.19 8
+```
+
 ### Spectral boundary
 
 Spectral filter data stays wavelength-resolved all the way through the [scene-radiance-to-sensor bridge](#scene-radiance-to-sensor-irradiance). Photivra does not turn a spectral filter into an undocumented RGB tint.
@@ -5527,6 +5551,20 @@ All modes:
 
 Flash-aware behaviour, safety shift and the program behaviour of named cameras are separate work.
 
+### The capture facade's program line and the lens's f-number range (#583)
+
+`simulateCapture()` and the display view in `exposure.mode: "program"` use an engine-authored generic line (f/16 1/2000 s … f/8
+1/125 s … f/4 1.024 s, assumption `exposure.programLine`). `resolveProgramAutoExposureMode()` refuses a line whose apertures leave
+the capability range, so with a lens range that does not hold f/4–f/16 (`lens.ideal` `widestFNumber`/`narrowestFNumber`,
+`lens.prime`, `lens.catalogue`) the facade limits the line to the range first: the line's f/4 and f/16 are clamped to the range, giving the same shape with
+the aperture held at the range's end and the shutter keeping each point's exposure (t/N², camera equation H = 0.65·L·t/N²),
+still from 1/2000 s to 1.024 s. Where both lines run, the limited line's aperture is the old one clamped in log2 to the range.
+Beyond the line's ends the resolver holds them as before. A range that holds f/4–f/16, or no range, keeps the line and its
+bytes. The limited line is recorded as its profile (id `"facade-generic-program-line-lens-range"`), with node stops measured from the
+capture's exposure anchor (f/8, 1/125 s; the same N²/t at the range's aperture nearest f/8; or, #585, that aperture at the
+body's shortest shutter when the same N²/t would need a shorter one). An approximation of a generic
+program, not a manufacturer's.
+
 ## Program Auto and Full Auto exposure
 
 Program Auto and Full Auto exposure both need a declared, versioned **program line**: a curve that says which aperture and shutter to use at each brightness level. The engine does not invent one "correct" aperture/shutter pair.
@@ -7480,7 +7518,8 @@ own designs, not real products). `resolveGenericLens` resolves one for a sensor,
 (scaled by the crop factor), aperture range, close focus, projection and its character, Seidel aberrations, axial and lateral
 colour, distortion and vignetting profiles, flare, breathing and focus scatter, each a labelled approximation.
 `simulateGenericLensFocusError` draws a seeded autofocus error; `createGenericLensCorrectionProfile` builds the lens's generic
-correction profile for `resolveLensCorrectionPlan`. `simulateCapture` renders a catalogue lens with `lens.catalogue`
+correction profile for `resolveLensCorrectionPlan`, which `simulateCapture` applies to its developed image with
+`output.lensCorrections` (#570; never to the RAW or the DNG). `simulateCapture` renders a catalogue lens with `lens.catalogue`
 ([quick start](QUICK_START.md#generic-lens-catalogue-549)); `fast: true` (or `lens: { catalogue: { kind, fast: true } }`) takes its
 fast method (#568), a labeled approximation that blends the PSF over a field grid, for interactive captures. Equations, tables and the
 chart measurements: [LENS_CATALOGUE.md](https://github.com/Photivra/photivra/blob/main/docs/LENS_CATALOGUE.md).
@@ -7742,6 +7781,12 @@ console.log(star.assumptions.filter((a) => a.kind === "default").map((a) => a.id
 console.log(star.request.siteInput(0).environment.optics.nominalFNumber);
 ```
 
+A capture can render its RAW in parallel parts (`output.region`, one call per part). `serializeSimulatedCaptureDngFromParts()`
+writes the whole frame's DNG from the parts, and `simulateCaptureFromParts()` (#571) develops the whole frame from them,
+including the whole-image stages `output.diffractionCorrection` and `output.sharpening` that a region refuses, with the same
+bytes as a whole-frame `simulateCapture()` and per-row progress (`diffraction-correction`, `sharpening`). See
+[Quick start, Developing a capture rendered in parts](QUICK_START.md#developing-a-capture-rendered-in-parts-571).
+
 ### Color charts (2.14)
 
 The engine's own [color patches](https://github.com/Photivra/photivra/blob/main/docs/COLOR_PATCHES.md) are reflectance spectra lit by the capture's illuminant. Draw the

package/docs/api/core-version.md

@@ -11,5 +11,5 @@ version they were made with. Proof-of-concept (POC), schema and model contracts
 own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "2.18.0" as const
+ENGINE_API_VERSION = "2.19.0" as const
 ```

package/docs/api/exports.json

@@ -1,6 +1,6 @@
 {
-  "packageVersion": "2.18.0",
-  "engineApiVersion": "2.18.0",
+  "packageVersion": "2.19.0",
+  "engineApiVersion": "2.19.0",
   "exports": [
     {
       "name": "AbsoluteUncertaintyEstimate",
@@ -732,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",
@@ -3317,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",
@@ -3584,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"
     },
     {
@@ -3597,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",
@@ -3747,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",
@@ -8572,11 +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
@@ -467,6 +467,22 @@ export interface SimulateCaptureFastReport {
 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.
@@ -531,7 +547,8 @@ export interface SimulateCaptureOptions {
      * 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. Default off.
+     * 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 };
     /**
@@ -738,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;
@@ -776,7 +803,7 @@ export interface SimulateCaptureOptions {
   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;
 }
 ```
@@ -799,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

@@ -28,6 +28,7 @@
 - [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.18.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",