@photivra/engine 0.2.0 → 0.5.0

package/dist/optics/illumination-vignetting.js.map

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

package/dist/optics/lateral-chromatic-aberration.d.ts

@@ -0,0 +1,117 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type LensFieldPointMm, type RadialDistortionCoefficients } from "./radial-distortion.js";
+export type LateralChromaticAberrationChannel = "red" | "green" | "blue";
+export interface LateralChromaticAberrationProfile {
+    /** Shared physical image-plane normalization radius in millimetres. */
+    normalizationRadiusMm: number;
+    /** Shared undistorted normalized-radius operating envelope. */
+    maximumNormalizedRadius: number;
+    /**
+     * Green-reference base geometric distortion.
+     *
+     * This common mapping is included in every channel. Red/blue CA terms are
+     * added to this base, so callers should not apply a second distortion pass.
+     */
+    baseDistortionCoefficients: RadialDistortionCoefficients;
+    /** Additional red-channel radial coefficients relative to green. */
+    redCoefficientOffset: RadialDistortionCoefficients;
+    /** Additional blue-channel radial coefficients relative to green. */
+    blueCoefficientOffset: RadialDistortionCoefficients;
+}
+export interface CalculateLateralChromaticAberrationMappingInput {
+    /** Ideal/undistorted image-plane point shared by all channels. */
+    imagePointMm: LensFieldPointMm;
+    profile: LateralChromaticAberrationProfile;
+}
+export interface CalculateInverseLateralChromaticAberrationMappingInput {
+    /**
+     * Distorted output image-plane destination. Each output channel is inverse-
+     * mapped independently to its ideal source coordinate.
+     */
+    distortedImagePointMm: LensFieldPointMm;
+    profile: LateralChromaticAberrationProfile;
+}
+export interface CalculateInverseLateralChromaticAberrationMappingsInput {
+    /**
+     * Distorted output image-plane destinations. Each destination is inverse-
+     * mapped independently for red, green, and blue after one profile-resolution
+     * step for the batch.
+     */
+    distortedImagePointsMm: readonly LensFieldPointMm[];
+    profile: LateralChromaticAberrationProfile;
+}
+export interface LateralChromaticAberrationChannelMapping {
+    mappedImagePointMm: LensFieldPointMm;
+    radialScale: number;
+    combinedCoefficients: RadialDistortionCoefficients;
+}
+export interface InverseLateralChromaticAberrationChannelMapping {
+    sourceImagePointMm: LensFieldPointMm;
+    radialScaleAtSource: number;
+    combinedCoefficients: RadialDistortionCoefficients;
+}
+export interface ChannelSeparationVectorMm {
+    x: number;
+    y: number;
+    distance: number;
+}
+export interface LateralChromaticAberrationSeparation {
+    redGreen: ChannelSeparationVectorMm;
+    blueGreen: ChannelSeparationVectorMm;
+    redBlue: ChannelSeparationVectorMm;
+    maximumPairDistanceMm: number;
+}
+export interface LateralChromaticAberrationMapping {
+    direction: "undistorted-to-channel-distorted";
+    referenceChannel: "green";
+    sourceImagePointMm: LensFieldPointMm;
+    channels: {
+        red: LateralChromaticAberrationChannelMapping;
+        green: LateralChromaticAberrationChannelMapping;
+        blue: LateralChromaticAberrationChannelMapping;
+    };
+    separation: LateralChromaticAberrationSeparation;
+}
+export interface InverseLateralChromaticAberrationMapping {
+    direction: "distorted-output-to-channel-sources";
+    referenceChannel: "green";
+    distortedImagePointMm: LensFieldPointMm;
+    channels: {
+        red: InverseLateralChromaticAberrationChannelMapping;
+        green: InverseLateralChromaticAberrationChannelMapping;
+        blue: InverseLateralChromaticAberrationChannelMapping;
+    };
+    sourceSeparation: LateralChromaticAberrationSeparation;
+}
+export interface InverseLateralChromaticAberrationMappings {
+    direction: "distorted-output-to-channel-sources-batch";
+    referenceChannel: "green";
+    mappings: readonly InverseLateralChromaticAberrationMapping[];
+    pointCount: number;
+}
+/**
+ * Calculates generic lateral chromatic-aberration field separation by mapping
+ * one ideal image-plane point through a shared green-reference base distortion
+ * and red/blue radial coefficient offsets.
+ *
+ * This is channel-dependent field mapping, not a blur kernel.
+ */
+export declare function calculateLateralChromaticAberrationMapping(input: CalculateLateralChromaticAberrationMappingInput): CalculationResult<LateralChromaticAberrationMapping>;
+/**
+ * Inverse-maps one distorted output destination independently for the
+ * representative red/green/blue channels.
+ *
+ * Renderers can use the returned per-channel ideal source coordinates for
+ * inverse sampling without inventing chromatic-aberration equations.
+ */
+export declare function calculateInverseLateralChromaticAberrationMapping(input: CalculateInverseLateralChromaticAberrationMappingInput): CalculationResult<InverseLateralChromaticAberrationMapping>;
+/**
+ * Inverse-maps multiple distorted destinations while resolving the shared CA
+ * profile once and validating each combined channel profile once for the
+ * complete batch.
+ *
+ * Per-point values match calculateInverseLateralChromaticAberrationMapping();
+ * provenance is shared once at the batch boundary.
+ */
+export declare function calculateInverseLateralChromaticAberrationMappings(input: CalculateInverseLateralChromaticAberrationMappingsInput): CalculationResult<InverseLateralChromaticAberrationMappings>;
+//# sourceMappingURL=lateral-chromatic-aberration.d.ts.map

