@photivra/engine 1.4.0 → 2.0.0

package/dist/optics/zernike-wavefront.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Describes lens aberrations as a wavefront, for the complex-pupil PSF (point-spread function)
+ * reference.
+ *
+ * This module builds the declared pupil grid: relative amplitude plus optical path difference (OPD)
+ * in micrometres. calculateLensComplexPupilPsf() uses that grid unchanged. This module does no light
+ * propagation itself.
+ *
+ * Zernike polynomials use Noll's single index j >= 1 and Noll's normalisation (Noll 1976, JOSA
+ * 66:207):
+ * - m = 0: Z_j = sqrt(n + 1) R_n^0(rho)
+ * - m != 0: Z_j = sqrt(2 (n + 1)) R_n^|m|(rho) cos(m theta) for even j, or sin(m theta) for odd j
+ * So each term has an RMS of 1 over the unit disk. The RMS wavefront error of sum_j c_j Z_j (piston
+ * excluded) is sqrt(sum_{j>=2} c_j^2). The radial polynomial R_n^m is the standard one in Noll's
+ * nomenclature (Mathar, arXiv:0809.2368, eq. 1, free). Also see: Born & Wolf, Principles of Optics,
+ * 7th ed., sec. 9.2 and app. VII.
+ *
+ * Primary (Seidel) aberrations use the wave-aberration expansion in normalised field height H and
+ * normalised pupil coordinates (rho, phi), phi measured from the field direction (Hopkins 1950,
+ * Wave Theory of Aberrations; Wyant & Creath 1992, Applied Optics and Optical Engineering XI ch. 1):
+ *   W = W020 rho^2 + W111 H rho cos(phi) + W040 rho^4 + W131 H rho^3 cos(phi)
+ *     + W222 H^2 rho^2 cos^2(phi) + W220 H^2 rho^2 + W311 H^3 rho cos(phi).
+ *
+ * Paraxial defocus: an image-plane defocus dz at working f-number N gives W020 = dz / (8 N^2)
+ * (Wyant & Creath 1992, Applied Optics and Optical Engineering XI ch. 1, eq. 18, free author copy.
+ * Also see: Goodman, Introduction to Fourier Optics, 3rd ed., sec. 6.4; Mahajan, Optical Imaging and
+ * Aberrations Part I, sec. 3.4). That is a Zernike Z4 coefficient of W020 / (2 sqrt 3).
+ *
+ * Marechal/Mahajan approximation: Strehl ratio ~ exp(-(2 pi sigma / lambda)^2) for a small RMS
+ * wavefront error sigma (Marechal 1947; Mahajan 1982 JOSA 72:1258; free: Wyant & Creath 1992,
+ * ch. 1, eq. 67). It is an approximation, valid
+ * roughly for Strehl ratios above 0.3.
+ *
+ * Pupil coordinates are in metric units, aligned with the image plane (+X right, +Y up). theta is
+ * measured counter-clockwise from +X.
+ * @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 { LensComplexPupilGrid } from "./complex-pupil-psf.js";
+/** Largest supported Noll index (radial order n <= 10). */
+export declare const ZERNIKE_MAXIMUM_NOLL_INDEX = 66;
+/** Largest odd pupil grid width: 63 x 63 = 3969 samples, within the complex-pupil 4096 limit. */
+export declare const ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS = 63;
+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;
+}
+export interface ZernikeCoefficient {
+    nollIndex: number;
+    /** Coefficient of the unit-RMS Noll polynomial, in micrometres of optical path difference. */
+    coefficientMicrometers: number;
+}
+/** Peak Seidel wave-aberration coefficients in micrometres of optical path difference. */
+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;
+}
+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;
+}
+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;
+    }[];
+}
+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;
+}
+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;
+}
+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;
+}
+export interface EstimateMarechalStrehlRatioInput {
+    rmsWavefrontErrorMicrometers: number;
+    wavelengthNm: number;
+}
+/** Converts a Noll index to radial order n and signed azimuthal frequency m (Noll 1976). */
+export declare function resolveZernikeNollOrder(nollIndex: number): ZernikeOrder;
+/** Evaluates the unit-RMS Noll Zernike polynomial at normalised pupil polar coordinates. */
+export declare function evaluateZernikePolynomial(nollIndex: number, normalizedRadius: number, azimuthRadians: number): number;
+/**
+ * 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.
+ */
+export declare function createWavefrontPupilGrid(input: CreateWavefrontPupilGridInput): CalculationResult<WavefrontPupilGrid>;
+/**
+ * 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.
+ */
+export declare function calculateDefocusWavefront(input: CalculateDefocusWavefrontInput): CalculationResult<DefocusWavefront>;
+/**
+ * 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.
+ */
+export declare function estimateMarechalStrehlRatio(input: EstimateMarechalStrehlRatioInput): CalculationResult<{
+    strehlRatio: number;
+    rmsWaves: number;
+}>;

package/dist/optics/zernike-wavefront.js

