@photivra/engine 1.5.0 → 2.1.0

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

@@ -0,0 +1,363 @@
+import type { EvidenceProvenance } from "../core/evidence-provenance.js";
+import { type GenericEquipmentTier, type GenericEquipmentTierPreset } from "../equipment/generic-tier-assets.js";
+import { type ResolvedWhiteBalanceState } from "../color/white-balance.js";
+import { type NativeRawOutput, type NativeRawPlan } from "../capture/native-raw.js";
+import { type NativeEnvironmentRawInput } from "../capture/native-environment-raw.js";
+import { type NativeRawDevelopmentInput, type RawHighlightDiagnostics } from "../capture/native-raw-development.js";
+import { type SdrToneCurve, type SdrToneCurveParameters, type SdrRenderingResult } from "../output/sdr-rendering.js";
+import type { RawHighlightMode } from "../color/sensor-color-development.js";
+import type { SimulateEnvironmentSensorRawFrameInput } from "../capture/environment-raw-producer.js";
+import { type LensProjectionModel } from "../camera/lens-projection.js";
+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. */
+export declare const SIMULATE_CAPTURE_FACADE_VERSION: "1.0.0";
+export type SimulateCaptureExposureMode = "manual" | "aperture-priority" | "shutter-priority" | "program";
+export type SimulateCaptureOutputFormat = "srgb-8" | "srgb-16" | "jpeg" | "png" | "dng";
+export type SimulateCaptureWhiteBalance = "scene-illuminant" | "auto" | "none" | {
+    kelvin: number;
+    tint?: number;
+} | {
+    channelGains: {
+        red: number;
+        green: number;
+        blue: number;
+    };
+};
+/**
+ * PNG colour encoding. `srgb` is the developed sRGB output. The others take the developed linear
+ * colour (camera → XYZ → linear sRGB/D65, unclipped) and convert it through CIE XYZ into the target
+ * primaries:
+ * - `display-p3`: Display P3 primaries (W3C CSS Color 4 `display-p3`; also SMPTE EG 432-1) with the
+ *   sRGB transfer function;
+ * - `rec2020`: ITU-R BT.2020 primaries and OETF.
+ * PQ and HLG (BT.2100) are not part of 2.0; see THIRD_PARTY.md.
+ */
+export type SimulateCaptureColorEncoding = "srgb" | "display-p3" | "rec2020";
+/**
+ * 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
+ * checked to keep the CFA (colour filter array) pattern consistent.
+ */
+export type SimulateCaptureBorderHandling = "margin" | "mirror";
+export type SimulateCaptureLensDistortion = {
+    kind: "radial";
+    profile: RadialDistortionProfile;
+} | {
+    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?: {
+        pitch?: number;
+        yaw?: number;
+        roll?: number;
+    };
+    /** Default "global". `rolling` derives the exposure schedule from the body's rolling readout declaration. */
+    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;
+}
+export interface SimulateCaptureOptions {
+    /** Generic tier preset id or a full preset record (for example a modified copy of a catalog entry). Default "professional". */
+    camera?: GenericEquipmentTier | GenericEquipmentTierPreset;
+    lens?: {
+        /** Must lie in the lens capability (the generic primes are 50 mm). Default: the lens's shortest focal length. */
+        focalLengthMm?: number;
+        /** Aperture for manual and aperture-priority modes. Default 8. */
+        fNumber?: number;
+        /** Focus distance in metres. Default: the subject distance. */
+        focusDistanceM?: number;
+        /** Opt-in ideal circular-pupil ray sampling (defocus/depth of field). Default off (central ray only). */
+        pupilSampling?: {
+            radialSamples: number;
+            angularSamples: number;
+        };
+        /** Ideal lens projection (`LENS_PROJECTION_MODELS`). Default "rectilinear". Not combinable with pupilSampling. */
+        projection?: LensProjectionModel;
+        /** Caller-declared radial or Brown–Conrady distortion profile. Default none. Not combinable with pupilSampling. */
+        distortion?: SimulateCaptureLensDistortion;
+        /** Caller-declared radial relative-illumination (vignetting) profile, applied as environment field throughput. */
+        vignetting?: IlluminationVignettingProfile;
+        /**
+         * Caller sampled lens PSF, passed unchanged to the environment contract. Its focal length, f-number and
+         * focus must equal the resolved capture settings exactly. Not combinable with pupilSampling.
+         */
+        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". */
+        mode?: SimulateCaptureExposureMode;
+        /** Default 100. */
+        iso?: number;
+        /** 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;
+    /** Distance from the camera to the scene plane in metres. Default 5. */
+    subjectDistanceM?: number;
+    /** Default: Planckian 6500 K (a blackbody stand-in for daylight; CIE D65 is not bundled). */
+    illuminant?: CaptureIlluminant;
+    /** Illuminance on the scene plane, lux. Default about 21 481 lux (see `SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX` and the assumptions). */
+    illuminanceLux?: number;
+    output?: {
+        /** Output pixels; the native sensor raster adds a one-site demosaic border on each side. Defaults 64 × 64. */
+        width?: number;
+        height?: number;
+        /** Default "srgb-8". */
+        format?: SimulateCaptureOutputFormat;
+        /** Default "identity". */
+        toneCurve?: SdrToneCurve;
+        /** Required by the luminance tone curves (see `SdrToneCurveParameters`). The facade does not make one up. */
+        toneCurveParameters?: SdrToneCurveParameters;
+        /** Default "clip". */
+        highlightMode?: RawHighlightMode;
+        /** Default "scene-illuminant". */
+        whiteBalance?: SimulateCaptureWhiteBalance;
+        /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 2. */
+        jpegQuantizationStep?: number;
+        /** PNG only. Default "srgb". */
+        colorEncoding?: SimulateCaptureColorEncoding;
+        /** PNG only: 8 or 16 bits per sample. Default 8. */
+        bitDepth?: 8 | 16;
+        /**
+         * PNG SDR encodings only. Default "clip" (per-component clip to the target gamut). "perceptual" maps
+         * 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 "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;
+        };
+    };
+    /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
+    motion?: SimulateCaptureMotion;
+    sensor?: {
+        /** Pixel pitch in micrometres. Default 6. */
+        pixelPitchMicrometers?: number;
+        /** Maximum spectral quadrature subinterval in nm. Default 20. */
+        spectralStepNanometers?: number;
+        /** Temporal midpoint samples across the exposure. Default 1. */
+        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;
+    totalTileCount: number;
+}
+/** One decision the facade made: a default, a derived value or a fixed modelling choice. */
+export interface SimulateCaptureAssumption {
+    /** Dotted option path or modelling topic, for example "exposure.shutterSeconds" or "model.lens-psf". */
+    id: string;
+    kind: "default" | "derived" | "model";
+    value: unknown;
+    explanation: string;
+}
+export interface SimulateCaptureResult {
+    facadeVersion: typeof SIMULATE_CAPTURE_FACADE_VERSION;
+    engineApiVersion: string;
+    image: {
+        width: number;
+        height: number;
+        format: SimulateCaptureOutputFormat;
+        /** Interleaved RGB, row by row from the top-left. sRGB-encoded (W3C CSS Color 4 sRGB; also IEC 61966-2-1) unless `colorEncoding` says otherwise. */
+        samples: Uint8Array | Uint16Array;
+        /** Baseline JPEG bytes when format is "jpeg". */
+        jpeg?: Uint8Array;
+        /** PNG file bytes when format is "png". */
+        png?: Uint8Array;
+        /** Encoding of `samples` and `png` when format is "png". */
+        colorEncoding?: SimulateCaptureColorEncoding;
+        /** Lossless uncompressed CFA DNG of the packed RAW when format is "dng" (`serializeNativeRawDng`); `samples` are then sRGB 8-bit. */
+        dng?: Uint8Array;
+    };
+    /** Packed native RAW (codes, black levels, saturation flags) as produced by the native environment RAW task. */
+    raw: NativeRawOutput;
+    plan: NativeRawPlan;
+    /** The complete underlying request. */
+    request: {
+        environmentRaw: NativeEnvironmentRawInput;
+        /** Rebuilds the exact physical site input the provider supplied for a native row-major index. */
+        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;
+        settings: {
+            fNumber: number;
+            shutterSeconds: number;
+            iso: number;
+        };
+        /** Exposure value at ISO 100 of the settings, log2(N²/t). */
+        ev100: number;
+        meteredSceneLuminanceCdPerSquareMeter: number;
+        /** Full output of the existing exposure-mode resolver. */
+        resolution: unknown;
+    };
+    scene: {
+        sceneId: string;
+        preset: string;
+        parameters: Readonly<Record<string, unknown>>;
+        illuminant: {
+            id: string;
+            description: string;
+            illuminanceLux: number;
+        };
+        distanceM: number;
+        /** Physical size of the framed scene plane, metres. */
+        framedWidthM: number;
+        framedHeightM: number;
+        /**
+         * SHA-256 of the canonical scene description, recorded as the capture source digest. Caller spectra (a
+         * `spectrum` or `daylight` illuminant, chart reflectance spectra) are part of the description: tabulated
+         * data exactly, function spectra sampled at 1 nm over 380-780 nm, plus the daylight basis datasetId.
+         * The body of a caller scene's evaluate function is not hashed.
+         */
+        sourceSha256: string;
+    };
+    diagnostics: {
+        providerEvaluationCount: number;
+        highlight: RawHighlightDiagnostics;
+        rendering: SdrRenderingResult["diagnostics"];
+        /** Present with output.gamutMapping "perceptual": pixels whose chroma or lightness the mapping changed. */
+        gamutMapping?: {
+            method: "cielab-hue-preserving-chroma-compression";
+            kneeFraction: number;
+            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";
+        cameraPresetId: string;
+        cameraPresetVersion: string;
+        evidence: readonly EvidenceProvenance[];
+        /** Existing engine contracts the facade composed, in execution order. */
+        composedContracts: readonly string[];
+        limitations: readonly string[];
+    };
+    assumptions: readonly SimulateCaptureAssumption[];
+}
+/**
+ * Default illuminance, lux: an 18 % Lambertian grey card (L = 0.18·E/π) then gets exactly the CIPA DC-004 standard
+ * output sensitivity reference exposure H = 10/S at f/8, 1/125 s, ISO 100:
+ * E = π·10·N²/(0.65·t·S·0.18) = π·80 000/11.7 ≈ 21 480.98 lux.
+ */
+export declare const SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX: number;
+/**
+ * Simulates one still capture of a planar scene and returns the developed image, the packed RAW, the full
+ * underlying request/plan, provenance and every assumption made. See docs/QUICK_START.md.
+ */
+export declare function simulateCapture(options: SimulateCaptureOptions): Promise<SimulateCaptureResult>;
+/** Chart preset ids accepted by `simulateCapture({ scene: { preset } })`. */
+export declare const SIMULATE_CAPTURE_CHART_PRESETS: readonly ("uniform" | "patches" | "slanted-edge" | "siemens-star" | "step-wedge" | "grey-ramp" | "checkerboard" | "point-grid")[];