@photivra/engine 2.20.0 → 2.22.0

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

@@ -1,16 +1,18 @@
 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";
 import type { RawFrameReconstructionPhaseProfile } from "../capture/raw-frame-reconstruction.js";
-import { type SdrToneCurve, type SdrToneCurveParameters, type SdrRenderingResult } from "../output/sdr-rendering.js";
+import { type SdrRenderingProfile, 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 OutputTextMetadata } from "../output/text-metadata.js";
@@ -20,15 +22,16 @@ import type { BrownConradyDistortionProfile } from "../optics/brown-conrady-dist
 import type { IlluminationVignettingProfile } from "../optics/illumination-vignetting.js";
 import type { CalculateSensorPsfIrradianceQuadratureInput } from "../optics/sensor-psf-quadrature.js";
 import type { CalculateEnvironmentSensorPhotoSignalInput } from "../sensor/environment-photo-signal.js";
-import { type DiffractionLimitedPsfProfile } from "../optics/diffraction-psf-profile.js";
+import type { DiffractionLimitedPsfProfile } from "../optics/diffraction-psf-profile.js";
 import { type DefocusDiscSiteKernel, type ResolvedDefocusDisc } from "../optics/defocus-disc-kernel.js";
-import { type DefocusBokehOptions } from "../optics/defocus-bokeh-kernel.js";
+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;
@@ -495,8 +511,12 @@ export interface SimulateCaptureOptions {
         toneCurve?: SdrToneCurve;
         /** Required by the luminance tone curves (see `SdrToneCurveParameters`). The facade does not make one up. */
         toneCurveParameters?: SdrToneCurveParameters;
-        /** Default "clip". */
-        highlightMode?: RawHighlightMode;
+        /**
+         * Default "clip". 2.22.0 (#602, opt-in): "reconstruct-neighbors" rebuilds clipped channels from color ratios of the unclipped
+         * pixels around each clipped region (an estimate; `src/color/neighbor-highlight-reconstruction.ts`): the ring's mean ratios
+         * (fast) or their harmonic interpolation inward (full). Whole-image, so not with `output.region`.
+         */
+        highlightMode?: SimulateCaptureHighlightMode;
         /**
          * Opt-in (#556) development exposure push in stops, −2 to +5 (`NATIVE_RAW_DEVELOPMENT_EXPOSURE_RANGE_STOPS`); default 0.
          * A linear gain 2^stops on the RAW after black subtraction and white normalization, before demosaic, white balance,
@@ -507,6 +527,14 @@ export interface SimulateCaptureOptions {
          * honour it. Reported in the assumption `output.exposureCompensationStops`. 0 or omitted: byte-identical to before.
          */
         exposureCompensationStops?: number;
+        /**
+         * #601 (2.22.0, opt-in): the sRGB rendering's gamut handling after the tone curve. "clip-components" (the default) clips
+         * each component to [0, 1]; "desaturate-to-luminance" moves a pixel whose largest component exceeds 1 toward the gray of its
+         * own luminance until that component is 1, keeping its luminance and hue (`desaturateToLuminance`, src/output/sdr-rendering.ts),
+         * instead of shifting bright saturated colors toward the secondaries. sRGB output only (not with a wide-gamut `colorEncoding`
+         * or `gamutMapping`). Reported in the assumption `output.gamutHandling`. Omitted: byte-identical to before.
+         */
+        gamutHandling?: SdrRenderingProfile["gamutHandling"] & ("clip-components" | "desaturate-to-luminance");
         /** Default "scene-illuminant". */
         whiteBalance?: SimulateCaptureWhiteBalance;
         /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 1 (2.20.0; 2 before), the full-quality export. */
@@ -592,6 +620,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 +672,16 @@ 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", "sensor.spectralStepNanometers", "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];
+/** `output.highlightMode`: the RAW development's modes plus (#602) the whole-image neighbor reconstruction. */
+export type SimulateCaptureHighlightMode = RawHighlightMode | "reconstruct-neighbors";
 /**
  * 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", "sensor.spectralStepNanometers"];
 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 {
@@ -1092,8 +1129,7 @@ export interface DisplayViewResult {
     sensor: SimulateCaptureSensorReport;
     /**
      * Work done: real pixels sampled, real-site expectations evaluated, scene queries, display pixels sampled in full (detail) or with
-     * a quarter of the samples per axis (uniform), display pixels whose value includes the AHD low-signal correction, and wall-clock
-     * milliseconds (diagnostic only; never affects the samples).
+     * a quarter of the samples per axis (uniform), and wall-clock milliseconds (diagnostic only; never affects the samples).
      */
     diagnostics: {
         sampleCount: number;
@@ -1101,6 +1137,10 @@ export interface DisplayViewResult {
         sceneLookups: number;
         detailPixelCount: number;
         uniformPixelCount: number;
+        /**
+         * Display pixels whose value included the AHD low-signal correction (2.10–2.21).
+         * @deprecated Since 2.22.0 the view has no such correction, and this is always 0. Removed in 3.0.0.
+         */
         ahdCorrectedPixelCount: number;
         timingsMs: {
             view: number;
@@ -1163,7 +1203,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 +1236,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: {
@@ -1206,7 +1248,7 @@ export interface DisplayViewRunContext {
     focalLengthMm: number;
     focusDistanceM: number;
     height: number;
-    highlightMode: RawHighlightMode;
+    highlightMode: SimulateCaptureHighlightMode;
     /** #556: the development exposure gain 2^output.exposureCompensationStops (1 without a push). */
     exposureGain: number;
     illuminanceLux: number;
@@ -1229,11 +1271,13 @@ export interface DisplayViewRunContext {
         regimeId: string;
     }>;
     sensor: SimulateCaptureSensorReport;
-    /** 2.20.0: the view's own fast methods, resolved: the AHD low-signal correction's draws and threshold (`output.demosaic.ahd`) and the quarter sampling of uniform pixels (top-level `fast`). */
+    /** 2.20.0: the view's own fast methods, resolved: the quarter sampling of uniform pixels (top-level `fast`); 2.22.0: the coupled rendering steps' rules (#593, #601). */
     viewFast: {
-        ahd: boolean;
         uniformSampling: boolean;
+        rendering: boolean;
     };
+    /** #601: the sRGB rendering's gamut handling. */
+    gamutHandling: "clip-components" | "desaturate-to-luminance";
     resolvedIso: number;
     /** #516: how the ISO was chosen, reported in the view's `exposure`. */
     isoReport: {
@@ -1249,7 +1293,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 +1310,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 +1336,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 {};