@photivra/engine 2.0.0 → 2.2.0

package/docs/api/facade-chart-radiance-batch.md

@@ -24,10 +24,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## CHART_RADIANCE_BATCH_LIMITS
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+`maximumQueries` is the default batch limit; a request may raise it with its own `maximumQueries`, up to `ceilingQueries`.
 
 ```ts
-CHART_RADIANCE_BATCH_LIMITS = Object.freeze({ maximumQueries: 24_000_000, maximumWavelengths: 256, maximumChannels: 4 })
+CHART_RADIANCE_BATCH_LIMITS = Object.freeze({ maximumQueries: 24_000_000, ceilingQueries: FULL_RESOLUTION_CEILING_PIXELS, maximumWavelengths: 256,
+  maximumChannels: 4 })
 ```
 
 ## CHART_RADIANCE_BATCH_SCHEMA_VERSION
@@ -59,6 +60,11 @@ export interface ChartRadianceBatchInput {
   wavelengthIndices?: Uint8Array | Uint16Array;
   /** Spectral integration: per channel (1–4), one finite weight per wavelength. */
   channelWeights?: readonly (readonly number[])[];
+  /**
+   * Optional opt-in batch limit: an integer from 1 to `CHART_RADIANCE_BATCH_LIMITS.ceilingQueries`. Default
+   * `CHART_RADIANCE_BATCH_LIMITS.maximumQueries` (24 000 000). It does not change the values.
+   */
+  maximumQueries?: number;
 }
 ```
 

package/docs/api/facade-simulate-capture.md

@@ -2,6 +2,18 @@
 
 The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
+## SIMULATE_CAPTURE_COST_OPTIONS
+
+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.
+
+```ts
+SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["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"] as const)
+```
+
 ## SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX
 
 Default illuminance, lux: an 18 % Lambertian grey card (L = 0.18·E/π) then gets exactly the CIPA DC-004 standard
@@ -70,12 +82,22 @@ PQ and HLG (BT.2100) are not part of 2.0; see THIRD_PARTY.md.
 export type SimulateCaptureColorEncoding = "srgb" | "display-p3" | "rec2020";
 ```
 
+## SimulateCaptureCostOption
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SimulateCaptureCostOption = typeof SIMULATE_CAPTURE_COST_OPTIONS[number];
+```
+
 ## SimulateCaptureDemosaic
 
-Built-in Bayer demosaic kernels (`createBuiltInBayerDemosaicProfiles`).
+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.
 
 ```ts
-export type SimulateCaptureDemosaic = "bilinear";
+export type SimulateCaptureDemosaic = "bilinear" | "ahd";
 ```
 
 ## SimulateCaptureExposureMode
@@ -139,6 +161,13 @@ export interface SimulateCaptureOptions {
      * 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". */
@@ -189,6 +218,13 @@ export interface SimulateCaptureOptions {
     borderHandling?: SimulateCaptureBorderHandling;
     /** DNG only: optional capture-event time (YYYY-MM-DDTHH:mm:ss.sssZ); without it no date tags are written. */
     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;
@@ -201,6 +237,11 @@ 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;
@@ -262,6 +303,14 @@ 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;
@@ -295,7 +344,20 @@ export interface SimulateCaptureResult {
     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 };
-    timingsMs: { raw: number; whiteBalance: number; development: number; jpeg: number; total: 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";
@@ -310,6 +372,24 @@ export interface SimulateCaptureResult {
 }
 ```
 
+## SimulateCaptureSensorAntiAliasing
+
+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)).
+
+```ts
+export type SimulateCaptureSensorAntiAliasing =
+  | { kind: "four-spot"; separationSites?: number }
+  | { kind: "two-spot"; axis: "horizontal" | "vertical"; separationSites?: number }
+  | { kind: "point-splitting"; components: readonly AntiAliasingPointSplitComponent[] };
+```
+
 ## SimulateCaptureWhiteBalance
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.

package/docs/api/motion-temporal-exposure-sum.md

