@photivra/engine 0.6.0 → 1.0.1

package/docs/api/output-crop.md

@@ -0,0 +1,47 @@
+# output/crop.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## calculateCenteredCrop
+
+Calculates dimensions remaining after a centered, same-aspect-ratio crop.
+
+```ts
+export function calculateCenteredCrop(
+  input: CalculateCenteredCropInput
+): CalculationResult<CenteredCrop>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateCenteredCropInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateCenteredCropInput {
+  /** Original image width in pixels. */
+  pixelWidth: number;
+  /** Original image height in pixels. */
+  pixelHeight: number;
+  /**
+   * Linear crop factor. 1 means no crop; 1.5 retains 1 / 1.5 of each
+   * dimension while preserving aspect ratio.
+   */
+  cropFactor: number;
+}
+```
+
+## CenteredCrop
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CenteredCrop {
+  pixelWidth: number;
+  pixelHeight: number;
+  megapixels: number;
+  /** Fraction of original pixel area retained, from 0 to 1. */
+  retainedAreaFraction: number;
+}
+```

package/docs/api/output-geometric-transforms.md

@@ -0,0 +1,199 @@
+# output/geometric-transforms.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## AffineGeometricTransform
+
+Explicit destination-to-source affine map, including rotation/shear/offset.
+
+```ts
+export interface AffineGeometricTransform extends TransformIdentity {
+  kind: "affine";
+  matrix: GeometricJacobian;
+  offsetMm: LensFieldPointMm;
+}
+```
+
+## calculateComposedGeometricMapping
+
+Authoritative display-to-capture map and full local directional derivatives.
+
+```ts
+export function calculateComposedGeometricMapping(input: {
+  mapping: PreparedGeometricMapping; destinationPointMm: LensFieldPointMm;
+}): CalculationResult<GeometricMappingPoint>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateForwardGeometricMapping
+
+Capture-to-display bridge for focus, metering and overlays; reverses the same maps.
+
+```ts
+export function calculateForwardGeometricMapping(input: {
+  mapping: PreparedGeometricMapping; sourcePointMm: LensFieldPointMm;
+}): CalculationResult<LensFieldPointMm>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateGeometricResampling
+
+Samples an already-formed scalar image once; null output marks missing source support.
+
+```ts
+export function calculateGeometricResampling(input: {
+  plan: GeometricSamplingPlan; sourceSamples: readonly number[];
+}): CalculationResult<{ samples: readonly (number | null)[]; resamplePasses: 1; resampler: GeometricResampler }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculateGeometricSamplingPlan
+
+Resolves one joint validity/crop/AA plan after composing compatible inverse maps.
+
+```ts
+export function calculateGeometricSamplingPlan(input: {
+  mapping: PreparedGeometricMapping; sourceRaster: GeometricRaster; destinationRaster: GeometricRaster;
+  resampler: GeometricResampler; physicalProjectionDistanceMm: number;
+}): CalculationResult<GeometricSamplingPlan>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## DigitalGeometricTransform
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type DigitalGeometricTransform = AffineGeometricTransform | RadialGeometricTransform;
+```
+
+## GeometricImageDomain
+
+Domains are barriers: only contiguous equal-domain maps share a resample.
+
+```ts
+export type GeometricImageDomain = "raw-channel" | "reconstructed-linear" | "processed-output";
+```
+
+## GeometricJacobian
+
+Row-major derivative d(source mm)/d(destination mm).
+
+```ts
+export type GeometricJacobian = readonly [number, number, number, number];
+```
+
+## GeometricMappingPoint
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GeometricMappingPoint {
+  sourcePointMm: LensFieldPointMm;
+  jacobian: GeometricJacobian;
+  determinant: number;
+  principalStretches: readonly [number, number];
+  anisotropy: number;
+  components: readonly { id: string; sourcePointMm: LensFieldPointMm; jacobian: GeometricJacobian }[];
+}
+```
+
+## GeometricRaster
+
+Regular pixel centers on the optical plane: +X right, +Y up; row order down.
+
+```ts
+export interface GeometricRaster {
+  width: number;
+  height: number;
+  centerMm: LensFieldPointMm;
+  pitchMm: number;
+}
+```
+
+## GeometricResampler
+
+Resampler identity is independent of mapping. Prefiltering is a caller obligation.
+
+```ts
+export interface GeometricResampler {
+  id: string;
+  version: string;
+  filter: "nearest" | "bilinear";
+  antialias: "none" | "source-prefiltered";
+}
+```
+
+## GeometricSamplingPlan
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GeometricSamplingPlan {
+  mapping: PreparedGeometricMapping;
+  sourceRaster: GeometricRaster;
+  destinationRaster: GeometricRaster;
+  resampler: GeometricResampler;
+  points: readonly GeometricMappingPoint[];
+  /** Includes exact center-domain support for the selected filter; no edge extension. */
+  validSourceMask: readonly boolean[];
+  /** Largest all-valid axis-aligned pixel rectangle, half-open. Null if empty. */
+  jointCrop: { x: number; y: number; width: number; height: number } | null;
+  requiresPrefilter: boolean;
+  canResample: boolean;
+  physicalCapturedFovDegrees: { horizontal: number; vertical: number };
+  /** Envelope of mapped pixel-center rays retained by the joint crop, not edge FOV. */
+  retainedSampleRayEnvelopeDegrees: { minX: number; maxX: number; minY: number; maxY: number } | null;
+}
+```
+
+## parseDigitalGeometricTransform
+
+Parses strict transform data, rejecting unknown semantics and noninvertible profiles.
+
+```ts
+export function parseDigitalGeometricTransform(value: unknown): DigitalGeometricTransform;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PreparedGeometricMapping
+
+Serializable prepared state. Maps are applied in listed destination-to-source order.
+
+```ts
+export interface PreparedGeometricMapping {
+  schemaVersion: "0.1.0";
+  frameTimeSeconds: number;
+  transforms: readonly DigitalGeometricTransform[];
+  semanticKey: string;
+  groups: readonly { domain: GeometricImageDomain; componentIds: readonly string[] }[];
+}
+```
+
+## prepareGeometricMapping
+
+Prepares deterministic still/frame geometry; time changes require another preparation.
+
+```ts
+export function prepareGeometricMapping(input: {
+  transforms: readonly DigitalGeometricTransform[]; frameTimeSeconds: number;
+}): CalculationResult<PreparedGeometricMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## RadialGeometricTransform
+
+Correction samples physical distorted data at the mapped ideal destination.
+
+```ts
+export interface RadialGeometricTransform extends TransformIdentity {
+  kind: "radial";
+  profile: RadialDistortionProfile;
+}
+```

