@photivra/engine 1.5.0 → 2.1.0

package/docs/api/optics-thin-lens.md

@@ -1,6 +1,6 @@
 # optics/thin-lens.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
 
 ## calculateThinLensImageDistance
 
@@ -10,8 +10,9 @@ Calculates Gaussian thin-lens image distance:
 
 where f is focal length, s is object distance, and v is image distance.
 
-This is a paraxial ideal-lens model. It does not model real-lens focus
-breathing, pupil magnification, principal-plane movement, or aberrations.
+This is a paraxial (small-angle) ideal-lens model. It does not model
+real-lens focus breathing, pupil magnification, principal-plane movement
+or aberrations.
 
 ```ts
 export function calculateThinLensImageDistance(

package/docs/api/optics-zernike-wavefront.md

@@ -0,0 +1,229 @@
+# optics/zernike-wavefront.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.
+
+## calculateDefocusWavefront
+
+Converts a signed paraxial image-plane defocus into the defocus wave aberration
+W020 = dz / (8 N^2) and its Noll Z4 coefficient W020 / (2 sqrt 3).
+
+Sign convention: dz = sensor distance minus image distance. Positive W020 means the image lies in
+front of the sensor. With pure defocus, the PSF intensity does not depend on the sign.
+
+```ts
+export function calculateDefocusWavefront(
+  input: CalculateDefocusWavefrontInput
+): CalculationResult<DefocusWavefront>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculateDefocusWavefrontInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CalculateDefocusWavefrontInput {
+  /** Signed image-plane defocus, sensor minus image distance, in micrometres. */
+  signedDefocusImagePlaneMicrometers: number;
+  /** Image-side working f-number (image distance / pupil diameter). */
+  workingFNumber: number;
+}
+```
+
+## createWavefrontPupilGrid
+
+Builds a complex-pupil grid: a circular pupil, an optional polygon mask, and an OPD from Zernike
+coefficients, Seidel coefficients or both. If every coefficient is zero, the OPD is exactly zero,
+so the PSF equals the existing aberration-free circular-pupil reference.
+
+```ts
+export function createWavefrontPupilGrid(
+  input: CreateWavefrontPupilGridInput
+): CalculationResult<WavefrontPupilGrid>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateWavefrontPupilGridInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateWavefrontPupilGridInput {
+  /** Pupil diameter in mm; rho = 1 at radius pupilDiameterMm / 2. */
+  pupilDiameterMm: number;
+  /** Odd number of samples across the pupil diameter, from 3 to 63. */
+  samplesAcross: number;
+  zernikeCoefficients?: readonly ZernikeCoefficient[];
+  seidelCoefficients?: SeidelWavefrontCoefficients;
+  /** Required when any field-dependent Seidel coefficient is non-zero. */
+  seidelField?: SeidelFieldPosition;
+  /**
+   * Optional additional aperture mask: a simple polygon in pupil-plane mm (for example the
+   * cat's-eye pupil from calculateMechanicalVignetting). Samples outside it get zero amplitude.
+   */
+  apertureMaskVerticesMm?: readonly { x: number; y: number }[];
+}
+```
+
+## DefocusWavefront
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DefocusWavefront {
+  signedDefocusImagePlaneMicrometers: number;
+  workingFNumber: number;
+  /** Peak defocus coefficient W020 = dz / (8 N^2), micrometres. */
+  w020Micrometers: number;
+  /** Equivalent Noll Z4 coefficient W020 / (2 sqrt 3), micrometres (equals the RMS). */
+  zernikeZ4Micrometers: number;
+}
+```
+
+## estimateMarechalStrehlRatio
+
+Marechal/Mahajan approximation of the Strehl ratio: exp(-(2 pi sigma / lambda)^2). Valid only for a
+small RMS wavefront error (Strehl roughly above 0.3). It is not an exact PSF calculation.
+
+```ts
+export function estimateMarechalStrehlRatio(
+  input: EstimateMarechalStrehlRatioInput
+): CalculationResult<{ strehlRatio: number; rmsWaves: number }>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## EstimateMarechalStrehlRatioInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EstimateMarechalStrehlRatioInput {
+  rmsWavefrontErrorMicrometers: number;
+  wavelengthNm: number;
+}
+```
+
+## evaluateZernikePolynomial
+
+Evaluates the unit-RMS Noll Zernike polynomial at normalised pupil polar coordinates.
+
+```ts
+export function evaluateZernikePolynomial(
+  nollIndex: number,
+  normalizedRadius: number,
+  azimuthRadians: number
+): number;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveZernikeNollOrder
+
+Converts a Noll index to radial order n and signed azimuthal frequency m (Noll 1976).
+
+```ts
+export function resolveZernikeNollOrder(nollIndex: number): ZernikeOrder;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SeidelFieldPosition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SeidelFieldPosition {
+  /** Normalised field height H in [0, 1]. */
+  normalizedFieldHeight: number;
+  /** Image-plane direction of the field point, degrees counter-clockwise from +X. */
+  fieldAzimuthDegrees: number;
+}
+```
+
+## SeidelWavefrontCoefficients
+
+Peak Seidel wave-aberration coefficients in micrometres of optical path difference.
+
+```ts
+export interface SeidelWavefrontCoefficients {
+  /** Defocus rho^2. */
+  w020Micrometers?: number;
+  /** Tilt H rho cos(phi). */
+  w111Micrometers?: number;
+  /** Spherical aberration rho^4. */
+  w040Micrometers?: number;
+  /** Coma H rho^3 cos(phi). */
+  w131Micrometers?: number;
+  /** Astigmatism H^2 rho^2 cos^2(phi). */
+  w222Micrometers?: number;
+  /** Field curvature H^2 rho^2. */
+  w220Micrometers?: number;
+  /** Distortion H^3 rho cos(phi). */
+  w311Micrometers?: number;
+}
+```
+
+## WavefrontPupilGrid
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface WavefrontPupilGrid {
+  /** Grid for LensComplexPupilProfile.grid. Amplitude is 1 inside and 0 outside; OPD is in micrometres. */
+  grid: LensComplexPupilGrid;
+  pupilDiameterMm: number;
+  /** Number of samples with non-zero amplitude. */
+  openSampleCount: number;
+  /** sqrt(sum c_j^2, j >= 2): RMS of the Zernike terms alone over the continuous unit disk. */
+  zernikeRmsMicrometers: number;
+  /** RMS of the sampled OPD over open samples, with piston removed (all terms). */
+  sampledRmsMicrometers: number;
+  /** Peak-to-valley of the sampled OPD over open samples. */
+  sampledPeakToValleyMicrometers: number;
+}
+```
+
+## ZERNIKE_MAXIMUM_NOLL_INDEX
+
+Largest supported Noll index (radial order n <= 10).
+
+```ts
+ZERNIKE_MAXIMUM_NOLL_INDEX = 66
+```
+
+## ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS
+
+Largest odd pupil grid width: 63 x 63 = 3969 samples, within the complex-pupil 4096 limit.
+
+```ts
+ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS = 63
+```
+
+## ZernikeCoefficient
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ZernikeCoefficient {
+  nollIndex: number;
+  /** Coefficient of the unit-RMS Noll polynomial, in micrometres of optical path difference. */
+  coefficientMicrometers: number;
+}
+```
+
+## ZernikeOrder
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ZernikeOrder {
+  nollIndex: number;
+  /** Radial order n. */
+  radialOrder: number;
+  /** Signed azimuthal frequency m. Positive means cos(m theta); negative means sin(|m| theta). */
+  azimuthalFrequency: number;
+}
+```

