@photivra/engine 1.5.0 → 2.1.0

package/dist/optics/depth-of-field.js

@@ -1,28 +1,40 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates thin-lens depth-of-field limits using the conventional hyperfocal-distance formulation.
- * The model is geometric and does not include diffraction, aberrations, focus breathing, pupil
- * magnification, or macro/high-magnification effects.
- * Calculates the geometric defocus-circle diameter at the sensor plane for a subject plane away from
- * the selected focus plane.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Thin-lens depth of field (DoF) and defocus blur.
+ *
+ * Depth-of-field limits are exact for a thin lens. They use the hyperfocal distance
+ * H = f^2/(Nc) + f:
+ *   near = s(H - f)/(H + s - 2f)
+ *   far  = s(H - f)/(H - s), infinite (null) when s >= H
+ * The model is geometric. It does not include diffraction, aberrations, focus breathing, pupil
+ * magnification or macro (high-magnification) effects.
+ *
+ * The defocus circle is the geometric blur-circle diameter at the sensor for a subject plane that is
+ * not at the focus distance.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { calculatedResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
 import { calculateThinLensImageDistance } from "./thin-lens.js";
+import { requireInputKeys } from "../core/record-validation.js";
 /**
- * Calculates thin-lens depth-of-field limits using the conventional
- * hyperfocal-distance formulation.
+ * Calculates exact thin-lens depth-of-field limits. With hyperfocal
+ * distance H = f^2/(Nc) + f and focus distance s, the near limit is
+ * s(H - f)/(H + s - 2f) and the far limit is s(H - f)/(H - s), which is
+ * infinite (`null`) when s >= H. At both limits the geometric defocus circle
+ * from {@link calculateDefocusCircle} equals the supplied circle of confusion.
+ * The circle of confusion must be smaller than the aperture diameter f/N;
+ * otherwise the near limit would fall inside the focal length.
  *
- * The model is geometric and does not include diffraction, aberrations,
- * focus breathing, pupil magnification, or macro/high-magnification effects.
+ * The model is geometric. It does not include diffraction, aberrations,
+ * focus breathing, pupil magnification or macro (high-magnification) effects.
  *
  * @param input Lens, focus, aperture, and acceptable blur-circle inputs.
  * @returns Hyperfocal, near, and far depth-of-field distances.
  */
 export function calculateDepthOfField(input) {
+    requireInputKeys(input, "calculateDepthOfField", ["focalLengthMm", "aperture", "focusDistanceM", "circleOfConfusionMm"]);
     requirePositiveFinite("focalLengthMm", input.focalLengthMm);
     requirePositiveFinite("aperture", input.aperture);
     requirePositiveFinite("focusDistanceM", input.focusDistanceM);
@@ -31,22 +43,37 @@ export function calculateDepthOfField(input) {
     if (focusDistanceMm <= input.focalLengthMm) {
         throw new InvalidScientificInputError("focusDistanceM must place the focus plane beyond the focal length.");
     }
-    const hyperfocalDistanceMm = (input.focalLengthMm * input.focalLengthMm) /
-        (input.aperture * input.circleOfConfusionMm) +
-        input.focalLengthMm;
-    const focusOffsetMm = focusDistanceMm - input.focalLengthMm;
-    const nearLimitMm = (hyperfocalDistanceMm * focusDistanceMm) /
-        (hyperfocalDistanceMm + focusOffsetMm);
-    const farDenominator = hyperfocalDistanceMm - focusOffsetMm;
-    const farLimitMm = farDenominator <= 0
+    // The near limit lies beyond the focal length only when H - f = f^2/(Nc) > f,
+    // i.e. c < f/N (the entrance-pupil diameter). A blur circle at least as large
+    // as the pupil itself has no real-image depth-of-field solution.
+    if (input.circleOfConfusionMm >= input.focalLengthMm / input.aperture) {
+        throw new InvalidScientificInputError("circleOfConfusionMm must be smaller than the aperture diameter focalLengthMm / aperture.");
+    }
+    // H - f = f^2 / (N c), kept separately to avoid cancellation.
+    const hyperfocalOffsetMm = (input.focalLengthMm * input.focalLengthMm) /
+        (input.aperture * input.circleOfConfusionMm);
+    const hyperfocalDistanceMm = hyperfocalOffsetMm + input.focalLengthMm;
+    // Exact thin-lens limits. The defocus-circle diameter for a subject at d
+    // while focused at s is c(d) = f^2 |s - d| / (N d (s - f)). Solving
+    // c(d) = c with H = f^2 / (N c) + f gives
+    //   near = s (H - f) / (H + s - 2f) = s (H - f) / ((H - f) + (s - f))
+    //   far  = s (H - f) / (H - s), infinite when s >= H.
+    const nearLimitMm = (focusDistanceMm * hyperfocalOffsetMm) /
+        (hyperfocalOffsetMm + (focusDistanceMm - input.focalLengthMm));
+    // Compare against the reported hyperfocal distance in metres as well, so a
+    // caller focusing at exactly the returned hyperfocalDistanceM always gets an
+    // infinite far limit despite millimetre/metre rounding.
+    const hyperfocalDistanceM = hyperfocalDistanceMm / 1000;
+    const farDenominator = hyperfocalDistanceMm - focusDistanceMm;
+    const farLimitMm = farDenominator <= 0 || input.focusDistanceM >= hyperfocalDistanceM
         ? null
-        : (hyperfocalDistanceMm * focusDistanceMm) / farDenominator;
+        : (focusDistanceMm * hyperfocalOffsetMm) / farDenominator;
     return calculatedResult({
-        hyperfocalDistanceM: hyperfocalDistanceMm / 1000,
+        hyperfocalDistanceM,
         nearLimitM: nearLimitMm / 1000,
         farLimitM: farLimitMm === null ? null : farLimitMm / 1000,
         totalDepthOfFieldM: farLimitMm === null ? null : (farLimitMm - nearLimitMm) / 1000
-    }, "thin-lens-depth-of-field", "1.0.0", [
+    }, "thin-lens-depth-of-field", "1.1.0", [
         "Geometric thin-lens model",
         "Circle of confusion is supplied by the caller",
         "Macro/high-magnification effects are not modeled"
@@ -54,12 +81,14 @@ export function calculateDepthOfField(input) {
 }
 /**
  * Calculates the geometric defocus-circle diameter at the sensor plane for a
- * subject plane away from the selected focus plane.
+ * subject plane away from the selected focus plane, using the stable closed
+ * form c = f^2 |s - d| / (N d (s - f)) (model 1.1.0).
  *
  * @param input Lens, aperture, focus-plane, and subject-plane distances.
  * @returns Geometric blur-circle diameter.
  */
 export function calculateDefocusCircle(input) {
+    requireInputKeys(input, "calculateDefocusCircle", ["focalLengthMm", "aperture", "focusDistanceM", "subjectDistanceM"]);
     return calculateDefocusCircleUsingFocusProjection(input);
 }
 /** @internal Reuses a projection already calculated for this exact POC request. */
@@ -97,10 +126,21 @@ export function calculateDefocusCircleUsingFocusProjection(input, projection) {
         }
         throw error;
     }
+    // Both image distances are still resolved above, so the thin-lens domain checks
+    // and the reused-projection identity check still run.
+    void focusImageDistanceMm;
+    void subjectImageDistanceMm;
     const apertureDiameterMm = input.focalLengthMm / input.aperture;
+    const focusDistanceMm = input.focusDistanceM * 1000;
+    const subjectDistanceMm = input.subjectDistanceM * 1000;
+    // Closed form of D |v_d - v_s| / v_d with v = f x / (x - f) (Gaussian thin lens):
+    //   c = f^2 |s - d| / (N d (s - f)).
+    // It avoids subtracting two nearly equal image distances (catastrophic
+    // cancellation for distant subjects) and is grouped as bounded ratios so the
+    // intermediate products cannot overflow for finite in-domain inputs.
     const diameterMm = apertureDiameterMm *
-        (Math.abs(subjectImageDistanceMm - focusImageDistanceMm) /
-            subjectImageDistanceMm);
-    return calculatedResult({ diameterMm }, "thin-lens-defocus-circle", "1.0.0", ["Geometric thin-lens model", "Ideal circular entrance pupil"]);
+        (Math.abs(focusDistanceMm - subjectDistanceMm) / subjectDistanceMm) *
+        (input.focalLengthMm / (focusDistanceMm - input.focalLengthMm));
+    return calculatedResult({ diameterMm }, "thin-lens-defocus-circle", "1.1.0", ["Geometric thin-lens model", "Ideal circular entrance pupil"]);
 }
 //# sourceMappingURL=depth-of-field.js.map

package/dist/optics/depth-of-field.js.map

@@ -1 +1 @@
-{"version":3,"file":"depth-of-field.js","sourceRoot":"","sources":["../../src/optics/depth-of-field.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"depth-of-field.js","sourceRoot":"","sources":["../../src/optics/depth-of-field.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,8BAA8B,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAsBhE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAiC;IAEjC,gBAAgB,CAAC,KAAK,EAAE,uBAAuB,EAAE,CAAC,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,qBAAqB,CAAC,CAAC,CAAC;IACzH,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9D,qBAAqB,CAAC,qBAAqB,EAAE,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAExE,MAAM,eAAe,GAAG,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC;IACpD,IAAI,eAAe,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QAC3C,MAAM,IAAI,2BAA2B,CACnC,oEAAoE,CACrE,CAAC;IACJ,CAAC;IACD,8EAA8E;IAC9E,8EAA8E;IAC9E,iEAAiE;IACjE,IAAI,KAAK,CAAC,mBAAmB,IAAI,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;QACtE,MAAM,IAAI,2BAA2B,CACnC,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IAED,8DAA8D;IAC9D,MAAM,kBAAkB,GACtB,CAAC,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;QAC3C,CAAC,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAC/C,MAAM,oBAAoB,GAAG,kBAAkB,GAAG,KAAK,CAAC,aAAa,CAAC;IAEtE,yEAAyE;IACzE,oEAAoE;IACpE,0CAA0C;IAC1C,sEAAsE;IACtE,sDAAsD;IACtD,MAAM,WAAW,GACf,CAAC,eAAe,GAAG,kBAAkB,CAAC;QACtC,CAAC,kBAAkB,GAAG,CAAC,eAAe,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IAEjE,2EAA2E;IAC3E,6EAA6E;IAC7E,wDAAwD;IACxD,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,IAAI,CAAC;IACxD,MAAM,cAAc,GAAG,oBAAoB,GAAG,eAAe,CAAC;IAC9D,MAAM,UAAU,GACd,cAAc,IAAI,CAAC,IAAI,KAAK,CAAC,cAAc,IAAI,mBAAmB;QAChE,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,CAAC,eAAe,GAAG,kBAAkB,CAAC,GAAG,cAAc,CAAC;IAE9D,OAAO,gBAAgB,CACrB;QACE,mBAAmB;QACnB,UAAU,EAAE,WAAW,GAAG,IAAI;QAC9B,SAAS,EAAE,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,GAAG,IAAI;QACzD,kBAAkB,EAChB,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,IAAI;KACjE,EACD,0BAA0B,EAC1B,OAAO,EACP;QACE,2BAA2B;QAC3B,+CAA+C;QAC/C,kDAAkD;KACnD,CACF,CAAC;AACJ,CAAC;AAkBD;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAkC;IAElC,gBAAgB,CAAC,KAAK,EAAE,wBAAwB,EAAE,CAAC,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACvH,OAAO,0CAA0C,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AASD,mFAAmF;AACnF,MAAM,UAAU,0CAA0C,CACxD,KAAkC,EAClC,UAA2C;IAE3C,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9D,qBAAqB,CAAC,kBAAkB,EAAE,KAAK,CAAC,gBAAgB,CAAC,CAAC;IAElE,IAAI,oBAA4B,CAAC;IACjC,IAAI,sBAA8B,CAAC;IACnC,IAAI,CAAC;QACH,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,IAAI,UAAU,CAAC,aAAa,KAAK,KAAK,CAAC,aAAa;gBAChD,UAAU,CAAC,cAAc,KAAK,KAAK,CAAC,cAAc;gBAClD,KAAK,CAAC,cAAc,GAAG,IAAI,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;gBACvD,MAAM,IAAI,2BAA2B,CAAC,8DAA8D,CAAC,CAAC;YACxG,CAAC;YACD,qBAAqB,CAAC,8BAA8B,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;YAClF,oBAAoB,GAAG,UAAU,CAAC,eAAe,CAAC;QACpD,CAAC;aAAM,CAAC;YACN,oBAAoB,GAAG,8BAA8B,CAAC;gBACpD,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,eAAe,EAAE,KAAK,CAAC,cAAc;aACtC,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;QAC3B,CAAC;QACD,sBAAsB,GAAG,8BAA8B,CAAC;YACtD,aAAa,EAAE,KAAK,CAAC,aAAa;YAClC,eAAe,EAAE,KAAK,CAAC,gBAAgB;SACxC,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,2BAA2B,EAAE,CAAC;YACjD,MAAM,IAAI,2BAA2B,CACnC,sEAAsE,CACvE,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,gFAAgF;IAChF,sDAAsD;IACtD,KAAK,oBAAoB,CAAC;IAC1B,KAAK,sBAAsB,CAAC;IAC5B,MAAM,kBAAkB,GAAG,KAAK,CAAC,aAAa,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChE,MAAM,eAAe,GAAG,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC;IACpD,MAAM,iBAAiB,GAAG,KAAK,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAExD,kFAAkF;IAClF,qCAAqC;IACrC,uEAAuE;IACvE,6EAA6E;IAC7E,qEAAqE;IACrE,MAAM,UAAU,GACd,kBAAkB;QAClB,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,GAAG,iBAAiB,CAAC,GAAG,iBAAiB,CAAC;QACnE,CAAC,KAAK,CAAC,aAAa,GAAG,CAAC,eAAe,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IAElE,OAAO,gBAAgB,CACrB,EAAE,UAAU,EAAE,EACd,0BAA0B,EAC1B,OAAO,EACP,CAAC,2BAA2B,EAAE,+BAA+B,CAAC,CAC/D,CAAC;AACJ,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Thin-lens depth of field (DoF) and defocus blur.\n *\n * Depth-of-field limits are exact for a thin lens. They use the hyperfocal distance\n * H = f^2/(Nc) + f:\n *   near = s(H - f)/(H + s - 2f)\n *   far  = s(H - f)/(H - s), infinite (null) when s >= H\n * The model is geometric. It does not include diffraction, aberrations, focus breathing, pupil\n * magnification or macro (high-magnification) effects.\n *\n * The defocus circle is the geometric blur-circle diameter at the sensor for a subject plane that is\n * not at the focus distance.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport { calculateThinLensImageDistance } from \"./thin-lens.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\nexport interface CalculateDepthOfFieldInput {\n  /** Lens focal length in millimetres. */\n  focalLengthMm: number;\n  /** F-number. */\n  aperture: number;\n  /** Focus distance from the lens plane in metres. */\n  focusDistanceM: number;\n  /** Acceptable circle of confusion diameter in millimetres. */\n  circleOfConfusionMm: number;\n}\n\nexport interface DepthOfField {\n  hyperfocalDistanceM: number;\n  nearLimitM: number;\n  /** Null represents an infinite far limit. */\n  farLimitM: number | null;\n  /** Null represents infinite total depth of field. */\n  totalDepthOfFieldM: number | null;\n}\n\n/**\n * Calculates exact thin-lens depth-of-field limits. With hyperfocal\n * distance H = f^2/(Nc) + f and focus distance s, the near limit is\n * s(H - f)/(H + s - 2f) and the far limit is s(H - f)/(H - s), which is\n * infinite (`null`) when s >= H. At both limits the geometric defocus circle\n * from {@link calculateDefocusCircle} equals the supplied circle of confusion.\n * The circle of confusion must be smaller than the aperture diameter f/N;\n * otherwise the near limit would fall inside the focal length.\n *\n * The model is geometric. It does not include diffraction, aberrations,\n * focus breathing, pupil magnification or macro (high-magnification) effects.\n *\n * @param input Lens, focus, aperture, and acceptable blur-circle inputs.\n * @returns Hyperfocal, near, and far depth-of-field distances.\n */\nexport function calculateDepthOfField(\n  input: CalculateDepthOfFieldInput\n): CalculationResult<DepthOfField> {\n  requireInputKeys(input, \"calculateDepthOfField\", [\"focalLengthMm\", \"aperture\", \"focusDistanceM\", \"circleOfConfusionMm\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"aperture\", input.aperture);\n  requirePositiveFinite(\"focusDistanceM\", input.focusDistanceM);\n  requirePositiveFinite(\"circleOfConfusionMm\", input.circleOfConfusionMm);\n\n  const focusDistanceMm = input.focusDistanceM * 1000;\n  if (focusDistanceMm <= input.focalLengthMm) {\n    throw new InvalidScientificInputError(\n      \"focusDistanceM must place the focus plane beyond the focal length.\"\n    );\n  }\n  // The near limit lies beyond the focal length only when H - f = f^2/(Nc) > f,\n  // i.e. c < f/N (the entrance-pupil diameter). A blur circle at least as large\n  // as the pupil itself has no real-image depth-of-field solution.\n  if (input.circleOfConfusionMm >= input.focalLengthMm / input.aperture) {\n    throw new InvalidScientificInputError(\n      \"circleOfConfusionMm must be smaller than the aperture diameter focalLengthMm / aperture.\"\n    );\n  }\n\n  // H - f = f^2 / (N c), kept separately to avoid cancellation.\n  const hyperfocalOffsetMm =\n    (input.focalLengthMm * input.focalLengthMm) /\n    (input.aperture * input.circleOfConfusionMm);\n  const hyperfocalDistanceMm = hyperfocalOffsetMm + input.focalLengthMm;\n\n  // Exact thin-lens limits. The defocus-circle diameter for a subject at d\n  // while focused at s is c(d) = f^2 |s - d| / (N d (s - f)). Solving\n  // c(d) = c with H = f^2 / (N c) + f gives\n  //   near = s (H - f) / (H + s - 2f) = s (H - f) / ((H - f) + (s - f))\n  //   far  = s (H - f) / (H - s), infinite when s >= H.\n  const nearLimitMm =\n    (focusDistanceMm * hyperfocalOffsetMm) /\n    (hyperfocalOffsetMm + (focusDistanceMm - input.focalLengthMm));\n\n  // Compare against the reported hyperfocal distance in metres as well, so a\n  // caller focusing at exactly the returned hyperfocalDistanceM always gets an\n  // infinite far limit despite millimetre/metre rounding.\n  const hyperfocalDistanceM = hyperfocalDistanceMm / 1000;\n  const farDenominator = hyperfocalDistanceMm - focusDistanceMm;\n  const farLimitMm =\n    farDenominator <= 0 || input.focusDistanceM >= hyperfocalDistanceM\n      ? null\n      : (focusDistanceMm * hyperfocalOffsetMm) / farDenominator;\n\n  return calculatedResult(\n    {\n      hyperfocalDistanceM,\n      nearLimitM: nearLimitMm / 1000,\n      farLimitM: farLimitMm === null ? null : farLimitMm / 1000,\n      totalDepthOfFieldM:\n        farLimitMm === null ? null : (farLimitMm - nearLimitMm) / 1000\n    },\n    \"thin-lens-depth-of-field\",\n    \"1.1.0\",\n    [\n      \"Geometric thin-lens model\",\n      \"Circle of confusion is supplied by the caller\",\n      \"Macro/high-magnification effects are not modeled\"\n    ]\n  );\n}\n\nexport interface CalculateDefocusCircleInput {\n  /** Lens focal length in millimetres. */\n  focalLengthMm: number;\n  /** F-number. */\n  aperture: number;\n  /** Focus-plane distance from the lens plane in metres. */\n  focusDistanceM: number;\n  /** Subject-plane distance from the lens plane in metres. */\n  subjectDistanceM: number;\n}\n\nexport interface DefocusCircle {\n  /** Geometric blur-circle diameter at the sensor plane in millimetres. */\n  diameterMm: number;\n}\n\n/**\n * Calculates the geometric defocus-circle diameter at the sensor plane for a\n * subject plane away from the selected focus plane, using the stable closed\n * form c = f^2 |s - d| / (N d (s - f)) (model 1.1.0).\n *\n * @param input Lens, aperture, focus-plane, and subject-plane distances.\n * @returns Geometric blur-circle diameter.\n */\nexport function calculateDefocusCircle(\n  input: CalculateDefocusCircleInput\n): CalculationResult<DefocusCircle> {\n  requireInputKeys(input, \"calculateDefocusCircle\", [\"focalLengthMm\", \"aperture\", \"focusDistanceM\", \"subjectDistanceM\"]);\n  return calculateDefocusCircleUsingFocusProjection(input);\n}\n\n/** @internal Immutable identity for one request. Not a public cache or API. */\nexport interface ResolvedDefocusFocusProjection {\n  readonly focalLengthMm: number;\n  readonly focusDistanceM: number;\n  readonly imageDistanceMm: number;\n}\n\n/** @internal Reuses a projection already calculated for this exact POC request. */\nexport function calculateDefocusCircleUsingFocusProjection(\n  input: CalculateDefocusCircleInput,\n  projection?: ResolvedDefocusFocusProjection\n): CalculationResult<DefocusCircle> {\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"aperture\", input.aperture);\n  requirePositiveFinite(\"focusDistanceM\", input.focusDistanceM);\n  requirePositiveFinite(\"subjectDistanceM\", input.subjectDistanceM);\n\n  let focusImageDistanceMm: number;\n  let subjectImageDistanceMm: number;\n  try {\n    if (projection !== undefined) {\n      if (projection.focalLengthMm !== input.focalLengthMm ||\n          projection.focusDistanceM !== input.focusDistanceM ||\n          input.focusDistanceM * 1000 <= input.focalLengthMm) {\n        throw new InvalidScientificInputError(\"Resolved focus projection identity differs from the request.\");\n      }\n      requirePositiveFinite(\"resolvedFocusImageDistanceMm\", projection.imageDistanceMm);\n      focusImageDistanceMm = projection.imageDistanceMm;\n    } else {\n      focusImageDistanceMm = calculateThinLensImageDistance({\n        focalLengthMm: input.focalLengthMm,\n        objectDistanceM: input.focusDistanceM\n      }).value.imageDistanceMm;\n    }\n    subjectImageDistanceMm = calculateThinLensImageDistance({\n      focalLengthMm: input.focalLengthMm,\n      objectDistanceM: input.subjectDistanceM\n    }).value.imageDistanceMm;\n  } catch (error) {\n    if (error instanceof InvalidScientificInputError) {\n      throw new InvalidScientificInputError(\n        \"focusDistanceM and subjectDistanceM must be beyond the focal length.\"\n      );\n    }\n    throw error;\n  }\n  // Both image distances are still resolved above, so the thin-lens domain checks\n  // and the reused-projection identity check still run.\n  void focusImageDistanceMm;\n  void subjectImageDistanceMm;\n  const apertureDiameterMm = input.focalLengthMm / input.aperture;\n  const focusDistanceMm = input.focusDistanceM * 1000;\n  const subjectDistanceMm = input.subjectDistanceM * 1000;\n\n  // Closed form of D |v_d - v_s| / v_d with v = f x / (x - f) (Gaussian thin lens):\n  //   c = f^2 |s - d| / (N d (s - f)).\n  // It avoids subtracting two nearly equal image distances (catastrophic\n  // cancellation for distant subjects) and is grouped as bounded ratios so the\n  // intermediate products cannot overflow for finite in-domain inputs.\n  const diameterMm =\n    apertureDiameterMm *\n    (Math.abs(focusDistanceMm - subjectDistanceMm) / subjectDistanceMm) *\n    (input.focalLengthMm / (focusDistanceMm - input.focalLengthMm));\n\n  return calculatedResult(\n    { diameterMm },\n    \"thin-lens-defocus-circle\",\n    \"1.1.0\",\n    [\"Geometric thin-lens model\", \"Ideal circular entrance pupil\"]\n  );\n}\n"]}

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

@@ -0,0 +1,118 @@
+/**
+ * Builds a `LensSampledPsfProfile` for an ideal, aberration-free, in-focus lens with a uniformly lit
+ * circular pupil: the Airy pattern of scalar Fraunhofer diffraction, one unit-sum kernel per declared
+ * wavelength on ONE shared sample grid (2.1.0).
+ *
+ * **Model.** The pupil diameter is D = f/N (entrance pupil = exit pupil, unity pupil magnification) and
+ * the pupil-to-image distance z is the thin-lens image distance for the focus (f at infinity), so the
+ * image-side (working) f-number is N_w = z/D. The incoherent optical transfer function (OTF) of a
+ * uniform circular pupil is the normalized autocorrelation of the pupil,
+ *   H(ρ) = (2/π)·(acos ρ − ρ·√(1 − ρ²)),  ρ = |f|/f_c ≤ 1,  f_c = 1/(λ·N_w),
+ * and the intensity PSF is its inverse Fourier transform (the Airy pattern, first zero at 1.21967·λ·N_w)
+ * (MIT OpenCourseWare 2.71 Optics, Spring 2009, lectures 21–22, free: the intensity PSF as the transform of
+ * the pupil autocorrelation and the circular-pupil MTF; also see: Goodman, Introduction to Fourier Optics,
+ * 4th ed., 2017, §6.3).
+ *
+ * **Cell integration (exact, no Bessel functions).** Kernel sample (i, j) is the PSF energy inside the
+ * square cell of side p centred on (i·p, j·p). The cell integral is the PSF convolved with the cell's
+ * indicator, evaluated at the cell centre, so in the frequency domain
+ *   K(i, j) = p² ∫∫ H(|f|/f_c)·sinc(p·f_x)·sinc(p·f_y)·cos(2π·p·i·f_x)·cos(2π·p·j·f_y) d²f,
+ * with sinc(x) = sin(πx)/(πx) (the sine terms vanish because H is even). It is evaluated in polar
+ * coordinates: a trapezoid rule in angle (exponentially convergent for this smooth periodic integrand) and
+ * Gauss–Legendre in t with ρ = 1 − t², which removes the (1 − ρ)^{3/2} edge behaviour of H. The node counts
+ * follow from the integrand's bandwidth with a fixed margin; the tests check convergence by doubling them and
+ * check the values against an independent real-space integration of `calculateIdealPolygonDiffractionPsf` in
+ * its many-blade (circular) limit. The sum of all cells is exactly 1 (Parseval), so the energy captured by
+ * the finite kernel is Σ K over its window and the truncated energy is 1 − Σ K.
+ *
+ * **Truncation and normalization.** The kernel is the (2R+1)² window of cells. The Airy tails fall only as
+ * r⁻³, so a finite window always misses some energy: it is reported per wavelength, and the window is then
+ * renormalized to unit sum because the sampled-profile contract requires unit-energy kernels. The missing
+ * tail energy is thereby put back inside the window (an approximation that slightly raises low-frequency
+ * contrast compared with the untruncated pattern).
+ *
+ * **Approximations (labelled):** scalar (no polarization), aberration-free, uniform pupil amplitude, exactly in
+ * focus (no defocus), thin lens with unity pupil magnification, the on-axis PSF used across the declared field
+ * (isoplanatic), PSF energy binned into the sample cells, finite window renormalized. Not a measured lens.
+ * @see docs/PSF_FOUNDATION.md, "Diffraction-limited sampled profile (2.1)".
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import type { FocusPlane } from "./focus-state.js";
+import { type LensSampledPsfProfile } from "./lens-psf-profile.js";
+export declare const DIFFRACTION_LIMITED_PSF_PROFILE_MODEL: Readonly<{
+    modelId: "photivra-diffraction-limited-circular-pupil-psf";
+    modelVersion: "1.0.0";
+}>;
+/** Input limits: at most 64 wavelengths, kernel radius 0–32 samples (the irradiance-convolution limit). */
+export declare const DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS: Readonly<{
+    maximumWavelengths: 64;
+    maximumKernelRadiusSamples: 32;
+}>;
+export interface CreateDiffractionLimitedPsfProfileInput {
+    /** Only `circular` in 2.1.0 (polygon pupils: `calculateIdealPolygonDiffractionPsf` gives point densities). */
+    aperture: "circular";
+    focalLengthMm: number;
+    apertureFNumber: number;
+    focus: FocusPlane;
+    /** Strictly increasing wavelengths, nm, in the medium of propagation (no air/vacuum conversion is applied). 1–64. */
+    wavelengthsNm: readonly number[];
+    /** Square sample pitch of every kernel, µm. */
+    samplePitchMicrometers: number;
+    /** Kernel half-width in samples; each kernel is (2R + 1)². 0–32. */
+    kernelRadiusSamples: number;
+    /** Half-extent of the image field over which the on-axis PSF is declared (profile field axes ±x, ±y), mm. */
+    fieldHalfExtentMm: {
+        x: number;
+        y: number;
+    };
+    profileId: string;
+}
+export interface DiffractionLimitedPsfWavelength {
+    wavelengthNm: number;
+    /** f_c = 1/(λ·N_w), cycles per µm. */
+    cutoffFrequencyCyclesPerMicrometer: number;
+    /** 1.21967·λ·N_w, µm. */
+    firstZeroRadiusMicrometers: number;
+    /** Σ of the cell energies inside the window before renormalization (of a total of 1). */
+    capturedEnergyFraction: number;
+    /** 1 − capturedEnergyFraction: the Airy tail energy outside the window, put back by renormalization. */
+    truncatedEnergyFraction: number;
+    /** Fraction of the renormalized kernel in the centre sample. */
+    centreSampleFraction: number;
+}
+export interface DiffractionLimitedPsfProfile {
+    profile: LensSampledPsfProfile;
+    model: typeof DIFFRACTION_LIMITED_PSF_PROFILE_MODEL;
+    pupilDiameterMm: number;
+    pupilToImageDistanceMm: number;
+    workingFNumber: number;
+    kernelRadiusSamples: number;
+    samplePitchMicrometers: number;
+    wavelengths: readonly DiffractionLimitedPsfWavelength[];
+    /** Largest truncated energy over the wavelengths. */
+    maximumTruncatedEnergyFraction: number;
+    quadrature: {
+        method: "polar-frequency-domain-trapezoid-gauss-legendre";
+        maximumRadialNodes: number;
+        maximumAngularNodes: number;
+    };
+}
+/**
+ * Cell energies K(i, j), 0 ≤ i, j ≤ R, of the Airy pattern for β = p·f_c (cell side in units of the cut-off
+ * period). `scale` multiplies the node counts (1 in production; the tests use 2 to check convergence).
+ */
+export declare function calculateAiryCellEnergies(beta: number, radius: number, scale?: number): {
+    cells: Float64Array;
+    radialNodes: number;
+    angularNodes: number;
+};
+/**
+ * Creates a sampled lens PSF profile for an ideal diffraction-limited lens with a circular pupil: one
+ * unit-sum Airy kernel per wavelength on one shared (2R+1)² grid, with the truncated energy reported per
+ * wavelength. The profile declares the given focal length, f-number and focus exactly, and the field axes
+ * ±`fieldHalfExtentMm` with the same kernel at every field node.
+ * @param input - See `CreateDiffractionLimitedPsfProfileInput`.
+ * @returns The profile and its diffraction record. An approximation; not a measured lens.
+ * @see docs/PSF_FOUNDATION.md, "Diffraction-limited sampled profile (2.1)".
+ */
+export declare function createDiffractionLimitedPsfProfile(input: CreateDiffractionLimitedPsfProfileInput): CalculationResult<DiffractionLimitedPsfProfile>;

package/dist/optics/diffraction-psf-profile.js

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Builds a `LensSampledPsfProfile` for an ideal, aberration-free, in-focus lens with a uniformly lit
+ * circular pupil: the Airy pattern of scalar Fraunhofer diffraction, one unit-sum kernel per declared
+ * wavelength on ONE shared sample grid (2.1.0).
+ *
+ * **Model.** The pupil diameter is D = f/N (entrance pupil = exit pupil, unity pupil magnification) and
+ * the pupil-to-image distance z is the thin-lens image distance for the focus (f at infinity), so the
+ * image-side (working) f-number is N_w = z/D. The incoherent optical transfer function (OTF) of a
+ * uniform circular pupil is the normalized autocorrelation of the pupil,
+ *   H(ρ) = (2/π)·(acos ρ − ρ·√(1 − ρ²)),  ρ = |f|/f_c ≤ 1,  f_c = 1/(λ·N_w),
+ * and the intensity PSF is its inverse Fourier transform (the Airy pattern, first zero at 1.21967·λ·N_w)
+ * (MIT OpenCourseWare 2.71 Optics, Spring 2009, lectures 21–22, free: the intensity PSF as the transform of
+ * the pupil autocorrelation and the circular-pupil MTF; also see: Goodman, Introduction to Fourier Optics,
+ * 4th ed., 2017, §6.3).
+ *
+ * **Cell integration (exact, no Bessel functions).** Kernel sample (i, j) is the PSF energy inside the
+ * square cell of side p centred on (i·p, j·p). The cell integral is the PSF convolved with the cell's
+ * indicator, evaluated at the cell centre, so in the frequency domain
+ *   K(i, j) = p² ∫∫ H(|f|/f_c)·sinc(p·f_x)·sinc(p·f_y)·cos(2π·p·i·f_x)·cos(2π·p·j·f_y) d²f,
+ * with sinc(x) = sin(πx)/(πx) (the sine terms vanish because H is even). It is evaluated in polar
+ * coordinates: a trapezoid rule in angle (exponentially convergent for this smooth periodic integrand) and
+ * Gauss–Legendre in t with ρ = 1 − t², which removes the (1 − ρ)^{3/2} edge behaviour of H. The node counts
+ * follow from the integrand's bandwidth with a fixed margin; the tests check convergence by doubling them and
+ * check the values against an independent real-space integration of `calculateIdealPolygonDiffractionPsf` in
+ * its many-blade (circular) limit. The sum of all cells is exactly 1 (Parseval), so the energy captured by
+ * the finite kernel is Σ K over its window and the truncated energy is 1 − Σ K.
+ *
+ * **Truncation and normalization.** The kernel is the (2R+1)² window of cells. The Airy tails fall only as
+ * r⁻³, so a finite window always misses some energy: it is reported per wavelength, and the window is then
+ * renormalized to unit sum because the sampled-profile contract requires unit-energy kernels. The missing
+ * tail energy is thereby put back inside the window (an approximation that slightly raises low-frequency
+ * contrast compared with the untruncated pattern).
+ *
+ * **Approximations (labelled):** scalar (no polarization), aberration-free, uniform pupil amplitude, exactly in
+ * focus (no defocus), thin lens with unity pupil magnification, the on-axis PSF used across the declared field
+ * (isoplanatic), PSF energy binned into the sample cells, finite window renormalized. Not a measured lens.
+ * @see docs/PSF_FOUNDATION.md, "Diffraction-limited sampled profile (2.1)".
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { requireAllowlistedRecord } from "../core/record-validation.js";
+import { calculateThinLensImageDistance } from "./thin-lens.js";
+import { parseLensSampledPsfProfile } from "./lens-psf-profile.js";
+export const DIFFRACTION_LIMITED_PSF_PROFILE_MODEL = Object.freeze({
+    modelId: "photivra-diffraction-limited-circular-pupil-psf", modelVersion: "1.0.0"
+});
+/** Input limits: at most 64 wavelengths, kernel radius 0–32 samples (the irradiance-convolution limit). */
+export const DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS = Object.freeze({ maximumWavelengths: 64, maximumKernelRadiusSamples: 32 });
+/** Radius of the first dark ring of the Airy pattern in units of λ·N_w: j₁,₁/π, j₁,₁ = 3.8317059702 (first zero of J₁). */
+const AIRY_FIRST_ZERO_PER_LAMBDA_N = 3.8317059702075125 / Math.PI;
+const EVIDENCE = Object.freeze([Object.freeze({ sourceOrigin: "photivra",
+        sourceReference: "photivra:diffraction-limited-psf-profile", reuseStatus: "photivra-owned" })]);
+const LIMITATIONS = Object.freeze([
+    "Scalar Fraunhofer diffraction of an ideal, uniformly lit circular pupil (Airy pattern); no aberration, apodization, polarization or stray light.",
+    "Exactly in focus: no defocus or depth of field. Thin lens with unity pupil magnification; the pupil-to-image distance is the thin-lens image distance.",
+    "The on-axis PSF is declared unchanged across the field (isoplanatic); no field-dependent aberration or pupil clipping.",
+    "PSF energy is binned into square sample cells; the finite window misses the Airy tail energy listed per wavelength and is renormalized to unit sum.",
+    "Wavelengths are used as given, in the declared basis, without air/vacuum conversion."
+]);
+function positive(value, name) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        throw new InvalidConfigurationError(name + " must be a positive finite number.");
+    return value;
+}
+/** Gauss–Legendre nodes and weights on [0, 1] (Newton iteration on Pₙ; DLMF §3.5(v)). Cached per n. */
+const GAUSS_LEGENDRE = new Map();
+function gaussLegendre(n) {
+    const cached = GAUSS_LEGENDRE.get(n);
+    if (cached)
+        return cached;
+    const nodes = new Float64Array(n), weights = new Float64Array(n);
+    for (let k = 0; k < Math.ceil(n / 2); k++) {
+        let x = Math.cos(Math.PI * (k + 0.75) / (n + 0.5));
+        for (let iteration = 0; iteration < 100; iteration++) {
+            let p0 = 1, p1 = x;
+            for (let m = 2; m <= n; m++) {
+                const p2 = ((2 * m - 1) * x * p1 - (m - 1) * p0) / m;
+                p0 = p1;
+                p1 = p2;
+            }
+            const step = p1 / (n * (x * p1 - p0) / (x * x - 1));
+            x -= step;
+            if (Math.abs(step) < 1e-16)
+                break;
+        }
+        let p0 = 1, p1 = x;
+        for (let m = 2; m <= n; m++) {
+            const p2 = ((2 * m - 1) * x * p1 - (m - 1) * p0) / m;
+            p0 = p1;
+            p1 = p2;
+        }
+        const derivative = n * (x * p1 - p0) / (x * x - 1);
+        const w = 1 / ((1 - x * x) * derivative * derivative);
+        // Map [-1, 1] to [0, 1]: t = (1 ± x)/2, weight w (2/(1-x²)P'² halved).
+        nodes[k] = (1 - x) / 2;
+        weights[k] = w;
+        nodes[n - 1 - k] = (1 + x) / 2;
+        weights[n - 1 - k] = w;
+    }
+    const result = { nodes, weights };
+    if (GAUSS_LEGENDRE.size < 64)
+        GAUSS_LEGENDRE.set(n, result);
+    return result;
+}
+function sinc(x) {
+    if (x === 0)
+        return 1;
+    const a = Math.PI * x;
+    return Math.sin(a) / a;
+}
+/**
+ * Cell energies K(i, j), 0 ≤ i, j ≤ R, of the Airy pattern for β = p·f_c (cell side in units of the cut-off
+ * period). `scale` multiplies the node counts (1 in production; the tests use 2 to check convergence).
+ */
+export function calculateAiryCellEnergies(beta, radius, scale = 1) {
+    // Bandwidth of the angular and radial integrands: c = π·β·(2R + 1)·√2 (the sinc factors and the highest cosine).
+    const c = Math.PI * beta * (2 * radius + 1) * Math.SQRT2, margin = 10 * Math.cbrt(c) + 24;
+    const quarter = Math.ceil(scale * (c + margin) / 4), radialNodes = Math.ceil(scale * (c + margin));
+    const { nodes, weights } = gaussLegendre(radialNodes), size = radius + 1, cells = new Float64Array(size * size);
+    const ca = new Float64Array(size), cb = new Float64Array(size), angularStep = (Math.PI / 2) / quarter;
+    for (let r = 0; r < radialNodes; r++) {
+        const t = nodes[r], rho = 1 - t * t;
+        // H(1 − t²) without cancellation: acos(1 − t²) = 2·asin(t/√2), ρ·√(1 − ρ²) = ρ·t·√(2 − t²).
+        const otf = (2 / Math.PI) * (2 * Math.asin(t / Math.SQRT2) - rho * t * Math.sqrt(2 - t * t));
+        // ∫₀¹ g(ρ) dρ = ∫₀¹ g(1 − t²)·2t dt; the 4 is the four symmetric quadrants of the angular trapezoid.
+        const radialWeight = weights[r] * 2 * t * rho * otf * 4 * angularStep;
+        for (let k = 0; k <= quarter; k++) {
+            const theta = k * angularStep, x = beta * rho * Math.cos(theta), y = beta * rho * Math.sin(theta);
+            const w = radialWeight * (k === 0 || k === quarter ? 0.5 : 1) * sinc(x) * sinc(y);
+            // cos(2π·i·x) and cos(2π·j·y) by the Chebyshev recurrence.
+            const cx = Math.cos(2 * Math.PI * x), cy = Math.cos(2 * Math.PI * y);
+            ca[0] = 1;
+            cb[0] = 1;
+            if (size > 1) {
+                ca[1] = cx;
+                cb[1] = cy;
+            }
+            for (let i = 2; i < size; i++) {
+                ca[i] = 2 * cx * ca[i - 1] - ca[i - 2];
+                cb[i] = 2 * cy * cb[i - 1] - cb[i - 2];
+            }
+            for (let j = 0; j < size; j++) {
+                const wj = w * cb[j];
+                for (let i = 0; i < size; i++) {
+                    const o = j * size + i;
+                    cells[o] = cells[o] + wj * ca[i];
+                }
+            }
+        }
+    }
+    const area = beta * beta;
+    for (let i = 0; i < cells.length; i++)
+        cells[i] = cells[i] * area;
+    return { cells, radialNodes, angularNodes: 4 * quarter };
+}
+/**
+ * Creates a sampled lens PSF profile for an ideal diffraction-limited lens with a circular pupil: one
+ * unit-sum Airy kernel per wavelength on one shared (2R+1)² grid, with the truncated energy reported per
+ * wavelength. The profile declares the given focal length, f-number and focus exactly, and the field axes
+ * ±`fieldHalfExtentMm` with the same kernel at every field node.
+ * @param input - See `CreateDiffractionLimitedPsfProfileInput`.
+ * @returns The profile and its diffraction record. An approximation; not a measured lens.
+ * @see docs/PSF_FOUNDATION.md, "Diffraction-limited sampled profile (2.1)".
+ */
+export function createDiffractionLimitedPsfProfile(input) {
+    const r = requireAllowlistedRecord(input, ["aperture", "focalLengthMm", "apertureFNumber", "focus", "wavelengthsNm", "samplePitchMicrometers",
+        "kernelRadiusSamples", "fieldHalfExtentMm", "profileId"], "Invalid diffraction-limited PSF profile input.");
+    if (r.aperture !== "circular")
+        throw new InvalidConfigurationError("aperture must be \"circular\".");
+    const focalLengthMm = positive(r.focalLengthMm, "focalLengthMm"), fNumber = positive(r.apertureFNumber, "apertureFNumber");
+    const pitch = positive(r.samplePitchMicrometers, "samplePitchMicrometers");
+    const L = DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS;
+    const radius = r.kernelRadiusSamples;
+    if (typeof radius !== "number" || !Number.isSafeInteger(radius) || radius < 0 || radius > L.maximumKernelRadiusSamples) {
+        throw new InvalidConfigurationError("kernelRadiusSamples must be an integer from 0 to " + L.maximumKernelRadiusSamples + ".");
+    }
+    const focus = requireAllowlistedRecord(r.focus, ["kind", "distanceM"], "Invalid focus.");
+    let focusDiopters, distanceMm;
+    if (focus.kind === "infinity") {
+        if (focus.distanceM !== undefined)
+            throw new InvalidConfigurationError("An infinity focus has no distanceM.");
+        focusDiopters = 0;
+        distanceMm = focalLengthMm;
+    }
+    else if (focus.kind === "finite") {
+        const distanceM = positive(focus.distanceM, "focus.distanceM");
+        focusDiopters = 1 / distanceM;
+        distanceMm = calculateThinLensImageDistance({ focalLengthMm, objectDistanceM: distanceM }).value.imageDistanceMm;
+    }
+    else
+        throw new InvalidConfigurationError("focus.kind must be finite or infinity.");
+    const field = requireAllowlistedRecord(r.fieldHalfExtentMm, ["x", "y"], "Invalid fieldHalfExtentMm.");
+    const fieldX = positive(field.x, "fieldHalfExtentMm.x"), fieldY = positive(field.y, "fieldHalfExtentMm.y");
+    const list = r.wavelengthsNm;
+    if (!Array.isArray(list) || list.length < 1 || list.length > L.maximumWavelengths)
+        throw new InvalidConfigurationError("wavelengthsNm must list 1 to 64 wavelengths.");
+    const wavelengths = list.map((value, index) => positive(value, "wavelengthsNm[" + index + "]"));
+    for (let i = 1; i < wavelengths.length; i++)
+        if (!(wavelengths[i] > wavelengths[i - 1]))
+            throw new InvalidConfigurationError("wavelengthsNm must be strictly increasing.");
+    if (typeof r.profileId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(r.profileId))
+        throw new InvalidConfigurationError("profileId must be a public opaque ID.");
+    const pupilDiameterMm = focalLengthMm / fNumber, workingFNumber = distanceMm / pupilDiameterMm, size = 2 * radius + 1;
+    let maximumRadialNodes = 0, maximumAngularNodes = 0, maximumTruncated = 0;
+    const records = [], kernels = [];
+    for (const nm of wavelengths) {
+        const lambdaN = nm / 1000 * workingFNumber, cutoff = 1 / lambdaN;
+        const airy = calculateAiryCellEnergies(pitch * cutoff, radius);
+        maximumRadialNodes = Math.max(maximumRadialNodes, airy.radialNodes);
+        maximumAngularNodes = Math.max(maximumAngularNodes, airy.angularNodes);
+        const values = new Array(size * size);
+        let captured = 0;
+        for (let ky = 0; ky < size; ky++)
+            for (let kx = 0; kx < size; kx++) {
+                const value = airy.cells[Math.abs(ky - radius) * (radius + 1) + Math.abs(kx - radius)];
+                // Every cell energy of a non-negative PSF is positive; a negative value would be a quadrature failure.
+                if (!(value > -1e-13))
+                    throw new InvalidConfigurationError("Diffraction cell integration failed to converge.");
+                values[ky * size + kx] = Math.max(0, value);
+                captured += values[ky * size + kx];
+            }
+        if (!(captured > 0 && captured <= 1 + 1e-9))
+            throw new InvalidConfigurationError("Diffraction cell integration failed to converge.");
+        const truncated = Math.max(0, 1 - captured);
+        maximumTruncated = Math.max(maximumTruncated, truncated);
+        const kernel = values.map((v) => v / captured);
+        kernels.push(kernel);
+        records.push({ wavelengthNm: nm, cutoffFrequencyCyclesPerMicrometer: cutoff, firstZeroRadiusMicrometers: AIRY_FIRST_ZERO_PER_LAMBDA_N * lambdaN,
+            capturedEnergyFraction: captured, truncatedEnergyFraction: truncated, centreSampleFraction: kernel[radius * size + radius] });
+    }
+    const uncertainty = { kind: "not-quantified", limitation: "Ideal diffraction-limited model; no measured lens or quadrature error bound." };
+    const nodes = [-fieldX, fieldX].flatMap((fx) => [-fieldY, fieldY].flatMap((fy) => wavelengths.map((nm, index) => ({
+        nodeId: "airy-" + (fx < 0 ? "xm" : "xp") + "-" + (fy < 0 ? "ym" : "yp") + "-" + index,
+        coordinate: { focalLengthMm, focusDiopters, apertureFNumber: fNumber, fieldXmm: fx, fieldYmm: fy, wavelengthNm: nm, signedDefocusImagePlaneMicrometers: 0 },
+        kernel: { widthSamples: size, heightSamples: size, samplePitchMicrometersX: pitch, samplePitchMicrometersY: pitch, centerSampleX: radius, centerSampleY: radius,
+            normalizedIntensity: kernels[index] },
+        bestFocusImagePlaneOffsetMicrometers: 0, relativePupilThroughputFactor: 1, evidence: EVIDENCE, uncertainty
+    }))));
+    const profile = parseLensSampledPsfProfile({ schemaVersion: "0.1.0", profileId: r.profileId, profileVersion: DIFFRACTION_LIMITED_PSF_PROFILE_MODEL.modelVersion,
+        scientificStatus: "approximation", opticalDomain: "lens-primary-optical-path-only", coordinateSystem: "image-plane-metric", fieldAxes: "+X right, +Y up",
+        kernelEnergyNormalization: "unit-energy-shape", interpolation: "bounded-regular-grid-multilinear", throughputOwnership: "separate-relative-pupil-throughput-factor",
+        responseIncludes: { diffraction: true, aberration: false, defocus: false, pupilClippingShape: false },
+        sensorOpticalStackIncluded: false, sensorSamplingIncluded: false, reconstructionIncluded: false, strayLightIncluded: false,
+        axes: { focalLengthMm: [focalLengthMm], focusDiopters: [focusDiopters], apertureFNumber: [fNumber], fieldXmm: [-fieldX, fieldX], fieldYmm: [-fieldY, fieldY],
+            wavelengthNm: wavelengths, signedDefocusImagePlaneMicrometers: [0] },
+        nodes, evidence: EVIDENCE, limitations: [...LIMITATIONS] });
+    return approximationResult({ profile, model: DIFFRACTION_LIMITED_PSF_PROFILE_MODEL, pupilDiameterMm, pupilToImageDistanceMm: distanceMm, workingFNumber,
+        kernelRadiusSamples: radius, samplePitchMicrometers: pitch, wavelengths: records, maximumTruncatedEnergyFraction: maximumTruncated,
+        quadrature: { method: "polar-frequency-domain-trapezoid-gauss-legendre", maximumRadialNodes, maximumAngularNodes } }, DIFFRACTION_LIMITED_PSF_PROFILE_MODEL.modelId, DIFFRACTION_LIMITED_PSF_PROFILE_MODEL.modelVersion, [...LIMITATIONS]);
+}
+//# sourceMappingURL=diffraction-psf-profile.js.map