@photivra/engine 0.5.1 → 1.0.0

package/docs/api/exposure-metering-target.md

@@ -0,0 +1,134 @@
+# exposure/metering-target.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## createExposureMeterTargetFromMeteringResult
+
+Freezes one metering result into the stable relative exposure target
+consumed by downstream camera-control policy.
+
+The target copies the meter snapshot by value. Future scene/light changes do
+not mutate this object, which is the engine seam needed for AE-lock behavior.
+
+```ts
+export function createExposureMeterTargetFromMeteringResult(
+  input:
+    CreateExposureMeterTargetInput
+): ExposureMeterTarget;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateExposureMeterTargetInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateExposureMeterTargetInput {
+  targetId: string;
+  meterResult:
+    ExposureMeterTargetSourceResult;
+}
+```
+
+## EXPOSURE_METER_TARGET_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+EXPOSURE_METER_TARGET_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## ExposureMeterSnapshotIdentity
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExposureMeterSnapshotIdentity {
+  sourceKind:
+    ExposureMeterTargetSourceKind;
+  measurementId: string;
+  sceneStateId: string;
+  meteringProfileId: string;
+}
+```
+
+## ExposureMeterTarget
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ExposureMeterTarget =
+  | (ExposureMeterTargetBase & {
+      status: "resolved";
+      baseRequiredExposureScaleToTarget:
+        number;
+      baseExposureOffsetStopsToTarget:
+        number;
+      requiredExposureScaleToTarget:
+        number;
+      exposureOffsetStopsToTarget:
+        number;
+    })
+  | (ExposureMeterTargetBase & {
+      status: "no-signal";
+      baseRequiredExposureScaleResolved:
+        false;
+      baseExposureOffsetStopsResolved:
+        false;
+      requiredExposureScaleResolved:
+        false;
+      exposureOffsetStopsResolved:
+        false;
+    });
+```
+
+## ExposureMeterTargetSourceKind
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ExposureMeterTargetSourceKind =
+  | "spatial-metering-result"
+  | "temporal-metering-result";
+```
+
+## ExposureMeterTargetSourceResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ExposureMeterTargetSourceResult =
+  | ExposureMeteringResult
+  | SceneRadianceTemporalExposureMeteringResult;
+```
+
+## setExposureCompensationOnMeterTarget
+
+Sets an absolute exposure-compensation value on a frozen meter target.
+
+Compensation is always re-derived from the uncompensated base target, so
+repeated UI updates cannot accidentally accumulate floating-point/control
+drift. Positive compensation requests more exposure.
+
+```ts
+export function setExposureCompensationOnMeterTarget(
+  input:
+    SetExposureCompensationOnMeterTargetInput
+): ExposureMeterTarget;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SetExposureCompensationOnMeterTargetInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SetExposureCompensationOnMeterTargetInput {
+  targetId: string;
+  baseTarget: ExposureMeterTarget;
+  exposureCompensationStops: number;
+}
+```

package/docs/api/exposure-metering-temporal.md

@@ -0,0 +1,77 @@
+# exposure/metering-temporal.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## meterSceneRadianceTemporalExposure
+
+Meters a declared weighted time-average of scene-radiance-derived relative
+pre-exposure samples.
+
+Every temporal sample must already be explicitly bound to one #85 temporal
+illumination profile and one capture time in the
+first-opening-boundary-phase reference. Spatial metering is performed first
+in the same declared profile, then those scalar pre-exposure measurements are
+combined linearly by caller-declared normalized time weights.
+
+```ts
+export function meterSceneRadianceTemporalExposure(
+  input:
+    MeterSceneRadianceTemporalExposureInput
+): CalculationResult<
+  SceneRadianceTemporalExposureMeteringResult
+>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## MeterSceneRadianceTemporalExposureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MeterSceneRadianceTemporalExposureInput {
+  temporalMeasurementId: string;
+  profile: ExposureMeteringProfile;
+  policy: {
+    kind: "weighted-time-average";
+    timeReference:
+      "first-opening-boundary-phase";
+  };
+  temporalSamples:
+    readonly SceneRadianceTemporalMeteringSample[];
+}
+```
+
+## SceneRadianceTemporalExposureMeteringResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneRadianceTemporalExposureMeteringResult =
+  | (SceneRadianceTemporalExposureMeteringResultBase & {
+      status: "resolved";
+      requiredExposureScaleToTarget:
+        number;
+      exposureOffsetStopsToTarget:
+        number;
+    })
+  | (SceneRadianceTemporalExposureMeteringResultBase & {
+      status: "no-signal";
+      requiredExposureScaleResolved:
+        false;
+      exposureOffsetStopsResolved:
+        false;
+    });
+```
+
+## SceneRadianceTemporalMeteringSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneRadianceTemporalMeteringSample {
+  normalizedTimeWeight: number;
+  sampleSet:
+    SceneRadianceDerivedExposureMeteringSampleSet;
+}
+```

