@photivra/engine 2.10.0 → 2.12.0

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

@@ -21,8 +21,10 @@ export interface DisplayViewResult {
    */
   view: { width: number; height: number; frameWidth: number; frameHeight: number; scaleX: number; scaleY: number; samplesPerAxis: number;
     region?: { x: number; y: number; width: number; height: number } };
-  /** The resolved exposure of the capture this view shows. */
-  exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; iso: number }; ev100: number };
+  /** The resolved exposure of the capture this view shows; `standardExposureDeviationStops` as in {@link SimulateCaptureResult}. */
+  exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; iso: number }; ev100: number; standardExposureDeviationStops: number | null;
+    /** #516: as in the capture result. */
+    isoControl: "manual" | "automatic"; autoIso?: SimulateCaptureAutoIsoReport };
   scene: SimulateCaptureResult["scene"];
   /**
    * Work done: real pixels sampled, real-site expectations evaluated, scene queries, display pixels sampled in full (detail) or with
@@ -31,8 +33,8 @@ export interface DisplayViewResult {
    */
   diagnostics: { sampleCount: number; siteEvaluations: number; sceneLookups: number; detailPixelCount: number; uniformPixelCount: number; ahdCorrectedPixelCount: number;
     timingsMs: { view: number; total: number };
-    /** #395: exact or fast, as requested and as run (see {@link SimulateCaptureFastReport}). */
-    fast: SimulateCaptureFastReport };
+    /** #395: exact or fast, as requested and as run; 2.11 (#481): plus `execution`, where the render ran (see {@link DisplayViewFastReport}). */
+    fast: DisplayViewFastReport };
   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`. */
@@ -53,7 +55,9 @@ export interface IdealReferenceResult {
   engineApiVersion: string;
   image: { width: number; height: number; format: SimulateCaptureOutputFormat; samples: Uint8Array | Uint16Array; png?: Uint8Array; colorEncoding?: SimulateCaptureColorEncoding };
   /** The resolved exposure of the capture this reference matches. */
-  exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; iso: number }; ev100: number };
+  exposure: { mode: SimulateCaptureExposureMode; settings: { fNumber: number; shutterSeconds: number; iso: number }; ev100: number;
+    /** #516: as in the capture result. */
+    isoControl: "manual" | "automatic"; autoIso?: SimulateCaptureAutoIsoReport };
   scene: SimulateCaptureResult["scene"];
   region?: { x: number; y: number; width: number; height: number; frameWidth: number; frameHeight: number };
   diagnostics: { sampleCount: number; timingsMs: { reference: number; total: number } };
@@ -96,7 +100,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", "sensor.antiAliasing", "sensor.pixelAperture.box", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "output.region",
+  "lens.diffraction", "lens.defocus", "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.format.jpeg", "output.format.png", "output.format.dng"] as const)
 ```