package/docs/api/output-capture-corrected-sdr.md

@@ -1,10 +1,11 @@
 # output/capture-corrected-sdr.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
 
 ## calculateCaptureCorrectedSdr
 
-Bounded committed capture → color/WB → native correction → oriented output view → SDR. No physical stage activation.
+Runs a bounded committed capture through colour/WB → native lens correction → oriented output
+view → SDR. No physical simulation stage is run.
 
 ```ts
 export function calculateCaptureCorrectedSdr(input: CaptureCorrectedSdrInput): CalculationResult<CaptureCorrectedSdrResult>;
@@ -22,14 +23,15 @@ CAPTURE_CORRECTED_SDR_SCHEMA_VERSION = "0.1.0" as const
 
 ## CaptureCorrectedSdrInput
 
-Explicit native-optical correction binding. Body/lens/mode identities remain producer declarations.
+Input: a capture plus an explicit lens-correction choice in native optical coordinates. Camera
+body, lens and mode identities are taken as the capture producer declared them.
 
 ```ts
 export interface CaptureCorrectedSdrInput extends CaptureSdrInput {
   correction: {
     profile: GenericLensCorrectionProfile;
     state: OpticalProfileState;
-    /** Native optical +X right/+Y up, RGB basis after the selected color/WB operation. */
+    /** Native optical coordinates (+X right, +Y up), in the RGB space after the selected colour/WB step. */
     coordinateFrame: "native-optical-linear-srgb-d65";
     selections: Readonly<Record<string, "on" | "off" | "auto">>;
     selectionKind: ResolvedLensCorrectionPlan["selectionKind"];
@@ -45,7 +47,7 @@ export interface CaptureCorrectedSdrInput extends CaptureSdrInput {
 
 ## CaptureCorrectedSdrResult
 
-Derived output view, never a replacement for the committed capture's physical geometry.
+A derived output view. It never replaces the committed capture's physical geometry.
 
 ```ts
 export interface CaptureCorrectedSdrResult extends Omit<CaptureSdrResult, "schemaVersion"> {
@@ -54,7 +56,7 @@ export interface CaptureCorrectedSdrResult extends Omit<CaptureSdrResult, "schem
   plan: CalculationResult<ResolvedLensCorrectionPlan>;
   correction: ReturnType<typeof calculateLensCorrectedCapture>;
   projection: ReturnType<typeof calculateFieldOfView>;
-  /** Oriented full-output support; child correction plans retain native optical coordinates. */
+  /** Valid-source mask over the full oriented output. The nested correction plans still use native optical coordinates. */
   validSourceMask: readonly boolean[];
   outputView: { imageStateId: string; rect: RasterRect; pixelWidth: number; pixelHeight: number; samples: readonly number[] };
 }
@@ -62,7 +64,8 @@ export interface CaptureCorrectedSdrResult extends Omit<CaptureSdrResult, "schem
 
 ## parseCaptureCorrectedSdrInput
 
-Strict boundary; execution also checks capture optics, native raster binding and source history.
+Strictly parses untrusted input. Running the calculation also checks the capture's optics,
+native pixel-grid binding and source history.
 
 ```ts
 export function parseCaptureCorrectedSdrInput(input: unknown): CaptureCorrectedSdrInput;

package/docs/api/output-capture-geometry.md

@@ -1,6 +1,6 @@
 # output/capture-geometry.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
 
 ## ActiveCaptureFieldOfView
 
@@ -12,8 +12,8 @@ export interface ActiveCaptureFieldOfView {
   horizontalDegrees: number;
   verticalDegrees: number;
   /**
-   * Larger of the two opposite-corner diagonal angular spans. For centered
-   * crops both diagonal spans are equal.
+   * The larger of the two corner-to-corner diagonal angles. For a centred
+   * crop the two diagonals are equal.
    */
   diagonalDegrees: number;
   horizontalBoundsDegrees: {
@@ -39,10 +39,11 @@ export interface ActiveCaptureFieldOfView {
 
 ## calculateActiveCaptureFieldOfView
 
-Calculates asymmetric horizontal/vertical FOV plus opposite-corner diagonal
-spans for the active physical capture area after physical camera orientation.
+Calculates the field of view (FOV) of the active physical capture area after
+camera orientation. Horizontal and vertical FOV can be asymmetric about the
+optical axis; both corner-to-corner diagonals are reported.
 
-Final digital/output crop is intentionally excluded.
+The final digital (output) crop is deliberately not included.
 
 ```ts
 export function calculateActiveCaptureFieldOfView(
@@ -69,9 +70,8 @@ export interface CalculateActiveCaptureFieldOfViewInput {
 
 ## calculateOutputFieldOfView
 
-Calculates final visible field of view after physical active capture,
-orientation, and digital/output crop. Output raster resolution does not
-affect this optical/framing result.
+Calculates the final visible field of view after the active capture area,
+orientation and digital (output) crop. Output resolution does not affect it.
 
 ```ts
 export function calculateOutputFieldOfView(
@@ -111,9 +111,9 @@ export type CaptureOrientation =
 
 ## ImagePlaneMetricPointMm
 
-Pre-orientation optical image-plane coordinate in millimetres.
+A point on the optical image plane, in millimetres, before camera orientation is applied.
 
-Origin is the optical axis; +X points right and +Y points up.
+The origin is the optical axis. +X points right and +Y points up.
 
 ```ts
 export interface ImagePlaneMetricPointMm {
@@ -124,13 +124,12 @@ export interface ImagePlaneMetricPointMm {
 
 ## mapImagePlanePointToOrientedPhysicalUv
 
-Maps a pre-orientation optical image-plane point into normalized coordinates
-of an oriented physical raster region.
+Maps an optical image-plane point (before camera orientation) to normalized
+coordinates in an oriented physical image region.
 
-This is the exact coordinate inverse of
-mapOrientedPhysicalUvToImagePlanePoint(). Points outside the supplied region
-fail closed; a tiny tolerance only absorbs floating-point round-trip noise at
-an edge.
+This is the exact inverse of mapOrientedPhysicalUvToImagePlanePoint(). A point
+outside the region is rejected. A tiny tolerance only absorbs floating-point
+round-trip error at an edge.
 
 ```ts
 export function mapImagePlanePointToOrientedPhysicalUv(
@@ -174,13 +173,13 @@ export interface MapOrientedPhysicalUvToImagePlaneInput {
 
 ## mapOrientedPhysicalUvToImagePlanePoint
 
-Maps normalized coordinates in an oriented physical raster region into the
-pre-orientation optical image plane used by lens-field and camera-mapping
-APIs.
+Maps normalized (0–1) coordinates in an oriented physical image region to the
+optical image plane used by the lens-field and camera-mapping APIs, before
+camera orientation.
 
-The supplied physical bounds use the capture contract's +Y-down basis after
-physical camera orientation. The returned image-plane point uses optical-axis
-origin, +X right and +Y up. No lens or projection equation is applied.
+The input bounds are after camera orientation and use +Y down. The returned
+point has its origin on the optical axis, with +X right and +Y up. No lens or
+projection equation is applied.
 
 ```ts
 export function mapOrientedPhysicalUvToImagePlanePoint(
@@ -287,8 +286,8 @@ export interface RasterVector {
 
 ## resolveCaptureGeometry
 
-Resolves native sensor geometry, active capture, physical camera orientation,
-and final digital/output geometry without conflating their identities.
+Resolves native sensor geometry, active capture area, physical camera orientation
+and final digital (output) geometry, keeping each one distinct.
 
 ```ts
 export function resolveCaptureGeometry(
@@ -314,16 +313,16 @@ export interface ResolveCaptureGeometryInput {
    */
   activeCaptureRect?: RasterRect;
   /**
-   * Final digital/output crop in oriented active-capture raster coordinates.
+   * Final digital (output) crop, in oriented active-capture pixel coordinates.
    *
    * Defaults to the full oriented active capture.
    */
   outputCropRect?: RasterRect;
   /**
-   * Final output raster after optional digital crop/resampling.
+   * Final output image size after the optional digital crop and resampling.
    *
-   * Defaults to the output-crop dimensions. The output raster must preserve
-   * the crop aspect ratio within a small integer-rounding tolerance.
+   * Defaults to the output-crop size. The output must keep the crop's aspect
+   * ratio, allowing only a small tolerance for integer rounding.
    */
   outputRaster?: RasterDimensions;
 }
@@ -354,7 +353,7 @@ export interface ResolvedCaptureGeometry {
     /** Native physical bounds relative to the optical axis. */
     physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
     /**
-     * Current generic model assumes native image samples uniformly span the
+     * The current generic model assumes the native pixels evenly cover the
      * declared physical imaging area.
      */
     imagingAreaDerivation: "uniform-native-raster";
@@ -369,9 +368,9 @@ export interface ResolvedCaptureGeometry {
   };
   output: {
     /**
-     * Digital/output crop expressed in oriented active-capture coordinates.
+     * Digital (output) crop, in oriented active-capture coordinates.
      *
-     * This crop does not mutate physical sensor identity or active-capture
+     * This crop does not change the physical sensor or the active-capture
      * geometry.
      */
     cropRect: RasterRect;
@@ -381,7 +380,7 @@ export interface ResolvedCaptureGeometry {
     physicalBoundsFromOpticalAxisMm: PhysicalBoundsFromOpticalAxisMm;
     centerOffsetFromOpticalAxisMm: RasterVector;
     sourceRetainedAreaFraction: number;
-    /** Pixel-domain resampling from oriented active capture into output. */
+    /** Pixel resampling from the oriented active capture to the output image. */
     orientedCaptureToOutputScale: {
       x: number;
       y: number;
@@ -393,8 +392,8 @@ export interface ResolvedCaptureGeometry {
 
 ## transformNativeRasterPointToOriented
 
-Transforms a continuous native raster edge-coordinate point into oriented
-capture coordinates. Pixel centers can be represented with +0.5 offsets.
+Converts a point in native pixel coordinates to oriented capture coordinates.
+Coordinates are continuous and measured from pixel edges, so a pixel centre is at +0.5.
 
 ```ts
 export function transformNativeRasterPointToOriented(
@@ -430,7 +429,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## transformOrientedRasterPointToNative
 
-Transforms an oriented raster edge-coordinate point back to native coordinates.
+Converts a point in oriented pixel coordinates (measured from pixel edges) back to native coordinates.
 
 ```ts
 export function transformOrientedRasterPointToNative(

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

@@ -1,6 +1,6 @@
 # output/capture-sdr.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
 
 ## calculateCaptureSdr
 
@@ -22,7 +22,7 @@ CAPTURE_SDR_SCHEMA_VERSION = "0.1.0" as const
 
 ## CaptureSdrInput
 
-Select an existing RGB state or explicitly derive one; never estimate WB here.
+Either select an existing RGB image state or derive one explicitly. White balance is never estimated here.
 
 ```ts
 export interface CaptureSdrInput {
@@ -40,7 +40,7 @@ export interface CaptureSdrInput {
 
 ## CaptureSdrResult
 
-Keeps source capture history, optional color derivation and SDR diagnostics distinct.
+Result. The source capture history, the optional colour derivation and the SDR diagnostics are kept separate.
 
 ```ts
 export interface CaptureSdrResult {
@@ -60,7 +60,7 @@ export interface CaptureSdrResult {
 
 ## parseCaptureSdrInput
 
-Validates the capture and explicit color/render choices at an untrusted boundary.
+Validates untrusted input: the capture and the explicit colour and rendering choices.
 
 ```ts
 export function parseCaptureSdrInput(value: unknown): CaptureSdrInput;

package/docs/api/output-crop.md

@@ -1,10 +1,10 @@
 # output/crop.ts public contracts
 
-Package **1.5.0**, root API **1.5.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.
 
 ## calculateCenteredCrop
 
-Calculates dimensions remaining after a centered, same-aspect-ratio crop.
+Calculates the dimensions left after a centred crop that keeps the aspect ratio.
 
 ```ts
 export function calculateCenteredCrop(
@@ -25,8 +25,11 @@ export interface CalculateCenteredCropInput {
   /** 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.
+   * Linear crop factor. 1 means no crop; 1.5 keeps at most 1 / 1.5 of each
+   * dimension. The shorter axis is floor(dimension / cropFactor). The longer
+   * axis is the integer that best matches the source aspect ratio, capped at
+   * floor(dimension / cropFactor). This keeps the aspect ratio as close as
+   * whole pixels allow.
    */
   cropFactor: number;
 }