@photivra/engine 0.1.0 → 0.4.0

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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"}

package/dist/optics/radial-distortion.d.ts

@@ -0,0 +1,91 @@
+import { type CalculationResult } from "../core/calculation-result.js";
+export interface RadialDistortionCoefficients {
+    /** Dimensionless r² coefficient. */
+    k1: number;
+    /** Dimensionless r⁴ coefficient. */
+    k2: number;
+    /** Dimensionless r⁶ coefficient. */
+    k3: number;
+}
+export interface RadialDistortionProfile {
+    /**
+     * Physical image-plane radius used to normalize field position, in mm.
+     * Coefficients are meaningful only with this declared normalization.
+     */
+    normalizationRadiusMm: number;
+    /**
+     * Maximum undistorted normalized radius over which this profile is declared
+     * valid and must remain one-to-one/invertible.
+     */
+    maximumNormalizedRadius: number;
+    coefficients: RadialDistortionCoefficients;
+}
+export interface LensFieldPointMm {
+    /** Image-plane X coordinate relative to the optical axis, in mm. */
+    x: number;
+    /** Image-plane Y coordinate relative to the optical axis, in mm. */
+    y: number;
+}
+export interface CalculateRadialDistortionMappingInput {
+    /** Ideal/undistorted image-plane point. */
+    imagePointMm: LensFieldPointMm;
+    profile: RadialDistortionProfile;
+}
+export interface CalculateInverseRadialDistortionMappingInput {
+    /** Distorted image-plane point to inverse-map back to ideal coordinates. */
+    distortedImagePointMm: LensFieldPointMm;
+    profile: RadialDistortionProfile;
+}
+export interface RadialDistortionMapping {
+    direction: "undistorted-to-distorted";
+    sourceImagePointMm: LensFieldPointMm;
+    mappedImagePointMm: LensFieldPointMm;
+    sourceNormalizedRadius: number;
+    mappedNormalizedRadius: number;
+    radialScale: number;
+    deltaMm: {
+        x: number;
+        y: number;
+        distance: number;
+    };
+    profileMinimumRadialDerivative: number;
+}
+export interface InverseRadialDistortionMapping {
+    direction: "distorted-to-undistorted";
+    distortedImagePointMm: LensFieldPointMm;
+    sourceImagePointMm: LensFieldPointMm;
+    distortedNormalizedRadius: number;
+    sourceNormalizedRadius: number;
+    radialScaleAtSource: number;
+    deltaMm: {
+        x: number;
+        y: number;
+        distance: number;
+    };
+    profileMinimumRadialDerivative: number;
+}
+/**
+ * Applies a generic radial lens-distortion field mapping to one ideal
+ * image-plane point.
+ *
+ * The mapping is rotationally symmetric about the optical axis:
+ *
+ *   p_distorted = p_ideal * (1 + k1 r² + k2 r⁴ + k3 r⁶)
+ *
+ * where r is normalized by the caller-declared physical reference radius.
+ *
+ * The profile is accepted only when the radial mapping is strictly monotonic
+ * over its declared operating radius, which makes inverse destination-to-source
+ * sampling well-defined.
+ */
+export declare function calculateRadialDistortionMapping(input: CalculateRadialDistortionMappingInput): CalculationResult<RadialDistortionMapping>;
+/**
+ * Inverse-maps one distorted image-plane point to its ideal/undistorted source
+ * coordinate for destination-to-source renderer sampling.
+ *
+ * The same profile monotonicity requirement used by the forward mapping makes
+ * the inverse unique over the declared operating radius. A deterministic fixed
+ * bisection count is used rather than an unconstrained iterative solver.
+ */
+export declare function calculateInverseRadialDistortionMapping(input: CalculateInverseRadialDistortionMappingInput): CalculationResult<InverseRadialDistortionMapping>;
+//# sourceMappingURL=radial-distortion.d.ts.map

