@photivra/engine 1.4.0 → 2.0.0

package/docs/api/gpu-image-kernel-accelerator.md

@@ -0,0 +1,157 @@
+# gpu/image-kernel-accelerator.ts public contracts
+
+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.
+
+## AcceleratedNativeCaptureSdrOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AcceleratedNativeCaptureSdrOutput extends NativeCaptureSdrOutput { execution: ImageKernelExecution }
+```
+
+## AcceleratedNativeRawDevelopmentOutput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AcceleratedNativeRawDevelopmentOutput extends NativeRawDevelopmentOutput { execution: ImageKernelExecution }
+```
+
+## AcceleratedPackedSensorRawResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AcceleratedPackedSensorRawResult extends PackedSensorRawResult {
+  execution: ImageKernelExecution;
+  /**
+   * Region-relative indices of the flagged sites, ascending (empty for `cpu-reference`). Every other site
+   * equals the reference; recomputing these sites with the reference makes the whole region bit-identical.
+   */
+  flaggedSiteIndices: Uint32Array;
+}
+```
+
+## ChartRadianceResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ChartRadianceResult {
+  plan: ChartRadianceBatchPlan;
+  /** Row-major (query, column): float64 for `cpu-reference`, float32 for `webgpu-f32`. */
+  values: Float64Array | Float32Array;
+  columns: number;
+  execution: ImageKernelExecution;
+  /**
+   * Queries whose float32 classification fell inside its bound, recomputed on the host with the
+   * reference (then rounded to float32). Empty for `cpu-reference`.
+   */
+  hostRecomputedQueryIndices: Uint32Array;
+}
+```
+
+## createImageKernelAccelerator
+
+Requests a backend. Never swaps backends silently: a fallback must be set in the options and is shown in every result label.
+
+```ts
+export async function createImageKernelAccelerator(options: ImageKernelAcceleratorOptions): Promise<ImageKernelAccelerator>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
+## ImageKernelAccelerator
+
+Runs one operation at a time. dispose() releases the device and every buffer.
+
+```ts
+export interface ImageKernelAccelerator {
+  readonly backend: ImageKernelBackend;
+  readonly requestedBackend: ImageKernelBackend;
+  readonly fallbackReason: ImageKernelFallbackReason | null;
+  readonly state: ImageKernelAcceleratorState;
+  renderNativeCaptureSdr(input: NativeCaptureSdrInput, provider: NativeCaptureSdrProvider, options?: ImageKernelRunOptions): Promise<AcceleratedNativeCaptureSdrOutput>;
+  /** Takes ownership of `input.raw` exactly like `createNativeRawDevelopmentTask` (the caller's arrays are detached). */
+  developNativeRaw(input: NativeRawDevelopmentInput, provider: NativeRawDevelopmentProvider | ((signal: AbortSignal) => Promise<void>),
+    options?: ImageKernelRunOptions): Promise<AcceleratedNativeRawDevelopmentOutput>;
+  convolveIrradiance(input: IrradianceConvolutionInput, options?: ImageKernelRunOptions): Promise<IrradianceConvolutionResult>;
+  /** Sensor stage on typed arrays: seeded charge, read noise and ADC to RAW codes (see `simulatePackedSensorRaw`). */
+  simulateSensorRaw(input: PackedSensorRawInput, options?: ImageKernelRunOptions): Promise<AcceleratedPackedSensorRawResult>;
+  /** Exposure and motion as a weighted sum of shifted frames (see `calculateTemporalExposureSum`). */
+  sumTemporalExposure(input: TemporalExposureSumInput, options?: ImageKernelRunOptions): Promise<TemporalExposureSumResult>;
+  /** Chart scene radiance or its spectral integral at many frame points (see `calculateChartRadianceBatch`). */
+  evaluateChartRadiance(input: ChartRadianceBatchInput, options?: ImageKernelRunOptions): Promise<ChartRadianceResult>;
+  dispose(): void;
+}
+```
+
+## ImageKernelAcceleratorOptions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImageKernelAcceleratorOptions {
+  /** Requested backend. `cpu-reference` is the reference and never touches WebGPU. */
+  backend: ImageKernelBackend;
+  /** Required with `webgpu-f32`: use the CPU reference (labelled) or fail when WebGPU cannot be acquired. */
+  fallback?: "cpu-reference" | "fail";
+  /** WebGPU entry point; defaults to `navigator.gpu`. Supply a worker's `navigator.gpu` explicitly if needed. */
+  gpu?: unknown;
+  powerPreference?: "low-power" | "high-performance";
+  /** Largest single GPU band buffer in bytes (4 KiB up to the device limit); default min(64 MiB, device limit). Affects memory only, never results. */
+  maximumBandBytes?: number;
+  /** Aborts adapter/device acquisition. */
+  signal?: AbortSignal;
+}
+```
+
+## ImageKernelAcceleratorState
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ImageKernelAcceleratorState = "ready" | "lost" | "disposed";
+```
+
+## ImageKernelRunOptions
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImageKernelRunOptions {
+  signal?: AbortSignal;
+  /** Yields to the host event loop between CPU reference chunks and GPU bands. Convolution, sensor and temporal stages; tasks keep their own yields. */
+  yieldControl?: (signal: AbortSignal) => Promise<void>;
+}
+```
+
+## IrradianceConvolutionResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IrradianceConvolutionResult {
+  plan: IrradianceConvolutionPlan;
+  /** Float64 for `cpu-reference`, float32 for `webgpu-f32`; row-major, same grid as the input. */
+  values: Float64Array | Float32Array;
+  /** Float64 sums of the input and output samples. Their difference is the amount lost across the grid edge. */
+  inputSum: number;
+  outputSum: number;
+  execution: ImageKernelExecution;
+}
+```
+
+## TemporalExposureSumResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface TemporalExposureSumResult {
+  plan: TemporalExposureSumPlan;
+  /** Float64 for `cpu-reference`, float32 for `webgpu-f32`; row-major, same grid as the input. */
+  values: Float64Array | Float32Array;
+  execution: ImageKernelExecution;
+}
+```