package/dist/optics/lateral-chromatic-aberration.d.ts.map

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

package/dist/optics/lateral-chromatic-aberration.js

@@ -0,0 +1,228 @@
+// SPDX-License-Identifier: Apache-2.0
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { calculateInverseRadialDistortionMapping, calculateInverseRadialSourcePointValue, calculateRadialDistortionMapping, validateRadialDistortionProfile } from "./radial-distortion.js";
+function requireFiniteCoefficients(path, coefficients) {
+    for (const key of ["k1", "k2", "k3"]) {
+        if (!Number.isFinite(coefficients[key])) {
+            throw new InvalidScientificInputError(`${path}.${key} must be finite.`);
+        }
+    }
+}
+function addCoefficients(base, offset) {
+    return {
+        k1: base.k1 + offset.k1,
+        k2: base.k2 + offset.k2,
+        k3: base.k3 + offset.k3
+    };
+}
+function resolveProfiles(profile) {
+    requireFiniteCoefficients("profile.baseDistortionCoefficients", profile.baseDistortionCoefficients);
+    requireFiniteCoefficients("profile.redCoefficientOffset", profile.redCoefficientOffset);
+    requireFiniteCoefficients("profile.blueCoefficientOffset", profile.blueCoefficientOffset);
+    const shared = {
+        normalizationRadiusMm: profile.normalizationRadiusMm,
+        maximumNormalizedRadius: profile.maximumNormalizedRadius
+    };
+    return {
+        red: {
+            ...shared,
+            coefficients: addCoefficients(profile.baseDistortionCoefficients, profile.redCoefficientOffset)
+        },
+        green: {
+            ...shared,
+            coefficients: { ...profile.baseDistortionCoefficients }
+        },
+        blue: {
+            ...shared,
+            coefficients: addCoefficients(profile.baseDistortionCoefficients, profile.blueCoefficientOffset)
+        }
+    };
+}
+function withChannelContext(channel, calculate) {
+    try {
+        return calculate();
+    }
+    catch (error) {
+        if (error instanceof InvalidScientificInputError) {
+            throw new InvalidScientificInputError(`Lateral chromatic aberration ${channel} channel: ${error.message}`);
+        }
+        throw error;
+    }
+}
+function separationVector(first, second) {
+    const x = first.x - second.x;
+    const y = first.y - second.y;
+    return {
+        x,
+        y,
+        distance: Math.hypot(x, y)
+    };
+}
+function separations(red, green, blue) {
+    const redGreen = separationVector(red, green);
+    const blueGreen = separationVector(blue, green);
+    const redBlue = separationVector(red, blue);
+    return {
+        redGreen,
+        blueGreen,
+        redBlue,
+        maximumPairDistanceMm: Math.max(redGreen.distance, blueGreen.distance, redBlue.distance)
+    };
+}
+function assumptions() {
+    return [
+        "Generic lateral chromatic aberration is represented as independent radial field mapping for abstract red, green, and blue renderer channels",
+        "Green is the reference field mapping; red and blue coefficient offsets are added to the green-reference base distortion rather than applied as a second warp",
+        "All channel mappings share one physical normalization radius and declared operating envelope",
+        "Each combined channel radial profile must remain one-to-one over the declared operating envelope",
+        "The RGB channel labels are representative rendering channels, not calibrated wavelengths, sensor spectral responses, or CFA primaries",
+        "This model changes channel field coordinates only; it does not blur, change PSF shape, modify channel intensity, or model longitudinal chromatic aberration",
+        "Profiles are generic caller inputs and do not represent a named lens unless separately calibrated with defensible provenance"
+    ];
+}
+/**
+ * Calculates generic lateral chromatic-aberration field separation by mapping
+ * one ideal image-plane point through a shared green-reference base distortion
+ * and red/blue radial coefficient offsets.
+ *
+ * This is channel-dependent field mapping, not a blur kernel.
+ */
+export function calculateLateralChromaticAberrationMapping(input) {
+    const profiles = resolveProfiles(input.profile);
+    const red = withChannelContext("red", () => calculateRadialDistortionMapping({
+        imagePointMm: input.imagePointMm,
+        profile: profiles.red
+    })).value;
+    const green = withChannelContext("green", () => calculateRadialDistortionMapping({
+        imagePointMm: input.imagePointMm,
+        profile: profiles.green
+    })).value;
+    const blue = withChannelContext("blue", () => calculateRadialDistortionMapping({
+        imagePointMm: input.imagePointMm,
+        profile: profiles.blue
+    })).value;
+    return approximationResult({
+        direction: "undistorted-to-channel-distorted",
+        referenceChannel: "green",
+        sourceImagePointMm: { ...input.imagePointMm },
+        channels: {
+            red: {
+                mappedImagePointMm: { ...red.mappedImagePointMm },
+                radialScale: red.radialScale,
+                combinedCoefficients: { ...profiles.red.coefficients }
+            },
+            green: {
+                mappedImagePointMm: { ...green.mappedImagePointMm },
+                radialScale: green.radialScale,
+                combinedCoefficients: { ...profiles.green.coefficients }
+            },
+            blue: {
+                mappedImagePointMm: { ...blue.mappedImagePointMm },
+                radialScale: blue.radialScale,
+                combinedCoefficients: { ...profiles.blue.coefficients }
+            }
+        },
+        separation: separations(red.mappedImagePointMm, green.mappedImagePointMm, blue.mappedImagePointMm)
+    }, "generic-green-reference-lateral-chromatic-aberration", "1.0.0", assumptions());
+}
+/**
+ * Inverse-maps one distorted output destination independently for the
+ * representative red/green/blue channels.
+ *
+ * Renderers can use the returned per-channel ideal source coordinates for
+ * inverse sampling without inventing chromatic-aberration equations.
+ */
+export function calculateInverseLateralChromaticAberrationMapping(input) {
+    const profiles = resolveProfiles(input.profile);
+    const red = withChannelContext("red", () => calculateInverseRadialDistortionMapping({
+        distortedImagePointMm: input.distortedImagePointMm,
+        profile: profiles.red
+    })).value;
+    const green = withChannelContext("green", () => calculateInverseRadialDistortionMapping({
+        distortedImagePointMm: input.distortedImagePointMm,
+        profile: profiles.green
+    })).value;
+    const blue = withChannelContext("blue", () => calculateInverseRadialDistortionMapping({
+        distortedImagePointMm: input.distortedImagePointMm,
+        profile: profiles.blue
+    })).value;
+    return approximationResult({
+        direction: "distorted-output-to-channel-sources",
+        referenceChannel: "green",
+        distortedImagePointMm: { ...input.distortedImagePointMm },
+        channels: {
+            red: {
+                sourceImagePointMm: { ...red.sourceImagePointMm },
+                radialScaleAtSource: red.radialScaleAtSource,
+                combinedCoefficients: { ...profiles.red.coefficients }
+            },
+            green: {
+                sourceImagePointMm: { ...green.sourceImagePointMm },
+                radialScaleAtSource: green.radialScaleAtSource,
+                combinedCoefficients: { ...profiles.green.coefficients }
+            },
+            blue: {
+                sourceImagePointMm: { ...blue.sourceImagePointMm },
+                radialScaleAtSource: blue.radialScaleAtSource,
+                combinedCoefficients: { ...profiles.blue.coefficients }
+            }
+        },
+        sourceSeparation: separations(red.sourceImagePointMm, green.sourceImagePointMm, blue.sourceImagePointMm)
+    }, "generic-inverse-green-reference-lateral-chromatic-aberration", "1.0.0", assumptions());
+}
+/**
+ * Inverse-maps multiple distorted destinations while resolving the shared CA
+ * profile once and validating each combined channel profile once for the
+ * complete batch.
+ *
+ * Per-point values match calculateInverseLateralChromaticAberrationMapping();
+ * provenance is shared once at the batch boundary.
+ */
+export function calculateInverseLateralChromaticAberrationMappings(input) {
+    const profiles = resolveProfiles(input.profile);
+    const validatedProfiles = {
+        red: withChannelContext("red", () => validateRadialDistortionProfile(profiles.red)),
+        green: withChannelContext("green", () => validateRadialDistortionProfile(profiles.green)),
+        blue: withChannelContext("blue", () => validateRadialDistortionProfile(profiles.blue))
+    };
+    const mappings = input.distortedImagePointsMm.map((point, index) => {
+        const red = withChannelContext("red", () => calculateInverseRadialSourcePointValue(point, validatedProfiles.red, `distortedImagePointsMm[${index}]`));
+        const green = withChannelContext("green", () => calculateInverseRadialSourcePointValue(point, validatedProfiles.green, `distortedImagePointsMm[${index}]`));
+        const blue = withChannelContext("blue", () => calculateInverseRadialSourcePointValue(point, validatedProfiles.blue, `distortedImagePointsMm[${index}]`));
+        return {
+            direction: "distorted-output-to-channel-sources",
+            referenceChannel: "green",
+            distortedImagePointMm: { ...point },
+            channels: {
+                red: {
+                    sourceImagePointMm: { ...red.sourceImagePointMm },
+                    radialScaleAtSource: red.radialScaleAtSource,
+                    combinedCoefficients: { ...profiles.red.coefficients }
+                },
+                green: {
+                    sourceImagePointMm: { ...green.sourceImagePointMm },
+                    radialScaleAtSource: green.radialScaleAtSource,
+                    combinedCoefficients: { ...profiles.green.coefficients }
+                },
+                blue: {
+                    sourceImagePointMm: { ...blue.sourceImagePointMm },
+                    radialScaleAtSource: blue.radialScaleAtSource,
+                    combinedCoefficients: { ...profiles.blue.coefficients }
+                }
+            },
+            sourceSeparation: separations(red.sourceImagePointMm, green.sourceImagePointMm, blue.sourceImagePointMm)
+        };
+    });
+    return approximationResult({
+        direction: "distorted-output-to-channel-sources-batch",
+        referenceChannel: "green",
+        mappings,
+        pointCount: mappings.length
+    }, "generic-inverse-green-reference-lateral-chromatic-aberration-batch", "1.0.0", [
+        ...assumptions(),
+        "Combined red/green/blue radial profiles are resolved once for the batch",
+        "Each channel profile is validated once before batch point sampling"
+    ]);
+}
+//# sourceMappingURL=lateral-chromatic-aberration.js.map

