@photivra/engine 1.4.0 → 2.0.0

package/docs/api/simulation-poc-simulation.md

@@ -1,13 +1,13 @@
 # simulation/poc-simulation.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
 
 ## POC_SIMULATION_API_VERSION
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
 
 ```ts
-POC_SIMULATION_API_VERSION = "0.20.0" as const
+POC_SIMULATION_API_VERSION = "1.0.0" as const
 ```
 
 ## PocSimulationRequest
@@ -41,16 +41,16 @@ export interface PocSimulationRequest {
   };
   crop: {
     /**
-     * Legacy centered same-aspect crop factor.
+     * Legacy centred crop factor that keeps the aspect ratio.
      *
-     * When capture geometry is supplied this must remain 1. New callers should
-     * use capture.activeCaptureRect/outputCropRect instead of stacking two
-     * independent crop models.
+     * When capture geometry is supplied this must stay 1. New callers should
+     * use capture.activeCaptureRect and outputCropRect instead, rather than
+     * stacking two separate crop models.
      */
     factor: number;
   };
   /**
-   * Opt-in staged capture geometry. Omit for exact legacy POC behavior.
+   * Optional staged capture geometry. Leave it out to get the exact legacy POC behaviour.
    */
   capture?: {
     orientation: CaptureOrientation;
@@ -128,11 +128,11 @@ export interface PocSimulationResponse {
     diagonalDegrees: number;
   };
   sensor: {
-    /** Physical imaging-area/native-raster metrics from the shared sensor foundation. */
+    /** Physical imaging area and native pixel grid, from the shared sensor geometry model. */
     geometry: SensorGeometryMetrics;
     /**
-     * Backwards-compatible representative pitch used by the current composed
-     * POC calculations. This remains the horizontal pitch.
+     * The single pixel pitch the POC calculations use, kept for backwards
+     * compatibility. It is the horizontal pitch.
      */
     pixelPitchMicrometers: number;
     pitchXMicrometers: number;
@@ -151,8 +151,8 @@ export interface PocSimulationResponse {
       basis: "diagonal";
     };
     /**
-     * Axis-aware pixel-domain mapping from oriented active-capture samples to
-     * the declared output raster. Subject framing is a later crop, not another
+     * Per-axis pixel mapping from the oriented active capture area to the
+     * declared output image. Subject framing is a later crop, not another
      * resampling step.
      */
     outputSamplingScale: {
@@ -161,8 +161,9 @@ export interface PocSimulationResponse {
       axisRelativeDifference: number;
     };
     /**
-     * Additional post-output subject framing. This does not mutate physical
-     * sensor identity, active capture, or active-capture focal equivalence.
+     * Extra subject-framing crop applied after output. It does not change the
+     * physical sensor, the active capture area or the active capture's
+     * equivalent focal length.
      */
     subjectFraming?: CaptureSubjectFraming;
     motion: {
@@ -352,8 +353,8 @@ export interface PocSimulationResponse {
 
 ## simulatePocCamera
 
-Composes the validated POC calculations into a single renderer/agent-facing
-response without introducing any new photographic model.
+Runs the validated POC calculations and returns them as one response for a
+renderer or agent. It adds no new photographic model.
 
 ```ts
 export function simulatePocCamera(

package/docs/api/stabilization-camera-shake.md

@@ -1,14 +1,19 @@
 # stabilization/camera-shake.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
 
 ## CameraShakeBlurSample
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+How far a still world point on the optical axis moves in the image during
+the exposure, in image-plane axes (+X right, +Y up). For a single axis it
+equals the deltaMm from calculateCameraRotationImageMapping() at the
+optical axis.
 
 ```ts
 export interface CameraShakeBlurSample {
+  /** +X-right image displacement in millimetres: +d·tan(yaw·t). */
   deltaXmm: number;
+  /** +Y-up image displacement in millimetres: -d·tan(pitch·t). */
   deltaYmm: number;
   distanceMm: number;
   distancePixels?: number;
@@ -32,16 +37,21 @@ export interface CameraShakeEstimate {
 
 ## estimateCameraShakeBlur
 
-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, 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.
 
-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 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.
 
-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.
+Each axis's rotation during the exposure must stay below a quarter turn
+(π/2 rad).
 
 ```ts
 export function estimateCameraShakeBlur(
@@ -59,6 +69,15 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface EstimateCameraShakeBlurInput {
   focalLengthMm: number;
   shutterSeconds: number;
+  /**
+   * Constant camera angular velocity in radians per second. Signs follow the
+   * same physical right-hand rule as calculateCameraRotationImageMapping().
+   * The camera axes are +X right, +Y up, +Z forward (a left-handed basis).
+   * - Positive yaw turns the optical axis left and moves still image content
+   *   toward +X.
+   * - Positive pitch tilts the optical axis up and moves still image content
+   *   toward -Y.
+   */
   angularVelocityRadPerSec: {
     yaw: number;
     pitch: number;

package/docs/api/stabilization-system.md

@@ -1,15 +1,16 @@
 # stabilization/system.ts public contracts
 
-Package **1.4.0**, root API **1.4.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.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/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.
 
 ## calculateStabilizedCaptureTemporalSamples
 
-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.
+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.
 
 ```ts
 export function calculateStabilizedCaptureTemporalSamples(
@@ -42,12 +43,13 @@ export interface CalculateStabilizedCaptureTemporalSamplesInput {
 
 ## calculateStabilizedRotationTrajectory
 
-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.
+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.
 
 ```ts
 export function calculateStabilizedRotationTrajectory(
@@ -75,12 +77,13 @@ export interface CalculateStabilizedRotationTrajectoryInput {
 
 ## parseStabilizationDisturbanceTrajectory
 
-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.
+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.
 
 ```ts
 export function parseStabilizationDisturbanceTrajectory(
@@ -92,12 +95,13 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## parseStabilizationSystemProfile
 
-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.
+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.
 
 ```ts
 export function parseStabilizationSystemProfile(