@photivra/engine 1.5.0 → 2.1.0

package/docs/api/processing-demosaic.md

@@ -0,0 +1,120 @@
+# processing/demosaic.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.
+
+## AhdDemosaicInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AhdDemosaicInput {
+  plane: CfaMosaicPlane;
+  /** CFA channel ids of the red, green and blue sites; output order is red, green, blue. */
+  channelRoles: { red: string; green: string; blue: string };
+  /**
+   * Camera-linear RGB → CIE XYZ, used only for the homogeneity metric (in CIELAB). Default: the
+   * sRGB/D65 matrix, so the plane is treated as linear sRGB for the metric. Output values are never
+   * transformed.
+   */
+  cameraToXyz?: ColorMatrix3x3;
+  maximumWorkingBytes?: number;
+}
+```
+
+## AhdDemosaicOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AhdDemosaicOutput extends ProcessingRgbImage {
+  /** Per pixel: 0 horizontal, 1 vertical, 2 equal homogeneity (average of both). */
+  direction: Uint8Array;
+  provenance: ProcessingProvenance;
+}
+```
+
+## CfaMosaicPlane
+
+A single-channel linear CFA mosaic in absolute native site coordinates (row-major, +Y down).
+
+```ts
+export interface CfaMosaicPlane {
+  width: number;
+  height: number;
+  captureModeId: string;
+  /** Periodic mosaic anchored at site (0, 0) of this plane. */
+  colorSamplingProfile: SensorColorSamplingProfile;
+  /** Linear values, e.g. black-subtracted normalized RAW or merged HDR radiance. */
+  samples: Float32Array;
+}
+```
+
+## CfaPlaneReconstructionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CfaPlaneReconstructionInput {
+  plane: CfaMosaicPlane;
+  phaseProfiles: readonly RawFrameReconstructionPhaseProfile[];
+  /** Default `reject`: every neighbourhood must lie inside the plane. */
+  borderHandling?: RawReconstructionBorderHandling;
+  /** Output region in plane coordinates; default the whole plane. */
+  region?: { x: number; y: number; width: number; height: number };
+  maximumWorkingBytes?: number;
+}
+```
+
+## CfaPlaneReconstructionOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CfaPlaneReconstructionOutput {
+  width: number;
+  height: number;
+  region: { x: number; y: number; width: number; height: number };
+  channelIds: readonly string[];
+  /** Interleaved `channelIds.length` channels, row-major over the region. */
+  data: Float32Array;
+  borderHandling: RawReconstructionBorderHandling;
+  provenance: ProcessingProvenance;
+}
+```
+
+## createAhdDemosaicTask
+
+Adaptive homogeneity-directed (AHD) demosaicing after Hirakawa & Parks, IEEE TIP 14(3), 2005:
+1. green is interpolated separately along rows and columns with the 5-tap directional filter
+   [−1/4, 1/2, 1/2, 1/2, −1/4] (bilinear green plus the own-channel second difference);
+2. red and blue are filled from bilinearly interpolated colour differences (R−G, B−G) against each
+   directional green, giving two full-colour candidates;
+3. both candidates are converted to CIELAB. At each pixel, the homogeneity is the number of
+   4-neighbours within adaptive luminance and chrominance tolerances ε_L, ε_C. Each tolerance is the
+   smaller of the two directions' largest differences along their own direction;
+4. homogeneity is summed over 3×3, and the more homogeneous candidate is chosen (a tie averages
+   both).
+The paper's optional iterative median step for reducing artifacts is not applied. Mirrored
+(reflect-101) borders keep each site's Bayer channel. The method is non-linear: the output is not a
+linear function of the mosaic.
+
+```ts
+export function createAhdDemosaicTask(input: AhdDemosaicInput, provider: ProcessingProvider): ProcessingTask<AhdDemosaicOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createCfaPlaneReconstructionTask
+
+Runs explicit linear reconstruction kernels, one per CFA phase, over a typed CFA plane.
+- With `mirror` borders, a site outside the plane is read from its mirrored (reflect-101) position.
+  This is accepted only if the mirrored site has the same CFA channel, which is always true for a
+  2×2 Bayer pattern.
+- With `reject`, out-of-plane reads throw (fail closed), like the reference resolver.
+Values are linear and signed. No clamping, white balance or colour transform is applied.
+
+```ts
+export function createCfaPlaneReconstructionTask(input: CfaPlaneReconstructionInput, provider: ProcessingProvider): ProcessingTask<CfaPlaneReconstructionOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/processing-denoise.md

