@photivra/engine 1.4.0 → 2.0.0

package/docs/api/optics-brown-conrady-distortion.md

@@ -0,0 +1,123 @@
+# optics/brown-conrady-distortion.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.
+
+## BrownConradyDistortionCoefficients
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BrownConradyDistortionCoefficients {
+  /** Radial r^2 coefficient. */
+  k1: number;
+  /** Radial r^4 coefficient. */
+  k2: number;
+  /** Radial r^6 coefficient. */
+  k3: number;
+  /** Tangential (decentering) coefficient p1 (couples to y; see module equation). */
+  p1: number;
+  /** Tangential (decentering) coefficient p2 (couples to x; see module equation). */
+  p2: number;
+}
+```
+
+## BrownConradyDistortionMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BrownConradyDistortionMapping {
+  direction: "undistorted-to-distorted";
+  sourceImagePointMm: LensFieldPointMm;
+  mappedImagePointMm: LensFieldPointMm;
+  sourceNormalizedRadius: number;
+  /** Determinant of d(mapped)/d(source) at the source point (dimensionless area scale). */
+  jacobianDeterminant: number;
+  deltaMm: { x: number; y: number; distance: number };
+  profileMinimumJacobianDeterminant: number;
+}
+```
+
+## BrownConradyDistortionProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface BrownConradyDistortionProfile {
+  /** Physical image-plane radius used to normalize field position, in mm. */
+  normalizationRadiusMm: number;
+  /** Maximum undistorted normalized radius of the operating envelope. */
+  maximumNormalizedRadius: number;
+  coefficients: BrownConradyDistortionCoefficients;
+}
+```
+
+## calculateBrownConradyDistortionMapping
+
+Applies the Brown-Conrady forward mapping to one ideal image-plane point.
+
+```ts
+export function calculateBrownConradyDistortionMapping(
+  input: CalculateBrownConradyDistortionMappingInput
+): CalculationResult<BrownConradyDistortionMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateBrownConradyDistortionMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateBrownConradyDistortionMappingInput {
+  /** Ideal/undistorted image-plane point, in mm. */
+  imagePointMm: LensFieldPointMm;
+  profile: BrownConradyDistortionProfile;
+}
+```
+
+## calculateInverseBrownConradyDistortionMapping
+
+Inverse-maps one distorted image-plane point to its ideal source point, for destination-to-source
+resampling. Damped Newton iteration starts from the radial-only inverse. The solution must lie
+inside the declared envelope and must reproduce the distorted point within a relative tolerance of
+1e-12.
+
+```ts
+export function calculateInverseBrownConradyDistortionMapping(
+  input: CalculateInverseBrownConradyDistortionMappingInput
+): CalculationResult<InverseBrownConradyDistortionMapping>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateInverseBrownConradyDistortionMappingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateInverseBrownConradyDistortionMappingInput {
+  /** Distorted image-plane point to map back to ideal coordinates, in mm. */
+  distortedImagePointMm: LensFieldPointMm;
+  profile: BrownConradyDistortionProfile;
+}
+```
+
+## InverseBrownConradyDistortionMapping
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface InverseBrownConradyDistortionMapping {
+  direction: "distorted-to-undistorted";
+  distortedImagePointMm: LensFieldPointMm;
+  sourceImagePointMm: LensFieldPointMm;
+  sourceNormalizedRadius: number;
+  jacobianDeterminantAtSource: number;
+  newtonIterations: number;
+  /** Forward-mapping residual of the solved source point, in mm. */
+  residualMm: number;
+  deltaMm: { x: number; y: number; distance: number };
+  profileMinimumJacobianDeterminant: number;
+}
+```

package/docs/api/optics-circle-of-confusion.md

@@ -1,6 +1,6 @@
 # optics/circle-of-confusion.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.
 
 ## EquivalentViewingCircleOfConfusion
 
