@photivra/engine 0.6.0 → 1.0.1

package/docs/api/optics-lateral-chromatic-aberration.md

@@ -0,0 +1,225 @@
+# optics/lateral-chromatic-aberration.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.
+
+## calculateInverseLateralChromaticAberrationMapping
+
+Inverse-maps one distorted output destination independently for the
+representative red/green/blue channels.
+
+Renderers can use the returned per-channel ideal source coordinates for
+inverse sampling without inventing chromatic-aberration equations.
+
+```ts
+export function calculateInverseLateralChromaticAberrationMapping(
+  input: CalculateInverseLateralChromaticAberrationMappingInput
+): CalculationResult<InverseLateralChromaticAberrationMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateInverseLateralChromaticAberrationMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateInverseLateralChromaticAberrationMappingInput {
+  /**
+   * Distorted output image-plane destination. Each output channel is inverse-
+   * mapped independently to its ideal source coordinate.
+   */
+  distortedImagePointMm: LensFieldPointMm;
+  profile: LateralChromaticAberrationProfile;
+}
+```
+
+## calculateInverseLateralChromaticAberrationMappings
+
+Inverse-maps multiple distorted destinations while resolving the shared CA
+profile once and validating each combined channel profile once for the
+complete batch.
+
+Per-point values match calculateInverseLateralChromaticAberrationMapping();
+provenance is shared once at the batch boundary.
+
+```ts
+export function calculateInverseLateralChromaticAberrationMappings(
+  input: CalculateInverseLateralChromaticAberrationMappingsInput
+): CalculationResult<InverseLateralChromaticAberrationMappings>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateInverseLateralChromaticAberrationMappingsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateInverseLateralChromaticAberrationMappingsInput {
+  /**
+   * Distorted output image-plane destinations. Each destination is inverse-
+   * mapped independently for red, green, and blue after one profile-resolution
+   * step for the batch.
+   */
+  distortedImagePointsMm: readonly LensFieldPointMm[];
+  profile: LateralChromaticAberrationProfile;
+}
+```
+
+## calculateLateralChromaticAberrationMapping
+
+Calculates generic lateral chromatic-aberration field separation by mapping
+one ideal image-plane point through a shared green-reference base distortion
+and red/blue radial coefficient offsets.
+
+This is channel-dependent field mapping, not a blur kernel.
+
+```ts
+export function calculateLateralChromaticAberrationMapping(
+  input: CalculateLateralChromaticAberrationMappingInput
+): CalculationResult<LateralChromaticAberrationMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLateralChromaticAberrationMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLateralChromaticAberrationMappingInput {
+  /** Ideal/undistorted image-plane point shared by all channels. */
+  imagePointMm: LensFieldPointMm;
+  profile: LateralChromaticAberrationProfile;
+}
+```
+
+## ChannelSeparationVectorMm
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ChannelSeparationVectorMm {
+  x: number;
+  y: number;
+  distance: number;
+}
+```
+
+## InverseLateralChromaticAberrationChannelMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface InverseLateralChromaticAberrationChannelMapping {
+  sourceImagePointMm: LensFieldPointMm;
+  radialScaleAtSource: number;
+  combinedCoefficients: RadialDistortionCoefficients;
+}
+```
+
+## InverseLateralChromaticAberrationMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface InverseLateralChromaticAberrationMapping {
+  direction: "distorted-output-to-channel-sources";
+  referenceChannel: "green";
+  distortedImagePointMm: LensFieldPointMm;
+  channels: {
+    red: InverseLateralChromaticAberrationChannelMapping;
+    green: InverseLateralChromaticAberrationChannelMapping;
+    blue: InverseLateralChromaticAberrationChannelMapping;
+  };
+  sourceSeparation: LateralChromaticAberrationSeparation;
+}
+```
+
+## InverseLateralChromaticAberrationMappings
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface InverseLateralChromaticAberrationMappings {
+  direction: "distorted-output-to-channel-sources-batch";
+  referenceChannel: "green";
+  mappings: readonly InverseLateralChromaticAberrationMapping[];
+  pointCount: number;
+}
+```
+
+## LateralChromaticAberrationChannel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type LateralChromaticAberrationChannel = "red" | "green" | "blue";
+```
+
+## LateralChromaticAberrationChannelMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LateralChromaticAberrationChannelMapping {
+  mappedImagePointMm: LensFieldPointMm;
+  radialScale: number;
+  combinedCoefficients: RadialDistortionCoefficients;
+}
+```
+
+## LateralChromaticAberrationMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LateralChromaticAberrationMapping {
+  direction: "undistorted-to-channel-distorted";
+  referenceChannel: "green";
+  sourceImagePointMm: LensFieldPointMm;
+  channels: {
+    red: LateralChromaticAberrationChannelMapping;
+    green: LateralChromaticAberrationChannelMapping;
+    blue: LateralChromaticAberrationChannelMapping;
+  };
+  separation: LateralChromaticAberrationSeparation;
+}
+```
+
+## LateralChromaticAberrationProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LateralChromaticAberrationProfile {
+  /** Shared physical image-plane normalization radius in millimetres. */
+  normalizationRadiusMm: number;
+  /** Shared undistorted normalized-radius operating envelope. */
+  maximumNormalizedRadius: number;
+  /**
+   * Green-reference base geometric distortion.
+   *
+   * This common mapping is included in every channel. Red/blue CA terms are
+   * added to this base, so callers should not apply a second distortion pass.
+   */
+  baseDistortionCoefficients: RadialDistortionCoefficients;
+  /** Additional red-channel radial coefficients relative to green. */
+  redCoefficientOffset: RadialDistortionCoefficients;
+  /** Additional blue-channel radial coefficients relative to green. */
+  blueCoefficientOffset: RadialDistortionCoefficients;
+}
+```
+
+## LateralChromaticAberrationSeparation
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LateralChromaticAberrationSeparation {
+  redGreen: ChannelSeparationVectorMm;
+  blueGreen: ChannelSeparationVectorMm;
+  redBlue: ChannelSeparationVectorMm;
+  maximumPairDistanceMm: number;
+}
+```

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

@@ -0,0 +1,380 @@
+# optics/lens-psf-profile.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.
+
+## assessMtfOnlyPsfRenderability
+
+Explain why MTF-only evidence cannot determine a unique renderable PSF; return blockers instead of
+fabricating phase information.
+
+Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
+support. Interpolation stays within declared applicability and preserves normalized shape separately
+from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
+unique PSF.
+
+```ts
+export function assessMtfOnlyPsfRenderability(
+  profile:
+    LensMtfDiagnosticProfile
+): MtfOnlyPsfRenderabilityAssessment;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## LENS_MTF_DIAGNOSTIC_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+LENS_MTF_DIAGNOSTIC_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## LENS_SAMPLED_PSF_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+LENS_SAMPLED_PSF_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## LensMtfDiagnosticProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensMtfDiagnosticProfile {
+  schemaVersion:
+    typeof LENS_MTF_DIAGNOSTIC_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  opticalDomain:
+    "lens-primary-optical-path-only";
+  phaseInformationAvailable:
+    false;
+  magnitudeMeaning:
+    "mtf-magnitude-only";
+  fieldPointMm: {
+    x: number;
+    y: number;
+  };
+  focalLengthMm: number;
+  focus: FocusPlane;
+  apertureFNumber: number;
+  wavelengthNm: number | null;
+  samples:
+    readonly LensMtfDiagnosticSample[];
+  evidence:
+    readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## LensMtfDiagnosticSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensMtfDiagnosticSample {
+  spatialFrequencyCyclesPerMm:
+    number;
+  sagittalMagnitude: number;
+  tangentialMagnitude: number;
+}
+```
+
+## LensPsfGridAxes
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensPsfGridAxes {
+  focalLengthMm:
+    readonly number[];
+  focusDiopters:
+    readonly number[];
+  apertureFNumber:
+    readonly number[];
+  fieldXmm:
+    readonly number[];
+  fieldYmm:
+    readonly number[];
+  wavelengthNm:
+    readonly number[];
+  signedDefocusImagePlaneMicrometers:
+    readonly number[];
+}
+```
+
+## LensPsfKernel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensPsfKernel {
+  widthSamples: number;
+  heightSamples: number;
+  samplePitchMicrometersX: number;
+  samplePitchMicrometersY: number;
+  centerSampleX: number;
+  centerSampleY: number;
+  normalizedIntensity:
+    readonly number[];
+}
+```
+
+## LensPsfScientificStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type LensPsfScientificStatus =
+  | "calibrated"
+  | "approximation";
+```
+
+## LensPsfUncertainty
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type LensPsfUncertainty =
+  | {
+      kind: "relative";
+      fraction: number;
+      basis: string;
+    }
+  | {
+      kind: "not-quantified";
+      limitation: string;
+    };
+```
+
+## LensSampledPsfGridCoordinate
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensSampledPsfGridCoordinate {
+  focalLengthMm: number;
+  focusDiopters: number;
+  apertureFNumber: number;
+  fieldXmm: number;
+  fieldYmm: number;
+  wavelengthNm: number;
+  signedDefocusImagePlaneMicrometers:
+    number;
+}
+```
+
+## LensSampledPsfGridNode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensSampledPsfGridNode {
+  nodeId: string;
+  coordinate:
+    LensSampledPsfGridCoordinate;
+  kernel: LensPsfKernel;
+  bestFocusImagePlaneOffsetMicrometers:
+    number;
+  relativePupilThroughputFactor:
+    number;
+  evidence:
+    readonly EvidenceProvenance[];
+  uncertainty:
+    LensPsfUncertainty;
+}
+```
+
+## LensSampledPsfProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensSampledPsfProfile {
+  schemaVersion:
+    typeof LENS_SAMPLED_PSF_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  scientificStatus:
+    LensPsfScientificStatus;
+  opticalDomain:
+    "lens-primary-optical-path-only";
+  coordinateSystem:
+    "image-plane-metric";
+  fieldAxes:
+    "+X right, +Y up";
+  kernelEnergyNormalization:
+    "unit-energy-shape";
+  interpolation:
+    "bounded-regular-grid-multilinear";
+  throughputOwnership:
+    "separate-relative-pupil-throughput-factor";
+  responseIncludes: {
+    diffraction: boolean;
+    aberration: boolean;
+    defocus: boolean;
+    pupilClippingShape:
+      boolean;
+  };
+  sensorOpticalStackIncluded:
+    false;
+  sensorSamplingIncluded:
+    false;
+  reconstructionIncluded:
+    false;
+  strayLightIncluded: false;
+  axes: LensPsfGridAxes;
+  nodes:
+    readonly LensSampledPsfGridNode[];
+  evidence:
+    readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## MtfOnlyPsfRenderabilityAssessment
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MtfOnlyPsfRenderabilityAssessment {
+  profileId: string;
+  psfReconstructionAuthorized:
+    false;
+  reason:
+    "mtf-magnitude-lacks-phase-and-does-not-uniquely-determine-psf";
+  diagnosticUseAuthorized: true;
+}
+```
+
+## parseLensMtfDiagnosticProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
+support. Interpolation stays within declared applicability and preserves normalized shape separately
+from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
+unique PSF.
+
+```ts
+export function parseLensMtfDiagnosticProfile(
+  value: unknown
+): LensMtfDiagnosticProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseLensSampledPsfProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
+support. Interpolation stays within declared applicability and preserves normalized shape separately
+from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
+unique PSF.
+
+```ts
+export function parseLensSampledPsfProfile(
+  value: unknown
+): LensSampledPsfProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedLensSampledPsf
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedLensSampledPsf {
+  profileId: string;
+  profileVersion: string;
+  scientificStatus:
+    LensPsfScientificStatus;
+  resolutionStatus:
+    | "exact-grid-sample"
+    | "interpolated";
+  coordinate:
+    LensSampledPsfGridCoordinate;
+  focus: FocusPlane;
+  kernel: LensPsfKernel;
+  bestFocusImagePlaneOffsetMicrometers:
+    number;
+  relativePupilThroughputFactor:
+    number;
+  sourceNodes:
+    readonly {
+      nodeId: string;
+      weight: number;
+      evidence:
+        readonly EvidenceProvenance[];
+      uncertainty:
+        LensPsfUncertainty;
+    }[];
+  responseIncludes:
+    LensSampledPsfProfile["responseIncludes"];
+  throughputOwnership:
+    "separate-relative-pupil-throughput-factor";
+  longitudinalChromaticFocusMayVaryWithWavelength:
+    true;
+  fieldCurvatureMayVaryWithFieldPosition:
+    true;
+  geometricDistortionModified:
+    false;
+  lateralChromaticPositionShiftApplied:
+    false;
+  sensorOpticalStackIncluded:
+    false;
+  sensorSamplingIncluded: false;
+  reconstructionIncluded: false;
+  strayLightIncluded: false;
+  scalarSharpnessScoreProduced:
+    false;
+}
+```
+
+## resolveLensSampledPsf
+
+Resolve the bounded sampled PSF for a declared optical state and support point without extrapolation
+or silently inventing missing dimensions.
+
+Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
+support. Interpolation stays within declared applicability and preserves normalized shape separately
+from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
+unique PSF.
+
+```ts
+export function resolveLensSampledPsf(
+  input:
+    ResolveLensSampledPsfInput
+): CalculationResult<ResolvedLensSampledPsf>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveLensSampledPsfInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveLensSampledPsfInput {
+  profile:
+    LensSampledPsfProfile;
+  focalLengthMm: number;
+  focus: FocusPlane;
+  apertureFNumber: number;
+  fieldPointMm: {
+    x: number;
+    y: number;
+  };
+  wavelengthNm: number;
+  signedDefocusImagePlaneMicrometers:
+    number;
+}
+```

package/docs/api/optics-polygon-diffraction.md

@@ -0,0 +1,68 @@
+# optics/polygon-diffraction.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.
+
+## CalculateIdealPolygonDiffractionInput
+
+On-axis, in-focus scalar diffraction of one ideal regular polygon pupil.
+
+```ts
+export interface CalculateIdealPolygonDiffractionInput extends CalculateIdealApertureInput {
+  /** Diameter of a circle with the SAME AREA as the physical polygon opening. */
+  equivalentAreaPupilDiameterMm: number;
+  /** Paraxial pupil-to-image propagation scale; not silently inferred from focus. */
+  pupilToImageDistanceMm: number;
+  /** Wavelength in the declared propagation medium; no air/vacuum conversion. */
+  wavelengthNm: number;
+  wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+  /** Displacements from the on-axis PSF center, +X right / +Y up; at most 4096. */
+  imagePointsMicrometers: readonly { x: number; y: number }[];
+}
+```
+
+## calculateIdealPolygonDiffractionPsf
+
+Calculates continuous monochromatic Fraunhofer PSF density for a uniformly
+illuminated, zero-phase, on-axis ideal straight-edged regular polygon.
+Physical area is explicit; f/N may supply the equal-area diameter only under
+a declared nominal-area convention. No phase aberration, clipping, field
+dependence, curved blades, defocus or polychromatic behavior is inferred.
+
+Density = A |F/A|² / (lambda * propagationDistance)². Parseval normalization
+is over the infinite plane, NOT over the supplied point list. Downstream
+quadrature must preserve density × area and report truncation/convergence.
+
+```ts
+export function calculateIdealPolygonDiffractionPsf(
+  input: CalculateIdealPolygonDiffractionInput
+): CalculationResult<IdealPolygonDiffraction>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## IdealPolygonDiffraction
+
+Continuous unit-energy PSF samples, not a normalized finite convolution kernel.
+
+```ts
+export interface IdealPolygonDiffraction {
+  bladeCount: number;
+  firstBladeEdgeAngleDegrees: number;
+  pupilToImageDistanceMm: number;
+  wavelengthNm: number;
+  wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+  pupilAreaSquareMm: number;
+  pupilCircumradiusMm: number;
+  pupilNormalization: "equal-area-circle";
+  fieldAxes: "+X right, +Y up";
+  energyNormalization: "unit-integral-over-infinite-image-plane";
+  throughputApplied: false;
+  samples: readonly {
+    imagePointMicrometers: { x: number; y: number };
+    /** |F/A|²; unity at the origin. Not an energy/probability weight. */
+    peakNormalizedIntensity: number;
+    /** Density integrating to unity over the full image plane, in 1/µm². */
+    intensityDensityPerSquareMicrometer: number;
+  }[];
+}
+```