@@ -0,0 +1,148 @@
+# processing/denoise.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.
+
+## BilateralFilterInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BilateralFilterInput {
+  image: ProcessingRgbImage;
+  spatialSigmaPixels: number;
+  /** Range σ in the units of the image values. */
+  rangeSigma: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## createBilateralFilterTask
+
+Brute-force bilateral filter (window radius ⌈3σ_s⌉, reflect-101 borders).
+
+```ts
+export function createBilateralFilterTask(input: BilateralFilterInput, provider: ProcessingProvider): ProcessingTask<ProcessedRgbImage>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createNonLocalMeansTask
+
+Non-local means (Buades, Coll & Morel 2005), offset-major with box-filtered patch distances.
+
+```ts
+export function createNonLocalMeansTask(input: NonLocalMeansInput, provider: ProcessingProvider): ProcessingTask<ProcessedRgbImage>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createSyntheticFilmGrainTask
+
+Adds deterministic synthetic grain:
+1. Unit-variance Gaussian white noise per pixel. It is seeded by the absolute pixel index, so tiling
+   never changes it.
+2. Optionally blurred by a Gaussian with σ = grain size, then renormalized to unit variance.
+3. Scaled by a(v) = intensity·2√(v(1 − v)): zero at black and white, `intensity` at mid-grey.
+4. Clipped to [0, 1].
+It is labelled synthetic and aesthetic. It is never a film model.
+
+```ts
+export function createSyntheticFilmGrainTask(input: SyntheticFilmGrainInput, provider: ProcessingProvider): ProcessingTask<SyntheticFilmGrainOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createUnsharpMaskTask
+
+Unsharp masking: in + amount·(in − G_σ ⊗ in) where the detail exceeds the threshold.
+
+```ts
+export function createUnsharpMaskTask(input: UnsharpMaskInput, provider: ProcessingProvider): ProcessingTask<ProcessedRgbImage>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## NonLocalMeansInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NonLocalMeansInput {
+  image: ProcessingRgbImage;
+  /** Filtering parameter h (image units). */
+  filteringParameter: number;
+  /** Known noise standard deviation σ (image units); default 0. */
+  noiseStandardDeviation?: number;
+  /** Patch radius f (patch (2f+1)²); default 1. */
+  patchRadius?: number;
+  /** Search-window radius r ((2r+1)² candidates); default 5. */
+  searchRadius?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## ProcessedRgbImage
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ProcessedRgbImage extends ProcessingRgbImage {
+  provenance: ProcessingProvenance;
+}
+```
+
+## SYNTHETIC_FILM_GRAIN_STREAM_ID
+
+Random-stream id for synthetic grain. Different from every RAW charge, read-noise and fixed-pattern stream.
+
+```ts
+SYNTHETIC_FILM_GRAIN_STREAM_ID = 64 as const
+```
+
+## SyntheticFilmGrainInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SyntheticFilmGrainInput {
+  /** Display-referred (encoded) RGB with values in [0, 1]. */
+  image: ProcessingRgbImage;
+  /** uint32 seed; equal seeds reproduce the grain exactly. */
+  seedUint32: number;
+  /** Grain standard deviation at mid-grey (value 0.5), in encoded units. */
+  intensity: number;
+  /** Spatial correlation σ of the grain in pixels; 0 = per-pixel white grain. Default 0.7. */
+  grainSizePixels?: number;
+  /** `monochrome` (default) adds one grain field to all channels; `per-channel` uses three. */
+  mode?: "monochrome" | "per-channel";
+  maximumWorkingBytes?: number;
+}
+```
+
+## SyntheticFilmGrainOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SyntheticFilmGrainOutput extends ProcessedRgbImage {
+  /** Always true: the grain is an aesthetic texture, not a physical film model. */
+  syntheticAesthetic: true;
+  physicalFilmModel: false;
+  clippedSampleCount: number;
+}
+```
+
+## UnsharpMaskInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface UnsharpMaskInput {
+  image: ProcessingRgbImage;
+  radiusSigmaPixels: number;
+  amount: number;
+  /** Detail magnitude below which a component is left unchanged; default 0. */
+  threshold?: number;
+  maximumWorkingBytes?: number;
+}
+```

package/docs/api/processing-focus-stacking.md

@@ -0,0 +1,41 @@
+# processing/focus-stacking.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.
+
+## createFocusStackTask
+
+Laplacian-energy focus stacking with Laplacian-pyramid blending.
+
+```ts
+export function createFocusStackTask(input: FocusStackInput, provider: ProcessingProvider): ProcessingTask<FocusStackOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## FocusStackInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FocusStackInput {
+  /** Registered frames of one scene, ordered by focus distance (any consistent order). */
+  frames: readonly ProcessingRgbImage[];
+  /** σ (pixels) of the Gaussian window averaging the squared Laplacian; default 2. */
+  sharpnessSigmaPixels?: number;
+  /** Pyramid levels for seam-free blending; default down to a 1-pixel side (at most 10). */
+  pyramidLevels?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## FocusStackOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FocusStackOutput extends ProcessingRgbImage {
+  /** Index of the sharpest frame per pixel (the blending selection). */
+  selectedFrameIndex: Uint8Array;
+  provenance: ProcessingProvenance;
+}
+```

