@photivra/engine 0.5.1 → 1.0.0

package/docs/api/optics-profile-contract.md

@@ -0,0 +1,47 @@
+# optics/profile-contract.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [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.
+
+## GenericOpticalEvidence
+
+Generic approximation evidence; never implies measured calibration.
+
+```ts
+export interface GenericOpticalEvidence {
+  kind: "generic-parametric";
+  basis: string;
+  residualNote: string;
+  sources: readonly EvidenceProvenance[];
+}
+```
+
+## OpticalProfileState
+
+Exact, generic camera/lens and acquisition state; no implicit interpolation.
+
+```ts
+export interface OpticalProfileState {
+  bodyId: string;
+  bodyVersion: string;
+  lensId: string;
+  lensVersion: string;
+  focalLengthMm: number;
+  aperture: number;
+  focusDistanceM: number;
+  captureMode: "still" | "video";
+  outputWidth: number;
+  outputHeight: number;
+  frameRateHz: number;
+  stabilizationMode: string;
+}
+```
+
+## parseOpticalProfileState
+
+Parses a complete exact-state binding, including still/video/output settings.
+
+```ts
+export function parseOpticalProfileState(value: unknown): OpticalProfileState;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/optics-psf-foundation.md

@@ -0,0 +1,181 @@
+# optics/psf-foundation.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [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.
+
+## calculatePsfFoundationComponents
+
+Evaluates the currently implemented PSF-related diagnostics in one explicit
+field/depth/spectral/pupil context without combining them into a synthetic
+PSF or blur radius.
+
+Field position is recorded even though the current defocus-circle and
+circular-Airy diagnostics are not field dependent. Future field-dependent
+contributions can consume the same context without changing these existing
+primitives.
+
+```ts
+export function calculatePsfFoundationComponents(
+  input: CalculatePsfFoundationComponentsInput
+): CalculationResult<PsfFoundationComponents>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculatePsfFoundationComponentsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculatePsfFoundationComponentsInput {
+  focalLengthMm: number;
+  aperture: number;
+  focusDistanceM: number;
+  subjectDistanceM: number;
+  /**
+   * Image-plane field position relative to the optical axis, in millimetres.
+   * +X is right and +Y is up.
+   */
+  fieldPointMm: LensFieldPointMm;
+  /**
+   * Physical image-plane radius used only to normalize field position for
+   * cross-case diagnostics. It is not a lens calibration or validity bound.
+   */
+  fieldNormalizationRadiusMm: number;
+  spectralBasis: {
+    kind: "monochromatic";
+    wavelengthNm: number;
+  };
+}
+```
+
+## getPsfFoundationContract
+
+Returns the public PSF/pupil foundation contract.
+
+The contract describes current diagnostics plus reserved future contribution
+ownership. It does not imply that reserved contributions are implemented.
+
+```ts
+export function getPsfFoundationContract(): PsfFoundationContract;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PSF_FOUNDATION_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PSF_FOUNDATION_VERSION = "0.3.0" as const
+```
+
+## PsfContributionContract
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PsfContributionContract {
+  id: PsfContributionId;
+  status: PsfContributionStatus;
+  dependsOn: readonly (
+    | "field-position"
+    | "focus-depth"
+    | "pupil"
+    | "wavelength"
+  )[];
+  note: string;
+}
+```
+
+## PsfContributionId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type PsfContributionId =
+  | "geometric-defocus-circle"
+  | "circular-diffraction-first-zero"
+  | "non-circular-diffraction"
+  | "mechanical-pupil-clipping"
+  | "field-curvature"
+  | "field-dependent-aberration"
+  | "field-dependent-bokeh";
+```
+
+## PsfContributionStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type PsfContributionStatus =
+  | "implemented-diagnostic"
+  | "implemented-framework"
+  | "reserved-contract";
+```
+
+## PsfFoundationComponents
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PsfFoundationComponents {
+  context: {
+    field: {
+      imagePointMm: LensFieldPointMm;
+      radiusMm: number;
+      normalizationRadiusMm: number;
+      normalizedRadius: number;
+    };
+    depth: {
+      focusDistanceM: number;
+      subjectDistanceM: number;
+    };
+    spectralBasis: {
+      kind: "monochromatic";
+      wavelengthNm: number;
+    };
+    pupil: {
+      kind: "ideal-circular-f-number-derived";
+      apertureFNumber: number;
+      diameterMm: number;
+    };
+  };
+  contributions: {
+    geometricDefocus: {
+      id: "geometric-defocus-circle";
+      diameterMm: number;
+      provenance: CalculationProvenance;
+    };
+    circularDiffraction: {
+      id: "circular-diffraction-first-zero";
+      firstZeroDiameterMicrometers: number;
+      provenance: CalculationProvenance;
+    };
+  };
+  composition: {
+    status: "not-composed";
+    note: string;
+  };
+}
+```
+
+## PsfFoundationContract
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PsfFoundationContract {
+  version: typeof PSF_FOUNDATION_VERSION;
+  coordinateSpace: "image-plane-metric";
+  fieldAxes: "+X right, +Y up";
+  compositionPolicy:
+    "separate-diagnostics-plus-explicit-profiled-combined-psf";
+  contributions: readonly PsfContributionContract[];
+  previewReferencePolicy: {
+    previewMayApproximate: true;
+    referenceMayUseHigherFidelity: true;
+    mustPreserveContributionSemantics: true;
+  };
+  notes: readonly string[];
+}
+```