@@ -0,0 +1,352 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Describes lens aberrations as a wavefront, for the complex-pupil PSF (point-spread function)
+ * reference.
+ *
+ * This module builds the declared pupil grid: relative amplitude plus optical path difference (OPD)
+ * in micrometres. calculateLensComplexPupilPsf() uses that grid unchanged. This module does no light
+ * propagation itself.
+ *
+ * Zernike polynomials use Noll's single index j >= 1 and Noll's normalisation (Noll 1976, JOSA
+ * 66:207):
+ * - m = 0: Z_j = sqrt(n + 1) R_n^0(rho)
+ * - m != 0: Z_j = sqrt(2 (n + 1)) R_n^|m|(rho) cos(m theta) for even j, or sin(m theta) for odd j
+ * So each term has an RMS of 1 over the unit disk. The RMS wavefront error of sum_j c_j Z_j (piston
+ * excluded) is sqrt(sum_{j>=2} c_j^2). The radial polynomial R_n^m is the standard one in Noll's
+ * nomenclature (Mathar, arXiv:0809.2368, eq. 1, free). Also see: Born & Wolf, Principles of Optics,
+ * 7th ed., sec. 9.2 and app. VII.
+ *
+ * Primary (Seidel) aberrations use the wave-aberration expansion in normalised field height H and
+ * normalised pupil coordinates (rho, phi), phi measured from the field direction (Hopkins 1950,
+ * Wave Theory of Aberrations; Wyant & Creath 1992, Applied Optics and Optical Engineering XI ch. 1):
+ *   W = W020 rho^2 + W111 H rho cos(phi) + W040 rho^4 + W131 H rho^3 cos(phi)
+ *     + W222 H^2 rho^2 cos^2(phi) + W220 H^2 rho^2 + W311 H^3 rho cos(phi).
+ *
+ * Paraxial defocus: an image-plane defocus dz at working f-number N gives W020 = dz / (8 N^2)
+ * (Wyant & Creath 1992, Applied Optics and Optical Engineering XI ch. 1, eq. 18, free author copy.
+ * Also see: Goodman, Introduction to Fourier Optics, 3rd ed., sec. 6.4; Mahajan, Optical Imaging and
+ * Aberrations Part I, sec. 3.4). That is a Zernike Z4 coefficient of W020 / (2 sqrt 3).
+ *
+ * Marechal/Mahajan approximation: Strehl ratio ~ exp(-(2 pi sigma / lambda)^2) for a small RMS
+ * wavefront error sigma (Marechal 1947; Mahajan 1982 JOSA 72:1258; free: Wyant & Creath 1992,
+ * ch. 1, eq. 67). It is an approximation, valid
+ * roughly for Strehl ratios above 0.3.
+ *
+ * Pupil coordinates are in metric units, aligned with the image plane (+X right, +Y up). theta is
+ * measured counter-clockwise from +X.
+ * @see docs/PSF_FOUNDATION.md for the equations, units, coordinate conventions, known blockers and
+ * support limits.
+ */
+import { approximationResult, calculatedResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+/** Largest supported Noll index (radial order n <= 10). */
+export const ZERNIKE_MAXIMUM_NOLL_INDEX = 66;
+/** Largest odd pupil grid width: 63 x 63 = 3969 samples, within the complex-pupil 4096 limit. */
+export const ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS = 63;
+function requireFinite(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new InvalidScientificInputError(`${name} must be finite.`);
+    }
+    return value;
+}
+function requireNollIndex(value) {
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < 1 ||
+        value > ZERNIKE_MAXIMUM_NOLL_INDEX) {
+        throw new InvalidScientificInputError(`nollIndex must be an integer from 1 through ${ZERNIKE_MAXIMUM_NOLL_INDEX}.`);
+    }
+    return value;
+}
+/** Converts a Noll index to radial order n and signed azimuthal frequency m (Noll 1976). */
+export function resolveZernikeNollOrder(nollIndex) {
+    const j = requireNollIndex(nollIndex);
+    let n = 0;
+    while (((n + 1) * (n + 2)) / 2 < j) {
+        n += 1;
+    }
+    // Position within radial order n; |m| increases with it, two indices per non-zero |m|.
+    const k = j - (n * (n + 1)) / 2 - 1;
+    const absoluteM = n % 2 === 0 ? 2 * Math.floor((k + 1) / 2) : 2 * Math.floor(k / 2) + 1;
+    return {
+        nollIndex: j,
+        radialOrder: n,
+        azimuthalFrequency: absoluteM === 0 ? 0 : j % 2 === 0 ? absoluteM : -absoluteM
+    };
+}
+function factorial(value) {
+    let result = 1;
+    for (let k = 2; k <= value; k += 1)
+        result *= k;
+    return result;
+}
+function radialPolynomial(n, m, rho) {
+    let sum = 0;
+    for (let k = 0; k <= (n - m) / 2; k += 1) {
+        const coefficient = ((k % 2 === 0 ? 1 : -1) * factorial(n - k)) /
+            (factorial(k) * factorial((n + m) / 2 - k) * factorial((n - m) / 2 - k));
+        sum += coefficient * rho ** (n - 2 * k);
+    }
+    return sum;
+}
+/** Evaluates the unit-RMS Noll Zernike polynomial at normalised pupil polar coordinates. */
+export function evaluateZernikePolynomial(nollIndex, normalizedRadius, azimuthRadians) {
+    const order = resolveZernikeNollOrder(nollIndex);
+    const rho = requireFinite("normalizedRadius", normalizedRadius);
+    const theta = requireFinite("azimuthRadians", azimuthRadians);
+    if (rho < 0 || rho > 1 + 1e-12) {
+        throw new InvalidScientificInputError("normalizedRadius must lie in [0, 1].");
+    }
+    const n = order.radialOrder;
+    const m = Math.abs(order.azimuthalFrequency);
+    const radial = radialPolynomial(n, m, Math.min(1, rho));
+    if (m === 0) {
+        return Math.sqrt(n + 1) * radial;
+    }
+    const angular = order.azimuthalFrequency > 0 ? Math.cos(m * theta) : Math.sin(m * theta);
+    return Math.sqrt(2 * (n + 1)) * radial * angular;
+}
+function parseZernike(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value)) {
+        throw new InvalidConfigurationError("zernikeCoefficients must be an array.");
+    }
+    const seen = new Set();
+    return value.map((entry, index) => {
+        if (typeof entry !== "object" || entry === null) {
+            throw new InvalidConfigurationError(`zernikeCoefficients[${index}] must be an object.`);
+        }
+        const nollIndex = requireNollIndex(entry.nollIndex);
+        if (seen.has(nollIndex)) {
+            throw new InvalidScientificInputError("zernikeCoefficients must not repeat a nollIndex.");
+        }
+        seen.add(nollIndex);
+        return {
+            nollIndex,
+            coefficientMicrometers: requireFinite(`zernikeCoefficients[${index}].coefficientMicrometers`, entry.coefficientMicrometers)
+        };
+    });
+}
+const SEIDEL_KEYS = [
+    "w020Micrometers",
+    "w111Micrometers",
+    "w040Micrometers",
+    "w131Micrometers",
+    "w222Micrometers",
+    "w220Micrometers",
+    "w311Micrometers"
+];
+function parseSeidel(value) {
+    const result = {
+        w020Micrometers: 0,
+        w111Micrometers: 0,
+        w040Micrometers: 0,
+        w131Micrometers: 0,
+        w222Micrometers: 0,
+        w220Micrometers: 0,
+        w311Micrometers: 0
+    };
+    if (value === undefined)
+        return result;
+    if (typeof value !== "object" || value === null) {
+        throw new InvalidConfigurationError("seidelCoefficients must be an object.");
+    }
+    for (const key of Object.keys(value)) {
+        if (!SEIDEL_KEYS.includes(key)) {
+            throw new InvalidConfigurationError(`seidelCoefficients.${key} is not supported.`);
+        }
+    }
+    for (const key of SEIDEL_KEYS) {
+        if (value[key] !== undefined) {
+            result[key] = requireFinite(`seidelCoefficients.${key}`, value[key]);
+        }
+    }
+    return result;
+}
+function pointInPolygon(x, y, vertices) {
+    let inside = false;
+    for (let i = 0, j = vertices.length - 1; i < vertices.length; j = i, i += 1) {
+        const a = vertices[i];
+        const b = vertices[j];
+        if (a.y > y !== b.y > y &&
+            x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x) {
+            inside = !inside;
+        }
+    }
+    return inside;
+}
+function parseMask(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.length < 3 || value.length > 4096) {
+        throw new InvalidScientificInputError("apertureMaskVerticesMm must contain 3 through 4096 vertices.");
+    }
+    return value.map((vertex, index) => {
+        if (typeof vertex !== "object" || vertex === null) {
+            throw new InvalidConfigurationError(`apertureMaskVerticesMm[${index}] must be an object.`);
+        }
+        return {
+            x: requireFinite(`apertureMaskVerticesMm[${index}].x`, vertex.x),
+            y: requireFinite(`apertureMaskVerticesMm[${index}].y`, vertex.y)
+        };
+    });
+}
+/**
+ * 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.
+ */
+export function createWavefrontPupilGrid(input) {
+    requireInputKeys(input, "createWavefrontPupilGrid", ["pupilDiameterMm", "samplesAcross", "zernikeCoefficients", "seidelCoefficients", "seidelField", "apertureMaskVerticesMm"]);
+    requirePositiveFinite("pupilDiameterMm", input.pupilDiameterMm);
+    const n = input.samplesAcross;
+    if (!Number.isSafeInteger(n) ||
+        n < 3 ||
+        n > ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS ||
+        n % 2 === 0) {
+        throw new InvalidScientificInputError(`samplesAcross must be an odd integer from 3 through ${ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS}.`);
+    }
+    const zernike = parseZernike(input.zernikeCoefficients);
+    const seidel = parseSeidel(input.seidelCoefficients);
+    const mask = parseMask(input.apertureMaskVerticesMm);
+    const fieldDependent = seidel.w111Micrometers !== 0 ||
+        seidel.w131Micrometers !== 0 ||
+        seidel.w222Micrometers !== 0 ||
+        seidel.w220Micrometers !== 0 ||
+        seidel.w311Micrometers !== 0;
+    let fieldHeight = 0;
+    let fieldAzimuth = 0;
+    if (input.seidelField !== undefined) {
+        if (typeof input.seidelField !== "object" || input.seidelField === null) {
+            throw new InvalidConfigurationError("seidelField must be an object.");
+        }
+        fieldHeight = requireFinite("seidelField.normalizedFieldHeight", input.seidelField.normalizedFieldHeight);
+        if (fieldHeight < 0 || fieldHeight > 1) {
+            throw new InvalidScientificInputError("seidelField.normalizedFieldHeight must lie in [0, 1].");
+        }
+        fieldAzimuth =
+            (requireFinite("seidelField.fieldAzimuthDegrees", input.seidelField.fieldAzimuthDegrees) *
+                Math.PI) /
+                180;
+    }
+    else if (fieldDependent) {
+        throw new InvalidScientificInputError("seidelField is required when a field-dependent Seidel coefficient is non-zero.");
+    }
+    const radiusMm = input.pupilDiameterMm / 2;
+    const pitch = input.pupilDiameterMm / (n - 1);
+    const center = (n - 1) / 2;
+    const amplitude = [];
+    const opd = [];
+    const open = [];
+    for (let row = 0; row < n; row += 1) {
+        for (let column = 0; column < n; column += 1) {
+            const xMm = (column - center) * pitch;
+            const yMm = (row - center) * pitch;
+            const rho = Math.hypot(xMm, yMm) / radiusMm;
+            const inside = rho <= 1 + 1e-12 && (mask === undefined || pointInPolygon(xMm, yMm, mask));
+            if (!inside) {
+                amplitude.push(0);
+                opd.push(0);
+                continue;
+            }
+            const r = Math.min(1, rho);
+            const theta = Math.atan2(yMm, xMm);
+            let w = 0;
+            for (const term of zernike) {
+                if (term.coefficientMicrometers !== 0) {
+                    w += term.coefficientMicrometers * evaluateZernikePolynomial(term.nollIndex, r, theta);
+                }
+            }
+            const cosPhi = Math.cos(theta - fieldAzimuth);
+            const r2 = r * r;
+            w +=
+                seidel.w020Micrometers * r2 +
+                    seidel.w040Micrometers * r2 * r2 +
+                    seidel.w111Micrometers * fieldHeight * r * cosPhi +
+                    seidel.w131Micrometers * fieldHeight * r2 * r * cosPhi +
+                    seidel.w222Micrometers * fieldHeight * fieldHeight * r2 * cosPhi * cosPhi +
+                    seidel.w220Micrometers * fieldHeight * fieldHeight * r2 +
+                    seidel.w311Micrometers * fieldHeight ** 3 * r * cosPhi;
+            amplitude.push(1);
+            opd.push(w);
+            open.push(w);
+        }
+    }
+    if (open.length === 0) {
+        throw new InvalidScientificInputError("The aperture mask leaves no open pupil samples.");
+    }
+    const mean = open.reduce((sum, value) => sum + value, 0) / open.length;
+    const variance = open.reduce((sum, value) => sum + (value - mean) ** 2, 0) / open.length;
+    const zernikeRms = Math.sqrt(zernike
+        .filter((term) => term.nollIndex >= 2)
+        .reduce((sum, term) => sum + term.coefficientMicrometers ** 2, 0));
+    return approximationResult({
+        grid: {
+            widthSamples: n,
+            heightSamples: n,
+            pupilSamplePitchMmX: pitch,
+            pupilSamplePitchMmY: pitch,
+            centerSampleX: center,
+            centerSampleY: center,
+            relativeAmplitude: amplitude,
+            opticalPathDifferenceMicrometers: opd
+        },
+        pupilDiameterMm: input.pupilDiameterMm,
+        openSampleCount: open.length,
+        zernikeRmsMicrometers: zernikeRms,
+        sampledRmsMicrometers: Math.sqrt(variance),
+        sampledPeakToValleyMicrometers: Math.max(...open) - Math.min(...open)
+    }, "zernike-seidel-wavefront-pupil-grid", "1.0.0", [
+        "Uniform unit amplitude inside the circular pupil (and inside the optional polygon mask); zero outside",
+        "Noll-indexed, unit-RMS Zernike polynomials over the unit disk; Seidel terms are peak wave-aberration coefficients",
+        "Pupil coordinates are metric and aligned with the image plane (+X right, +Y up)",
+        "Sampled RMS differs slightly from the continuous Zernike RMS because the disk is represented by discrete samples",
+        "Coefficients are caller inputs; no named-lens calibration is implied"
+    ]);
+}
+/**
+ * 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.
+ */
+export function calculateDefocusWavefront(input) {
+    requireInputKeys(input, "calculateDefocusWavefront", ["signedDefocusImagePlaneMicrometers", "workingFNumber"]);
+    const dz = requireFinite("signedDefocusImagePlaneMicrometers", input.signedDefocusImagePlaneMicrometers);
+    requirePositiveFinite("workingFNumber", input.workingFNumber);
+    const w020 = dz / (8 * input.workingFNumber * input.workingFNumber);
+    return calculatedResult({
+        signedDefocusImagePlaneMicrometers: dz,
+        workingFNumber: input.workingFNumber,
+        w020Micrometers: w020,
+        zernikeZ4Micrometers: w020 / (2 * Math.sqrt(3))
+    }, "paraxial-defocus-wavefront", "1.0.0", [
+        "Paraxial (small-angle) relation between longitudinal image-plane defocus and the rho^2 wave aberration",
+        "Sign convention: defocus is sensor minus image distance"
+    ]);
+}
+/**
+ * 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.
+ */
+export function estimateMarechalStrehlRatio(input) {
+    requireInputKeys(input, "estimateMarechalStrehlRatio", ["rmsWavefrontErrorMicrometers", "wavelengthNm"]);
+    const sigma = requireFinite("rmsWavefrontErrorMicrometers", input.rmsWavefrontErrorMicrometers);
+    if (sigma < 0) {
+        throw new InvalidScientificInputError("rmsWavefrontErrorMicrometers must be non-negative.");
+    }
+    requirePositiveFinite("wavelengthNm", input.wavelengthNm);
+    const rmsWaves = sigma / (input.wavelengthNm / 1000);
+    return approximationResult({
+        strehlRatio: Math.exp(-((2 * Math.PI * rmsWaves) ** 2)),
+        rmsWaves
+    }, "marechal-mahajan-strehl-approximation", "1.0.0", [
+        "Strehl ratio approximated as exp(-(2 pi sigma / lambda)^2) (Marechal 1947; Mahajan 1982)",
+        "Valid for small RMS wavefront error, roughly Strehl above 0.3; it is not an exact PSF evaluation"
+    ]);
+}
+//# sourceMappingURL=zernike-wavefront.js.map

