@photivra/engine 0.6.0 → 1.0.1

package/docs/api/capture-simulated-capture.md

@@ -0,0 +1,179 @@
+# capture/simulated-capture.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.
+
+## CaptureFloatStorage
+
+External bytes are caller-owned; the engine never reads a path or URL.
+
+```ts
+export type CaptureFloatStorage =
+  | { kind: "inline-float64"; samples: readonly number[] }
+  | { kind: "external-float32" | "external-float64"; byteOrder: "little-endian"; artifactId: string; sha256: string; sampleCount: number };
+```
+
+## CaptureLinearImageState
+
+Distinct linear domains, not one interchangeable 'linear' flag.
+
+```ts
+export type CaptureLinearImageState = "scene-referred-xyz" | "virtual-sensor-channels" | "color-transformed-linear-rgb";
+```
+
+## CaptureLinearPlane
+
+Linear float plane; all channels are co-sited and interleaved in row-major order.
+
+```ts
+export interface CaptureLinearPlane {
+  id: string;
+  imageStateId: string;
+  imageState: CaptureLinearImageState;
+  rasterBinding: "oriented-active-capture" | "output";
+  pixelWidth: number;
+  pixelHeight: number;
+  channelIds: readonly string[];
+  colorProfile: CapturePublicProfileReference | null;
+  /** Defined for colorimetric/RGB encodings; null for unresolved sensor channels. */
+  encodingReferenceWhiteXyz: CaptureWhiteXyz | null;
+  /** Value normalization, independent of capture saturation or eventual integer white. */
+  referenceWhiteValue: number;
+  whiteBalanceApplication: "intent-only" | "applied-rgb-gains" | "applied-chromatic-adaptation" | "not-applicable";
+  captureSaturation:
+    | { kind: "not-modeled" }
+    | { kind: "declared-virtual-white"; whiteLevel: number; upstreamClippedSampleCount: number };
+  appliedTransforms: readonly { profile: CapturePublicProfileReference; kind: "linear-color" | "chromatic-adaptation" | "digital-lens-correction" }[];
+  storage: CaptureFloatStorage;
+}
+```
+
+## CapturePublicProfileReference
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CapturePublicProfileReference { id: string; version: string }
+```
+
+## CaptureWhiteBalanceIntent
+
+A resolved #108 choice, sanitized for public metadata. No estimator is rerun.
+
+```ts
+export interface CaptureWhiteBalanceIntent {
+  stateId: string;
+  source: ResolvedWhiteBalanceState["source"];
+  locked: boolean;
+  channelGains: WhiteBalanceChannelGains;
+  sourceProfile: CapturePublicProfileReference | null;
+}
+```
+
+## CaptureWhiteXyz
+
+Normalized tristimulus white; Y=1. This is not a spectrum or Kelvin value.
+
+```ts
+export interface CaptureWhiteXyz { x: number; y: 1; z: number }
+```
+
+## createCaptureWhiteBalanceIntent
+
+Converts validated shooting WB into a public metadata allowlist, discarding private extras.
+
+```ts
+export function createCaptureWhiteBalanceIntent(input: { state: ResolvedWhiteBalanceState }): CaptureWhiteBalanceIntent;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## createSimulatedCapture
+
+Commits a format-neutral float master manifest; no radiance generation, clamp, WB or export encoding.
+
+```ts
+export function createSimulatedCapture(input: SimulatedCaptureInput): CalculationResult<SimulatedCapture>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSimulatedCapture
+
+Parses an archived capture, recomputing and checking all derived geometry/focal metadata.
+
+```ts
+export function parseSimulatedCapture(value: unknown): SimulatedCapture;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveSimulatedCapturePlane
+
+Requires an exact plane image state; callers may not substitute another kind of 'linear'.
+
+```ts
+export function resolveSimulatedCapturePlane(input: {
+  capture: SimulatedCapture; planeId: string; requiredImageState: CaptureLinearImageState;
+}): CaptureLinearPlane;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## serializeSimulatedCapture
+
+Canonical allowlisted JSON, including semantic samples/IDs, not private caches or file layout.
+
+```ts
+export function serializeSimulatedCapture(input: { capture: SimulatedCapture }): string;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SIMULATED_CAPTURE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SIMULATED_CAPTURE_SCHEMA_VERSION = "0.2.0" as const
+```
+
+## SimulatedCapture
+
+Immutable committed value. Geometry/focal equivalence are derived, never caller overrides.
+
+```ts
+export interface SimulatedCapture extends SimulatedCaptureInput {
+  schemaVersion: typeof SIMULATED_CAPTURE_SCHEMA_VERSION;
+  engineApiVersion: string;
+  resolvedGeometry: ResolvedCaptureGeometry;
+  equivalentFocalLength35Mm: number;
+}
+```
+
+## SimulatedCaptureInput
+
+Format-neutral input from an upstream master/capture provider, not a preview image.
+
+```ts
+export interface SimulatedCaptureInput {
+  captureId: string;
+  sceneStateId: string;
+  /** Seconds on the declared scene clock, not an embedded wall-clock timestamp. */
+  sceneTimeSeconds: number;
+  geometry: ResolveCaptureGeometryInput;
+  exposure: { focalLengthMm: number; aperture: number; shutterSeconds: number; iso: number };
+  focus: FocusPlane;
+  noise: { seedUint32: number; realizationId: string; model: CapturePublicProfileReference };
+  source: {
+    kind: "scene-linear-master" | "sensor-derived-linear" | "color-transformed-linear-master";
+    artifactId: string;
+    sha256: string;
+    dynamicRangeHistory: "unknown" | "no-loss-declared" | "upstream-clipped";
+  };
+  whiteBalanceIntent: CaptureWhiteBalanceIntent | null;
+  /** Adopted/WB white is a camera choice, not automatically the encoding white. */
+  adoptedWhiteXyz: CaptureWhiteXyz | null;
+  models: readonly { profile: CapturePublicProfileReference; scientificStatus: ProvenanceKind; publicEvidenceIds: readonly string[] }[];
+  planes: readonly CaptureLinearPlane[];
+}
+```

package/docs/api/color-capture-color.md

@@ -0,0 +1,122 @@
+# color/capture-color.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.
+
+## calculateCaptureColorTransform
+
+Converts a bounded inline XYZ/ideal-camera plane to unclamped linear sRGB.
+Reuses resolved WB intent; never estimates illumination or changes exposure/noise.
+XYZ diagonal adaptation is explicitly an approximation, distinct from RGB gains.
+
+```ts
+export function calculateCaptureColorTransform(input: CaptureColorTransformInput): CalculationResult<CaptureColorTransformResult>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CAPTURE_COLOR_MODEL_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+CAPTURE_COLOR_MODEL_VERSION = "0.1.0" as const
+```
+
+## CaptureColorModel
+
+Profile data exposes complete row-major matrices and domain conditions to consumers.
+
+```ts
+export interface CaptureColorModel {
+  version: typeof CAPTURE_COLOR_MODEL_VERSION;
+  cameraProfile: CapturePublicProfileReference;
+  outputProfile: CapturePublicProfileReference;
+  referenceIlluminant: "D65";
+  observer: "cie-1931-2-degree";
+  referenceWhiteXyz: { x: number; y: 1; z: number };
+  cameraRgbToXyz: Matrix;
+  xyzToCameraRgb: Matrix;
+  scientificStatus: "calculated";
+  validConditions: readonly string[];
+  publicEvidenceIds: readonly string[];
+}
+```
+
+## CaptureColorTransformInput
+
+IDs identify a new derived plane; source capture stays immutable.
+
+```ts
+export interface CaptureColorTransformInput {
+  capture: SimulatedCapture;
+  sourcePlaneId: string;
+  outputPlaneId: string;
+  outputImageStateId: string;
+  whiteBalance: CaptureColorWhiteBalance;
+}
+```
+
+## CaptureColorTransformResult
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CaptureColorTransformResult {
+  plane: CaptureLinearPlane;
+  colorModel: CaptureColorModel;
+  sourcePlaneId: string;
+  sourceImageStateId: string;
+  whiteBalance: CaptureColorWhiteBalance;
+  /** Matrix on CIE XYZ, identity when no adaptation; row-major, dimensionless. */
+  chromaticAdaptationMatrix: Matrix;
+  /** False: even adopted-white scaling is a camera choice under mixed illumination. */
+  claimsUniqueSceneWhite: false;
+}
+```
+
+## CaptureColorWhiteBalance
+
+One explicit color interpretation; gains and adaptation cannot silently double-apply WB.
+
+```ts
+export type CaptureColorWhiteBalance =
+  | { kind: "preserve-intent" }
+  | { kind: "apply-resolved-rgb-gains"; channelBasis: CapturePublicProfileReference }
+  | { kind: "adopted-white-xyz-scaling" };
+```
+
+## LINEAR_CAPTURE_RGB_PROFILE
+
+Linear light, sRGB primaries/D65; no sRGB transfer curve is applied.
+
+```ts
+LINEAR_CAPTURE_RGB_PROFILE = Object.freeze({ id: "linear-srgb-d65", version: CAPTURE_COLOR_MODEL_VERSION })
+```
+
+## parseCaptureColorTransformInput
+
+Validates the entire capture and explicit transform policy across untrusted JSON boundaries.
+
+```ts
+export function parseCaptureColorTransformInput(value: unknown): CaptureColorTransformInput;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveCaptureColorModel
+
+Returns the versioned ideal camera basis, independent of rendering/serializer state.
+
+```ts
+export function resolveCaptureColorModel(): CaptureColorModel;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## VIRTUAL_COLOR_CAMERA_PROFILE
+
+Explicit ideal colorimetric camera, not measured spectral sensor channels.
+
+```ts
+VIRTUAL_COLOR_CAMERA_PROFILE = Object.freeze({ id: "photivra-colorimetric-rgb-d65", version: CAPTURE_COLOR_MODEL_VERSION })
+```

