@photivra/engine 1.4.0 → 2.0.0

package/dist/optics/longitudinal-chromatic-aberration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"longitudinal-chromatic-aberration.js","sourceRoot":"","sources":["../../src/optics/longitudinal-chromatic-aberration.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Longitudinal (axial) chromatic aberration: wavelength-dependent focal length and the resulting\n * per-wavelength image-plane defocus for a sensor focused at a reference wavelength.\n *\n * Two dispersion inputs:\n * - thin-singlet-abbe: an ideal thin singlet whose index follows a two-term Cauchy dispersion\n *   n(lambda) = A + B / lambda^2 fitted to n_d and the Abbe number V_d = (n_d - 1) / (n_F - n_C)\n *   (Cauchy 1836; Oh 2023, arXiv:2309.09375, sec. 2.3.1(b), free; Abbe number: Greivenkamp,\n *   OPTI-502 course notes, University of Arizona, sec. 17, free. Also see: Born & Wolf, Principles\n *   of Optics, sec. 2.3; Hecht, Optics, 5th ed., sec. 3.5 and 6.3). Lensmaker scaling gives\n *   f(lambda) = f_ref (n_ref - 1) / (n(lambda) - 1), so f_C - f_F ~ f_d / V_d (Greivenkamp,\n *   OPTI-502 course notes, sec. 20, free. Also see: Hecht sec. 6.3.2; Kingslake & Johnson, Lens\n *   Design Fundamentals, 2nd ed., ch. 5). The Fraunhofer d, F and C wavelengths (587.5618, 486.1327, 656.2725 nm) are standard\n *   spectral-line constants (SCHOTT Technical Information TIE-29, 2023, free; also specified in\n *   ISO 7944). A real multi-element lens is not a singlet, so this is an educational\n *   approximation.\n * - declared-focal-shift: a caller-supplied table of focal-length shift versus wavelength\n *   (for example a corrected lens's secondary spectrum), interpolated linearly without extrapolation.\n *\n * How defocus is computed:\n * - The sensor sits at the Gaussian thin-lens image distance for focusDistanceM at the reference\n *   wavelength.\n * - At each wavelength, the image distance of subjectDistanceM uses f(lambda).\n * - The signed image-plane defocus dz is the sensor distance minus that image distance.\n * - The geometric blur diameter is D |dz| / v(lambda), where D = f_ref / N is the entrance-pupil\n *   diameter. This is the same thin-lens form as calculateDefocusCircle().\n * The defocus also feeds calculateDefocusWavefront(), so a complex-pupil PSF (point-spread function)\n * can be evaluated per wavelength.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport { calculateDefocusWavefront } from \"./zernike-wavefront.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\n/** Fraunhofer spectral-line wavelengths in nm (SCHOTT TIE-29 table; also ISO 7944 reference wavelengths). */\nexport const FRAUNHOFER_D_LINE_NM = 587.5618;\nexport const FRAUNHOFER_F_LINE_NM = 486.1327;\nexport const FRAUNHOFER_C_LINE_NM = 656.2725;\n\nconst CAUCHY_MINIMUM_WAVELENGTH_NM = 360;\nconst CAUCHY_MAXIMUM_WAVELENGTH_NM = 830;\n\nexport type LongitudinalChromaticDispersion =\n  | {\n      kind: \"thin-singlet-abbe\";\n      /** Refractive index at the d line. */\n      refractiveIndexD: number;\n      /** Abbe number V_d = (n_d - 1) / (n_F - n_C). */\n      abbeNumberD: number;\n    }\n  | {\n      kind: \"declared-focal-shift\";\n      /** Strictly increasing wavelengths; shift is f(lambda) - f_nominal in micrometres. */\n      samples: readonly {\n        wavelengthNm: number;\n        focalLengthShiftMicrometers: number;\n      }[];\n    };\n\nexport interface CalculateLongitudinalChromaticFocusInput {\n  /** Focal length at the reference wavelength, in mm. */\n  focalLengthMm: number;\n  /** Wavelength at which the sensor is focused, in nm. */\n  referenceWavelengthNm: number;\n  /** Wavelength to evaluate, in nm (same wavelength basis as the dispersion data). */\n  wavelengthNm: number;\n  /** Nominal f-number at the reference wavelength (entrance-pupil diameter = f / N). */\n  apertureFNumber: number;\n  /** Focus (object) distance at the reference wavelength, metres from the principal plane. */\n  focusDistanceM: number;\n  /** Subject distance in metres; defaults to focusDistanceM. */\n  subjectDistanceM?: number;\n  dispersion: LongitudinalChromaticDispersion;\n}\n\nexport interface LongitudinalChromaticFocus {\n  wavelengthNm: number;\n  referenceWavelengthNm: number;\n  focalLengthAtWavelengthMm: number;\n  /** f(lambda) - f(reference), micrometres. */\n  focalShiftMicrometers: number;\n  /** Sensor plane distance (reference-wavelength image of the focus plane), mm. */\n  sensorImageDistanceMm: number;\n  /** Image distance of the subject at this wavelength, mm. */\n  imageDistanceAtWavelengthMm: number;\n  /** Sensor minus image distance, micrometres. */\n  signedDefocusImagePlaneMicrometers: number;\n  /** Geometric thin-lens blur-circle diameter at the sensor, mm. */\n  geometricBlurDiameterMm: number;\n  /** Image-side working f-number v(lambda) / D. */\n  workingFNumberAtWavelength: number;\n  /** Defocus wave aberration W020 for the complex-pupil PSF, micrometres. */\n  w020Micrometers: number;\n  /** Equivalent Noll Z4 coefficient, micrometres. */\n  zernikeZ4Micrometers: number;\n}\n\nfunction requireFinite(name: string, value: unknown): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value)) {\n    throw new InvalidScientificInputError(`${name} must be finite.`);\n  }\n  return value;\n}\n\nfunction cauchyIndex(\n  refractiveIndexD: number,\n  abbeNumberD: number,\n  wavelengthNm: number\n): number {\n  const inverseSquare = (nm: number): number => 1 / (nm / 1000) ** 2;\n  const b =\n    (refractiveIndexD - 1) /\n    abbeNumberD /\n    (inverseSquare(FRAUNHOFER_F_LINE_NM) - inverseSquare(FRAUNHOFER_C_LINE_NM));\n  return (\n    refractiveIndexD +\n    b * (inverseSquare(wavelengthNm) - inverseSquare(FRAUNHOFER_D_LINE_NM))\n  );\n}\n\n/**\n * Two-term Cauchy refractive index fitted to n_d and V_d. Valid as an approximation over\n * 360-830 nm only.\n */\nexport function calculateCauchyRefractiveIndex(input: {\n  refractiveIndexD: number;\n  abbeNumberD: number;\n  wavelengthNm: number;\n}): CalculationResult<{ refractiveIndex: number }> {\n  requireInputKeys(input, \"calculateCauchyRefractiveIndex\", [\"refractiveIndexD\", \"abbeNumberD\", \"wavelengthNm\"]);\n  validateAbbe(input.refractiveIndexD, input.abbeNumberD);\n  validateCauchyWavelength(\"wavelengthNm\", input.wavelengthNm);\n  return approximationResult(\n    {\n      refractiveIndex: cauchyIndex(\n        input.refractiveIndexD,\n        input.abbeNumberD,\n        input.wavelengthNm\n      )\n    },\n    \"two-term-cauchy-abbe-dispersion\",\n    \"1.0.0\",\n    [\n      \"n(lambda) = A + B / lambda^2 fitted exactly to n_d and V_d = (n_d - 1) / (n_F - n_C)\",\n      \"Two-term Cauchy dispersion is an approximation for normal dispersion in the visible (360-830 nm)\"\n    ]\n  );\n}\n\nfunction validateAbbe(refractiveIndexD: unknown, abbeNumberD: unknown): void {\n  const n = requireFinite(\"dispersion.refractiveIndexD\", refractiveIndexD);\n  const v = requireFinite(\"dispersion.abbeNumberD\", abbeNumberD);\n  if (n <= 1 || n > 4) {\n    throw new InvalidScientificInputError(\n      \"dispersion.refractiveIndexD must lie in (1, 4].\"\n    );\n  }\n  if (v < 5 || v > 200) {\n    throw new InvalidScientificInputError(\n      \"dispersion.abbeNumberD must lie in [5, 200].\"\n    );\n  }\n}\n\nfunction validateCauchyWavelength(name: string, value: unknown): void {\n  const wavelength = requireFinite(name, value);\n  if (\n    wavelength < CAUCHY_MINIMUM_WAVELENGTH_NM ||\n    wavelength > CAUCHY_MAXIMUM_WAVELENGTH_NM\n  ) {\n    throw new InvalidScientificInputError(\n      `${name} must lie in ${CAUCHY_MINIMUM_WAVELENGTH_NM}-${CAUCHY_MAXIMUM_WAVELENGTH_NM} nm for the Cauchy dispersion approximation.`\n    );\n  }\n}\n\nfunction interpolateShift(\n  samples: readonly { wavelengthNm: number; focalLengthShiftMicrometers: number }[],\n  wavelengthNm: number,\n  name: string\n): number {\n  const first = samples[0]!;\n  const last = samples[samples.length - 1]!;\n  if (wavelengthNm < first.wavelengthNm || wavelengthNm > last.wavelengthNm) {\n    throw new InvalidScientificInputError(\n      `${name} lies outside the declared focal-shift wavelength range; extrapolation is not performed.`\n    );\n  }\n  for (let index = 1; index < samples.length; index += 1) {\n    const right = samples[index]!;\n    if (wavelengthNm <= right.wavelengthNm) {\n      const left = samples[index - 1]!;\n      const t = (wavelengthNm - left.wavelengthNm) / (right.wavelengthNm - left.wavelengthNm);\n      return (\n        left.focalLengthShiftMicrometers +\n        t * (right.focalLengthShiftMicrometers - left.focalLengthShiftMicrometers)\n      );\n    }\n  }\n  return first.focalLengthShiftMicrometers;\n}\n\nfunction parseSamples(\n  value: unknown\n): readonly { wavelengthNm: number; focalLengthShiftMicrometers: number }[] {\n  if (!Array.isArray(value) || value.length < 2 || value.length > 1024) {\n    throw new InvalidScientificInputError(\n      \"dispersion.samples must contain 2 through 1024 entries.\"\n    );\n  }\n  let previous = 0;\n  return value.map((entry: unknown, index) => {\n    if (typeof entry !== \"object\" || entry === null) {\n      throw new InvalidConfigurationError(`dispersion.samples[${index}] must be an object.`);\n    }\n    const record = entry as Record<string, unknown>;\n    const wavelengthNm = requireFinite(`dispersion.samples[${index}].wavelengthNm`, record.wavelengthNm);\n    if (wavelengthNm <= previous) {\n      throw new InvalidScientificInputError(\n        \"dispersion.samples wavelengths must be positive and strictly increasing.\"\n      );\n    }\n    previous = wavelengthNm;\n    return {\n      wavelengthNm,\n      focalLengthShiftMicrometers: requireFinite(\n        `dispersion.samples[${index}].focalLengthShiftMicrometers`,\n        record.focalLengthShiftMicrometers\n      )\n    };\n  });\n}\n\nfunction imageDistanceMm(focalLengthMm: number, objectDistanceM: number): number {\n  const objectMm = objectDistanceM * 1000;\n  if (objectMm <= focalLengthMm) {\n    throw new InvalidScientificInputError(\n      \"Object distances must lie beyond the wavelength-dependent focal length.\"\n    );\n  }\n  return (focalLengthMm * objectMm) / (objectMm - focalLengthMm);\n}\n\n/**\n * Wavelength-dependent focus for one wavelength: focal length, image distance, signed defocus at\n * a sensor focused at the reference wavelength, geometric blur and the defocus wavefront.\n */\nexport function calculateLongitudinalChromaticFocus(\n  input: CalculateLongitudinalChromaticFocusInput\n): CalculationResult<LongitudinalChromaticFocus> {\n  requireInputKeys(input, \"calculateLongitudinalChromaticFocus\", [\"focalLengthMm\", \"referenceWavelengthNm\", \"wavelengthNm\", \"apertureFNumber\", \"focusDistanceM\", \"subjectDistanceM\", \"dispersion\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"referenceWavelengthNm\", input.referenceWavelengthNm);\n  requirePositiveFinite(\"wavelengthNm\", input.wavelengthNm);\n  requirePositiveFinite(\"apertureFNumber\", input.apertureFNumber);\n  requirePositiveFinite(\"focusDistanceM\", input.focusDistanceM);\n  const subjectDistanceM = input.subjectDistanceM ?? input.focusDistanceM;\n  requirePositiveFinite(\"subjectDistanceM\", subjectDistanceM);\n  const dispersion = input.dispersion;\n  if (typeof dispersion !== \"object\" || dispersion === null) {\n    throw new InvalidConfigurationError(\"dispersion must be an object.\");\n  }\n\n  let focalLengthAtWavelengthMm: number;\n  let model: string;\n  let dispersionAssumption: string;\n  if (dispersion.kind === \"thin-singlet-abbe\") {\n    validateAbbe(dispersion.refractiveIndexD, dispersion.abbeNumberD);\n    validateCauchyWavelength(\"referenceWavelengthNm\", input.referenceWavelengthNm);\n    validateCauchyWavelength(\"wavelengthNm\", input.wavelengthNm);\n    const nRef = cauchyIndex(dispersion.refractiveIndexD, dispersion.abbeNumberD, input.referenceWavelengthNm);\n    const nLambda = cauchyIndex(dispersion.refractiveIndexD, dispersion.abbeNumberD, input.wavelengthNm);\n    focalLengthAtWavelengthMm = (input.focalLengthMm * (nRef - 1)) / (nLambda - 1);\n    model = \"thin-singlet-abbe-longitudinal-chromatic-focus\";\n    dispersionAssumption =\n      \"Ideal thin singlet with two-term Cauchy dispersion fitted to n_d and V_d; f(lambda) = f_ref (n_ref - 1) / (n(lambda) - 1)\";\n  } else if (dispersion.kind === \"declared-focal-shift\") {\n    const samples = parseSamples(dispersion.samples);\n    const shiftRef = interpolateShift(samples, input.referenceWavelengthNm, \"referenceWavelengthNm\");\n    const shift = interpolateShift(samples, input.wavelengthNm, \"wavelengthNm\");\n    focalLengthAtWavelengthMm = input.focalLengthMm + (shift - shiftRef) / 1000;\n    model = \"declared-focal-shift-longitudinal-chromatic-focus\";\n    dispersionAssumption =\n      \"Caller-declared focal-length shift table, linearly interpolated and re-referenced to the reference wavelength; no extrapolation\";\n  } else {\n    throw new InvalidConfigurationError(\"dispersion.kind is invalid.\");\n  }\n  if (!(focalLengthAtWavelengthMm > 0) || !Number.isFinite(focalLengthAtWavelengthMm)) {\n    throw new InvalidScientificInputError(\n      \"Wavelength-dependent focal length must remain finite and positive.\"\n    );\n  }\n\n  const sensorImageDistanceMm = imageDistanceMm(input.focalLengthMm, input.focusDistanceM);\n  const imageDistanceAtWavelengthMm = imageDistanceMm(focalLengthAtWavelengthMm, subjectDistanceM);\n  const pupilDiameterMm = input.focalLengthMm / input.apertureFNumber;\n  const defocusMm = sensorImageDistanceMm - imageDistanceAtWavelengthMm;\n  const workingFNumberAtWavelength = imageDistanceAtWavelengthMm / pupilDiameterMm;\n  const wavefront = calculateDefocusWavefront({\n    signedDefocusImagePlaneMicrometers: defocusMm * 1000,\n    workingFNumber: workingFNumberAtWavelength\n  }).value;\n\n  return approximationResult(\n    {\n      wavelengthNm: input.wavelengthNm,\n      referenceWavelengthNm: input.referenceWavelengthNm,\n      focalLengthAtWavelengthMm,\n      focalShiftMicrometers: (focalLengthAtWavelengthMm - input.focalLengthMm) * 1000,\n      sensorImageDistanceMm,\n      imageDistanceAtWavelengthMm,\n      signedDefocusImagePlaneMicrometers: defocusMm * 1000,\n      geometricBlurDiameterMm:\n        (pupilDiameterMm * Math.abs(defocusMm)) / imageDistanceAtWavelengthMm,\n      workingFNumberAtWavelength,\n      w020Micrometers: wavefront.w020Micrometers,\n      zernikeZ4Micrometers: wavefront.zernikeZ4Micrometers\n    },\n    model,\n    \"1.0.0\",\n    [\n      dispersionAssumption,\n      \"Gaussian thin-lens imaging; the sensor is focused on focusDistanceM at the reference wavelength\",\n      \"Entrance-pupil diameter f_ref / N is wavelength independent; distances are measured from ideal principal planes\",\n      \"Longitudinal chromatic focus only: lateral chromatic magnification, spherochromatism and sensor response are separate\",\n      \"Wavelength basis must match the dispersion data; no air/vacuum conversion is performed\"\n    ]\n  );\n}\n"]}