package/docs/api/output-lens-corrections.md

@@ -0,0 +1,162 @@
+# output/lens-corrections.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## calculateLensCorrectedCapture
+
+Executes bounded reconstructed-linear corrections on already sampled RGB channels.
+Compatible common geometry plus channel CA is sampled once per channel.
+A gain between geometry components or incompatible domains requires an external staged consumer.
+
+```ts
+export function calculateLensCorrectedCapture(input: {
+  plan: ResolvedLensCorrectionPlan; capture: LensCorrectionCapture;
+  destinationRaster: GeometricRaster; resampler: GeometricResampler;
+  physicalProjectionDistanceMm: number; clippingLevel: number;
+}): CalculationResult<{
+  captureId: string; noiseRealizationId: string; timeSeconds: number;
+  application: ResolvedLensCorrectionPlan["application"];
+  channels: Readonly<Record<LensCorrectionChannel, readonly (number | null)[]>>;
+  samplingPlans: Partial<Record<LensCorrectionChannel, GeometricSamplingPlan>>;
+  /** Intersection across all channel footprints, before crop; no missing colors fabricated. */
+  validSourceMask: readonly boolean[];
+  jointCrop: GeometricSamplingPlan["jointCrop"];
+  /** Gain-stage clipping events before joint support/crop; repeated stages count separately. */
+  illuminationClippingEventCount: number;
+}>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculatePeripheralIlluminationCorrection
+
+Applies scalar post-capture gain and reports pre-clip variance; no photon/SNR history rewrite.
+
+```ts
+export function calculatePeripheralIlluminationCorrection(input: {
+  component: IlluminationLensCorrection; imagePointMm: LensFieldPointMm;
+  signal: number; noiseVariance: number; clippingLevel: number;
+}): CalculationResult<{ gain: number; signalBeforeClipping: number; signal: number; noiseVarianceBeforeClipping: number; clipped: boolean }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## GenericLensCorrectionProfile
+
+Exact generic system binding, with components in authoritative application order.
+
+```ts
+export interface GenericLensCorrectionProfile {
+  schemaVersion: "0.1.0";
+  id: string;
+  version: string;
+  state: OpticalProfileState;
+  evidence: GenericOpticalEvidence;
+  components: readonly LensCorrectionComponent[];
+}
+```
+
+## GeometricLensCorrection
+
+A separately declared correction map may deliberately retain physical distortion.
+
+```ts
+export interface GeometricLensCorrection extends CorrectionComponentIdentity {
+  kind: "geometry";
+  transform: DigitalGeometricTransform;
+}
+```
+
+## IlluminationLensCorrection
+
+Post-capture scalar gain; strength 0..1 leaves explicit residual falloff.
+
+```ts
+export interface IlluminationLensCorrection extends CorrectionComponentIdentity {
+  kind: "peripheral-illumination";
+  profile: IlluminationVignettingProfile;
+  strength: number;
+}
+```
+
+## LateralCaLensCorrection
+
+Channel registration only, not longitudinal CA or color shading.
+
+```ts
+export interface LateralCaLensCorrection extends CorrectionComponentIdentity {
+  kind: "lateral-ca";
+  transforms: Readonly<Record<LensCorrectionChannel, DigitalGeometricTransform>>;
+}
+```
+
+## LensCorrectionCapture
+
+Immutable capture identity accompanies downstream channels for meaningful On/Off comparisons.
+
+```ts
+export interface LensCorrectionCapture {
+  state: OpticalProfileState;
+  captureId: string;
+  noiseRealizationId: string;
+  timeSeconds: number;
+  raster: GeometricRaster;
+  channels: Readonly<Record<LensCorrectionChannel, readonly number[]>>;
+}
+```
+
+## LensCorrectionChannel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type LensCorrectionChannel = "red" | "green" | "blue";
+```
+
+## LensCorrectionComponent
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type LensCorrectionComponent = GeometricLensCorrection | LateralCaLensCorrection | IlluminationLensCorrection;
+```
+
+## parseGenericLensCorrectionProfile
+
+Strict parser for generic system corrections; no extrapolation or restoration claim.
+
+```ts
+export function parseGenericLensCorrectionProfile(value: unknown): GenericLensCorrectionProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedLensCorrectionPlan
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedLensCorrectionPlan {
+  profile: GenericLensCorrectionProfile;
+  outputKind: "raw-like" | "processed";
+  selectionKind: "camera-selectable" | "reference-bypass";
+  components: readonly { component: LensCorrectionComponent; enabled: boolean;
+    reason: "selected" | "default" | "mandatory" | "stabilization-dependency" | "component-dependency" | "reference-bypass" }[];
+  /** RAW-like intent remains metadata only in this first foundation. */
+  application: "metadata-only" | "bake-downstream";
+}
+```
+
+## resolveLensCorrectionPlan
+
+Resolves independent camera states, explicit dependencies, RAW intent and educational bypass.
+
+```ts
+export function resolveLensCorrectionPlan(input: {
+  profile: GenericLensCorrectionProfile; state: OpticalProfileState;
+  selections: Readonly<Record<string, "on" | "off" | "auto">>;
+  outputKind: "raw-like" | "processed"; selectionKind: "camera-selectable" | "reference-bypass";
+}): CalculationResult<ResolvedLensCorrectionPlan>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/output-sdr-rendering.md

@@ -0,0 +1,122 @@
+# output/sdr-rendering.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## calculateSdrRendering
+
+Standalone SDR rendering: rendering exposure → tone → gamut → sRGB transfer → quantization.
+No physical capture, metering, WB/color/correction integration or display adaptation runs.
+
+```ts
+export function calculateSdrRendering(input: SdrRenderingInput): CalculationResult<SdrRenderingResult>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSdrRenderingInput
+
+Validates declared image state and a bounded finite inline raster; never resolves WB/color.
+
+```ts
+export function parseSdrRenderingInput(value: unknown): SdrRenderingInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSdrRenderingProfile
+
+Validates every explicit rendering/encoding policy; unknown HDR/display modes fail.
+
+```ts
+export function parseSdrRenderingProfile(value: unknown): SdrRenderingProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SDR_RENDERING_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SDR_RENDERING_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## SdrRenderingInput
+
+Only an explicitly color-transformed, co-sited linear-sRGB/D65 raster is accepted.
+
+```ts
+export interface SdrRenderingInput {
+  sourceImageStateId: string;
+  inputImageState: "color-transformed-linear-rgb";
+  inputColorSpace: "linear-srgb-d65";
+  whiteBalanceHandling: "already-applied-upstream" | "not-required";
+  pixelWidth: number;
+  pixelHeight: number;
+  referenceWhiteValue: number;
+  /** Relative linear RGB, row-major tightly interleaved red/green/blue. */
+  samples: readonly number[];
+  profile: SdrRenderingProfile;
+}
+```
+
+## SdrRenderingProfile
+
+First-party rendering choices, independent of physical exposure and display calibration.
+
+```ts
+export interface SdrRenderingProfile {
+  schemaVersion: typeof SDR_RENDERING_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  renderingExposureEv: number;
+  toneCurve: "identity" | "positive-reinhard-per-channel";
+  gamutHandling: "clip-components" | "reject-out-of-range";
+  outputDynamicRange: "sdr";
+  transferFunction: "srgb";
+  bitDepth: 8 | 16;
+  rounding: "nearest-ties-up";
+  dither: "none";
+}
+```
+
+## SdrRenderingResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SdrRenderingResult {
+  schemaVersion: typeof SDR_RENDERING_SCHEMA_VERSION;
+  sourceImageStateId: string;
+  profile: SdrRenderingProfile;
+  pixelWidth: number;
+  pixelHeight: number;
+  channelOrder: readonly ["red", "green", "blue"];
+  whiteBalanceHandling: SdrRenderingInput["whiteBalanceHandling"];
+  /** Relative normalized linear samples after exposure/tone, before gamut handling. */
+  toneMappedLinearSamples: readonly number[];
+  outputLinearSamples: readonly number[];
+  outputEncodedSamples: readonly number[];
+  integerSamples: readonly number[];
+  outputEncoding: {
+    imageState: "output-referred-sdr";
+    colorSpace: "srgb";
+    primariesXy: { red: readonly [number, number]; green: readonly [number, number]; blue: readonly [number, number] };
+    whitePointXy: readonly [number, number];
+    referenceWhiteLuminanceCdM2: 80;
+    codeMinimum: 0;
+    codeMaximum: number;
+  };
+  diagnostics: {
+    renderingNegativeSampleCount: number;
+    renderingAboveReferenceSampleCount: number;
+    toneChangedSampleCount: number;
+    gamutClippedLowSampleCount: number;
+    gamutClippedHighSampleCount: number;
+    /** Upstream full-well/ADC/RAW saturation is unavailable, never inferred from output. */
+    captureSaturation: "not-consumed";
+  };
+  /** Platform color management follows this encoded output; no actual display is assessed. */
+  displayAdaptation: { kind: "external-platform"; applied: false; displayCapabilities: "unknown" };
+}
+```

package/docs/api/output-subject-framing-crop.md

@@ -0,0 +1,59 @@
+# output/subject-framing-crop.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## calculateSubjectFramingCrop
+
+Calculates the same-aspect-ratio crop needed for a subject to occupy a
+requested fraction of frame height.
+
+This calculation assumes a centered/positionable crop with enough spatial
+margin around the subject. It does not validate subject position against
+image edges.
+
+```ts
+export function calculateSubjectFramingCrop(
+  input: CalculateSubjectFramingCropInput
+): CalculationResult<SubjectFramingCrop>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateSubjectFramingCropInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateSubjectFramingCropInput {
+  /** Source image width in pixels. */
+  pixelWidth: number;
+  /** Source image height in pixels. */
+  pixelHeight: number;
+  /** Projected subject height in source-image pixels. */
+  subjectHeightPixels: number;
+  /** Desired subject height as a fraction of output frame height, >0 and <=1. */
+  targetSubjectHeightFraction: number;
+}
+```
+
+## SubjectFramingCrop
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SubjectFramingCrop {
+  cropFactor: number;
+  pixelWidth: number;
+  pixelHeight: number;
+  megapixels: number;
+  /**
+   * Actual subject height divided by cropped frame height.
+   * Values greater than 1 mean the subject is taller than the output frame.
+   */
+  subjectHeightFraction: number;
+  /** Whether the projected subject exceeds the cropped frame height. */
+  subjectClipped: boolean;
+  /** Whether achieving the target required an additional crop. */
+  cropped: boolean;
+}
+```

