@photivra/engine 2.0.0 → 2.2.0

package/dist/facade/host-yield.js

@@ -2,10 +2,6 @@
 /** Returns a function that yields to the host event loop once per call, and the mechanism it uses. */
 export function createHostYield(host = globalThis) {
     const g = host;
-    const scheduler = g.scheduler;
-    if (scheduler !== undefined && typeof scheduler.yield === "function") {
-        return { mechanism: "scheduler.yield", yieldControl: async () => { await scheduler.yield.call(scheduler); } };
-    }
     const Channel = g.MessageChannel;
     if (typeof Channel === "function") {
         return { mechanism: "message-channel", yieldControl: () => new Promise((resolve) => {

package/dist/facade/host-yield.js.map

@@ -1 +1 @@
-{"version":3,"file":"host-yield.js","sourceRoot":"","sources":["../../src/facade/host-yield.ts"],"names":[],"mappings":"AAAA,sCAAsC;AA2BtC,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,OAAe,UAAU;IACvD,MAAM,CAAC,GAAG,IAAoB,CAAC;IAC/B,MAAM,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC;IAC9B,IAAI,SAAS,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACrE,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,KAAK,IAAmB,EAAE,GAAG,MAAM,SAAS,CAAC,KAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChI,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,CAAC,cAAc,CAAC;IACjC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBACvF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;gBAC9B,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,GAAS,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;gBAC5E,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;YACvC,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,CAAC,YAAY,CAAC;IACjC,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;QACpC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChI,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACvH,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Host yield for the capture facade's cooperative tasks. Browsers clamp nested `setTimeout(…, 0)` to\n * at least 4 ms (WHATWG HTML timers, nesting level above 5), so a task that yields every few\n * milliseconds through timers can sit idle for a large share of its run time. These yields are not\n * clamped. The first available mechanism is used:\n *\n * 1. `scheduler.yield()` (Prioritized Task Scheduling API), which also keeps the task's priority;\n * 2. a `MessageChannel` message, a new task without the timer clamp (one channel per yield, closed after\n *    delivery, so no port keeps a Node process alive);\n * 3. `setImmediate` (Node and some other non-browser hosts);\n * 4. `setTimeout(…, 0)` as the last resort.\n *\n * Only global feature detection is used; nothing is imported, so the browser package surface is unchanged.\n * The yield changes scheduling only, never results.\n */\n\ntype YieldGlobals = {\n  scheduler?: { yield?: () => Promise<unknown> };\n  MessageChannel?: new () => { port1: { onmessage: ((event: unknown) => void) | null; close(): void }; port2: { postMessage(message: unknown): void } };\n  setImmediate?: (callback: () => void) => unknown;\n};\n\n/** Mechanism chosen by {@link createHostYield}, for diagnostics and tests. */\nexport type HostYieldMechanism = \"scheduler.yield\" | \"message-channel\" | \"set-immediate\" | \"set-timeout\";\n\n/** Returns a function that yields to the host event loop once per call, and the mechanism it uses. */\nexport function createHostYield(host: object = globalThis): { mechanism: HostYieldMechanism; yieldControl: () => Promise<void> } {\n  const g = host as YieldGlobals;\n  const scheduler = g.scheduler;\n  if (scheduler !== undefined && typeof scheduler.yield === \"function\") {\n    return { mechanism: \"scheduler.yield\", yieldControl: async (): Promise<void> => { await scheduler.yield!.call(scheduler); } };\n  }\n  const Channel = g.MessageChannel;\n  if (typeof Channel === \"function\") {\n    return { mechanism: \"message-channel\", yieldControl: () => new Promise<void>((resolve) => {\n      const channel = new Channel();\n      channel.port1.onmessage = (): void => { channel.port1.close(); resolve(); };\n      channel.port2.postMessage(undefined);\n    }) };\n  }\n  const immediate = g.setImmediate;\n  if (typeof immediate === \"function\") {\n    return { mechanism: \"set-immediate\", yieldControl: () => new Promise<void>((resolve) => { immediate.call(host, resolve); }) };\n  }\n  return { mechanism: \"set-timeout\", yieldControl: () => new Promise<void>((resolve) => { setTimeout(resolve, 0); }) };\n}\n"]}
+{"version":3,"file":"host-yield.js","sourceRoot":"","sources":["../../src/facade/host-yield.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAsCtC,sGAAsG;AACtG,MAAM,UAAU,eAAe,CAAC,OAAe,UAAU;IACvD,MAAM,CAAC,GAAG,IAAoB,CAAC;IAC/B,MAAM,OAAO,GAAG,CAAC,CAAC,cAAc,CAAC;IACjC,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBACvF,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;gBAC9B,OAAO,CAAC,KAAK,CAAC,SAAS,GAAG,GAAS,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;gBAC5E,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;YACvC,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IACD,MAAM,SAAS,GAAG,CAAC,CAAC,YAAY,CAAC;IACjC,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;QACpC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChI,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACvH,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Host yield for the capture facade's cooperative tasks. Browsers clamp nested `setTimeout(…, 0)` to\n * at least 4 ms (WHATWG HTML timers, nesting level above 5), so a task that yields every few\n * milliseconds through timers can sit idle for a large share of its run time. The first available\n * mechanism is used:\n *\n * 1. a `MessageChannel` message, a new task without the timer clamp (one channel per yield, closed after\n *    delivery, so no port keeps a Node process alive);\n * 2. `setImmediate` (Node and some other non-browser hosts);\n * 3. `setTimeout(…, 0)` as the last resort.\n *\n * Every yield must let tasks that are already queued run first, so that a caller's cancel message (for\n * example a Web Worker `message` event that aborts the capture's `AbortSignal`) is handled at the next\n * yield. A `MessageChannel` message is queued on the HTML posted message task source, the same source as\n * worker and port `message` events, and tasks from one source run in the order they were queued.\n *\n * `scheduler.yield()` is deliberately not used (engine 2.0.0 used it first). Its continuation inherits\n * the \"user-visible\" priority and gets a higher effective priority than ordinary tasks; the WICG\n * Prioritized Task Scheduling draft (§ \"Task and Continuation Priorities\", effective priority table;\n * § \"Event loop: processing model\" note) intends such continuations to run ahead of most other task\n * sources, and its explainer (\"Preventing Task Starvation by Continuations\") only bounds that by\n * duration. A capture that yields every 8 ms through `scheduler.yield()` therefore starved a worker's\n * cancel message until the capture finished (measured in Chromium).\n *\n * Only global feature detection is used; nothing is imported, so the browser package surface is unchanged.\n * The yield changes scheduling only, never results.\n */\n\ntype YieldGlobals = {\n  MessageChannel?: new () => { port1: { onmessage: ((event: unknown) => void) | null; close(): void }; port2: { postMessage(message: unknown): void } };\n  setImmediate?: (callback: () => void) => unknown;\n};\n\n/** Mechanism chosen by {@link createHostYield}, for diagnostics and tests. */\nexport type HostYieldMechanism = \"message-channel\" | \"set-immediate\" | \"set-timeout\";\n\n/** Returns a function that yields to the host event loop once per call, and the mechanism it uses. */\nexport function createHostYield(host: object = globalThis): { mechanism: HostYieldMechanism; yieldControl: () => Promise<void> } {\n  const g = host as YieldGlobals;\n  const Channel = g.MessageChannel;\n  if (typeof Channel === \"function\") {\n    return { mechanism: \"message-channel\", yieldControl: () => new Promise<void>((resolve) => {\n      const channel = new Channel();\n      channel.port1.onmessage = (): void => { channel.port1.close(); resolve(); };\n      channel.port2.postMessage(undefined);\n    }) };\n  }\n  const immediate = g.setImmediate;\n  if (typeof immediate === \"function\") {\n    return { mechanism: \"set-immediate\", yieldControl: () => new Promise<void>((resolve) => { immediate.call(host, resolve); }) };\n  }\n  return { mechanism: \"set-timeout\", yieldControl: () => new Promise<void>((resolve) => { setTimeout(resolve, 0); }) };\n}\n"]}

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

@@ -12,6 +12,8 @@ import type { RadialDistortionProfile } from "../optics/radial-distortion.js";
 import type { BrownConradyDistortionProfile } from "../optics/brown-conrady-distortion.js";
 import type { IlluminationVignettingProfile } from "../optics/illumination-vignetting.js";
 import type { CalculateEnvironmentSensorPhotoSignalInput } from "../sensor/environment-photo-signal.js";
+import { type DiffractionLimitedPsfProfile } from "../optics/diffraction-psf-profile.js";
+import { type AntiAliasingPointSplitComponent } from "../sensor/optical-stack.js";
 import { type ChartScene } from "./chart-scenes.js";
 import { type CaptureIlluminant, type CallerRadianceScene, type CallerReflectanceScene } from "./scene-radiance.js";
 /** Version of how the facade builds requests. It changes whenever the same input would build a different request. */
@@ -38,8 +40,12 @@ export type SimulateCaptureWhiteBalance = "scene-illuminant" | "auto" | "none" |
  * PQ and HLG (BT.2100) are not part of 2.0; see THIRD_PARTY.md.
  */
 export type SimulateCaptureColorEncoding = "srgb" | "display-p3" | "rec2020";
-/** Built-in Bayer demosaic kernels (`createBuiltInBayerDemosaicProfiles`). */
-export type SimulateCaptureDemosaic = "bilinear";
+/**
+ * Demosaic. `bilinear`: the built-in Bayer kernels (`createBuiltInBayerDemosaicProfiles`). `ahd` (2.1): adaptive
+ * homogeneity-directed demosaicing (`createAhdDemosaicTask`, after Hirakawa & Parks 2005), a non-linear
+ * edge-directed method that reduces zipper and false colour on sharp edges.
+ */
+export type SimulateCaptureDemosaic = "bilinear" | "ahd";
 /**
  * `margin` renders extra native sites around the output, as far as the kernel reaches. `mirror` renders
  * exactly the output and reads mirrored (reflect-101) copies of the missing border sites. Mirroring is
@@ -53,6 +59,32 @@ export type SimulateCaptureLensDistortion = {
     kind: "brown-conrady";
     profile: BrownConradyDistortionProfile;
 };
+/** Diffraction model (2.1): the shorthand or a record with an explicit kernel radius in sites. */
+export type SimulateCaptureLensDiffraction = "circular-aperture" | {
+    aperture: "circular-aperture";
+    kernelRadiusSamples?: number;
+};
+/**
+ * Optical anti-aliasing (low-pass) filter (2.1), modelled as birefringent point splitting: each image point is
+ * split into equally bright copies (the engine's `normalized-point-splitting-kernel` optical-stack response).
+ * - `four-spot`: two crossed birefringent plates; copies at (±d/2, ±d/2), weight 1/4 each, MTF |cos(π·f_x·d)·cos(π·f_y·d)|.
+ * - `two-spot`: one plate splitting along `axis`; copies at ±d/2, weight 1/2 each, MTF |cos(π·f·d)|.
+ * - `point-splitting`: the engine contract itself, offsets in micrometres (+x right, +y down) and positive weights
+ *   summing to 1 (at most 16 components, each within 4 sites).
+ * d = `separationSites` × pixel pitch, 0 < separationSites ≤ 4, default 1 (first MTF zero at the sensor's Nyquist
+ * frequency 1/(2·pitch)).
+ */
+export type SimulateCaptureSensorAntiAliasing = {
+    kind: "four-spot";
+    separationSites?: number;
+} | {
+    kind: "two-spot";
+    axis: "horizontal" | "vertical";
+    separationSites?: number;
+} | {
+    kind: "point-splitting";
+    components: readonly AntiAliasingPointSplitComponent[];
+};
 export interface SimulateCaptureMotion {
     /** Constant camera angular velocity, rad/s, in the engine's pitch/yaw/roll convention. Missing axes are 0. */
     angularVelocityRadPerSec?: {
@@ -93,6 +125,13 @@ export interface SimulateCaptureOptions {
         psf?: Extract<CalculateEnvironmentSensorPhotoSignalInput["psf"], {
             kind: "sampled-local";
         }>;
+        /**
+         * Opt-in (2.1) diffraction blur of an ideal, aberration-free, in-focus lens with a circular pupil at the
+         * capture's resolved f-number: the engine builds the Airy kernels (`createDiffractionLimitedPsfProfile`)
+         * on the site pitch. `kernelRadiusSamples` (0–32) sets the kernel window; default: the third dark ring at
+         * the longest spectral node. Not combinable with `psf` or `pupilSampling`. Default off.
+         */
+        diffraction?: SimulateCaptureLensDiffraction;
     };
     exposure?: {
         /** Default "manual". */
@@ -145,6 +184,13 @@ export interface SimulateCaptureOptions {
         dng?: {
             capturedAtUtc?: string;
         };
+        /**
+         * Opt-in large images: the most native sensor sites (the output plus the demosaic margin on each side) the
+         * capture may allocate, an integer up to `NATIVE_RAW_LIMITS.ceilingPixels` (2^27). With it, `width` and
+         * `height` may each reach 16 384 sites including the margin; without it they stay at most 4094. Time and
+         * memory grow with the pixel count (see "Large images" in the quick start); browsers may fail at large sizes.
+         */
+        maximumPixels?: number;
     };
     /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
     motion?: SimulateCaptureMotion;
@@ -157,12 +203,23 @@ export interface SimulateCaptureOptions {
         temporalSampleCount?: number;
         /** Noise seed (uint32). Default 1. */
         noiseSeed?: number;
+        /**
+         * Opt-in (2.1) optical anti-aliasing filter (birefringent point splitting, `SimulateCaptureSensorAntiAliasing`).
+         * Multiplies the scene queries by the number of split points. Default off (the tiers declare no filter).
+         */
+        antiAliasing?: SimulateCaptureSensorAntiAliasing;
     };
     /** 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. */
     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", "sensor.antiAliasing", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror", "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"];
+export type SimulateCaptureCostOption = typeof SIMULATE_CAPTURE_COST_OPTIONS[number];
 export interface SimulateCaptureProgress {
     stage: "raw" | "white-balance" | "development" | "jpeg";
     completedTileCount: number;
@@ -204,6 +261,19 @@ export interface SimulateCaptureResult {
         siteInput(nativeIndex: number): SimulateEnvironmentSensorRawFrameInput["sites"][number];
         development: Omit<NativeRawDevelopmentInput, "raw">;
         whiteBalanceState: ResolvedWhiteBalanceState | null;
+        /**
+         * Present with lens.diffraction (2.1): the engine-built Airy profile, the equivalent environment sampled PSF
+         * selection, and how it was applied. With `object-space-convolution` the site inputs declare no PSF and the
+         * provider answers with the PSF-convolved radiance; putting `psf` into each site input and using the plain
+         * scene provider gives the same expected signal (to float rounding) through the per-tap environment quadrature.
+         */
+        diffraction?: {
+            profile: DiffractionLimitedPsfProfile;
+            psf: Extract<CalculateEnvironmentSensorPhotoSignalInput["psf"], {
+                kind: "sampled-local";
+            }>;
+            execution: "object-space-convolution" | "environment-psf-quadrature";
+        };
     };
     exposure: {
         mode: SimulateCaptureExposureMode;
@@ -250,13 +320,29 @@ export interface SimulateCaptureResult {
             adjustedPixelCount: number;
             lightnessClippedPixelCount: number;
         };
+        /**
+         * Wall-clock milliseconds per stage. `raw`, `whiteBalance` (the second RAW pass of auto white balance), `development`
+         * (includes DNG writing), `jpeg` and `total` are whole milliseconds (`Date.now()`). Since 2.1, where a stage ran:
+         * `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.
+         */
         timingsMs: {
             raw: number;
             whiteBalance: number;
             development: number;
             jpeg: number;
             total: number;
+            diffraction?: 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
+         * the user's device.
+         */
+        options: readonly SimulateCaptureCostOption[];
     };
     provenance: {
         scientificStatus: "approximation";