@@ -17,11 +17,12 @@ export interface EquivalentViewingCircleOfConfusion {
 
 ## estimateEquivalentViewingCircleOfConfusion
 
-Estimates a circle-of-confusion criterion for equivalent final viewing by
-scaling a caller-supplied reference criterion in proportion to sensor
+Estimates a circle-of-confusion criterion for equivalent final viewing. It
+scales a caller-supplied reference criterion in proportion to the sensor
 diagonal.
 
-This is a viewing/acceptability convention, not a physical blur threshold.
+This is a viewing (acceptable-sharpness) convention, not a physical blur
+threshold.
 
 ```ts
 export function estimateEquivalentViewingCircleOfConfusion(

package/docs/api/optics-complex-pupil-psf.md

@@ -1,16 +1,16 @@
 # optics/complex-pupil-psf.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.
 
 ## calculateLensComplexPupilPsf
 
-Evaluate a declared complex pupil with explicit amplitude/phase and sampling support; normalize PSF
-shape and retain pupil throughput as a separate quantity.
+Evaluates a declared complex pupil with explicit amplitude, phase and sampling support. Returns the
+normalized PSF shape, and the pupil throughput as a separate quantity.
 
-Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
-shape is normalized separately from pupil throughput; coherent phase, pupil energy and
-spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
-owned or reusable-data provenance.
+The complex pupil is evaluated by summing the declared amplitude and phase over a bounded, regular
+pupil grid. The PSF shape is normalized separately from the pupil throughput. A single blur radius
+cannot stand in for coherent phase, pupil energy, or the wavelength and field range where the
+profile applies. Numeric profiles need provenance showing the data is owned or reusable.
 
 ```ts
 export function calculateLensComplexPupilPsf(
@@ -29,9 +29,9 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface CalculateLensComplexPupilPsfInput {
   profile:
     LensComplexPupilProfile;
-  /** Physical pupil-to-image propagation scale in mm. Omission preserves the
-   * nominal focal-plane reference. Finite-focus callers must explicitly resolve
-   * the supported principal-plane geometry; profile metadata does not do so. */
+  /** Physical propagation distance from pupil to image, in mm. If omitted, the
+   * nominal focal-plane reference is used. At finite focus the caller must
+   * resolve the supported principal-plane geometry; profile metadata does not. */
   propagationDistanceMm?: number;
 }
 ```
@@ -146,6 +146,8 @@ export interface LensComplexPupilPsf {
   context:
     LensComplexPupilProfile["context"];
   kernel: LensPsfKernel;
+  /** Nyquist sampling diagnostics and the applied zero padding. */
+  sampling: LensComplexPupilPsfSampling;
   relativePupilThroughputFactor:
     number;
   throughputOwnership:
@@ -180,15 +182,54 @@ export interface LensComplexPupilPsf {
 }
 ```
 
+## LensComplexPupilPsfSampling
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface LensComplexPupilPsfSampling {
+  criterion: "discrete-intensity-alias-free-goodman-q-above-2";
+  /** Number of pupil samples spanned by non-zero amplitude, per axis. */
+  pupilSupportSamplesX: number;
+  pupilSupportSamplesY: number;
+  /**
+   * Sampled pupil diameter D = (support samples - 1) x pupil pitch: the
+   * centre-to-centre span of the outermost non-zero samples, in millimetres.
+   */
+  pupilSupportDiameterMmX: number;
+  pupilSupportDiameterMmY: number;
+  /**
+   * Widest support allowed by the declared f-number at the resolved propagation distance:
+   * propagationDistanceMm / apertureFNumber, in millimetres. For the nominal focal-plane reference
+   * this is focalLengthMm / apertureFNumber.
+   */
+  declaredPupilDiameterMm: number;
+  /** Declared pupil grid size before zero padding. */
+  pupilGridWidthSamples: number;
+  pupilGridHeightSamples: number;
+  /** DFT size after zero padding; equals the output kernel size. */
+  transformWidthSamples: number;
+  transformHeightSamples: number;
+  zeroPaddingApplied: boolean;
+  /**
+   * Achieved Goodman sampling factor Q = lambda*(z/D)/imagePitch =
+   * transform samples / (support samples - 1). Always greater than 2. Null
+   * when the support is a single sample on that axis (no finite diameter).
+   */
+  samplingFactorQX: number | null;
+  samplingFactorQY: number | null;
+}
+```
+
 ## parseLensComplexPupilProfile
 
-Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
-missing required fields and incompatible scientific data fail at this boundary.
+Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data are rejected here.
 
-Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
-shape is normalized separately from pupil throughput; coherent phase, pupil energy and
-spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
-owned or reusable-data provenance.
+The complex pupil is evaluated by summing the declared amplitude and phase over a bounded, regular
+pupil grid. The PSF shape is normalized separately from the pupil throughput. A single blur radius
+cannot stand in for coherent phase, pupil energy, or the wavelength and field range where the
+profile applies. Numeric profiles need provenance showing the data is owned or reusable.
 
 ```ts
 export function parseLensComplexPupilProfile(

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

@@ -1,11 +1,12 @@
 # optics/depth-of-field.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.
 
 ## calculateDefocusCircle
 
 Calculates the geometric defocus-circle diameter at the sensor plane for a
-subject plane away from the selected focus plane.
+subject plane away from the selected focus plane, using the stable closed
+form c = f^2 |s - d| / (N d (s - f)) (model 1.1.0).
 
 ```ts
 export function calculateDefocusCircle(
@@ -34,11 +35,16 @@ export interface CalculateDefocusCircleInput {
 
 ## calculateDepthOfField
 
-Calculates thin-lens depth-of-field limits using the conventional
-hyperfocal-distance formulation.
+Calculates exact thin-lens depth-of-field limits. With hyperfocal
+distance H = f^2/(Nc) + f and focus distance s, the near limit is
+s(H - f)/(H + s - 2f) and the far limit is s(H - f)/(H - s), which is
+infinite (`null`) when s >= H. At both limits the geometric defocus circle
+from {@link calculateDefocusCircle} equals the supplied circle of confusion.
+The circle of confusion must be smaller than the aperture diameter f/N;
+otherwise the near limit would fall inside the focal length.
 
-The model is geometric and does not include diffraction, aberrations,
-focus breathing, pupil magnification, or macro/high-magnification effects.
+The model is geometric. It does not include diffraction, aberrations,
+focus breathing, pupil magnification or macro (high-magnification) effects.
 
 ```ts
 export function calculateDepthOfField(

package/docs/api/optics-diffraction.md

@@ -1,6 +1,6 @@
 # optics/diffraction.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.
 
 ## AiryDisk
 
@@ -9,8 +9,8 @@ The exact contract is declared below; use the domain guide for assumptions and s
 ```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.
+   * Diameter of the first dark ring of the diffraction pattern, in
+   * micrometres: 2.44 * wavelength * f-number.
    */
   firstZeroDiameterMicrometers: number;
 }
@@ -18,11 +18,12 @@ export interface AiryDisk {
 
 ## calculateAiryDisk
 
-Calculates the first-zero Airy-disk diameter for an ideal circular aperture.
+Calculates the Airy-disk diameter to the first dark ring 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.
+It uses the standard diffraction relation d = 2.44 * lambda * N. This is an
+independent implementation of that relation. It does not model lens
+aberrations or non-circular pupils.
 
 ```ts
 export function calculateAiryDisk(

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

@@ -1,14 +1,15 @@
 # optics/focus-breathing.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.
 
 ## calculateFocusBreathingFieldOfView
 
-Calculates one-axis field of view for the generic declared-scale focus-
-breathing projection and reports the corresponding ideal thin-lens FOV.
+Calculates the one-axis field of view under the declared-scale
+focus-breathing model, and reports the ideal thin-lens field of view for
+comparison.
 
-A breathingProjectionScale of 1 reproduces the current focus-aware
-thin-lens field-of-view result exactly.
+A breathingProjectionScale of 1 reproduces the focus-aware thin-lens field
+of view exactly.
 
 ```ts
 export function calculateFocusBreathingFieldOfView(
@@ -35,13 +36,13 @@ export interface CalculateFocusBreathingFieldOfViewInput
 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.
+Photivra does not guess the scale from focal length, focus distance, lens
+identity or marketing data. A scale of 1 keeps the thin-lens projection
+exactly.
 
-This is a generic approximation of focus-dependent projection/magnification,
-not a calibrated real-lens model. The physical focal length remains
-authoritative and unchanged.
+This is a generic approximation of how projection and magnification change
+with focus. It is not a calibrated real-lens model. The physical focal
+length is never changed and stays authoritative.
 
 ```ts
 export function calculateFocusBreathingProjection(
@@ -65,14 +66,61 @@ export interface CalculateFocusBreathingProjectionInput {
    * 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.
+   * 1 means no breathing beyond the thin-lens model. Values above 1 narrow the
+   * framing (more magnification). Values below 1 widen it (less
+   * magnification).
    */
   breathingProjectionScale: number;
 }
 ```
 
+## calculateGeometricFocusBreathing
+
+Focus breathing derived from ideal focusing geometry, instead of a declared scale.
+
+- unit-focus: the whole lens moves. u + v = L - hiatus and 1/u + 1/v = 1/f, so
+  v = (T - sqrt(T^2 - 4 f T)) / 2, where T = L - hiatus >= 4 f. The field narrows as v grows.
+- fixed-image-distance-internal-focus: an idealised internal-focus lens keeps the rear principal
+  plane at v = f_infinity and shortens its focal length to f' = u v / (u + v). The angular field
+  at the rear nodal point then stays the same, and the magnification is f_infinity / u.
+Both use paraxial Gaussian optics with the nodal points at the principal planes (unit pupil
+magnification; Greivenkamp, OPTI-502 course notes, University of Arizona, sec. 3 and 5, free. Also
+see: Kingslake & Johnson, Lens Design Fundamentals, 2nd ed., ch. 3; Ray, Applied Photographic
+Optics, 3rd ed., ch. 9 and 14). Real internal-focus lenses also move their pupils and
+principal planes, so modelling their breathing needs a calibrated profile.
+
+```ts
+export function calculateGeometricFocusBreathing(
+  input: CalculateGeometricFocusBreathingInput
+): CalculationResult<GeometricFocusBreathing>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateGeometricFocusBreathingInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateGeometricFocusBreathingInput {
+  /** Focal length at infinity focus, mm. */
+  focalLengthMm: number;
+  /**
+   * Photographic focus distance measured from the subject plane to the sensor (image) plane, in
+   * metres, as marked on lens distance scales.
+   */
+  subjectToSensorDistanceM: number;
+  /** Sensor/capture dimension along the axis of interest, mm. */
+  sensorDimensionMm: number;
+  focusingMethod: GeometricFocusingMethod;
+  /**
+   * Signed distance between the front and rear principal planes (the "hiatus"), in mm. Default 0
+   * (thin lens). The subject-to-sensor distance is u + hiatus + v.
+   */
+  principalPlaneSeparationMm?: number;
+}
+```
+
 ## FocusBreathingFieldOfView
 
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
@@ -105,8 +153,8 @@ export interface FocusBreathingProjection {
   /**
    * Effective projection distance used by the generic breathing model.
    *
-   * This is a projection/magnification parameter, not a replacement physical
-   * focal length.
+   * This is a projection (magnification) parameter. It does not replace the
+   * physical focal length.
    */
   effectiveProjectionDistanceMm: number;
   /** Caller-declared scale relative to ideal thin-lens projection. */
@@ -117,3 +165,43 @@ export interface FocusBreathingProjection {
   effectiveMagnification: number;
 }
 ```
+
+## GeometricFocusBreathing
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GeometricFocusBreathing {
+  focusingMethod: GeometricFocusingMethod;
+  infinityFocalLengthMm: number;
+  /** Focal length of the focused system (changes only for internal focus), mm. */
+  effectiveFocalLengthMm: number;
+  /** Subject distance from the front principal plane, mm. */
+  objectDistanceMm: number;
+  /** Rear principal plane to sensor distance (projection distance), mm. */
+  imageDistanceMm: number;
+  /** Lateral magnification v / u. */
+  magnification: number;
+  /** v / f_infinity: framing scale relative to infinity focus. */
+  projectionScaleRelativeToInfinity: number;
+  /**
+   * v divided by the ideal thin-lens image distance, at objectDistanceMm, of a lens with the same
+   * infinity focal length. Exactly 1 for unit focus. You can pass it as breathingProjectionScale to
+   * calculateFocusBreathingProjection() with focusDistanceM = objectDistanceMm / 1000.
+   */
+  equivalentBreathingProjectionScale: number;
+  fieldOfViewDegrees: number;
+  infinityFieldOfViewDegrees: number;
+  deltaDegrees: number;
+}
+```
+
+## GeometricFocusingMethod
+
+Ideal focusing geometry for {@link calculateGeometricFocusBreathing}.
+
+```ts
+export type GeometricFocusingMethod =
+  | "unit-focus"
+  | "fixed-image-distance-internal-focus";
+```

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

@@ -1,14 +1,14 @@
 # optics/focus-state.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.
 
 ## 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.
+Finite focus uses the existing Gaussian thin-lens calculation, so its
+numbers and provenance are unchanged. Infinity focus gives exactly the
+nominal focal length, with a limiting magnification of zero.
 
 ```ts
 export function calculateFocusPlaneImageDistance(
@@ -35,10 +35,9 @@ export interface CalculateFocusPlaneImageDistanceInput {
 
 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.
+A finite distance is measured along the camera's optical axis, from the
+ideal lens principal plane to the object plane. Infinity is a named state.
+It is never stored as JavaScript Infinity or as a made-up large distance.
 
 ```ts
 export type FocusPlane =
@@ -53,9 +52,9 @@ export type FocusPlane =
 
 ## parseFocusPlane
 
-Parses an explicit focus-plane state from an untrusted JSON boundary.
+Parses an explicit focus-plane state from untrusted JSON.
 
-Missing/unknown focus is rejected rather than being interpreted as infinity.
+Missing or unknown focus is rejected. It is never read as infinity.
 
 ```ts
 export function parseFocusPlane(value: unknown): FocusPlane;