@photivra/engine 0.5.1 → 1.0.0

package/docs/api/motion-extended-object-projection.md

@@ -0,0 +1,312 @@
+# motion/extended-object-projection.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.
+
+## calculateCaptureExtendedObjectTemporalProjection
+
+Evaluates extended-object projection at deterministic midpoint nodes inside
+each point's authoritative #12 local exposure window.
+
+```ts
+export function calculateCaptureExtendedObjectTemporalProjection(
+  input:
+    CalculateCaptureExtendedObjectTemporalProjectionInput
+): CalculationResult<CaptureExtendedObjectTemporalProjection>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCaptureExtendedObjectTemporalProjectionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCaptureExtendedObjectTemporalProjectionInput {
+  objectId: string;
+  timing:
+    ResolvedCaptureModeTiming;
+  focalLengthMm: number;
+  focusDistanceM?: number;
+  objectTranslationVelocityMps:
+    Vector3;
+  cameraTranslationVelocityMps:
+    Vector3;
+  temporalSampleCount: number;
+  points:
+    readonly CaptureExtendedObjectMetricPoint[];
+  frontoparallelPlane?:
+    ExtendedObjectFrontoparallelPlaneDeclaration;
+}
+```
+
+## calculateExtendedObjectProjectionTrajectory
+
+Evaluates multiple explicit metric points on one rigidly translating object
+at deterministic physical times.
+
+This is geometry only. It does not synthesize a blur kernel, visibility,
+radiance integration, deformation, camera rotation or a universal scale.
+
+```ts
+export function calculateExtendedObjectProjectionTrajectory(
+  input:
+    CalculateExtendedObjectProjectionTrajectoryInput
+): CalculationResult<ExtendedObjectProjectionTrajectory>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateExtendedObjectProjectionTrajectoryInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateExtendedObjectProjectionTrajectoryInput {
+  objectId: string;
+  focalLengthMm: number;
+  focusDistanceM?: number;
+  objectTranslationVelocityMps:
+    Vector3;
+  cameraTranslationVelocityMps:
+    Vector3;
+  sampleTimesSecondsFromReference:
+    readonly number[];
+  points:
+    readonly ExtendedObjectMetricPoint[];
+  frontoparallelPlane?:
+    ExtendedObjectFrontoparallelPlaneDeclaration;
+}
+```
+
+## CaptureExtendedObjectMetricPoint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureExtendedObjectMetricPoint
+  extends ExtendedObjectMetricPoint {
+  /**
+   * Native destination point selecting the authoritative #12 local exposure
+   * window for this object point.
+   */
+  destinationPointNative:
+    RasterPoint;
+}
+```
+
+## CaptureExtendedObjectPointTrajectory
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureExtendedObjectPointTrajectory {
+  pointId: string;
+  destinationPointNative:
+    RasterPoint;
+  referencePositionCameraM:
+    Vector3;
+  referenceImagePointMm: {
+    x: number;
+    y: number;
+  };
+  localExposureWindow: {
+    startSecondsFromCaptureReference:
+      number;
+    endSecondsFromCaptureReference:
+      number;
+    durationSeconds: number;
+  };
+  nodes:
+    readonly CaptureExtendedObjectTemporalNode[];
+}
+```
+
+## CaptureExtendedObjectTemporalNode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureExtendedObjectTemporalNode
+  extends ExtendedObjectProjectionNode {
+  localExposurePhase: number;
+  normalizedTimeWeight: number;
+  timeMeasureSeconds: number;
+}
+```
+
+## CaptureExtendedObjectTemporalProjection
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureExtendedObjectTemporalProjection {
+  objectId: string;
+  timeReference:
+    "first-opening-boundary-phase";
+  timingProfileIdentity: {
+    profileId: string;
+    profileVersion: string;
+    captureModeId: string;
+  };
+  projectionDistanceMm: number;
+  temporalSampleCount: number;
+  objectTranslationVelocityMps:
+    Vector3;
+  cameraTranslationVelocityMps:
+    Vector3;
+  relativeTranslationVelocityMps:
+    Vector3;
+  rigidTranslationOnly: true;
+  pointTrajectories:
+    readonly CaptureExtendedObjectPointTrajectory[];
+  planarMagnificationDiagnosticAvailable:
+    boolean;
+  metricSceneDepthRequired: true;
+  oneGlobalHomographyAuthorized:
+    false;
+  oneGlobalScaleAuthorizedForArbitrary3dGeometry:
+    false;
+  cameraRotationComposed: false;
+  visibilityOcclusionModeled: false;
+  deformationModeled: false;
+  accelerationModeled: false;
+  blurKernelCalculated: false;
+  radianceIntegrated: false;
+  sensorReadoutTimingUsedAsExposureTiming:
+    false;
+  timeVaryingDefocusMayBeRequired:
+    boolean;
+}
+```
+
+## ExtendedObjectFrontoparallelPlaneDeclaration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExtendedObjectFrontoparallelPlaneDeclaration {
+  kind: "fronto-parallel-planar-patch";
+  referenceDepthM: number;
+}
+```
+
+## ExtendedObjectMetricPoint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExtendedObjectMetricPoint {
+  pointId: string;
+  /**
+   * Metric camera-space point at the common reference phase.
+   *
+   * +X right, +Y up, +Z forward/away from the camera.
+   */
+  positionCameraM: Vector3;
+}
+```
+
+## ExtendedObjectPlanarMagnificationDiagnostic
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExtendedObjectPlanarMagnificationDiagnostic {
+  geometry:
+    "declared-fronto-parallel-planar-patch";
+  referenceDepthM: number;
+  uniformScaleAuthorizedWithinDeclaredPatch:
+    true;
+  scaleByTime:
+    readonly {
+      sampleIndex: number;
+      timeSecondsFromReference:
+        number;
+      scaleFromReference: number;
+    }[];
+  lateralRigidTranslationDoesNotChangePatchScale:
+    true;
+  notAuthorizedForArbitrary3dGeometry:
+    true;
+}
+```
+
+## ExtendedObjectPointProjectionTrajectory
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExtendedObjectPointProjectionTrajectory {
+  pointId: string;
+  referencePositionCameraM:
+    Vector3;
+  referenceImagePointMm: {
+    x: number;
+    y: number;
+  };
+  nodes:
+    readonly ExtendedObjectProjectionNode[];
+}
+```
+
+## ExtendedObjectProjectionNode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExtendedObjectProjectionNode {
+  sampleIndex: number;
+  timeSecondsFromReference: number;
+  relativePositionCameraM:
+    Vector3;
+  mappedImagePointMm: {
+    x: number;
+    y: number;
+  };
+  deltaFromReferenceImagePlaneMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+  depthM: number;
+  planarMagnificationScaleFromReference:
+    number | null;
+}
+```
+
+## ExtendedObjectProjectionTrajectory
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExtendedObjectProjectionTrajectory {
+  objectId: string;
+  timeReference:
+    "caller-declared-common-reference-phase";
+  projectionDistanceMm: number;
+  objectTranslationVelocityMps:
+    Vector3;
+  cameraTranslationVelocityMps:
+    Vector3;
+  relativeTranslationVelocityMps:
+    Vector3;
+  rigidTranslationOnly: true;
+  pointTrajectories:
+    readonly ExtendedObjectPointProjectionTrajectory[];
+  planarMagnificationDiagnostic:
+    ExtendedObjectPlanarMagnificationDiagnostic | null;
+  metricSceneDepthRequired: true;
+  oneGlobalHomographyAuthorized:
+    false;
+  oneGlobalScaleAuthorizedForArbitrary3dGeometry:
+    false;
+  cameraRotationComposed: false;
+  visibilityOcclusionModeled: false;
+  deformationModeled: false;
+  accelerationModeled: false;
+  blurKernelCalculated: false;
+  radianceIntegrated: false;
+  timeVaryingDefocusMayBeRequired:
+    boolean;
+}
+```