@@ -24,11 +24,12 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## TEMPORAL_EXPOSURE_SUM_LIMITS
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+`maximumPixels` is the default grid limit; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`.
 
 ```ts
 TEMPORAL_EXPOSURE_SUM_LIMITS = Object.freeze({
   maximumPixels: 24_000_000,
+  ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,
   maximumDimension: 16_384,
   maximumTemporalSamples: 256,
   maximumDisplacementSites: 4_096,
@@ -63,6 +64,11 @@ export interface TemporalExposureSumInput {
   /** Quadrature weights `[k][row]` (nodes × height), finite and non-negative, for example seconds of each row's window near t_k. */
   rowWeights: Float32Array | Float64Array;
   boundary: "zero-outside-grid";
+  /**
+   * Optional opt-in grid limit for large images: an integer from 1 to `TEMPORAL_EXPOSURE_SUM_LIMITS.ceilingPixels`.
+   * Default `TEMPORAL_EXPOSURE_SUM_LIMITS.maximumPixels` (24 000 000). It does not change the result.
+   */
+  maximumPixels?: number;
 }
 ```
 

package/docs/api/optics-diffraction-psf-profile.md

@@ -0,0 +1,96 @@
+# optics/diffraction-psf-profile.ts public contracts
+
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## createDiffractionLimitedPsfProfile
+
+Creates a sampled lens PSF profile for an ideal diffraction-limited lens with a circular pupil: one
+unit-sum Airy kernel per wavelength on one shared (2R+1)² grid, with the truncated energy reported per
+wavelength. The profile declares the given focal length, f-number and focus exactly, and the field axes
+±`fieldHalfExtentMm` with the same kernel at every field node.
+
+```ts
+export function createDiffractionLimitedPsfProfile(input: CreateDiffractionLimitedPsfProfileInput): CalculationResult<DiffractionLimitedPsfProfile>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateDiffractionLimitedPsfProfileInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateDiffractionLimitedPsfProfileInput {
+  /** Only `circular` in 2.1.0 (polygon pupils: `calculateIdealPolygonDiffractionPsf` gives point densities). */
+  aperture: "circular";
+  focalLengthMm: number;
+  apertureFNumber: number;
+  focus: FocusPlane;
+  /** Strictly increasing wavelengths, nm, in the medium of propagation (no air/vacuum conversion is applied). 1–64. */
+  wavelengthsNm: readonly number[];
+  /** Square sample pitch of every kernel, µm. */
+  samplePitchMicrometers: number;
+  /** Kernel half-width in samples; each kernel is (2R + 1)². 0–32. */
+  kernelRadiusSamples: number;
+  /** Half-extent of the image field over which the on-axis PSF is declared (profile field axes ±x, ±y), mm. */
+  fieldHalfExtentMm: { x: number; y: number };
+  profileId: string;
+}
+```
+
+## DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS
+
+Input limits: at most 64 wavelengths, kernel radius 0–32 samples (the irradiance-convolution limit).
+
+```ts
+DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS = Object.freeze({ maximumWavelengths: 64, maximumKernelRadiusSamples: 32 })
+```
+
+## DIFFRACTION_LIMITED_PSF_PROFILE_MODEL
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+DIFFRACTION_LIMITED_PSF_PROFILE_MODEL = Object.freeze({
+  modelId: "photivra-diffraction-limited-circular-pupil-psf" as const, modelVersion: "1.0.0" as const })
+```
+
+## DiffractionLimitedPsfProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DiffractionLimitedPsfProfile {
+  profile: LensSampledPsfProfile;
+  model: typeof DIFFRACTION_LIMITED_PSF_PROFILE_MODEL;
+  pupilDiameterMm: number;
+  pupilToImageDistanceMm: number;
+  workingFNumber: number;
+  kernelRadiusSamples: number;
+  samplePitchMicrometers: number;
+  wavelengths: readonly DiffractionLimitedPsfWavelength[];
+  /** Largest truncated energy over the wavelengths. */
+  maximumTruncatedEnergyFraction: number;
+  quadrature: { method: "polar-frequency-domain-trapezoid-gauss-legendre"; maximumRadialNodes: number; maximumAngularNodes: number };
+}
+```
+
+## DiffractionLimitedPsfWavelength
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DiffractionLimitedPsfWavelength {
+  wavelengthNm: number;
+  /** f_c = 1/(λ·N_w), cycles per µm. */
+  cutoffFrequencyCyclesPerMicrometer: number;
+  /** 1.21967·λ·N_w, µm. */
+  firstZeroRadiusMicrometers: number;
+  /** Σ of the cell energies inside the window before renormalization (of a total of 1). */
+  capturedEnergyFraction: number;
+  /** 1 − capturedEnergyFraction: the Airy tail energy outside the window, put back by renormalization. */
+  truncatedEnergyFraction: number;
+  /** Fraction of the renormalized kernel in the centre sample. */
+  centreSampleFraction: number;
+}
+```

package/docs/api/optics-irradiance-convolution.md

@@ -24,11 +24,12 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## IRRADIANCE_CONVOLUTION_LIMITS
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+`maximumPixels` is the default grid limit; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`.
 
 ```ts
 IRRADIANCE_CONVOLUTION_LIMITS = Object.freeze({
   maximumPixels: 24_000_000,
+  ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,
   maximumDimension: 16_384,
   maximumKernelRadius: 32,
   maximumPatchCount: 4_096,
@@ -70,6 +71,11 @@ export interface IrradianceConvolutionInput {
    */
   kernels: Float32Array | Float64Array;
   boundary: "zero-outside-grid";
+  /**
+   * Optional opt-in grid limit for large images: an integer from 1 to `IRRADIANCE_CONVOLUTION_LIMITS.ceilingPixels`.
+   * Default `IRRADIANCE_CONVOLUTION_LIMITS.maximumPixels` (24 000 000). It does not change the result.
+   */
+  maximumPixels?: number;
 }
 ```
 

package/docs/api/output-native-capture-sdr.md

@@ -24,10 +24,10 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## NATIVE_CAPTURE_SDR_LIMITS
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+`maximumPixels` is the default pixel limit; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`.
 
 ```ts
-NATIVE_CAPTURE_SDR_LIMITS = Object.freeze({ maximumPixels: 24_000_000,
+NATIVE_CAPTURE_SDR_LIMITS = Object.freeze({ maximumPixels: 24_000_000, ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,
   maximumDimension: 16_384, tileWidth: 256, tileHeight: 32, maximumTileStorageSamples: 32_768 })
 ```
 
@@ -51,6 +51,11 @@ export interface NativeCaptureSdrInput {
   profile: SdrRenderingProfile;
   /** Limit on the size of the integer output. Checked before anything is allocated or any tile is read. */
   maximumOutputBytes: number;
+  /**
+   * Optional opt-in pixel limit for large captures: an integer from 1 to `NATIVE_CAPTURE_SDR_LIMITS.ceilingPixels`.
+   * Default `NATIVE_CAPTURE_SDR_LIMITS.maximumPixels` (24 000 000). `maximumOutputBytes` still applies.
+   */
+  maximumPixels?: number;
 }
 ```
 

package/docs/api/output-png-encoder.md

@@ -13,9 +13,11 @@ PNG_ENCODER_ID = "photivra-png-rgb-v1" as const
 ## PNG_ENCODER_LIMITS
 
 Limits, checked before allocation. 100 MP (megapixels) of 16-bit RGB is about 600 MB of filtered scanlines.
+`maximumPixels` is the default; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`.
 
 ```ts
-PNG_ENCODER_LIMITS = Object.freeze({ maximumDimension: 65535, maximumPixels: 100_000_000, maximumIccProfileBytes: 4_000_000 })
+PNG_ENCODER_LIMITS = Object.freeze({ maximumDimension: 65535, maximumPixels: 100_000_000, ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,
+  maximumIccProfileBytes: 4_000_000 })
 ```
 
 ## PngCicpPrimaries
@@ -74,6 +76,11 @@ export interface PngEncodeInput {
   compression?: "stored" | "fixed-huffman";
   /** PNG filter type 0..4 for every row, or the specification's minimum-sum-of-absolute-differences heuristic. Default "adaptive". */
   filter?: "none" | "sub" | "up" | "average" | "paeth" | "adaptive";
+  /**
+   * Optional opt-in pixel limit: an integer from 1 to `PNG_ENCODER_LIMITS.ceilingPixels`. Default
+   * `PNG_ENCODER_LIMITS.maximumPixels` (100 000 000). It does not change the encoded bytes.
+   */
+  maximumPixels?: number;
 }
 ```
 

package/docs/api/output-print-jpeg.md

@@ -22,6 +22,17 @@ export function parsePrintJpegInput(input:PrintJpegInput):PrintJpegInput;
 
 This call is synchronous; any supplied provider must follow its explicit synchronous contract.
 
+## PRINT_JPEG_LIMITS
+
+Admission limits. `maximumPixels` is the default source limit; a request may raise it with its own
+`maximumPixels`, up to `ceilingPixels`. A raised limit raises the `maximumEncodedBytes` ceiling in proportion
+(256 000 000 bytes per 24 000 000 source pixels).
+
+```ts
+PRINT_JPEG_LIMITS=Object.freeze({maximumPixels:24_000_000,ceilingPixels:FULL_RESOLUTION_CEILING_PIXELS,maximumDimension:16_384,
+  maximumEncodedBytes:256_000_000,maximumProviderReads:1_000_000})
+```
+
 ## PRINT_JPEG_SCHEMA_VERSION
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -57,6 +68,12 @@ export interface PrintJpegInput {
    * carries 72/1 with ResolutionUnit = 2; that is the standard's unknown-resolution marker, not a print size.
    */
   pixelsPerInch?:number;
+  /**
+   * Optional opt-in source pixel limit for large images: an integer from 1 to `PRINT_JPEG_LIMITS.ceilingPixels`.
+   * Default `PRINT_JPEG_LIMITS.maximumPixels` (24 000 000). When given it is recorded in the XMP export plan, like the
+   * other admission budgets; the image data are unchanged.
+   */
+  maximumPixels?:number;
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",
@@ -35,7 +35,8 @@
     "dist/schema",
     "dist/sensor",
     "dist/simulation",
-    "dist/stabilization","dist/processing",
+    "dist/stabilization",
+    "dist/processing",
     "!dist/capture/browser-native-reference-*",
     "!dist/schema/camera.js",
     "!dist/schema/camera.js.map",