package/docs/api/schema-camera.md

@@ -0,0 +1,84 @@
+# schema/camera.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## CameraConfiguration
+
+Renderer-independent camera configuration consumed by simulation modules.
+
+```ts
+export interface CameraConfiguration {
+  sensor: SensorConfiguration;
+  lens: LensConfiguration;
+  exposure: ExposureConfiguration;
+  focus: FocusConfiguration;
+  stabilization?: StabilizationConfiguration;
+}
+```
+
+## CameraSupport
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type CameraSupport = "handheld" | "braced" | "monopod" | "tripod";
+```
+
+## ExposureConfiguration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ExposureConfiguration {
+  shutterSeconds: number;
+  iso: number;
+}
+```
+
+## FocusConfiguration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FocusConfiguration {
+  focusDistanceM: number;
+}
+```
+
+## LensConfiguration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensConfiguration {
+  focalLengthMm: number;
+  aperture: number;
+}
+```
+
+## SensorConfiguration
+
+The legacy CameraConfiguration is a finite unit-bearing POC setting record, not a complete
+equipment capability profile. Its parser lives in schema/validation; newer ISO/exposure
+capabilities remain separate so adding a control policy does not reinterpret saved POC data.
+
+```ts
+export interface SensorConfiguration {
+  widthMm: number;
+  heightMm: number;
+  pixelWidth: number;
+  pixelHeight: number;
+}
+```
+
+## StabilizationConfiguration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface StabilizationConfiguration {
+  bodyEnabled: boolean;
+  lensEnabled: boolean;
+  support: CameraSupport;
+}
+```