@photivra/engine 0.6.0 → 1.0.1

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

@@ -0,0 +1,217 @@
+/**
+ * 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.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type EvidenceProvenance } from "../core/evidence-provenance.js";
+import { type FocusPlane } from "./focus-state.js";
+export declare const LENS_SAMPLED_PSF_PROFILE_SCHEMA_VERSION: "0.1.0";
+export declare const LENS_MTF_DIAGNOSTIC_PROFILE_SCHEMA_VERSION: "0.1.0";
+export type LensPsfScientificStatus = "calibrated" | "approximation";
+export type LensPsfUncertainty = {
+    kind: "relative";
+    fraction: number;
+    basis: string;
+} | {
+    kind: "not-quantified";
+    limitation: string;
+};
+export interface LensPsfKernel {
+    widthSamples: number;
+    heightSamples: number;
+    samplePitchMicrometersX: number;
+    samplePitchMicrometersY: number;
+    centerSampleX: number;
+    centerSampleY: number;
+    normalizedIntensity: readonly number[];
+}
+export interface LensPsfGridAxes {
+    focalLengthMm: readonly number[];
+    focusDiopters: readonly number[];
+    apertureFNumber: readonly number[];
+    fieldXmm: readonly number[];
+    fieldYmm: readonly number[];
+    wavelengthNm: readonly number[];
+    signedDefocusImagePlaneMicrometers: readonly number[];
+}
+export interface LensSampledPsfGridCoordinate {
+    focalLengthMm: number;
+    focusDiopters: number;
+    apertureFNumber: number;
+    fieldXmm: number;
+    fieldYmm: number;
+    wavelengthNm: number;
+    signedDefocusImagePlaneMicrometers: number;
+}
+export interface LensSampledPsfGridNode {
+    nodeId: string;
+    coordinate: LensSampledPsfGridCoordinate;
+    kernel: LensPsfKernel;
+    bestFocusImagePlaneOffsetMicrometers: number;
+    relativePupilThroughputFactor: number;
+    evidence: readonly EvidenceProvenance[];
+    uncertainty: LensPsfUncertainty;
+}
+export interface LensSampledPsfProfile {
+    schemaVersion: typeof LENS_SAMPLED_PSF_PROFILE_SCHEMA_VERSION;
+    profileId: string;
+    profileVersion: string;
+    scientificStatus: LensPsfScientificStatus;
+    opticalDomain: "lens-primary-optical-path-only";
+    coordinateSystem: "image-plane-metric";
+    fieldAxes: "+X right, +Y up";
+    kernelEnergyNormalization: "unit-energy-shape";
+    interpolation: "bounded-regular-grid-multilinear";
+    throughputOwnership: "separate-relative-pupil-throughput-factor";
+    responseIncludes: {
+        diffraction: boolean;
+        aberration: boolean;
+        defocus: boolean;
+        pupilClippingShape: boolean;
+    };
+    sensorOpticalStackIncluded: false;
+    sensorSamplingIncluded: false;
+    reconstructionIncluded: false;
+    strayLightIncluded: false;
+    axes: LensPsfGridAxes;
+    nodes: readonly LensSampledPsfGridNode[];
+    evidence: readonly EvidenceProvenance[];
+    limitations: readonly string[];
+}
+export interface ResolveLensSampledPsfInput {
+    profile: LensSampledPsfProfile;
+    focalLengthMm: number;
+    focus: FocusPlane;
+    apertureFNumber: number;
+    fieldPointMm: {
+        x: number;
+        y: number;
+    };
+    wavelengthNm: number;
+    signedDefocusImagePlaneMicrometers: number;
+}
+export interface ResolvedLensSampledPsf {
+    profileId: string;
+    profileVersion: string;
+    scientificStatus: LensPsfScientificStatus;
+    resolutionStatus: "exact-grid-sample" | "interpolated";
+    coordinate: LensSampledPsfGridCoordinate;
+    focus: FocusPlane;
+    kernel: LensPsfKernel;
+    bestFocusImagePlaneOffsetMicrometers: number;
+    relativePupilThroughputFactor: number;
+    sourceNodes: readonly {
+        nodeId: string;
+        weight: number;
+        evidence: readonly EvidenceProvenance[];
+        uncertainty: LensPsfUncertainty;
+    }[];
+    responseIncludes: LensSampledPsfProfile["responseIncludes"];
+    throughputOwnership: "separate-relative-pupil-throughput-factor";
+    longitudinalChromaticFocusMayVaryWithWavelength: true;
+    fieldCurvatureMayVaryWithFieldPosition: true;
+    geometricDistortionModified: false;
+    lateralChromaticPositionShiftApplied: false;
+    sensorOpticalStackIncluded: false;
+    sensorSamplingIncluded: false;
+    reconstructionIncluded: false;
+    strayLightIncluded: false;
+    scalarSharpnessScoreProduced: false;
+}
+export interface LensMtfDiagnosticSample {
+    spatialFrequencyCyclesPerMm: number;
+    sagittalMagnitude: number;
+    tangentialMagnitude: number;
+}
+export interface LensMtfDiagnosticProfile {
+    schemaVersion: typeof LENS_MTF_DIAGNOSTIC_PROFILE_SCHEMA_VERSION;
+    profileId: string;
+    profileVersion: string;
+    opticalDomain: "lens-primary-optical-path-only";
+    phaseInformationAvailable: false;
+    magnitudeMeaning: "mtf-magnitude-only";
+    fieldPointMm: {
+        x: number;
+        y: number;
+    };
+    focalLengthMm: number;
+    focus: FocusPlane;
+    apertureFNumber: number;
+    wavelengthNm: number | null;
+    samples: readonly LensMtfDiagnosticSample[];
+    evidence: readonly EvidenceProvenance[];
+    limitations: readonly string[];
+}
+export interface MtfOnlyPsfRenderabilityAssessment {
+    profileId: string;
+    psfReconstructionAuthorized: false;
+    reason: "mtf-magnitude-lacks-phase-and-does-not-uniquely-determine-psf";
+    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.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * 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.
+ *
+ * @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

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

@@ -0,0 +1 @@
+{"version":3,"file":"lens-psf-profile.d.ts","sourceRoot":"","sources":["../../src/optics/lens-psf-profile.ts"],"names":[],"mappings":"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"}