package/dist/optics/lateral-chromatic-aberration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lateral-chromatic-aberration.js","sourceRoot":"","sources":["../../src/optics/lateral-chromatic-aberration.ts"],"names":[],"mappings":"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"}

package/dist/optics/psf-foundation.d.ts

@@ -0,0 +1,102 @@
+import { type CalculationProvenance, type CalculationResult } from "../core/calculation-result.js";
+import type { LensFieldPointMm } from "./radial-distortion.js";
+export declare const PSF_FOUNDATION_VERSION: "0.1.0";
+export type PsfContributionId = "geometric-defocus-circle" | "circular-diffraction-first-zero" | "non-circular-diffraction" | "mechanical-pupil-clipping" | "field-curvature" | "field-dependent-aberration" | "field-dependent-bokeh";
+export type PsfContributionStatus = "implemented-diagnostic" | "reserved-contract";
+export interface PsfContributionContract {
+    id: PsfContributionId;
+    status: PsfContributionStatus;
+    dependsOn: readonly ("field-position" | "focus-depth" | "pupil" | "wavelength")[];
+    note: string;
+}
+export interface PsfFoundationContract {
+    version: typeof PSF_FOUNDATION_VERSION;
+    coordinateSpace: "image-plane-metric";
+    fieldAxes: "+X right, +Y up";
+    compositionPolicy: "separate-contributions-no-combined-psf";
+    contributions: readonly PsfContributionContract[];
+    previewReferencePolicy: {
+        previewMayApproximate: true;
+        referenceMayUseHigherFidelity: true;
+        mustPreserveContributionSemantics: true;
+    };
+    notes: readonly string[];
+}
+export interface CalculatePsfFoundationComponentsInput {
+    focalLengthMm: number;
+    aperture: number;
+    focusDistanceM: number;
+    subjectDistanceM: number;
+    /**
+     * Image-plane field position relative to the optical axis, in millimetres.
+     * +X is right and +Y is up.
+     */
+    fieldPointMm: LensFieldPointMm;
+    /**
+     * Physical image-plane radius used only to normalize field position for
+     * cross-case diagnostics. It is not a lens calibration or validity bound.
+     */
+    fieldNormalizationRadiusMm: number;
+    spectralBasis: {
+        kind: "monochromatic";
+        wavelengthNm: number;
+    };
+}
+export interface PsfFoundationComponents {
+    context: {
+        field: {
+            imagePointMm: LensFieldPointMm;
+            radiusMm: number;
+            normalizationRadiusMm: number;
+            normalizedRadius: number;
+        };
+        depth: {
+            focusDistanceM: number;
+            subjectDistanceM: number;
+        };
+        spectralBasis: {
+            kind: "monochromatic";
+            wavelengthNm: number;
+        };
+        pupil: {
+            kind: "ideal-circular-f-number-derived";
+            apertureFNumber: number;
+            diameterMm: number;
+        };
+    };
+    contributions: {
+        geometricDefocus: {
+            id: "geometric-defocus-circle";
+            diameterMm: number;
+            provenance: CalculationProvenance;
+        };
+        circularDiffraction: {
+            id: "circular-diffraction-first-zero";
+            firstZeroDiameterMicrometers: number;
+            provenance: CalculationProvenance;
+        };
+    };
+    composition: {
+        status: "not-composed";
+        note: string;
+    };
+}
+/**
+ * Returns the public PSF/pupil foundation contract.
+ *
+ * The contract describes current diagnostics plus reserved future contribution
+ * ownership. It does not imply that reserved contributions are implemented.
+ */
+export declare function getPsfFoundationContract(): PsfFoundationContract;
+/**
+ * Evaluates the currently implemented PSF-related diagnostics in one explicit
+ * field/depth/spectral/pupil context without combining them into a synthetic
+ * PSF or blur radius.
+ *
+ * Field position is recorded even though the current defocus-circle and
+ * circular-Airy diagnostics are not field dependent. Future field-dependent
+ * contributions can consume the same context without changing these existing
+ * primitives.
+ */
+export declare function calculatePsfFoundationComponents(input: CalculatePsfFoundationComponentsInput): CalculationResult<PsfFoundationComponents>;
+//# sourceMappingURL=psf-foundation.d.ts.map