package/dist/optics/radial-distortion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"radial-distortion.d.ts","sourceRoot":"","sources":["../../src/optics/radial-distortion.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAMvC,MAAM,WAAW,4BAA4B;IAC3C,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,oCAAoC;IACpC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,uBAAuB,EAAE,MAAM,CAAC;IAChC,YAAY,EAAE,4BAA4B,CAAC;CAC5C;AAED,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,CAAC,EAAE,MAAM,CAAC;IACV,oEAAoE;IACpE,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,qCAAqC;IACpD,2CAA2C;IAC3C,YAAY,EAAE,gBAAgB,CAAC;IAC/B,OAAO,EAAE,uBAAuB,CAAC;CAClC;AAED,MAAM,WAAW,4CAA4C;IAC3D,4EAA4E;IAC5E,qBAAqB,EAAE,gBAAgB,CAAC;IACxC,OAAO,EAAE,uBAAuB,CAAC;CAClC;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,0BAA0B,CAAC;IACtC,kBAAkB,EAAE,gBAAgB,CAAC;IACrC,kBAAkB,EAAE,gBAAgB,CAAC;IACrC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE;QACP,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,8BAA8B,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,0BAA0B,CAAC;IACtC,qBAAqB,EAAE,gBAAgB,CAAC;IACxC,kBAAkB,EAAE,gBAAgB,CAAC;IACrC,yBAAyB,EAAE,MAAM,CAAC;IAClC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE;QACP,CAAC,EAAE,MAAM,CAAC;QACV,CAAC,EAAE,MAAM,CAAC;QACV,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,8BAA8B,EAAE,MAAM,CAAC;CACxC;AA2JD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qCAAqC,GAC3C,iBAAiB,CAAC,uBAAuB,CAAC,CAiD5C;AAED;;;;;;;GAOG;AACH,wBAAgB,uCAAuC,CACrD,KAAK,EAAE,4CAA4C,GAClD,iBAAiB,CAAC,8BAA8B,CAAC,CAiFnD"}

