@photivra/engine 2.20.0 → 2.21.0

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

@@ -1,11 +1,13 @@
 import type { EvidenceProvenance } from "../core/evidence-provenance.js";
 import { type GenericEquipmentTier, type GenericEquipmentTierPreset } from "../equipment/generic-tier-assets.js";
+import type { SensorProfile } from "../equipment/sensor-profile-body.js";
 import { type AutoIsoLimits, type ExposureResolutionConstraint } from "../exposure/exposure-mode-resolver.js";
 import { resolveColorTemperatureWhiteBalance, type ResolvedWhiteBalanceState } from "../color/white-balance.js";
 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 { MixedIllumination, ResolvedMixedIllumination } from "./mixed-illumination.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";
@@ -25,10 +27,11 @@ import { type DefocusDiscSiteKernel, type ResolvedDefocusDisc } from "../optics/
 import { type DefocusBokehOptions } from "../optics/defocus-bokeh-kernel.js";
 import { type AntiAliasingPointSplitComponent } from "../sensor/optical-stack.js";
 import { type NativeRawDng } from "../capture/native-raw-dng.js";
+import { type SimulateCaptureSubjectMotion } from "../motion/subject-motion.js";
 import { type SimulateCaptureSensorCharacteristics, type SimulateCaptureSensorReport } from "../sensor/sensor-characteristics.js";
 import { type ChartScene, type ResolvedChartScene } from "./chart-scenes.js";
 import { type ChartMaterialLayerScene, type ResolvedChartMaterialLayers } from "./chart-material-layers.js";