package/docs/api/gpu-image-kernel-execution.md

@@ -0,0 +1,152 @@
+# gpu/image-kernel-execution.ts public contracts
+
+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.
+
+## composeRelativeErrorBounds
+
+Composes two `relative-to-reference` bounds through a pipeline `second ∘ first`, where the second
+stage is linear with non-negative weights summing to at most `secondWeightSum` per output (convolution,
+temporal sums). With |ã − a| ≤ r₁a + a₁ elementwise and |B̃x − Bx| ≤ r₂Bx + a₂:
+|B̃ã − Ba| ≤ |B̃ã − Bã| + |B(ã − a)| ≤ r₂(1 + r₁)Ba + r₂W·a₁ + a₂ + r₁Ba + W·a₁,
+so r = r₁ + r₂ + r₁r₂ and a = a₂ + W·a₁·(1 + r₂). See docs/WEBGPU.md, "Accuracy contract".
+
+```ts
+export function composeRelativeErrorBounds(first: ImageKernelRelativeErrorBound, second: ImageKernelRelativeErrorBound,
+  secondWeightSum: number): ImageKernelRelativeErrorBound;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ImageKernelBackend
+
+Requested or actual execution backend.
+
+```ts
+export type ImageKernelBackend = "cpu-reference" | "webgpu-f32";
+```
+
+## ImageKernelCodeErrorBound
+
+Integer output codes: |code_webgpu − code_reference| ≤ maximumAbsoluteCodeDifference for every sample.
+
+```ts
+export interface ImageKernelCodeErrorBound {
+  kind: "integer-code-difference";
+  maximumAbsoluteCodeDifference: number;
+  /** Bound on the float32 linear value entering the sRGB transfer, after tone and gamut handling. */
+  linearAbsoluteBound: number;
+  /** Declared bound on the WGSL sRGB transfer evaluation (pow), see WEBGPU_F32_TRANSFER_ABSOLUTE_BOUND. */
+  transferAbsoluteBound: number;
+}
+```
+
+## ImageKernelExecution
+
+Label attached to every accelerated result.
+
+```ts
+export interface ImageKernelExecution {
+  backend: ImageKernelBackend;
+  requestedBackend: ImageKernelBackend;
+  fallbackReason: ImageKernelFallbackReason | null;
+  arithmetic: "float64" | "float32";
+  assurance: "engine-reference" | "approximation-with-a-priori-bound";
+  /**
+   * True only for `cpu-reference`. Bit-exact identities (SHA-256 artifact bindings, byte-parity fixtures,
+   * cross-engine determinism hashes) are CPU-only and must never be computed from a `webgpu-f32` result.
+   */
+  bitIdenticalToReference: boolean;
+  errorBound: ImageKernelCodeErrorBound | ImageKernelRelativeErrorBound | ImageKernelSeededRealizationBound | null;
+  /**
+   * Diagnostic counts equal the reference when no sample fell inside a float32 classification band
+   * (`diagnosticUncertaintySampleCount === 0`). Otherwise each count differs by at most that many
+   * samples.
+   */
+  diagnosticsExact: boolean;
+  diagnosticUncertaintySampleCount: number;
+  limitations: readonly string[];
+}
+```
+
+## ImageKernelExecutionError
+
+Domain error for getting and running a backend. Input validation still throws the engine's existing errors.
+
+```ts
+export class ImageKernelExecutionError extends Error {
+  readonly code = "IMAGE_KERNEL_EXECUTION";
+  readonly reason: ImageKernelFailureReason;
+
+  constructor(reason: ImageKernelFailureReason, message: string) {
+    super(message);
+    this.name = "ImageKernelExecutionError";
+    this.reason = reason;
+  }
+}
+```
+
+## ImageKernelFailureReason
+
+Failure classes reported by {@link ImageKernelExecutionError}.
+
+```ts
+export type ImageKernelFailureReason = ImageKernelFallbackReason | "device-lost" | "out-of-memory" | "gpu-validation" |
+  "aborted" | "disposed" | "busy" | "unsupported-on-backend" | "unsupported-float32-domain" | "indeterminate-float32-classification";
+```
+
+## ImageKernelFallbackReason
+
+Why a requested WebGPU backend was not used (only with `fallback: "cpu-reference"`).
+
+```ts
+export type ImageKernelFallbackReason = "webgpu-unavailable" | "adapter-unavailable" | "device-request-failed" |
+  "insufficient-limits" | "unsupported-platform-endianness";
+```
+
+## ImageKernelRelativeErrorBound
+
+Non-negative linear sums: |v_webgpu − v_reference| ≤ relative·v_reference + absolute for every sample.
+
+```ts
+export interface ImageKernelRelativeErrorBound {
+  kind: "relative-to-reference";
+  relative: number;
+  absolute: number;
+}
+```
+
+## ImageKernelSeededRealizationBound
+
+Seeded stochastic stages (the sensor stage). Random states are integer arithmetic and bit-identical to
+the reference. A site is flagged when any float32 decision (sampling test, saturation limit, rounding)
+fell inside its a-priori bound. Every unflagged site has exactly the reference code and flags; only
+flagged sites may differ, and the statistical-equivalence tests cover them (docs/WEBGPU.md).
+
+```ts
+export interface ImageKernelSeededRealizationBound {
+  kind: "exact-except-flagged-sites";
+  /** Number of flagged sites; equal to the execution's `diagnosticUncertaintySampleCount`. */
+  flaggedSiteCount: number;
+  noiseModel: { id: string; version: string };
+  seedSchedule: string;
+}
+```
+
+## WEBGPU_F32_TRANSFER_ABSOLUTE_BOUND
+
+Declared absolute error bound for the WGSL sRGB encode on [0, 1]: `1.055·pow(x, 1/2.4) − 0.055`. pow
+takes its accuracy from exp2(y·log2 x) (log2: 3 ULP, or 2^-21 absolute on [0.5, 2]; exp2: 3 + 2|x|
+ULP). The worst case over [0.0031308, 1] is about 2.5e-6. The bound 2^-17 ≈ 7.6e-6 keeps a 3× margin,
+and also covers the small jump where the sRGB segments join (< 1e-7).
+
+```ts
+WEBGPU_F32_TRANSFER_ABSOLUTE_BOUND = 2 ** -17
+```
+
+## WEBGPU_F32_UNIT_ROUNDOFF
+
+IEEE 754 binary32 unit roundoff.
+
+```ts
+WEBGPU_F32_UNIT_ROUNDOFF = 2 ** -24
+```

package/docs/api/motion-camera-rotation.md

@@ -1,6 +1,6 @@
 # motion/camera-rotation.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.
 
 ## AxisSamplingPitchMicrometers
 
@@ -18,14 +18,14 @@ export interface AxisSamplingPitchMicrometers {
 Maps one stationary-world ray to its image-plane location after pure camera
 rotation at an arbitrary physical time from exposure start.
 
-The initial image point defines the world ray in the camera frame at t=0.
-Constant angular velocity is integrated as one axis-angle rotation vector,
-avoiding Euler-order dependence. The stationary world ray is then expressed
-in the rotated camera frame using the inverse camera rotation and projected
-rectilinearly back onto the image plane.
+The starting image point defines the world ray in the camera frame at t=0.
+Constant angular velocity is integrated as a single axis-angle rotation
+vector, which avoids any dependence on Euler-angle order. The world ray is
+then expressed in the rotated camera frame with the inverse camera rotation,
+and projected rectilinearly back onto the image plane.
 
-This function models rotation only. It deliberately excludes camera
-translation because translational optical flow depends on scene depth.
+Only rotation is modelled. Camera translation is deliberately left out,
+because the image motion it causes depends on scene depth.
 
 ```ts
 export function calculateCameraRotationImageMapping(
@@ -46,7 +46,7 @@ export interface CalculateCameraRotationImageMappingInput {
   /**
    * Stationary-world-ray image-plane position at exposure start.
    *
-   * Image-plane coordinates use optical-axis origin, +X right, +Y up.
+   * Image-plane coordinates have their origin on the optical axis, +X right, +Y up.
    */
   imagePointMm: ImagePlanePointMm;
   /**
@@ -56,16 +56,20 @@ export interface CalculateCameraRotationImageMappingInput {
   /**
    * Constant camera angular-velocity vector in radians per second.
    *
-   * Components are resolved in the camera axes at exposure start and follow
-   * the right-hand rule: pitch about +X, yaw about +Y, roll about +Z.
+   * Components are given in the camera axes at exposure start and follow the
+   * physical right-hand rule:
+   * - pitch about +X: positive tilts up; content moves toward image -Y;
+   * - yaw about +Y: positive turns left; content moves toward image +X;
+   * - roll about +Z: positive is clockwise seen from behind the camera.
+   * See CameraAngularVelocityRadPerSec.
    */
   angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
   /** Optional focus distance in metres for thin-lens projection distance. */
   focusDistanceM?: number;
   /**
-   * Optional axis-aware geometric sampling pitch for reporting sample-domain
-   * displacement. This is geometric sample spacing, not photosite collection
-   * area.
+   * Optional sampling pitch per axis, used to also report the displacement in
+   * samples. This is the geometric spacing of samples, not the light-collecting
+   * area of a photosite.
    */
   samplingPitchMicrometers?: AxisSamplingPitchMicrometers;
 }
@@ -76,9 +80,9 @@ export interface CalculateCameraRotationImageMappingInput {
 Maps a captured stationary-world ray at one non-negative capture time back
 to its image-plane location at exposure start.
 
-For the existing constant-axis pure-rotation model this inverse is analytic:
-the captured ray is transformed by the forward camera rotation before
-rectilinear projection. No iterative solver is required.
+For this constant-axis, pure-rotation model the inverse is analytic: apply
+the forward camera rotation to the captured ray, then project
+rectilinearly. No iterative solver is needed.
 
 ```ts
 export function calculateInverseCameraRotationImageMapping(
@@ -98,7 +102,7 @@ export interface CalculateInverseCameraRotationImageMappingInput {
   focalLengthMm: number;
   /**
    * Captured image-plane location of a stationary world ray at the requested
-   * time. Coordinates use optical-axis origin, +X right and +Y up.
+   * time. Coordinates have their origin on the optical axis, +X right, +Y up.
    */
   imagePointMm: ImagePlanePointMm;
   /**
@@ -114,8 +118,8 @@ export interface CalculateInverseCameraRotationImageMappingInput {
   /** Optional focus distance in metres for thin-lens projection distance. */
   focusDistanceM?: number;
   /**
-   * Optional axis-aware geometric sampling pitch for reporting sample-domain
-   * inverse displacement.
+   * Optional sampling pitch per axis, used to also report the inverse
+   * displacement in samples.
    */
   samplingPitchMicrometers?: AxisSamplingPitchMicrometers;
 }
@@ -123,15 +127,28 @@ export interface CalculateInverseCameraRotationImageMappingInput {
 
 ## CameraAngularVelocityRadPerSec
 
-The exact contract is declared below; use the domain guide for assumptions and staged integration.
+Camera angular velocity in radians per second about the exposure-start
+camera axes (+X right, +Y up, +Z forward along the optical axis).
+
+Signs follow the physical right-hand rule about each named axis. These axes
+form a left-handed basis. So a positive rotation is the mirror image of what
+the plain component Rodrigues (cross-product) formula would give in it:
+
+- Positive pitch tilts the optical axis up. Still scene content moves
+  toward image -Y (down).
+- Positive yaw turns the optical axis left (counter-clockwise seen from
+  above). Still scene content moves toward image +X (right).
+- Positive roll turns the camera clockwise, as seen by the photographer
+  looking along +Z. Still scene content rotates counter-clockwise in the
+  +X-right/+Y-up image plane.
 
 ```ts
 export interface CameraAngularVelocityRadPerSec {
-  /** Right-hand rotation rate about camera +X (right), in radians per second. */
+  /** Right-hand rotation rate about camera +X (right): positive tilts the optical axis up. */
   pitch: number;
-  /** Right-hand rotation rate about camera +Y (up), in radians per second. */
+  /** Right-hand rotation rate about camera +Y (up): positive turns the optical axis left. */
   yaw: number;
-  /** Right-hand rotation rate about camera +Z (forward), in radians per second. */
+  /** Right-hand rotation rate about camera +Z (forward): positive rolls the camera clockwise as seen from behind it. */
   roll: number;
 }
 ```
@@ -158,8 +175,8 @@ export interface CameraRotationImageMapping {
     distance: number;
   };
   /**
-   * Optional geometric sample displacement in the image-plane basis
-   * (+X right, +Y up). This is not a native-raster vector.
+   * Optional displacement in samples, in image-plane axes (+X right, +Y up).
+   * This is not a vector in native raster axes.
    */
   deltaImagePlaneSamples?: {
     x: number;

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

@@ -1,24 +1,24 @@
 # motion/capture-rotation-inverse-mapping.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.
 
 ## calculateCaptureRotationInverseMappings
 
-Calculates an instantaneous inverse capture-scan mapping for stationary
-world rays under pure camera rotation.
+Calculates an instantaneous inverse capture-scan mapping for still world
+rays under pure camera rotation.
 
-The destination native sensor location is authoritative for local exposure
-timing. At an explicit phase within that local window, the captured
-image-plane ray is analytically mapped back to the reference image plane at
-the first opening-boundary phase.
+The destination point on the native sensor sets the local exposure timing.
+At a chosen phase within that local window, the captured image-plane ray is
+mapped back analytically to the reference image plane at the first
+opening-boundary phase.
 
-No fixed-point/iterative solve is used because pure rotation under the
-existing constant-axis model has an analytic inverse once destination
-location and local capture time are known.
+No iterative solve is needed. Once the destination and local capture time
+are known, pure rotation under this constant-axis model has an analytic
+inverse.
 
-This function is not a finite-exposure renderer and does not integrate blur.
-Sensor data-readout timing is deliberately absent; exposure boundaries are
-the only timing source.
+This is not a renderer for a finite exposure, and it does not integrate
+blur. Sensor data-readout timing is deliberately not used; exposure
+boundaries are the only timing source.
 
 ```ts
 export function calculateCaptureRotationInverseMappings(
@@ -40,17 +40,18 @@ export interface CalculateCaptureRotationInverseMappingsInput
   focusDistanceM?: number;
   angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
   /**
-   * Fraction of each point's local exposure interval at which the
-   * instantaneous mapping is evaluated.
+   * Where in each point's local exposure interval to evaluate the
+   * instantaneous mapping, as a fraction.
    *
    * 0 = local exposure start, 0.5 = local midpoint, 1 = local exposure end.
-   * A phase is required because finite exposure has no single sharp geometry.
+   * A phase is required because a finite exposure has no single sharp
+   * geometry.
    */
   localExposurePhase: number;
   /**
-   * Physical capture orientation used only to rotate the reported native
-   * inverse sample-displacement vector into oriented-capture coordinates.
-   * It does not alter the native exposure schedule.
+   * Physical capture orientation. It is used only to rotate the reported
+   * native inverse displacement (in samples) into oriented-capture
+   * coordinates. It does not change the native exposure schedule.
    */
   orientation: CaptureOrientation;
   samplePointsNative: readonly RasterPoint[];
@@ -101,8 +102,8 @@ export interface CaptureRotationInverseMappingSample {
   localExposurePhase: number;
   captureTimeSecondsFromReference: number;
   /**
-   * Same stationary world ray expressed in the exposure-start reference image
-   * plane. This may lie outside the active capture; it is intentionally not
+   * The same still world ray on the reference image plane at exposure start.
+   * It may lie outside the active capture area; it is deliberately not
    * clamped.
    */
   referenceImagePointMm: ImagePlanePointMm;
@@ -112,8 +113,8 @@ export interface CaptureRotationInverseMappingSample {
     distance: number;
   };
   /**
-   * Reference-minus-destination displacement in continuous native effective
-   * raster-sample units (+X right, +Y down).
+   * Reference minus destination displacement, in continuous native effective
+   * raster samples (+X right, +Y down).
    */
   inverseDisplacementNativeSamples: RasterVector & {
     distance: number;

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

@@ -1,26 +1,26 @@
 # motion/capture-rotation-temporal-quadrature.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.
 
 ## calculateCaptureRotationTemporalQuadrature
 
-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.
 
 ```ts
 export function calculateCaptureRotationTemporalQuadrature(
@@ -41,8 +41,8 @@ export interface CalculateCaptureRotationTemporalQuadratureInput
     "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;
 }
@@ -83,15 +83,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;