@photivra/engine 1.5.0 → 2.1.0

package/dist/stabilization/camera-shake.js

@@ -1,27 +1,35 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Estimates sensor-plane blur from a controlled constant-angular-velocity handheld shake profile, with
- * optional equivalent stabilization attenuation. With focusDistanceM supplied, angular motion is
- * projected using the same ideal thin-lens sensor-plane distance as the other focus-aware projection
- * primitives; otherwise nominal focal length preserves the prior approximation. The optical projection
- * is physically calculated, but mapping a stabilization rating in stops to residual angular motion by
- * 2^-stops is an educational approximation. It is not a CIPA DC-011 measurement or a real-camera
- * rating.
- * @see docs/STABILIZATION.md for equations, coordinate/unit conventions, blockers and support limits.
+ * Estimates blur on the sensor from a simple handheld-shake profile: the camera turns at a constant
+ * angular velocity. An optional stabilization rating reduces that motion.
+ *
+ * With focusDistanceM, angular motion is projected using the ideal thin-lens sensor distance, like
+ * the other focus-aware projection functions. Without it, the nominal focal length is used, which
+ * keeps the older approximation.
+ *
+ * The optical projection is physically calculated. But turning a stabilization rating in stops into
+ * residual angular motion by 2^-stops is an educational approximation. It is not a CIPA DC-011
+ * measurement or a real-camera rating.
+ * @see docs/STABILIZATION.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 { portableHypot } from "../core/portable-math.js";
 import { calculateThinLensImageDistance } from "../optics/thin-lens.js";