package/dist/optics/psf-foundation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"psf-foundation.d.ts","sourceRoot":"","sources":["../../src/optics/psf-foundation.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAI/D,eAAO,MAAM,sBAAsB,EAAG,OAAgB,CAAC;AAEvD,MAAM,MAAM,iBAAiB,GACzB,0BAA0B,GAC1B,iCAAiC,GACjC,0BAA0B,GAC1B,2BAA2B,GAC3B,iBAAiB,GACjB,4BAA4B,GAC5B,uBAAuB,CAAC;AAE5B,MAAM,MAAM,qBAAqB,GAC7B,wBAAwB,GACxB,mBAAmB,CAAC;AAExB,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,iBAAiB,CAAC;IACtB,MAAM,EAAE,qBAAqB,CAAC;IAC9B,SAAS,EAAE,SAAS,CAChB,gBAAgB,GAChB,aAAa,GACb,OAAO,GACP,YAAY,CACf,EAAE,CAAC;IACJ,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,sBAAsB,CAAC;IACvC,eAAe,EAAE,oBAAoB,CAAC;IACtC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,iBAAiB,EAAE,wCAAwC,CAAC;IAC5D,aAAa,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAClD,sBAAsB,EAAE;QACtB,qBAAqB,EAAE,IAAI,CAAC;QAC5B,6BAA6B,EAAE,IAAI,CAAC;QACpC,iCAAiC,EAAE,IAAI,CAAC;KACzC,CAAC;IACF,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,qCAAqC;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,YAAY,EAAE,gBAAgB,CAAC;IAC/B;;;OAGG;IACH,0BAA0B,EAAE,MAAM,CAAC;IACnC,aAAa,EAAE;QACb,IAAI,EAAE,eAAe,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE;QACP,KAAK,EAAE;YACL,YAAY,EAAE,gBAAgB,CAAC;YAC/B,QAAQ,EAAE,MAAM,CAAC;YACjB,qBAAqB,EAAE,MAAM,CAAC;YAC9B,gBAAgB,EAAE,MAAM,CAAC;SAC1B,CAAC;QACF,KAAK,EAAE;YACL,cAAc,EAAE,MAAM,CAAC;YACvB,gBAAgB,EAAE,MAAM,CAAC;SAC1B,CAAC;QACF,aAAa,EAAE;YACb,IAAI,EAAE,eAAe,CAAC;YACtB,YAAY,EAAE,MAAM,CAAC;SACtB,CAAC;QACF,KAAK,EAAE;YACL,IAAI,EAAE,iCAAiC,CAAC;YACxC,eAAe,EAAE,MAAM,CAAC;YACxB,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC;KACH,CAAC;IACF,aAAa,EAAE;QACb,gBAAgB,EAAE;YAChB,EAAE,EAAE,0BAA0B,CAAC;YAC/B,UAAU,EAAE,MAAM,CAAC;YACnB,UAAU,EAAE,qBAAqB,CAAC;SACnC,CAAC;QACF,mBAAmB,EAAE;YACnB,EAAE,EAAE,iCAAiC,CAAC;YACtC,4BAA4B,EAAE,MAAM,CAAC;YACrC,UAAU,EAAE,qBAAqB,CAAC;SACnC,CAAC;KACH,CAAC;IACF,WAAW,EAAE;QACX,MAAM,EAAE,cAAc,CAAC;QACvB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AA8DD;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,qBAAqB,CAiBhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qCAAqC,GAC3C,iBAAiB,CAAC,uBAAuB,CAAC,CAiG5C"}

