@photivra/engine 1.5.0 → 2.1.0

package/dist/optics/brown-conrady-distortion.js

@@ -0,0 +1,291 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Generic Brown-Conrady lens distortion: radial (k1, k2, k3) plus tangential/decentering (p1, p2)
+ * terms on normalized image-plane coordinates (x, y) = point / normalizationRadiusMm, r^2 = x^2 + y^2:
+ *   x_d = x (1 + k1 r^2 + k2 r^4 + k3 r^6) + 2 p1 x y + p2 (r^2 + 2 x^2)
+ *   y_d = y (1 + k1 r^2 + k2 r^4 + k3 r^6) + p1 (r^2 + 2 y^2) + 2 p2 x y
+ * In vector form the tangential term is r^2 P + 2 (P . u) u with P = (p2, p1), so (p1, p2) rotate as
+ * a vector with the image.
+ *
+ * Sources: Conrady 1919 (MNRAS 79:384, decentred lens systems); Brown 1966
+ * (Photogrammetric Engineering 32:444, "Decentering distortion of lenses"); Brown 1971 (Photogramm.
+ * Eng. 37:855, close-range camera calibration). The coefficient layout follows the widely used
+ * Brown-Conrady convention (for example Heikkila & Silven 1997, CVPR). The coefficient names match
+ * that convention, but the values only mean something together with the declared normalization
+ * radius.
+ *
+ * Validity checks (matching the radial-distortion validator):
+ * - The radial part must be strictly monotonic over the envelope (the valid radius range).
+ * - The Jacobian determinant must stay positive at a dense, fixed polar grid of samples over the
+ *   envelope disk.
+ * - The mapped envelope boundary must have strictly increasing polar angle, so it is a simple
+ *   star-shaped curve.
+ * A smooth, locally invertible map of a closed disk that is one-to-one on its boundary is one-to-one
+ * everywhere. So these conditions make the inverse single-valued. Note that the Jacobian and boundary
+ * conditions are checked at samples, not proven between them.
+ *
+ * The inverse uses damped Newton iteration, starting from the radial-only inverse.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { calculateInverseRadialSourcePointValue, validateRadialDistortionProfile } from "./radial-distortion.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+const VALIDATION_RINGS = 64;
+const VALIDATION_AZIMUTHS = 256;
+const MAXIMUM_NEWTON_ITERATIONS = 100;
+function requireFinite(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new InvalidScientificInputError(`${name} must be finite.`);
+    }
+    return value;
+}
+function requirePoint(name, point) {
+    if (typeof point !== "object" || point === null) {
+        throw new InvalidConfigurationError(`${name} must be an object with finite numeric x and y coordinates.`);
+    }
+    const record = point;
+    return {
+        x: requireFinite(`${name}.x`, record.x),
+        y: requireFinite(`${name}.y`, record.y)
+    };
+}
+/** Forward map on normalized coordinates. */
+function forwardNormalized(x, y, c) {
+    const r2 = x * x + y * y;
+    const radial = 1 + r2 * (c.k1 + r2 * (c.k2 + r2 * c.k3));
+    return {
+        x: x * radial + 2 * c.p1 * x * y + c.p2 * (r2 + 2 * x * x),
+        y: y * radial + c.p1 * (r2 + 2 * y * y) + 2 * c.p2 * x * y
+    };
+}
+/** Jacobian [[a, b], [c, d]] of the normalized forward map. */
+function jacobianNormalized(x, y, c) {
+    const r2 = x * x + y * y;
+    const s = 1 + r2 * (c.k1 + r2 * (c.k2 + r2 * c.k3));
+    const ds = c.k1 + r2 * (2 * c.k2 + 3 * c.k3 * r2);
+    const off = 2 * x * y * ds + 2 * c.p1 * x + 2 * c.p2 * y;
+    return {
+        a: s + 2 * x * x * ds + 2 * c.p1 * y + 6 * c.p2 * x,
+        b: off,
+        c: off,
+        d: s + 2 * y * y * ds + 6 * c.p1 * y + 2 * c.p2 * x
+    };
+}
+function determinant(j) {
+    return j.a * j.d - j.b * j.c;
+}
+function validateProfile(profile) {
+    if (typeof profile !== "object" || profile === null) {
+        throw new InvalidConfigurationError("profile must be an object.");
+    }
+    if (typeof profile.coefficients !== "object" || profile.coefficients === null) {
+        throw new InvalidConfigurationError("profile.coefficients must be an object.");
+    }
+    const coefficients = {
+        k1: requireFinite("profile.coefficients.k1", profile.coefficients.k1),
+        k2: requireFinite("profile.coefficients.k2", profile.coefficients.k2),
+        k3: requireFinite("profile.coefficients.k3", profile.coefficients.k3),
+        p1: requireFinite("profile.coefficients.p1", profile.coefficients.p1),
+        p2: requireFinite("profile.coefficients.p2", profile.coefficients.p2)
+    };
+    const radial = validateRadialDistortionProfile({
+        normalizationRadiusMm: profile.normalizationRadiusMm,
+        maximumNormalizedRadius: profile.maximumNormalizedRadius,
+        coefficients: {
+            k1: coefficients.k1,
+            k2: coefficients.k2,
+            k3: coefficients.k3
+        }
+    });
+    const maximum = radial.maximumNormalizedRadius;
+    let minimumJacobianDeterminant = Number.POSITIVE_INFINITY;
+    for (let ring = 0; ring <= VALIDATION_RINGS; ring += 1) {
+        const rho = (maximum * ring) / VALIDATION_RINGS;
+        const azimuths = ring === 0 ? 1 : VALIDATION_AZIMUTHS;
+        for (let index = 0; index < azimuths; index += 1) {
+            const phi = (2 * Math.PI * index) / VALIDATION_AZIMUTHS;
+            const det = determinant(jacobianNormalized(rho * Math.cos(phi), rho * Math.sin(phi), coefficients));
+            minimumJacobianDeterminant = Math.min(minimumJacobianDeterminant, det);
+        }
+    }
+    if (!Number.isFinite(minimumJacobianDeterminant) || minimumJacobianDeterminant <= 0) {
+        throw new InvalidScientificInputError("Brown-Conrady profile must keep a positive Jacobian determinant over maximumNormalizedRadius so the mapping stays locally invertible.");
+    }
+    // The mapped boundary must be star-shaped about the mapped centre (the origin): its polar angle
+    // must increase strictly around the circle, so the boundary curve is simple.
+    let previous;
+    let accumulated = 0;
+    for (let index = 0; index <= VALIDATION_AZIMUTHS; index += 1) {
+        const phi = (2 * Math.PI * index) / VALIDATION_AZIMUTHS;
+        const mapped = forwardNormalized(maximum * Math.cos(phi), maximum * Math.sin(phi), coefficients);
+        const angle = Math.atan2(mapped.y, mapped.x);
+        if (previous !== undefined) {
+            let step = angle - previous;
+            if (step <= -Math.PI)
+                step += 2 * Math.PI;
+            if (step > Math.PI)
+                step -= 2 * Math.PI;
+            if (!(step > 0)) {
+                throw new InvalidScientificInputError("Brown-Conrady profile maps the envelope boundary to a curve that is not star-shaped about the optical axis; the inverse would not be single-valued.");
+            }
+            accumulated += step;
+        }
+        previous = angle;
+    }
+    if (Math.abs(accumulated - 2 * Math.PI) > 1e-9) {
+        throw new InvalidScientificInputError("Brown-Conrady profile boundary must wind exactly once around the optical axis.");
+    }
+    return { radial, coefficients, minimumJacobianDeterminant };
+}
+function assumptions() {
+    return [
+        "Generic Brown-Conrady radial (k1, k2, k3) plus tangential/decentering (p1, p2) polynomial field mapping",
+        "Coordinates are normalized by the caller-declared normalizationRadiusMm; the optical axis maps to itself",
+        "Validity: monotonic radial part, positive Jacobian at a 64-ring x 256-azimuth polar sample and a strictly star-shaped mapped boundary; checked at samples, not proven between them",
+        "Coefficients are generic caller inputs and do not represent a named lens unless separately calibrated with defensible provenance",
+        "Thin-prism, anamorphic and higher-order decentering terms are not modeled"
+    ];
+}
+/** @internal Validates one profile for repeated evaluation (geometric mapping, ray queries). */
+export function validateBrownConradyDistortionProfile(profile) {
+    return validateProfile(profile);
+}
+/** @internal Forward map in mm with its Jacobian d(distorted)/d(ideal), row-major. */
+export function brownConradyForwardValue(profile, point) {
+    const scale = profile.radial.normalizationRadiusMm;
+    const x = point.x / scale;
+    const y = point.y / scale;
+    if (Math.hypot(x, y) > profile.radial.maximumNormalizedRadius) {
+        throw new InvalidScientificInputError("Point lies outside the Brown-Conrady profile maximumNormalizedRadius.");
+    }
+    const mapped = forwardNormalized(x, y, profile.coefficients);
+    const j = jacobianNormalized(x, y, profile.coefficients);
+    return {
+        mappedImagePointMm: { x: mapped.x * scale, y: mapped.y * scale },
+        jacobian: [j.a, j.b, j.c, j.d]
+    };
+}
+/** @internal Inverse map in mm (distorted to ideal). */
+export function brownConradyInverseValue(profile, point) {
+    const solved = solveInverseBrownConrady(profile, point);
+    const scale = profile.radial.normalizationRadiusMm;
+    return { x: solved.x * scale, y: solved.y * scale };
+}
+function solveInverseBrownConrady(profile, point) {
+    const scale = profile.radial.normalizationRadiusMm;
+    const maximum = profile.radial.maximumNormalizedRadius;
+    const tx = point.x / scale;
+    const ty = point.y / scale;
+    const tolerance = 1e-12 * Math.max(1, Math.hypot(tx, ty));
+    // Starting point: the radial-only inverse if inside its mapped envelope, otherwise the target itself.
+    let x = tx;
+    let y = ty;
+    if (Math.hypot(tx, ty) <= profile.radial.maximumMappedNormalizedRadius) {
+        const seed = calculateInverseRadialSourcePointValue(point, profile.radial, "distortedImagePointMm").sourceImagePointMm;
+        x = seed.x / scale;
+        y = seed.y / scale;
+    }
+    let iterations = 0;
+    let residual = Number.POSITIVE_INFINITY;
+    for (; iterations < MAXIMUM_NEWTON_ITERATIONS; iterations += 1) {
+        const f = forwardNormalized(x, y, profile.coefficients);
+        const rx = f.x - tx;
+        const ry = f.y - ty;
+        residual = Math.hypot(rx, ry);
+        if (residual <= tolerance) {
+            break;
+        }
+        const j = jacobianNormalized(x, y, profile.coefficients);
+        const det = determinant(j);
+        if (!(Math.abs(det) > 0) || !Number.isFinite(det)) {
+            break;
+        }
+        const stepX = (j.d * rx - j.b * ry) / det;
+        const stepY = (-j.c * rx + j.a * ry) / det;
+        // Damping: halve the step until the residual decreases (at most 30 halvings).
+        let lambda = 1;
+        let accepted = false;
+        for (let halving = 0; halving < 30; halving += 1) {
+            const nx = x - lambda * stepX;
+            const ny = y - lambda * stepY;
+            const g = forwardNormalized(nx, ny, profile.coefficients);
+            if (Math.hypot(g.x - tx, g.y - ty) < residual) {
+                x = nx;
+                y = ny;
+                accepted = true;
+                break;
+            }
+            lambda /= 2;
+        }
+        if (!accepted) {
+            break;
+        }
+    }
+    const sourceNormalizedRadius = Math.hypot(x, y);
+    if (!(residual <= tolerance) ||
+        sourceNormalizedRadius > maximum * (1 + 1e-12)) {
+        throw new InvalidScientificInputError("distortedImagePointMm lies outside the mapped Brown-Conrady profile operating envelope.");
+    }
+    return { x, y, iterations, residual, sourceNormalizedRadius };
+}
+/** Applies the Brown-Conrady forward mapping to one ideal image-plane point. */
+export function calculateBrownConradyDistortionMapping(input) {
+    requireInputKeys(input, "calculateBrownConradyDistortionMapping", ["imagePointMm", "profile"]);
+    const point = requirePoint("imagePointMm", input.imagePointMm);
+    const profile = validateProfile(input.profile);
+    const scale = profile.radial.normalizationRadiusMm;
+    const x = point.x / scale;
+    const y = point.y / scale;
+    const sourceNormalizedRadius = Math.hypot(x, y);
+    if (sourceNormalizedRadius > profile.radial.maximumNormalizedRadius) {
+        throw new InvalidScientificInputError("imagePointMm lies outside the Brown-Conrady profile maximumNormalizedRadius.");
+    }
+    const mapped = forwardNormalized(x, y, profile.coefficients);
+    const mappedImagePointMm = { x: mapped.x * scale, y: mapped.y * scale };
+    const dx = mappedImagePointMm.x - point.x;
+    const dy = mappedImagePointMm.y - point.y;
+    return approximationResult({
+        direction: "undistorted-to-distorted",
+        sourceImagePointMm: point,
+        mappedImagePointMm,
+        sourceNormalizedRadius,
+        jacobianDeterminant: determinant(jacobianNormalized(x, y, profile.coefficients)),
+        deltaMm: { x: dx, y: dy, distance: Math.hypot(dx, dy) },
+        profileMinimumJacobianDeterminant: profile.minimumJacobianDeterminant
+    }, "generic-brown-conrady-lens-distortion", "1.0.0", assumptions());
+}
+/**
+ * Inverse-maps one distorted image-plane point to its ideal source point, for destination-to-source
+ * resampling. Damped Newton iteration starts from the radial-only inverse. The solution must lie
+ * inside the declared envelope and must reproduce the distorted point within a relative tolerance of
+ * 1e-12.
+ */
+export function calculateInverseBrownConradyDistortionMapping(input) {
+    requireInputKeys(input, "calculateInverseBrownConradyDistortionMapping", ["distortedImagePointMm", "profile"]);
+    const point = requirePoint("distortedImagePointMm", input.distortedImagePointMm);
+    const profile = validateProfile(input.profile);
+    const solved = solveInverseBrownConrady(profile, point);
+    const scale = profile.radial.normalizationRadiusMm;
+    const { x, y, iterations, residual, sourceNormalizedRadius } = solved;
+    const sourceImagePointMm = { x: x * scale, y: y * scale };
+    const dx = sourceImagePointMm.x - point.x;
+    const dy = sourceImagePointMm.y - point.y;
+    return approximationResult({
+        direction: "distorted-to-undistorted",
+        distortedImagePointMm: point,
+        sourceImagePointMm,
+        sourceNormalizedRadius,
+        jacobianDeterminantAtSource: determinant(jacobianNormalized(x, y, profile.coefficients)),
+        newtonIterations: iterations,
+        residualMm: residual * scale,
+        deltaMm: { x: dx, y: dy, distance: Math.hypot(dx, dy) },
+        profileMinimumJacobianDeterminant: profile.minimumJacobianDeterminant
+    }, "generic-inverse-brown-conrady-lens-distortion", "1.0.0", [
+        ...assumptions(),
+        `Inverse uses damped Newton iteration (at most ${MAXIMUM_NEWTON_ITERATIONS} steps) seeded by the radial-only inverse, accepted at a normalized residual of 1e-12`
+    ]);
+}
+//# sourceMappingURL=brown-conrady-distortion.js.map