package/docs/api/processing-hdr.md

@@ -0,0 +1,113 @@
+# processing/hdr.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.
+
+## createHdrBracketMergeTask
+
+Noise-optimal merge of linear RAW exposure brackets into a scene-linear photo-electron rate.
+
+```ts
+export function createHdrBracketMergeTask(input: HdrBracketMergeInput, provider: ProcessingProvider): ProcessingTask<HdrBracketMergeOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createHdrImageEncodingTask
+
+Converts linear RGB to unclipped float32 linear BT.2020 (relative values, no transfer function or quantization).
+
+```ts
+export function createHdrImageEncodingTask(input: HdrImageEncodingInput, provider: ProcessingProvider): ProcessingTask<HdrImageEncodingOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## HdrBracketFrame
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrBracketFrame {
+  exposureTimeSeconds: number;
+  /** Linear RAW codes, one per sample. */
+  codes: Uint16Array | Float32Array;
+  blackLevelCode: number;
+  /** Codes at or above this level are saturated and excluded. */
+  whiteLevelCode: number;
+  /** Optional per-sample flags. Non-zero excludes the sample (for example physical saturation before the ADC). */
+  saturationFlags?: Uint8Array;
+  /** System conversion gain K, electrons per code (includes the frame's ISO gain). */
+  conversionGainElectronsPerCode: number;
+  /** RMS read noise in electrons for this frame's readout regime. */
+  readNoiseElectrons: number;
+}
+```
+
+## HdrBracketMergeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrBracketMergeInput {
+  /** Samples per frame (e.g. width·height for a mosaic, width·height·3 for RGB). */
+  sampleCount: number;
+  frames: readonly HdrBracketFrame[];
+  /** Variance reweighting iterations after the shot-noise-limited start; default 2. */
+  iterations?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## HdrBracketMergeOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrBracketMergeOutput {
+  /** Scene-linear photo-electron rate per sample, e⁻/s (relative scene radiance; not absolute). */
+  radianceElectronsPerSecond: Float32Array;
+  /** Model standard deviation of each estimate, e⁻/s. */
+  standardDeviationElectronsPerSecond: Float32Array;
+  /** Frames that contributed; 0 marks a sample saturated in every frame (value is a lower bound). */
+  contributingFrameCount: Uint8Array;
+  saturatedInAllFramesCount: number;
+  provenance: ProcessingProvenance;
+}
+```
+
+## HdrImageEncodingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrImageEncodingInput {
+  image: ProcessingRgbImage;
+  inputColorSpace: ProcessingLinearColorSpace;
+  transfer: HdrTransfer;
+  maximumWorkingBytes?: number;
+}
+```
+
+## HdrImageEncodingOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface HdrImageEncodingOutput {
+  width: number;
+  height: number;
+  colorSpace: "rec2020";
+  transfer: HdrTransfer;
+  /** Interleaved linear BT.2020 RGB (relative, unclipped). */
+  linear: Float32Array;
+  provenance: ProcessingProvenance;
+}
+```
+
+## HdrTransfer
+
+The only output transfer in 2.0: unclipped float32 linear values (PQ and HLG are not shipped).
+
+```ts
+export type HdrTransfer = "linear-float32";
+```

package/docs/api/processing-panorama.md