package/dist/optics/psf-foundation.js

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: Apache-2.0
+import { calculatedResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
+import { calculateDefocusCircle } from "./depth-of-field.js";
+import { calculateAiryDisk } from "./diffraction.js";
+export const PSF_FOUNDATION_VERSION = "0.1.0";
+const CONTRIBUTIONS = [
+    {
+        id: "geometric-defocus-circle",
+        status: "implemented-diagnostic",
+        dependsOn: ["focus-depth", "pupil"],
+        note: "Existing thin-lens geometric defocus diameter. This is a blur-circle diagnostic, not a complete intensity PSF."
+    },
+    {
+        id: "circular-diffraction-first-zero",
+        status: "implemented-diagnostic",
+        dependsOn: ["pupil", "wavelength"],
+        note: "Existing ideal circular-pupil first-zero Airy diameter. This is a diffraction-size diagnostic, not a sampled intensity PSF."
+    },
+    {
+        id: "non-circular-diffraction",
+        status: "reserved-contract",
+        dependsOn: ["pupil", "wavelength", "field-position"],
+        note: "Reserved for a defensible pupil-dependent diffraction model. Polygon aperture geometry alone does not implement this contribution."
+    },
+    {
+        id: "mechanical-pupil-clipping",
+        status: "reserved-contract",
+        dependsOn: ["pupil", "field-position"],
+        note: "Reserved for field-dependent pupil clipping/mechanical vignetting that can affect both throughput and PSF/bokeh shape."
+    },
+    {
+        id: "field-curvature",
+        status: "reserved-contract",
+        dependsOn: ["field-position", "focus-depth"],
+        note: "Reserved for field-dependent focus displacement. It must not be represented as geometric distortion."
+    },
+    {
+        id: "field-dependent-aberration",
+        status: "reserved-contract",
+        dependsOn: ["field-position", "focus-depth", "pupil", "wavelength"],
+        note: "Reserved for defensible field-dependent aberration/PSF structure. Do not replace this with a generic lens-sharpness score."
+    },
+    {
+        id: "field-dependent-bokeh",
+        status: "reserved-contract",
+        dependsOn: ["field-position", "focus-depth", "pupil"],
+        note: "Reserved for field-dependent out-of-focus PSF/bokeh behavior, including future cat's-eye effects when pupil clipping is modeled."
+    }
+];
+const NOTES = [
+    "This foundation preserves PSF-related contributions separately; it does not calculate a combined PSF, MTF, or one scalar lens-sharpness result.",
+    "Existing geometric defocus and circular Airy outputs remain independently named scientific diagnostics with their own provenance.",
+    "Reserved contributions describe ownership/dependencies only and do not claim implemented visual behavior.",
+    "Illumination vignetting is a separate throughput-only model and is not a PSF contribution.",
+    "Real-lens PSF calibration requires defensible provenance, compatible reuse rights, and explicit limitations/uncertainty."
+];
+/**
+ * Returns the public PSF/pupil foundation contract.
+ *
+ * The contract describes current diagnostics plus reserved future contribution
+ * ownership. It does not imply that reserved contributions are implemented.
+ */
+export function getPsfFoundationContract() {
+    return {
+        version: PSF_FOUNDATION_VERSION,
+        coordinateSpace: "image-plane-metric",
+        fieldAxes: "+X right, +Y up",
+        compositionPolicy: "separate-contributions-no-combined-psf",
+        contributions: CONTRIBUTIONS.map((contribution) => ({
+            ...contribution,
+            dependsOn: [...contribution.dependsOn]
+        })),
+        previewReferencePolicy: {
+            previewMayApproximate: true,
+            referenceMayUseHigherFidelity: true,
+            mustPreserveContributionSemantics: true
+        },
+        notes: [...NOTES]
+    };
+}
+/**
+ * Evaluates the currently implemented PSF-related diagnostics in one explicit
+ * field/depth/spectral/pupil context without combining them into a synthetic
+ * PSF or blur radius.
+ *
+ * Field position is recorded even though the current defocus-circle and
+ * circular-Airy diagnostics are not field dependent. Future field-dependent
+ * contributions can consume the same context without changing these existing
+ * primitives.
+ */
+export function calculatePsfFoundationComponents(input) {
+    requirePositiveFinite("focalLengthMm", input.focalLengthMm);
+    requirePositiveFinite("aperture", input.aperture);
+    requirePositiveFinite("focusDistanceM", input.focusDistanceM);
+    requirePositiveFinite("subjectDistanceM", input.subjectDistanceM);
+    requirePositiveFinite("fieldNormalizationRadiusMm", input.fieldNormalizationRadiusMm);
+    if (input.spectralBasis?.kind !== "monochromatic") {
+        throw new InvalidScientificInputError('spectralBasis.kind must be "monochromatic".');
+    }
+    requirePositiveFinite("spectralBasis.wavelengthNm", input.spectralBasis.wavelengthNm);
+    if (!Number.isFinite(input.fieldPointMm.x)) {
+        throw new InvalidScientificInputError("fieldPointMm.x must be finite.");
+    }
+    if (!Number.isFinite(input.fieldPointMm.y)) {
+        throw new InvalidScientificInputError("fieldPointMm.y must be finite.");
+    }
+    const defocus = calculateDefocusCircle({
+        focalLengthMm: input.focalLengthMm,
+        aperture: input.aperture,
+        focusDistanceM: input.focusDistanceM,
+        subjectDistanceM: input.subjectDistanceM
+    });
+    const diffraction = calculateAiryDisk({
+        aperture: input.aperture,
+        wavelengthNm: input.spectralBasis.wavelengthNm
+    });
+    const radiusMm = Math.hypot(input.fieldPointMm.x, input.fieldPointMm.y);
+    return calculatedResult({
+        context: {
+            field: {
+                imagePointMm: { ...input.fieldPointMm },
+                radiusMm,
+                normalizationRadiusMm: input.fieldNormalizationRadiusMm,
+                normalizedRadius: radiusMm / input.fieldNormalizationRadiusMm
+            },
+            depth: {
+                focusDistanceM: input.focusDistanceM,
+                subjectDistanceM: input.subjectDistanceM
+            },
+            spectralBasis: {
+                kind: "monochromatic",
+                wavelengthNm: input.spectralBasis.wavelengthNm
+            },
+            pupil: {
+                kind: "ideal-circular-f-number-derived",
+                apertureFNumber: input.aperture,
+                diameterMm: input.focalLengthMm / input.aperture
+            }
+        },
+        contributions: {
+            geometricDefocus: {
+                id: "geometric-defocus-circle",
+                diameterMm: defocus.value.diameterMm,
+                provenance: { ...defocus.provenance }
+            },
+            circularDiffraction: {
+                id: "circular-diffraction-first-zero",
+                firstZeroDiameterMicrometers: diffraction.value.firstZeroDiameterMicrometers,
+                provenance: { ...diffraction.provenance }
+            }
+        },
+        composition: {
+            status: "not-composed",
+            note: "No combined PSF, MTF, convolution kernel, or scalar sharpness value has been calculated."
+        }
+    }, "psf-foundation-separated-components", "1.0.0", [
+        "Current geometric defocus and ideal circular-pupil diffraction diagnostics are evaluated independently",
+        "Field position is explicit context but does not alter the current field-invariant diagnostic primitives",
+        "The result intentionally does not combine defocus and diffraction into one blur radius or PSF",
+        "Illumination vignetting is excluded because it is a separate throughput-only stage"
+    ]);
+}
+//# sourceMappingURL=psf-foundation.js.map

package/dist/optics/psf-foundation.js.map

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