@photivra/engine 1.5.0 → 2.1.0

package/dist/optics/lens-psf-profile.d.ts

@@ -1,16 +1,18 @@
 /**
- * Module boundary and integration notes.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. Sampled lens PSF
- * shapes bind exact generic optical state, field, wavelength and signed defocus support. Interpolation
- * stays within declared applicability and preserves normalized shape separately from throughput.
- * MTF-only data lacks phase/spatial information and does not authorize rendering a unique PSF.
- * Resolve the bounded sampled PSF for a declared optical state and support point without extrapolation
- * or silently inventing missing dimensions. Sampled lens PSF shapes bind exact generic optical state,
- * field, wavelength and signed defocus support. Interpolation stays within declared applicability and
- * preserves normalized shape separately from throughput. MTF-only data lacks phase/spatial information
- * and does not authorize rendering a unique PSF.
- * @see docs/PSF_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support limits.
+ * Sampled lens PSF (point-spread function) profiles, and MTF-only diagnostic profiles.
+ *
+ * The parsers validate untrusted input and return the normalized typed contract. Unknown enum
+ * values, missing required fields and incompatible scientific data are rejected.
+ *
+ * The resolver finds the sampled PSF for a declared optical state and query point. It never
+ * extrapolates and never invents missing dimensions.
+ *
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @see docs/PSF_FOUNDATION.md for the equations, units, coordinate conventions, known blockers and
+ * support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type EvidenceProvenance } from "../core/evidence-provenance.js";
@@ -26,6 +28,21 @@ export type LensPsfUncertainty = {
     kind: "not-quantified";
     limitation: string;
 };
+/**
+ * Kernel interpolation between regular-grid nodes.
+ * - `bounded-regular-grid-multilinear`: the legacy weighted sum of kernel values. Blending kernels
+ *   whose peaks sit at different positions gives several peaks.
+ * - `bounded-regular-grid-centroid-aligned`: each node kernel is first shifted so its intensity
+ *   centroid sits at the weighted (interpolated) centroid. Then the same multilinear weights are
+ *   applied. Shifted or asymmetric PSFs therefore blend into one peak at the interpolated position.
+ * - `rotationally-symmetric-radial-field-centroid-aligned`: for a rotationally symmetric lens. Nodes
+ *   are declared only along the +X field axis (fieldYmm = [0], fieldXmm >= 0). A query at field
+ *   (x, y) is interpolated, with centroid alignment, at radius hypot(x, y). The kernel is then
+ *   rotated by atan2(y, x) about its centre. The sample pitch must be square.
+ * Shifts and rotations use bilinear resampling. This smooths the kernel slightly (by at most about
+ * one sample). Samples outside the kernel are zero, and the result is renormalised to unit energy.
+ */
+export type LensSampledPsfInterpolation = "bounded-regular-grid-multilinear" | "bounded-regular-grid-centroid-aligned" | "rotationally-symmetric-radial-field-centroid-aligned";
 export interface LensPsfKernel {
     widthSamples: number;
     heightSamples: number;
@@ -71,7 +88,7 @@ export interface LensSampledPsfProfile {
     coordinateSystem: "image-plane-metric";
     fieldAxes: "+X right, +Y up";
     kernelEnergyNormalization: "unit-energy-shape";
-    interpolation: "bounded-regular-grid-multilinear";
+    interpolation: LensSampledPsfInterpolation;
     throughputOwnership: "separate-relative-pupil-throughput-factor";
     responseIncludes: {
         diffraction: boolean;
@@ -159,59 +176,74 @@ export interface MtfOnlyPsfRenderabilityAssessment {
     diagnosticUseAuthorized: true;
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Internal: registers a private profile declaration owned by the engine, so that repeated
+ * resolveLensSampledPsf calls reuse one parse. The declaration is a structured clone that caller code
+ * never sees.
  *
- * Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
- * support. Interpolation stays within declared applicability and preserves normalized shape separately
- * from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
- * unique PSF.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns LensSampledPsfProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The first resolve parses it exactly like untrusted input. It then deep-freezes the declaration and
+ * caches the frozen parse with its node index. A frozen declaration cannot change, so the cached
+ * parse stays exact. Caller objects that were never registered are always parsed again.
+ */
+export declare function markEngineOwnedLensSampledPsfProfile(value: unknown): void;
+/**
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
+ *
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns LensSampledPsfProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function parseLensSampledPsfProfile(value: unknown): LensSampledPsfProfile;
 /**
- * Resolve the bounded sampled PSF for a declared optical state and support point without extrapolation
- * or silently inventing missing dimensions.
+ * Internal (2.0 performance): the kernel resolveLensSampledPsf returns for the same input, computed by
+ * the same code without building the result envelope. Throws whenever resolveLensSampledPsf would throw
+ * before its envelope. Not exported from the package.
+ */
+export declare function resolveLensSampledPsfKernel(input: ResolveLensSampledPsfInput): LensPsfKernel;
+/**
+ * Resolves the sampled PSF for a declared optical state and query point. It never extrapolates and
+ * never invents missing dimensions.
  *
- * Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
- * support. Interpolation stays within declared applicability and preserves normalized shape separately
- * from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
- * unique PSF.
- * @param input - ResolveLensSampledPsfInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<ResolvedLensSampledPsf>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @param input - ResolveLensSampledPsfInput. See that type for coordinates, units and profile binding.
+ * @returns CalculationResult<ResolvedLensSampledPsf>. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function resolveLensSampledPsf(input: ResolveLensSampledPsfInput): CalculationResult<ResolvedLensSampledPsf>;
 /**
- * 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.
  *
- * Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
- * support. Interpolation stays within declared applicability and preserves normalized shape separately
- * from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
- * unique PSF.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns LensMtfDiagnosticProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns LensMtfDiagnosticProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function parseLensMtfDiagnosticProfile(value: unknown): LensMtfDiagnosticProfile;
 /**
- * Explain why MTF-only evidence cannot determine a unique renderable PSF; return blockers instead of
- * fabricating phase information.
+ * Explains why MTF-only evidence cannot determine one unique renderable PSF. Returns blockers instead
+ * of making up phase information.
  *
- * Sampled lens PSF shapes bind exact generic optical state, field, wavelength and signed defocus
- * support. Interpolation stays within declared applicability and preserves normalized shape separately
- * from throughput. MTF-only data lacks phase/spatial information and does not authorize rendering a
- * unique PSF.
- * @param profile - LensMtfDiagnosticProfile. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns MtfOnlyPsfRenderabilityAssessment. Read structured blockers before consuming an authorization.
+ * A sampled lens PSF is tied to an exact generic optical state and to declared ranges of field
+ * position, wavelength and signed defocus. Interpolation stays inside those declared ranges. It keeps
+ * the normalized shape separate from the throughput. MTF (modulation transfer function) data alone
+ * has no phase or spatial information, so it cannot justify rendering one unique PSF.
+ * @param profile - LensMtfDiagnosticProfile. See that type for coordinates, units and profile binding.
+ * @returns MtfOnlyPsfRenderabilityAssessment. Read the structured blockers before relying on any authorization.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function assessMtfOnlyPsfRenderability(profile: LensMtfDiagnosticProfile): MtfOnlyPsfRenderabilityAssessment;
-//# sourceMappingURL=lens-psf-profile.d.ts.map