package/docs/api/color-white-balance.md

@@ -0,0 +1,386 @@
+# color/white-balance.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.
+
+## COLOR_TEMPERATURE_WHITE_BALANCE_INTENT_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+COLOR_TEMPERATURE_WHITE_BALANCE_INTENT_VERSION =
+  "0.1.0" as const
+```
+
+## ColorTemperatureWhiteBalanceIntent
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ColorTemperatureWhiteBalanceIntent {
+  version: typeof COLOR_TEMPERATURE_WHITE_BALANCE_INTENT_VERSION;
+  intentId: string;
+  colorTemperatureKelvin: number;
+  tint: number;
+  channelGainsResolved: false;
+  requiresCameraProfileColorimetry: true;
+  sceneIlluminationModified: false;
+}
+```
+
+## createColorTemperatureWhiteBalanceIntent
+
+Records independent color-temperature and tint intent.
+
+No channel gains are fabricated here; mapping CCT+tint into a camera's
+channel/color space belongs to a profile/colorimetry contract.
+
+```ts
+export function createColorTemperatureWhiteBalanceIntent(
+  input: CreateColorTemperatureWhiteBalanceIntentInput
+): ColorTemperatureWhiteBalanceIntent;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateColorTemperatureWhiteBalanceIntentInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateColorTemperatureWhiteBalanceIntentInput {
+  intentId: string;
+  colorTemperatureKelvin: number;
+  tint: number;
+}
+```
+
+## createLockedWhiteBalanceState
+
+Freezes a resolved WB state under a new stable identity.
+
+Locking changes neither the scene nor the gains; later AWB estimates may
+differ while this locked state remains unchanged.
+
+```ts
+export function createLockedWhiteBalanceState(
+  input: CreateLockedWhiteBalanceStateInput
+): ResolvedWhiteBalanceState;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateLockedWhiteBalanceStateInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateLockedWhiteBalanceStateInput {
+  stateId: string;
+  sourceState: ResolvedWhiteBalanceState;
+}
+```
+
+## estimateAutoWhiteBalance
+
+Estimates one global AWB state from declared pre-WB camera-linear samples.
+
+It intentionally does not accept true illuminant metadata. A gray-world
+neutralizing estimate is softened by the profile's correctionStrength so
+different generic AWB priorities can preserve different amounts of cast.
+
+```ts
+export function estimateAutoWhiteBalance(
+  input: EstimateAutoWhiteBalanceInput
+): ResolvedWhiteBalanceState;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## EstimateAutoWhiteBalanceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EstimateAutoWhiteBalanceInput {
+  stateId: string;
+  profile: WhiteBalanceProfile;
+  policyId: string;
+  sampleSet: PreWhiteBalanceRgbSampleSet;
+}
+```
+
+## parseResolvedWhiteBalanceState
+
+Parses a committed resolved white-balance state from an untrusted JSON
+boundary without re-estimating WB.
+
+This is intentionally a state parser, not an AWB estimator. It preserves the
+resolved gains/policy/measurement identity that a capture committed earlier.
+
+```ts
+export function parseResolvedWhiteBalanceState(
+  value: unknown
+): ResolvedWhiteBalanceState;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseWhiteBalanceProfile
+
+Parses generic WB presets and AWB policies.
+
+Preset gains and AWB correction strength are profile-owned. Labels are not
+treated as universal Kelvin aliases or manufacturer-specific behavior.
+
+```ts
+export function parseWhiteBalanceProfile(
+  value: unknown
+): WhiteBalanceProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## PreWhiteBalanceRgbSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PreWhiteBalanceRgbSample {
+  sampleId: string;
+  red: number;
+  green: number;
+  blue: number;
+  weight: number;
+  clipped: boolean;
+}
+```
+
+## PreWhiteBalanceRgbSampleSet
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface PreWhiteBalanceRgbSampleSet {
+  imageStateId: string;
+  inputDomain: WhiteBalanceInputDomain;
+  samples: readonly PreWhiteBalanceRgbSample[];
+}
+```
+
+## resolveCustomWhiteBalance
+
+Resolves a user-declared neutral/gray custom-WB measurement.
+
+The engine validates and reduces the selected pre-WB sample, but it does not
+claim the selected object is spectrally neutral in the real scene.
+
+```ts
+export function resolveCustomWhiteBalance(
+  input: ResolveCustomWhiteBalanceInput
+): ResolvedWhiteBalanceState;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveCustomWhiteBalanceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveCustomWhiteBalanceInput {
+  stateId: string;
+  sampleSet: PreWhiteBalanceRgbSampleSet;
+}
+```
+
+## ResolvedWhiteBalanceState
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedWhiteBalanceState {
+  version: typeof WHITE_BALANCE_STATE_VERSION;
+  stateId: string;
+  inputDomain: WhiteBalanceInputDomain;
+  source:
+    | "preset"
+    | "manual-gains"
+    | "custom-measurement"
+    | "auto-white-balance";
+  channelGains: WhiteBalanceChannelGains;
+  locked: boolean;
+  sourceProfile?: {
+    profileId: string;
+    profileVersion: string;
+  };
+  presetId?: string;
+  awbPolicy?: {
+    policyId: string;
+    intent: WhiteBalanceAwbIntent;
+    correctionStrength: number;
+  };
+  measurement?: {
+    imageStateId: string;
+    usableSampleCount: number;
+    rejectedClippedSampleCount: number;
+    weightedMeanPreWbSignal: {
+      red: number;
+      green: number;
+      blue: number;
+    };
+  };
+  sourceStateId?: string;
+  trueIlluminantMetadataUsed: false;
+  sceneIlluminationModified: false;
+  rawCaptureDestructivelyModified: false;
+  physicalExposureModified: false;
+  focusModified: false;
+  limitations: readonly string[];
+}
+```
+
+## resolveManualWhiteBalance
+
+Resolves explicit manual camera-linear channel gains.
+
+```ts
+export function resolveManualWhiteBalance(
+  input: ResolveManualWhiteBalanceInput
+): ResolvedWhiteBalanceState;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveManualWhiteBalanceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveManualWhiteBalanceInput {
+  stateId: string;
+  channelGains: WhiteBalanceChannelGains;
+}
+```
+
+## resolvePresetWhiteBalance
+
+Resolves a profile-owned WB preset without universal label/Kelvin rules.
+
+```ts
+export function resolvePresetWhiteBalance(
+  input: ResolvePresetWhiteBalanceInput
+): ResolvedWhiteBalanceState;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvePresetWhiteBalanceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvePresetWhiteBalanceInput {
+  stateId: string;
+  profile: WhiteBalanceProfile;
+  presetId: string;
+}
+```
+
+## WHITE_BALANCE_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+WHITE_BALANCE_PROFILE_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## WHITE_BALANCE_STATE_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+WHITE_BALANCE_STATE_VERSION = "0.1.0" as const
+```
+
+## WhiteBalanceAwbIntent
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type WhiteBalanceAwbIntent =
+  | "neutral-priority"
+  | "standard"
+  | "ambience-preserving";
+```
+
+## WhiteBalanceAwbPolicy
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface WhiteBalanceAwbPolicy {
+  policyId: string;
+  intent: WhiteBalanceAwbIntent;
+  /**
+   * Fraction of a gray-world neutralizing correction applied in logarithmic
+   * gain space. 1 is full neutral-priority correction; lower values preserve
+   * more of the observed cast.
+   */
+  correctionStrength: EvidenceBackedFact<number>;
+  limitations?: readonly string[];
+}
+```
+
+## WhiteBalanceChannelGains
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface WhiteBalanceChannelGains {
+  red: number;
+  green: number;
+  blue: number;
+}
+```
+
+## WhiteBalanceInputDomain
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type WhiteBalanceInputDomain =
+  "relative-pre-wb-camera-linear-rgb";
+```
+
+## WhiteBalancePresetDefinition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface WhiteBalancePresetDefinition {
+  presetId: string;
+  label: string;
+  channelGains: EvidenceBackedFact<WhiteBalanceChannelGains>;
+  nominalColorTemperatureKelvin?: number;
+  nominalTint?: number;
+  limitations?: readonly string[];
+}
+```
+
+## WhiteBalanceProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface WhiteBalanceProfile {
+  schemaVersion: typeof WHITE_BALANCE_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  scientificStatus: "approximation";
+  inputDomain: WhiteBalanceInputDomain;
+  presets: readonly WhiteBalancePresetDefinition[];
+  awbPolicies: readonly WhiteBalanceAwbPolicy[];
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```