@photivra/engine 0.6.0 → 1.0.1

package/docs/api/optics-depth-of-field.md

@@ -0,0 +1,92 @@
+# optics/depth-of-field.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.
+
+## calculateDefocusCircle
+
+Calculates the geometric defocus-circle diameter at the sensor plane for a
+subject plane away from the selected focus plane.
+
+```ts
+export function calculateDefocusCircle(
+  input: CalculateDefocusCircleInput
+): CalculationResult<DefocusCircle>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateDefocusCircleInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateDefocusCircleInput {
+  /** Lens focal length in millimetres. */
+  focalLengthMm: number;
+  /** F-number. */
+  aperture: number;
+  /** Focus-plane distance from the lens plane in metres. */
+  focusDistanceM: number;
+  /** Subject-plane distance from the lens plane in metres. */
+  subjectDistanceM: number;
+}
+```
+
+## calculateDepthOfField
+
+Calculates thin-lens depth-of-field limits using the conventional
+hyperfocal-distance formulation.
+
+The model is geometric and does not include diffraction, aberrations,
+focus breathing, pupil magnification, or macro/high-magnification effects.
+
+```ts
+export function calculateDepthOfField(
+  input: CalculateDepthOfFieldInput
+): CalculationResult<DepthOfField>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateDepthOfFieldInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateDepthOfFieldInput {
+  /** Lens focal length in millimetres. */
+  focalLengthMm: number;
+  /** F-number. */
+  aperture: number;
+  /** Focus distance from the lens plane in metres. */
+  focusDistanceM: number;
+  /** Acceptable circle of confusion diameter in millimetres. */
+  circleOfConfusionMm: number;
+}
+```
+
+## DefocusCircle
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DefocusCircle {
+  /** Geometric blur-circle diameter at the sensor plane in millimetres. */
+  diameterMm: number;
+}
+```
+
+## DepthOfField
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DepthOfField {
+  hyperfocalDistanceM: number;
+  nearLimitM: number;
+  /** Null represents an infinite far limit. */
+  farLimitM: number | null;
+  /** Null represents infinite total depth of field. */
+  totalDepthOfFieldM: number | null;
+}
+```

package/docs/api/optics-diffraction.md

