@photivra/engine 2.17.0 → 2.19.0

package/dist/facade/simulate-capture.d.ts

@@ -6,6 +6,7 @@ import { type CaptureWhiteBalanceIntent } from "../capture/simulated-capture.js"
 import { type NativeRawOutput, type NativeRawPlan } from "../capture/native-raw.js";
 import { type DisplayViewExpectedSignal, type DisplayViewExpectedSignalInput } from "./expected-signal.js";
 import type { DisplayViewFastReport } from "./display-view-gpu.js";
+import type { DisplayViewLensPsf } from "./display-view-lens-signal.js";
 import { type NativeEnvironmentRawInput } from "../capture/native-environment-raw.js";
 import { type NativeRawDevelopmentInput, type RawHighlightDiagnostics } from "../capture/native-raw-development.js";
 import type { RawFrameReconstructionPhaseProfile } from "../capture/raw-frame-reconstruction.js";
@@ -156,6 +157,11 @@ export type SimulateCaptureColorEncoding = "srgb" | "display-p3" | "rec2020";
  * edge-directed method that reduces zipper and false colour on sharp edges.
  */
 export type SimulateCaptureDemosaic = "bilinear" | "ahd";
+/** `lens.catalogue` as a record (#568): the lens id as `kind` and the `fast` override (see {@link SimulateCaptureOptions.fast}). */
+export interface SimulateCaptureLensCatalogueRecord {
+    kind: string;
+    fast?: boolean;
+}
 /** `output.demosaic` as a record (#395): the demosaic and its `fast` override (see {@link SimulateCaptureOptions.fast}). */
 export interface SimulateCaptureDemosaicRecord {
     kind: SimulateCaptureDemosaic;
@@ -247,6 +253,18 @@ export interface SimulateCaptureDiffractionCorrection {
     /** FIR radius R in pixels, 1–16. Default: the Airy pattern's third dark ring at the design wavelength, within 1–16. */
     kernelRadiusPixels?: number;
 }
+/**
+ * `output.lensCorrections` (#570): which of the catalogue lens's generic corrections (`createGenericLensCorrectionProfile`) the
+ * development applies. Each is off unless set to true.
+ */
+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;
+}
 /** `diagnostics.detail` (#552): what the development detail stages did. Present only when one ran. */
 export interface SimulateCaptureDetailDiagnostics {
     diffractionCorrection?: {
@@ -299,6 +317,23 @@ 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
@@ -307,9 +342,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.
@@ -522,6 +560,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;
@@ -555,26 +603,26 @@ 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;
 }
 /**
  * Options reported in `diagnostics.options` (2.1), in this order, when they ran: the ones that change how much work
  * a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.temporalSampleCount` a count above 1.
  */
-export declare const SIMULATE_CAPTURE_COST_OPTIONS: readonly ["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"];
+export declare const SIMULATE_CAPTURE_COST_OPTIONS: readonly ["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.lensCorrections", "output.format.jpeg", "output.format.png", "output.format.dng"];
 export type SimulateCaptureCostOption = typeof SIMULATE_CAPTURE_COST_OPTIONS[number];
 /**
  * The options that take the exact-or-fast flag (#395), in the path style of {@link SIMULATE_CAPTURE_COST_OPTIONS}: each accepts
  * the record form with `fast` and is reported in `diagnostics.fast.applied` when it runs. Every one of them takes the flag,
  * whether or not it has a fast method yet; one without runs exact and reports `false`.
  */
-export declare const SIMULATE_CAPTURE_FAST_OPTIONS: readonly ["lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"];
+export declare const SIMULATE_CAPTURE_FAST_OPTIONS: readonly ["lens.diffraction", "lens.catalogue", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"];
 export type SimulateCaptureFastOption = typeof SIMULATE_CAPTURE_FAST_OPTIONS[number];
 /** `diagnostics.fast` of a capture or display view (#395): what was asked for and what ran. */
 export interface SimulateCaptureFastReport {
@@ -585,8 +633,15 @@ export interface SimulateCaptureFastReport {
     /** `engine-reference` when every option ran exact; `approximation-with-a-priori-bound` when any fast method ran (the WebGPU execution record's values). */
     assurance: "engine-reference" | "approximation-with-a-priori-bound";
 }
+/**
+ * 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.
+ */
 export interface SimulateCaptureProgress {
-    stage: "raw" | "white-balance" | "development" | "jpeg";
+    stage: "raw" | "white-balance" | "development" | "diffraction-correction" | "sharpening" | "jpeg";
     completedTileCount: number;
     totalTileCount: number;
 }
@@ -1107,6 +1162,8 @@ export interface DisplayViewRunContext {
      * through the lens (display-view-lens-signal.ts, loaded on demand); undefined without them (the rectilinear expected signal).
      */
     lens?: ((input: DisplayViewExpectedSignalInput, spanColumns?: number) => DisplayViewExpectedSignal) | undefined;
+    /** #569: with `lens.catalogue`, the field-dependent PSF the lens signal reads (createDisplayViewLensPsf, display-view-lens-signal.ts); its axis kernels set the expected signal's lattice. */
+    lensPsf?: DisplayViewLensPsf | undefined;
     diffractionPsf: {
         kind: "sampled-local";
         configuration: Pick<CalculateSensorPsfIrradianceQuadratureInput, "psf" | "psfWavelengthBasis" | "spatialModel">;
@@ -1187,11 +1244,13 @@ export interface ParsedDisplayView {
 export declare function parseDisplayViewOption(value: unknown, frameWidth: number, frameHeight: number): ParsedDisplayView;
 /** Internal: passed as the view of a "display-view" run to resolve the request without a view (`prepareDisplayView`, #387). */
 export declare const DISPLAY_VIEW_WITHOUT_VIEW: unique symbol;
+/** Internal: what `runCapture` produces. The two `-from-parts` runs take the parts as `viewOption`. */
+type CaptureRun = "capture" | "ideal-reference" | "display-view" | "dng-from-parts" | "develop-from-parts";
 /**
  * Internal: the request path shared by {@link simulateCapture}, {@link simulateIdealReference} and the display view, whose renderer is
  * passed in; for a display view the renderer's value is returned (a result, or a prepared view with DISPLAY_VIEW_WITHOUT_VIEW).
  */
-export declare function runCapture(options: SimulateCaptureOptions, run: "capture" | "ideal-reference" | "display-view" | "dng-from-parts", viewOption?: unknown, renderView?: (context: DisplayViewRunContext) => Promise<unknown>): Promise<unknown>;
+export declare function runCapture(options: SimulateCaptureOptions, run: CaptureRun, viewOption?: unknown, renderView?: (context: DisplayViewRunContext) => Promise<unknown>): Promise<unknown>;
 /** Chart preset ids accepted by `simulateCapture({ scene: { preset } })`. */
 export declare const SIMULATE_CAPTURE_CHART_PRESETS: readonly ("composite" | "uniform" | "patches" | "slanted-edge" | "siemens-star" | "step-wedge" | "grey-ramp" | "checkerboard" | "point-grid" | "color-patches" | "dead-leaves" | "bar-groups" | "hyperbolic-wedge" | "zone-plate" | "slanted-squares" | "line-grid" | "fiducial")[];
 export {};