package/dist/optics/brown-conrady-distortion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brown-conrady-distortion.js","sourceRoot":"","sources":["../../src/optics/brown-conrady-distortion.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Generic Brown-Conrady lens distortion: radial (k1, k2, k3) plus tangential/decentering (p1, p2)\n * terms on normalized image-plane coordinates (x, y) = point / normalizationRadiusMm, r^2 = x^2 + y^2:\n *   x_d = x (1 + k1 r^2 + k2 r^4 + k3 r^6) + 2 p1 x y + p2 (r^2 + 2 x^2)\n *   y_d = y (1 + k1 r^2 + k2 r^4 + k3 r^6) + p1 (r^2 + 2 y^2) + 2 p2 x y\n * In vector form the tangential term is r^2 P + 2 (P . u) u with P = (p2, p1), so (p1, p2) rotate as\n * a vector with the image.\n *\n * Sources: Conrady 1919 (MNRAS 79:384, decentred lens systems); Brown 1966\n * (Photogrammetric Engineering 32:444, \"Decentering distortion of lenses\"); Brown 1971 (Photogramm.\n * Eng. 37:855, close-range camera calibration). The coefficient layout follows the widely used\n * Brown-Conrady convention (for example Heikkila & Silven 1997, CVPR). The coefficient names match\n * that convention, but the values only mean something together with the declared normalization\n * radius.\n *\n * Validity checks (matching the radial-distortion validator):\n * - The radial part must be strictly monotonic over the envelope (the valid radius range).\n * - The Jacobian determinant must stay positive at a dense, fixed polar grid of samples over the\n *   envelope disk.\n * - The mapped envelope boundary must have strictly increasing polar angle, so it is a simple\n *   star-shaped curve.\n * A smooth, locally invertible map of a closed disk that is one-to-one on its boundary is one-to-one\n * everywhere. So these conditions make the inverse single-valued. Note that the Jacobian and boundary\n * conditions are checked at samples, not proven between them.\n *\n * The inverse uses damped Newton iteration, starting from the radial-only inverse.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport {\n  calculateInverseRadialSourcePointValue,\n  validateRadialDistortionProfile,\n  type LensFieldPointMm,\n  type ValidatedRadialProfile\n} from \"./radial-distortion.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport interface BrownConradyDistortionCoefficients {\n  /** Radial r^2 coefficient. */\n  k1: number;\n  /** Radial r^4 coefficient. */\n  k2: number;\n  /** Radial r^6 coefficient. */\n  k3: number;\n  /** Tangential (decentering) coefficient p1 (couples to y; see module equation). */\n  p1: number;\n  /** Tangential (decentering) coefficient p2 (couples to x; see module equation). */\n  p2: number;\n}\n\nexport interface BrownConradyDistortionProfile {\n  /** Physical image-plane radius used to normalize field position, in mm. */\n  normalizationRadiusMm: number;\n  /** Maximum undistorted normalized radius of the operating envelope. */\n  maximumNormalizedRadius: number;\n  coefficients: BrownConradyDistortionCoefficients;\n}\n\nexport interface CalculateBrownConradyDistortionMappingInput {\n  /** Ideal/undistorted image-plane point, in mm. */\n  imagePointMm: LensFieldPointMm;\n  profile: BrownConradyDistortionProfile;\n}\n\nexport interface CalculateInverseBrownConradyDistortionMappingInput {\n  /** Distorted image-plane point to map back to ideal coordinates, in mm. */\n  distortedImagePointMm: LensFieldPointMm;\n  profile: BrownConradyDistortionProfile;\n}\n\nexport interface BrownConradyDistortionMapping {\n  direction: \"undistorted-to-distorted\";\n  sourceImagePointMm: LensFieldPointMm;\n  mappedImagePointMm: LensFieldPointMm;\n  sourceNormalizedRadius: number;\n  /** Determinant of d(mapped)/d(source) at the source point (dimensionless area scale). */\n  jacobianDeterminant: number;\n  deltaMm: { x: number; y: number; distance: number };\n  profileMinimumJacobianDeterminant: number;\n}\n\nexport interface InverseBrownConradyDistortionMapping {\n  direction: \"distorted-to-undistorted\";\n  distortedImagePointMm: LensFieldPointMm;\n  sourceImagePointMm: LensFieldPointMm;\n  sourceNormalizedRadius: number;\n  jacobianDeterminantAtSource: number;\n  newtonIterations: number;\n  /** Forward-mapping residual of the solved source point, in mm. */\n  residualMm: number;\n  deltaMm: { x: number; y: number; distance: number };\n  profileMinimumJacobianDeterminant: number;\n}\n\ninterface ValidatedBrownConradyProfile {\n  radial: ValidatedRadialProfile;\n  coefficients: BrownConradyDistortionCoefficients;\n  minimumJacobianDeterminant: number;\n}\n\nconst VALIDATION_RINGS = 64;\nconst VALIDATION_AZIMUTHS = 256;\nconst MAXIMUM_NEWTON_ITERATIONS = 100;\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 requirePoint(name: string, point: unknown): LensFieldPointMm {\n  if (typeof point !== \"object\" || point === null) {\n    throw new InvalidConfigurationError(\n      `${name} must be an object with finite numeric x and y coordinates.`\n    );\n  }\n  const record = point as Record<string, unknown>;\n  return {\n    x: requireFinite(`${name}.x`, record.x),\n    y: requireFinite(`${name}.y`, record.y)\n  };\n}\n\n/** Forward map on normalized coordinates. */\nfunction forwardNormalized(\n  x: number,\n  y: number,\n  c: BrownConradyDistortionCoefficients\n): { x: number; y: number } {\n  const r2 = x * x + y * y;\n  const radial = 1 + r2 * (c.k1 + r2 * (c.k2 + r2 * c.k3));\n  return {\n    x: x * radial + 2 * c.p1 * x * y + c.p2 * (r2 + 2 * x * x),\n    y: y * radial + c.p1 * (r2 + 2 * y * y) + 2 * c.p2 * x * y\n  };\n}\n\n/** Jacobian [[a, b], [c, d]] of the normalized forward map. */\nfunction jacobianNormalized(\n  x: number,\n  y: number,\n  c: BrownConradyDistortionCoefficients\n): { a: number; b: number; c: number; d: number } {\n  const r2 = x * x + y * y;\n  const s = 1 + r2 * (c.k1 + r2 * (c.k2 + r2 * c.k3));\n  const ds = c.k1 + r2 * (2 * c.k2 + 3 * c.k3 * r2);\n  const off = 2 * x * y * ds + 2 * c.p1 * x + 2 * c.p2 * y;\n  return {\n    a: s + 2 * x * x * ds + 2 * c.p1 * y + 6 * c.p2 * x,\n    b: off,\n    c: off,\n    d: s + 2 * y * y * ds + 6 * c.p1 * y + 2 * c.p2 * x\n  };\n}\n\nfunction determinant(j: { a: number; b: number; c: number; d: number }): number {\n  return j.a * j.d - j.b * j.c;\n}\n\nfunction validateProfile(\n  profile: BrownConradyDistortionProfile\n): ValidatedBrownConradyProfile {\n  if (typeof profile !== \"object\" || profile === null) {\n    throw new InvalidConfigurationError(\"profile must be an object.\");\n  }\n  if (typeof profile.coefficients !== \"object\" || profile.coefficients === null) {\n    throw new InvalidConfigurationError(\"profile.coefficients must be an object.\");\n  }\n  const coefficients: BrownConradyDistortionCoefficients = {\n    k1: requireFinite(\"profile.coefficients.k1\", profile.coefficients.k1),\n    k2: requireFinite(\"profile.coefficients.k2\", profile.coefficients.k2),\n    k3: requireFinite(\"profile.coefficients.k3\", profile.coefficients.k3),\n    p1: requireFinite(\"profile.coefficients.p1\", profile.coefficients.p1),\n    p2: requireFinite(\"profile.coefficients.p2\", profile.coefficients.p2)\n  };\n  const radial = validateRadialDistortionProfile({\n    normalizationRadiusMm: profile.normalizationRadiusMm,\n    maximumNormalizedRadius: profile.maximumNormalizedRadius,\n    coefficients: {\n      k1: coefficients.k1,\n      k2: coefficients.k2,\n      k3: coefficients.k3\n    }\n  });\n\n  const maximum = radial.maximumNormalizedRadius;\n  let minimumJacobianDeterminant = Number.POSITIVE_INFINITY;\n  for (let ring = 0; ring <= VALIDATION_RINGS; ring += 1) {\n    const rho = (maximum * ring) / VALIDATION_RINGS;\n    const azimuths = ring === 0 ? 1 : VALIDATION_AZIMUTHS;\n    for (let index = 0; index < azimuths; index += 1) {\n      const phi = (2 * Math.PI * index) / VALIDATION_AZIMUTHS;\n      const det = determinant(\n        jacobianNormalized(rho * Math.cos(phi), rho * Math.sin(phi), coefficients)\n      );\n      minimumJacobianDeterminant = Math.min(minimumJacobianDeterminant, det);\n    }\n  }\n  if (!Number.isFinite(minimumJacobianDeterminant) || minimumJacobianDeterminant <= 0) {\n    throw new InvalidScientificInputError(\n      \"Brown-Conrady profile must keep a positive Jacobian determinant over maximumNormalizedRadius so the mapping stays locally invertible.\"\n    );\n  }\n\n  // The mapped boundary must be star-shaped about the mapped centre (the origin): its polar angle\n  // must increase strictly around the circle, so the boundary curve is simple.\n  let previous: number | undefined;\n  let accumulated = 0;\n  for (let index = 0; index <= VALIDATION_AZIMUTHS; index += 1) {\n    const phi = (2 * Math.PI * index) / VALIDATION_AZIMUTHS;\n    const mapped = forwardNormalized(\n      maximum * Math.cos(phi),\n      maximum * Math.sin(phi),\n      coefficients\n    );\n    const angle = Math.atan2(mapped.y, mapped.x);\n    if (previous !== undefined) {\n      let step = angle - previous;\n      if (step <= -Math.PI) step += 2 * Math.PI;\n      if (step > Math.PI) step -= 2 * Math.PI;\n      if (!(step > 0)) {\n        throw new InvalidScientificInputError(\n          \"Brown-Conrady profile maps the envelope boundary to a curve that is not star-shaped about the optical axis; the inverse would not be single-valued.\"\n        );\n      }\n      accumulated += step;\n    }\n    previous = angle;\n  }\n  if (Math.abs(accumulated - 2 * Math.PI) > 1e-9) {\n    throw new InvalidScientificInputError(\n      \"Brown-Conrady profile boundary must wind exactly once around the optical axis.\"\n    );\n  }\n\n  return { radial, coefficients, minimumJacobianDeterminant };\n}\n\nfunction assumptions(): readonly string[] {\n  return [\n    \"Generic Brown-Conrady radial (k1, k2, k3) plus tangential/decentering (p1, p2) polynomial field mapping\",\n    \"Coordinates are normalized by the caller-declared normalizationRadiusMm; the optical axis maps to itself\",\n    \"Validity: monotonic radial part, positive Jacobian at a 64-ring x 256-azimuth polar sample and a strictly star-shaped mapped boundary; checked at samples, not proven between them\",\n    \"Coefficients are generic caller inputs and do not represent a named lens unless separately calibrated with defensible provenance\",\n    \"Thin-prism, anamorphic and higher-order decentering terms are not modeled\"\n  ];\n}\n\n/** @internal Opaque validated profile for repeated in-package evaluation. */\nexport type ValidatedBrownConradyDistortionProfile = ValidatedBrownConradyProfile;\n\n/** @internal Validates one profile for repeated evaluation (geometric mapping, ray queries). */\nexport function validateBrownConradyDistortionProfile(\n  profile: BrownConradyDistortionProfile\n): ValidatedBrownConradyDistortionProfile {\n  return validateProfile(profile);\n}\n\n/** @internal Forward map in mm with its Jacobian d(distorted)/d(ideal), row-major. */\nexport function brownConradyForwardValue(\n  profile: ValidatedBrownConradyDistortionProfile,\n  point: LensFieldPointMm\n): { mappedImagePointMm: LensFieldPointMm; jacobian: readonly [number, number, number, number] } {\n  const scale = profile.radial.normalizationRadiusMm;\n  const x = point.x / scale;\n  const y = point.y / scale;\n  if (Math.hypot(x, y) > profile.radial.maximumNormalizedRadius) {\n    throw new InvalidScientificInputError(\n      \"Point lies outside the Brown-Conrady profile maximumNormalizedRadius.\"\n    );\n  }\n  const mapped = forwardNormalized(x, y, profile.coefficients);\n  const j = jacobianNormalized(x, y, profile.coefficients);\n  return {\n    mappedImagePointMm: { x: mapped.x * scale, y: mapped.y * scale },\n    jacobian: [j.a, j.b, j.c, j.d]\n  };\n}\n\n/** @internal Inverse map in mm (distorted to ideal). */\nexport function brownConradyInverseValue(\n  profile: ValidatedBrownConradyDistortionProfile,\n  point: LensFieldPointMm\n): LensFieldPointMm {\n  const solved = solveInverseBrownConrady(profile, point);\n  const scale = profile.radial.normalizationRadiusMm;\n  return { x: solved.x * scale, y: solved.y * scale };\n}\n\nfunction solveInverseBrownConrady(\n  profile: ValidatedBrownConradyProfile,\n  point: LensFieldPointMm\n): { x: number; y: number; iterations: number; residual: number; sourceNormalizedRadius: number } {\n  const scale = profile.radial.normalizationRadiusMm;\n  const maximum = profile.radial.maximumNormalizedRadius;\n  const tx = point.x / scale;\n  const ty = point.y / scale;\n  const tolerance = 1e-12 * Math.max(1, Math.hypot(tx, ty));\n\n  // Starting point: the radial-only inverse if inside its mapped envelope, otherwise the target itself.\n  let x = tx;\n  let y = ty;\n  if (Math.hypot(tx, ty) <= profile.radial.maximumMappedNormalizedRadius) {\n    const seed = calculateInverseRadialSourcePointValue(\n      point,\n      profile.radial,\n      \"distortedImagePointMm\"\n    ).sourceImagePointMm;\n    x = seed.x / scale;\n    y = seed.y / scale;\n  }\n\n  let iterations = 0;\n  let residual = Number.POSITIVE_INFINITY;\n  for (; iterations < MAXIMUM_NEWTON_ITERATIONS; iterations += 1) {\n    const f = forwardNormalized(x, y, profile.coefficients);\n    const rx = f.x - tx;\n    const ry = f.y - ty;\n    residual = Math.hypot(rx, ry);\n    if (residual <= tolerance) {\n      break;\n    }\n    const j = jacobianNormalized(x, y, profile.coefficients);\n    const det = determinant(j);\n    if (!(Math.abs(det) > 0) || !Number.isFinite(det)) {\n      break;\n    }\n    const stepX = (j.d * rx - j.b * ry) / det;\n    const stepY = (-j.c * rx + j.a * ry) / det;\n    // Damping: halve the step until the residual decreases (at most 30 halvings).\n    let lambda = 1;\n    let accepted = false;\n    for (let halving = 0; halving < 30; halving += 1) {\n      const nx = x - lambda * stepX;\n      const ny = y - lambda * stepY;\n      const g = forwardNormalized(nx, ny, profile.coefficients);\n      if (Math.hypot(g.x - tx, g.y - ty) < residual) {\n        x = nx;\n        y = ny;\n        accepted = true;\n        break;\n      }\n      lambda /= 2;\n    }\n    if (!accepted) {\n      break;\n    }\n  }\n\n  const sourceNormalizedRadius = Math.hypot(x, y);\n  if (\n    !(residual <= tolerance) ||\n    sourceNormalizedRadius > maximum * (1 + 1e-12)\n  ) {\n    throw new InvalidScientificInputError(\n      \"distortedImagePointMm lies outside the mapped Brown-Conrady profile operating envelope.\"\n    );\n  }\n\n  return { x, y, iterations, residual, sourceNormalizedRadius };\n}\n\n/** Applies the Brown-Conrady forward mapping to one ideal image-plane point. */\nexport function calculateBrownConradyDistortionMapping(\n  input: CalculateBrownConradyDistortionMappingInput\n): CalculationResult<BrownConradyDistortionMapping> {\n  requireInputKeys(input, \"calculateBrownConradyDistortionMapping\", [\"imagePointMm\", \"profile\"]);\n  const point = requirePoint(\"imagePointMm\", input.imagePointMm);\n  const profile = validateProfile(input.profile);\n  const scale = profile.radial.normalizationRadiusMm;\n  const x = point.x / scale;\n  const y = point.y / scale;\n  const sourceNormalizedRadius = Math.hypot(x, y);\n  if (sourceNormalizedRadius > profile.radial.maximumNormalizedRadius) {\n    throw new InvalidScientificInputError(\n      \"imagePointMm lies outside the Brown-Conrady profile maximumNormalizedRadius.\"\n    );\n  }\n  const mapped = forwardNormalized(x, y, profile.coefficients);\n  const mappedImagePointMm = { x: mapped.x * scale, y: mapped.y * scale };\n  const dx = mappedImagePointMm.x - point.x;\n  const dy = mappedImagePointMm.y - point.y;\n  return approximationResult(\n    {\n      direction: \"undistorted-to-distorted\",\n      sourceImagePointMm: point,\n      mappedImagePointMm,\n      sourceNormalizedRadius,\n      jacobianDeterminant: determinant(jacobianNormalized(x, y, profile.coefficients)),\n      deltaMm: { x: dx, y: dy, distance: Math.hypot(dx, dy) },\n      profileMinimumJacobianDeterminant: profile.minimumJacobianDeterminant\n    },\n    \"generic-brown-conrady-lens-distortion\",\n    \"1.0.0\",\n    assumptions()\n  );\n}\n\n/**\n * Inverse-maps one distorted image-plane point to its ideal source point, for destination-to-source\n * resampling. Damped Newton iteration starts from the radial-only inverse. The solution must lie\n * inside the declared envelope and must reproduce the distorted point within a relative tolerance of\n * 1e-12.\n */\nexport function calculateInverseBrownConradyDistortionMapping(\n  input: CalculateInverseBrownConradyDistortionMappingInput\n): CalculationResult<InverseBrownConradyDistortionMapping> {\n  requireInputKeys(input, \"calculateInverseBrownConradyDistortionMapping\", [\"distortedImagePointMm\", \"profile\"]);\n  const point = requirePoint(\"distortedImagePointMm\", input.distortedImagePointMm);\n  const profile = validateProfile(input.profile);\n  const solved = solveInverseBrownConrady(profile, point);\n  const scale = profile.radial.normalizationRadiusMm;\n  const { x, y, iterations, residual, sourceNormalizedRadius } = solved;\n  const sourceImagePointMm = { x: x * scale, y: y * scale };\n  const dx = sourceImagePointMm.x - point.x;\n  const dy = sourceImagePointMm.y - point.y;\n  return approximationResult(\n    {\n      direction: \"distorted-to-undistorted\",\n      distortedImagePointMm: point,\n      sourceImagePointMm,\n      sourceNormalizedRadius,\n      jacobianDeterminantAtSource: determinant(\n        jacobianNormalized(x, y, profile.coefficients)\n      ),\n      newtonIterations: iterations,\n      residualMm: residual * scale,\n      deltaMm: { x: dx, y: dy, distance: Math.hypot(dx, dy) },\n      profileMinimumJacobianDeterminant: profile.minimumJacobianDeterminant\n    },\n    \"generic-inverse-brown-conrady-lens-distortion\",\n    \"1.0.0\",\n    [\n      ...assumptions(),\n      `Inverse uses damped Newton iteration (at most ${MAXIMUM_NEWTON_ITERATIONS} steps) seeded by the radial-only inverse, accepted at a normalized residual of 1e-12`\n    ]\n  );\n}\n"]}

