@photivra/engine 1.5.0 → 2.0.0

package/dist/motion/capture-rotation-temporal-quadrature.d.ts

@@ -1,17 +1,22 @@
 /**
- * Module boundary and integration notes.
- * 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.
- * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Time samples (temporal quadrature nodes) across each destination point's local exposure, for a
+ * rotating camera. The samples are deterministic.
+ *
+ * The first model uses an equal-width midpoint rule. Every node calls
+ * calculateCaptureRotationInverseMappings(), so the instantaneous geometry has a single
+ * implementation.
+ *
+ * No radiance is evaluated here. Two weights are returned:
+ * - normalizedTimeWeight: for a time average, assuming a uniform response over time.
+ * - timeMeasureSeconds: the local dt, for a time integral.
+ * Neither weight includes shutter transmission, scene flicker, sensor response, radiometric
+ * calibration or any other throughput term.
+ *
+ * No numerical integration error estimate is reported, on purpose. Geometry alone cannot tell the
+ * error in a scene-radiance integral. A renderer that needs evidence of convergence can compare
+ * results for increasing sample counts in its own radiance domain.
+ * @see docs/MOTION_AND_SIGNAL.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationProvenance, type CalculationResult } from "../core/calculation-result.js";
 import type { RasterPoint, RasterVector } from "../output/capture-geometry.js";
@@ -19,8 +24,8 @@ import type { ImagePlanePointMm } from "./camera-rotation.js";
 import { type CalculateCaptureRotationInverseMappingsInput } from "./capture-rotation-inverse-mapping.js";
 export interface CalculateCaptureRotationTemporalQuadratureInput extends Omit<CalculateCaptureRotationInverseMappingsInput, "localExposurePhase"> {
     /**
-     * Number of deterministic temporal quadrature nodes per local exposure
-     * interval. Nodes use the uniform midpoint rule.
+     * Number of time samples (quadrature nodes) per local exposure interval.
+     * Nodes follow the uniform midpoint rule.
      */
     temporalSampleCount: number;
 }
@@ -32,15 +37,15 @@ export interface CaptureRotationTemporalQuadratureNode {
     localExposurePhase: number;
     captureTimeSecondsFromReference: number;
     /**
-     * Dimensionless weight for approximating the time-average of a downstream
-     * quantity under a uniform temporal-response assumption.
+     * Dimensionless weight for approximating the time average of a quantity,
+     * assuming a uniform response over time.
      */
     normalizedTimeWeight: number;
     /**
-     * Seconds-valued quadrature measure for approximating a time integral.
+     * Quadrature measure in seconds, for approximating a time integral.
      *
-     * This is temporal measure only. It is not shutter transmission, radiometric
-     * throughput, photon count, sensor response, or scene radiance.
+     * This is a measure of time only. It is not shutter transmission,
+     * radiometric throughput, photon count, sensor response or scene radiance.
      */
     timeMeasureSeconds: number;
     referenceImagePointMm: ImagePlanePointMm;
@@ -82,23 +87,22 @@ export interface CaptureRotationTemporalQuadrature {
     };
 }
 /**
- * Builds deterministic temporal quadrature nodes for pure-camera-rotation
- * capture geometry over each destination point's local exposure interval.
+ * Builds deterministic time samples (temporal quadrature nodes) for a
+ * rotating camera, across 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.
+ * The first model uses an equal-width midpoint rule. Every node calls
+ * calculateCaptureRotationInverseMappings(), so the instantaneous geometry
+ * has a single 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.
+ * No radiance is evaluated here. normalizedTimeWeight is for a time average,
+ * assuming a uniform response over time. timeMeasureSeconds is the local dt
+ * for a 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.
+ * No numerical integration error estimate is reported, on purpose. Geometry
+ * alone cannot tell the error in a scene-radiance integral. A renderer that
+ * needs evidence of convergence can compare results for increasing sample
+ * counts in its own radiance domain.
  */
 export declare function calculateCaptureRotationTemporalQuadrature(input: CalculateCaptureRotationTemporalQuadratureInput): CalculationResult<CaptureRotationTemporalQuadrature>;
-//# sourceMappingURL=capture-rotation-temporal-quadrature.d.ts.map

package/dist/motion/capture-rotation-temporal-quadrature.js

@@ -1,50 +1,59 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * 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.
- * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Time samples (temporal quadrature nodes) across each destination point's local exposure, for a
+ * rotating camera. The samples are deterministic.
+ *
+ * The first model uses an equal-width midpoint rule. Every node calls
+ * calculateCaptureRotationInverseMappings(), so the instantaneous geometry has a single
+ * implementation.
+ *
+ * No radiance is evaluated here. Two weights are returned:
+ * - normalizedTimeWeight: for a time average, assuming a uniform response over time.
+ * - timeMeasureSeconds: the local dt, for a time integral.
+ * Neither weight includes shutter transmission, scene flicker, sensor response, radiometric
+ * calibration or any other throughput term.
+ *
+ * No numerical integration error estimate is reported, on purpose. Geometry alone cannot tell the
+ * error in a scene-radiance integral. A renderer that needs evidence of convergence can compare
+ * results for increasing sample counts in its own radiance domain.
+ * @see docs/MOTION_AND_SIGNAL.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { approximationResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError, requirePositiveInteger } from "../core/validation.js";
 import { calculateCaptureRotationInverseMappings } from "./capture-rotation-inverse-mapping.js";
