@photivra/engine 0.5.1 → 1.0.0

package/docs/api/motion-capture-rotation-inverse-mapping.md

@@ -0,0 +1,128 @@
+# motion/capture-rotation-inverse-mapping.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.
+
+## calculateCaptureRotationInverseMappings
+
+Calculates an instantaneous inverse capture-scan mapping for stationary
+world rays under pure camera rotation.
+
+The destination native sensor location is authoritative for local exposure
+timing. At an explicit phase within that local window, the captured
+image-plane ray is analytically mapped back to the reference image plane at
+the first opening-boundary phase.
+
+No fixed-point/iterative solve is used because pure rotation under the
+existing constant-axis model has an analytic inverse once destination
+location and local capture time are known.
+
+This function is not a finite-exposure renderer and does not integrate blur.
+Sensor data-readout timing is deliberately absent; exposure boundaries are
+the only timing source.
+
+```ts
+export function calculateCaptureRotationInverseMappings(
+  input: CalculateCaptureRotationInverseMappingsInput
+): CalculationResult<CaptureRotationInverseMappings>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCaptureRotationInverseMappingsInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCaptureRotationInverseMappingsInput
+  extends CalculateCaptureExposureWindowsInput {
+  imagingArea: SensorImagingArea;
+  focalLengthMm: number;
+  focusDistanceM?: number;
+  angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
+  /**
+   * Fraction of each point's local exposure interval at which the
+   * instantaneous mapping is evaluated.
+   *
+   * 0 = local exposure start, 0.5 = local midpoint, 1 = local exposure end.
+   * A phase is required because finite exposure has no single sharp geometry.
+   */
+  localExposurePhase: number;
+  /**
+   * Physical capture orientation used only to rotate the reported native
+   * inverse sample-displacement vector into oriented-capture coordinates.
+   * It does not alter the native exposure schedule.
+   */
+  orientation: CaptureOrientation;
+  samplePointsNative: readonly RasterPoint[];
+}
+```
+
+## CaptureRotationInverseMappings
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureRotationInverseMappings {
+  timeReference: "first-opening-boundary-phase";
+  referenceTimeSecondsFromCaptureReference: 0;
+  mappingMeaning:
+    "instantaneous-destination-to-exposure-start-reference-ray";
+  orientation: CaptureOrientation;
+  localExposurePhase: number;
+  imagingArea: SensorImagingArea;
+  activeCaptureRect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  samples: readonly CaptureRotationInverseMappingSample[];
+  componentProvenance: {
+    exposureWindows: CalculationProvenance;
+    sensorGeometry: CalculationProvenance;
+    inverseCameraRotation: CalculationProvenance;
+  };
+}
+```
+
+## CaptureRotationInverseMappingSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureRotationInverseMappingSample {
+  destinationPointNative: RasterPoint;
+  destinationImagePointMm: ImagePlanePointMm;
+  localExposureWindow: {
+    startSecondsFromCaptureReference: number;
+    endSecondsFromCaptureReference: number;
+    durationSeconds: number;
+  };
+  localExposurePhase: number;
+  captureTimeSecondsFromReference: number;
+  /**
+   * Same stationary world ray expressed in the exposure-start reference image
+   * plane. This may lie outside the active capture; it is intentionally not
+   * clamped.
+   */
+  referenceImagePointMm: ImagePlanePointMm;
+  inverseDisplacementImagePlaneMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+  /**
+   * Reference-minus-destination displacement in continuous native effective
+   * raster-sample units (+X right, +Y down).
+   */
+  inverseDisplacementNativeSamples: RasterVector & {
+    distance: number;
+  };
+  /**
+   * The same displacement after physical capture orientation.
+   */
+  inverseDisplacementOrientedSamples: RasterVector & {
+    distance: number;
+  };
+}
+```

package/docs/api/motion-capture-rotation-temporal-quadrature.md

