@photivra/engine 2.9.0 → 2.10.0

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

@@ -30,7 +30,9 @@ export interface DisplayViewResult {
    * milliseconds (diagnostic only; never affects the samples).
    */
   diagnostics: { sampleCount: number; siteEvaluations: number; sceneLookups: number; detailPixelCount: number; uniformPixelCount: number; ahdCorrectedPixelCount: number;
-    timingsMs: { view: number; total: number } };
+    timingsMs: { view: number; total: number };
+    /** #395: exact or fast, as requested and as run (see {@link SimulateCaptureFastReport}). */
+    fast: SimulateCaptureFastReport };
   provenance: { scientificStatus: "approximation"; cameraPresetId: string; cameraPresetVersion: string; evidence: readonly EvidenceProvenance[];
     composedContracts: readonly string[]; limitations: readonly string[] };
   /** The capture request's assumptions, then `view.definition`, `view.estimation`, `view.noise`, `view.demosaic` and `view.source`. */
@@ -118,6 +120,16 @@ Version of how the facade builds requests. It changes whenever the same input wo
 SIMULATE_CAPTURE_FACADE_VERSION = "1.0.0" as const
 ```
 
+## SIMULATE_CAPTURE_FAST_OPTIONS
+
+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`.
+
+```ts
+SIMULATE_CAPTURE_FAST_OPTIONS = Object.freeze(["lens.diffraction", "sensor.antiAliasing", "sensor.pixelAperture.box", "output.demosaic.ahd"] as const)
+```
+
 ## SIMULATE_DISPLAY_VIEW_DEFAULT_SAMPLES_PER_AXIS
 
 Default stratified samples per axis of a display view (`view.samplesPerAxis`): 16 × 16 sampled real pixels per display pixel with detail, 4 × 4 where it is uniform.
@@ -193,6 +205,14 @@ edge-directed method that reduces zipper and false colour on sharp edges.
 export type SimulateCaptureDemosaic = "bilinear" | "ahd";
 ```
 
+## SimulateCaptureDemosaicRecord
+
+`output.demosaic` as a record (#395): the demosaic and its `fast` override (see {@link SimulateCaptureOptions.fast}).
+
+```ts
+export interface SimulateCaptureDemosaicRecord { kind: SimulateCaptureDemosaic; fast?: boolean }
+```
+
 ## SimulateCaptureDngPart
 
 One part of a whole-frame DNG (#391): a region render's packed RAW and where its native sites lie (`result.raw`, `result.region`).
@@ -212,6 +232,29 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export type SimulateCaptureExposureMode = "manual" | "aperture-priority" | "shutter-priority" | "program";
 ```
 
+## SimulateCaptureFastOption
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureFastOption = typeof SIMULATE_CAPTURE_FAST_OPTIONS[number];
+```
+
+## SimulateCaptureFastReport
+
+`diagnostics.fast` of a capture or display view (#395): what was asked for and what ran.
+
+```ts
+export interface SimulateCaptureFastReport {
+  /** True when `fast: true` was given at the top level or in any option's record. */
+  requested: boolean;
+  /** 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). */
+  assurance: "engine-reference" | "approximation-with-a-priori-bound";
+}
+```
+
 ## SimulateCaptureLensDistortion
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -332,8 +375,8 @@ export interface SimulateCaptureOptions {
      * through `prepareRgbGamutMapping`: constant CIELAB L* and hue, chroma above 90 % of the boundary compressed.
      */
     gamutMapping?: "clip" | "perceptual";
-    /** Default: the 1.0 facade's bilinear RGGB kernels. */
-    demosaic?: SimulateCaptureDemosaic;
+    /** Default: the 1.0 facade's bilinear RGGB kernels. The record form (#395) adds a `fast` override. */
+    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. */
@@ -391,6 +434,13 @@ 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. No option has a fast method yet, so every result is 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. */
@@ -408,10 +458,10 @@ export type SimulateCaptureOutputFormat = "srgb-8" | "srgb-16" | "jpeg" | "png"
 
 ## SimulateCapturePixelAperture
 
-Pixel aperture (2.3): centre sampling, or the square photosite integrated with an N × N midpoint rule.
+Pixel aperture (2.3): centre sampling, or the square photosite integrated with an N × N midpoint rule; `fast` (#395) overrides the top-level flag.
 
 ```ts