package/dist/optics/circle-of-confusion.d.ts

@@ -1,10 +1,10 @@
 /**
- * Module boundary and integration notes.
- * Estimates a circle-of-confusion criterion for equivalent final viewing by scaling a caller-supplied
- * reference criterion in proportion to sensor diagonal. This is a viewing/acceptability convention,
- * not a physical blur threshold.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Estimates a circle-of-confusion (CoC) criterion for equivalent final viewing. It scales a
+ * caller-supplied reference criterion in proportion to the sensor diagonal.
+ *
+ * This is a viewing (acceptable-sharpness) convention, not a physical blur threshold.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 export interface EstimateEquivalentViewingCircleOfConfusionInput {
@@ -21,11 +21,11 @@ export interface EquivalentViewingCircleOfConfusion {
     scaleFactor: number;
 }
 /**
- * Estimates a circle-of-confusion criterion for equivalent final viewing by
- * scaling a caller-supplied reference criterion in proportion to sensor
+ * Estimates a circle-of-confusion criterion for equivalent final viewing. It
+ * scales a caller-supplied reference criterion in proportion to the sensor
  * diagonal.
  *
- * This is a viewing/acceptability convention, not a physical blur threshold.
+ * This is a viewing (acceptable-sharpness) convention, not a physical blur
+ * threshold.
  */
 export declare function estimateEquivalentViewingCircleOfConfusion(input: EstimateEquivalentViewingCircleOfConfusionInput): CalculationResult<EquivalentViewingCircleOfConfusion>;