package/docs/api/exposure-metering.md

@@ -0,0 +1,172 @@
+# exposure/metering.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## EXPOSURE_METERING_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+EXPOSURE_METERING_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## ExposureMeteringPolicy
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ExposureMeteringPolicy =
+  | {
+      kind: "multi-zone-uniform";
+    }
+  | {
+      kind: "center-weighted-radial";
+      edgeWeight: number;
+      exponent: number;
+    }
+  | {
+      kind: "spot";
+      centerOrientedCaptureUv:
+        NormalizedRasterUv;
+      radiusFractionOfCaptureDiagonal:
+        number;
+    }
+  | {
+      kind: "highlight-weighted";
+      minimumWeightFraction: number;
+      exponent: number;
+    };
+```
+
+## ExposureMeteringProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExposureMeteringProfile {
+  schemaVersion:
+    typeof EXPOSURE_METERING_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  scientificStatus: "approximation";
+  inputDomain:
+    "relative-pre-exposure-linear-signal";
+  captureRegion:
+    "oriented-active-capture";
+  policy: ExposureMeteringPolicy;
+  target: {
+    kind: "relative-signal-reference";
+    targetRelativeSignal: number;
+    evidence: readonly EvidenceProvenance[];
+  };
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## ExposureMeteringResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ExposureMeteringResult =
+  | (ExposureMeteringResultBase & {
+      status: "resolved";
+      requiredExposureScaleToTarget:
+        number;
+      exposureOffsetStopsToTarget:
+        number;
+    })
+  | (ExposureMeteringResultBase & {
+      status: "no-signal";
+      requiredExposureScaleResolved:
+        false;
+      exposureOffsetStopsResolved:
+        false;
+    });
+```
+
+## ExposureMeteringSampleSet
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExposureMeteringSampleSet {
+  measurementId: string;
+  sceneStateId: string;
+  inputDomain:
+    "relative-pre-exposure-linear-signal";
+  captureRegion:
+    "oriented-active-capture";
+  captureGeometry:
+    ResolvedCaptureGeometry;
+  processingState: {
+    exposureSettingsApplied: false;
+    whiteBalanceApplied: false;
+    toneMappingApplied: false;
+    displayGammaApplied: false;
+    sharpeningApplied: false;
+  };
+  samples:
+    readonly ExposureMeteringZoneSample[];
+}
+```
+
+## ExposureMeteringZoneSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExposureMeteringZoneSample {
+  sampleId: string;
+  positionOrientedCaptureUv:
+    NormalizedRasterUv;
+  relativeLinearSignal: number;
+  areaWeight: number;
+}
+```
+
+## meterRelativeExposure
+
+Meters relative pre-exposure linear signal over the actual oriented active
+capture frame.
+
+The first contract is an educational/relative approximation. It is
+intentionally independent of final output crop, display/tone mapping,
+exposure compensation, and automatic exposure setting resolution.
+
+```ts
+export function meterRelativeExposure(
+  input:
+    MeterRelativeExposureInput
+): CalculationResult<ExposureMeteringResult>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## MeterRelativeExposureInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface MeterRelativeExposureInput {
+  profile: ExposureMeteringProfile;
+  sampleSet: ExposureMeteringSampleSet;
+}
+```
+
+## parseExposureMeteringProfile
+
+Parses one generic relative exposure-metering profile.
+
+Schema 0.1.0 is approximation-only and consumes relative pre-exposure
+linear signal. It deliberately does not claim luminance, spectral radiance,
+sensor-plane irradiance, or a specific manufacturer's meter calibration.
+
+```ts
+export function parseExposureMeteringProfile(
+  value: unknown
+): ExposureMeteringProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/exposure-program-line.md

@@ -0,0 +1,64 @@
+# exposure/program-line.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## EXPOSURE_PROGRAM_LINE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+EXPOSURE_PROGRAM_LINE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## ExposureProgramLineNode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExposureProgramLineNode {
+  nodeId: string;
+  opticalExposureStopsFromReference: number;
+  aperture: number;
+  shutterSeconds: number;
+}
+```
+
+## ExposureProgramLineProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExposureProgramLineProfile {
+  schemaVersion:
+    typeof EXPOSURE_PROGRAM_LINE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  scientificStatus: "approximation";
+  policyKind:
+    "generic-program-line";
+  interpolation:
+    "log2-aperture-shutter";
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+  nodes:
+    readonly ExposureProgramLineNode[];
+}
+```
+
+## parseExposureProgramLineProfile
+
+Parses a generic educational/product exposure program line.
+
+A program line is control policy, not physics. Nodes declare desired
+aperture/shutter pairs at explicit optical-exposure stops relative to the
+resolver's reference exposure. Resolution later verifies that every node is
+physically consistent with that reference and current equipment capability.
+
+```ts
+export function parseExposureProgramLineProfile(
+  value: unknown
+): ExposureProgramLineProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

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