@@ -0,0 +1,46 @@
+# optics/diffraction.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.
+
+## AiryDisk
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface AiryDisk {
+  /**
+   * Diameter from the center of the diffraction pattern to the first dark-ring
+   * diameter, in micrometres: 2.44 * wavelength * f-number.
+   */
+  firstZeroDiameterMicrometers: number;
+}
+```
+
+## calculateAiryDisk
+
+Calculates the first-zero Airy-disk diameter for an ideal circular aperture.
+
+This uses the established diffraction relation d = 2.44 * lambda * N.
+It is an independent implementation of the mathematical relation and does
+not model lens aberrations or non-circular pupil geometry.
+
+```ts
+export function calculateAiryDisk(
+  input: CalculateAiryDiskInput
+): CalculationResult<AiryDisk>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateAiryDiskInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateAiryDiskInput {
+  /** F-number. */
+  aperture: number;
+  /** Wavelength in nanometres. Defaults are intentionally left to callers. */
+  wavelengthNm: number;
+}
+```

package/docs/api/optics-focus-breathing.md

@@ -0,0 +1,119 @@
+# optics/focus-breathing.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.
+
+## calculateFocusBreathingFieldOfView
+
+Calculates one-axis field of view for the generic declared-scale focus-
+breathing projection and reports the corresponding ideal thin-lens FOV.
+
+A breathingProjectionScale of 1 reproduces the current focus-aware
+thin-lens field-of-view result exactly.
+
+```ts
+export function calculateFocusBreathingFieldOfView(
+  input: CalculateFocusBreathingFieldOfViewInput
+): CalculationResult<FocusBreathingFieldOfView>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateFocusBreathingFieldOfViewInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateFocusBreathingFieldOfViewInput
+  extends CalculateFocusBreathingProjectionInput {
+  /** Sensor/capture dimension corresponding to the requested FOV, in millimetres. */
+  sensorDimensionMm: number;
+}
+```
+
+## calculateFocusBreathingProjection
+
+Applies a caller-declared focus-breathing projection scale to the ideal
+Gaussian thin-lens projection for one focus state.
+
+Photivra does not infer the scale from focal length, focus distance, lens
+identity, or marketing data. A value of 1 exactly preserves the current
+thin-lens projection.
+
+This is a generic approximation of focus-dependent projection/magnification,
+not a calibrated real-lens model. The physical focal length remains
+authoritative and unchanged.
+
+```ts
+export function calculateFocusBreathingProjection(
+  input: CalculateFocusBreathingProjectionInput
+): CalculationResult<FocusBreathingProjection>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateFocusBreathingProjectionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateFocusBreathingProjectionInput {
+  /** Physical lens focal length in millimetres. This value is never rewritten. */
+  focalLengthMm: number;
+  /** Selected focus distance in metres. */
+  focusDistanceM: number;
+  /**
+   * Caller-declared projection scale for this focus state, relative to the
+   * ideal thin-lens image distance.
+   *
+   * 1 means no additional breathing relative to the current thin-lens model.
+   * Values above 1 narrow framing / increase magnification; values below 1
+   * widen framing / reduce magnification.
+   */
+  breathingProjectionScale: number;
+}
+```
+
+## FocusBreathingFieldOfView
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FocusBreathingFieldOfView {
+  physicalFocalLengthMm: number;
+  focusDistanceM: number;
+  sensorDimensionMm: number;
+  breathingProjectionScale: number;
+  idealProjectionDistanceMm: number;
+  effectiveProjectionDistanceMm: number;
+  idealDegrees: number;
+  effectiveDegrees: number;
+  deltaDegrees: number;
+}
+```
+
+## FocusBreathingProjection
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FocusBreathingProjection {
+  /** Authoritative physical focal length supplied by the caller. */
+  physicalFocalLengthMm: number;
+  focusDistanceM: number;
+  /** Ideal Gaussian thin-lens image distance before breathing adjustment. */
+  idealProjectionDistanceMm: number;
+  /**
+   * Effective projection distance used by the generic breathing model.
+   *
+   * This is a projection/magnification parameter, not a replacement physical
+   * focal length.
+   */
+  effectiveProjectionDistanceMm: number;
+  /** Caller-declared scale relative to ideal thin-lens projection. */
+  breathingProjectionScale: number;
+  /** Ideal Gaussian thin-lens magnification at the selected focus distance. */
+  idealMagnification: number;
+  /** Generic breathing-adjusted magnification. */
+  effectiveMagnification: number;
+}
+```

package/docs/api/optics-focus-state.md

@@ -0,0 +1,64 @@
+# optics/focus-state.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.
+
+## calculateFocusPlaneImageDistance
+
+Calculates the ideal image-plane distance for an explicit focus state.
+
+Finite focus delegates to the existing Gaussian thin-lens calculation, so
+its numerical result and provenance are unchanged. Infinity focus resolves
+exactly to the nominal focal length with zero limiting magnification.
+
+```ts
+export function calculateFocusPlaneImageDistance(
+  input: CalculateFocusPlaneImageDistanceInput
+): CalculationResult<ThinLensImageDistance>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateFocusPlaneImageDistanceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateFocusPlaneImageDistanceInput {
+  /** Lens focal length in millimetres. */
+  focalLengthMm: number;
+  /** Explicit finite or infinity focus-plane state. */
+  focus: FocusPlane;
+}
+```
+
+## FocusPlane
+
+Explicit ideal focus-plane state.
+
+Finite distance is the longitudinal object-plane distance from the ideal
+lens principal plane along the camera optical axis. Infinity is a semantic
+state and is never represented with JavaScript Infinity or a fabricated
+large distance.
+
+```ts
+export type FocusPlane =
+  | {
+      kind: "finite";
+      distanceM: number;
+    }
+  | {
+      kind: "infinity";
+    };
+```
+
+## parseFocusPlane
+
+Parses an explicit focus-plane state from an untrusted JSON boundary.
+
+Missing/unknown focus is rejected rather than being interpreted as infinity.
+
+```ts
+export function parseFocusPlane(value: unknown): FocusPlane;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/optics-front-of-lens-filter.md