package/dist/optics/zernike-wavefront.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zernike-wavefront.js","sourceRoot":"","sources":["../../src/optics/zernike-wavefront.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Describes lens aberrations as a wavefront, for the complex-pupil PSF (point-spread function)\n * reference.\n *\n * This module builds the declared pupil grid: relative amplitude plus optical path difference (OPD)\n * in micrometres. calculateLensComplexPupilPsf() uses that grid unchanged. This module does no light\n * propagation itself.\n *\n * Zernike polynomials use Noll's single index j >= 1 and Noll's normalisation (Noll 1976, JOSA\n * 66:207):\n * - m = 0: Z_j = sqrt(n + 1) R_n^0(rho)\n * - m != 0: Z_j = sqrt(2 (n + 1)) R_n^|m|(rho) cos(m theta) for even j, or sin(m theta) for odd j\n * So each term has an RMS of 1 over the unit disk. The RMS wavefront error of sum_j c_j Z_j (piston\n * excluded) is sqrt(sum_{j>=2} c_j^2). The radial polynomial R_n^m is the standard one in Noll's\n * nomenclature (Mathar, arXiv:0809.2368, eq. 1, free). Also see: Born & Wolf, Principles of Optics,\n * 7th ed., sec. 9.2 and app. VII.\n *\n * Primary (Seidel) aberrations use the wave-aberration expansion in normalised field height H and\n * normalised pupil coordinates (rho, phi), phi measured from the field direction (Hopkins 1950,\n * Wave Theory of Aberrations; Wyant & Creath 1992, Applied Optics and Optical Engineering XI ch. 1):\n *   W = W020 rho^2 + W111 H rho cos(phi) + W040 rho^4 + W131 H rho^3 cos(phi)\n *     + W222 H^2 rho^2 cos^2(phi) + W220 H^2 rho^2 + W311 H^3 rho cos(phi).\n *\n * Paraxial defocus: an image-plane defocus dz at working f-number N gives W020 = dz / (8 N^2)\n * (Wyant & Creath 1992, Applied Optics and Optical Engineering XI ch. 1, eq. 18, free author copy.\n * Also see: Goodman, Introduction to Fourier Optics, 3rd ed., sec. 6.4; Mahajan, Optical Imaging and\n * Aberrations Part I, sec. 3.4). That is a Zernike Z4 coefficient of W020 / (2 sqrt 3).\n *\n * Marechal/Mahajan approximation: Strehl ratio ~ exp(-(2 pi sigma / lambda)^2) for a small RMS\n * wavefront error sigma (Marechal 1947; Mahajan 1982 JOSA 72:1258; free: Wyant & Creath 1992,\n * ch. 1, eq. 67). It is an approximation, valid\n * roughly for Strehl ratios above 0.3.\n *\n * Pupil coordinates are in metric units, aligned with the image plane (+X right, +Y up). theta is\n * measured counter-clockwise from +X.\n * @see docs/PSF_FOUNDATION.md for the equations, units, coordinate conventions, known blockers and\n * support limits.\n */\n\nimport {\n  approximationResult,\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport type { LensComplexPupilGrid } from \"./complex-pupil-psf.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\n/** Largest supported Noll index (radial order n <= 10). */\nexport const ZERNIKE_MAXIMUM_NOLL_INDEX = 66;\n/** Largest odd pupil grid width: 63 x 63 = 3969 samples, within the complex-pupil 4096 limit. */\nexport const ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS = 63;\n\nexport interface ZernikeOrder {\n  nollIndex: number;\n  /** Radial order n. */\n  radialOrder: number;\n  /** Signed azimuthal frequency m. Positive means cos(m theta); negative means sin(|m| theta). */\n  azimuthalFrequency: number;\n}\n\nexport interface ZernikeCoefficient {\n  nollIndex: number;\n  /** Coefficient of the unit-RMS Noll polynomial, in micrometres of optical path difference. */\n  coefficientMicrometers: number;\n}\n\n/** Peak Seidel wave-aberration coefficients in micrometres of optical path difference. */\nexport interface SeidelWavefrontCoefficients {\n  /** Defocus rho^2. */\n  w020Micrometers?: number;\n  /** Tilt H rho cos(phi). */\n  w111Micrometers?: number;\n  /** Spherical aberration rho^4. */\n  w040Micrometers?: number;\n  /** Coma H rho^3 cos(phi). */\n  w131Micrometers?: number;\n  /** Astigmatism H^2 rho^2 cos^2(phi). */\n  w222Micrometers?: number;\n  /** Field curvature H^2 rho^2. */\n  w220Micrometers?: number;\n  /** Distortion H^3 rho cos(phi). */\n  w311Micrometers?: number;\n}\n\nexport interface SeidelFieldPosition {\n  /** Normalised field height H in [0, 1]. */\n  normalizedFieldHeight: number;\n  /** Image-plane direction of the field point, degrees counter-clockwise from +X. */\n  fieldAzimuthDegrees: number;\n}\n\nexport interface CreateWavefrontPupilGridInput {\n  /** Pupil diameter in mm; rho = 1 at radius pupilDiameterMm / 2. */\n  pupilDiameterMm: number;\n  /** Odd number of samples across the pupil diameter, from 3 to 63. */\n  samplesAcross: number;\n  zernikeCoefficients?: readonly ZernikeCoefficient[];\n  seidelCoefficients?: SeidelWavefrontCoefficients;\n  /** Required when any field-dependent Seidel coefficient is non-zero. */\n  seidelField?: SeidelFieldPosition;\n  /**\n   * Optional additional aperture mask: a simple polygon in pupil-plane mm (for example the\n   * cat's-eye pupil from calculateMechanicalVignetting). Samples outside it get zero amplitude.\n   */\n  apertureMaskVerticesMm?: readonly { x: number; y: number }[];\n}\n\nexport interface WavefrontPupilGrid {\n  /** Grid for LensComplexPupilProfile.grid. Amplitude is 1 inside and 0 outside; OPD is in micrometres. */\n  grid: LensComplexPupilGrid;\n  pupilDiameterMm: number;\n  /** Number of samples with non-zero amplitude. */\n  openSampleCount: number;\n  /** sqrt(sum c_j^2, j >= 2): RMS of the Zernike terms alone over the continuous unit disk. */\n  zernikeRmsMicrometers: number;\n  /** RMS of the sampled OPD over open samples, with piston removed (all terms). */\n  sampledRmsMicrometers: number;\n  /** Peak-to-valley of the sampled OPD over open samples. */\n  sampledPeakToValleyMicrometers: number;\n}\n\nexport interface CalculateDefocusWavefrontInput {\n  /** Signed image-plane defocus, sensor minus image distance, in micrometres. */\n  signedDefocusImagePlaneMicrometers: number;\n  /** Image-side working f-number (image distance / pupil diameter). */\n  workingFNumber: number;\n}\n\nexport interface DefocusWavefront {\n  signedDefocusImagePlaneMicrometers: number;\n  workingFNumber: number;\n  /** Peak defocus coefficient W020 = dz / (8 N^2), micrometres. */\n  w020Micrometers: number;\n  /** Equivalent Noll Z4 coefficient W020 / (2 sqrt 3), micrometres (equals the RMS). */\n  zernikeZ4Micrometers: number;\n}\n\nexport interface EstimateMarechalStrehlRatioInput {\n  rmsWavefrontErrorMicrometers: number;\n  wavelengthNm: number;\n}\n\nfunction requireFinite(name: string, value: unknown): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value)) {\n    throw new InvalidScientificInputError(`${name} must be finite.`);\n  }\n  return value;\n}\n\nfunction requireNollIndex(value: unknown): number {\n  if (\n    typeof value !== \"number\" ||\n    !Number.isSafeInteger(value) ||\n    value < 1 ||\n    value > ZERNIKE_MAXIMUM_NOLL_INDEX\n  ) {\n    throw new InvalidScientificInputError(\n      `nollIndex must be an integer from 1 through ${ZERNIKE_MAXIMUM_NOLL_INDEX}.`\n    );\n  }\n  return value;\n}\n\n/** Converts a Noll index to radial order n and signed azimuthal frequency m (Noll 1976). */\nexport function resolveZernikeNollOrder(nollIndex: number): ZernikeOrder {\n  const j = requireNollIndex(nollIndex);\n  let n = 0;\n  while (((n + 1) * (n + 2)) / 2 < j) {\n    n += 1;\n  }\n  // Position within radial order n; |m| increases with it, two indices per non-zero |m|.\n  const k = j - (n * (n + 1)) / 2 - 1;\n  const absoluteM =\n    n % 2 === 0 ? 2 * Math.floor((k + 1) / 2) : 2 * Math.floor(k / 2) + 1;\n  return {\n    nollIndex: j,\n    radialOrder: n,\n    azimuthalFrequency:\n      absoluteM === 0 ? 0 : j % 2 === 0 ? absoluteM : -absoluteM\n  };\n}\n\nfunction factorial(value: number): number {\n  let result = 1;\n  for (let k = 2; k <= value; k += 1) result *= k;\n  return result;\n}\n\nfunction radialPolynomial(n: number, m: number, rho: number): number {\n  let sum = 0;\n  for (let k = 0; k <= (n - m) / 2; k += 1) {\n    const coefficient =\n      ((k % 2 === 0 ? 1 : -1) * factorial(n - k)) /\n      (factorial(k) * factorial((n + m) / 2 - k) * factorial((n - m) / 2 - k));\n    sum += coefficient * rho ** (n - 2 * k);\n  }\n  return sum;\n}\n\n/** Evaluates the unit-RMS Noll Zernike polynomial at normalised pupil polar coordinates. */\nexport function evaluateZernikePolynomial(\n  nollIndex: number,\n  normalizedRadius: number,\n  azimuthRadians: number\n): number {\n  const order = resolveZernikeNollOrder(nollIndex);\n  const rho = requireFinite(\"normalizedRadius\", normalizedRadius);\n  const theta = requireFinite(\"azimuthRadians\", azimuthRadians);\n  if (rho < 0 || rho > 1 + 1e-12) {\n    throw new InvalidScientificInputError(\n      \"normalizedRadius must lie in [0, 1].\"\n    );\n  }\n  const n = order.radialOrder;\n  const m = Math.abs(order.azimuthalFrequency);\n  const radial = radialPolynomial(n, m, Math.min(1, rho));\n  if (m === 0) {\n    return Math.sqrt(n + 1) * radial;\n  }\n  const angular =\n    order.azimuthalFrequency > 0 ? Math.cos(m * theta) : Math.sin(m * theta);\n  return Math.sqrt(2 * (n + 1)) * radial * angular;\n}\n\nfunction parseZernike(\n  value: readonly ZernikeCoefficient[] | undefined\n): ZernikeCoefficient[] {\n  if (value === undefined) return [];\n  if (!Array.isArray(value)) {\n    throw new InvalidConfigurationError(\"zernikeCoefficients must be an array.\");\n  }\n  const seen = new Set<number>();\n  return value.map((entry, index) => {\n    if (typeof entry !== \"object\" || entry === null) {\n      throw new InvalidConfigurationError(`zernikeCoefficients[${index}] must be an object.`);\n    }\n    const nollIndex = requireNollIndex(entry.nollIndex);\n    if (seen.has(nollIndex)) {\n      throw new InvalidScientificInputError(\"zernikeCoefficients must not repeat a nollIndex.\");\n    }\n    seen.add(nollIndex);\n    return {\n      nollIndex,\n      coefficientMicrometers: requireFinite(\n        `zernikeCoefficients[${index}].coefficientMicrometers`,\n        entry.coefficientMicrometers\n      )\n    };\n  });\n}\n\nconst SEIDEL_KEYS = [\n  \"w020Micrometers\",\n  \"w111Micrometers\",\n  \"w040Micrometers\",\n  \"w131Micrometers\",\n  \"w222Micrometers\",\n  \"w220Micrometers\",\n  \"w311Micrometers\"\n] as const;\n\nfunction parseSeidel(\n  value: SeidelWavefrontCoefficients | undefined\n): Required<SeidelWavefrontCoefficients> {\n  const result = {\n    w020Micrometers: 0,\n    w111Micrometers: 0,\n    w040Micrometers: 0,\n    w131Micrometers: 0,\n    w222Micrometers: 0,\n    w220Micrometers: 0,\n    w311Micrometers: 0\n  };\n  if (value === undefined) return result;\n  if (typeof value !== \"object\" || value === null) {\n    throw new InvalidConfigurationError(\"seidelCoefficients must be an object.\");\n  }\n  for (const key of Object.keys(value)) {\n    if (!(SEIDEL_KEYS as readonly string[]).includes(key)) {\n      throw new InvalidConfigurationError(`seidelCoefficients.${key} is not supported.`);\n    }\n  }\n  for (const key of SEIDEL_KEYS) {\n    if (value[key] !== undefined) {\n      result[key] = requireFinite(`seidelCoefficients.${key}`, value[key]);\n    }\n  }\n  return result;\n}\n\nfunction pointInPolygon(\n  x: number,\n  y: number,\n  vertices: readonly { x: number; y: number }[]\n): boolean {\n  let inside = false;\n  for (let i = 0, j = vertices.length - 1; i < vertices.length; j = i, i += 1) {\n    const a = vertices[i]!;\n    const b = vertices[j]!;\n    if (\n      a.y > y !== b.y > y &&\n      x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x\n    ) {\n      inside = !inside;\n    }\n  }\n  return inside;\n}\n\nfunction parseMask(\n  value: readonly { x: number; y: number }[] | undefined\n): readonly { x: number; y: number }[] | undefined {\n  if (value === undefined) return undefined;\n  if (!Array.isArray(value) || value.length < 3 || value.length > 4096) {\n    throw new InvalidScientificInputError(\n      \"apertureMaskVerticesMm must contain 3 through 4096 vertices.\"\n    );\n  }\n  return value.map((vertex, index) => {\n    if (typeof vertex !== \"object\" || vertex === null) {\n      throw new InvalidConfigurationError(`apertureMaskVerticesMm[${index}] must be an object.`);\n    }\n    return {\n      x: requireFinite(`apertureMaskVerticesMm[${index}].x`, vertex.x),\n      y: requireFinite(`apertureMaskVerticesMm[${index}].y`, vertex.y)\n    };\n  });\n}\n\n/**\n * Builds a complex-pupil grid: a circular pupil, an optional polygon mask, and an OPD from Zernike\n * coefficients, Seidel coefficients or both. If every coefficient is zero, the OPD is exactly zero,\n * so the PSF equals the existing aberration-free circular-pupil reference.\n */\nexport function createWavefrontPupilGrid(\n  input: CreateWavefrontPupilGridInput\n): CalculationResult<WavefrontPupilGrid> {\n  requireInputKeys(input, \"createWavefrontPupilGrid\", [\"pupilDiameterMm\", \"samplesAcross\", \"zernikeCoefficients\", \"seidelCoefficients\", \"seidelField\", \"apertureMaskVerticesMm\"]);\n  requirePositiveFinite(\"pupilDiameterMm\", input.pupilDiameterMm);\n  const n = input.samplesAcross;\n  if (\n    !Number.isSafeInteger(n) ||\n    n < 3 ||\n    n > ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS ||\n    n % 2 === 0\n  ) {\n    throw new InvalidScientificInputError(\n      `samplesAcross must be an odd integer from 3 through ${ZERNIKE_PUPIL_MAXIMUM_SAMPLES_ACROSS}.`\n    );\n  }\n  const zernike = parseZernike(input.zernikeCoefficients);\n  const seidel = parseSeidel(input.seidelCoefficients);\n  const mask = parseMask(input.apertureMaskVerticesMm);\n  const fieldDependent =\n    seidel.w111Micrometers !== 0 ||\n    seidel.w131Micrometers !== 0 ||\n    seidel.w222Micrometers !== 0 ||\n    seidel.w220Micrometers !== 0 ||\n    seidel.w311Micrometers !== 0;\n  let fieldHeight = 0;\n  let fieldAzimuth = 0;\n  if (input.seidelField !== undefined) {\n    if (typeof input.seidelField !== \"object\" || input.seidelField === null) {\n      throw new InvalidConfigurationError(\"seidelField must be an object.\");\n    }\n    fieldHeight = requireFinite(\n      \"seidelField.normalizedFieldHeight\",\n      input.seidelField.normalizedFieldHeight\n    );\n    if (fieldHeight < 0 || fieldHeight > 1) {\n      throw new InvalidScientificInputError(\n        \"seidelField.normalizedFieldHeight must lie in [0, 1].\"\n      );\n    }\n    fieldAzimuth =\n      (requireFinite(\"seidelField.fieldAzimuthDegrees\", input.seidelField.fieldAzimuthDegrees) *\n        Math.PI) /\n      180;\n  } else if (fieldDependent) {\n    throw new InvalidScientificInputError(\n      \"seidelField is required when a field-dependent Seidel coefficient is non-zero.\"\n    );\n  }\n\n  const radiusMm = input.pupilDiameterMm / 2;\n  const pitch = input.pupilDiameterMm / (n - 1);\n  const center = (n - 1) / 2;\n  const amplitude: number[] = [];\n  const opd: number[] = [];\n  const open: number[] = [];\n  for (let row = 0; row < n; row += 1) {\n    for (let column = 0; column < n; column += 1) {\n      const xMm = (column - center) * pitch;\n      const yMm = (row - center) * pitch;\n      const rho = Math.hypot(xMm, yMm) / radiusMm;\n      const inside =\n        rho <= 1 + 1e-12 && (mask === undefined || pointInPolygon(xMm, yMm, mask));\n      if (!inside) {\n        amplitude.push(0);\n        opd.push(0);\n        continue;\n      }\n      const r = Math.min(1, rho);\n      const theta = Math.atan2(yMm, xMm);\n      let w = 0;\n      for (const term of zernike) {\n        if (term.coefficientMicrometers !== 0) {\n          w += term.coefficientMicrometers * evaluateZernikePolynomial(term.nollIndex, r, theta);\n        }\n      }\n      const cosPhi = Math.cos(theta - fieldAzimuth);\n      const r2 = r * r;\n      w +=\n        seidel.w020Micrometers * r2 +\n        seidel.w040Micrometers * r2 * r2 +\n        seidel.w111Micrometers * fieldHeight * r * cosPhi +\n        seidel.w131Micrometers * fieldHeight * r2 * r * cosPhi +\n        seidel.w222Micrometers * fieldHeight * fieldHeight * r2 * cosPhi * cosPhi +\n        seidel.w220Micrometers * fieldHeight * fieldHeight * r2 +\n        seidel.w311Micrometers * fieldHeight ** 3 * r * cosPhi;\n      amplitude.push(1);\n      opd.push(w);\n      open.push(w);\n    }\n  }\n  if (open.length === 0) {\n    throw new InvalidScientificInputError(\n      \"The aperture mask leaves no open pupil samples.\"\n    );\n  }\n  const mean = open.reduce((sum, value) => sum + value, 0) / open.length;\n  const variance =\n    open.reduce((sum, value) => sum + (value - mean) ** 2, 0) / open.length;\n  const zernikeRms = Math.sqrt(\n    zernike\n      .filter((term) => term.nollIndex >= 2)\n      .reduce((sum, term) => sum + term.coefficientMicrometers ** 2, 0)\n  );\n\n  return approximationResult(\n    {\n      grid: {\n        widthSamples: n,\n        heightSamples: n,\n        pupilSamplePitchMmX: pitch,\n        pupilSamplePitchMmY: pitch,\n        centerSampleX: center,\n        centerSampleY: center,\n        relativeAmplitude: amplitude,\n        opticalPathDifferenceMicrometers: opd\n      },\n      pupilDiameterMm: input.pupilDiameterMm,\n      openSampleCount: open.length,\n      zernikeRmsMicrometers: zernikeRms,\n      sampledRmsMicrometers: Math.sqrt(variance),\n      sampledPeakToValleyMicrometers: Math.max(...open) - Math.min(...open)\n    },\n    \"zernike-seidel-wavefront-pupil-grid\",\n    \"1.0.0\",\n    [\n      \"Uniform unit amplitude inside the circular pupil (and inside the optional polygon mask); zero outside\",\n      \"Noll-indexed, unit-RMS Zernike polynomials over the unit disk; Seidel terms are peak wave-aberration coefficients\",\n      \"Pupil coordinates are metric and aligned with the image plane (+X right, +Y up)\",\n      \"Sampled RMS differs slightly from the continuous Zernike RMS because the disk is represented by discrete samples\",\n      \"Coefficients are caller inputs; no named-lens calibration is implied\"\n    ]\n  );\n}\n\n/**\n * Converts a signed paraxial image-plane defocus into the defocus wave aberration\n * W020 = dz / (8 N^2) and its Noll Z4 coefficient W020 / (2 sqrt 3).\n *\n * Sign convention: dz = sensor distance minus image distance. Positive W020 means the image lies in\n * front of the sensor. With pure defocus, the PSF intensity does not depend on the sign.\n */\nexport function calculateDefocusWavefront(\n  input: CalculateDefocusWavefrontInput\n): CalculationResult<DefocusWavefront> {\n  requireInputKeys(input, \"calculateDefocusWavefront\", [\"signedDefocusImagePlaneMicrometers\", \"workingFNumber\"]);\n  const dz = requireFinite(\n    \"signedDefocusImagePlaneMicrometers\",\n    input.signedDefocusImagePlaneMicrometers\n  );\n  requirePositiveFinite(\"workingFNumber\", input.workingFNumber);\n  const w020 = dz / (8 * input.workingFNumber * input.workingFNumber);\n  return calculatedResult(\n    {\n      signedDefocusImagePlaneMicrometers: dz,\n      workingFNumber: input.workingFNumber,\n      w020Micrometers: w020,\n      zernikeZ4Micrometers: w020 / (2 * Math.sqrt(3))\n    },\n    \"paraxial-defocus-wavefront\",\n    \"1.0.0\",\n    [\n      \"Paraxial (small-angle) relation between longitudinal image-plane defocus and the rho^2 wave aberration\",\n      \"Sign convention: defocus is sensor minus image distance\"\n    ]\n  );\n}\n\n/**\n * Marechal/Mahajan approximation of the Strehl ratio: exp(-(2 pi sigma / lambda)^2). Valid only for a\n * small RMS wavefront error (Strehl roughly above 0.3). It is not an exact PSF calculation.\n */\nexport function estimateMarechalStrehlRatio(\n  input: EstimateMarechalStrehlRatioInput\n): CalculationResult<{ strehlRatio: number; rmsWaves: number }> {\n  requireInputKeys(input, \"estimateMarechalStrehlRatio\", [\"rmsWavefrontErrorMicrometers\", \"wavelengthNm\"]);\n  const sigma = requireFinite(\n    \"rmsWavefrontErrorMicrometers\",\n    input.rmsWavefrontErrorMicrometers\n  );\n  if (sigma < 0) {\n    throw new InvalidScientificInputError(\n      \"rmsWavefrontErrorMicrometers must be non-negative.\"\n    );\n  }\n  requirePositiveFinite(\"wavelengthNm\", input.wavelengthNm);\n  const rmsWaves = sigma / (input.wavelengthNm / 1000);\n  return approximationResult(\n    {\n      strehlRatio: Math.exp(-((2 * Math.PI * rmsWaves) ** 2)),\n      rmsWaves\n    },\n    \"marechal-mahajan-strehl-approximation\",\n    \"1.0.0\",\n    [\n      \"Strehl ratio approximated as exp(-(2 pi sigma / lambda)^2) (Marechal 1947; Mahajan 1982)\",\n      \"Valid for small RMS wavefront error, roughly Strehl above 0.3; it is not an exact PSF evaluation\"\n    ]\n  );\n}\n"]}