-import { type ChartSizeOption, type CaptureIlluminant, type CallerMaterialScene, type CallerRadianceScene, type CallerReflectanceScene, type ResolvedCallerScene, type PlanarSceneRadianceProvider, type ResolvedCaptureIlluminant } from "./scene-radiance.js";
+import { type ChartSizeOption, type CaptureIlluminant, type CallerMaterialScene, type CallerRadianceScene, type CallerReflectanceScene, type ImagePlaneScene, type ResolvedCallerScene, type PlanarSceneRadianceProvider, type ResolvedCaptureIlluminant } 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";
@@ -161,8 +164,9 @@ export type SimulateCaptureDemosaic = "bilinear" | "ahd";
 /**
  * `lens.catalogue` as a record (#568): the lens id as `kind` and the `fast` override (see {@link SimulateCaptureOptions.fast}).
  * Fast: the tabulated fast method (#568), and with `lens.defocus` the lens's bokeh without its cat's eye (#567; fast wides and
- * normals only), whose field-varying PSF needs a finer fast grid (measured 2.2–3.4× slower). Exact: the per-site PSF with the
- * cat's eye. Blades and spherical aberration always apply (they cost nothing).
+ * normals only), whose field-varying PSF needs a finer fast grid (measured 2.2–3.4× slower); with camera rotation under
+ * `motion.shutter: "rolling"`, the per-tap PSF points instead of the lattice reading (#588). Exact: the per-site PSF with the
+ * cat's eye, read on the lattice. Blades and spherical aberration always apply (they cost nothing).
  */
 export interface SimulateCaptureLensCatalogueRecord {
     kind: string;
@@ -313,6 +317,11 @@ export interface SimulateCaptureMotion {
     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;
+    /**
+     * #551: a moving subject: the whole scene, or one rectangle of it over a still background, translating on the scene plane
+     * (and optionally rotating about the optical axis) during the exposure. Off by default (a still scene).
+     */
+    subject?: SimulateCaptureSubjectMotion;
 }
 export interface SimulateCaptureOptions {
     /** Generic tier preset id or a full preset record (for example a modified copy of a catalog entry). Default "professional". */
@@ -468,9 +477,10 @@ export interface SimulateCaptureOptions {
     /**
      * 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.
+     * byte, and the display view can render it on the GPU), a caller reflectance, radiance or material function, or (2.21, #581) an
+     * `image-plane` scene: a photo as a flat print (docs/IMAGE_PLANE.md).
      */
-    scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
+    scene: ChartScene | ChartMaterialLayerScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene | ImagePlaneScene;
     /** Distance from the camera to the scene plane in metres. Default 5. */
     subjectDistanceM?: number;
     /**
@@ -485,6 +495,12 @@ export interface SimulateCaptureOptions {
     illuminant?: CaptureIlluminant;
     /** Illuminance on the scene plane, lux. Default about 21 481 lux (see `SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX` and the assumptions). */
     illuminanceLux?: number;
+    /**
+     * 2.22 (#550), opt-in mixed lighting: two or more sources blended across the chart (docs/MIXED_ILLUMINATION.md), instead of
+     * `illuminant` and `illuminanceLux`. The frame center's light sets the grey-card meter and the standard-exposure figures, and
+     * its strongest source the "scene-illuminant" white balance; both are reported in `assumptions`.
+     */
+    illumination?: MixedIllumination;
     output?: {
         /** Output pixels; the native sensor raster adds a one-site demosaic border on each side. Defaults 64 × 64. */
         width?: number;
@@ -592,6 +608,13 @@ export interface SimulateCaptureOptions {
     motion?: SimulateCaptureMotion;
     /** #555: plus the sensor characteristics ({@link SimulateCaptureSensorCharacteristics}), each off by default. */
     sensor?: SimulateCaptureSensorCharacteristics & {
+        /**
+         * #554: a sensor profile record (`SENSOR_PROFILES`, or `resolveSensorProfile(id)`), checked strictly. It replaces the body's ISO range, readout regimes
+         * (full well, read noise of each conversion gain, the dual-gain switch, high-gain storage, ADC bit depth), readout time and
+         * fixed-pattern noise, and sets the default pixel pitch and peak QE; explicit fields here still override it one at a time.
+         * Default: none (the body's own sensor). See docs/SENSOR_PROFILES.md.
+         */
+        profile?: SensorProfile;
         /**
          * Pixel pitch in micrometres, 0.5–1000. Default 6. The simulated sensor is output width × pitch wide. 2.5: above 100 µm the
          * capture is a downsized view of a whole frame (for example 36 mm / 48 pixels = 750 µm), recorded in the assumption
@@ -637,14 +660,14 @@ export interface SimulateCaptureOptions {
  * 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.lensCorrections", "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.subject", "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", "lens.catalogue", "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", "motion.subject"];
 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 {
@@ -1163,7 +1186,7 @@ export interface DisplayViewRunContext {
         relativePerElectron: Record<Channel, number>;
     };
     boxSamples: number;
-    buildProvider: (sceneIlluminant: ResolvedCaptureIlluminant, scale: number) => PlanarSceneRadianceProvider;
+    buildProvider: (sceneIlluminant: ResolvedCaptureIlluminant, scale: number, light?: ResolvedMixedIllumination) => PlanarSceneRadianceProvider;
     callerScene: ResolvedCallerScene | undefined;
     chart: ResolvedChartScene | undefined;
     /** #491: the declared material-layers scene behind `callerScene`, when the request gave one. */
@@ -1196,6 +1219,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;
+    /** #551: with motion.subject, the moving scene of a provider (its irradiance scale and illuminant shape, or #550's mixed lighting, light the revealed background). */
+    movingScene?: ((base: PlanarSceneRadianceProvider, scale: number, shape: (nm: number) => number, light?: ResolvedMixedIllumination) => PlanarSceneRadianceProvider) | 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: {
@@ -1249,7 +1274,7 @@ export interface DisplayViewRunContext {
     /** 2.14: the capture's `exposure.metering`. */
     metering: SimulateCaptureMetering;
     sceneOption: unknown;
-    scenePreset: "composite" | "uniform" | "patches" | "slanted-edge" | "siemens-star" | "step-wedge" | "grey-ramp" | "checkerboard" | "point-grid" | "dead-leaves" | "bar-groups" | "hyperbolic-wedge" | "zone-plate" | "slanted-squares" | "line-grid" | "fiducial" | "color-patches" | "reflectance-function" | "radiance-function" | "material-function";
+    scenePreset: "composite" | "uniform" | "patches" | "slanted-edge" | "siemens-star" | "step-wedge" | "grey-ramp" | "checkerboard" | "point-grid" | "dead-leaves" | "bar-groups" | "hyperbolic-wedge" | "zone-plate" | "slanted-squares" | "line-grid" | "fiducial" | "color-patches" | "reflectance-function" | "radiance-function" | "material-function" | "image-plane";
     shutterSeconds: number;
     started: number;
     subjectDistanceM: number;
@@ -1266,6 +1291,8 @@ export interface DisplayViewRunContext {
     yieldControl: () => Promise<void>;
     /** The Kelvin white balance request, which the view resolves with the portable functions. */
     kelvinWhiteBalanceInput: Parameters<typeof resolveColorTemperatureWhiteBalance>[0] | undefined;
+    /** #550: with `illumination`, resolves it again with the given illuminant formulas (the view's portable ones). */
+    mixedIllumination?: ((resolve: (value: CaptureIlluminant) => ResolvedCaptureIlluminant) => ResolvedMixedIllumination) | undefined;
 }
 export interface ParsedDisplayView {
     width: number;
@@ -1290,7 +1317,9 @@ type CaptureRun = "capture" | "ideal-reference" | "display-view" | "dng-from-par
  * 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: CaptureRun, viewOption?: unknown, renderView?: (context: DisplayViewRunContext) => Promise<unknown>): Promise<unknown>;
+export declare function runCapture(options: SimulateCaptureOptions, run: CaptureRun, 
+/** The display view option, the parts, or (#534) for a capture an exposure build-up's callback, which sees each native RAW input. */
+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 {};