-//# sourceMappingURL=circle-of-confusion.d.ts.map

package/dist/optics/circle-of-confusion.js

@@ -1,29 +1,33 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Estimates a circle-of-confusion criterion for equivalent final viewing by scaling a caller-supplied
- * reference criterion in proportion to sensor diagonal. This is a viewing/acceptability convention,
- * not a physical blur threshold.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Estimates a circle-of-confusion (CoC) criterion for equivalent final viewing. It scales a
+ * caller-supplied reference criterion in proportion to the sensor diagonal.
+ *
+ * This is a viewing (acceptable-sharpness) convention, not a physical blur threshold.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { approximationResult } from "../core/calculation-result.js";
 import { requirePositiveFinite } from "../core/validation.js";
+import { portableHypot } from "../core/portable-math.js";
+import { requireInputKeys } from "../core/record-validation.js";
 /**
- * Estimates a circle-of-confusion criterion for equivalent final viewing by
- * scaling a caller-supplied reference criterion in proportion to sensor
+ * Estimates a circle-of-confusion criterion for equivalent final viewing. It
+ * scales a caller-supplied reference criterion in proportion to the sensor
  * diagonal.
  *
- * This is a viewing/acceptability convention, not a physical blur threshold.
+ * This is a viewing (acceptable-sharpness) convention, not a physical blur
+ * threshold.
  */
 export function estimateEquivalentViewingCircleOfConfusion(input) {
+    requireInputKeys(input, "estimateEquivalentViewingCircleOfConfusion", ["sensorWidthMm", "sensorHeightMm", "referenceSensorWidthMm", "referenceSensorHeightMm", "referenceCircleOfConfusionMm"]);
     requirePositiveFinite("sensorWidthMm", input.sensorWidthMm);
     requirePositiveFinite("sensorHeightMm", input.sensorHeightMm);
     requirePositiveFinite("referenceSensorWidthMm", input.referenceSensorWidthMm);
     requirePositiveFinite("referenceSensorHeightMm", input.referenceSensorHeightMm);
     requirePositiveFinite("referenceCircleOfConfusionMm", input.referenceCircleOfConfusionMm);
-    const sensorDiagonalMm = Math.hypot(input.sensorWidthMm, input.sensorHeightMm);
-    const referenceSensorDiagonalMm = Math.hypot(input.referenceSensorWidthMm, input.referenceSensorHeightMm);
+    const sensorDiagonalMm = portableHypot(input.sensorWidthMm, input.sensorHeightMm);
+    const referenceSensorDiagonalMm = portableHypot(input.referenceSensorWidthMm, input.referenceSensorHeightMm);
     const scaleFactor = sensorDiagonalMm / referenceSensorDiagonalMm;
     return approximationResult({
         circleOfConfusionMm: input.referenceCircleOfConfusionMm * scaleFactor,

package/dist/optics/circle-of-confusion.js.map

@@ -1 +1 @@
-{"version":3,"file":"circle-of-confusion.js","sourceRoot":"","sources":["../../src/optics/circle-of-confusion.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;GAOG;AAEH,OAAO,EACL,mBAAmB,EAEpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAiB9D;;;;;;GAMG;AACH,MAAM,UAAU,0CAA0C,CACxD,KAAsD;IAEtD,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9D,qBAAqB,CACnB,wBAAwB,EACxB,KAAK,CAAC,sBAAsB,CAC7B,CAAC;IACF,qBAAqB,CACnB,yBAAyB,EACzB,KAAK,CAAC,uBAAuB,CAC9B,CAAC;IACF,qBAAqB,CACnB,8BAA8B,EAC9B,KAAK,CAAC,4BAA4B,CACnC,CAAC;IAEF,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CACjC,KAAK,CAAC,aAAa,EACnB,KAAK,CAAC,cAAc,CACrB,CAAC;IACF,MAAM,yBAAyB,GAAG,IAAI,CAAC,KAAK,CAC1C,KAAK,CAAC,sBAAsB,EAC5B,KAAK,CAAC,uBAAuB,CAC9B,CAAC;IACF,MAAM,WAAW,GAAG,gBAAgB,GAAG,yBAAyB,CAAC;IAEjE,OAAO,mBAAmB,CACxB;QACE,mBAAmB,EACjB,KAAK,CAAC,4BAA4B,GAAG,WAAW;QAClD,gBAAgB;QAChB,yBAAyB;QACzB,WAAW;KACZ,EACD,wCAAwC,EACxC,OAAO,EACP;QACE,iFAAiF;QACjF,wEAAwE;QACxE,qEAAqE;QACrE,yEAAyE;KAC1E,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"circle-of-confusion.js","sourceRoot":"","sources":["../../src/optics/circle-of-confusion.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;GAOG;AAEH,OAAO,EACL,mBAAmB,EAEpB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAiBhE;;;;;;;GAOG;AACH,MAAM,UAAU,0CAA0C,CACxD,KAAsD;IAEtD,gBAAgB,CAAC,KAAK,EAAE,4CAA4C,EAAE,CAAC,eAAe,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,8BAA8B,CAAC,CAAC,CAAC;IAChM,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9D,qBAAqB,CACnB,wBAAwB,EACxB,KAAK,CAAC,sBAAsB,CAC7B,CAAC;IACF,qBAAqB,CACnB,yBAAyB,EACzB,KAAK,CAAC,uBAAuB,CAC9B,CAAC;IACF,qBAAqB,CACnB,8BAA8B,EAC9B,KAAK,CAAC,4BAA4B,CACnC,CAAC;IAEF,MAAM,gBAAgB,GAAG,aAAa,CACpC,KAAK,CAAC,aAAa,EACnB,KAAK,CAAC,cAAc,CACrB,CAAC;IACF,MAAM,yBAAyB,GAAG,aAAa,CAC7C,KAAK,CAAC,sBAAsB,EAC5B,KAAK,CAAC,uBAAuB,CAC9B,CAAC;IACF,MAAM,WAAW,GAAG,gBAAgB,GAAG,yBAAyB,CAAC;IAEjE,OAAO,mBAAmB,CACxB;QACE,mBAAmB,EACjB,KAAK,CAAC,4BAA4B,GAAG,WAAW;QAClD,gBAAgB;QAChB,yBAAyB;QACzB,WAAW;KACZ,EACD,wCAAwC,EACxC,OAAO,EACP;QACE,iFAAiF;QACjF,wEAAwE;QACxE,qEAAqE;QACrE,yEAAyE;KAC1E,CACF,CAAC;AACJ,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Estimates a circle-of-confusion (CoC) criterion for equivalent final viewing. It scales a\n * caller-supplied reference criterion in proportion to the sensor diagonal.\n *\n * This is a viewing (acceptable-sharpness) convention, not a physical blur threshold.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport { requirePositiveFinite } from \"../core/validation.js\";\nimport { portableHypot } from \"../core/portable-math.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\nexport interface EstimateEquivalentViewingCircleOfConfusionInput {\n  sensorWidthMm: number;\n  sensorHeightMm: number;\n  referenceSensorWidthMm: number;\n  referenceSensorHeightMm: number;\n  referenceCircleOfConfusionMm: number;\n}\n\nexport interface EquivalentViewingCircleOfConfusion {\n  circleOfConfusionMm: number;\n  sensorDiagonalMm: number;\n  referenceSensorDiagonalMm: number;\n  scaleFactor: number;\n}\n\n/**\n * Estimates a circle-of-confusion criterion for equivalent final viewing. It\n * scales a caller-supplied reference criterion in proportion to the sensor\n * diagonal.\n *\n * This is a viewing (acceptable-sharpness) convention, not a physical blur\n * threshold.\n */\nexport function estimateEquivalentViewingCircleOfConfusion(\n  input: EstimateEquivalentViewingCircleOfConfusionInput\n): CalculationResult<EquivalentViewingCircleOfConfusion> {\n  requireInputKeys(input, \"estimateEquivalentViewingCircleOfConfusion\", [\"sensorWidthMm\", \"sensorHeightMm\", \"referenceSensorWidthMm\", \"referenceSensorHeightMm\", \"referenceCircleOfConfusionMm\"]);\n  requirePositiveFinite(\"sensorWidthMm\", input.sensorWidthMm);\n  requirePositiveFinite(\"sensorHeightMm\", input.sensorHeightMm);\n  requirePositiveFinite(\n    \"referenceSensorWidthMm\",\n    input.referenceSensorWidthMm\n  );\n  requirePositiveFinite(\n    \"referenceSensorHeightMm\",\n    input.referenceSensorHeightMm\n  );\n  requirePositiveFinite(\n    \"referenceCircleOfConfusionMm\",\n    input.referenceCircleOfConfusionMm\n  );\n\n  const sensorDiagonalMm = portableHypot(\n    input.sensorWidthMm,\n    input.sensorHeightMm\n  );\n  const referenceSensorDiagonalMm = portableHypot(\n    input.referenceSensorWidthMm,\n    input.referenceSensorHeightMm\n  );\n  const scaleFactor = sensorDiagonalMm / referenceSensorDiagonalMm;\n\n  return approximationResult(\n    {\n      circleOfConfusionMm:\n        input.referenceCircleOfConfusionMm * scaleFactor,\n      sensorDiagonalMm,\n      referenceSensorDiagonalMm,\n      scaleFactor\n    },\n    \"equivalent-viewing-circle-of-confusion\",\n    \"1.0.0\",\n    [\n      \"Reference and target images are compared at equivalent final display/print size\",\n      \"Viewing distance and visual-acuity criterion are treated as equivalent\",\n      \"Acceptable circle of confusion scales linearly with sensor diagonal\",\n      \"This is a viewing convention, not a physical lens/sensor blur threshold\"\n    ]\n  );\n}\n"]}

package/dist/optics/complex-pupil-psf.d.ts

@@ -1,17 +1,15 @@
 /**
- * Module boundary and integration notes.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. Complex pupil
- * evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF shape is
- * normalized separately from pupil throughput; coherent phase, pupil energy and spectral/field
- * applicability cannot be replaced by a scalar blur radius. Numeric profiles require owned or
- * reusable-data provenance.
- * Evaluate a declared complex pupil with explicit amplitude/phase and sampling support; normalize PSF
- * shape and retain pupil throughput as a separate quantity. Complex pupil evaluation sums declared
- * amplitude and phase on a bounded regular pupil grid. PSF shape is normalized separately from pupil
- * throughput; coherent phase, pupil energy and spectral/field applicability cannot be replaced by a
- * scalar blur radius. Numeric profiles require owned or reusable-data provenance.
- * @see docs/PSF_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support limits.
+ * PSF (point-spread function) from a declared complex pupil: amplitude and phase sampled on a grid.
+ *
+ * The profile parser validates untrusted input and returns the normalized typed contract. Unknown
+ * enum values, missing required fields and incompatible scientific data are rejected.
+ *
+ * The complex pupil is evaluated by summing the declared amplitude and phase over a bounded, regular
+ * pupil grid. The PSF shape is normalized separately from the pupil throughput. A single blur radius
+ * cannot stand in for coherent phase, pupil energy, or the wavelength and field range where the
+ * profile applies. Numeric profiles need provenance showing the data is owned or reusable.
+ * @see docs/PSF_FOUNDATION.md for the equations, units, coordinate conventions, known blockers and
+ * support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type EvidenceProvenance } from "../core/evidence-provenance.js";
@@ -71,9 +69,9 @@ export interface LensComplexPupilProfile {
 }
 export interface CalculateLensComplexPupilPsfInput {
     profile: LensComplexPupilProfile;
-    /** Physical pupil-to-image propagation scale in mm. Omission preserves the
-     * nominal focal-plane reference. Finite-focus callers must explicitly resolve
-     * the supported principal-plane geometry; profile metadata does not do so. */
+    /** Physical propagation distance from pupil to image, in mm. If omitted, the
+     * nominal focal-plane reference is used. At finite focus the caller must
+     * resolve the supported principal-plane geometry; profile metadata does not. */
     propagationDistanceMm?: number;
 }
 export interface LensComplexPupilPsf {
@@ -84,6 +82,8 @@ export interface LensComplexPupilPsf {
     scientificStatus: LensPsfScientificStatus;
     context: LensComplexPupilProfile["context"];
     kernel: LensPsfKernel;
+    /** Nyquist sampling diagnostics and the applied zero padding. */
+    sampling: LensComplexPupilPsfSampling;
     relativePupilThroughputFactor: number;
     throughputOwnership: "separate-relative-pupil-throughput-factor";
     diffractionAndAberrationJointlyEvaluated: true;
@@ -104,31 +104,62 @@ export interface LensComplexPupilPsf {
     uncertainty: LensPsfUncertainty;
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
- * shape is normalized separately from pupil throughput; coherent phase, pupil energy and
- * spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
- * owned or reusable-data provenance.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns LensComplexPupilProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The complex pupil is evaluated by summing the declared amplitude and phase over a bounded, regular
+ * pupil grid. The PSF shape is normalized separately from the pupil throughput. A single blur radius
+ * cannot stand in for coherent phase, pupil energy, or the wavelength and field range where the
+ * profile applies. Numeric profiles need provenance showing the data is owned or reusable.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns LensComplexPupilProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function parseLensComplexPupilProfile(value: unknown): LensComplexPupilProfile;
+export interface LensComplexPupilPsfSampling {
+    criterion: "discrete-intensity-alias-free-goodman-q-above-2";
+    /** Number of pupil samples spanned by non-zero amplitude, per axis. */
+    pupilSupportSamplesX: number;
+    pupilSupportSamplesY: number;
+    /**
+     * Sampled pupil diameter D = (support samples - 1) x pupil pitch: the
+     * centre-to-centre span of the outermost non-zero samples, in millimetres.
+     */
+    pupilSupportDiameterMmX: number;
+    pupilSupportDiameterMmY: number;
+    /**
+     * Widest support allowed by the declared f-number at the resolved propagation distance:
+     * propagationDistanceMm / apertureFNumber, in millimetres. For the nominal focal-plane reference
+     * this is focalLengthMm / apertureFNumber.
+     */
+    declaredPupilDiameterMm: number;
+    /** Declared pupil grid size before zero padding. */
+    pupilGridWidthSamples: number;
+    pupilGridHeightSamples: number;
+    /** DFT size after zero padding; equals the output kernel size. */
+    transformWidthSamples: number;
+    transformHeightSamples: number;
+    zeroPaddingApplied: boolean;
+    /**
+     * Achieved Goodman sampling factor Q = lambda*(z/D)/imagePitch =
+     * transform samples / (support samples - 1). Always greater than 2. Null
+     * when the support is a single sample on that axis (no finite diameter).
+     */
+    samplingFactorQX: number | null;
+    samplingFactorQY: number | null;
+}
 /**
- * Evaluate a declared complex pupil with explicit amplitude/phase and sampling support; normalize PSF
- * shape and retain pupil throughput as a separate quantity.
+ * Evaluates a declared complex pupil with explicit amplitude, phase and sampling support. Returns the
+ * normalized PSF shape, and the pupil throughput as a separate quantity.
  *
- * Complex pupil evaluation sums declared amplitude and phase on a bounded regular pupil grid. PSF
- * shape is normalized separately from pupil throughput; coherent phase, pupil energy and
- * spectral/field applicability cannot be replaced by a scalar blur radius. Numeric profiles require
- * owned or reusable-data provenance.
- * @param input - CalculateLensComplexPupilPsfInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns CalculationResult<LensComplexPupilPsf>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The complex pupil is evaluated by summing the declared amplitude and phase over a bounded, regular
+ * pupil grid. The PSF shape is normalized separately from the pupil throughput. A single blur radius
+ * cannot stand in for coherent phase, pupil energy, or the wavelength and field range where the
+ * profile applies. Numeric profiles need provenance showing the data is owned or reusable.
+ * @param input - CalculateLensComplexPupilPsfInput. See that type for coordinates, units and profile binding.
+ * @returns CalculationResult<LensComplexPupilPsf>. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export declare function calculateLensComplexPupilPsf(input: CalculateLensComplexPupilPsfInput): CalculationResult<LensComplexPupilPsf>;
-//# sourceMappingURL=complex-pupil-psf.d.ts.map