+import { rejectUnknownFields, requireInputKeys, requireInputObject } from "../core/record-validation.js";
 function requireFinite(name, value) {
     if (!Number.isFinite(value)) {
         throw new InvalidScientificInputError(`${name} must be finite.`);
     }
 }
 function projectAngularDisplacement(projectionDistanceMm, yawRad, pitchRad, pixelPitchMicrometers) {
+    // Physical right-hand rule in the left-handed camera basis: positive yaw
+    // (turn left) moves content toward +X; positive pitch (tilt up) toward -Y.
     const deltaXmm = projectionDistanceMm * Math.tan(yawRad);
-    const deltaYmm = projectionDistanceMm * Math.tan(pitchRad);
-    const distanceMm = Math.hypot(deltaXmm, deltaYmm);
+    // "0 -" keeps zero pitch at +0 rather than -0.
+    const deltaYmm = 0 - projectionDistanceMm * Math.tan(pitchRad);
+    const distanceMm = portableHypot(deltaXmm, deltaYmm);
     if (pixelPitchMicrometers === undefined) {
         return { deltaXmm, deltaYmm, distanceMm };
     }
@@ -36,20 +44,28 @@ function projectAngularDisplacement(projectionDistanceMm, yawRad, pitchRad, pixe
     };
 }
 /**
- * Estimates sensor-plane blur from a controlled constant-angular-velocity
- * handheld shake profile, with optional equivalent stabilization attenuation.
+ * Estimates blur on the sensor from a simple handheld-shake profile, where
+ * the camera turns at a constant angular velocity. An optional stabilization
+ * rating reduces that motion.
  *
- * With focusDistanceM supplied, angular motion is projected using the same
- * ideal thin-lens sensor-plane distance as the other focus-aware projection
- * primitives; otherwise nominal focal length preserves the prior approximation.
+ * With focusDistanceM, angular motion is projected using the ideal thin-lens
+ * sensor distance, like the other focus-aware projection functions. Without
+ * it, the nominal focal length is used, which keeps the older approximation.
  *
- * The optical projection is physically calculated, but mapping a stabilization
- * rating in stops to residual angular motion by 2^-stops is an educational
- * approximation. It is not a CIPA DC-011 measurement or a real-camera rating.
+ * The optical projection is physically calculated. But turning a
+ * stabilization rating in stops into residual angular motion by 2^-stops is
+ * an educational approximation. It is not a CIPA DC-011 measurement or a
+ * real-camera rating.
+ *
+ * Each axis's rotation during the exposure must stay below a quarter turn
+ * (π/2 rad).
  */
 export function estimateCameraShakeBlur(input) {
+    requireInputKeys(input, "estimateCameraShakeBlur", ["focalLengthMm", "shutterSeconds", "angularVelocityRadPerSec", "stabilizationStopsEquivalent", "focusDistanceM", "pixelPitchMicrometers"]);
     requirePositiveFinite("focalLengthMm", input.focalLengthMm);
     requirePositiveFinite("shutterSeconds", input.shutterSeconds);
+    requireInputObject(input.angularVelocityRadPerSec, "angularVelocityRadPerSec");
+    rejectUnknownFields(input.angularVelocityRadPerSec, ["yaw", "pitch"], "angularVelocityRadPerSec");
     requireFinite("angularVelocityRadPerSec.yaw", input.angularVelocityRadPerSec.yaw);
     requireFinite("angularVelocityRadPerSec.pitch", input.angularVelocityRadPerSec.pitch);
     if (!Number.isFinite(input.stabilizationStopsEquivalent) ||
@@ -68,6 +84,12 @@ export function estimateCameraShakeBlur(input) {
     const projectionDistanceMm = focusProjection?.value.imageDistanceMm ?? input.focalLengthMm;
     const yawRad = input.angularVelocityRadPerSec.yaw * input.shutterSeconds;
     const pitchRad = input.angularVelocityRadPerSec.pitch * input.shutterSeconds;
+    // tan() flips sign past a quarter turn, which would break the sign
+    // convention. The rotation mapping likewise rejects a world ray that maps to
+    // or behind the camera plane.
+    if (Math.abs(yawRad) >= Math.PI / 2 || Math.abs(pitchRad) >= Math.PI / 2) {
+        throw new InvalidScientificInputError("Camera-shake rotation over the exposure must stay below a quarter turn (|angular velocity × shutterSeconds| < π/2 rad) on each axis.");
+    }
     const residualMotionFactor = 2 ** -input.stabilizationStopsEquivalent;
     return approximationResult({
         residualMotionFactor,
@@ -76,12 +98,13 @@ export function estimateCameraShakeBlur(input) {
         stabilized: projectAngularDisplacement(projectionDistanceMm, yawRad * residualMotionFactor, pitchRad * residualMotionFactor, input.pixelPitchMicrometers)
     }, focusProjection === undefined
         ? "constant-angular-velocity-stabilization-equivalent"
-        : "focus-aware-constant-angular-velocity-stabilization-equivalent", "1.0.0", [
+        : "focus-aware-constant-angular-velocity-stabilization-equivalent", "2.0.0", [
         "Camera rotation is constant during the exposure",
         focusProjection === undefined
             ? "Nominal focal length is used as the infinity-focus projection distance"
             : "Thin-lens image distance for the selected focus plane is used as the projection distance",
         "Yaw and pitch are treated independently",
+        "Positive yaw/pitch follow the physical right-hand rule about camera +Y/+X (yaw left moves content toward +X; pitch up moves content toward -Y)",
         "Equivalent stabilization stops attenuate angular displacement by 2^-stops",
         "This is not a CIPA DC-011 compliance measurement",
         "Roll, translation, subject motion, and stabilization limits are not modeled"

package/dist/stabilization/camera-shake.js.map

@@ -1 +1 @@
-{"version":3,"file":"camera-shake.js","sourceRoot":"","sources":["../../src/stabilization/camera-shake.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"camera-shake.js","sourceRoot":"","sources":["../../src/stabilization/camera-shake.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Estimates blur on the sensor from a simple handheld-shake profile: the camera turns at a constant\n * angular velocity. An optional stabilization rating reduces that motion.\n *\n * With focusDistanceM, angular motion is projected using the ideal thin-lens sensor distance, like\n * the other focus-aware projection functions. Without it, the nominal focal length is used, which\n * keeps the older approximation.\n *\n * The optical projection is physically calculated. But turning a stabilization rating in stops into\n * residual angular motion by 2^-stops is an educational approximation. It is not a CIPA DC-011\n * measurement or a real-camera rating.\n * @see docs/STABILIZATION.md for the equations, units, coordinate conventions, known blockers and\n * support limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport { portableHypot } from \"../core/portable-math.js\";\nimport { calculateThinLensImageDistance } from \"../optics/thin-lens.js\";\nimport { rejectUnknownFields, requireInputKeys, requireInputObject } from \"../core/record-validation.js\";\n\nexport interface EstimateCameraShakeBlurInput {\n  focalLengthMm: number;\n  shutterSeconds: number;\n  /**\n   * Constant camera angular velocity in radians per second. Signs follow the\n   * same physical right-hand rule as calculateCameraRotationImageMapping().\n   * The camera axes are +X right, +Y up, +Z forward (a left-handed basis).\n   * - Positive yaw turns the optical axis left and moves still image content\n   *   toward +X.\n   * - Positive pitch tilts the optical axis up and moves still image content\n   *   toward -Y.\n   */\n  angularVelocityRadPerSec: {\n    yaw: number;\n    pitch: number;\n  };\n  stabilizationStopsEquivalent: number;\n  /** Optional focus distance in metres for focus-aware sensor-plane projection. */\n  focusDistanceM?: number;\n  pixelPitchMicrometers?: number;\n}\n\n/**\n * How far a still world point on the optical axis moves in the image during\n * the exposure, in image-plane axes (+X right, +Y up). For a single axis it\n * equals the deltaMm from calculateCameraRotationImageMapping() at the\n * optical axis.\n */\nexport interface CameraShakeBlurSample {\n  /** +X-right image displacement in millimetres: +d·tan(yaw·t). */\n  deltaXmm: number;\n  /** +Y-up image displacement in millimetres: -d·tan(pitch·t). */\n  deltaYmm: number;\n  distanceMm: number;\n  distancePixels?: number;\n  deltaXPixels?: number;\n  deltaYPixels?: number;\n}\n\nexport interface CameraShakeEstimate {\n  residualMotionFactor: number;\n  projectionDistanceMm: number;\n  unstabilized: CameraShakeBlurSample;\n  stabilized: CameraShakeBlurSample;\n}\n\nfunction requireFinite(name: string, value: number): void {\n  if (!Number.isFinite(value)) {\n    throw new InvalidScientificInputError(`${name} must be finite.`);\n  }\n}\n\nfunction projectAngularDisplacement(\n  projectionDistanceMm: number,\n  yawRad: number,\n  pitchRad: number,\n  pixelPitchMicrometers?: number\n): CameraShakeBlurSample {\n  // Physical right-hand rule in the left-handed camera basis: positive yaw\n  // (turn left) moves content toward +X; positive pitch (tilt up) toward -Y.\n  const deltaXmm = projectionDistanceMm * Math.tan(yawRad);\n  // \"0 -\" keeps zero pitch at +0 rather than -0.\n  const deltaYmm = 0 - projectionDistanceMm * Math.tan(pitchRad);\n  const distanceMm = portableHypot(deltaXmm, deltaYmm);\n\n  if (pixelPitchMicrometers === undefined) {\n    return { deltaXmm, deltaYmm, distanceMm };\n  }\n\n  const pitchMm = pixelPitchMicrometers / 1000;\n  return {\n    deltaXmm,\n    deltaYmm,\n    distanceMm,\n    distancePixels: distanceMm / pitchMm,\n    deltaXPixels: deltaXmm / pitchMm,\n    deltaYPixels: deltaYmm / pitchMm\n  };\n}\n\n/**\n * Estimates blur on the sensor from a simple handheld-shake profile, where\n * the camera turns at a constant angular velocity. An optional stabilization\n * rating reduces that motion.\n *\n * With focusDistanceM, angular motion is projected using the ideal thin-lens\n * sensor distance, like the other focus-aware projection functions. Without\n * it, the nominal focal length is used, which keeps the older approximation.\n *\n * The optical projection is physically calculated. But turning a\n * stabilization rating in stops into residual angular motion by 2^-stops is\n * an educational approximation. It is not a CIPA DC-011 measurement or a\n * real-camera rating.\n *\n * Each axis's rotation during the exposure must stay below a quarter turn\n * (π/2 rad).\n */\nexport function estimateCameraShakeBlur(\n  input: EstimateCameraShakeBlurInput\n): CalculationResult<CameraShakeEstimate> {\n  requireInputKeys(input, \"estimateCameraShakeBlur\", [\"focalLengthMm\", \"shutterSeconds\", \"angularVelocityRadPerSec\", \"stabilizationStopsEquivalent\", \"focusDistanceM\", \"pixelPitchMicrometers\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"shutterSeconds\", input.shutterSeconds);\n  requireInputObject(input.angularVelocityRadPerSec, \"angularVelocityRadPerSec\");\n  rejectUnknownFields(input.angularVelocityRadPerSec, [\"yaw\", \"pitch\"], \"angularVelocityRadPerSec\");\n  requireFinite(\n    \"angularVelocityRadPerSec.yaw\",\n    input.angularVelocityRadPerSec.yaw\n  );\n  requireFinite(\n    \"angularVelocityRadPerSec.pitch\",\n    input.angularVelocityRadPerSec.pitch\n  );\n\n  if (\n    !Number.isFinite(input.stabilizationStopsEquivalent) ||\n    input.stabilizationStopsEquivalent < 0\n  ) {\n    throw new InvalidScientificInputError(\n      \"stabilizationStopsEquivalent must be finite and greater than or equal to zero.\"\n    );\n  }\n\n  if (input.pixelPitchMicrometers !== undefined) {\n    requirePositiveFinite(\n      \"pixelPitchMicrometers\",\n      input.pixelPitchMicrometers\n    );\n  }\n\n  const focusProjection =\n    input.focusDistanceM === undefined\n      ? undefined\n      : calculateThinLensImageDistance({\n          focalLengthMm: input.focalLengthMm,\n          objectDistanceM: input.focusDistanceM\n        });\n  const projectionDistanceMm =\n    focusProjection?.value.imageDistanceMm ?? input.focalLengthMm;\n  const yawRad =\n    input.angularVelocityRadPerSec.yaw * input.shutterSeconds;\n  const pitchRad =\n    input.angularVelocityRadPerSec.pitch * input.shutterSeconds;\n  // tan() flips sign past a quarter turn, which would break the sign\n  // convention. The rotation mapping likewise rejects a world ray that maps to\n  // or behind the camera plane.\n  if (Math.abs(yawRad) >= Math.PI / 2 || Math.abs(pitchRad) >= Math.PI / 2) {\n    throw new InvalidScientificInputError(\n      \"Camera-shake rotation over the exposure must stay below a quarter turn (|angular velocity × shutterSeconds| < π/2 rad) on each axis.\"\n    );\n  }\n  const residualMotionFactor =\n    2 ** -input.stabilizationStopsEquivalent;\n\n  return approximationResult(\n    {\n      residualMotionFactor,\n      projectionDistanceMm,\n      unstabilized: projectAngularDisplacement(\n        projectionDistanceMm,\n        yawRad,\n        pitchRad,\n        input.pixelPitchMicrometers\n      ),\n      stabilized: projectAngularDisplacement(\n        projectionDistanceMm,\n        yawRad * residualMotionFactor,\n        pitchRad * residualMotionFactor,\n        input.pixelPitchMicrometers\n      )\n    },\n    focusProjection === undefined\n      ? \"constant-angular-velocity-stabilization-equivalent\"\n      : \"focus-aware-constant-angular-velocity-stabilization-equivalent\",\n    \"2.0.0\",\n    [\n      \"Camera rotation is constant during the exposure\",\n      focusProjection === undefined\n        ? \"Nominal focal length is used as the infinity-focus projection distance\"\n        : \"Thin-lens image distance for the selected focus plane is used as the projection distance\",\n      \"Yaw and pitch are treated independently\",\n      \"Positive yaw/pitch follow the physical right-hand rule about camera +Y/+X (yaw left moves content toward +X; pitch up moves content toward -Y)\",\n      \"Equivalent stabilization stops attenuate angular displacement by 2^-stops\",\n      \"This is not a CIPA DC-011 compliance measurement\",\n      \"Roll, translation, subject motion, and stabilization limits are not modeled\"\n    ]\n  );\n}\n"]}

package/dist/stabilization/system.d.ts

@@ -1,16 +1,16 @@
 /**
- * Module boundary and integration notes.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. Generic
- * stabilization evaluates declared angular disturbance with per-axis response, latency, limits and
- * panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
- * calibration, arbitrary stop rating or inferred coordination is supplied.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. Generic
- * stabilization evaluates declared angular disturbance with per-axis response, latency, limits and
- * panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
- * calibration, arbitrary stop rating or inferred coordination is supplied.
- * @see docs/STABILIZATION.md for equations, coordinate/unit conventions, blockers and support limits.
+ * Generic image stabilization: profiles, disturbance trajectories, the stabilized rotation and its
+ * effect on capture timing samples.
+ *
+ * The parsers validate untrusted input and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected.
+ *
+ * The generic stabilizer takes a declared angular disturbance (camera shake) and applies a per-axis
+ * response, latency, travel limits and a panning policy. The leftover (residual) motion feeds the
+ * existing temporal mapping. No commercial IBIS (in-body) or OIS (optical) calibration is supplied,
+ * no arbitrary "stops" rating is used, and body/lens coordination is never inferred.
+ * @see docs/STABILIZATION.md for the equations, units, coordinate conventions, known blockers and
+ * support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type EvidenceBackedFact, type EvidenceProvenance } from "../core/evidence-provenance.js";
@@ -164,55 +164,58 @@ export interface StabilizedCaptureTemporalSamples {
     digitalStabilizationApplied: false;
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
- * and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
- * calibration, arbitrary stop rating or inferred coordination is supplied.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns StabilizationSystemProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The generic stabilizer takes a declared angular disturbance (camera shake) and applies a per-axis
+ * response, latency, travel limits and a panning policy. The leftover (residual) motion feeds the
+ * existing temporal mapping. No commercial IBIS (in-body) or OIS (optical) calibration is supplied,
+ * no arbitrary "stops" rating is used, and body/lens coordination is never inferred.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns StabilizationSystemProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function parseStabilizationSystemProfile(value: unknown): StabilizationSystemProfile;
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
- * and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
- * calibration, arbitrary stop rating or inferred coordination is supplied.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns StabilizationDisturbanceTrajectory. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The generic stabilizer takes a declared angular disturbance (camera shake) and applies a per-axis
+ * response, latency, travel limits and a panning policy. The leftover (residual) motion feeds the
+ * existing temporal mapping. No commercial IBIS (in-body) or OIS (optical) calibration is supplied,
+ * no arbitrary "stops" rating is used, and body/lens coordination is never inferred.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns StabilizationDisturbanceTrajectory. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function parseStabilizationDisturbanceTrajectory(value: unknown): StabilizationDisturbanceTrajectory;
 /**
- * Evaluate the declared generic per-axis controller against an explicit angular disturbance trajectory
- * and return residual motion with latency/limit diagnostics.
+ * Runs the declared generic per-axis controller against an explicit angular disturbance trajectory.
+ * Returns the residual motion, with diagnostics for latency and travel limits.
  *
- * Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
- * and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
- * calibration, arbitrary stop rating or inferred coordination is supplied.
- * @param input - CalculateStabilizedRotationTrajectoryInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<StabilizedRotationTrajectory>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The generic stabilizer takes a declared angular disturbance (camera shake) and applies a per-axis
+ * response, latency, travel limits and a panning policy. The leftover (residual) motion feeds the
+ * existing temporal mapping. No commercial IBIS (in-body) or OIS (optical) calibration is supplied,
+ * no arbitrary "stops" rating is used, and body/lens coordination is never inferred.
+ * @param input - CalculateStabilizedRotationTrajectoryInput. See that type for coordinates, units and profile binding.
+ * @returns CalculationResult<StabilizedRotationTrajectory>. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function calculateStabilizedRotationTrajectory(input: CalculateStabilizedRotationTrajectoryInput): CalculationResult<StabilizedRotationTrajectory>;
 /**
- * Feed the residual stabilized rotation into the existing local-exposure temporal mapping without
- * changing shutter timing or inventing a blur radius.
+ * Feeds the residual stabilized rotation into the existing local-exposure temporal mapping. Shutter
+ * timing is not changed, and no blur radius is invented.
  *
- * Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
- * and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
- * calibration, arbitrary stop rating or inferred coordination is supplied.
- * @param input - CalculateStabilizedCaptureTemporalSamplesInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<StabilizedCaptureTemporalSamples>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The generic stabilizer takes a declared angular disturbance (camera shake) and applies a per-axis
+ * response, latency, travel limits and a panning policy. The leftover (residual) motion feeds the
+ * existing temporal mapping. No commercial IBIS (in-body) or OIS (optical) calibration is supplied,
+ * no arbitrary "stops" rating is used, and body/lens coordination is never inferred.
+ * @param input - CalculateStabilizedCaptureTemporalSamplesInput. See that type for coordinates, units and profile binding.
+ * @returns CalculationResult<StabilizedCaptureTemporalSamples>. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function calculateStabilizedCaptureTemporalSamples(input: CalculateStabilizedCaptureTemporalSamplesInput): CalculationResult<StabilizedCaptureTemporalSamples>;
-//# sourceMappingURL=system.d.ts.map