@@ -0,0 +1,82 @@
+# processing/panorama.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.
+
+## createPanoramaTask
+
+Stitches frames with known rotations onto a cylindrical or equirectangular canvas.
+
+```ts
+export function createPanoramaTask(input: PanoramaInput, provider: ProcessingProvider): ProcessingTask<PanoramaOutput>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PanoramaCanvas
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PanoramaCanvas {
+  projection: "equirectangular" | "cylindrical";
+  width: number;
+  height: number;
+  /** [min, max] longitude θ in radians across the canvas columns (left → right). */
+  longitudeRangeRad: readonly [number, number];
+  /** [min, max] latitude φ in radians (bottom → top); cylindrical rows are linear in tan φ. */
+  latitudeRangeRad: readonly [number, number];
+}
+```
+
+## PanoramaFrame
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PanoramaFrame {
+  image: ProcessingRgbImage;
+  /** Rectilinear focal length in pixels (same pixel pitch on both axes). */
+  focalLengthPixels: number;
+  /** Principal point in pixel coordinates (pixel centres at i + 0.5); default the image centre. */
+  principalPointPixels?: { x: number; y: number };
+  /** Camera rotation relative to the reference camera: pitch/yaw/roll radians, engine sign convention. */
+  rotationRad: { pitch: number; yaw: number; roll: number };
+}
+```
+
+## PanoramaInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PanoramaInput {
+  frames: readonly PanoramaFrame[];
+  canvas: PanoramaCanvas;
+  /** Default `feather`. */
+  blending?: "feather" | "multi-band";
+  /** Default `gain` (Brown & Lowe 2007); `none` keeps frame intensities. */
+  exposureCompensation?: "none" | "gain";
+  /** Normalized intensity noise σ_N; default 0.04 (≈ 10/255, the published 8-bit value). */
+  gainNoiseSigma?: number;
+  /** Gain prior σ_g; default 0.1. */
+  gainPriorSigma?: number;
+  /** Multi-band pyramid levels; default min(4, auto). Coarse bands wider than the frame overlap mix
+   * low frequencies that were normalized differently, so keep 2^(levels−1) well below the overlap width. */
+  pyramidLevels?: number;
+  maximumWorkingBytes?: number;
+}
+```
+
+## PanoramaOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PanoramaOutput extends ProcessingRgbImage {
+  /** Number of frames covering each canvas pixel; 0 = uncovered (value 0). */
+  coverage: Uint8Array;
+  /** Gain applied to each frame (1 when compensation is off). */
+  gains: readonly number[];
+  provenance: ProcessingProvenance;
+}
+```

package/docs/api/processing-processing-task.md

@@ -0,0 +1,107 @@
+# processing/processing-task.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.
+
+## PROCESSING_DEFAULT_MAXIMUM_WORKING_BYTES
+
+Default working-memory bound when `maximumWorkingBytes` is omitted (1 GiB).
+
+```ts
+PROCESSING_DEFAULT_MAXIMUM_WORKING_BYTES = 1 << 30
+```
+
+## PROCESSING_MAX_FRAMES
+
+Largest number of input frames (brackets, focus slices, panorama frames).
+
+```ts
+PROCESSING_MAX_FRAMES = 32
+```
+
+## PROCESSING_MAX_PIXELS
+
+Largest image (pixels per frame) any processing operator accepts.
+
+```ts
+PROCESSING_MAX_PIXELS = 1 << 26
+```
+
+## PROCESSING_MODEL_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PROCESSING_MODEL_VERSION = "1.0.0" as const
+```
+
+## ProcessingLinearColorSpace
+
+Linear RGB encodings the colour-aware operators accept (all D65).
+
+```ts
+export type ProcessingLinearColorSpace = "linear-srgb-d65" | "linear-display-p3-d65" | "linear-rec2020-d65";
+```
+
+## ProcessingProvenance
+
+Result provenance of a processing operator; processing outputs are never calibrated.
+
+```ts
+export interface ProcessingProvenance extends CalculationProvenance {
+  kind: "approximation";
+  assumptions: readonly string[];
+}
+```
+
+## ProcessingProvider
+
+Host hooks, the same shape as the native task providers.
+
+```ts
+export interface ProcessingProvider {
+  /** Must yield to the host event loop, allowing cancellation/input events between rows. */
+  yieldControl(signal: AbortSignal): Promise<void>;
+  /** Optional observer called after each processed row of each pass; cannot change output. */
+  onProgress?(progress: NativeTaskProgress): void;
+}
+```
+
+## ProcessingRgbImage
+
+Interleaved RGB image: `data[(y·width + x)·3 + c]`, row-major, +Y down.
+
+```ts
+export interface ProcessingRgbImage {
+  width: number;
+  height: number;
+  data: Float32Array;
+}
+```
+
+## ProcessingTask
+
+Single-use cancellable processing task.
+
+```ts
+export interface ProcessingTask<T> {
+  readonly state: ProcessingTaskState;
+  /** Rows processed so far across every pass. */
+  readonly completedTileCount: number;
+  /** Total rows of every pass; known before `run()`. */
+  readonly totalTileCount: number;
+  /** Upper estimate of typed-array bytes allocated by the task, including its output. */
+  readonly estimatedWorkingBytes: number;
+  run(): Promise<void>;
+  cancel(): void;
+  dispose(): void;
+  takeOutput(): T;
+}
+```
+
+## ProcessingTaskState
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ProcessingTaskState = "ready" | "running" | "completed" | "cancelled" | "failed" | "disposed" | "transferred";
+```