+import { requireInputKeys, requireInputObject } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 function midpointPhase(index, sampleCount) {
     return (index + 0.5) / sampleCount;
 }
 /**
- * Builds deterministic temporal quadrature nodes for pure-camera-rotation
- * capture geometry over each destination point's local exposure interval.
+ * Builds deterministic time samples (temporal quadrature nodes) for a
+ * rotating camera, across 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.
+ * The first model uses an equal-width midpoint rule. Every node calls
+ * calculateCaptureRotationInverseMappings(), so the instantaneous geometry
+ * has a single 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.
+ * No radiance is evaluated here. normalizedTimeWeight is for a time average,
+ * assuming a uniform response over time. timeMeasureSeconds is the local dt
+ * for a 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.
+ * No numerical integration error estimate is reported, on purpose. Geometry
+ * alone cannot tell the error in a scene-radiance integral. A renderer that
+ * needs evidence of convergence can compare results for increasing sample
+ * counts in its own radiance domain.
  */
 export function calculateCaptureRotationTemporalQuadrature(input) {
+    requireInputKeys(input, "calculateCaptureRotationTemporalQuadrature", ["temporalSampleCount", "imagingArea", "focalLengthMm", "focusDistanceM", "angularVelocityRadPerSec", "orientation", "samplePointsNative", "nativeRaster", "activeCaptureRect", "shutterMechanism", "nominalExposureDurationSeconds", "opening", "closing"]);
     requirePositiveInteger("temporalSampleCount", input.temporalSampleCount);
     if (!Array.isArray(input.samplePointsNative) ||
         input.samplePointsNative.length === 0) {
-        throw new InvalidScientificInputError("samplePointsNative must be a non-empty array.");
+        throw new InvalidConfigurationError("samplePointsNative must be a non-empty array.");
     }
+    input.samplePointsNative.forEach((point, index) => requireInputObject(point, "samplePointsNative[" + index + "]"));
     const totalNodeCount = input.temporalSampleCount * input.samplePointsNative.length;
     if (!Number.isSafeInteger(totalNodeCount)) {
         throw new InvalidScientificInputError("temporalSampleCount × samplePointsNative.length must be a safe integer.");

package/dist/motion/capture-rotation-temporal-quadrature.js.map

@@ -1 +1 @@
-{"version":3,"file":"capture-rotation-temporal-quadrature.js","sourceRoot":"","sources":["../../src/motion/capture-rotation-temporal-quadrature.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"capture-rotation-temporal-quadrature.js","sourceRoot":"","sources":["../../src/motion/capture-rotation-temporal-quadrature.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Time samples (temporal quadrature nodes) across each destination point's local exposure, for a\n * rotating camera. The samples are deterministic.\n *\n * The first model uses an equal-width midpoint rule. Every node calls\n * calculateCaptureRotationInverseMappings(), so the instantaneous geometry has a single\n * implementation.\n *\n * No radiance is evaluated here. Two weights are returned:\n * - normalizedTimeWeight: for a time average, assuming a uniform response over time.\n * - timeMeasureSeconds: the local dt, for a time integral.\n * Neither weight includes shutter transmission, scene flicker, sensor response, radiometric\n * calibration or any other throughput term.\n *\n * No numerical integration error estimate is reported, on purpose. Geometry alone cannot tell the\n * error in a scene-radiance integral. A renderer that needs evidence of convergence can compare\n * results for increasing sample counts in its own radiance domain.\n * @see docs/MOTION_AND_SIGNAL.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationProvenance,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveInteger\n} from \"../core/validation.js\";\nimport type { RasterPoint, RasterVector } from \"../output/capture-geometry.js\";\nimport type { ImagePlanePointMm } from \"./camera-rotation.js\";\nimport {\n  calculateCaptureRotationInverseMappings,\n  type CalculateCaptureRotationInverseMappingsInput\n} from \"./capture-rotation-inverse-mapping.js\";\nimport { requireInputKeys, requireInputObject } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport interface CalculateCaptureRotationTemporalQuadratureInput\n  extends Omit<\n    CalculateCaptureRotationInverseMappingsInput,\n    \"localExposurePhase\"\n  > {\n  /**\n   * Number of time samples (quadrature nodes) per local exposure interval.\n   * Nodes follow the uniform midpoint rule.\n   */\n  temporalSampleCount: number;\n}\n\nexport interface CaptureRotationTemporalQuadratureNode {\n  temporalSampleIndex: number;\n  /**\n   * Normalized phase in the local exposure interval, strictly inside (0, 1).\n   */\n  localExposurePhase: number;\n  captureTimeSecondsFromReference: number;\n  /**\n   * Dimensionless weight for approximating the time average of a quantity,\n   * assuming a uniform response over time.\n   */\n  normalizedTimeWeight: number;\n  /**\n   * Quadrature measure in seconds, for approximating a time integral.\n   *\n   * This is a measure of time only. It is not shutter transmission,\n   * radiometric throughput, photon count, sensor response or scene radiance.\n   */\n  timeMeasureSeconds: number;\n  referenceImagePointMm: ImagePlanePointMm;\n  inverseDisplacementImagePlaneMm: {\n    x: number;\n    y: number;\n    distance: number;\n  };\n  inverseDisplacementNativeSamples: RasterVector & {\n    distance: number;\n  };\n  inverseDisplacementOrientedSamples: RasterVector & {\n    distance: number;\n  };\n}\n\nexport interface CaptureRotationTemporalQuadraturePoint {\n  destinationPointNative: RasterPoint;\n  destinationImagePointMm: ImagePlanePointMm;\n  localExposureWindow: {\n    startSecondsFromCaptureReference: number;\n    endSecondsFromCaptureReference: number;\n    durationSeconds: number;\n  };\n  nodes: readonly CaptureRotationTemporalQuadratureNode[];\n}\n\nexport interface CaptureRotationTemporalQuadrature {\n  timeReference: \"first-opening-boundary-phase\";\n  quadratureScheme: \"uniform-midpoint\";\n  temporalResponseModel: \"uniform-over-local-exposure\";\n  temporalSampleCount: number;\n  /**\n   * The quadrature returns geometry and temporal measure only. It does not\n   * integrate radiance or produce a blur kernel.\n   */\n  outputMeaning: \"temporal-geometry-quadrature-nodes\";\n  points: readonly CaptureRotationTemporalQuadraturePoint[];\n  componentProvenance: {\n    instantaneousInverseMapping: CalculationProvenance;\n  };\n}\n\nfunction midpointPhase(index: number, sampleCount: number): number {\n  return (index + 0.5) / sampleCount;\n}\n\n/**\n * Builds deterministic time samples (temporal quadrature nodes) for a\n * rotating camera, across each destination point's local exposure interval.\n *\n * The first model uses an equal-width midpoint rule. Every node calls\n * calculateCaptureRotationInverseMappings(), so the instantaneous geometry\n * has a single implementation.\n *\n * No radiance is evaluated here. normalizedTimeWeight is for a time average,\n * assuming a uniform response over time. timeMeasureSeconds is the local dt\n * for a time integral. Neither weight includes shutter transmission, scene\n * flicker, sensor response, radiometric calibration or any other throughput\n * term.\n *\n * No numerical integration error estimate is reported, on purpose. Geometry\n * alone cannot tell the error in a scene-radiance integral. A renderer that\n * needs evidence of convergence can compare results for increasing sample\n * counts in its own radiance domain.\n */\nexport function calculateCaptureRotationTemporalQuadrature(\n  input: CalculateCaptureRotationTemporalQuadratureInput\n): CalculationResult<CaptureRotationTemporalQuadrature> {\n  requireInputKeys(input, \"calculateCaptureRotationTemporalQuadrature\", [\"temporalSampleCount\", \"imagingArea\", \"focalLengthMm\", \"focusDistanceM\", \"angularVelocityRadPerSec\", \"orientation\", \"samplePointsNative\", \"nativeRaster\", \"activeCaptureRect\", \"shutterMechanism\", \"nominalExposureDurationSeconds\", \"opening\", \"closing\"]);\n  requirePositiveInteger(\n    \"temporalSampleCount\",\n    input.temporalSampleCount\n  );\n\n  if (\n    !Array.isArray(input.samplePointsNative) ||\n    input.samplePointsNative.length === 0\n  ) {\n    throw new InvalidConfigurationError(\n      \"samplePointsNative must be a non-empty array.\"\n    );\n  }\n  input.samplePointsNative.forEach((point, index) => requireInputObject(point, \"samplePointsNative[\" + index + \"]\"));\n\n  const totalNodeCount =\n    input.temporalSampleCount * input.samplePointsNative.length;\n  if (!Number.isSafeInteger(totalNodeCount)) {\n    throw new InvalidScientificInputError(\n      \"temporalSampleCount × samplePointsNative.length must be a safe integer.\"\n    );\n  }\n\n  const {\n    temporalSampleCount,\n    ...instantaneousInput\n  } = input;\n\n  const phaseResults = Array.from(\n    { length: temporalSampleCount },\n    (_, temporalSampleIndex) => {\n      const localExposurePhase = midpointPhase(\n        temporalSampleIndex,\n        temporalSampleCount\n      );\n\n      return calculateCaptureRotationInverseMappings({\n        ...instantaneousInput,\n        localExposurePhase\n      });\n    }\n  );\n\n  const firstResult = phaseResults[0];\n  if (firstResult === undefined) {\n    throw new InvalidScientificInputError(\n      \"At least one temporal quadrature node is required.\"\n    );\n  }\n\n  const normalizedTimeWeight = 1 / temporalSampleCount;\n\n  const points = firstResult.value.samples.map(\n    (firstSample, pointIndex) => {\n      const durationSeconds =\n        firstSample.localExposureWindow.durationSeconds;\n      const timeMeasureSeconds =\n        durationSeconds / temporalSampleCount;\n\n      const nodes = phaseResults.map(\n        (phaseResult, temporalSampleIndex) => {\n          const sample = phaseResult.value.samples[pointIndex];\n          if (sample === undefined) {\n            throw new InvalidScientificInputError(\n              \"Instantaneous inverse-mapping sample alignment failed.\"\n            );\n          }\n\n          const localExposurePhase = midpointPhase(\n            temporalSampleIndex,\n            temporalSampleCount\n          );\n\n          return {\n            temporalSampleIndex,\n            localExposurePhase,\n            captureTimeSecondsFromReference:\n              sample.captureTimeSecondsFromReference,\n            normalizedTimeWeight,\n            timeMeasureSeconds,\n            referenceImagePointMm: {\n              ...sample.referenceImagePointMm\n            },\n            inverseDisplacementImagePlaneMm: {\n              ...sample.inverseDisplacementImagePlaneMm\n            },\n            inverseDisplacementNativeSamples: {\n              ...sample.inverseDisplacementNativeSamples\n            },\n            inverseDisplacementOrientedSamples: {\n              ...sample.inverseDisplacementOrientedSamples\n            }\n          };\n        }\n      );\n\n      return {\n        destinationPointNative: {\n          ...firstSample.destinationPointNative\n        },\n        destinationImagePointMm: {\n          ...firstSample.destinationImagePointMm\n        },\n        localExposureWindow: {\n          ...firstSample.localExposureWindow\n        },\n        nodes\n      };\n    }\n  );\n\n  return approximationResult(\n    {\n      timeReference: \"first-opening-boundary-phase\",\n      quadratureScheme: \"uniform-midpoint\",\n      temporalResponseModel: \"uniform-over-local-exposure\",\n      temporalSampleCount,\n      outputMeaning: \"temporal-geometry-quadrature-nodes\",\n      points,\n      componentProvenance: {\n        instantaneousInverseMapping: firstResult.provenance\n      }\n    },\n    \"capture-rotation-temporal-quadrature\",\n    \"1.0.0\",\n    [\n      \"Each destination native point retains its own validated local exposure interval.\",\n      \"Temporal nodes use a deterministic equal-width midpoint rule with phases (i + 0.5) / N and therefore do not sample the exact opening/closing boundaries.\",\n      \"Normalized temporal weights sum approximately to one and represent a uniform time-average measure only.\",\n      \"Seconds-valued temporal measures sum approximately to the local exposure duration and represent dt only.\",\n      \"Uniform temporal response is an explicit approximation; shutter transmission ramps, scene flicker, sensor response and radiometric throughput are not included.\",\n      \"Every node delegates instantaneous geometry to calculateCaptureRotationInverseMappings(); no second camera-motion equation is introduced.\",\n      \"Sensor data-readout timing and readout/exposure linkage metadata do not alter the exposure integral unless a future explicit image-formation model consumes them.\",\n      \"Reference rays may leave the active source frame under motion and are not clamped.\",\n      \"No radiance, photon count, blur kernel, PSF, source resampling or output pixel value is calculated.\",\n      \"No geometry-only convergence/error estimate is reported because temporal integration error depends on the downstream radiance/visibility function as well as motion.\",\n      \"Camera translation, scene-depth parallax, subject motion/deformation, occlusion changes, flash/flicker, shutter shock and non-uniform temporal response remain separate future work.\"\n    ]\n  );\n}\n"]}

package/dist/motion/capture-rotation-trajectory.d.ts

@@ -1,17 +1,22 @@
 /**
- * Module boundary and integration notes.
- * 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.
- * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Paths of still world rays across each point's local exposure window, for a camera that only
+ * rotates.
+ *
+ * This links timing to geometry. It is not a finished rolling-shutter image mapping.
+ * - The native sample point sets where a still world ray would land in the reference
+ *   global-shutter image, at the first opening-boundary phase (when the shutter starts to open).
+ * - The existing camera-rotation model is then evaluated at that point's local exposure start and
+ *   end.
+ *
+ * Sensor data-readout timing is deliberately not used. How readout relates to exposure boundaries
+ * depends on the camera and mode, and needs its own explicit contract. This function never assumes
+ * one.
+ *
+ * A future rolling-shutter warp for renderers must solve the image mapping with time that depends on
+ * capture location, and must integrate over the local exposure interval. Do not treat the endpoint
+ * chord returned here as a blur kernel or as an inverse destination-to-source sampling map.
+ * @see docs/MOTION_AND_SIGNAL.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationProvenance, type CalculationResult } from "../core/calculation-result.js";
 import { type RasterPoint } from "../output/capture-geometry.js";
@@ -33,8 +38,8 @@ export interface CalculateCaptureRotationTrajectoriesInput extends CalculateCapt
      */
     angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
     /**
-     * Native points whose stationary-reference-ray trajectories should be
-     * evaluated. Required and non-empty for this trajectory API.
+     * Native points whose still-ray paths to evaluate. Required, and must not be
+     * empty.
      */
     samplePointsNative: readonly RasterPoint[];
 }
@@ -94,20 +99,19 @@ export interface CaptureRotationTrajectories {
  * 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.
+ * This links timing to geometry. It is not a finished rolling-shutter image
+ * mapping. The native sample point sets where a still 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.
+ * Sensor data-readout timing is deliberately not used. How readout relates to
+ * exposure boundaries depends on the camera and mode, and needs its own
+ * 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.
+ * A future rolling-shutter warp for renderers must solve the image mapping
+ * with time that depends on capture location, and must integrate over the
+ * local exposure interval. Do not treat the endpoint chord returned here as a
+ * blur kernel or as an inverse destination-to-source sampling map.
  */
 export declare function calculateCaptureRotationTrajectories(input: CalculateCaptureRotationTrajectoriesInput): CalculationResult<CaptureRotationTrajectories>;
-//# sourceMappingURL=capture-rotation-trajectory.d.ts.map

package/dist/motion/capture-rotation-trajectory.js

@@ -1,28 +1,36 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * 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.
- * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Paths of still world rays across each point's local exposure window, for a camera that only
+ * rotates.
+ *
+ * This links timing to geometry. It is not a finished rolling-shutter image mapping.
+ * - The native sample point sets where a still world ray would land in the reference
+ *   global-shutter image, at the first opening-boundary phase (when the shutter starts to open).
+ * - The existing camera-rotation model is then evaluated at that point's local exposure start and
+ *   end.
+ *
+ * Sensor data-readout timing is deliberately not used. How readout relates to exposure boundaries
+ * depends on the camera and mode, and needs its own explicit contract. This function never assumes
+ * one.
+ *
+ * A future rolling-shutter warp for renderers must solve the image mapping with time that depends on
+ * capture location, and must integrate over the local exposure interval. Do not treat the endpoint
+ * chord returned here as a blur kernel or as an inverse destination-to-source sampling map.
+ * @see docs/MOTION_AND_SIGNAL.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { approximationResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
 import { mapOrientedPhysicalUvToImagePlanePoint, resolveCaptureGeometry } from "../output/capture-geometry.js";
 import { calculateCaptureExposureWindows } from "../sensor/exposure-window.js";
 import { calculateCameraRotationImageMapping } from "./camera-rotation.js";
+import { requireInputObject, requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 function requireNonEmptySamples(samplePointsNative) {
     if (!Array.isArray(samplePointsNative) || samplePointsNative.length === 0) {
-        throw new InvalidScientificInputError("samplePointsNative must be a non-empty array.");
+        throw new InvalidConfigurationError("samplePointsNative must be a non-empty array.");
     }
+    samplePointsNative.forEach((point, index) => requireInputObject(point, "samplePointsNative[" + index + "]"));
 }
 function nativePointToReferenceImagePlane(point, activeCaptureRect, activePhysicalBoundsFromOpticalAxisMm) {
     const u = (point.x - activeCaptureRect.x) / activeCaptureRect.width;
@@ -87,22 +95,24 @@ function trajectorySample(point, exposure, referenceImagePointMm, input) {
  * 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.
+ * This links timing to geometry. It is not a finished rolling-shutter image
+ * mapping. The native sample point sets where a still 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.
+ * Sensor data-readout timing is deliberately not used. How readout relates to
+ * exposure boundaries depends on the camera and mode, and needs its own
+ * 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.
+ * A future rolling-shutter warp for renderers must solve the image mapping
+ * with time that depends on capture location, and must integrate over the
+ * local exposure interval. Do not treat the endpoint chord returned here as a
+ * blur kernel or as an inverse destination-to-source sampling map.
  */
 export function calculateCaptureRotationTrajectories(input) {
+    requireInputKeys(input, "calculateCaptureRotationTrajectories", ["imagingArea", "focalLengthMm", "focusDistanceM", "angularVelocityRadPerSec", "samplePointsNative", "nativeRaster", "activeCaptureRect", "shutterMechanism", "nominalExposureDurationSeconds", "opening", "closing"]);
+    requireInputObject(input.imagingArea, "imagingArea");
     requirePositiveFinite("imagingArea.widthMm", input.imagingArea.widthMm);
     requirePositiveFinite("imagingArea.heightMm", input.imagingArea.heightMm);
     requirePositiveFinite("focalLengthMm", input.focalLengthMm);

package/dist/motion/capture-rotation-trajectory.js.map

@@ -1 +1 @@
-{"version":3,"file":"capture-rotation-trajectory.js","sourceRoot":"","sources":["../../src/motion/capture-rotation-trajectory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"capture-rotation-trajectory.js","sourceRoot":"","sources":["../../src/motion/capture-rotation-trajectory.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Paths of still world rays across each point's local exposure window, for a camera that only\n * rotates.\n *\n * This links timing to geometry. It is not a finished rolling-shutter image mapping.\n * - The native sample point sets where a still world ray would land in the reference\n *   global-shutter image, at the first opening-boundary phase (when the shutter starts to open).\n * - The existing camera-rotation model is then evaluated at that point's local exposure start and\n *   end.\n *\n * Sensor data-readout timing is deliberately not used. How readout relates to exposure boundaries\n * depends on the camera and mode, and needs its own explicit contract. This function never assumes\n * one.\n *\n * A future rolling-shutter warp for renderers must solve the image mapping with time that depends on\n * capture location, and must integrate over the local exposure interval. Do not treat the endpoint\n * chord returned here as a blur kernel or as an inverse destination-to-source sampling map.\n * @see docs/MOTION_AND_SIGNAL.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationProvenance,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport {\n  mapOrientedPhysicalUvToImagePlanePoint,\n  resolveCaptureGeometry,\n  type RasterPoint\n} from \"../output/capture-geometry.js\";\nimport {\n  calculateCaptureExposureWindows,\n  type CalculateCaptureExposureWindowsInput,\n  type CaptureExposureWindowSample\n} from \"../sensor/exposure-window.js\";\nimport type { SensorImagingArea } from \"../sensor/sensor-geometry.js\";\nimport {\n  calculateCameraRotationImageMapping,\n  type CameraAngularVelocityRadPerSec,\n  type CameraRotationImageMapping,\n  type ImagePlanePointMm\n} from \"./camera-rotation.js\";\nimport { requireInputObject, requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport interface CalculateCaptureRotationTrajectoriesInput\n  extends CalculateCaptureExposureWindowsInput {\n  /**\n   * Physical photosensitive imaging area associated with nativeRaster.\n   */\n  imagingArea: SensorImagingArea;\n  /** Physical focal length in millimetres. */\n  focalLengthMm: number;\n  /** Optional focus distance in metres for focus-aware projection distance. */\n  focusDistanceM?: number;\n  /**\n   * Constant physical camera angular velocity resolved in camera axes at the\n   * first opening-boundary phase.\n   */\n  angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;\n  /**\n   * Native points whose still-ray paths to evaluate. Required, and must not be\n   * empty.\n   */\n  samplePointsNative: readonly RasterPoint[];\n}\n\nexport interface CaptureRotationTrajectoryEndpoint {\n  timeSecondsFromCaptureReference: number;\n  mappedImagePointMm: ImagePlanePointMm;\n  deltaFromReferenceMm: {\n    x: number;\n    y: number;\n    distance: number;\n  };\n}\n\nexport interface CaptureRotationTrajectorySample {\n  pointNative: RasterPoint;\n  /**\n   * Image-plane position of the stationary world ray at the capture reference\n   * time (the first opening-boundary phase).\n   */\n  referenceImagePointMm: ImagePlanePointMm;\n  localExposureWindow: {\n    startSecondsFromCaptureReference: number;\n    endSecondsFromCaptureReference: number;\n    durationSeconds: number;\n    openingNormalizedScanPosition: number | null;\n    closingNormalizedScanPosition: number | null;\n  };\n  atLocalExposureStart: CaptureRotationTrajectoryEndpoint;\n  atLocalExposureEnd: CaptureRotationTrajectoryEndpoint;\n  /**\n   * Chord between the two trajectory endpoints.\n   *\n   * This is not a blur kernel, integrated exposure, or rolling-shutter warp.\n   */\n  localExposureTrajectoryEndpointDeltaMm: {\n    x: number;\n    y: number;\n    distance: number;\n  };\n}\n\nexport interface CaptureRotationTrajectories {\n  timeReference: \"first-opening-boundary-phase\";\n  trajectoryMeaning: \"forward-stationary-reference-ray\";\n  imagingArea: SensorImagingArea;\n  activeCaptureRect: {\n    x: number;\n    y: number;\n    width: number;\n    height: number;\n  };\n  samples: readonly CaptureRotationTrajectorySample[];\n  componentProvenance: {\n    exposureWindows: CalculationProvenance;\n    cameraRotation: CalculationProvenance;\n  };\n}\n\nfunction requireNonEmptySamples(\n  samplePointsNative: readonly RasterPoint[]\n): void {\n  if (!Array.isArray(samplePointsNative) || samplePointsNative.length === 0) {\n    throw new InvalidConfigurationError(\n      \"samplePointsNative must be a non-empty array.\"\n    );\n  }\n  samplePointsNative.forEach((point, index) => requireInputObject(point, \"samplePointsNative[\" + index + \"]\"));\n}\n\nfunction nativePointToReferenceImagePlane(\n  point: RasterPoint,\n  activeCaptureRect: {\n    x: number;\n    y: number;\n    width: number;\n    height: number;\n  },\n  activePhysicalBoundsFromOpticalAxisMm: {\n    left: number;\n    right: number;\n    top: number;\n    bottom: number;\n  }\n): ImagePlanePointMm {\n  const u = (point.x - activeCaptureRect.x) / activeCaptureRect.width;\n  const v = (point.y - activeCaptureRect.y) / activeCaptureRect.height;\n\n  return mapOrientedPhysicalUvToImagePlanePoint({\n    uv: { u, v },\n    orientedPhysicalBoundsFromOpticalAxisMm:\n      activePhysicalBoundsFromOpticalAxisMm,\n    orientation: \"landscape\"\n  });\n}\n\nfunction endpointFromMapping(\n  mapping: CameraRotationImageMapping\n): CaptureRotationTrajectoryEndpoint {\n  return {\n    timeSecondsFromCaptureReference:\n      mapping.timeSecondsFromExposureStart,\n    mappedImagePointMm: { ...mapping.mappedImagePointMm },\n    deltaFromReferenceMm: { ...mapping.deltaMm }\n  };\n}\n\nfunction trajectorySample(\n  point: RasterPoint,\n  exposure: CaptureExposureWindowSample,\n  referenceImagePointMm: ImagePlanePointMm,\n  input: CalculateCaptureRotationTrajectoriesInput\n): {\n  sample: CaptureRotationTrajectorySample;\n  rotationProvenance: CalculationProvenance;\n} {\n  const common = {\n    focalLengthMm: input.focalLengthMm,\n    imagePointMm: referenceImagePointMm,\n    angularVelocityRadPerSec: input.angularVelocityRadPerSec,\n    ...(input.focusDistanceM === undefined\n      ? {}\n      : { focusDistanceM: input.focusDistanceM })\n  };\n\n  const start = calculateCameraRotationImageMapping({\n    ...common,\n    timeSecondsFromExposureStart:\n      exposure.startOffsetSecondsFromOpeningReference\n  });\n  const end = calculateCameraRotationImageMapping({\n    ...common,\n    timeSecondsFromExposureStart:\n      exposure.endOffsetSecondsFromOpeningReference\n  });\n\n  const endpointDeltaX =\n    end.value.mappedImagePointMm.x -\n    start.value.mappedImagePointMm.x;\n  const endpointDeltaY =\n    end.value.mappedImagePointMm.y -\n    start.value.mappedImagePointMm.y;\n\n  return {\n    sample: {\n      pointNative: { ...point },\n      referenceImagePointMm: { ...referenceImagePointMm },\n      localExposureWindow: {\n        startSecondsFromCaptureReference:\n          exposure.startOffsetSecondsFromOpeningReference,\n        endSecondsFromCaptureReference:\n          exposure.endOffsetSecondsFromOpeningReference,\n        durationSeconds: exposure.localExposureDurationSeconds,\n        openingNormalizedScanPosition:\n          exposure.openingNormalizedScanPosition,\n        closingNormalizedScanPosition:\n          exposure.closingNormalizedScanPosition\n      },\n      atLocalExposureStart: endpointFromMapping(start.value),\n      atLocalExposureEnd: endpointFromMapping(end.value),\n      localExposureTrajectoryEndpointDeltaMm: {\n        x: endpointDeltaX,\n        y: endpointDeltaY,\n        distance: Math.hypot(endpointDeltaX, endpointDeltaY)\n      }\n    },\n    rotationProvenance: start.provenance\n  };\n}\n\n/**\n * Evaluates pure-camera-rotation trajectories for stationary reference rays\n * over each point's local exposure window.\n *\n * This links timing to geometry. It is not a finished rolling-shutter image\n * mapping. The native sample point sets where a still world ray would land in\n * the reference global-shutter image at the first opening-boundary phase. The\n * existing camera-rotation model is then evaluated at that point's local\n * exposure start and end.\n *\n * Sensor data-readout timing is deliberately not used. How readout relates to\n * exposure boundaries depends on the camera and mode, and needs its own\n * explicit contract. This function never assumes one.\n *\n * A future rolling-shutter warp for renderers must solve the image mapping\n * with time that depends on capture location, and must integrate over the\n * local exposure interval. Do not treat the endpoint chord returned here as a\n * blur kernel or as an inverse destination-to-source sampling map.\n */\nexport function calculateCaptureRotationTrajectories(\n  input: CalculateCaptureRotationTrajectoriesInput\n): CalculationResult<CaptureRotationTrajectories> {\n  requireInputKeys(input, \"calculateCaptureRotationTrajectories\", [\"imagingArea\", \"focalLengthMm\", \"focusDistanceM\", \"angularVelocityRadPerSec\", \"samplePointsNative\", \"nativeRaster\", \"activeCaptureRect\", \"shutterMechanism\", \"nominalExposureDurationSeconds\", \"opening\", \"closing\"]);\n  requireInputObject(input.imagingArea, \"imagingArea\");\n  requirePositiveFinite(\"imagingArea.widthMm\", input.imagingArea.widthMm);\n  requirePositiveFinite(\"imagingArea.heightMm\", input.imagingArea.heightMm);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requireNonEmptySamples(input.samplePointsNative);\n\n  const exposureWindows = calculateCaptureExposureWindows({\n    nativeRaster: input.nativeRaster,\n    ...(input.activeCaptureRect === undefined\n      ? {}\n      : { activeCaptureRect: input.activeCaptureRect }),\n    shutterMechanism: input.shutterMechanism,\n    nominalExposureDurationSeconds:\n      input.nominalExposureDurationSeconds,\n    opening: input.opening,\n    closing: input.closing,\n    samplePointsNative: input.samplePointsNative\n  });\n\n  const geometry = resolveCaptureGeometry({\n    imagingArea: input.imagingArea,\n    nativeRaster: input.nativeRaster,\n    orientation: \"landscape\",\n    activeCaptureRect: exposureWindows.value.activeCaptureRect\n  }).value;\n\n  const exposureByPoint = exposureWindows.value.samples;\n  const samples: CaptureRotationTrajectorySample[] = [];\n  let rotationProvenance: CalculationProvenance | undefined;\n\n  input.samplePointsNative.forEach((point, index) => {\n    const exposure = exposureByPoint[index];\n    if (exposure === undefined) {\n      throw new InvalidScientificInputError(\n        \"Exposure-window sample alignment failed.\"\n      );\n    }\n\n    const referenceImagePointMm = nativePointToReferenceImagePlane(\n      point,\n      geometry.activeCapture.nativeRect,\n      geometry.activeCapture.physicalBoundsFromOpticalAxisMm\n    );\n\n    const resolved = trajectorySample(\n      point,\n      exposure,\n      referenceImagePointMm,\n      input\n    );\n    samples.push(resolved.sample);\n    rotationProvenance ??= resolved.rotationProvenance;\n  });\n\n  if (rotationProvenance === undefined) {\n    throw new InvalidScientificInputError(\n      \"At least one rotation trajectory sample is required.\"\n    );\n  }\n\n  return approximationResult(\n    {\n      timeReference: \"first-opening-boundary-phase\",\n      trajectoryMeaning: \"forward-stationary-reference-ray\",\n      imagingArea: { ...input.imagingArea },\n      activeCaptureRect: {\n        ...exposureWindows.value.activeCaptureRect\n      },\n      samples,\n      componentProvenance: {\n        exposureWindows: exposureWindows.provenance,\n        cameraRotation: rotationProvenance\n      }\n    },\n    \"capture-rotation-exposure-trajectory\",\n    \"1.0.0\",\n    [\n      \"The first opening-boundary phase is explicitly bound to t=0 of the low-level camera-rotation model for this composition only.\",\n      \"Each native point identifies a stationary world ray by its reference image-plane location at the capture reference time.\",\n      \"Local exposure start/end times come only from the capture exposure-window contract.\",\n      \"Sensor data-readout timing does not participate and is never assumed to equal an exposure boundary.\",\n      \"Camera angular velocity is constant and resolved in camera axes at the first opening-boundary phase.\",\n      \"Only pure camera rotation is modeled; camera translation, scene depth parallax, subject motion, deformation and occlusion changes are excluded.\",\n      \"The returned start/end mappings are a forward stationary-ray trajectory, not a rolling-shutter image warp.\",\n      \"The trajectory endpoint chord is not an integrated blur kernel and may not represent the curved path between endpoints.\",\n      \"A later inverse renderer warp must solve capture-location-dependent timing consistently rather than evaluating one forward displacement at the destination coordinate.\",\n      \"Exposure integration over the full local interval remains future work.\"\n    ]\n  );\n}\n"]}

package/dist/motion/capture-translation-parallax-temporal-quadrature.d.ts

@@ -1,11 +1,13 @@
 /**
- * Module boundary and integration notes.
- * 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.
- * @see docs/MOTION_AND_SIGNAL.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Parallax from camera movement (translation): nearer points shift more in the image than distant
+ * ones. It is evaluated at deterministic midpoint time samples across each scene point's local
+ * exposure window.
+ *
+ * The model works point by point, on purpose. Camera movement and optional subject movement combine
+ * as relative linear motion; neither is recast as the other. Camera rotation, and visibility or
+ * occlusion, are separate models.
+ * @see docs/MOTION_AND_SIGNAL.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type CaptureOrientation, type RasterPoint } from "../output/capture-geometry.js";
@@ -15,18 +17,18 @@ import type { SensorImagingArea } from "../sensor/sensor-geometry.js";
 export interface CaptureTranslationParallaxSceneSample {
     sampleId: string;
     /**
-     * Native destination point whose authoritative local exposure window applies
-     * to this scene sample.
+     * Native destination point. Its 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.
+     * Point position in metres, 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.
+     * Optional constant velocity of the subject (world point), in the same
+     * starting camera axes. If omitted, the world point is still.
      */
     subjectVelocityMps?: Vector3;
 }
@@ -37,8 +39,8 @@ export interface CalculateCaptureTranslationParallaxTemporalQuadratureInput {
     focusDistanceM?: number;
     orientation: CaptureOrientation;
     /**
-     * Constant physical camera-center translation in camera axes at the capture
-     * reference phase. Rotation is intentionally separate.
+     * Constant movement of the camera centre, in camera axes at the capture
+     * reference phase. Rotation is handled separately, on purpose.
      */
     cameraTranslationVelocityMps: Vector3;
     temporalSampleCount: number;
@@ -108,12 +110,12 @@ export interface CaptureTranslationParallaxTemporalQuadrature {
     sensorReadoutTimingUsedAsExposureTiming: false;
 }
 /**
- * Evaluates depth-dependent translational parallax at deterministic midpoint
- * nodes over each scene point's authoritative local exposure window.
+ * Evaluates depth-dependent parallax from camera movement at deterministic
+ * midpoint time samples across each scene point's 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.
+ * The model works point by point, on purpose. Camera movement and optional
+ * subject movement combine as relative linear motion; neither is recast as
+ * the other. Camera rotation, and visibility or occlusion, are separate
+ * models.
  */
 export declare function calculateCaptureTranslationParallaxTemporalQuadrature(input: CalculateCaptureTranslationParallaxTemporalQuadratureInput): CalculationResult<CaptureTranslationParallaxTemporalQuadrature>;
-//# sourceMappingURL=capture-translation-parallax-temporal-quadrature.d.ts.map