@photivra/engine 0.6.0 → 1.0.1

package/docs/api/optics-thin-lens.md

@@ -0,0 +1,53 @@
+# optics/thin-lens.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+
+## calculateThinLensImageDistance
+
+Calculates Gaussian thin-lens image distance:
+
+1/f = 1/s + 1/v
+
+where f is focal length, s is object distance, and v is image distance.
+
+This is a paraxial ideal-lens model. It does not model real-lens focus
+breathing, pupil magnification, principal-plane movement, or aberrations.
+
+```ts
+export function calculateThinLensImageDistance(
+  input: CalculateThinLensImageDistanceInput
+): CalculationResult<ThinLensImageDistance>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateThinLensImageDistanceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateThinLensImageDistanceInput {
+  /** Lens focal length in millimetres. */
+  focalLengthMm: number;
+  /** Object/focus-plane distance from the lens principal plane in metres. */
+  objectDistanceM: number;
+}
+```
+
+## ThinLensImageDistance
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ThinLensImageDistance {
+  /** Image/sensor-plane distance from the lens principal plane in millimetres. */
+  imageDistanceMm: number;
+  /** Absolute paraxial magnification at the supplied object distance. */
+  magnification: number;
+  /**
+   * Image-distance scale relative to the infinity-focus approximation f.
+   * Values approach 1 as object distance becomes large.
+   */
+  infinityProjectionScale: number;
+}
+```

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

@@ -0,0 +1,71 @@
+# output/capture-corrected-sdr.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+
+## calculateCaptureCorrectedSdr
+
+Bounded committed capture → color/WB → native correction → oriented output view → SDR. No physical stage activation.
+
+```ts
+export function calculateCaptureCorrectedSdr(input: CaptureCorrectedSdrInput): CalculationResult<CaptureCorrectedSdrResult>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CAPTURE_CORRECTED_SDR_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+CAPTURE_CORRECTED_SDR_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## CaptureCorrectedSdrInput
+
+Explicit native-optical correction binding. Body/lens/mode identities remain producer declarations.
+
+```ts
+export interface CaptureCorrectedSdrInput extends CaptureSdrInput {
+  correction: {
+    profile: GenericLensCorrectionProfile;
+    state: OpticalProfileState;
+    /** Native optical +X right/+Y up, RGB basis after the selected color/WB operation. */
+    coordinateFrame: "native-optical-linear-srgb-d65";
+    selections: Readonly<Record<string, "on" | "off" | "auto">>;
+    selectionKind: ResolvedLensCorrectionPlan["selectionKind"];
+    /** Seconds from exposure start, not the capture's scene-clock time. */
+    frameTimeSeconds: number;
+    resampler: GeometricResampler;
+    clippingLevel: number;
+    invalidSupport: "reject" | "joint-valid-crop";
+    outputImageStateId: string;
+  };
+}
+```
+
+## CaptureCorrectedSdrResult
+
+Derived output view, never a replacement for the committed capture's physical geometry.
+
+```ts
+export interface CaptureCorrectedSdrResult extends Omit<CaptureSdrResult, "schemaVersion"> {
+  schemaVersion: typeof CAPTURE_CORRECTED_SDR_SCHEMA_VERSION;
+  sceneTimeSeconds: number;
+  plan: CalculationResult<ResolvedLensCorrectionPlan>;
+  correction: ReturnType<typeof calculateLensCorrectedCapture>;
+  projection: ReturnType<typeof calculateFieldOfView>;
+  /** Oriented full-output support; child correction plans retain native optical coordinates. */
+  validSourceMask: readonly boolean[];
+  outputView: { imageStateId: string; rect: RasterRect; pixelWidth: number; pixelHeight: number; samples: readonly number[] };
+}
+```
+
+## parseCaptureCorrectedSdrInput
+
+Strict boundary; execution also checks capture optics, native raster binding and source history.
+
+```ts
+export function parseCaptureCorrectedSdrInput(input: unknown): CaptureCorrectedSdrInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/output-capture-geometry.md

@@ -0,0 +1,500 @@
+# output/capture-geometry.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+
+## ActiveCaptureFieldOfView
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ActiveCaptureFieldOfView {
+  orientation: CaptureOrientation;
+  horizontalDegrees: number;
+  verticalDegrees: number;
+  /**
+   * Larger of the two opposite-corner diagonal angular spans. For centered
+   * crops both diagonal spans are equal.
+   */
+  diagonalDegrees: number;
+  horizontalBoundsDegrees: {
+    minimum: number;
+    maximum: number;
+  };
+  verticalBoundsDegrees: {
+    minimum: number;
+    maximum: number;
+  };
+  diagonalDegreesByCornerPair: {
+    topLeftToBottomRight: number;
+    topRightToBottomLeft: number;
+  };
+  activeImagingArea: SensorImagingArea;
+  centerOffsetFromOpticalAxisMm: RasterVector;
+  projection: {
+    projectionDistanceMm: number;
+    provenance: CalculationProvenance;
+  };
+}
+```
+
+## calculateActiveCaptureFieldOfView
+
+Calculates asymmetric horizontal/vertical FOV plus opposite-corner diagonal
+spans for the active physical capture area after physical camera orientation.
+
+Final digital/output crop is intentionally excluded.
+
+```ts
+export function calculateActiveCaptureFieldOfView(
+  input: CalculateActiveCaptureFieldOfViewInput
+): CalculationResult<ActiveCaptureFieldOfView>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateActiveCaptureFieldOfViewInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateActiveCaptureFieldOfViewInput {
+  imagingArea: SensorImagingArea;
+  nativeRaster: NativeImageRaster;
+  orientation: CaptureOrientation;
+  activeCaptureRect?: RasterRect;
+  focalLengthMm: number;
+  focusDistanceM?: number;
+}
+```
+
+## calculateOutputFieldOfView
+
+Calculates final visible field of view after physical active capture,
+orientation, and digital/output crop. Output raster resolution does not
+affect this optical/framing result.
+
+```ts
+export function calculateOutputFieldOfView(
+  input: CalculateOutputFieldOfViewInput
+): CalculationResult<OutputFieldOfView>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateOutputFieldOfViewInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateOutputFieldOfViewInput {
+  imagingArea: SensorImagingArea;
+  nativeRaster: NativeImageRaster;
+  orientation: CaptureOrientation;
+  activeCaptureRect?: RasterRect;
+  outputCropRect?: RasterRect;
+  focalLengthMm: number;
+  focusDistanceM?: number;
+}
+```
+
+## CaptureOrientation
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CaptureOrientation =
+  | "landscape"
+  | "portrait-clockwise"
+  | "landscape-inverted"
+  | "portrait-counter-clockwise";
+```
+
+## ImagePlaneMetricPointMm
+
+Pre-orientation optical image-plane coordinate in millimetres.
+
+Origin is the optical axis; +X points right and +Y points up.
+
+```ts
+export interface ImagePlaneMetricPointMm {
+  x: number;
+  y: number;
+}
+```
+
+## mapImagePlanePointToOrientedPhysicalUv
+
+Maps a pre-orientation optical image-plane point into normalized coordinates
+of an oriented physical raster region.
+
+This is the exact coordinate inverse of
+mapOrientedPhysicalUvToImagePlanePoint(). Points outside the supplied region
+fail closed; a tiny tolerance only absorbs floating-point round-trip noise at
+an edge.
+
+```ts
+export function mapImagePlanePointToOrientedPhysicalUv(
+  input: MapImagePlanePointToOrientedPhysicalUvInput
+): NormalizedRasterUv;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## MapImagePlanePointToOrientedPhysicalUvInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MapImagePlanePointToOrientedPhysicalUvInput {
+  imagePlanePointMm: ImagePlaneMetricPointMm;
+  /**
+   * Physical region represented by the normalized raster, after physical
+   * camera orientation, using the capture contract's +Y-down physical basis.
+   */
+  orientedPhysicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
+  orientation: CaptureOrientation;
+}
+```
+
+## MapOrientedPhysicalUvToImagePlaneInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MapOrientedPhysicalUvToImagePlaneInput {
+  uv: NormalizedRasterUv;
+  /**
+   * Physical region represented by the normalized raster, after physical
+   * camera orientation, using the capture contract's +Y-down physical basis.
+   */
+  orientedPhysicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
+  orientation: CaptureOrientation;
+}
+```
+
+## mapOrientedPhysicalUvToImagePlanePoint
+
+Maps normalized coordinates in an oriented physical raster region into the
+pre-orientation optical image plane used by lens-field and camera-mapping
+APIs.
+
+The supplied physical bounds use the capture contract's +Y-down basis after
+physical camera orientation. The returned image-plane point uses optical-axis
+origin, +X right and +Y up. No lens or projection equation is applied.
+
+```ts
+export function mapOrientedPhysicalUvToImagePlanePoint(
+  input: MapOrientedPhysicalUvToImagePlaneInput
+): ImagePlaneMetricPointMm;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## NormalizedRasterUv
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NormalizedRasterUv {
+  /** 0 at the left edge, 1 at the right edge. */
+  u: number;
+  /** 0 at the top edge, 1 at the bottom edge. */
+  v: number;
+}
+```
+
+## OutputFieldOfView
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface OutputFieldOfView {
+  orientation: CaptureOrientation;
+  horizontalDegrees: number;
+  verticalDegrees: number;
+  diagonalDegrees: number;
+  horizontalBoundsDegrees: {
+    minimum: number;
+    maximum: number;
+  };
+  verticalBoundsDegrees: {
+    minimum: number;
+    maximum: number;
+  };
+  diagonalDegreesByCornerPair: {
+    topLeftToBottomRight: number;
+    topRightToBottomLeft: number;
+  };
+  outputImagingArea: SensorImagingArea;
+  centerOffsetFromOpticalAxisMm: RasterVector;
+  projection: {
+    projectionDistanceMm: number;
+    provenance: CalculationProvenance;
+  };
+}
+```
+
+## PhysicalBoundsFromOpticalAxisMm
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PhysicalBoundsFromOpticalAxisMm {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+}
+```
+
+## RasterPoint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RasterPoint {
+  x: number;
+  y: number;
+}
+```
+
+## RasterRect
+
+Integer half-open rectangle in raster coordinates.
+
+Coordinates use a top-left origin with +X to the right and +Y downward.
+The covered extent is [x, x + width) × [y, y + height).
+
+```ts
+export interface RasterRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+```
+
+## RasterVector
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RasterVector {
+  x: number;
+  y: number;
+}
+```
+
+## resolveCaptureGeometry
+
+Resolves native sensor geometry, active capture, physical camera orientation,
+and final digital/output geometry without conflating their identities.
+
+```ts
+export function resolveCaptureGeometry(
+  input: ResolveCaptureGeometryInput
+): CalculationResult<ResolvedCaptureGeometry>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveCaptureGeometryInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveCaptureGeometryInput {
+  imagingArea: SensorImagingArea;
+  nativeRaster: NativeImageRaster;
+  orientation: CaptureOrientation;
+  /**
+   * Active capture rectangle in native sensor raster coordinates.
+   *
+   * Defaults to the full native raster.
+   */
+  activeCaptureRect?: RasterRect;
+  /**
+   * Final digital/output crop in oriented active-capture raster coordinates.
+   *
+   * Defaults to the full oriented active capture.
+   */
+  outputCropRect?: RasterRect;
+  /**
+   * Final output raster after optional digital crop/resampling.
+   *
+   * Defaults to the output-crop dimensions. The output raster must preserve
+   * the crop aspect ratio within a small integer-rounding tolerance.
+   */
+  outputRaster?: RasterDimensions;
+}
+```
+
+## ResolvedCaptureGeometry
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedCaptureGeometry {
+  native: {
+    imagingArea: SensorImagingArea;
+    raster: NativeImageRaster;
+  };
+  activeCapture: {
+    nativeRect: RasterRect;
+    imagingArea: SensorImagingArea;
+    /**
+     * Top-left active-area offset from the native imaging-area top-left.
+     */
+    physicalOffsetMm: {
+      x: number;
+      y: number;
+    };
+    /** Active-area center relative to the native optical axis. */
+    centerOffsetFromOpticalAxisMm: RasterVector;
+    /** Native physical bounds relative to the optical axis. */
+    physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
+    /**
+     * Current generic model assumes native image samples uniformly span the
+     * declared physical imaging area.
+     */
+    imagingAreaDerivation: "uniform-native-raster";
+    raster: RasterDimensions;
+  };
+  orientedCapture: {
+    orientation: CaptureOrientation;
+    imagingArea: SensorImagingArea;
+    /** Oriented physical bounds relative to the optical axis. */
+    physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
+    raster: RasterDimensions;
+  };
+  output: {
+    /**
+     * Digital/output crop expressed in oriented active-capture coordinates.
+     *
+     * This crop does not mutate physical sensor identity or active-capture
+     * geometry.
+     */
+    cropRect: RasterRect;
+    raster: RasterDimensions;
+    /** Physical region retained by the digital/output crop. */
+    imagingArea: SensorImagingArea;
+    physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
+    centerOffsetFromOpticalAxisMm: RasterVector;
+    sourceRetainedAreaFraction: number;
+    /** Pixel-domain resampling from oriented active capture into output. */
+    orientedCaptureToOutputScale: {
+      x: number;
+      y: number;
+      axisRelativeDifference: number;
+    };
+  };
+}
+```
+
+## transformNativeRasterPointToOriented
+
+Transforms a continuous native raster edge-coordinate point into oriented
+capture coordinates. Pixel centers can be represented with +0.5 offsets.
+
+```ts
+export function transformNativeRasterPointToOriented(
+  input: TransformRasterPointInput
+): RasterPoint;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## transformNativeRasterRectToOriented
+
+Transforms an integer half-open native raster rectangle into oriented coordinates.
+
+```ts
+export function transformNativeRasterRectToOriented(
+  input: TransformRasterRectInput
+): RasterRect;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## transformNativeRasterVectorToOriented
+
+Rotates a native raster vector into oriented coordinates.
+
+```ts
+export function transformNativeRasterVectorToOriented(
+  input: TransformRasterVectorInput
+): RasterVector;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## transformOrientedRasterPointToNative
+
+Transforms an oriented raster edge-coordinate point back to native coordinates.
+
+```ts
+export function transformOrientedRasterPointToNative(
+  input: TransformRasterPointInput
+): RasterPoint;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## transformOrientedRasterRectToNative
+
+Transforms an oriented integer half-open rectangle back to native coordinates.
+
+```ts
+export function transformOrientedRasterRectToNative(
+  input: TransformRasterRectInput
+): RasterRect;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## transformOrientedRasterVectorToNative
+
+Rotates an oriented raster vector back into native coordinates.
+
+```ts
+export function transformOrientedRasterVectorToNative(
+  input: TransformRasterVectorInput
+): RasterVector;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## TransformRasterPointInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface TransformRasterPointInput {
+  point: RasterPoint;
+  nativeRaster: NativeImageRaster;
+  orientation: CaptureOrientation;
+}
+```
+
+## TransformRasterRectInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface TransformRasterRectInput {
+  rect: RasterRect;
+  nativeRaster: NativeImageRaster;
+  orientation: CaptureOrientation;
+}
+```
+
+## TransformRasterVectorInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface TransformRasterVectorInput {
+  vector: RasterVector;
+  orientation: CaptureOrientation;
+}
+```

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