package/dist/optics/polygon-diffraction.d.ts

@@ -1,14 +1,19 @@
 /**
- * Module boundary and integration notes.
- * Calculates continuous monochromatic Fraunhofer PSF density for a uniformly illuminated, zero-phase,
- * on-axis ideal straight-edged regular polygon. Physical area is explicit; f/N may supply the
- * equal-area diameter only under a declared nominal-area convention. No phase aberration, clipping,
- * field dependence, curved blades, defocus or polychromatic behavior is inferred. Density = A |F/A|² /
- * (lambda * propagationDistance)². Parseval normalization is over the infinite plane, NOT over the
- * supplied point list. Downstream quadrature must preserve density × area and report
- * truncation/convergence.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Diffraction PSF (point-spread function) of a polygon-shaped aperture.
+ *
+ * The main model gives the continuous, single-wavelength Fraunhofer (far-field) PSF density of an
+ * ideal regular polygon with straight edges. The pupil is uniformly lit, has zero phase and sits on
+ * the optical axis.
+ * - The physical area is explicit. f/N may supply the diameter of a circle with the same area, but
+ *   only when the caller declares the nominal-area convention.
+ * - Nothing else is assumed: no phase aberration, clipping, field dependence, curved blades, defocus
+ *   or multi-wavelength behaviour.
+ *
+ * Density = A |F/A|² / (lambda * propagationDistance)². The density integrates to 1 over the
+ * infinite image plane (Parseval). It is NOT normalized over the supplied list of points. Code that
+ * sums these samples must keep density × area and report truncation and convergence.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type CalculateIdealApertureInput } from "./aperture.js";
@@ -17,9 +22,9 @@ import type { SpectralWavelengthBasis } from "../core/spectral.js";
 export interface CalculateIdealPolygonDiffractionInput extends CalculateIdealApertureInput {
     /** Diameter of a circle with the SAME AREA as the physical polygon opening. */
     equivalentAreaPupilDiameterMm: number;