-export type SimulateCapturePixelAperture = "point" | "box" | { kind: "box"; samplesPerAxis?: number };
+export type SimulateCapturePixelAperture = "point" | "box" | { kind: "box"; samplesPerAxis?: number; fast?: boolean };
 ```
 
 ## SimulateCaptureProgress
@@ -532,6 +582,8 @@ export interface SimulateCaptureResult {
      * the user's device.
      */
     options: readonly SimulateCaptureCostOption[];
+    /** #395: exact or fast, as requested and as run (see {@link SimulateCaptureFastReport}). */
+    fast: SimulateCaptureFastReport;
   };
   provenance: {
     scientificStatus: "approximation";
@@ -559,9 +611,9 @@ frequency 1/(2·pitch)).
 
 ```ts
 export type SimulateCaptureSensorAntiAliasing =
-  | { kind: "four-spot"; separationSites?: number }
-  | { kind: "two-spot"; axis: "horizontal" | "vertical"; separationSites?: number }
-  | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[] };
+  | { kind: "four-spot"; separationSites?: number; fast?: boolean }
+  | { kind: "two-spot"; axis: "horizontal" | "vertical"; separationSites?: number; fast?: boolean }
+  | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[]; fast?: boolean };
 ```
 
 ## SimulateCaptureWhiteBalance

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

@@ -11,8 +11,30 @@ setup: use it to render one view in many regions, for example on each worker of
 
 ```ts
 export interface PreparedDisplayView {
-  /** Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup. */
+  /**
+   * Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup and the
+   * realm's AHD correction states, which never change a byte (docs/DISPLAY_VIEW.md, "AHD at low signal").
+   */
   render(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewResult>;
+  /**
+   * 2.10 (#447): the key of this request's AHD low-signal correction states, or null when the request has no AHD
+   * (`output.demosaic` other than "ahd"). Every input of the key is fixed when the request is prepared; two prepared views
+   * with the same key read the same states.
+   */
+  correctionKey(): string | null;
+  /**
+   * 2.10 (#447): the grid keys of every correction state a render of `view` reads (ascending, whether or not this realm holds
+   * them), found by a render of the view's region that records the states instead of computing them. No image is returned;
+   * it costs about one render whose states are all held. Fails with an InvalidConfigurationError when the request has no AHD.
+   */
+  collectCorrectionStates(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewCorrectionStateKeys>;
+  /**
+   * 2.10 (#447): computes the correction states of `gridKeys` (from `collectCorrectionStates`, or a share of them) as a render
+   * would, stores them in this realm's cache and returns their values, for {@link bindDisplayViewCorrectionStates} in
+   * another realm. States this realm holds are read, not computed. Yields and honours `signal` like `render`. Fails with an
+   * InvalidConfigurationError when the request has no AHD or a grid key is out of range.
+   */
+  computeCorrectionStates(gridKeys: Int32Array, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewCorrectionStateSet>;
 }
 ```
 

package/docs/api/gpu-image-kernel-execution.md

@@ -51,6 +51,11 @@ export interface ImageKernelExecution {
   fallbackReason: ImageKernelFallbackReason | null;
   arithmetic: "float64" | "float32";
   assurance: "engine-reference" | "approximation-with-a-priori-bound";
+  /**
+   * The exact-or-fast flag in the facade's words (#395): false for `cpu-reference` (the engine reference), true for
+   * `webgpu-f32` (a bounded approximation). `backend` still names where the work ran.
+   */
+  fast: boolean;
   /**
    * True only for `cpu-reference`. Bit-exact identities (SHA-256 artifact bindings, byte-parity fixtures,
    * cross-engine determinism hashes) are CPU-only and must never be computed from a `webgpu-f32` result.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",