@@ -0,0 +1,215 @@
+# motion/camera-rotation.ts public contracts
+
+Package **1.0.0**, root API **0.116.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+
+## AxisSamplingPitchMicrometers
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AxisSamplingPitchMicrometers {
+  x: number;
+  y: number;
+}
+```
+
+## calculateCameraRotationImageMapping
+
+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.
+
+This function models rotation only. It deliberately excludes camera
+translation because translational optical flow depends on scene depth.
+
+```ts
+export function calculateCameraRotationImageMapping(
+  input: CalculateCameraRotationImageMappingInput
+): CalculationResult<CameraRotationImageMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCameraRotationImageMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCameraRotationImageMappingInput {
+  /** Physical focal length in millimetres. */
+  focalLengthMm: number;
+  /**
+   * Stationary-world-ray image-plane position at exposure start.
+   *
+   * Image-plane coordinates use optical-axis origin, +X right, +Y up.
+   */
+  imagePointMm: ImagePlanePointMm;
+  /**
+   * Time in seconds from exposure start. Must be greater than or equal to zero.
+   */
+  timeSecondsFromExposureStart: number;
+  /**
+   * 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.
+   */
+  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.
+   */
+  samplingPitchMicrometers?: AxisSamplingPitchMicrometers;
+}
+```
+
+## calculateInverseCameraRotationImageMapping
+
+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.
+
+```ts
+export function calculateInverseCameraRotationImageMapping(
+  input: CalculateInverseCameraRotationImageMappingInput
+): CalculationResult<InverseCameraRotationImageMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateInverseCameraRotationImageMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateInverseCameraRotationImageMappingInput {
+  /** Physical focal length in millimetres. */
+  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.
+   */
+  imagePointMm: ImagePlanePointMm;
+  /**
+   * Capture time in seconds from exposure start. Must be greater than or equal
+   * to zero.
+   */
+  timeSecondsFromExposureStart: number;
+  /**
+   * Constant camera angular-velocity vector in radians per second, with the
+   * same sign/axis semantics as calculateCameraRotationImageMapping().
+   */
+  angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;
+  /** Optional focus distance in metres for thin-lens projection distance. */
+  focusDistanceM?: number;
+  /**
+   * Optional axis-aware geometric sampling pitch for reporting sample-domain
+   * inverse displacement.
+   */
+  samplingPitchMicrometers?: AxisSamplingPitchMicrometers;
+}
+```
+
+## CameraAngularVelocityRadPerSec
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CameraAngularVelocityRadPerSec {
+  /** Right-hand rotation rate about camera +X (right), in radians per second. */
+  pitch: number;
+  /** Right-hand rotation rate about camera +Y (up), in radians per second. */
+  yaw: number;
+  /** Right-hand rotation rate about camera +Z (forward), in radians per second. */
+  roll: number;
+}
+```
+
+## CameraRotationImageMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CameraRotationImageMapping {
+  projectionDistanceMm: number;
+  timeSecondsFromExposureStart: number;
+  angularDisplacementRad: {
+    pitch: number;
+    yaw: number;
+    roll: number;
+    magnitude: number;
+  };
+  startImagePointMm: ImagePlanePointMm;
+  mappedImagePointMm: ImagePlanePointMm;
+  deltaMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+  /**
+   * Optional geometric sample displacement in the image-plane basis
+   * (+X right, +Y up). This is not a native-raster vector.
+   */
+  deltaImagePlaneSamples?: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+}
+```
+
+## ImagePlanePointMm
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImagePlanePointMm {
+  /** Image-plane X coordinate relative to the optical axis, in millimetres. */
+  x: number;
+  /** Image-plane Y coordinate relative to the optical axis, in millimetres. */
+  y: number;
+}
+```
+
+## InverseCameraRotationImageMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface InverseCameraRotationImageMapping {
+  projectionDistanceMm: number;
+  timeSecondsFromExposureStart: number;
+  angularDisplacementRad: {
+    pitch: number;
+    yaw: number;
+    roll: number;
+    magnitude: number;
+  };
+  capturedImagePointMm: ImagePlanePointMm;
+  referenceImagePointMm: ImagePlanePointMm;
+  /**
+   * Reference-minus-captured displacement in the image-plane basis.
+   */
+  deltaMm: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+  deltaImagePlaneSamples?: {
+    x: number;
+    y: number;
+    distance: number;
+  };
+}
+```