@@ -163,6 +167,45 @@ export interface SimulateCaptureAssumption {
 }
 ```
 
+## SimulateCaptureAutoIsoAfterMaximum
+
+#516: what aperture priority does with Auto ISO once the ISO reaches the body's Auto ISO maximum and the exposure is
+still under the meter target: `"allow-slower-shutter"` lengthens the shutter past the slowest preferred shutter to reach
+the target; `"hold-preferred-shutter"` keeps the preferred shutter and leaves the exposure under target.
+
+```ts
+export type SimulateCaptureAutoIsoAfterMaximum = "allow-slower-shutter" | "hold-preferred-shutter";
+```
+
+## SimulateCaptureAutoIsoReport
+
+#516: how Auto ISO chose the ISO (`exposure.iso: "auto"`), reported in the result's `exposure.autoIso`. The full
+resolver output stays in the capture's `exposure.resolution`.
+
+```ts
+export interface SimulateCaptureAutoIsoReport {
+  /** The ISO the meter target asked for at the resolved aperture and shutter, before the Auto ISO range and the ISO grid. */
+  idealIsoBeforeConstraints: number;
+  /** The Auto ISO range the ISO was chosen in: the body's Auto ISO bounds, or its ISO range when it declares none (the tiers: ISO 100 to their maximum). */
+  autoIsoMinimum: number;
+  autoIsoMaximum: number;
+  /** Whether the ISO was held at an end of the Auto ISO range. */
+  clamped: false | "minimum" | "maximum";
+  /**
+   * The constraint that limited the resolved exposure: the resolver's `targetResidual.limitingConstraint`, for example
+   * `"iso-maximum"` (the exposure stays under target at the Auto ISO maximum), `"iso-grid-quantization"` (the nearest
+   * selectable ISO) or `"none"` (on target).
+   */
+  limitingConstraint: ExposureResolutionConstraint;
+  /** The resolver's residual, log2(target / achieved exposure), in stops: positive when the exposure is under the meter target, negative when over it. */
+  residualStops: number;
+  /** Aperture priority only: the policy and slowest preferred shutter used, and whether the slower-shutter fallback ran. */
+  afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum;
+  slowestPreferredShutterSeconds?: number;
+  afterMaximumIsoFallbackUsed?: boolean;
+}
+```
+
 ## SimulateCaptureBorderHandling
 
 `margin` renders extra native sites around the output, as far as the kernel reaches. `mirror` renders
@@ -323,19 +366,47 @@ export interface SimulateCaptureOptions {
      * the longest spectral node, capped at 32 sites. Not combinable with `psf` or `pupilSampling`. Default off.
      */
     diffraction?: SimulateCaptureLensDiffraction;
+    /**
+     * Opt-in (#492): defocus of the flat scene plane when `focusDistanceM` differs from the subject distance, as a
+     * geometric disc (`model: "geometric-disc"`): the thin-lens blur circle of an ideal uniform circular pupil
+     * (`calculateDefocusCircle`), an approximation. The blur diameter is recorded in the `lens.defocus` assumption.
+     * `simulateCapture` renders the blur as an object-space convolution of the scene radiance on the site lattice and
+     * `simulateDisplayView` as a site kernel in its expected signal; with `diffraction` each spectral node's diffraction
+     * kernel is convolved with the disc (a further approximation). In focus the result is that of the same request
+     * without the option, plus the assumption.
+     * Not combinable with `pupilSampling` or `psf`. Default off.
+     */
+    defocus?: { model: "geometric-disc" };
   };
   exposure?: {
     /** Default "manual". */
     mode?: SimulateCaptureExposureMode;
-    /** Default 100. */
-    iso?: number;
+    /**
+     * Default 100. #516: `"auto"` lets the body's Auto ISO choose the ISO from the meter target, within its Auto ISO range
+     * (the tiers: ISO 100 to their maximum), in every mode: manual keeps the aperture and shutter; aperture priority keeps the
+     * aperture and follows `autoIso`; shutter priority picks the aperture at the lowest Auto ISO (no wider than the target
+     * needs, so at most the widest) and raises the ISO for the rest; program picks the program line at the lowest Auto ISO and
+     * raises the ISO beyond the line's end. The result reports the ISO in `exposure.settings.iso` and how it was chosen in
+     * `exposure.autoIso`.
+     */
+    iso?: number | "auto";
+    /**
+     * #516: aperture priority with `iso: "auto"` only (required there). The shutter gets as long as
+     * `slowestPreferredShutterSeconds` (seconds, within the body's shutter range) at the lowest Auto ISO; beyond it the ISO
+     * rises; at the Auto ISO maximum `afterMaximumIso` decides (default `"allow-slower-shutter"`).
+     */
+    autoIso?: { slowestPreferredShutterSeconds: number; afterMaximumIso?: SimulateCaptureAutoIsoAfterMaximum };
     /** Shutter for manual and shutter-priority modes. Default 1/125 s. */
     shutterSeconds?: number;
     /** Exposure compensation applied to the meter target, in stops. Default 0. */
     compensationStops?: number;
   };
-  /** Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card) or a caller reflectance/radiance function. */
-  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
+  /**
+   * 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.
+   */
+  scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
   /** Distance from the camera to the scene plane in metres. Default 5. */
   subjectDistanceM?: number;
   /**
@@ -533,7 +604,18 @@ export interface SimulateCaptureResult {
     settings: { fNumber: number; shutterSeconds: number; iso: number };
     /** Exposure value at ISO 100 of the settings, log2(N²/t). */
     ev100: number;
+    /** #516: `"automatic"` when the request asked for `iso: "auto"`, else `"manual"`. */
+    isoControl: "manual" | "automatic";
+    /** #516: present with `iso: "auto"`: how Auto ISO chose `settings.iso` and what limited it. */
+    autoIso?: SimulateCaptureAutoIsoReport;
     meteredSceneLuminanceCdPerSquareMeter: number;
+    /**
+     * #515: deviation, in stops, of the exposure used from the CIPA DC-004-2020 standard exposure for the metered luminance L:
+     * log2(N²/t) − log2(0.65·L·S/10). Positive is darker than the standard exposure (under), negative brighter (over). In an
+     * automatic mode it is the compensation with the opposite sign plus any step or limit the resolver hit. Finite, or null when
+     * the metered luminance is 0 (a black scene has no standard exposure).
+     */
+    standardExposureDeviationStops: number | null;
     /** Full output of the existing exposure-mode resolver. */
     resolution: unknown;
   };
@@ -574,8 +656,10 @@ export interface SimulateCaptureResult {
      * `diffraction` (the object-space convolution of `lens.diffraction`; part of `raw` and `whiteBalance`), `demosaic`
      * (the AHD demosaic; part of `development`) and `encode` (PNG, JPEG or DNG serialization), with sub-millisecond
      * resolution where the host has `performance.now()`. Timings vary from run to run and never enter any digest or output byte.
+     * #492: `defocus`, the object-space convolution of `lens.defocus` out of focus (with `lens.diffraction` the combined
+     * kernel's convolution, reported here instead of under `diffraction`).
      */
-    timingsMs: { raw: number; whiteBalance: number; development: number; jpeg: number; total: number; diffraction?: number; demosaic?: number; encode?: number };
+    timingsMs: { raw: number; whiteBalance: number; development: number; jpeg: number; total: number; diffraction?: number; defocus?: number; demosaic?: number; encode?: number };
     /**
      * 2.1: the opt-in options that changed the work of this run, in a fixed order (see `SIMULATE_CAPTURE_COST_OPTIONS`).
      * Empty for a capture with every default. With `timingsMs` it lets an application measure each option's cost on

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

@@ -13,9 +13,17 @@ setup: use it to render one view in many regions, for example on each worker of
 export interface PreparedDisplayView {
   /**
    * 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").
+   * realm's AHD correction states, which never change a byte (docs/DISPLAY_VIEW.md, "AHD at low signal"). With `gpu: "auto"`
+   * or `"require"` (#481) GPU renders of one prepared view run one at a time on its device, and `diagnostics.fast.execution`
+   * says whether the GPU or the CPU reference rendered the view, and why.
    */
   render(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewResult>;
+  /**
+   * 2.11 (#481): releases the WebGPU device the view acquired (none with `gpu: "off"`, or when `gpuDevice` gave an accelerator,
+   * whose device its owner keeps). Later renders run the CPU reference labelled `fallbackReason: "disposed"` (`"auto"`) or fail
+   * with that reason (`"require"`). Idempotent.
+   */
+  dispose(): void;
   /**
    * 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
@@ -57,8 +65,15 @@ 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
+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
+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".
+
 ```ts