-    /** Paraxial pupil-to-image propagation scale; not silently inferred from focus. */
+    /** Paraxial propagation distance from pupil to image. Never inferred from focus. */
     pupilToImageDistanceMm: number;
-    /** Wavelength in the declared propagation medium; no air/vacuum conversion. */
+    /** Wavelength in the declared propagation medium. No air/vacuum conversion is applied. */
     wavelengthNm: number;
     wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
     /** Displacements from the on-axis PSF center, +X right / +Y up; at most 4096. */
@@ -28,7 +33,7 @@ export interface CalculateIdealPolygonDiffractionInput extends CalculateIdealApe
         y: number;
     }[];
 }
-/** Continuous unit-energy PSF samples, not a normalized finite convolution kernel. */
+/** Samples of a continuous unit-energy PSF. This is not a normalized finite convolution kernel. */
 export interface IdealPolygonDiffraction {
     bladeCount: number;
     firstBladeEdgeAngleDegrees: number;
@@ -46,22 +51,74 @@ export interface IdealPolygonDiffraction {
             x: number;
             y: number;
         };
-        /** |F/A|²; unity at the origin. Not an energy/probability weight. */
+        /** |F/A|². Equal to 1 at the origin. Not an energy or probability weight. */
         peakNormalizedIntensity: number;
         /** Density integrating to unity over the full image plane, in 1/µm². */
         intensityDensityPerSquareMicrometer: number;
     }[];
 }
 /**
- * Calculates continuous monochromatic Fraunhofer PSF density for a uniformly
- * illuminated, zero-phase, on-axis ideal straight-edged regular polygon.
- * Physical area is explicit; f/N may supply the equal-area diameter only under
- * a declared nominal-area convention. No phase aberration, clipping, field
- * dependence, curved blades, defocus or polychromatic behavior is inferred.
+ * Calculates the continuous, single-wavelength Fraunhofer (far-field) PSF
+ * density of an ideal regular polygon with straight edges. The pupil is
+ * uniformly lit, has zero phase and sits on the optical axis.
+ *
+ * The physical area is explicit. f/N may supply the equal-area diameter only
+ * when the caller declares the nominal-area convention. Nothing else is
+ * assumed: no phase aberration, clipping, field dependence, curved blades,
+ * defocus or multi-wavelength behaviour.
  *
- * Density = A |F/A|² / (lambda * propagationDistance)². Parseval normalization
- * is over the infinite plane, NOT over the supplied point list. Downstream
- * quadrature must preserve density × area and report truncation/convergence.
+ * Density = A |F/A|² / (lambda * propagationDistance)². It integrates to 1
+ * over the infinite plane (Parseval), NOT over the supplied points. Code that
+ * sums the samples must keep density × area and report truncation and
+ * convergence.
  */
 export declare function calculateIdealPolygonDiffractionPsf(input: CalculateIdealPolygonDiffractionInput): CalculationResult<IdealPolygonDiffraction>;
-//# sourceMappingURL=polygon-diffraction.d.ts.map
+/** On-axis scalar Fraunhofer diffraction of one arbitrary simple polygon pupil. */
+export interface CalculatePolygonPupilFraunhoferPsfInput {
+    /**
+     * Simple (non-self-intersecting) pupil polygon in pupil-plane millimetres, +X right / +Y up,
+     * with 3 to 4096 vertices. For example, the cat's-eye pupil from calculateMechanicalVignetting().
+     */
+    pupilVerticesMm: readonly {
+        x: number;
+        y: number;
+    }[];
+    /** Paraxial propagation distance from pupil to image. Never inferred from focus. */
+    pupilToImageDistanceMm: number;
+    /** Wavelength in the declared propagation medium. No air/vacuum conversion is applied. */
+    wavelengthNm: number;
+    wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+    /** Displacements from the PSF centre (the geometric image point), +X right / +Y up; at most 4096. */
+    imagePointsMicrometers: readonly {
+        x: number;
+        y: number;
+    }[];
+}
+export interface PolygonPupilFraunhoferPsf {
+    pupilAreaSquareMm: number;
+    pupilToImageDistanceMm: number;
+    wavelengthNm: number;
+    wavelengthBasis: Exclude<SpectralWavelengthBasis, "unspecified">;
+    fieldAxes: "+X right, +Y up";
+    energyNormalization: "unit-integral-over-infinite-image-plane";
+    throughputApplied: false;
+    samples: readonly {
+        imagePointMicrometers: {
+            x: number;
+            y: number;
+        };
+        /** |F/A|²; unity at the origin. */
+        peakNormalizedIntensity: number;
+        /** Density integrating to unity over the full image plane, in 1/µm². */
+        intensityDensityPerSquareMicrometer: number;
+    }[];
+}
+/**
+ * Continuous, single-wavelength Fraunhofer PSF density for any simple polygon pupil that is uniformly
+ * lit and has zero phase (for example a cat's-eye pupil from mechanical vignetting).
+ *
+ * It uses the same analytic edge integral as the regular-polygon model, so there is no aliasing from
+ * a pupil grid. Moving the pupil off the axis only adds a linear phase; the intensity does not
+ * change. Density = A |F/A|² / (lambda z)², and it integrates to 1 over the infinite plane.
+ */
+export declare function calculatePolygonPupilFraunhoferPsf(input: CalculatePolygonPupilFraunhoferPsfInput): CalculationResult<PolygonPupilFraunhoferPsf>;

