@photivra/engine 1.5.0 → 2.0.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":"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","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.d.ts

@@ -1,10 +1,11 @@
 /**
- * Module boundary and integration notes.
- * Calculates the first-zero Airy-disk diameter for an ideal circular aperture. This uses the
- * established diffraction relation d = 2.44 * lambda * N. It is an independent implementation of the
- * mathematical relation and does not model lens aberrations or non-circular pupil geometry.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Diameter of the Airy disk (the central diffraction spot) out to its first dark ring, for an ideal
+ * circular aperture. It uses the standard relation d = 2.44 * lambda * N.
+ *
+ * This is an independent implementation of that relation. It does not model lens aberrations or
+ * non-circular pupils.
+ * @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 CalculateAiryDiskInput {
@@ -15,20 +16,20 @@ export interface CalculateAiryDiskInput {
 }
 export interface AiryDisk {
     /**
-     * Diameter from the center of the diffraction pattern to the first dark-ring
-     * diameter, in micrometres: 2.44 * wavelength * f-number.
+     * Diameter of the first dark ring of the diffraction pattern, in
+     * micrometres: 2.44 * wavelength * f-number.
      */
     firstZeroDiameterMicrometers: number;
 }
 /**
- * Calculates the first-zero Airy-disk diameter for an ideal circular aperture.
+ * Calculates the Airy-disk diameter to the first dark ring for an ideal
+ * circular aperture.
  *
- * This uses the established diffraction relation d = 2.44 * lambda * N.
- * It is an independent implementation of the mathematical relation and does
- * not model lens aberrations or non-circular pupil geometry.
+ * It uses the standard diffraction relation d = 2.44 * lambda * N. This is an
+ * independent implementation of that relation. It does not model lens
+ * aberrations or non-circular pupils.
  *
  * @param input F-number and wavelength.
  * @returns Diffraction diameter at the image plane.
  */
 export declare function calculateAiryDisk(input: CalculateAiryDiskInput): CalculationResult<AiryDisk>;
-//# sourceMappingURL=diffraction.d.ts.map

package/dist/optics/diffraction.js

@@ -1,25 +1,29 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates the first-zero Airy-disk diameter for an ideal circular aperture. This uses the
- * established diffraction relation d = 2.44 * lambda * N. It is an independent implementation of the
- * mathematical relation and does not model lens aberrations or non-circular pupil geometry.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Diameter of the Airy disk (the central diffraction spot) out to its first dark ring, for an ideal
+ * circular aperture. It uses the standard relation d = 2.44 * lambda * N.
+ *
+ * This is an independent implementation of that relation. It does not model lens aberrations or
+ * non-circular pupils.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { calculatedResult } from "../core/calculation-result.js";
 import { requirePositiveFinite } from "../core/validation.js";