package/docs/api/motion-projected-motion.md

@@ -0,0 +1,60 @@
+# motion/projected-motion.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.
+
+## calculateProjectedMotionBlur
+
+Calculates sensor-plane motion during an exposure using ideal rectilinear
+projection and constant linear object velocity.
+
+Without focusDistanceM, nominal focal length is the backwards-compatible
+pinhole projection distance. With focusDistanceM, the selected thin-lens
+sensor-plane image distance is used.
+
+The calculation projects the object's shutter-open and shutter-close
+positions onto the image plane and measures the displacement between them.
+It therefore handles lateral and depth-direction motion without relying on a
+generic "subject speed" category.
+
+```ts
+export function calculateProjectedMotionBlur(
+  input: CalculateProjectedMotionBlurInput
+): CalculationResult<ProjectedMotionBlur>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateProjectedMotionBlurInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateProjectedMotionBlurInput {
+  /** Lens focal length in millimetres. */
+  focalLengthMm: number;
+  /** Shutter-open duration in seconds. */
+  shutterSeconds: number;
+  /** Object position at shutter open, in camera-relative metres. +z is away from the camera. */
+  positionM: Vector3;
+  /** Constant world-space velocity during the exposure, in metres per second. */
+  velocityMps: Vector3;
+  /** Optional focus distance in metres for focus-aware sensor-plane projection. */
+  focusDistanceM?: number;
+  /** Optional sensor pixel pitch in micrometres for pixel-domain blur reporting. */
+  pixelPitchMicrometers?: number;
+}
+```
+
+## ProjectedMotionBlur
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ProjectedMotionBlur {
+  deltaXMm: number;
+  deltaYMm: number;
+  distanceMm: number;
+  projectionDistanceMm: number;
+  distancePixels?: number;
+}
+```

package/docs/api/optics-aperture.md

@@ -0,0 +1,69 @@
+# optics/aperture.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.
+
+## ApertureVertex
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ApertureVertex {
+  x: number;
+  y: number;
+}
+```
+
+## calculateIdealApertureGeometry
+
+Calculates ideal regular-polygon aperture geometry and the corresponding
+straight-edge diffraction-ray directions.
+
+This models only geometry/symmetry. It does not calculate diffraction
+intensity, wavelength-dependent star length, blade curvature, lens
+aberrations, coatings, or sensor blooming.
+
+```ts
+export function calculateIdealApertureGeometry(
+  input: CalculateIdealApertureInput
+): CalculationResult<IdealApertureGeometry>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateIdealApertureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateIdealApertureInput {
+  /** Number of straight diaphragm blades/sides. Must be from 3 through 1024. */
+  bladeCount: number;
+  /**
+   * Rotation of the first blade edge in degrees, measured counter-clockwise
+   * in image coordinates before the diffraction-normal offset is applied.
+   */
+  firstBladeEdgeAngleDegrees?: number;
+}
+```
+
+## IdealApertureGeometry
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IdealApertureGeometry {
+  bladeCount: number;
+  /** Number of diffraction ray directions for the ideal straight-edged polygon. */
+  sunstarRayCount: number;
+  /**
+   * Diffraction-ray directions in degrees, normalized to [0, 360).
+   *
+   * Each ray is perpendicular to a blade edge. Parallel opposite edges overlap
+   * for even blade counts; odd blade counts therefore produce twice as many
+   * visible ray directions.
+   */
+  sunstarRayAnglesDegrees: readonly number[];
+  /** Unit-circumradius regular-polygon vertices. */
+  normalizedVertices: readonly ApertureVertex[];
+}
+```

package/docs/api/optics-circle-of-confusion.md

@@ -0,0 +1,46 @@
+# optics/circle-of-confusion.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.
+
+## EquivalentViewingCircleOfConfusion
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EquivalentViewingCircleOfConfusion {
+  circleOfConfusionMm: number;
+  sensorDiagonalMm: number;
+  referenceSensorDiagonalMm: number;
+  scaleFactor: number;
+}
+```
+
+## estimateEquivalentViewingCircleOfConfusion
+
+Estimates a circle-of-confusion criterion for equivalent final viewing by
+scaling a caller-supplied reference criterion in proportion to sensor
+diagonal.
+
+This is a viewing/acceptability convention, not a physical blur threshold.
+
+```ts
+export function estimateEquivalentViewingCircleOfConfusion(
+  input: EstimateEquivalentViewingCircleOfConfusionInput
+): CalculationResult<EquivalentViewingCircleOfConfusion>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## EstimateEquivalentViewingCircleOfConfusionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EstimateEquivalentViewingCircleOfConfusionInput {
+  sensorWidthMm: number;
+  sensorHeightMm: number;
+  referenceSensorWidthMm: number;
+  referenceSensorHeightMm: number;
+  referenceCircleOfConfusionMm: number;
+}
+```