package/dist/optics/polygon-diffraction.js

@@ -1,19 +1,26 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates continuous monochromatic Fraunhofer PSF density for a uniformly illuminated, zero-phase,
- * on-axis ideal straight-edged regular polygon. Physical area is explicit; f/N may supply the
- * equal-area diameter only under a declared nominal-area convention. No phase aberration, clipping,
- * field dependence, curved blades, defocus or polychromatic behavior is inferred. Density = A |F/A|² /
- * (lambda * propagationDistance)². Parseval normalization is over the infinite plane, NOT over the
- * supplied point list. Downstream quadrature must preserve density × area and report
- * truncation/convergence.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Diffraction PSF (point-spread function) of a polygon-shaped aperture.
+ *
+ * The main model gives the continuous, single-wavelength Fraunhofer (far-field) PSF density of an
+ * ideal regular polygon with straight edges. The pupil is uniformly lit, has zero phase and sits on
+ * the optical axis.
+ * - The physical area is explicit. f/N may supply the diameter of a circle with the same area, but
+ *   only when the caller declares the nominal-area convention.
+ * - Nothing else is assumed: no phase aberration, clipping, field dependence, curved blades, defocus
+ *   or multi-wavelength behaviour.
+ *
+ * Density = A |F/A|² / (lambda * propagationDistance)². The density integrates to 1 over the
+ * infinite image plane (Parseval). It is NOT normalized over the supplied list of points. Code that
+ * sums these samples must keep density × area and report truncation and convergence.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { approximationResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
 import { calculateIdealApertureGeometry } from "./aperture.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 /** sin(x)/x - 1, evaluated without cancellation near zero. */
 function sincMinusOne(x) {
     if (Math.abs(x) < 0.01) {
@@ -23,10 +30,11 @@ function sincMinusOne(x) {
     return Math.sin(x) / x - 1;
 }
 /**
- * Independently derived polygon Fourier boundary integral via the divergence
- * theorem. Coordinates use unit circumradius so pupil size cannot change the
- * numerical conditioning. Subtracting the zero-frequency edge term (whose
- * closed-contour sum is zero) removes cancellation at/near the origin.
+ * Fourier transform of the polygon, written as an integral around its edges
+ * using the divergence theorem (independently derived). Coordinates use a
+ * circumradius of 1, so pupil size cannot affect numerical conditioning.
+ * Subtracting the zero-frequency edge term (which sums to zero around the
+ * closed polygon) avoids cancellation at and near the origin.
  */
 function peakIntensity(vertices, area, qx, qy) {
     const q = Math.hypot(qx, qy);
@@ -53,15 +61,19 @@ function peakIntensity(vertices, area, qx, qy) {
     return real * real + imaginary * imaginary;
 }
 /**
- * Calculates continuous monochromatic Fraunhofer PSF density for a uniformly
- * illuminated, zero-phase, on-axis ideal straight-edged regular polygon.
- * Physical area is explicit; f/N may supply the equal-area diameter only under
- * a declared nominal-area convention. No phase aberration, clipping, field
- * dependence, curved blades, defocus or polychromatic behavior is inferred.
+ * Calculates the continuous, single-wavelength Fraunhofer (far-field) PSF
+ * density of an ideal regular polygon with straight edges. The pupil is
+ * uniformly lit, has zero phase and sits on the optical axis.
+ *
+ * The physical area is explicit. f/N may supply the equal-area diameter only
+ * when the caller declares the nominal-area convention. Nothing else is
+ * assumed: no phase aberration, clipping, field dependence, curved blades,
+ * defocus or multi-wavelength behaviour.
  *
- * Density = A |F/A|² / (lambda * propagationDistance)². Parseval normalization
- * is over the infinite plane, NOT over the supplied point list. Downstream
- * quadrature must preserve density × area and report truncation/convergence.
+ * Density = A |F/A|² / (lambda * propagationDistance)². It integrates to 1
+ * over the infinite plane (Parseval), NOT over the supplied points. Code that
+ * sums the samples must keep density × area and report truncation and
+ * convergence.
  */
 export function calculateIdealPolygonDiffractionPsf(input) {
     // Reject unmodeled effects rather than silently accepting and ignoring them.
@@ -71,13 +83,13 @@ export function calculateIdealPolygonDiffractionPsf(input) {
     ]);
     if (typeof input !== "object" || input === null || Array.isArray(input) ||
         Object.keys(input).some((key) => !allowed.has(key))) {
-        throw new InvalidScientificInputError("Polygon diffraction input contains unsupported fields or is not an object.");
+        throw new InvalidConfigurationError("Polygon diffraction input contains unsupported fields or is not an object.");
     }
     requirePositiveFinite("equivalentAreaPupilDiameterMm", input.equivalentAreaPupilDiameterMm);
     requirePositiveFinite("pupilToImageDistanceMm", input.pupilToImageDistanceMm);
     requirePositiveFinite("wavelengthNm", input.wavelengthNm);
     if (input.wavelengthBasis !== "air" && input.wavelengthBasis !== "vacuum") {
-        throw new InvalidScientificInputError("wavelengthBasis must be air or vacuum.");
+        throw new InvalidConfigurationError("wavelengthBasis must be air or vacuum.");
     }
     if (input.firstBladeEdgeAngleDegrees !== undefined && !Number.isFinite(input.firstBladeEdgeAngleDegrees)) {
         throw new InvalidScientificInputError("firstBladeEdgeAngleDegrees must be finite when supplied.");
@@ -91,7 +103,7 @@ export function calculateIdealPolygonDiffractionPsf(input) {
             throw new InvalidScientificInputError("imagePointsMicrometers must not contain sparse entries.");
         }
     }
-    const geometry = calculateIdealApertureGeometry(input).value;
+    const geometry = calculateIdealApertureGeometry({ bladeCount: input.bladeCount, ...(input.firstBladeEdgeAngleDegrees === undefined ? {} : { firstBladeEdgeAngleDegrees: input.firstBladeEdgeAngleDegrees }) }).value;
     const unitArea = input.bladeCount * Math.sin(2 * Math.PI / input.bladeCount) / 2;
     const pupilAreaSquareMm = Math.PI * (input.equivalentAreaPupilDiameterMm / 2) ** 2;
     const radius = Math.sqrt(pupilAreaSquareMm / unitArea);
@@ -142,4 +154,97 @@ export function calculateIdealPolygonDiffractionPsf(input) {
         "Circular Airy remains a separate named diagnostic; do not stack this diffraction PSF over an already diffracted complex-pupil result."
     ], { notes: ["No quantified physical-model uncertainty is asserted. Numerical tolerances in tests are validation evidence, not real-lens accuracy bounds."] });
 }
+function requirePlanarPoint(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new InvalidScientificInputError(`${path} must contain finite x/y coordinates only.`);
+    }
+    const record = value;
+    if (Object.keys(record).some((key) => key !== "x" && key !== "y") ||
+        typeof record.x !== "number" || typeof record.y !== "number" ||
+        !Number.isFinite(record.x) || !Number.isFinite(record.y)) {
+        throw new InvalidScientificInputError(`${path} must contain finite x/y coordinates only.`);
+    }
+    return { x: record.x, y: record.y };
+}
+/**
+ * Continuous, single-wavelength Fraunhofer PSF density for any simple polygon pupil that is uniformly
+ * lit and has zero phase (for example a cat's-eye pupil from mechanical vignetting).
+ *
+ * It uses the same analytic edge integral as the regular-polygon model, so there is no aliasing from
+ * a pupil grid. Moving the pupil off the axis only adds a linear phase; the intensity does not
+ * change. Density = A |F/A|² / (lambda z)², and it integrates to 1 over the infinite plane.
+ */
+export function calculatePolygonPupilFraunhoferPsf(input) {
+    requireInputKeys(input, "calculatePolygonPupilFraunhoferPsf", ["pupilVerticesMm", "pupilToImageDistanceMm", "wavelengthNm", "wavelengthBasis", "imagePointsMicrometers"]);
+    requirePositiveFinite("pupilToImageDistanceMm", input.pupilToImageDistanceMm);
+    requirePositiveFinite("wavelengthNm", input.wavelengthNm);
+    if (input.wavelengthBasis !== "air" && input.wavelengthBasis !== "vacuum") {
+        throw new InvalidConfigurationError("wavelengthBasis must be air or vacuum.");
+    }
+    if (!Array.isArray(input.pupilVerticesMm) || input.pupilVerticesMm.length < 3 ||
+        input.pupilVerticesMm.length > 4096) {
+        throw new InvalidScientificInputError("pupilVerticesMm must contain 3 through 4096 vertices.");
+    }
+    if (!Array.isArray(input.imagePointsMicrometers) ||
+        input.imagePointsMicrometers.length === 0 || input.imagePointsMicrometers.length > 4096) {
+        throw new InvalidScientificInputError("imagePointsMicrometers must contain 1 through 4096 points.");
+    }
+    const vertices = input.pupilVerticesMm.map((vertex, index) => requirePlanarPoint(vertex, `pupilVerticesMm[${index}]`));
+    // Centre and scale the polygon for conditioning; translation changes only the phase of F.
+    const cx = vertices.reduce((sum, v) => sum + v.x, 0) / vertices.length;
+    const cy = vertices.reduce((sum, v) => sum + v.y, 0) / vertices.length;
+    const scale = Math.max(...vertices.map((v) => Math.hypot(v.x - cx, v.y - cy)));
+    if (!(scale > 0) || !Number.isFinite(scale)) {
+        throw new InvalidScientificInputError("pupilVerticesMm must span a finite non-zero region.");
+    }
+    let normalized = vertices.map((v) => ({ x: (v.x - cx) / scale, y: (v.y - cy) / scale }));
+    let twiceArea = 0;
+    for (let index = 0; index < normalized.length; index += 1) {
+        const a = normalized[index];
+        const b = normalized[(index + 1) % normalized.length];
+        twiceArea += a.x * b.y - b.x * a.y;
+    }
+    if (twiceArea < 0) {
+        normalized = [...normalized].reverse();
+        twiceArea = -twiceArea;
+    }
+    const unitArea = twiceArea / 2;
+    const pupilAreaSquareMm = unitArea * scale * scale;
+    const propagationScale = input.wavelengthNm / 1_000_000 * input.pupilToImageDistanceMm;
+    const densityScale = pupilAreaSquareMm / propagationScale ** 2 / 1_000_000;
+    if (!(unitArea > 1e-12) ||
+        ![pupilAreaSquareMm, propagationScale, densityScale].every((x) => Number.isFinite(x) && x > 0)) {
+        throw new InvalidScientificInputError("Polygon pupil area and derived scales must remain finite and positive.");
+    }
+    const samples = input.imagePointsMicrometers.map((value, index) => {
+        const point = requirePlanarPoint(value, `imagePointsMicrometers[${index}]`);
+        const qx = 2 * Math.PI * (point.x / 1000) * scale / propagationScale;
+        const qy = 2 * Math.PI * (point.y / 1000) * scale / propagationScale;
+        if (!Number.isFinite(Math.hypot(qx, qy)) || Math.hypot(qx, qy) > 1_000_000) {
+            throw new InvalidScientificInputError("Dimensionless pupil phase radius must not exceed 1000000.");
+        }
+        const intensity = peakIntensity(normalized, unitArea, qx, qy);
+        return {
+            imagePointMicrometers: { x: point.x === 0 ? 0 : point.x, y: point.y === 0 ? 0 : point.y },
+            peakNormalizedIntensity: intensity,
+            intensityDensityPerSquareMicrometer: intensity * densityScale
+        };
+    });
+    return approximationResult({
+        pupilAreaSquareMm,
+        pupilToImageDistanceMm: input.pupilToImageDistanceMm,
+        wavelengthNm: input.wavelengthNm,
+        wavelengthBasis: input.wavelengthBasis,
+        fieldAxes: "+X right, +Y up",
+        energyNormalization: "unit-integral-over-infinite-image-plane",
+        throughputApplied: false,
+        samples
+    }, "polygon-pupil-fraunhofer-diffraction", "1.0.0", [
+        "Uniform unit pupil amplitude and zero phase over a caller-declared simple polygon; scalar paraxial Fraunhofer propagation.",
+        "The PSF is centred on the geometric image point; a pupil offset from the optical axis adds only a linear phase.",
+        "Continuous PSF density has unit integral over the infinite image plane. Point samples are not a finite energy-normalized kernel.",
+        "Pupil-area throughput (for example mechanical vignetting) is reported separately and not applied to the density.",
+        "No aberration, defocus, polarization, sensor response or stray light is modeled."
+    ], { notes: ["No quantified physical-model uncertainty is asserted. Numerical tolerances in tests are validation evidence, not real-lens accuracy bounds."] });
+}
 //# sourceMappingURL=polygon-diffraction.js.map

package/dist/optics/polygon-diffraction.js.map

@@ -1 +1 @@
-{"version":3,"file":"polygon-diffraction.js","sourceRoot":"","sources":["../../src/optics/polygon-diffraction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"polygon-diffraction.js","sourceRoot":"","sources":["../../src/optics/polygon-diffraction.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Diffraction PSF (point-spread function) of a polygon-shaped aperture.\n *\n * The main model gives the continuous, single-wavelength Fraunhofer (far-field) PSF density of an\n * ideal regular polygon with straight edges. The pupil is uniformly lit, has zero phase and sits on\n * the optical axis.\n * - The physical area is explicit. f/N may supply the diameter of a circle with the same area, but\n *   only when the caller declares the nominal-area convention.\n * - Nothing else is assumed: no phase aberration, clipping, field dependence, curved blades, defocus\n *   or multi-wavelength behaviour.\n *\n * Density = A |F/A|² / (lambda * propagationDistance)². The density integrates to 1 over the\n * infinite image plane (Parseval). It is NOT normalized over the supplied list of points. Code that\n * sums these samples must keep density × area and report truncation and convergence.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError, requirePositiveFinite } from \"../core/validation.js\";\nimport { calculateIdealApertureGeometry, type CalculateIdealApertureInput } from \"./aperture.js\";\nimport type { SpectralWavelengthBasis } from \"../core/spectral.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\n/** On-axis, in-focus scalar diffraction of one ideal regular polygon pupil. */\nexport interface CalculateIdealPolygonDiffractionInput extends CalculateIdealApertureInput {\n  /** Diameter of a circle with the SAME AREA as the physical polygon opening. */\n  equivalentAreaPupilDiameterMm: number;\n  /** Paraxial propagation distance from pupil to image. Never inferred from focus. */\n  pupilToImageDistanceMm: number;\n  /** Wavelength in the declared propagation medium. No air/vacuum conversion is applied. */\n  wavelengthNm: number;\n  wavelengthBasis: Exclude<SpectralWavelengthBasis, \"unspecified\">;\n  /** Displacements from the on-axis PSF center, +X right / +Y up; at most 4096. */\n  imagePointsMicrometers: readonly { x: number; y: number }[];\n}\n\n/** Samples of a continuous unit-energy PSF. This is not a normalized finite convolution kernel. */\nexport interface IdealPolygonDiffraction {\n  bladeCount: number;\n  firstBladeEdgeAngleDegrees: number;\n  pupilToImageDistanceMm: number;\n  wavelengthNm: number;\n  wavelengthBasis: Exclude<SpectralWavelengthBasis, \"unspecified\">;\n  pupilAreaSquareMm: number;\n  pupilCircumradiusMm: number;\n  pupilNormalization: \"equal-area-circle\";\n  fieldAxes: \"+X right, +Y up\";\n  energyNormalization: \"unit-integral-over-infinite-image-plane\";\n  throughputApplied: false;\n  samples: readonly {\n    imagePointMicrometers: { x: number; y: number };\n    /** |F/A|². Equal to 1 at the origin. Not an energy or probability weight. */\n    peakNormalizedIntensity: number;\n    /** Density integrating to unity over the full image plane, in 1/µm². */\n    intensityDensityPerSquareMicrometer: number;\n  }[];\n}\n\n/** sin(x)/x - 1, evaluated without cancellation near zero. */\nfunction sincMinusOne(x: number): number {\n  if (Math.abs(x) < 0.01) {\n    const x2 = x * x;\n    return x2 * (-1 / 6 + x2 * (1 / 120 - x2 / 5040));\n  }\n  return Math.sin(x) / x - 1;\n}\n\n/**\n * Fourier transform of the polygon, written as an integral around its edges\n * using the divergence theorem (independently derived). Coordinates use a\n * circumradius of 1, so pupil size cannot affect numerical conditioning.\n * Subtracting the zero-frequency edge term (which sums to zero around the\n * closed polygon) avoids cancellation at and near the origin.\n */\nfunction peakIntensity(\n  vertices: readonly { x: number; y: number }[],\n  area: number,\n  qx: number,\n  qy: number\n): number {\n  const q = Math.hypot(qx, qy);\n  if (q === 0) return 1;\n  const ux = qx / q;\n  const uy = qy / q;\n  let real = 0;\n  let imaginary = 0;\n  for (let index = 0; index < vertices.length; index += 1) {\n    const a = vertices[index]!;\n    const b = vertices[(index + 1) % vertices.length]!;\n    const dx = b.x - a.x;\n    const dy = b.y - a.y;\n    const midpointPhase = qx * (a.x + b.x) / 2 + qy * (a.y + b.y) / 2;\n    const edgePhase = (qx * dx + qy * dy) / 2;\n    const sm1 = sincMinusOne(edgePhase);\n    const sinc = 1 + sm1;\n    const coefficient = (ux * dy - uy * dx) / area;\n    // i times the edge integral: real = -Im(edge), imaginary = Re(edge).\n    real += coefficient * sinc * (Math.sin(midpointPhase) / q);\n    imaginary += coefficient * (sm1 - sinc * 2 * Math.sin(midpointPhase / 2) ** 2) / q;\n  }\n  return real * real + imaginary * imaginary;\n}\n\n/**\n * Calculates the continuous, single-wavelength Fraunhofer (far-field) PSF\n * density of an ideal regular polygon with straight edges. The pupil is\n * uniformly lit, has zero phase and sits on the optical axis.\n *\n * The physical area is explicit. f/N may supply the equal-area diameter only\n * when the caller declares the nominal-area convention. Nothing else is\n * assumed: no phase aberration, clipping, field dependence, curved blades,\n * defocus or multi-wavelength behaviour.\n *\n * Density = A |F/A|² / (lambda * propagationDistance)². It integrates to 1\n * over the infinite plane (Parseval), NOT over the supplied points. Code that\n * sums the samples must keep density × area and report truncation and\n * convergence.\n */\nexport function calculateIdealPolygonDiffractionPsf(\n  input: CalculateIdealPolygonDiffractionInput\n): CalculationResult<IdealPolygonDiffraction> {\n  // Reject unmodeled effects rather than silently accepting and ignoring them.\n  const allowed = new Set([\n    \"bladeCount\", \"firstBladeEdgeAngleDegrees\", \"equivalentAreaPupilDiameterMm\",\n    \"pupilToImageDistanceMm\", \"wavelengthNm\", \"wavelengthBasis\", \"imagePointsMicrometers\"\n  ]);\n  if (typeof input !== \"object\" || input === null || Array.isArray(input) ||\n      Object.keys(input).some((key) => !allowed.has(key))) {\n    throw new InvalidConfigurationError(\"Polygon diffraction input contains unsupported fields or is not an object.\");\n  }\n  requirePositiveFinite(\"equivalentAreaPupilDiameterMm\", input.equivalentAreaPupilDiameterMm);\n  requirePositiveFinite(\"pupilToImageDistanceMm\", input.pupilToImageDistanceMm);\n  requirePositiveFinite(\"wavelengthNm\", input.wavelengthNm);\n  if (input.wavelengthBasis !== \"air\" && input.wavelengthBasis !== \"vacuum\") {\n    throw new InvalidConfigurationError(\"wavelengthBasis must be air or vacuum.\");\n  }\n  if (input.firstBladeEdgeAngleDegrees !== undefined && !Number.isFinite(input.firstBladeEdgeAngleDegrees)) {\n    throw new InvalidScientificInputError(\"firstBladeEdgeAngleDegrees must be finite when supplied.\");\n  }\n  if (!Array.isArray(input.imagePointsMicrometers) ||\n      input.imagePointsMicrometers.length === 0 || input.imagePointsMicrometers.length > 4096) {\n    throw new InvalidScientificInputError(\"imagePointsMicrometers must contain 1 through 4096 points.\");\n  }\n  for (let index = 0; index < input.imagePointsMicrometers.length; index += 1) {\n    if (!Object.hasOwn(input.imagePointsMicrometers, index)) {\n      throw new InvalidScientificInputError(\"imagePointsMicrometers must not contain sparse entries.\");\n    }\n  }\n  const geometry = calculateIdealApertureGeometry({ bladeCount: input.bladeCount, ...(input.firstBladeEdgeAngleDegrees === undefined ? {} : { firstBladeEdgeAngleDegrees: input.firstBladeEdgeAngleDegrees }) }).value;\n  const unitArea = input.bladeCount * Math.sin(2 * Math.PI / input.bladeCount) / 2;\n  const pupilAreaSquareMm = Math.PI * (input.equivalentAreaPupilDiameterMm / 2) ** 2;\n  const radius = Math.sqrt(pupilAreaSquareMm / unitArea);\n  const propagationScale = input.wavelengthNm / 1_000_000 * input.pupilToImageDistanceMm;\n  const densityScale = pupilAreaSquareMm / propagationScale ** 2 / 1_000_000;\n  if (![pupilAreaSquareMm, radius, propagationScale, densityScale].every((x) => Number.isFinite(x) && x > 0)) {\n    throw new InvalidScientificInputError(\"Derived polygon diffraction scales must remain finite and positive.\");\n  }\n  const samples = input.imagePointsMicrometers.map((point) => {\n    if (typeof point !== \"object\" || point === null || Array.isArray(point) ||\n        !Number.isFinite(point.x) || !Number.isFinite(point.y) ||\n        Object.keys(point).some((key) => key !== \"x\" && key !== \"y\")) {\n      throw new InvalidScientificInputError(\"Each image point must contain finite x/y coordinates only.\");\n    }\n    const qx = 2 * Math.PI * (point.x / 1000) * radius / propagationScale;\n    const qy = 2 * Math.PI * (point.y / 1000) * radius / propagationScale;\n    // A numerical envelope, not a real-lens calibration or physical accuracy bound.\n    if (!Number.isFinite(Math.hypot(qx, qy)) || Math.hypot(qx, qy) > 1_000_000) {\n      throw new InvalidScientificInputError(\"Dimensionless pupil phase radius must not exceed 1000000.\");\n    }\n    const intensity = peakIntensity(geometry.normalizedVertices, unitArea, qx, qy);\n    return {\n      imagePointMicrometers: { x: point.x === 0 ? 0 : point.x, y: point.y === 0 ? 0 : point.y },\n      peakNormalizedIntensity: intensity,\n      intensityDensityPerSquareMicrometer: intensity * densityScale\n    };\n  });\n  return approximationResult({\n    bladeCount: geometry.bladeCount,\n    firstBladeEdgeAngleDegrees: input.firstBladeEdgeAngleDegrees ?? 0,\n    pupilToImageDistanceMm: input.pupilToImageDistanceMm,\n    wavelengthNm: input.wavelengthNm,\n    wavelengthBasis: input.wavelengthBasis,\n    pupilAreaSquareMm,\n    pupilCircumradiusMm: radius,\n    pupilNormalization: \"equal-area-circle\",\n    fieldAxes: \"+X right, +Y up\",\n    energyNormalization: \"unit-integral-over-infinite-image-plane\",\n    throughputApplied: false,\n    samples\n  }, \"ideal-regular-polygon-fraunhofer-diffraction\", \"1.0.0\", [\n    \"Uniform unit pupil amplitude, zero phase, ideal regular straight-edged polygon; on-axis in-focus scalar paraxial Fraunhofer propagation only.\",\n    \"Wavelength is supplied in its declared propagation medium; no wavelength-basis conversion is performed.\",\n    \"Equal-area diameter fixes physical pupil area, not circumradius or inradius; no optical throughput loss is applied.\",\n    \"Continuous PSF density has unit integral over the infinite image plane. Point samples are not a finite energy-normalized kernel.\",\n    \"The analytical polygon boundary integral has no FFT/pupil-grid aliasing; downstream image-plane sampling and finite-support truncation still require convergence checks.\",\n    \"No real-lens calibration, aberration, defocus, mechanical clipping, curved blades, field dependence, polarization, sensor response or stray light is modeled.\",\n    \"Circular Airy remains a separate named diagnostic; do not stack this diffraction PSF over an already diffracted complex-pupil result.\"\n  ], { notes: [\"No quantified physical-model uncertainty is asserted. Numerical tolerances in tests are validation evidence, not real-lens accuracy bounds.\"] });\n}\n\n/** On-axis scalar Fraunhofer diffraction of one arbitrary simple polygon pupil. */\nexport interface CalculatePolygonPupilFraunhoferPsfInput {\n  /**\n   * Simple (non-self-intersecting) pupil polygon in pupil-plane millimetres, +X right / +Y up,\n   * with 3 to 4096 vertices. For example, the cat's-eye pupil from calculateMechanicalVignetting().\n   */\n  pupilVerticesMm: readonly { x: number; y: number }[];\n  /** Paraxial propagation distance from pupil to image. Never inferred from focus. */\n  pupilToImageDistanceMm: number;\n  /** Wavelength in the declared propagation medium. No air/vacuum conversion is applied. */\n  wavelengthNm: number;\n  wavelengthBasis: Exclude<SpectralWavelengthBasis, \"unspecified\">;\n  /** Displacements from the PSF centre (the geometric image point), +X right / +Y up; at most 4096. */\n  imagePointsMicrometers: readonly { x: number; y: number }[];\n}\n\nexport interface PolygonPupilFraunhoferPsf {\n  pupilAreaSquareMm: number;\n  pupilToImageDistanceMm: number;\n  wavelengthNm: number;\n  wavelengthBasis: Exclude<SpectralWavelengthBasis, \"unspecified\">;\n  fieldAxes: \"+X right, +Y up\";\n  energyNormalization: \"unit-integral-over-infinite-image-plane\";\n  throughputApplied: false;\n  samples: readonly {\n    imagePointMicrometers: { x: number; y: number };\n    /** |F/A|²; unity at the origin. */\n    peakNormalizedIntensity: number;\n    /** Density integrating to unity over the full image plane, in 1/µm². */\n    intensityDensityPerSquareMicrometer: number;\n  }[];\n}\n\nfunction requirePlanarPoint(value: unknown, path: string): { x: number; y: number } {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new InvalidScientificInputError(`${path} must contain finite x/y coordinates only.`);\n  }\n  const record = value as Record<string, unknown>;\n  if (\n    Object.keys(record).some((key) => key !== \"x\" && key !== \"y\") ||\n    typeof record.x !== \"number\" || typeof record.y !== \"number\" ||\n    !Number.isFinite(record.x) || !Number.isFinite(record.y)\n  ) {\n    throw new InvalidScientificInputError(`${path} must contain finite x/y coordinates only.`);\n  }\n  return { x: record.x, y: record.y };\n}\n\n/**\n * Continuous, single-wavelength Fraunhofer PSF density for any simple polygon pupil that is uniformly\n * lit and has zero phase (for example a cat's-eye pupil from mechanical vignetting).\n *\n * It uses the same analytic edge integral as the regular-polygon model, so there is no aliasing from\n * a pupil grid. Moving the pupil off the axis only adds a linear phase; the intensity does not\n * change. Density = A |F/A|² / (lambda z)², and it integrates to 1 over the infinite plane.\n */\nexport function calculatePolygonPupilFraunhoferPsf(\n  input: CalculatePolygonPupilFraunhoferPsfInput\n): CalculationResult<PolygonPupilFraunhoferPsf> {\n  requireInputKeys(input, \"calculatePolygonPupilFraunhoferPsf\", [\"pupilVerticesMm\", \"pupilToImageDistanceMm\", \"wavelengthNm\", \"wavelengthBasis\", \"imagePointsMicrometers\"]);\n  requirePositiveFinite(\"pupilToImageDistanceMm\", input.pupilToImageDistanceMm);\n  requirePositiveFinite(\"wavelengthNm\", input.wavelengthNm);\n  if (input.wavelengthBasis !== \"air\" && input.wavelengthBasis !== \"vacuum\") {\n    throw new InvalidConfigurationError(\"wavelengthBasis must be air or vacuum.\");\n  }\n  if (!Array.isArray(input.pupilVerticesMm) || input.pupilVerticesMm.length < 3 ||\n      input.pupilVerticesMm.length > 4096) {\n    throw new InvalidScientificInputError(\"pupilVerticesMm must contain 3 through 4096 vertices.\");\n  }\n  if (!Array.isArray(input.imagePointsMicrometers) ||\n      input.imagePointsMicrometers.length === 0 || input.imagePointsMicrometers.length > 4096) {\n    throw new InvalidScientificInputError(\"imagePointsMicrometers must contain 1 through 4096 points.\");\n  }\n  const vertices = input.pupilVerticesMm.map((vertex, index) =>\n    requirePlanarPoint(vertex, `pupilVerticesMm[${index}]`));\n  // Centre and scale the polygon for conditioning; translation changes only the phase of F.\n  const cx = vertices.reduce((sum, v) => sum + v.x, 0) / vertices.length;\n  const cy = vertices.reduce((sum, v) => sum + v.y, 0) / vertices.length;\n  const scale = Math.max(...vertices.map((v) => Math.hypot(v.x - cx, v.y - cy)));\n  if (!(scale > 0) || !Number.isFinite(scale)) {\n    throw new InvalidScientificInputError(\"pupilVerticesMm must span a finite non-zero region.\");\n  }\n  let normalized = vertices.map((v) => ({ x: (v.x - cx) / scale, y: (v.y - cy) / scale }));\n  let twiceArea = 0;\n  for (let index = 0; index < normalized.length; index += 1) {\n    const a = normalized[index]!;\n    const b = normalized[(index + 1) % normalized.length]!;\n    twiceArea += a.x * b.y - b.x * a.y;\n  }\n  if (twiceArea < 0) {\n    normalized = [...normalized].reverse();\n    twiceArea = -twiceArea;\n  }\n  const unitArea = twiceArea / 2;\n  const pupilAreaSquareMm = unitArea * scale * scale;\n  const propagationScale = input.wavelengthNm / 1_000_000 * input.pupilToImageDistanceMm;\n  const densityScale = pupilAreaSquareMm / propagationScale ** 2 / 1_000_000;\n  if (!(unitArea > 1e-12) ||\n      ![pupilAreaSquareMm, propagationScale, densityScale].every((x) => Number.isFinite(x) && x > 0)) {\n    throw new InvalidScientificInputError(\"Polygon pupil area and derived scales must remain finite and positive.\");\n  }\n  const samples = input.imagePointsMicrometers.map((value, index) => {\n    const point = requirePlanarPoint(value, `imagePointsMicrometers[${index}]`);\n    const qx = 2 * Math.PI * (point.x / 1000) * scale / propagationScale;\n    const qy = 2 * Math.PI * (point.y / 1000) * scale / propagationScale;\n    if (!Number.isFinite(Math.hypot(qx, qy)) || Math.hypot(qx, qy) > 1_000_000) {\n      throw new InvalidScientificInputError(\"Dimensionless pupil phase radius must not exceed 1000000.\");\n    }\n    const intensity = peakIntensity(normalized, unitArea, qx, qy);\n    return {\n      imagePointMicrometers: { x: point.x === 0 ? 0 : point.x, y: point.y === 0 ? 0 : point.y },\n      peakNormalizedIntensity: intensity,\n      intensityDensityPerSquareMicrometer: intensity * densityScale\n    };\n  });\n  return approximationResult({\n    pupilAreaSquareMm,\n    pupilToImageDistanceMm: input.pupilToImageDistanceMm,\n    wavelengthNm: input.wavelengthNm,\n    wavelengthBasis: input.wavelengthBasis,\n    fieldAxes: \"+X right, +Y up\",\n    energyNormalization: \"unit-integral-over-infinite-image-plane\",\n    throughputApplied: false,\n    samples\n  }, \"polygon-pupil-fraunhofer-diffraction\", \"1.0.0\", [\n    \"Uniform unit pupil amplitude and zero phase over a caller-declared simple polygon; scalar paraxial Fraunhofer propagation.\",\n    \"The PSF is centred on the geometric image point; a pupil offset from the optical axis adds only a linear phase.\",\n    \"Continuous PSF density has unit integral over the infinite image plane. Point samples are not a finite energy-normalized kernel.\",\n    \"Pupil-area throughput (for example mechanical vignetting) is reported separately and not applied to the density.\",\n    \"No aberration, defocus, polarization, sensor response or stray light is modeled.\"\n  ], { notes: [\"No quantified physical-model uncertainty is asserted. Numerical tolerances in tests are validation evidence, not real-lens accuracy bounds.\"] });\n}\n"]}