package/docs/api/optics-radial-distortion.md

@@ -0,0 +1,194 @@
+# optics/radial-distortion.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [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.
+
+## calculateInverseRadialDistortionMapping
+
+Invert the declared monotonic radial field map within its supported envelope using the existing
+bounded root solve and preserve explicit optical coordinates.
+
+```ts
+export function calculateInverseRadialDistortionMapping(
+  input: CalculateInverseRadialDistortionMappingInput
+): CalculationResult<InverseRadialDistortionMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateInverseRadialDistortionMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateInverseRadialDistortionMappingInput {
+  /** Distorted image-plane point to inverse-map back to ideal coordinates. */
+  distortedImagePointMm: LensFieldPointMm;
+  profile: RadialDistortionProfile;
+}
+```
+
+## calculateInverseRadialDistortionMappings
+
+Inverse-maps multiple distorted image-plane destinations while validating
+and resolving the radial profile only once for the complete batch.
+
+The returned per-point mappings are numerically identical to the scalar API;
+provenance and profile validation are shared once at the batch boundary.
+
+```ts
+export function calculateInverseRadialDistortionMappings(
+  input: CalculateInverseRadialDistortionMappingsInput
+): CalculationResult<InverseRadialDistortionMappings>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateInverseRadialDistortionMappingsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateInverseRadialDistortionMappingsInput {
+  /** Distorted image-plane destinations to inverse-map in one validated batch. */
+  distortedImagePointsMm: readonly LensFieldPointMm[];
+  profile: RadialDistortionProfile;
+}
+```
+
+## calculateRadialDistortionMapping
+
+Applies a generic radial lens-distortion field mapping to one ideal
+image-plane point.
+
+The mapping is rotationally symmetric about the optical axis:
+
+  p_distorted = p_ideal * (1 + k1 r² + k2 r⁴ + k3 r⁶)
+
+where r is normalized by the caller-declared physical reference radius.
+
+The profile is accepted only when the radial mapping is strictly monotonic
+over its declared operating radius, which makes inverse destination-to-source
+sampling well-defined.
+
+```ts
+export function calculateRadialDistortionMapping(
+  input: CalculateRadialDistortionMappingInput
+): CalculationResult<RadialDistortionMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateRadialDistortionMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateRadialDistortionMappingInput {
+  /** Ideal/undistorted image-plane point. */
+  imagePointMm: LensFieldPointMm;
+  profile: RadialDistortionProfile;
+}
+```
+
+## InverseRadialDistortionMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface InverseRadialDistortionMapping {
+  direction: "distorted-to-undistorted";
+  distortedImagePointMm: LensFieldPointMm;
+  sourceImagePointMm: LensFieldPointMm;
+  distortedNormalizedRadius: number;
+  sourceNormalizedRadius: number;
+  radialScaleAtSource: number;
+  deltaMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+  profileMinimumRadialDerivative: number;
+}
+```
+
+## InverseRadialDistortionMappings
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface InverseRadialDistortionMappings {
+  direction: "distorted-to-undistorted-batch";
+  mappings: readonly InverseRadialDistortionMapping[];
+  pointCount: number;
+  profileMinimumRadialDerivative: number;
+}
+```
+
+## LensFieldPointMm
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensFieldPointMm {
+  /** Image-plane X coordinate relative to the optical axis, in mm. */
+  x: number;
+  /** Image-plane Y coordinate relative to the optical axis, in mm. */
+  y: number;
+}
+```
+
+## RadialDistortionCoefficients
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RadialDistortionCoefficients {
+  /** Dimensionless r² coefficient. */
+  k1: number;
+  /** Dimensionless r⁴ coefficient. */
+  k2: number;
+  /** Dimensionless r⁶ coefficient. */
+  k3: number;
+}
+```
+
+## RadialDistortionMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RadialDistortionMapping {
+  direction: "undistorted-to-distorted";
+  sourceImagePointMm: LensFieldPointMm;
+  mappedImagePointMm: LensFieldPointMm;
+  sourceNormalizedRadius: number;
+  mappedNormalizedRadius: number;
+  radialScale: number;
+  deltaMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+  profileMinimumRadialDerivative: number;
+}
+```
+
+## RadialDistortionProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface RadialDistortionProfile {
+  /**
+   * Physical image-plane radius used to normalize field position, in mm.
+   * Coefficients are meaningful only with this declared normalization.
+   */
+  normalizationRadiusMm: number;
+  /**
+   * Maximum undistorted normalized radius over which this profile is declared
+   * valid and must remain one-to-one/invertible.
+   */
+  maximumNormalizedRadius: number;
+  coefficients: RadialDistortionCoefficients;
+}
+```