-export async function prepareDisplayView(options: SimulateCaptureOptions): Promise<PreparedDisplayView>;
+export async function prepareDisplayView(options: SimulateCaptureOptions, prepareOptions?: PrepareDisplayViewOptions): Promise<PreparedDisplayView>;
 ```
 
 This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.

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

@@ -71,6 +71,8 @@ export interface ImageKernelAccelerator {
   readonly backend: ImageKernelBackend;
   readonly requestedBackend: ImageKernelBackend;
   readonly fallbackReason: ImageKernelFallbackReason | null;
+  /** #481: the adapter of a `webgpu-f32` accelerator's device (null for `cpu-reference`, or when the browser gives no `GPUAdapter.info`). */
+  readonly adapter: ImageKernelAdapterDescription | null;
   readonly state: ImageKernelAcceleratorState;
   renderNativeCaptureSdr(input: NativeCaptureSdrInput, provider: NativeCaptureSdrProvider, options?: ImageKernelRunOptions): Promise<AcceleratedNativeCaptureSdrOutput>;
   /** Takes ownership of `input.raw` exactly like `createNativeRawDevelopmentTask` (the caller's arrays are detached). */
@@ -93,9 +95,14 @@ The exact contract is declared below; use the domain guide for assumptions and s
 
 ```ts
 export interface ImageKernelAcceleratorOptions {
-  /** Requested backend. `cpu-reference` is the reference and never touches WebGPU. */
-  backend: ImageKernelBackend;
-  /** Required with `webgpu-f32`: use the CPU reference (labelled) or fail when WebGPU cannot be acquired. */
+  /**
+   * The one-boolean form. `true` is `backend: "webgpu-f32"` with `fallback: "cpu-reference"` unless `fallback` is given;
+   * `false` is `backend: "cpu-reference"`. Give `webgpu` or `backend`, not both.
+   */
+  webgpu?: boolean;
+  /** Requested backend. `cpu-reference` is the reference and never touches WebGPU. Required unless `webgpu` is given. */
+  backend?: ImageKernelBackend;
+  /** Required with `backend: "webgpu-f32"`: use the CPU reference (labelled) or fail when WebGPU cannot be acquired. */
   fallback?: "cpu-reference" | "fail";
   /** WebGPU entry point; defaults to `navigator.gpu`. Supply a worker's `navigator.gpu` explicitly if needed. */
   gpu?: unknown;

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

@@ -2,6 +2,58 @@
 
 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.
 
+## ChartCompositeProbeComponent
+
+A component of the composite chart kernel's double-float32 probe (see {@link ChartCompositeProbeRecord}). The first four are the
+outputs of the probe before 2.11.0: `two-sum` is TwoSum's low part (`s.l`), `two-product` Dekker's TwoProduct low part (`m.l`),
+`double-word-add` the double-word sum's low part (`a.l`), `double-word-multiply` the Dekker double-word product (`q.h`, `q.l`).
+
+```ts
+export type ChartCompositeProbeComponent = "two-sum" | "two-product" | "double-word-add" | "double-word-multiply" | "fma-two-product" | "fma-double-word-multiply";
+```
+
+## ChartCompositeProbeMismatch
+
+One probe output that differs from its expected value: the component, the probe input's index, and the float32 bits (hex).
+
+```ts
+export interface ChartCompositeProbeMismatch {
+  component: ChartCompositeProbeComponent;
+  input: number;
+  got: string;
+  want: string;
+}
+```
+
+## ChartCompositeProbeRecord
+
+The composite chart kernel's device probe (docs/WEBGPU.md, "Scene radiance on the GPU"): how the device evaluated the kernel's
+double-float32 building blocks, and which product path the kernel was compiled with. Diagnostic; it never changes a result.
+
+- `deviceClass`: `exact` (the written order, round to nearest); `contracted` (only the Dekker product paths differ, consistent
+  with a multiply and an add fused into one rounding); `reassociated` (a sum path differs and every differing sum low part is
+  zero, the value an algebraic simplification of (a + b) − a to b gives); `other` (anything else, such as a sum path that differs
+  with non-zero low parts, as a rounding not to nearest gives, or a non-finite output).
+- `productPath`: `dekker` when the Dekker path passes, else `fma` when the fma path passes (which needs a fused `fma`), else null
+  (the device is refused for composite charts, the 2.3 elements and material-layers scenes).
+- `fmaFused`: whether every fma TwoProduct low part was exact (a fused `fma`; WGSL also allows an unfused one).
+
+```ts
+export interface ChartCompositeProbeRecord {
+  deviceClass: "exact" | "contracted" | "reassociated" | "other";
+  productPath: "dekker" | "fma" | null;
+  fmaFused: boolean;
+  /** Probe inputs, each checked on every component. */
+  inputs: number;
+  /** Differing outputs per component. */
+  mismatchCounts: Readonly<Record<ChartCompositeProbeComponent, number>>;
+  /** The indices of the probe inputs (`PROBE_INPUTS`) whose output differs, per component. */
+  mismatchedInputs: Readonly<Record<ChartCompositeProbeComponent, readonly number[]>>;
+  /** The first differing outputs (at most eight), in component order. */
+  mismatches: readonly ChartCompositeProbeMismatch[];
+}
+```
+
 ## composeRelativeErrorBounds
 
 Composes two `relative-to-reference` bounds through a pipeline `second ∘ first`, where the second
@@ -17,6 +69,20 @@ export function composeRelativeErrorBounds(first: ImageKernelRelativeErrorBound,
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## ImageKernelAdapterDescription
+
+#481: the WebGPU adapter a device came from, as `GPUAdapter.info` describes it (W3C WebGPU, `GPUAdapterInfo`): each field
+is the browser's string, or empty when the browser withholds it. Diagnostic only; it never changes a result.
+
+```ts
+export interface ImageKernelAdapterDescription {
+  vendor: string;
+  architecture: string;
+  device: string;
+  description: string;
+}
+```
+
 ## ImageKernelBackend
 
 Requested or actual execution backend.
@@ -92,19 +158,20 @@ export class ImageKernelExecutionError extends Error {
 
 ## ImageKernelFailureReason
 
-Failure classes reported by {@link ImageKernelExecutionError}.
+Failure classes reported by {@link ImageKernelExecutionError}. `conformance-failed` (#481): a device failed the display view's
+run-time self-check with `gpu: "require"`.
 
 ```ts
 export type ImageKernelFailureReason = ImageKernelFallbackReason | "device-lost" | "out-of-memory" | "gpu-validation" |
-  "aborted" | "disposed" | "busy" | "unsupported-on-backend" | "unsupported-float32-domain" | "indeterminate-float32-classification";
+  "aborted" | "disposed" | "busy" | "unsupported-on-backend" | "unsupported-float32-domain" | "indeterminate-float32-classification" | "conformance-failed";
 ```
 
 ## ImageKernelFallbackReason
 
-Why a requested WebGPU backend was not used (only with `fallback: "cpu-reference"`).
+Why a requested `webgpu-f32` backend ran the CPU reference instead. `webgpu-disabled`: `setWebGpuEnabled(false)` in this realm.
 
 ```ts
-export type ImageKernelFallbackReason = "webgpu-unavailable" | "adapter-unavailable" | "device-request-failed" |
+export type ImageKernelFallbackReason = "webgpu-unavailable" | "webgpu-disabled" | "adapter-unavailable" | "device-request-failed" |
   "insufficient-limits" | "unsupported-platform-endianness";
 ```
 

package/docs/api/gpu-webgpu-switch.md

@@ -0,0 +1,23 @@
+# gpu/webgpu-switch.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.
+
+## getWebGpuEnabled
+
+Whether this realm may use WebGPU when a caller asks for it.
+
+```ts
+export function getWebGpuEnabled(): boolean;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## setWebGpuEnabled
+
+Turns WebGPU on (`true`, the default) or off (`false`) for this realm. Anything but a boolean is refused.
+
+```ts
+export function setWebGpuEnabled(enabled: boolean): void;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.10.0",
+  "version": "2.12.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",
@@ -88,6 +88,8 @@
     "bench:webgpu": "vitest run --config vitest.webgpu-timing.config.ts",
     "test:webgpu:hardware": "node scripts/run-webgpu-hardware.mjs test",
     "bench:webgpu:hardware": "node scripts/run-webgpu-hardware.mjs bench",
+    "accept:gpu": "node scripts/accept-display-view-gpu.mjs --gpu",
+    "accept:gpu:hardware": "node scripts/accept-display-view-gpu.mjs --gpu --hardware",
     "check:browser-surface": "node scripts/check-browser-surface.mjs",
     "check:licenses": "node scripts/check-license-policy.mjs",
     "check:license-headers": "node scripts/check-license-headers.mjs",