package/dist/optics/profile-contract.d.ts

@@ -1,5 +1,5 @@
 import { type EvidenceProvenance } from "../core/evidence-provenance.js";
-/** Exact, generic camera/lens and acquisition state; no implicit interpolation. */
+/** Exact, generic camera, lens and acquisition state. Nothing is interpolated implicitly. */
 export interface OpticalProfileState {
     bodyId: string;
     bodyVersion: string;
@@ -14,7 +14,7 @@ export interface OpticalProfileState {
     frameRateHz: number;
     stabilizationMode: string;
 }
-/** Generic approximation evidence; never implies measured calibration. */
+/** Evidence for a generic approximation. It never implies a measured calibration. */
 export interface GenericOpticalEvidence {
     kind: "generic-parametric";
     basis: string;
@@ -31,12 +31,11 @@ export declare function positive(value: unknown, name: string): number;
 export declare function textValue(value: unknown): string;
 /** @internal */
 export declare function choice<T extends string>(value: unknown, choices: readonly T[]): T;
-/** @internal Reject holes, duplicates (by consumers), and unbounded work. */
+/** @internal Rejects gaps and unbounded work. Consumers reject duplicates. */
 export declare function list(value: unknown, maximum?: number): unknown[];
-/** Parses a complete exact-state binding, including still/video/output settings. */
+/** Parses a complete exact-state binding, including still, video and output settings. */
 export declare function parseOpticalProfileState(value: unknown): OpticalProfileState;
-/** @internal Exact binding; mismatches fail rather than extrapolate. */
+/** @internal Exact binding. A mismatch fails; it is never extrapolated. */
 export declare function requireSameState(expected: OpticalProfileState, actual: OpticalProfileState): void;
 /** @internal */
 export declare function parseEvidence(value: unknown): GenericOpticalEvidence;
-//# sourceMappingURL=profile-contract.d.ts.map

package/dist/optics/profile-contract.js

@@ -1,21 +1,24 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Generic optical state binds one body/lens/version/acquisition/output configuration to explicit
- * approximation evidence. These identities do not certify manufacturer calibration.
- * Correction/stray-light consumers validate exact state equality before applying declared
- * coefficients.
+ * Generic optical state. It ties one camera body, lens, version, acquisition setting and output
+ * configuration to explicit evidence for the approximation used.
+ *
+ * These identities do not certify manufacturer calibration. Correction and stray-light code checks
+ * that the state matches exactly before it applies any declared coefficients.
  * @see docs/RELEASE_1_0.md and the corresponding domain guide.
  */
 import { InvalidScientificInputError } from "../core/validation.js";
 import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 /** @internal Strict shared profile parser helpers. */
 export function record(value, keys) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        throw new InvalidScientificInputError("Expected a profile object.");
+        throw new InvalidConfigurationError("Expected a profile object.");
     }
     const result = value;
-    if (Object.keys(result).some((key) => !keys.includes(key))) {
-        throw new InvalidScientificInputError("Unknown profile field.");
+    const unknown = Object.keys(result).find((key) => !keys.includes(key));
+    if (unknown !== undefined) {
+        throw new InvalidConfigurationError(`Unknown profile field. Unknown field ${JSON.stringify(unknown)}.`);
     }
     return result;
 }
@@ -43,10 +46,10 @@ export function textValue(value) {
 /** @internal */
 export function choice(value, choices) {
     if (!choices.includes(value))
-        throw new InvalidScientificInputError("Unknown profile enum.");
+        throw new InvalidConfigurationError("Unknown profile enum.");
     return value;
 }
-/** @internal Reject holes, duplicates (by consumers), and unbounded work. */
+/** @internal Rejects gaps and unbounded work. Consumers reject duplicates. */
 export function list(value, maximum = 4096) {
     if (!Array.isArray(value) || value.length > maximum ||
         Array.from({ length: value.length }, (_, index) => index in value).includes(false)) {
@@ -54,7 +57,7 @@ export function list(value, maximum = 4096) {
     }
     return value;
 }
-/** Parses a complete exact-state binding, including still/video/output settings. */
+/** Parses a complete exact-state binding, including still, video and output settings. */
 export function parseOpticalProfileState(value) {
     const r = record(value, ["bodyId", "bodyVersion", "lensId", "lensVersion", "focalLengthMm",
         "aperture", "focusDistanceM", "captureMode", "outputWidth", "outputHeight", "frameRateHz", "stabilizationMode"]);
@@ -77,7 +80,7 @@ export function parseOpticalProfileState(value) {
         stabilizationMode: textValue(r.stabilizationMode)
     };
 }
-/** @internal Exact binding; mismatches fail rather than extrapolate. */
+/** @internal Exact binding. A mismatch fails; it is never extrapolated. */
 export function requireSameState(expected, actual) {
     if (JSON.stringify(parseOpticalProfileState(expected)) !== JSON.stringify(parseOpticalProfileState(actual))) {
         throw new InvalidScientificInputError("Profile is not applicable to this exact camera/lens state.");