@photivra/engine 2.15.0 → 2.17.0

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

@@ -4,6 +4,7 @@ import { type AutoIsoLimits, type ExposureResolutionConstraint } from "../exposu
 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 NativeEnvironmentRawInput } from "../capture/native-environment-raw.js";
 import { type NativeRawDevelopmentInput, type RawHighlightDiagnostics } from "../capture/native-raw-development.js";
@@ -19,7 +20,8 @@ import type { IlluminationVignettingProfile } from "../optics/illumination-vigne
 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 ResolvedDefocusDisc } from "../optics/defocus-disc-kernel.js";
+import { type DefocusDiscSiteKernel, type ResolvedDefocusDisc } from "../optics/defocus-disc-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 ChartScene, type ResolvedChartScene } from "./chart-scenes.js";
@@ -219,6 +221,58 @@ export type SimulateCapturePixelAperture = "point" | "box" | {
 };
 /** Default midpoint samples per axis of `sensor.pixelAperture: "box"`. */
 export declare const SIMULATE_CAPTURE_BOX_APERTURE_DEFAULT_SAMPLES = 4;
+/**
+ * `output.sharpening` (#552): unsharp mask y = x + amount·(x − G_σ∗x) where |x − G_σ∗x| ≥ threshold (GIMP and ImageMagick
+ * unsharp mask), per channel on sRGB-encoded values in [0, 1], then clipped to [0, 1]. Every field is optional.
+ */
+export interface SimulateCaptureSharpening {
+    /** Gaussian standard deviation σ in output pixels, (0, 8]; the kernel reaches ⌈3σ⌉. Default 1. */
+    radiusPixels?: number;
+    /** Gain on the detail signal, (0, 5]. Default 0.5. */
+    amount?: number;
+    /** Detail smaller than this (encoded units, [0, 1]) is left unchanged. Default 0 (every difference is sharpened). */
+    threshold?: number;
+}
+/**
+ * `output.diffractionCorrection` (#552): the Wiener–Tikhonov gain G(s) = min(maximumGain, H(s)(1 + α)/(H(s)² + α)) on the circular-pupil
+ * OTF H at s = f/f_c, f_c = 1/(λ·N_w), as a (2R + 1)² FIR per channel. Every field is optional.
+ */
+export interface SimulateCaptureDiffractionCorrection {
+    /** Design wavelength in nm, 380–780, used for all three channels. Default 550. */
+    wavelengthNm?: number;
+    /** α, an assumed noise-to-signal power ratio, 1e-4–1. Larger is safer and restores less. Default 0.01. */
+    regularization?: number;
+    /** Upper bound on the gain at any frequency, 1–10 (it bounds the noise amplification). Default 4. */
+    maximumGain?: number;
+    /** FIR radius R in pixels, 1–16. Default: the Airy pattern's third dark ring at the design wavelength, within 1–16. */
+    kernelRadiusPixels?: number;
+}
+/** `diagnostics.detail` (#552): what the development detail stages did. Present only when one ran. */
+export interface SimulateCaptureDetailDiagnostics {
+    diffractionCorrection?: {
+        /** Corrected linear samples below 0 (ringing below black; clipped later by gamut handling) and above the RAW white level 1. */
+        negativeSampleCount: number;
+        aboveWhiteSampleCount: number;
+        /** The diffraction cut-off p/(λ·N_w) in cycles per pixel (Nyquist is 0.5); nothing beyond it is recovered. */
+        cutoffCyclesPerPixel: number;
+        /** Measured largest |response| of the filter, and largest |response| beyond the cut-off (null when the Nyquist square is inside it). */
+        responsePeakGain: number;
+        responseMaximumBeyondCutoff: number | null;
+    };
+    sharpening?: {
+        /** Half-width ⌈3σ⌉ of the Gaussian in pixels. */
+        kernelRadiusPixels: number;
+        /** Samples changed by the mask, and samples left alone because their detail was under the threshold. */
+        sharpenedSampleCount: number;
+        thresholdHeldSampleCount: number;
+        /** Sharpened samples clipped at 0 or 1. */
+        clippedLowSampleCount: number;
+        clippedHighSampleCount: number;
+        /** Largest increase and decrease amount·detail before clipping, in encoded units: the halo strength. */
+        maximumIncrease: number;
+        maximumDecrease: number;
+    };
+}
 export interface SimulateCaptureMotion {
     /** Constant camera angular velocity, rad/s, in the engine's pitch/yaw/roll convention. Missing axes are 0. */
     angularVelocityRadPerSec?: {
@@ -245,6 +299,25 @@ export interface SimulateCaptureOptions {
          * focus distance below its minimum focus distance, is rejected. Not combinable with `focalLengthMm`.
          */
         prime?: number;
+        /**
+         * Opt-in (#549): a lens of the generic lens catalogue by id (`GENERIC_LENS_IDS`, for example "pv-50-1.2-pro" or "pv-50-1.8";
+         * docs/LENS_CATALOGUE.md). Like `prime`, its focal length is the full-frame equivalent ÷ the simulated frame's diagonal crop
+         * factor and it replaces the tier lens's focal length and f-number range (the transmission is kept). The capture renders the
+         * lens's character, all labelled approximations: its PSF (diffraction with the lens's Seidel aberrations, axial and lateral
+         * colour, at the resolved f-number and focus) through the environment PSF quadrature, its radial distortion, its vignetting
+         * and, for the fisheyes, the equisolid projection. Flare, focus breathing and bokeh shape are not rendered. Not combinable
+         * with `prime`, `focalLengthMm`, `projection`, `distortion`, `vignetting`, `psf`, `diffraction` or `pupilSampling` (the
+         * lens sets them); `defocus` convolves the disc into the lens's PSF. Not offered by the display view. Default off.
+         */
+        catalogue?: string;
+        /**
+         * Opt-in (#549), with `catalogue` only: a seeded autofocus error (`simulateGenericLensFocusError`). The focus distance becomes
+         * the sampled one for (seed, shotIndex), reported in the `lens.focusScatter` assumption; it is visible with `defocus`. Default off.
+         */
+        focusScatter?: {
+            seed: number;
+            shotIndex?: number;
+        };
         /** Aperture for manual and aperture-priority modes. Default 8. */
         fNumber?: number;
         /** Focus distance in metres. Default: the subject distance. */
@@ -283,10 +356,15 @@ export interface SimulateCaptureOptions {
          * 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.
+         *
+         * Bokeh character (#553), each part off by default (without them the disc is unchanged, byte for byte): `blades` (a
+         * polygonal or rounded-blade opening), `sphericalAberration` (primary W040: soft-edged blur on one side of the focus
+         * plane, bright-rimmed on the other) and `catsEye` (mechanical vignetting clipping the pupil by field position; the
+         * capture only, not with `diffraction`). See `calculateDefocusBokehKernel` and docs/QUICK_START.md, "Bokeh character".
          */
         defocus?: {
             model: "geometric-disc";
-        };
+        } & DefocusBokehOptions;
     };
     exposure?: {
         /** Default "manual". */
@@ -370,6 +448,16 @@ export interface SimulateCaptureOptions {
         toneCurveParameters?: SdrToneCurveParameters;
         /** Default "clip". */
         highlightMode?: RawHighlightMode;
+        /**
+         * 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,
+         * the highlight mode, colour, the tone curve and encoding, like a raw editor's exposure slider ("brighten in development").
+         * A site pushed to or past white clips there and counts as saturated (`highlightMode: "reconstruct"` rolls it off);
+         * raised shadows keep their real noise and ADC quantization. The RAW codes, `result.raw` and a DNG are not changed;
+         * the developed samples (`image.samples`, also with format "dng"), JPEG, PNG, the ideal reference and the display view
+         * honour it. Reported in the assumption `output.exposureCompensationStops`. 0 or omitted: byte-identical to before.
+         */
+        exposureCompensationStops?: number;
         /** Default "scene-illuminant". */
         whiteBalance?: SimulateCaptureWhiteBalance;
         /** JPEG constant quantization step 1-255 (not a manufacturer 'quality'). Default 2. */
@@ -420,6 +508,20 @@ export interface SimulateCaptureOptions {
             width: number;
             height: number;
         };
+        /**
+         * Opt-in (#552) diffraction correction: a bounded, regularized deconvolution of the developed linear colour with the
+         * diffraction OTF of the ideal circular pupil at the capture's working f-number (see {@link SimulateCaptureDiffractionCorrection}).
+         * It runs after demosaic, colour and white balance and before the tone curve. Frequencies beyond the diffraction cut-off
+         * 1/(λ·N_w) never reached the sensor and stay lost: the correction's design gain there is 0. Needs `lens.diffraction`.
+         * Not combinable with `region`. The DNG's RAW codes are not changed. Default off.
+         */
+        diffractionCorrection?: SimulateCaptureDiffractionCorrection;
+        /**
+         * Opt-in (#552) unsharp mask (see {@link SimulateCaptureSharpening}) on the sRGB-encoded values after the tone curve and gamut
+         * handling, before quantization. It raises edge contrast and creates halos; it adds no optical detail. sRGB output only
+         * (not the wide-gamut or perceptual PNG paths); not combinable with `region`. The DNG's RAW codes are not changed. Default off.
+         */
+        sharpening?: SimulateCaptureSharpening;
     };
     /** Camera motion and shutter type. Default: still camera, global electronic shutter. */
     motion?: SimulateCaptureMotion;
@@ -465,7 +567,7 @@ 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", "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"];
+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.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
@@ -558,7 +660,7 @@ export interface SimulateCaptureResult {
             psf: Extract<CalculateEnvironmentSensorPhotoSignalInput["psf"], {
                 kind: "sampled-local";
             }>;
-            execution: "object-space-convolution" | "environment-psf-quadrature";
+            execution: "object-space-convolution" | "environment-psf-quadrature" | "image-space-convolution";
         };
     };
     exposure: {
@@ -655,6 +757,8 @@ export interface SimulateCaptureResult {
             adjustedPixelCount: number;
             lightnessClippedPixelCount: number;
         };
+        /** #552: present with output.diffractionCorrection or output.sharpening. */
+        detail?: SimulateCaptureDetailDiagnostics;
         /**
          * 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:
@@ -915,6 +1019,8 @@ export interface DisplayViewResult {
         };
         /** #395: exact or fast, as requested and as run; 2.11 (#481): plus `execution`, where the render ran (see {@link DisplayViewFastReport}). */
         fast: DisplayViewFastReport;
+        /** #533: the saturated (clipped highlight) pixels of the real capture in the rendered region, as an expected value (see {@link DisplayViewHighlightDiagnostics}). */
+        highlight: DisplayViewHighlightDiagnostics;
     };
     provenance: {
         scientificStatus: "approximation";
@@ -927,6 +1033,33 @@ export interface DisplayViewResult {
     /** The capture request's assumptions, then `view.definition`, `view.estimation`, `view.noise`, `view.demosaic` and `view.source`. */
     assumptions: readonly SimulateCaptureAssumption[];
 }
+/**
+ * #533: the display view's highlight count. `simulateCapture` reports `diagnostics.highlight.saturatedPixelCount`, the
+ * output pixels with at least one clipped contributing RAW site (a site flagged saturated or at the white level) counted on its
+ * one noise sample (`sensor.noiseSeed`). The display view renders no RAW, so it reports that count's expected value over the
+ * noise: Σ_j w_j·P_j over the real output pixels j of the rendered region, w_j the part of pixel j inside the region (1 inside,
+ * a fraction at a region edge that cuts a real pixel) and P_j the probability, under the view's own site model (each site's
+ * normalized value normal with its exact expected electrons, shot, dark, read and ADC noise, as the expected value uses), that at
+ * least one site pixel j's demosaic reads is at or above the white level, the sites' noises independent. It is estimated as the
+ * view's expected value is (`view.estimation`: exact over every real pixel, or the stratified samples), so it is not an integer.
+ *
+ * - Where every contributing site is far from white (more than 8.5 noise standard deviations either side) P_j is exactly 0 or 1,
+ *   and the expected count equals the capture's count of the same pixels exactly (they then have no noise to differ by).
+ * - Regions are additive: the counts of regions that tile the view sum to the whole view's count (up to floating-point summation
+ *   order), each display pixel's share being the same in every region that renders it.
+ * - With the bilinear demosaic the sites are the capture's own contributing sites. With AHD the capture counts every site within
+ *   3 sites of the pixel (its interpolation reach, clipped to the raster); the view counts the 25–29 of those 49 that its AHD
+ *   candidates read, so its count can be lower where a clipped area ends in a corner or a speck 2–3 sites away diagonally
+ *   (an approximation; along a straight clipped edge the two agree).
+ * - It never changes a sample of the view. On the GPU (`prepareDisplayView` with `gpu`) it is the CPU reference's value: the
+ *   kernel decides P_j only where it is certainly 0 or 1 and the host computes every other pixel's share with the reference.
+ */
+export interface DisplayViewHighlightDiagnostics {
+    /** Expected number of saturated real output pixels in the rendered region (a non-negative real number; see above). */
+    saturatedPixelCount: number;
+    /** The statistic: always "expected-value" (the capture's own count is one noise sample of it). */
+    statistic: "expected-value";
+}
 /** Internal: the resolved request state that the display view's renderer (simulate-display-view.ts) reads. */
 export interface DisplayViewRunContext {
     ahd: boolean;
@@ -965,8 +1098,15 @@ export interface DisplayViewRunContext {
         defaulted: ("heightM" | "surroundReflectance")[];
     } | undefined;
     diffraction: DiffractionLimitedPsfProfile | undefined;
-    /** `lens.defocus` (#492): the resolved geometric disc out of focus; undefined in focus or without the option. */
-    defocus: ResolvedDefocusDisc | undefined;
+    /** `lens.defocus` (#492): the resolved geometric disc out of focus; undefined in focus or without the option. #553: with bokeh options, the shaped kernel. */
+    defocus: (ResolvedDefocusDisc & {
+        siteKernel?: DefocusDiscSiteKernel;
+    }) | undefined;
+    /**
+     * #563: with `lens.projection`, `lens.distortion`, `lens.vignetting` or camera rotation, the factory of the view's expected signal
+     * 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;
     diffractionPsf: {
         kind: "sampled-local";
         configuration: Pick<CalculateSensorPsfIrradianceQuadratureInput, "psf" | "psfWavelengthBasis" | "spatialModel">;
@@ -976,6 +1116,8 @@ export interface DisplayViewRunContext {
     focusDistanceM: number;
     height: number;
     highlightMode: RawHighlightMode;
+    /** #556: the development exposure gain 2^output.exposureCompensationStops (1 without a push). */
+    exposureGain: number;
     illuminanceLux: number;
     illuminant: ResolvedCaptureIlluminant;
     illuminantOption: CaptureIlluminant;