@@ -0,0 +1,127 @@
+# motion/capture-rotation-temporal-quadrature.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.
+
+## calculateCaptureRotationTemporalQuadrature
+
+Builds deterministic temporal quadrature nodes for pure-camera-rotation
+capture geometry over each destination point's local exposure interval.
+
+The first model uses an equal-width midpoint rule. Every node reuses
+calculateCaptureRotationInverseMappings(), so the instantaneous geometry has
+one authoritative implementation.
+
+No radiance is evaluated here. normalizedTimeWeight is suitable for a
+downstream time-average under a uniform temporal-response assumption, while
+timeMeasureSeconds is the local dt measure for a downstream time integral.
+Neither weight includes shutter transmission, scene flicker, sensor
+response, radiometric calibration or any other throughput term.
+
+The function intentionally reports no numerical integration error estimate:
+geometry alone cannot determine the error in a scene-radiance integral.
+Downstream renderers may compare increasing temporal sample counts in their
+own radiance domain when convergence evidence is required.
+
+```ts
+export function calculateCaptureRotationTemporalQuadrature(
+  input: CalculateCaptureRotationTemporalQuadratureInput
+): CalculationResult<CaptureRotationTemporalQuadrature>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCaptureRotationTemporalQuadratureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCaptureRotationTemporalQuadratureInput
+  extends Omit<
+    CalculateCaptureRotationInverseMappingsInput,
+    "localExposurePhase"
+  > {
+  /**
+   * Number of deterministic temporal quadrature nodes per local exposure
+   * interval. Nodes use the uniform midpoint rule.
+   */
+  temporalSampleCount: number;
+}
+```
+
+## CaptureRotationTemporalQuadrature
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureRotationTemporalQuadrature {
+  timeReference: "first-opening-boundary-phase";
+  quadratureScheme: "uniform-midpoint";
+  temporalResponseModel: "uniform-over-local-exposure";
+  temporalSampleCount: number;
+  /**
+   * The quadrature returns geometry and temporal measure only. It does not
+   * integrate radiance or produce a blur kernel.
+   */
+  outputMeaning: "temporal-geometry-quadrature-nodes";
+  points: readonly CaptureRotationTemporalQuadraturePoint[];
+  componentProvenance: {
+    instantaneousInverseMapping: CalculationProvenance;
+  };
+}
+```
+
+## CaptureRotationTemporalQuadratureNode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureRotationTemporalQuadratureNode {
+  temporalSampleIndex: number;
+  /**
+   * Normalized phase in the local exposure interval, strictly inside (0, 1).
+   */
+  localExposurePhase: number;
+  captureTimeSecondsFromReference: number;
+  /**
+   * Dimensionless weight for approximating the time-average of a downstream
+   * quantity under a uniform temporal-response assumption.
+   */
+  normalizedTimeWeight: number;
+  /**
+   * Seconds-valued quadrature measure for approximating a time integral.
+   *
+   * This is temporal measure only. It is not shutter transmission, radiometric
+   * throughput, photon count, sensor response, or scene radiance.
+   */
+  timeMeasureSeconds: number;
+  referenceImagePointMm: ImagePlanePointMm;
+  inverseDisplacementImagePlaneMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+  inverseDisplacementNativeSamples: RasterVector & {
+    distance: number;
+  };
+  inverseDisplacementOrientedSamples: RasterVector & {
+    distance: number;
+  };
+}
+```
+
+## CaptureRotationTemporalQuadraturePoint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureRotationTemporalQuadraturePoint {
+  destinationPointNative: RasterPoint;
+  destinationImagePointMm: ImagePlanePointMm;
+  localExposureWindow: {
+    startSecondsFromCaptureReference: number;
+    endSecondsFromCaptureReference: number;
+    durationSeconds: number;
+  };
+  nodes: readonly CaptureRotationTemporalQuadratureNode[];
+}
+```

package/docs/api/motion-capture-rotation-trajectory.md

@@ -0,0 +1,132 @@
+# motion/capture-rotation-trajectory.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.
+
+## calculateCaptureRotationTrajectories
+
+Evaluates pure-camera-rotation trajectories for stationary reference rays
+over each point's local exposure window.
+
+This is a temporal-geometry bridge, not a finished rolling-shutter image
+mapping. The native sample point defines where a stationary world ray would
+land in the reference global-shutter image at the first opening-boundary
+phase. The existing camera-rotation model is then evaluated at that point's
+local exposure start and end.
+
+Sensor data-readout timing is intentionally absent. A camera/mode-specific
+relationship between sensor readout and exposure boundaries requires a
+separate explicit contract; this function never assumes one.
+
+A later renderer-facing rolling-shutter warp must solve the image mapping
+consistently with capture-location-dependent time and integrate over the
+local exposure interval. The endpoint chord returned here must not be treated
+as a blur kernel or as an inverse destination-to-source sampling map.
+
+```ts
+export function calculateCaptureRotationTrajectories(
+  input: CalculateCaptureRotationTrajectoriesInput
+): CalculationResult<CaptureRotationTrajectories>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCaptureRotationTrajectoriesInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCaptureRotationTrajectoriesInput
+  extends CalculateCaptureExposureWindowsInput {
+  /**
+   * Physical photosensitive imaging area associated with nativeRaster.
+   */
+  imagingArea: SensorImagingArea;
+  /** Physical focal length in millimetres. */
+  focalLengthMm: number;
+  /** Optional focus distance in metres for focus-aware projection distance. */
+  focusDistanceM?: number;
+  /**
+   * Constant physical camera angular velocity resolved in camera axes at the
+   * first opening-boundary phase.
+   */
+  angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
+  /**
+   * Native points whose stationary-reference-ray trajectories should be
+   * evaluated. Required and non-empty for this trajectory API.
+   */
+  samplePointsNative: readonly RasterPoint[];
+}
+```
+
+## CaptureRotationTrajectories
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureRotationTrajectories {
+  timeReference: "first-opening-boundary-phase";
+  trajectoryMeaning: "forward-stationary-reference-ray";
+  imagingArea: SensorImagingArea;
+  activeCaptureRect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+  samples: readonly CaptureRotationTrajectorySample[];
+  componentProvenance: {
+    exposureWindows: CalculationProvenance;
+    cameraRotation: CalculationProvenance;
+  };
+}
+```
+
+## CaptureRotationTrajectoryEndpoint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureRotationTrajectoryEndpoint {
+  timeSecondsFromCaptureReference: number;
+  mappedImagePointMm: ImagePlanePointMm;
+  deltaFromReferenceMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+}
+```
+
+## CaptureRotationTrajectorySample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureRotationTrajectorySample {
+  pointNative: RasterPoint;
+  /**
+   * Image-plane position of the stationary world ray at the capture reference
+   * time (the first opening-boundary phase).
+   */
+  referenceImagePointMm: ImagePlanePointMm;
+  localExposureWindow: {
+    startSecondsFromCaptureReference: number;
+    endSecondsFromCaptureReference: number;
+    durationSeconds: number;
+    openingNormalizedScanPosition: number | null;
+    closingNormalizedScanPosition: number | null;
+  };
+  atLocalExposureStart: CaptureRotationTrajectoryEndpoint;
+  atLocalExposureEnd: CaptureRotationTrajectoryEndpoint;
+  /**
+   * Chord between the two trajectory endpoints.
+   *
+   * This is not a blur kernel, integrated exposure, or rolling-shutter warp.
+   */
+  localExposureTrajectoryEndpointDeltaMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+}
+```