package/dist/output/capture-corrected-sdr.d.ts

@@ -6,12 +6,15 @@ import { calculateLensCorrectedCapture, type GenericLensCorrectionProfile, type
 import { type GeometricResampler } from "./geometric-transforms.js";
 import { type RasterRect } from "./capture-geometry.js";
 export declare const CAPTURE_CORRECTED_SDR_SCHEMA_VERSION: "0.1.0";
-/** 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.
+ */
 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"];
@@ -23,14 +26,14 @@ export interface CaptureCorrectedSdrInput extends CaptureSdrInput {
         outputImageStateId: string;
     };
 }
-/** 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. */
 export interface CaptureCorrectedSdrResult extends Omit<CaptureSdrResult, "schemaVersion"> {
     schemaVersion: typeof CAPTURE_CORRECTED_SDR_SCHEMA_VERSION;
     sceneTimeSeconds: number;
     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;
@@ -40,10 +43,15 @@ export interface CaptureCorrectedSdrResult extends Omit<CaptureSdrResult, "schem
         samples: readonly number[];
     };
 }
-/** 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.
+ */
 export declare function parseCaptureCorrectedSdrInput(input: unknown): CaptureCorrectedSdrInput;
-/** Internal shared validation for capture-derived exporters; does not create or validate pixel values. */
+/** Internal: validates the correction choice for exporters that start from a capture. It neither creates nor checks pixel values. */
 export declare function parseCaptureCorrectionChoice(input: unknown, capture: CaptureSdrInput["capture"], forbiddenImageStateIds?: readonly string[]): CaptureCorrectedSdrInput["correction"];
-/** 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.
+ */
 export declare function calculateCaptureCorrectedSdr(input: CaptureCorrectedSdrInput): CalculationResult<CaptureCorrectedSdrResult>;
-//# sourceMappingURL=capture-corrected-sdr.d.ts.map