package/dist/optics/radial-distortion.js

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: Apache-2.0
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
+const INVERSE_BISECTION_ITERATIONS = 80;
+function requireFinite(name, value) {
+    if (!Number.isFinite(value)) {
+        throw new InvalidScientificInputError(`${name} must be finite.`);
+    }
+}
+function radialScale(normalizedRadius, coefficients) {
+    const r2 = normalizedRadius * normalizedRadius;
+    const r4 = r2 * r2;
+    const r6 = r4 * r2;
+    return (1 +
+        coefficients.k1 * r2 +
+        coefficients.k2 * r4 +
+        coefficients.k3 * r6);
+}
+function mappedNormalizedRadius(normalizedRadius, coefficients) {
+    return normalizedRadius * radialScale(normalizedRadius, coefficients);
+}
+function radialDerivativeFromSquaredRadius(squaredRadius, coefficients) {
+    return (1 +
+        3 * coefficients.k1 * squaredRadius +
+        5 * coefficients.k2 * squaredRadius * squaredRadius +
+        7 *
+            coefficients.k3 *
+            squaredRadius *
+            squaredRadius *
+            squaredRadius);
+}
+function derivativeCriticalSquaredRadii(coefficients) {
+    // d/dr² of the radial derivative:
+    // 3 k1 + 10 k2 s + 21 k3 s² = 0, where s = r².
+    const a = 21 * coefficients.k3;
+    const b = 10 * coefficients.k2;
+    const c = 3 * coefficients.k1;
+    if (a === 0) {
+        return b === 0 ? [] : [-c / b];
+    }
+    const discriminant = b * b - 4 * a * c;
+    if (discriminant < 0) {
+        return [];
+    }
+    const root = Math.sqrt(discriminant);
+    return [(-b - root) / (2 * a), (-b + root) / (2 * a)];
+}
+function validateProfile(profile) {
+    requirePositiveFinite("profile.normalizationRadiusMm", profile.normalizationRadiusMm);
+    requirePositiveFinite("profile.maximumNormalizedRadius", profile.maximumNormalizedRadius);
+    requireFinite("profile.coefficients.k1", profile.coefficients.k1);
+    requireFinite("profile.coefficients.k2", profile.coefficients.k2);
+    requireFinite("profile.coefficients.k3", profile.coefficients.k3);
+    const maximumSquaredRadius = profile.maximumNormalizedRadius * profile.maximumNormalizedRadius;
+    const candidates = [
+        0,
+        maximumSquaredRadius,
+        ...derivativeCriticalSquaredRadii(profile.coefficients).filter((value) => value > 0 && value < maximumSquaredRadius)
+    ];
+    const minimumRadialDerivative = Math.min(...candidates.map((squaredRadius) => radialDerivativeFromSquaredRadius(squaredRadius, profile.coefficients)));
+    if (!Number.isFinite(minimumRadialDerivative) ||
+        minimumRadialDerivative <= 0) {
+        throw new InvalidScientificInputError("Radial distortion profile must remain strictly monotonic over maximumNormalizedRadius so inverse mapping is single-valued.");
+    }
+    const maximumMappedRadius = mappedNormalizedRadius(profile.maximumNormalizedRadius, profile.coefficients);
+    if (!Number.isFinite(maximumMappedRadius) || maximumMappedRadius <= 0) {
+        throw new InvalidScientificInputError("Radial distortion profile produces an invalid mapped operating radius.");
+    }
+    return {
+        normalizationRadiusMm: profile.normalizationRadiusMm,
+        maximumNormalizedRadius: profile.maximumNormalizedRadius,
+        coefficients: { ...profile.coefficients },
+        minimumRadialDerivative,
+        maximumMappedNormalizedRadius: maximumMappedRadius
+    };
+}
+function requirePoint(name, point) {
+    requireFinite(`${name}.x`, point.x);
+    requireFinite(`${name}.y`, point.y);
+}
+function mappingAssumptions() {
+    return [
+        "Generic rotationally symmetric radial polynomial field mapping",
+        "Distortion is centered on the optical axis; decentering and tangential distortion are not modeled",
+        "Normalized radius is image-plane radius divided by the caller-declared normalizationRadiusMm",
+        "Radial scale is 1 + k1 r^2 + k2 r^4 + k3 r^6",
+        "The declared operating radius is required to remain strictly monotonic so inverse mapping is single-valued",
+        "Coefficients are generic caller inputs and do not represent a named lens unless separately calibrated with defensible provenance"
+    ];
+}
+/**
+ * Applies a generic radial lens-distortion field mapping to one ideal
+ * image-plane point.
+ *
+ * The mapping is rotationally symmetric about the optical axis:
+ *
+ *   p_distorted = p_ideal * (1 + k1 r² + k2 r⁴ + k3 r⁶)
+ *
+ * where r is normalized by the caller-declared physical reference radius.
+ *
+ * The profile is accepted only when the radial mapping is strictly monotonic
+ * over its declared operating radius, which makes inverse destination-to-source
+ * sampling well-defined.
+ */
+export function calculateRadialDistortionMapping(input) {
+    requirePoint("imagePointMm", input.imagePointMm);
+    const profile = validateProfile(input.profile);
+    const sourceRadiusMm = Math.hypot(input.imagePointMm.x, input.imagePointMm.y);
+    const sourceNormalizedRadius = sourceRadiusMm / profile.normalizationRadiusMm;
+    if (sourceNormalizedRadius > profile.maximumNormalizedRadius) {
+        throw new InvalidScientificInputError("imagePointMm lies outside the radial distortion profile maximumNormalizedRadius.");
+    }
+    const scale = radialScale(sourceNormalizedRadius, profile.coefficients);
+    const mappedImagePointMm = {
+        x: input.imagePointMm.x * scale,
+        y: input.imagePointMm.y * scale
+    };
+    const mappedRadius = sourceNormalizedRadius * scale;
+    const deltaX = mappedImagePointMm.x - input.imagePointMm.x;
+    const deltaY = mappedImagePointMm.y - input.imagePointMm.y;
+    return approximationResult({
+        direction: "undistorted-to-distorted",
+        sourceImagePointMm: { ...input.imagePointMm },
+        mappedImagePointMm,
+        sourceNormalizedRadius,
+        mappedNormalizedRadius: mappedRadius,
+        radialScale: scale,
+        deltaMm: {
+            x: deltaX,
+            y: deltaY,
+            distance: Math.hypot(deltaX, deltaY)
+        },
+        profileMinimumRadialDerivative: profile.minimumRadialDerivative
+    }, "generic-radial-lens-distortion", "1.0.0", mappingAssumptions());
+}
+/**
+ * Inverse-maps one distorted image-plane point to its ideal/undistorted source
+ * coordinate for destination-to-source renderer sampling.
+ *
+ * The same profile monotonicity requirement used by the forward mapping makes
+ * the inverse unique over the declared operating radius. A deterministic fixed
+ * bisection count is used rather than an unconstrained iterative solver.
+ */
+export function calculateInverseRadialDistortionMapping(input) {
+    requirePoint("distortedImagePointMm", input.distortedImagePointMm);
+    const profile = validateProfile(input.profile);
+    const distortedRadiusMm = Math.hypot(input.distortedImagePointMm.x, input.distortedImagePointMm.y);
+    const distortedNormalizedRadius = distortedRadiusMm / profile.normalizationRadiusMm;
+    if (distortedNormalizedRadius >
+        profile.maximumMappedNormalizedRadius) {
+        throw new InvalidScientificInputError("distortedImagePointMm lies outside the mapped radial distortion profile operating radius.");
+    }
+    let sourceNormalizedRadius = 0;
+    if (distortedNormalizedRadius > 0) {
+        let lower = 0;
+        let upper = profile.maximumNormalizedRadius;
+        for (let iteration = 0; iteration < INVERSE_BISECTION_ITERATIONS; iteration += 1) {
+            const midpoint = (lower + upper) / 2;
+            const mapped = mappedNormalizedRadius(midpoint, profile.coefficients);
+            if (mapped < distortedNormalizedRadius) {
+                lower = midpoint;
+            }
+            else {
+                upper = midpoint;
+            }
+        }
+        sourceNormalizedRadius = (lower + upper) / 2;
+    }
+    const scaleAtSource = radialScale(sourceNormalizedRadius, profile.coefficients);
+    const sourceImagePointMm = distortedNormalizedRadius === 0
+        ? { x: 0, y: 0 }
+        : {
+            x: input.distortedImagePointMm.x / scaleAtSource,
+            y: input.distortedImagePointMm.y / scaleAtSource
+        };
+    const deltaX = sourceImagePointMm.x - input.distortedImagePointMm.x;
+    const deltaY = sourceImagePointMm.y - input.distortedImagePointMm.y;
+    return approximationResult({
+        direction: "distorted-to-undistorted",
+        distortedImagePointMm: {
+            ...input.distortedImagePointMm
+        },
+        sourceImagePointMm,
+        distortedNormalizedRadius,
+        sourceNormalizedRadius,
+        radialScaleAtSource: scaleAtSource,
+        deltaMm: {
+            x: deltaX,
+            y: deltaY,
+            distance: Math.hypot(deltaX, deltaY)
+        },
+        profileMinimumRadialDerivative: profile.minimumRadialDerivative
+    }, "generic-inverse-radial-lens-distortion", "1.0.0", [
+        ...mappingAssumptions(),
+        `Inverse radius is solved with ${INVERSE_BISECTION_ITERATIONS} deterministic bisection iterations`
+    ]);
+}
+//# sourceMappingURL=radial-distortion.js.map

package/dist/optics/radial-distortion.js.map

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