package/docs/api/motion-capture-translation-parallax-temporal-quadrature.md

@@ -0,0 +1,171 @@
+# motion/capture-translation-parallax-temporal-quadrature.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.
+
+## calculateCaptureTranslationParallaxTemporalQuadrature
+
+Evaluates depth-dependent translational parallax at deterministic midpoint
+nodes over each scene point's authoritative local exposure window.
+
+The model is deliberately per point. Camera translation and optional subject
+translation coexist through relative linear motion; neither is redefined as
+the other. Camera rotation and visibility/occlusion remain separate models.
+
+```ts
+export function calculateCaptureTranslationParallaxTemporalQuadrature(
+  input:
+    CalculateCaptureTranslationParallaxTemporalQuadratureInput
+): CalculationResult<CaptureTranslationParallaxTemporalQuadrature>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCaptureTranslationParallaxTemporalQuadratureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCaptureTranslationParallaxTemporalQuadratureInput {
+  timing:
+    ResolvedCaptureModeTiming;
+  imagingArea:
+    SensorImagingArea;
+  focalLengthMm: number;
+  focusDistanceM?: number;
+  orientation:
+    CaptureOrientation;
+  /**
+   * Constant physical camera-center translation in camera axes at the capture
+   * reference phase. Rotation is intentionally separate.
+   */
+  cameraTranslationVelocityMps:
+    Vector3;
+  temporalSampleCount: number;
+  sceneSamples:
+    readonly CaptureTranslationParallaxSceneSample[];
+}
+```
+
+## CaptureTranslationParallaxSceneSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureTranslationParallaxSceneSample {
+  sampleId: string;
+  /**
+   * Native destination point whose authoritative local exposure window applies
+   * to this scene sample.
+   */
+  destinationPointNative:
+    RasterPoint;
+  /**
+   * Metric point position in the camera axes at the first-opening-boundary
+   * phase. +X right, +Y up, +Z forward/away from the camera.
+   */
+  positionCameraM: Vector3;
+  /**
+   * Optional constant subject/world-point velocity in the same initial camera
+   * axes. Omitted means stationary world point.
+   */
+  subjectVelocityMps?: Vector3;
+}
+```
+
+## CaptureTranslationParallaxTemporalNode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureTranslationParallaxTemporalNode {
+  temporalSampleIndex: number;
+  localExposurePhase: number;
+  captureTimeSecondsFromReference:
+    number;
+  normalizedTimeWeight: number;
+  timeMeasureSeconds: number;
+  relativePositionCameraM:
+    Vector3;
+  mappedImagePointMm: {
+    x: number;
+    y: number;
+  };
+  deltaFromReferenceImagePlaneMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+  deltaNativeSamples: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+  deltaOrientedSamples: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+}
+```
+
+## CaptureTranslationParallaxTemporalQuadrature
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureTranslationParallaxTemporalQuadrature {
+  timeReference:
+    "first-opening-boundary-phase";
+  timingProfileIdentity: {
+    profileId: string;
+    profileVersion: string;
+    captureModeId: string;
+  };
+  orientation:
+    CaptureOrientation;
+  projectionDistanceMm: number;
+  temporalSampleCount: number;
+  cameraTranslationVelocityMps:
+    Vector3;
+  samples:
+    readonly CaptureTranslationParallaxTemporalSample[];
+  geometryModel:
+    "metric-depth-dependent-constant-linear-translation";
+  relativeMotionComposition:
+    "subject-minus-camera-translation";
+  metricSceneDepthRequired: true;
+  oneGlobalHomographyAuthorized: false;
+  cameraRotationComposed: false;
+  visibilityOcclusionModeled: false;
+  sensorReadoutTimingUsedAsExposureTiming:
+    false;
+}
+```
+
+## CaptureTranslationParallaxTemporalSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureTranslationParallaxTemporalSample {
+  sampleId: string;
+  destinationPointNative:
+    RasterPoint;
+  referencePositionCameraM:
+    Vector3;
+  subjectVelocityMps: Vector3;
+  localExposureWindow: {
+    startSecondsFromCaptureReference:
+      number;
+    endSecondsFromCaptureReference:
+      number;
+    durationSeconds: number;
+  };
+  referenceImagePointMm: {
+    x: number;
+    y: number;
+  };
+  nodes:
+    readonly CaptureTranslationParallaxTemporalNode[];
+}
+```