@photivra/engine 2.19.0 → 2.21.0

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

@@ -66,6 +66,8 @@ export interface DisplayViewResult {
     /** #516: as in the capture result. */
     isoControl: "manual" | "automatic"; autoIso?: SimulateCaptureAutoIsoReport };
   scene: SimulateCaptureResult["scene"];
+  /** #555, #535: as in the capture result. */
+  sensor: SimulateCaptureSensorReport;
   /**
    * Work done: real pixels sampled, real-site expectations evaluated, scene queries, display pixels sampled in full (detail) or with
    * a quarter of the samples per axis (uniform), display pixels whose value includes the AHD low-signal correction, and wall-clock
@@ -142,7 +144,7 @@ a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.tempor
 
 ```ts
 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",
+  "lens.diffraction", "lens.defocus", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.subject", "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.lensCorrections", "output.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
@@ -173,7 +175,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", "lens.catalogue", "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", "motion.subject"] as const)
 ```
 
 ## SIMULATE_CAPTURE_METERING_MODES
@@ -425,6 +427,12 @@ One part of a whole-frame DNG (#391): a region render's packed RAW and where its
 export interface SimulateCaptureDngPart {
   raw: Pick<NativeRawOutput, "codes" | "blackLevels" | "digitalSaturationCodes" | "saturationFlags" | "effectiveSaturationCodes">;
   region: { nativeRect: { x: number; y: number; width: number; height: number } };
+  /**
+   * 2.20.0: true when a fast method ran for this part (`Object.values(result.diagnostics.fast.applied).includes(true)`). The join
+   * refuses such a part unless its own request resolves to fast too (a DNG, JPEG or PNG is exact by default): render the parts with
+   * the same `fast` as the join, or with `fast: false`.
+   */
+  fast?: boolean;
 }
 ```
 
@@ -450,8 +458,10 @@ export type SimulateCaptureFastOption = typeof SIMULATE_CAPTURE_FAST_OPTIONS[num
 
 ```ts
 export interface SimulateCaptureFastReport {
-  /** True when `fast: true` was given at the top level or in any option's record. */
+  /** 2.20.0: the resolved top-level value (`fast`, else the format default), or true when any option's record sets `fast: true`. */
   requested: boolean;
+  /** 2.20.0: where the top-level value came from: the request's `fast`, or the format default (see {@link SimulateCaptureOptions.fast}). */
+  defaultedFrom: "request" | "format";
   /** Each fast-capable option that ran, in {@link SIMULATE_CAPTURE_FAST_OPTIONS} order: true where its fast method ran. */
   applied: Readonly<Partial<Record<SimulateCaptureFastOption, boolean>>>;
   /** `engine-reference` when every option ran exact; `approximation-with-a-priori-bound` when any fast method ran (the WebGPU execution record's values). */
@@ -462,6 +472,10 @@ export interface SimulateCaptureFastReport {
 ## SimulateCaptureLensCatalogueRecord
 
 `lens.catalogue` as a record (#568): the lens id as `kind` and the `fast` override (see {@link SimulateCaptureOptions.fast}).
+Fast: the tabulated fast method (#568), and with `lens.defocus` the lens's bokeh without its cat's eye (#567; fast wides and
+normals only), whose field-varying PSF needs a finer fast grid (measured 2.2–3.4× slower); with camera rotation under
+`motion.shutter: "rolling"`, the per-tap PSF points instead of the lattice reading (#588). Exact: the per-site PSF with the
+cat's eye, read on the lattice. Blades and spherical aberration always apply (they cost nothing).
 
 ```ts
 export interface SimulateCaptureLensCatalogueRecord { kind: string; fast?: boolean }
@@ -516,6 +530,11 @@ export interface SimulateCaptureMotion {
   shutter?: "global" | "rolling";
   /** Rolling shutter only: time from the first to the last line over the simulated frame, in s. Default: the body's declared readout skew. */
   rollingShutterSkewSeconds?: number;
+  /**
+   * #551: a moving subject: the whole scene, or one rectangle of it over a still background, translating on the scene plane
+   * (and optionally rotating about the optical axis) during the exposure. Off by default (a still scene).
+   */
+  subject?: SimulateCaptureSubjectMotion;
 }
 ```
 
@@ -557,9 +576,9 @@ export interface SimulateCaptureOptions {
      * factor and it replaces the tier lens's focal length and f-number range (the transmission is kept). The capture renders the
      * lens's character, all labelled approximations: its PSF (diffraction with the lens's Seidel aberrations, axial and lateral
      * 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
+     * and, for the fisheyes, the equisolid projection. Flare and focus breathing 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. The display view renders it with the PSF taken per field zone (#569; docs/DISPLAY_VIEW.md). Default off.
+     * lens sets them); `defocus` convolves the lens's bokeh kernel (#567) into its 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").
@@ -659,9 +678,10 @@ export interface SimulateCaptureOptions {
   /**
    * Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card), a declared `material-layers` scene (#491:
    * a chart under shape-mask layers, as `resolveChartMaterialLayers` takes it; the capture is that of its `callerScene`, byte for
-   * byte, and the display view can render it on the GPU), or a caller reflectance, radiance or material function.
+   * byte, and the display view can render it on the GPU), a caller reflectance, radiance or material function, or (2.21, #581) an
+   * `image-plane` scene: a photo as a flat print (docs/IMAGE_PLANE.md).
    */
-  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
+  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene | ImagePlaneScene;
   /** Distance from the camera to the scene plane in metres. Default 5. */
   subjectDistanceM?: number;
   /**
@@ -676,6 +696,12 @@ export interface SimulateCaptureOptions {
   illuminant?: CaptureIlluminant;
   /** Illuminance on the scene plane, lux. Default about 21 481 lux (see `SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX` and the assumptions). */
   illuminanceLux?: number;
+  /**
+   * 2.22 (#550), opt-in mixed lighting: two or more sources blended across the chart (docs/MIXED_ILLUMINATION.md), instead of
+   * `illuminant` and `illuminanceLux`. The frame center's light sets the grey-card meter and the standard-exposure figures, and
+   * its strongest source the "scene-illuminant" white balance; both are reported in `assumptions`.
+   */
+  illumination?: MixedIllumination;
   output?: {
     /** Output pixels; the native sensor raster adds a one-site demosaic border on each side. Defaults 64 × 64. */
     width?: number;
@@ -700,7 +726,7 @@ export interface SimulateCaptureOptions {
     exposureCompensationStops?: number;
     /** Default "scene-illuminant". */
     whiteBalance?: SimulateCaptureWhiteBalance;
-    /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 2. */
+    /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 1 (2.20.0; 2 before), the full-quality export. */
     jpegQuantizationStep?: number;
     /** PNG only. Default "srgb". */
     colorEncoding?: SimulateCaptureColorEncoding;
@@ -715,8 +741,13 @@ export interface SimulateCaptureOptions {
     demosaic?: SimulateCaptureDemosaic | SimulateCaptureDemosaicRecord;
     /** Default "margin". */
     borderHandling?: SimulateCaptureBorderHandling;
-    /** DNG only: optional capture-event time (YYYY-MM-DDTHH:mm:ss.sssZ); without it no date tags are written. */
-    dng?: { capturedAtUtc?: string };
+    /**
+     * DNG only: optional capture-event time (YYYY-MM-DDTHH:mm:ss.sssZ); without it no date tags are written. Opt-in (#587), with
+     * `lens.catalogue`: `lensCorrectionOpcodes` writes the selected corrections of {@link SimulateCaptureLensCorrections} into the DNG as
+     * optional DNG opcodes in OpcodeList3 (FixVignetteRadial, WarpRectilinear with the zoom-to-fill; docs/NATIVE_RAW_AND_PRINT.md), for RAW editors
+     * that apply them; the RAW codes are unchanged. Whole frame only (no `region`). All off (or omitted): the same DNG bytes as without it.
+     */
+    dng?: { capturedAtUtc?: string; lensCorrectionOpcodes?: SimulateCaptureLensCorrections };
     /**
      * Opt-in (2.4) text written into the file for formats "jpeg", "png" and "dng": the caller's description,
      * software, copyright and comment, unchanged (JPEG XMP + COM, PNG tEXt/iTXt, DNG TIFF tags + XMP; see the
@@ -768,7 +799,15 @@ export interface SimulateCaptureOptions {
   };
   /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
   motion?: SimulateCaptureMotion;
-  sensor?: {
+  /** #555: plus the sensor characteristics ({@link SimulateCaptureSensorCharacteristics}), each off by default. */
+  sensor?: SimulateCaptureSensorCharacteristics & {
+    /**
+     * #554: a sensor profile record (`SENSOR_PROFILES`, or `resolveSensorProfile(id)`), checked strictly. It replaces the body's ISO range, readout regimes
+     * (full well, read noise of each conversion gain, the dual-gain switch, high-gain storage, ADC bit depth), readout time and
+     * fixed-pattern noise, and sets the default pixel pitch and peak QE; explicit fields here still override it one at a time.
+     * Default: none (the body's own sensor). See docs/SENSOR_PROFILES.md.
+     */
+    profile?: SensorProfile;
     /**
      * Pixel pitch in micrometres, 0.5–1000. Default 6. The simulated sensor is output width × pitch wide. 2.5: above 100 µm the
      * capture is a downsized view of a whole frame (for example 36 mm / 48 pixels = 750 µm), recorded in the assumption
@@ -795,10 +834,14 @@ export interface SimulateCaptureOptions {
     pixelAperture?: SimulateCapturePixelAperture;
   };
   /**
-   * 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. `lens.catalogue` has a fast method (#568); the other options run exact.
+   * Exact or fast (#395). `false`: 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.
+   * Omitted (2.20.0), the format decides: fast for `output.format` "srgb-8" and "srgb-16" and for the display view, exact for
+   * "dng", "jpeg" and "png" (exports) and for `simulateIdealReference`. `diagnostics.fast` reports the resolved value, where it
+   * came from and what ran. Fast methods: `lens.catalogue` (#568, #567) and `lens.diffraction` under rolling-shutter rotation
+   * (#565); in the display view also its catalogue PSF zones, its sampling of uniform pixels and its AHD low-signal correction
+   * (docs/DISPLAY_VIEW.md). The exact result also carries `result.sensor.midGrey` (#535). Calculators should pass `fast: false`.
    */
   fast?: boolean;
   /** Aborting cancels the running task; the promise rejects with a domain error and returns no partial image. */
@@ -994,6 +1037,8 @@ export interface SimulateCaptureResult {
     limitations: readonly string[];
   };
   assumptions: readonly SimulateCaptureAssumption[];
+  /** #555, #535: the sensor characteristics used, the calculated dynamic range and (when the request resolves to exact) the mid-grey noise figure. */
+  sensor: SimulateCaptureSensorReport;
 }
 ```
 

package/docs/api/facade-simulate-display-view.md

@@ -65,9 +65,10 @@ responses through the environment chain, the diffraction kernels, readout moment
 about 0.3–1.3 s per call on a 24 MP request; a region costs only its own pixels. Errors in the request are raised here;
 errors in the view by `render`.
 
-2.11 (#481): `prepareOptions.gpu` chooses the renderer: `"off"` (default) is the CPU reference, today's bytes; `"auto"` renders
+2.11 (#481): `prepareOptions.gpu` chooses the renderer: `"off"` is the CPU reference, today's bytes; `"auto"` renders
 on WebGPU when a conforming device is available and the request is supported, else on the CPU, labelled; `"require"` fails
-instead of falling back (`ImageKernelExecutionError`, acquisition failures here, later ones from `render`). `gpuDevice` is a
+instead of falling back (`ImageKernelExecutionError`, acquisition failures here, later ones from `render`). 2.20.0: the default is
+`"auto"` when the request resolves to fast (the view's default) and `"off"` with `fast: false`. `gpuDevice` is a
 WebGPU entry point or an `ImageKernelAccelerator` whose device the view shares; without it the engine acquires one device
 for the prepared view (the request's `signal` aborts the acquisition) and `dispose()` releases it. The realm's
 `setWebGpuEnabled(false)` vetoes both GPU modes (`webgpu-disabled`). See docs/DISPLAY_VIEW.md, "Rendering on the GPU".

package/docs/api/motion-subject-motion.md

@@ -0,0 +1,23 @@
+# motion/subject-motion.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.
+
+## SimulateCaptureSubjectMotion
+
+`motion.subject` of `simulateCapture`: a moving subject on the scene plane (#551).
+
+```ts
+export interface SimulateCaptureSubjectMotion {
+  /** Velocity on the scene plane, m/s: +x right, +y up as seen from the camera. Missing components are 0. */
+  velocityMPerSec?: { x?: number; y?: number };
+  /** Rotation about the optical axis direction, rad/s, counter-clockwise as seen from the camera (+x toward +y). Default 0. */
+  angularVelocityRadPerSec?: number;
+  /**
+   * The moving part: a rectangle on the scene plane at rest (at the first opening reference), its centre and size in metres
+   * (+x right, +y up from the optical axis). Omitted: the whole scene moves.
+   */
+  region?: { centerXM: number; centerYM: number; widthM: number; heightM: number };
+  /** Exact or fast (2.20.0 convention): fast takes fewer temporal midpoints when the subject's streak is short (see the docs). */
+  fast?: boolean;
+}
+```

package/docs/api/optics-aperture-diameter.md

@@ -0,0 +1,51 @@
+# optics/aperture-diameter.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.
+
+## ApertureDiameter
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ApertureDiameter {
+  /** Focal length supplied by the caller, in millimetres. */
+  focalLengthMm: number;
+  /** f-number supplied by the caller. */
+  fNumber: number;
+  /** Entrance-pupil diameter D = focalLengthMm / fNumber, in millimetres. */
+  entrancePupilDiameterMm: number;
+}
+```
+
+## calculateApertureDiameter
+
+Entrance-pupil (aperture) diameter in millimetres: focal length ÷ f-number.
+
+Exact by the definition of the f-number for an ideal lens focused at infinity. It is the
+entrance pupil (the aperture stop as seen from the front), not the diaphragm's physical
+opening. Close focus (working f-number N·(1 + m/P) with pupil magnification P) and focal-length
+changes while focusing are not modelled.
+
+Example: 50 mm at f/2 gives 25 mm; at f/4, 12.5 mm (half the diameter, a quarter of the area:
+two stops).
+
+```ts
+export function calculateApertureDiameter(
+  input: CalculateApertureDiameterInput
+): CalculationResult<ApertureDiameter>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateApertureDiameterInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateApertureDiameterInput {
+  /** Focal length of the lens in millimetres (the physical focal length, not a 35 mm equivalent). */
+  focalLengthMm: number;
+  /** f-number set on the lens (N = focal length / entrance-pupil diameter). */
+  fNumber: number;
+}
+```

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-lens-lateral-color.md

@@ -0,0 +1,79 @@
+# optics/generic-lens-lateral-color.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.
+
+## calculateLateralColorFringe
+
+The red–blue image displacement of a catalogue lens at a field position on a sensor, in micrometres and pixels, from the
+lens's own lateral-colour model Δr(λ) = L·R·H·D(λ) at the lens corrections' channel wavelengths (610 and 465 nm), or at the
+given `channelDispersion`. Exact for the model (no fast mode); an approximation of a generic lens, not a measured product.
+
+```ts
+export function calculateLateralColorFringe(input: CalculateLateralColorFringeInput): CalculationResult<LateralColorFringe>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLateralColorFringeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLateralColorFringeInput {
+  /** A catalogue id (`GENERIC_LENS_IDS`). */
+  lensId: string;
+  /** The sensor's active capture area, mm (the lens is scaled to it as in `resolveGenericLens`). */
+  activeImagingArea: { widthMm: number; heightMm: number };
+  /** The sensor's pixel pitch, µm. */
+  pixelPitchMicrometers: number;
+  /**
+   * The field position as fractions of the frame's half-width (x, +right) and half-height (y, +up) from the optical axis, each
+   * in [−1, 1]. Default `{ x: 1, y: 1 }`: the top-right corner.
+   */
+  fieldPosition?: { x: number; y: number };
+  /**
+   * 2.21.0: each channel's effective dispersion (`calculateChannelEffectiveDispersion` for the camera's channels and the light;
+   * only `red` and `blue` are read). Default: D at the single wavelengths 610 and 465 nm.
+   */
+  channelDispersion?: ChannelDispersion;
+}
+```
+
+## LateralColorDisplacement
+
+A signed displacement of the blue image from the red one: radial (positive: blue farther from the axis) and its x and y parts.
+
+```ts
+export interface LateralColorDisplacement {
+  radial: number;
+  x: number;
+  y: number;
+}
+```
+
+## LateralColorFringe
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LateralColorFringe {
+  lensId: string;
+  /** The image-plane point, mm from the optical axis (+x right, +y up). */
+  imagePointMm: { x: number; y: number };
+  /** Field height H: the point's distance from the axis as a fraction of the half-diagonal (1 at the corner). */
+  fieldHeight: number;
+  /** The channel wavelengths the displacement is taken at, nm; null with a given `channelDispersion`. */
+  channelWavelengthsNm: { red: number; blue: number } | null;
+  /** The red and blue dispersions D used (normalized: 0 at the d line, F minus C = 1). */
+  channelDispersion: { red: number; blue: number };
+  /** Blue-minus-red image displacement, µm. */
+  blueMinusRedMicrometers: LateralColorDisplacement;
+  /** The same in pixels of the given pitch. */
+  blueMinusRedPixels: LateralColorDisplacement;
+  /** The fringe width: |radial| displacement, µm and pixels. */
+  fringeWidthMicrometers: number;
+  fringeWidthPixels: number;
+  /** The lens's own F-to-C (486 to 656 nm) displacement at this point, L·R·H, µm. */
+  fToCMicrometers: number;
+}
+```

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

@@ -2,10 +2,19 @@
 
 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.
 
+## ChannelDispersion
+
+A normalized dispersion per channel (`genericLensDispersion` units: 0 at the d line, F minus C = 1).
+
+```ts
+export type ChannelDispersion = Readonly<Record<LensCorrectionChannel, number>>;
+```
+
 ## 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.
+a camera's channel responses peak, not a measured camera. The default of `createGenericLensCorrectionProfile` without a
+`channelDispersion`; `simulateCapture`'s `output.lensCorrections` uses the capture's own channels instead (#589).
 
 ```ts
 GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM: Readonly<Record<LensCorrectionChannel, number>> = Object.freeze({ red: 610, green: 540, blue: 465 })