@@ -0,0 +1,69 @@
+# output/capture-sdr.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [Navigation](../API_REFERENCE.md) · [Developer guide](../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.
+
+## calculateCaptureSdr
+
+Renders the validated capture color state without correction or resampling.
+
+```ts
+export function calculateCaptureSdr(input: CaptureSdrInput): CalculationResult<CaptureSdrResult>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CAPTURE_SDR_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+CAPTURE_SDR_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## CaptureSdrInput
+
+Select an existing RGB state or explicitly derive one; never estimate WB here.
+
+```ts
+export interface CaptureSdrInput {
+  capture: SimulatedCapture;
+  sourcePlaneId: string;
+  color: { kind: "already-transformed" } | {
+    kind: "transform";
+    outputPlaneId: string;
+    outputImageStateId: string;
+    whiteBalance: CaptureColorTransformInput["whiteBalance"];
+  };
+  profile: SdrRenderingProfile;
+}
+```
+
+## CaptureSdrResult
+
+Keeps source capture history, optional color derivation and SDR diagnostics distinct.
+
+```ts
+export interface CaptureSdrResult {
+  schemaVersion: typeof CAPTURE_SDR_SCHEMA_VERSION;
+  captureId: string;
+  sourcePlaneId: string;
+  sourceImageStateId: string;
+  rasterBinding: CaptureLinearPlane["rasterBinding"];
+  sourceCaptureSaturation: CaptureLinearPlane["captureSaturation"];
+  sourceDynamicRangeHistory: SimulatedCapture["source"]["dynamicRangeHistory"];
+  noiseRealizationId: string;
+  whiteBalance: "applied-here" | "already-applied-upstream" | "not-required";
+  color: CalculationResult<CaptureColorTransformResult> | null;
+  rendering: CalculationResult<SdrRenderingResult>;
+}
+```
+
+## parseCaptureSdrInput
+
+Validates the capture and explicit color/render choices at an untrusted boundary.
+
+```ts
+export function parseCaptureSdrInput(value: unknown): CaptureSdrInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.