+import { requireInputKeys } from "../core/record-validation.js";
 /**
- * Calculates the first-zero Airy-disk diameter for an ideal circular aperture.
+ * Calculates the Airy-disk diameter to the first dark ring for an ideal
+ * circular aperture.
  *
- * This uses the established diffraction relation d = 2.44 * lambda * N.
- * It is an independent implementation of the mathematical relation and does
- * not model lens aberrations or non-circular pupil geometry.
+ * It uses the standard diffraction relation d = 2.44 * lambda * N. This is an
+ * independent implementation of that relation. It does not model lens
+ * aberrations or non-circular pupils.
  *
  * @param input F-number and wavelength.
  * @returns Diffraction diameter at the image plane.
  */
 export function calculateAiryDisk(input) {
+    requireInputKeys(input, "calculateAiryDisk", ["aperture", "wavelengthNm"]);
     requirePositiveFinite("aperture", input.aperture);
     requirePositiveFinite("wavelengthNm", input.wavelengthNm);
     return calculatedResult({

package/dist/optics/diffraction.js.map

@@ -1 +1 @@
-{"version":3,"file":"diffraction.js","sourceRoot":"","sources":["../../src/optics/diffraction.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;GAOG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAiB9D;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA6B;IAE7B,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,cAAc,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAE1D,OAAO,gBAAgB,CACrB;QACE,4BAA4B,EAC1B,IAAI,GAAG,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,QAAQ;KACtD,EACD,mCAAmC,EACnC,OAAO,EACP,CAAC,yBAAyB,EAAE,0BAA0B,CAAC,CACxD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"diffraction.js","sourceRoot":"","sources":["../../src/optics/diffraction.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;GAQG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAiBhE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAA6B;IAE7B,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,EAAE,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;IAC3E,qBAAqB,CAAC,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IAClD,qBAAqB,CAAC,cAAc,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;IAE1D,OAAO,gBAAgB,CACrB;QACE,4BAA4B,EAC1B,IAAI,GAAG,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC,QAAQ;KACtD,EACD,mCAAmC,EACnC,OAAO,EACP,CAAC,yBAAyB,EAAE,0BAA0B,CAAC,CACxD,CAAC;AACJ,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Diameter of the Airy disk (the central diffraction spot) out to its first dark ring, for an ideal\n * circular aperture. It uses the standard relation d = 2.44 * lambda * N.\n *\n * This is an independent implementation of that relation. It does not model lens aberrations or\n * non-circular pupils.\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 { requirePositiveFinite } from \"../core/validation.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\nexport interface CalculateAiryDiskInput {\n  /** F-number. */\n  aperture: number;\n  /** Wavelength in nanometres. Defaults are intentionally left to callers. */\n  wavelengthNm: number;\n}\n\nexport interface AiryDisk {\n  /**\n   * Diameter of the first dark ring of the diffraction pattern, in\n   * micrometres: 2.44 * wavelength * f-number.\n   */\n  firstZeroDiameterMicrometers: number;\n}\n\n/**\n * Calculates the Airy-disk diameter to the first dark ring for an ideal\n * circular aperture.\n *\n * It uses the standard diffraction relation d = 2.44 * lambda * N. This is an\n * independent implementation of that relation. It does not model lens\n * aberrations or non-circular pupils.\n *\n * @param input F-number and wavelength.\n * @returns Diffraction diameter at the image plane.\n */\nexport function calculateAiryDisk(\n  input: CalculateAiryDiskInput\n): CalculationResult<AiryDisk> {\n  requireInputKeys(input, \"calculateAiryDisk\", [\"aperture\", \"wavelengthNm\"]);\n  requirePositiveFinite(\"aperture\", input.aperture);\n  requirePositiveFinite(\"wavelengthNm\", input.wavelengthNm);\n\n  return calculatedResult(\n    {\n      firstZeroDiameterMicrometers:\n        2.44 * (input.wavelengthNm / 1000) * input.aperture\n    },\n    \"ideal-circular-aperture-airy-disk\",\n    \"1.0.0\",\n    [\"Ideal circular aperture\", \"Monochromatic wavelength\"]\n  );\n}\n"]}

package/dist/optics/focus-breathing.d.ts

@@ -1,15 +1,19 @@
 /**
- * Module boundary and integration notes.
- * Applies a caller-declared focus-breathing projection scale to the ideal Gaussian thin-lens
- * projection for one focus state. Photivra does not infer the scale from focal length, focus distance,
- * lens identity, or marketing data. A value of 1 exactly preserves the current thin-lens projection.
- * This is a generic approximation of focus-dependent projection/magnification, not a calibrated
- * real-lens model. The physical focal length remains authoritative and unchanged.
- * Calculates one-axis field of view for the generic declared-scale focus- breathing projection and
- * reports the corresponding ideal thin-lens FOV. A breathingProjectionScale of 1 reproduces the
- * current focus-aware thin-lens field-of-view result exactly.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Focus breathing: the change in framing (magnification) as a lens focuses.
+ *
+ * The declared-scale model applies a caller-supplied projection scale to the ideal Gaussian thin-lens
+ * projection for one focus state. Photivra does not guess the scale from focal length, focus
+ * distance, lens identity or marketing data. A scale of 1 keeps the thin-lens projection exactly.
+ * This is a generic approximation of how projection and magnification change with focus. It is not a
+ * calibrated real-lens model. The physical focal length is never changed and stays authoritative.
+ *
+ * The field-of-view function gives the one-axis field of view (FOV) under this model, and the ideal
+ * thin-lens FOV for comparison. A breathingProjectionScale of 1 reproduces the focus-aware thin-lens
+ * FOV exactly.
+ *
+ * The geometric model derives breathing from ideal focusing geometry instead of a declared scale.
+ * @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 CalculateFocusBreathingProjectionInput {
@@ -21,9 +25,9 @@ export interface CalculateFocusBreathingProjectionInput {
      * Caller-declared projection scale for this focus state, relative to the
      * ideal thin-lens image distance.
      *
-     * 1 means no additional breathing relative to the current thin-lens model.
-     * Values above 1 narrow framing / increase magnification; values below 1
-     * widen framing / reduce magnification.
+     * 1 means no breathing beyond the thin-lens model. Values above 1 narrow the
+     * framing (more magnification). Values below 1 widen it (less
+     * magnification).
      */
     breathingProjectionScale: number;
 }
@@ -36,8 +40,8 @@ export interface FocusBreathingProjection {
     /**
      * Effective projection distance used by the generic breathing model.
      *
-     * This is a projection/magnification parameter, not a replacement physical
-     * focal length.
+     * This is a projection (magnification) parameter. It does not replace the
+     * physical focal length.
      */
     effectiveProjectionDistanceMm: number;
     /** Caller-declared scale relative to ideal thin-lens projection. */
@@ -66,21 +70,78 @@ export interface FocusBreathingFieldOfView {
  * Applies a caller-declared focus-breathing projection scale to the ideal
  * Gaussian thin-lens projection for one focus state.
  *
- * Photivra does not infer the scale from focal length, focus distance, lens
- * identity, or marketing data. A value of 1 exactly preserves the current
- * thin-lens projection.
+ * Photivra does not guess the scale from focal length, focus distance, lens
+ * identity or marketing data. A scale of 1 keeps the thin-lens projection
+ * exactly.
  *
- * This is a generic approximation of focus-dependent projection/magnification,
- * not a calibrated real-lens model. The physical focal length remains
- * authoritative and unchanged.
+ * This is a generic approximation of how projection and magnification change
+ * with focus. It is not a calibrated real-lens model. The physical focal
+ * length is never changed and stays authoritative.
  */
 export declare function calculateFocusBreathingProjection(input: CalculateFocusBreathingProjectionInput): CalculationResult<FocusBreathingProjection>;
 /**
- * Calculates one-axis field of view for the generic declared-scale focus-
- * breathing projection and reports the corresponding ideal thin-lens FOV.
+ * Calculates the one-axis field of view under the declared-scale
+ * focus-breathing model, and reports the ideal thin-lens field of view for
+ * comparison.
  *
- * A breathingProjectionScale of 1 reproduces the current focus-aware
- * thin-lens field-of-view result exactly.
+ * A breathingProjectionScale of 1 reproduces the focus-aware thin-lens field
+ * of view exactly.
  */
 export declare function calculateFocusBreathingFieldOfView(input: CalculateFocusBreathingFieldOfViewInput): CalculationResult<FocusBreathingFieldOfView>;
-//# sourceMappingURL=focus-breathing.d.ts.map
+/** Ideal focusing geometry for {@link calculateGeometricFocusBreathing}. */
+export type GeometricFocusingMethod = "unit-focus" | "fixed-image-distance-internal-focus";
+export interface CalculateGeometricFocusBreathingInput {
+    /** Focal length at infinity focus, mm. */
+    focalLengthMm: number;
+    /**
+     * Photographic focus distance measured from the subject plane to the sensor (image) plane, in
+     * metres, as marked on lens distance scales.
+     */
+    subjectToSensorDistanceM: number;
+    /** Sensor/capture dimension along the axis of interest, mm. */
+    sensorDimensionMm: number;
+    focusingMethod: GeometricFocusingMethod;
+    /**
+     * Signed distance between the front and rear principal planes (the "hiatus"), in mm. Default 0
+     * (thin lens). The subject-to-sensor distance is u + hiatus + v.
+     */
+    principalPlaneSeparationMm?: number;
+}
+export interface GeometricFocusBreathing {
+    focusingMethod: GeometricFocusingMethod;
+    infinityFocalLengthMm: number;
+    /** Focal length of the focused system (changes only for internal focus), mm. */
+    effectiveFocalLengthMm: number;
+    /** Subject distance from the front principal plane, mm. */
+    objectDistanceMm: number;
+    /** Rear principal plane to sensor distance (projection distance), mm. */
+    imageDistanceMm: number;
+    /** Lateral magnification v / u. */
+    magnification: number;
+    /** v / f_infinity: framing scale relative to infinity focus. */
+    projectionScaleRelativeToInfinity: number;
+    /**
+     * v divided by the ideal thin-lens image distance, at objectDistanceMm, of a lens with the same
+     * infinity focal length. Exactly 1 for unit focus. You can pass it as breathingProjectionScale to
+     * calculateFocusBreathingProjection() with focusDistanceM = objectDistanceMm / 1000.
+     */
+    equivalentBreathingProjectionScale: number;
+    fieldOfViewDegrees: number;
+    infinityFieldOfViewDegrees: number;
+    deltaDegrees: number;
+}
+/**
+ * Focus breathing derived from ideal focusing geometry, instead of a declared scale.
+ *
+ * - unit-focus: the whole lens moves. u + v = L - hiatus and 1/u + 1/v = 1/f, so
+ *   v = (T - sqrt(T^2 - 4 f T)) / 2, where T = L - hiatus >= 4 f. The field narrows as v grows.
+ * - fixed-image-distance-internal-focus: an idealised internal-focus lens keeps the rear principal
+ *   plane at v = f_infinity and shortens its focal length to f' = u v / (u + v). The angular field
+ *   at the rear nodal point then stays the same, and the magnification is f_infinity / u.
+ * Both use paraxial Gaussian optics with the nodal points at the principal planes (unit pupil
+ * magnification; Greivenkamp, OPTI-502 course notes, University of Arizona, sec. 3 and 5, free. Also
+ * see: Kingslake & Johnson, Lens Design Fundamentals, 2nd ed., ch. 3; Ray, Applied Photographic
+ * Optics, 3rd ed., ch. 9 and 14). Real internal-focus lenses also move their pupils and
+ * principal planes, so modelling their breathing needs a calibrated profile.
+ */
+export declare function calculateGeometricFocusBreathing(input: CalculateGeometricFocusBreathingInput): CalculationResult<GeometricFocusBreathing>;

package/dist/optics/focus-breathing.js

@@ -1,33 +1,40 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Applies a caller-declared focus-breathing projection scale to the ideal Gaussian thin-lens
- * projection for one focus state. Photivra does not infer the scale from focal length, focus distance,
- * lens identity, or marketing data. A value of 1 exactly preserves the current thin-lens projection.
- * This is a generic approximation of focus-dependent projection/magnification, not a calibrated
- * real-lens model. The physical focal length remains authoritative and unchanged.
- * Calculates one-axis field of view for the generic declared-scale focus- breathing projection and
- * reports the corresponding ideal thin-lens FOV. A breathingProjectionScale of 1 reproduces the
- * current focus-aware thin-lens field-of-view result exactly.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Focus breathing: the change in framing (magnification) as a lens focuses.
+ *
+ * The declared-scale model applies a caller-supplied projection scale to the ideal Gaussian thin-lens
+ * projection for one focus state. Photivra does not guess the scale from focal length, focus
+ * distance, lens identity or marketing data. A scale of 1 keeps the thin-lens projection exactly.
+ * This is a generic approximation of how projection and magnification change with focus. It is not a
+ * calibrated real-lens model. The physical focal length is never changed and stays authoritative.
+ *
+ * The field-of-view function gives the one-axis field of view (FOV) under this model, and the ideal
+ * thin-lens FOV for comparison. A breathingProjectionScale of 1 reproduces the focus-aware thin-lens
+ * FOV exactly.
+ *
+ * The geometric model derives breathing from ideal focusing geometry instead of a declared scale.
+ * @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 { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
 import { calculateThinLensImageDistance } from "./thin-lens.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 /**
  * Applies a caller-declared focus-breathing projection scale to the ideal
  * Gaussian thin-lens projection for one focus state.
  *
- * Photivra does not infer the scale from focal length, focus distance, lens
- * identity, or marketing data. A value of 1 exactly preserves the current
- * thin-lens projection.
+ * Photivra does not guess the scale from focal length, focus distance, lens
+ * identity or marketing data. A scale of 1 keeps the thin-lens projection
+ * exactly.
  *
- * This is a generic approximation of focus-dependent projection/magnification,
- * not a calibrated real-lens model. The physical focal length remains
- * authoritative and unchanged.
+ * This is a generic approximation of how projection and magnification change
+ * with focus. It is not a calibrated real-lens model. The physical focal
+ * length is never changed and stays authoritative.
  */
 export function calculateFocusBreathingProjection(input) {
+    requireInputKeys(input, "calculateFocusBreathingProjection", ["focalLengthMm", "focusDistanceM", "breathingProjectionScale"]);
     requirePositiveFinite("focalLengthMm", input.focalLengthMm);
     requirePositiveFinite("focusDistanceM", input.focusDistanceM);
     requirePositiveFinite("breathingProjectionScale", input.breathingProjectionScale);
@@ -55,15 +62,21 @@ export function calculateFocusBreathingProjection(input) {
     ]);
 }
 /**
- * Calculates one-axis field of view for the generic declared-scale focus-
- * breathing projection and reports the corresponding ideal thin-lens FOV.
+ * Calculates the one-axis field of view under the declared-scale
+ * focus-breathing model, and reports the ideal thin-lens field of view for
+ * comparison.
  *
- * A breathingProjectionScale of 1 reproduces the current focus-aware
- * thin-lens field-of-view result exactly.
+ * A breathingProjectionScale of 1 reproduces the focus-aware thin-lens field
+ * of view exactly.
  */
 export function calculateFocusBreathingFieldOfView(input) {
+    requireInputKeys(input, "calculateFocusBreathingFieldOfView", ["sensorDimensionMm", "focalLengthMm", "focusDistanceM", "breathingProjectionScale"]);
     requirePositiveFinite("sensorDimensionMm", input.sensorDimensionMm);
-    const projection = calculateFocusBreathingProjection(input);
+    const projection = calculateFocusBreathingProjection({
+        focalLengthMm: input.focalLengthMm,
+        focusDistanceM: input.focusDistanceM,
+        breathingProjectionScale: input.breathingProjectionScale
+    });
     const idealRadians = 2 *
         Math.atan(input.sensorDimensionMm /
             (2 * projection.value.idealProjectionDistanceMm));
@@ -87,4 +100,82 @@ export function calculateFocusBreathingFieldOfView(input) {
         "Rectilinear field of view is calculated from the declared sensor/capture dimension and effective projection distance"
     ]);
 }
+/**
+ * Focus breathing derived from ideal focusing geometry, instead of a declared scale.
+ *
+ * - unit-focus: the whole lens moves. u + v = L - hiatus and 1/u + 1/v = 1/f, so
+ *   v = (T - sqrt(T^2 - 4 f T)) / 2, where T = L - hiatus >= 4 f. The field narrows as v grows.
+ * - fixed-image-distance-internal-focus: an idealised internal-focus lens keeps the rear principal
+ *   plane at v = f_infinity and shortens its focal length to f' = u v / (u + v). The angular field
+ *   at the rear nodal point then stays the same, and the magnification is f_infinity / u.
+ * Both use paraxial Gaussian optics with the nodal points at the principal planes (unit pupil
+ * magnification; Greivenkamp, OPTI-502 course notes, University of Arizona, sec. 3 and 5, free. Also
+ * see: Kingslake & Johnson, Lens Design Fundamentals, 2nd ed., ch. 3; Ray, Applied Photographic
+ * Optics, 3rd ed., ch. 9 and 14). Real internal-focus lenses also move their pupils and
+ * principal planes, so modelling their breathing needs a calibrated profile.
+ */
+export function calculateGeometricFocusBreathing(input) {
+    requireInputKeys(input, "calculateGeometricFocusBreathing", ["focalLengthMm", "subjectToSensorDistanceM", "sensorDimensionMm", "focusingMethod", "principalPlaneSeparationMm"]);
+    requirePositiveFinite("focalLengthMm", input.focalLengthMm);
+    requirePositiveFinite("subjectToSensorDistanceM", input.subjectToSensorDistanceM);
+    requirePositiveFinite("sensorDimensionMm", input.sensorDimensionMm);
+    const hiatus = input.principalPlaneSeparationMm ?? 0;
+    if (typeof hiatus !== "number" || !Number.isFinite(hiatus)) {
+        throw new InvalidScientificInputError("principalPlaneSeparationMm must be finite.");
+    }
+    const f = input.focalLengthMm;
+    const conjugateSum = input.subjectToSensorDistanceM * 1000 - hiatus;
+    let imageDistanceMm;
+    let objectDistanceMm;
+    let effectiveFocalLengthMm;
+    if (input.focusingMethod === "unit-focus") {
+        if (!(conjugateSum >= 4 * f)) {
+            throw new InvalidScientificInputError("Unit focus requires subject-to-sensor distance minus hiatus of at least 4 x focal length (1:1 limit).");
+        }
+        // Stable smaller root of v^2 - T v + f T = 0: v = 2 f T / (T + sqrt(T^2 - 4 f T)).
+        imageDistanceMm =
+            (2 * f * conjugateSum) /
+                (conjugateSum + Math.sqrt(conjugateSum * conjugateSum - 4 * f * conjugateSum));
+        objectDistanceMm = conjugateSum - imageDistanceMm;
+        effectiveFocalLengthMm = f;
+    }
+    else if (input.focusingMethod === "fixed-image-distance-internal-focus") {
+        imageDistanceMm = f;
+        objectDistanceMm = conjugateSum - f;
+        if (!(objectDistanceMm > f)) {
+            throw new InvalidScientificInputError("Internal focus requires the subject to lie more than one focal length in front of the lens.");
+        }
+        effectiveFocalLengthMm = (objectDistanceMm * f) / (objectDistanceMm + f);
+    }
+    else {
+        throw new InvalidConfigurationError("focusingMethod must be unit-focus or fixed-image-distance-internal-focus.");
+    }
+    const thinLens = calculateThinLensImageDistance({
+        focalLengthMm: f,
+        objectDistanceM: objectDistanceMm / 1000
+    }).value.imageDistanceMm;
+    const fov = (projection) => (2 * Math.atan(input.sensorDimensionMm / (2 * projection)) * 180) / Math.PI;
+    const fieldOfViewDegrees = fov(imageDistanceMm);
+    const infinityFieldOfViewDegrees = fov(f);
+    return approximationResult({
+        focusingMethod: input.focusingMethod,
+        infinityFocalLengthMm: f,
+        effectiveFocalLengthMm,
+        objectDistanceMm,
+        imageDistanceMm,
+        magnification: imageDistanceMm / objectDistanceMm,
+        projectionScaleRelativeToInfinity: imageDistanceMm / f,
+        equivalentBreathingProjectionScale: input.focusingMethod === "unit-focus" ? 1 : imageDistanceMm / thinLens,
+        fieldOfViewDegrees,
+        infinityFieldOfViewDegrees,
+        deltaDegrees: fieldOfViewDegrees - infinityFieldOfViewDegrees
+    }, "geometric-focus-breathing", "1.0.0", [
+        "Paraxial Gaussian optics with nodal points at the principal planes (unit pupil magnification)",
+        input.focusingMethod === "unit-focus"
+            ? "Unit focus: the whole lens moves; focal length is constant"
+            : "Idealised internal focus: image distance fixed at the infinity focal length; focal length shortens",
+        "Subject-to-sensor distance = object distance + principal-plane separation + image distance",
+        "Rectilinear field of view from the rear-principal-plane projection distance; distortion, pupil shifts and named-lens behaviour are not modeled"
+    ]);
+}
 //# sourceMappingURL=focus-breathing.js.map