package/docs/api/optics-complex-pupil-psf.md

@@ -0,0 +1,193 @@
+# optics/complex-pupil-psf.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.
+
+## calculateLensComplexPupilPsf
+
+Evaluate a declared complex pupil with explicit amplitude/phase and sampling support; normalize PSF
+shape and retain pupil throughput as a separate quantity.
+
+Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
+shape is normalized separately from pupil throughput; coherent phase, pupil energy and
+spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
+owned or reusable-data provenance.
+
+```ts
+export function calculateLensComplexPupilPsf(
+  input:
+    CalculateLensComplexPupilPsfInput
+): CalculationResult<LensComplexPupilPsf>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateLensComplexPupilPsfInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateLensComplexPupilPsfInput {
+  profile:
+    LensComplexPupilProfile;
+}
+```
+
+## LENS_COMPLEX_PUPIL_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+LENS_COMPLEX_PUPIL_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## LensComplexPupilGrid
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensComplexPupilGrid {
+  widthSamples: number;
+  heightSamples: number;
+  pupilSamplePitchMmX: number;
+  pupilSamplePitchMmY: number;
+  centerSampleX: number;
+  centerSampleY: number;
+  relativeAmplitude:
+    readonly number[];
+  opticalPathDifferenceMicrometers:
+    readonly number[];
+}
+```
+
+## LensComplexPupilProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensComplexPupilProfile {
+  schemaVersion:
+    typeof LENS_COMPLEX_PUPIL_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  scientificStatus:
+    LensPsfScientificStatus;
+  opticalDomain:
+    "lens-primary-optical-path-only";
+  representation:
+    "complex-pupil-amplitude-plus-opd";
+  pupilCoordinateSystem:
+    "pupil-plane-metric-aligned-to-image-plane";
+  imageFieldAxes:
+    "+X right, +Y up";
+  amplitudeMeaning:
+    "relative-complex-pupil-amplitude-shape";
+  wavefrontMeaning:
+    "optical-path-difference-micrometers";
+  throughputOwnership:
+    "separate-relative-pupil-throughput-factor";
+  kernelEnergyNormalization:
+    "unit-energy-shape";
+  propagationModel:
+    "scalar-fraunhofer-discrete-reference";
+  context: {
+    focalLengthMm: number;
+    focus: FocusPlane;
+    apertureFNumber: number;
+    fieldPointMm: {
+      x: number;
+      y: number;
+    };
+    wavelengthNm: number;
+    signedDefocusImagePlaneMicrometers:
+      number;
+  };
+  responseIncludes: {
+    diffraction: true;
+    aberration: boolean;
+    defocus: boolean;
+    pupilClippingShape:
+      boolean;
+  };
+  relativePupilThroughputFactor:
+    number;
+  grid: LensComplexPupilGrid;
+  sensorOpticalStackIncluded:
+    false;
+  sensorSamplingIncluded:
+    false;
+  reconstructionIncluded:
+    false;
+  strayLightIncluded: false;
+  evidence:
+    readonly EvidenceProvenance[];
+  uncertainty:
+    LensPsfUncertainty;
+  limitations: readonly string[];
+}
+```
+
+## LensComplexPupilPsf
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensComplexPupilPsf {
+  profileId: string;
+  profileVersion: string;
+  scientificStatus:
+    LensPsfScientificStatus;
+  context:
+    LensComplexPupilProfile["context"];
+  kernel: LensPsfKernel;
+  relativePupilThroughputFactor:
+    number;
+  throughputOwnership:
+    "separate-relative-pupil-throughput-factor";
+  diffractionAndAberrationJointlyEvaluated:
+    true;
+  pupilClippingShapeIncluded:
+    boolean;
+  pupilClippingThroughputAppliedToKernel:
+    false;
+  scalarFraunhoferReference:
+    true;
+  full2dOrientationPreserved:
+    true;
+  geometricDistortionModified:
+    false;
+  lateralChromaticPositionShiftApplied:
+    false;
+  sensorOpticalStackIncluded:
+    false;
+  sensorSamplingIncluded: false;
+  reconstructionIncluded: false;
+  strayLightIncluded: false;
+  scalarSharpnessScoreProduced:
+    false;
+  componentEvidence: {
+    pupilProfile:
+      readonly EvidenceProvenance[];
+  };
+  uncertainty:
+    LensPsfUncertainty;
+}
+```
+
+## parseLensComplexPupilProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
+shape is normalized separately from pupil throughput; coherent phase, pupil energy and
+spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
+owned or reusable-data provenance.
+
+```ts
+export function parseLensComplexPupilProfile(
+  value: unknown
+): LensComplexPupilProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.