@@ -0,0 +1,263 @@
+# optics/front-of-lens-filter.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.
+
+## ComposedFrontOfLensFilterTransmission
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ComposedFrontOfLensFilterTransmission {
+  schemaVersion:
+    typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+  wavelengthNanometers: number;
+  wavelengthBasis:
+    Exclude<
+      SpectralWavelengthBasis,
+      "unspecified"
+    >;
+  appliedFilterCount: number;
+  components:
+    readonly ResolvedFrontOfLensFilterTransmission[];
+  combinedLinearTransmissionFactor:
+    number;
+  combinedAttenuationStops: number;
+  scientificStatus:
+    FrontOfLensFilterScientificStatus;
+  uncertaintyPropagation:
+    "not-propagated";
+  uncertaintyLimitation: string;
+  compositionModel:
+    "independent-multiplicative-unpolarized-transmission-no-inter-filter-reflections";
+  polarizationModeled: false;
+  wavelengthChangingBehaviorModeled:
+    false;
+  lensTransmissionIncluded: false;
+  sensorOpticalStackIncluded: false;
+  fieldThroughputIncluded: false;
+}
+```
+
+## composeFrontOfLensFilterTransmission
+
+Composes multiple passive front-of-lens filters multiplicatively at one
+wavelength while preserving each component's identity.
+
+```ts
+export function composeFrontOfLensFilterTransmission(
+  input:
+    ComposeFrontOfLensFilterTransmissionInput
+): ComposedFrontOfLensFilterTransmission;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ComposeFrontOfLensFilterTransmissionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ComposeFrontOfLensFilterTransmissionInput {
+  filters:
+    readonly FrontOfLensFilterProfile[];
+  wavelengthNanometers: number;
+  wavelengthBasis:
+    Exclude<
+      SpectralWavelengthBasis,
+      "unspecified"
+    >;
+}
+```
+
+## FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## FrontOfLensFilterProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FrontOfLensFilterProfile {
+  schemaVersion:
+    typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+  filterId: string;
+  profileVersion: string;
+  identityScope:
+    "photivra-generic-unbranded";
+  position: "front-of-lens";
+  scientificStatus:
+    FrontOfLensFilterScientificStatus;
+  wavelengthBasis:
+    Exclude<
+      SpectralWavelengthBasis,
+      "unspecified"
+    >;
+  wavelengthRangeNanometers: {
+    minimum: number;
+    maximum: number;
+  };
+  transmission:
+    FrontOfLensFilterTransmissionModel;
+  uncertainty:
+    FrontOfLensFilterUncertainty;
+  polarizationModeled: false;
+  wavelengthChangingBehaviorModeled:
+    false;
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## FrontOfLensFilterScientificStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type FrontOfLensFilterScientificStatus =
+  | "calibrated"
+  | "approximation";
+```
+
+## FrontOfLensFilterSpectralSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FrontOfLensFilterSpectralSample {
+  wavelengthNanometers: number;
+  linearTransmissionFactor: number;
+}
+```
+
+## FrontOfLensFilterTransmissionModel
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type FrontOfLensFilterTransmissionModel =
+  | {
+      kind: "neutral-linear-transmission";
+      linearTransmissionFactor:
+        EvidenceBackedFact<number>;
+    }
+  | {
+      kind: "neutral-optical-density";
+      opticalDensityBase10:
+        EvidenceBackedFact<number>;
+    }
+  | {
+      kind: "spectral-transmission";
+      samples:
+        EvidenceBackedFact<
+          readonly FrontOfLensFilterSpectralSample[]
+        >;
+    };
+```
+
+## FrontOfLensFilterUncertainty
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type FrontOfLensFilterUncertainty =
+  | {
+      kind: "relative";
+      fraction: number;
+      basis: string;
+    }
+  | {
+      kind: "not-quantified";
+      limitation: string;
+    };
+```
+
+## parseFrontOfLensFilterProfile
+
+Parses one generic front-of-lens transmission filter.
+
+Schema 0.1.0 is explicitly unbranded and unpolarized. It models only
+passive transmission placed before the lens. Reflections between stacked
+filters, polarization, flare/ghosting and wavelength-changing behavior are
+outside this contract.
+
+```ts
+export function parseFrontOfLensFilterProfile(
+  value: unknown
+): FrontOfLensFilterProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedFrontOfLensFilterTransmission
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedFrontOfLensFilterTransmission {
+  schemaVersion:
+    typeof FRONT_OF_LENS_FILTER_PROFILE_SCHEMA_VERSION;
+  filterId: string;
+  profileVersion: string;
+  identityScope:
+    "photivra-generic-unbranded";
+  position: "front-of-lens";
+  scientificStatus:
+    FrontOfLensFilterScientificStatus;
+  wavelengthNanometers: number;
+  wavelengthBasis:
+    Exclude<
+      SpectralWavelengthBasis,
+      "unspecified"
+    >;
+  transmissionKind:
+    FrontOfLensFilterTransmissionModel["kind"];
+  linearTransmissionFactor: number;
+  attenuationStops: number;
+  opticalDensityBase10: number;
+  polarizationModeled: false;
+  wavelengthChangingBehaviorModeled:
+    false;
+  lensTransmissionIncluded: false;
+  sensorOpticalStackIncluded: false;
+  fieldThroughputIncluded: false;
+  uncertainty:
+    FrontOfLensFilterUncertainty;
+  evidence: readonly EvidenceProvenance[];
+  limitations: readonly string[];
+}
+```
+
+## resolveFrontOfLensFilterTransmission
+
+Resolves one passive filter at one wavelength.
+
+```ts
+export function resolveFrontOfLensFilterTransmission(
+  input:
+    ResolveFrontOfLensFilterTransmissionInput
+): ResolvedFrontOfLensFilterTransmission;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveFrontOfLensFilterTransmissionInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveFrontOfLensFilterTransmissionInput {
+  profile: FrontOfLensFilterProfile;
+  wavelengthNanometers: number;
+  wavelengthBasis:
+    Exclude<
+      SpectralWavelengthBasis,
+      "unspecified"
+    >;
+}
+```

package/docs/api/optics-illumination-vignetting.md

@@ -0,0 +1,95 @@
+# optics/illumination-vignetting.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.
+
+## calculateIlluminationVignetting
+
+Calculates generic field-dependent illumination falloff as a multiplicative
+linear-light throughput factor.
+
+The profile is accepted only when its relative throughput remains strictly
+positive and never exceeds the optical-axis normalization of 1 throughout
+the complete declared operating envelope.
+
+```ts
+export function calculateIlluminationVignetting(
+  input: CalculateIlluminationVignettingInput
+): CalculationResult<IlluminationVignetting>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateIlluminationVignettingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateIlluminationVignettingInput {
+  /**
+   * Ideal image-plane field position relative to the optical axis, in mm.
+   *
+   * This slice evaluates throughput from the declared ideal field coordinate;
+   * it does not apply or invert geometric distortion.
+   */
+  imagePointMm: LensFieldPointMm;
+  profile: IlluminationVignettingProfile;
+}
+```
+
+## IlluminationVignetting
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IlluminationVignetting {
+  imagePointMm: LensFieldPointMm;
+  normalizedRadius: number;
+  /**
+   * Multiplicative factor for scene-linear/channel-linear signal.
+   *
+   * 1 means no attenuation; values are required to remain in (0, 1].
+   */
+  linearThroughputFactor: number;
+  /** Positive exposure loss relative to the optical axis, in stops. */
+  attenuationStops: number;
+  profileMinimumThroughputFactor: number;
+  profileMaximumThroughputFactor: number;
+}
+```
+
+## IlluminationVignettingCoefficients
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IlluminationVignettingCoefficients {
+  /** Coefficient on normalized radius squared. */
+  r2: number;
+  /** Coefficient on normalized radius to the fourth power. */
+  r4: number;
+  /** Coefficient on normalized radius to the sixth power. */
+  r6: number;
+}
+```
+
+## IlluminationVignettingProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IlluminationVignettingProfile {
+  /** Physical image-plane radius used to normalize field position, in mm. */
+  normalizationRadiusMm: number;
+  /** Maximum normalized image-plane radius over which the profile is valid. */
+  maximumNormalizedRadius: number;
+  /**
+   * Generic radial relative-illumination coefficients.
+   *
+   * Relative linear throughput is:
+   *   1 + r2 * rho^2 + r4 * rho^4 + r6 * rho^6
+   *
+   * where rho is physical image-plane radius / normalizationRadiusMm.
+   */
+  coefficients: IlluminationVignettingCoefficients;
+}
+```