@photivra/engine 1.4.0 → 2.0.0

package/dist/optics/profile-contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"profile-contract.js","sourceRoot":"","sources":["../../src/optics/profile-contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"profile-contract.js","sourceRoot":"","sources":["../../src/optics/profile-contract.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;GAOG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAA2B,MAAM,gCAAgC,CAAC;AAC5F,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AA0B3E,sDAAsD;AACtD,MAAM,UAAU,MAAM,CAAC,KAAc,EAAE,IAAuB;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,yBAAyB,CAAC,4BAA4B,CAAC,CAAC;IACpE,CAAC;IACD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACvE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,yBAAyB,CAAC,wCAAwC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1G,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,MAAM,CAAC,KAAc,EAAE,IAAY;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,2BAA2B,CAAC,GAAG,IAAI,kBAAkB,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,QAAQ,CAAC,KAAc,EAAE,IAAY;IACnD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACnC,IAAI,MAAM,IAAI,CAAC;QAAE,MAAM,IAAI,2BAA2B,CAAC,GAAG,IAAI,oBAAoB,CAAC,CAAC;IACpF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,2BAA2B,CAAC,kDAAkD,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,MAAM,CAAmB,KAAc,EAAE,OAAqB;IAC5E,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAU,CAAC;QAAE,MAAM,IAAI,yBAAyB,CAAC,uBAAuB,CAAC,CAAC;IAChG,OAAO,KAAU,CAAC;AACpB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,IAAI,CAAC,KAAc,EAAE,OAAO,GAAG,IAAI;IACjD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,OAAO;QAC/C,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACvF,MAAM,IAAI,2BAA2B,CAAC,iCAAiC,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,aAAa,EAAE,eAAe;QACxF,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,mBAAmB,CAAC,CAAC,CAAC;IACnH,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,2BAA2B,CAAC,0CAA0C,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAClD,IAAI,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,2BAA2B,CAAC,yDAAyD,CAAC,CAAC;IACnG,CAAC;IACD,OAAO;QACL,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;QAClE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;QAClE,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC,aAAa,EAAE,eAAe,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC;QACrG,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC,cAAc,EAAE,gBAAgB,CAAC,EAAE,WAAW,EAAE,IAAI;QAC/E,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI;QAC3D,iBAAiB,EAAE,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC;KAClD,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,QAA6B,EAAE,MAA2B;IACzF,IAAI,IAAI,CAAC,SAAS,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,wBAAwB,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAC5G,MAAM,IAAI,2BAA2B,CAAC,4DAA4D,CAAC,CAAC;IACtG,CAAC;AACH,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC;IACtE,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,kBAAkB,CAAC,CAAC;IAC3E,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,oBAAoB,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC;AACvI,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Generic optical state. It ties one camera body, lens, version, acquisition setting and output\n * configuration to explicit evidence for the approximation used.\n *\n * These identities do not certify manufacturer calibration. Correction and stray-light code checks\n * that the state matches exactly before it applies any declared coefficients.\n * @see docs/RELEASE_1_0.md and the corresponding domain guide.\n */\n\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { parseEvidenceList, type EvidenceProvenance } from \"../core/evidence-provenance.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\n/** Exact, generic camera, lens and acquisition state. Nothing is interpolated implicitly. */\nexport interface OpticalProfileState {\n  bodyId: string;\n  bodyVersion: string;\n  lensId: string;\n  lensVersion: string;\n  focalLengthMm: number;\n  aperture: number;\n  focusDistanceM: number;\n  captureMode: \"still\" | \"video\";\n  outputWidth: number;\n  outputHeight: number;\n  frameRateHz: number;\n  stabilizationMode: string;\n}\n\n/** Evidence for a generic approximation. It never implies a measured calibration. */\nexport interface GenericOpticalEvidence {\n  kind: \"generic-parametric\";\n  basis: string;\n  residualNote: string;\n  sources: readonly EvidenceProvenance[];\n}\n\n/** @internal Strict shared profile parser helpers. */\nexport function record(value: unknown, keys: readonly string[]): Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new InvalidConfigurationError(\"Expected a profile object.\");\n  }\n  const result = value as Record<string, unknown>;\n  const unknown = Object.keys(result).find((key) => !keys.includes(key));\n  if (unknown !== undefined) {\n    throw new InvalidConfigurationError(`Unknown profile field. Unknown field ${JSON.stringify(unknown)}.`);\n  }\n  return result;\n}\n\n/** @internal */\nexport function finite(value: unknown, name: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value)) {\n    throw new InvalidScientificInputError(`${name} must be finite.`);\n  }\n  return value;\n}\n\n/** @internal */\nexport function positive(value: unknown, name: string): number {\n  const number = finite(value, name);\n  if (number <= 0) throw new InvalidScientificInputError(`${name} must be positive.`);\n  return number;\n}\n\n/** @internal */\nexport function textValue(value: unknown): string {\n  if (typeof value !== \"string\" || value.trim() === \"\") {\n    throw new InvalidScientificInputError(\"Expected a nonempty identity or evidence string.\");\n  }\n  return value;\n}\n\n/** @internal */\nexport function choice<T extends string>(value: unknown, choices: readonly T[]): T {\n  if (!choices.includes(value as T)) throw new InvalidConfigurationError(\"Unknown profile enum.\");\n  return value as T;\n}\n\n/** @internal Rejects gaps and unbounded work. Consumers reject duplicates. */\nexport function list(value: unknown, maximum = 4096): unknown[] {\n  if (!Array.isArray(value) || value.length > maximum ||\n      Array.from({ length: value.length }, (_, index) => index in value).includes(false)) {\n    throw new InvalidScientificInputError(\"Expected a bounded dense array.\");\n  }\n  return value;\n}\n\n/** Parses a complete exact-state binding, including still, video and output settings. */\nexport function parseOpticalProfileState(value: unknown): OpticalProfileState {\n  const r = record(value, [\"bodyId\", \"bodyVersion\", \"lensId\", \"lensVersion\", \"focalLengthMm\",\n    \"aperture\", \"focusDistanceM\", \"captureMode\", \"outputWidth\", \"outputHeight\", \"frameRateHz\", \"stabilizationMode\"]);\n  const width = positive(r.outputWidth, \"outputWidth\");\n  const height = positive(r.outputHeight, \"outputHeight\");\n  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height)) {\n    throw new InvalidScientificInputError(\"Output dimensions must be safe integers.\");\n  }\n  const mode = choice(r.captureMode, [\"still\", \"video\"]);\n  const rate = finite(r.frameRateHz, \"frameRateHz\");\n  if (mode === \"still\" ? rate !== 0 : rate <= 0) {\n    throw new InvalidScientificInputError(\"Still frameRateHz must be zero; video must be positive.\");\n  }\n  return {\n    bodyId: textValue(r.bodyId), bodyVersion: textValue(r.bodyVersion),\n    lensId: textValue(r.lensId), lensVersion: textValue(r.lensVersion),\n    focalLengthMm: positive(r.focalLengthMm, \"focalLengthMm\"), aperture: positive(r.aperture, \"aperture\"),\n    focusDistanceM: positive(r.focusDistanceM, \"focusDistanceM\"), captureMode: mode,\n    outputWidth: width, outputHeight: height, frameRateHz: rate,\n    stabilizationMode: textValue(r.stabilizationMode)\n  };\n}\n\n/** @internal Exact binding. A mismatch fails; it is never extrapolated. */\nexport function requireSameState(expected: OpticalProfileState, actual: OpticalProfileState): void {\n  if (JSON.stringify(parseOpticalProfileState(expected)) !== JSON.stringify(parseOpticalProfileState(actual))) {\n    throw new InvalidScientificInputError(\"Profile is not applicable to this exact camera/lens state.\");\n  }\n}\n\n/** @internal */\nexport function parseEvidence(value: unknown): GenericOpticalEvidence {\n  const r = record(value, [\"kind\", \"basis\", \"residualNote\", \"sources\"]);\n  const sources = parseEvidenceList(list(r.sources, 32), \"evidence.sources\");\n  return { kind: choice(r.kind, [\"generic-parametric\"]), basis: textValue(r.basis), residualNote: textValue(r.residualNote), sources };\n}\n"]}

package/dist/optics/psf-foundation.d.ts

@@ -1,15 +1,16 @@
 /**
- * Module boundary and integration notes.
- * Returns the public PSF/pupil foundation contract. The contract describes current diagnostics plus
- * reserved future contribution ownership. It does not imply that reserved contributions are
- * implemented.
- * Evaluates the currently implemented PSF-related diagnostics in one explicit
- * field/depth/spectral/pupil context without combining them into a synthetic PSF or blur radius. Field
- * position is recorded even though the current defocus-circle and circular-Airy diagnostics are not
- * field dependent. Future field-dependent contributions can consume the same context without changing
- * these existing primitives.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Foundation contract for the PSF (point-spread function) and pupil.
+ *
+ * The contract lists the diagnostics that exist today. It also reserves names for future
+ * contributions. A reserved contribution is not implemented.
+ *
+ * The evaluator runs today's PSF-related diagnostics in one explicit context: field position,
+ * depth, wavelength and pupil. It does not combine them into a synthetic PSF or blur radius. The
+ * field position is recorded even though the current defocus-circle and circular-Airy diagnostics
+ * do not depend on it. Future field-dependent contributions can use the same context without
+ * changing these primitives.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationProvenance, type CalculationResult } from "../core/calculation-result.js";
 import type { LensFieldPointMm } from "./radial-distortion.js";
@@ -46,8 +47,9 @@ export interface CalculatePsfFoundationComponentsInput {
      */
     fieldPointMm: LensFieldPointMm;
     /**
-     * Physical image-plane radius used only to normalize field position for
-     * cross-case diagnostics. It is not a lens calibration or validity bound.
+     * Physical image-plane radius. It is used only to normalize the field
+     * position so diagnostics can be compared across cases. It is not a lens
+     * calibration or a validity limit.
      */
     fieldNormalizationRadiusMm: number;
     spectralBasis: {
@@ -97,19 +99,17 @@ export interface PsfFoundationComponents {
 /**
  * Returns the public PSF/pupil foundation contract.
  *
- * The contract describes current diagnostics plus reserved future contribution
- * ownership. It does not imply that reserved contributions are implemented.
+ * The contract lists today's diagnostics and reserves names for future
+ * contributions. A reserved contribution is not implemented.
  */
 export declare function getPsfFoundationContract(): PsfFoundationContract;
 /**
- * Evaluates the currently implemented PSF-related diagnostics in one explicit
- * field/depth/spectral/pupil context without combining them into a synthetic
- * PSF or blur radius.
+ * Evaluates today's PSF-related diagnostics in one explicit context (field
+ * position, depth, wavelength and pupil). It does not combine them into a
+ * synthetic PSF or blur radius.
  *
- * Field position is recorded even though the current defocus-circle and
- * circular-Airy diagnostics are not field dependent. Future field-dependent
- * contributions can consume the same context without changing these existing
- * primitives.
+ * The field position is recorded even though the current defocus-circle and
+ * circular-Airy diagnostics do not depend on it. Future field-dependent
+ * contributions can use the same context without changing these primitives.
  */
 export declare function calculatePsfFoundationComponents(input: CalculatePsfFoundationComponentsInput): CalculationResult<PsfFoundationComponents>;
-//# sourceMappingURL=psf-foundation.d.ts.map

package/dist/optics/psf-foundation.js

@@ -1,21 +1,24 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Returns the public PSF/pupil foundation contract. The contract describes current diagnostics plus
- * reserved future contribution ownership. It does not imply that reserved contributions are
- * implemented.
- * Evaluates the currently implemented PSF-related diagnostics in one explicit
- * field/depth/spectral/pupil context without combining them into a synthetic PSF or blur radius. Field
- * position is recorded even though the current defocus-circle and circular-Airy diagnostics are not
- * field dependent. Future field-dependent contributions can consume the same context without changing
- * these existing primitives.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Foundation contract for the PSF (point-spread function) and pupil.
+ *
+ * The contract lists the diagnostics that exist today. It also reserves names for future
+ * contributions. A reserved contribution is not implemented.
+ *
+ * The evaluator runs today's PSF-related diagnostics in one explicit context: field position,
+ * depth, wavelength and pupil. It does not combine them into a synthetic PSF or blur radius. The
+ * field position is recorded even though the current defocus-circle and circular-Airy diagnostics
+ * do not depend on it. Future field-dependent contributions can use the same context without
+ * changing these primitives.
+ * @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 { calculateDefocusCircle } from "./depth-of-field.js";
 import { calculateAiryDisk } from "./diffraction.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 export const PSF_FOUNDATION_VERSION = "0.3.0";
 const CONTRIBUTIONS = [
     {
@@ -71,8 +74,8 @@ const NOTES = [
 /**
  * Returns the public PSF/pupil foundation contract.
  *
- * The contract describes current diagnostics plus reserved future contribution
- * ownership. It does not imply that reserved contributions are implemented.
+ * The contract lists today's diagnostics and reserves names for future
+ * contributions. A reserved contribution is not implemented.
  */
 export function getPsfFoundationContract() {
     return {
@@ -93,23 +96,23 @@ export function getPsfFoundationContract() {
     };
 }
 /**
- * Evaluates the currently implemented PSF-related diagnostics in one explicit
- * field/depth/spectral/pupil context without combining them into a synthetic
- * PSF or blur radius.
+ * Evaluates today's PSF-related diagnostics in one explicit context (field
+ * position, depth, wavelength and pupil). It does not combine them into a
+ * synthetic PSF or blur radius.
  *
- * Field position is recorded even though the current defocus-circle and
- * circular-Airy diagnostics are not field dependent. Future field-dependent
- * contributions can consume the same context without changing these existing
- * primitives.
+ * The field position is recorded even though the current defocus-circle and
+ * circular-Airy diagnostics do not depend on it. Future field-dependent
+ * contributions can use the same context without changing these primitives.
  */
 export function calculatePsfFoundationComponents(input) {
+    requireInputKeys(input, "calculatePsfFoundationComponents", ["focalLengthMm", "aperture", "focusDistanceM", "subjectDistanceM", "fieldPointMm", "fieldNormalizationRadiusMm", "spectralBasis"]);
     requirePositiveFinite("focalLengthMm", input.focalLengthMm);
     requirePositiveFinite("aperture", input.aperture);
     requirePositiveFinite("focusDistanceM", input.focusDistanceM);
     requirePositiveFinite("subjectDistanceM", input.subjectDistanceM);
     requirePositiveFinite("fieldNormalizationRadiusMm", input.fieldNormalizationRadiusMm);
     if (input.spectralBasis?.kind !== "monochromatic") {
-        throw new InvalidScientificInputError('spectralBasis.kind must be "monochromatic".');
+        throw new InvalidConfigurationError('spectralBasis.kind must be "monochromatic".');
     }
     requirePositiveFinite("spectralBasis.wavelengthNm", input.spectralBasis.wavelengthNm);
     if (!Number.isFinite(input.fieldPointMm.x)) {

package/dist/optics/psf-foundation.js.map

@@ -1 +1 @@
-{"version":3,"file":"psf-foundation.js","sourceRoot":"","sources":["../../src/optics/psf-foundation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"psf-foundation.js","sourceRoot":"","sources":["../../src/optics/psf-foundation.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Foundation contract for the PSF (point-spread function) and pupil.\n *\n * The contract lists the diagnostics that exist today. It also reserves names for future\n * contributions. A reserved contribution is not implemented.\n *\n * The evaluator runs today's PSF-related diagnostics in one explicit context: field position,\n * depth, wavelength and pupil. It does not combine them into a synthetic PSF or blur radius. The\n * field position is recorded even though the current defocus-circle and circular-Airy diagnostics\n * do not depend on it. Future field-dependent contributions can use the same context without\n * changing these primitives.\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 CalculationProvenance,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport type { LensFieldPointMm } from \"./radial-distortion.js\";\nimport { calculateDefocusCircle } from \"./depth-of-field.js\";\nimport { calculateAiryDisk } from \"./diffraction.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport const PSF_FOUNDATION_VERSION = \"0.3.0\" as const;\n\nexport type PsfContributionId =\n  | \"geometric-defocus-circle\"\n  | \"circular-diffraction-first-zero\"\n  | \"non-circular-diffraction\"\n  | \"mechanical-pupil-clipping\"\n  | \"field-curvature\"\n  | \"field-dependent-aberration\"\n  | \"field-dependent-bokeh\";\n\nexport type PsfContributionStatus =\n  | \"implemented-diagnostic\"\n  | \"implemented-framework\"\n  | \"reserved-contract\";\n\nexport interface PsfContributionContract {\n  id: PsfContributionId;\n  status: PsfContributionStatus;\n  dependsOn: readonly (\n    | \"field-position\"\n    | \"focus-depth\"\n    | \"pupil\"\n    | \"wavelength\"\n  )[];\n  note: string;\n}\n\nexport interface PsfFoundationContract {\n  version: typeof PSF_FOUNDATION_VERSION;\n  coordinateSpace: \"image-plane-metric\";\n  fieldAxes: \"+X right, +Y up\";\n  compositionPolicy:\n    \"separate-diagnostics-plus-explicit-profiled-combined-psf\";\n  contributions: readonly PsfContributionContract[];\n  previewReferencePolicy: {\n    previewMayApproximate: true;\n    referenceMayUseHigherFidelity: true;\n    mustPreserveContributionSemantics: true;\n  };\n  notes: readonly string[];\n}\n\nexport interface CalculatePsfFoundationComponentsInput {\n  focalLengthMm: number;\n  aperture: number;\n  focusDistanceM: number;\n  subjectDistanceM: number;\n  /**\n   * Image-plane field position relative to the optical axis, in millimetres.\n   * +X is right and +Y is up.\n   */\n  fieldPointMm: LensFieldPointMm;\n  /**\n   * Physical image-plane radius. It is used only to normalize the field\n   * position so diagnostics can be compared across cases. It is not a lens\n   * calibration or a validity limit.\n   */\n  fieldNormalizationRadiusMm: number;\n  spectralBasis: {\n    kind: \"monochromatic\";\n    wavelengthNm: number;\n  };\n}\n\nexport interface PsfFoundationComponents {\n  context: {\n    field: {\n      imagePointMm: LensFieldPointMm;\n      radiusMm: number;\n      normalizationRadiusMm: number;\n      normalizedRadius: number;\n    };\n    depth: {\n      focusDistanceM: number;\n      subjectDistanceM: number;\n    };\n    spectralBasis: {\n      kind: \"monochromatic\";\n      wavelengthNm: number;\n    };\n    pupil: {\n      kind: \"ideal-circular-f-number-derived\";\n      apertureFNumber: number;\n      diameterMm: number;\n    };\n  };\n  contributions: {\n    geometricDefocus: {\n      id: \"geometric-defocus-circle\";\n      diameterMm: number;\n      provenance: CalculationProvenance;\n    };\n    circularDiffraction: {\n      id: \"circular-diffraction-first-zero\";\n      firstZeroDiameterMicrometers: number;\n      provenance: CalculationProvenance;\n    };\n  };\n  composition: {\n    status: \"not-composed\";\n    note: string;\n  };\n}\n\nconst CONTRIBUTIONS = [\n  {\n    id: \"geometric-defocus-circle\",\n    status: \"implemented-diagnostic\",\n    dependsOn: [\"focus-depth\", \"pupil\"],\n    note:\n      \"Existing thin-lens geometric defocus diameter. This is a blur-circle diagnostic, not a complete intensity PSF.\"\n  },\n  {\n    id: \"circular-diffraction-first-zero\",\n    status: \"implemented-diagnostic\",\n    dependsOn: [\"pupil\", \"wavelength\"],\n    note:\n      \"Existing ideal circular-pupil first-zero Airy diameter. This is a diffraction-size diagnostic, not a sampled intensity PSF.\"\n  },\n  {\n    id: \"non-circular-diffraction\",\n    status: \"implemented-framework\",\n    dependsOn: [\"pupil\", \"wavelength\"],\n    note:\n      \"Implemented ideal on-axis regular-polygon Fraunhofer PSF density with explicit equal-area physical pupil scaling. Curved blades, aberration and off-axis/clipped real pupils are not inferred.\"\n  },\n  {\n    id: \"mechanical-pupil-clipping\",\n    status: \"implemented-framework\",\n    dependsOn: [\"pupil\", \"field-position\"],\n    note:\n      \"Implemented through explicit sampled-PSF or complex-pupil profile semantics. PSF shape and relative pupil throughput remain separately owned to avoid double counting.\"\n  },\n  {\n    id: \"field-curvature\",\n    status: \"implemented-framework\",\n    dependsOn: [\"field-position\", \"focus-depth\"],\n    note:\n      \"Implemented as explicit field-dependent best-focus image-plane offset in the lens-PSF profile framework. It remains separate from geometric distortion.\"\n  },\n  {\n    id: \"field-dependent-aberration\",\n    status: \"implemented-framework\",\n    dependsOn: [\"field-position\", \"focus-depth\", \"pupil\", \"wavelength\"],\n    note:\n      \"Implemented through full 2D sampled PSF kernels and explicit complex-pupil amplitude/OPD propagation. No scalar lens-sharpness score is produced.\"\n  },\n  {\n    id: \"field-dependent-bokeh\",\n    status: \"implemented-framework\",\n    dependsOn: [\"field-position\", \"focus-depth\", \"pupil\"],\n    note:\n      \"Implemented through signed-defocus sampled PSF context and optional pupil-clipping shape. Visibility/depth compositing remains renderer work.\"\n  }\n] as const satisfies readonly PsfContributionContract[];\n\nconst NOTES = [\n  \"This foundation preserves the legacy defocus/Airy diagnostics separately while the lens-PSF framework can resolve explicitly profiled combined primary-optical PSFs. It still never emits one scalar lens-sharpness result.\",\n  \"Existing geometric defocus and circular Airy outputs remain independently named scientific diagnostics with their own provenance.\",\n  \"Framework contributions require explicit profile/evaluator APIs; the ideal polygon diffraction evaluator is standalone and is not silently composed into the legacy diagnostics or POC.\",\n  \"Illumination vignetting is a separate throughput-only model and is not a PSF contribution.\",\n  \"Real-lens PSF calibration requires defensible provenance, compatible reuse rights, and explicit limitations/uncertainty.\"\n] as const;\n\n/**\n * Returns the public PSF/pupil foundation contract.\n *\n * The contract lists today's diagnostics and reserves names for future\n * contributions. A reserved contribution is not implemented.\n */\nexport function getPsfFoundationContract(): PsfFoundationContract {\n  return {\n    version: PSF_FOUNDATION_VERSION,\n    coordinateSpace: \"image-plane-metric\",\n    fieldAxes: \"+X right, +Y up\",\n    compositionPolicy:\n      \"separate-diagnostics-plus-explicit-profiled-combined-psf\",\n    contributions: CONTRIBUTIONS.map((contribution) => ({\n      ...contribution,\n      dependsOn: [...contribution.dependsOn]\n    })),\n    previewReferencePolicy: {\n      previewMayApproximate: true,\n      referenceMayUseHigherFidelity: true,\n      mustPreserveContributionSemantics: true\n    },\n    notes: [...NOTES]\n  };\n}\n\n/**\n * Evaluates today's PSF-related diagnostics in one explicit context (field\n * position, depth, wavelength and pupil). It does not combine them into a\n * synthetic PSF or blur radius.\n *\n * The field position is recorded even though the current defocus-circle and\n * circular-Airy diagnostics do not depend on it. Future field-dependent\n * contributions can use the same context without changing these primitives.\n */\nexport function calculatePsfFoundationComponents(\n  input: CalculatePsfFoundationComponentsInput\n): CalculationResult<PsfFoundationComponents> {\n  requireInputKeys(input, \"calculatePsfFoundationComponents\", [\"focalLengthMm\", \"aperture\", \"focusDistanceM\", \"subjectDistanceM\", \"fieldPointMm\", \"fieldNormalizationRadiusMm\", \"spectralBasis\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"aperture\", input.aperture);\n  requirePositiveFinite(\"focusDistanceM\", input.focusDistanceM);\n  requirePositiveFinite(\"subjectDistanceM\", input.subjectDistanceM);\n  requirePositiveFinite(\n    \"fieldNormalizationRadiusMm\",\n    input.fieldNormalizationRadiusMm\n  );\n  if (input.spectralBasis?.kind !== \"monochromatic\") {\n    throw new InvalidConfigurationError(\n      'spectralBasis.kind must be \"monochromatic\".'\n    );\n  }\n  requirePositiveFinite(\n    \"spectralBasis.wavelengthNm\",\n    input.spectralBasis.wavelengthNm\n  );\n\n  if (!Number.isFinite(input.fieldPointMm.x)) {\n    throw new InvalidScientificInputError(\n      \"fieldPointMm.x must be finite.\"\n    );\n  }\n  if (!Number.isFinite(input.fieldPointMm.y)) {\n    throw new InvalidScientificInputError(\n      \"fieldPointMm.y must be finite.\"\n    );\n  }\n\n  const defocus = calculateDefocusCircle({\n    focalLengthMm: input.focalLengthMm,\n    aperture: input.aperture,\n    focusDistanceM: input.focusDistanceM,\n    subjectDistanceM: input.subjectDistanceM\n  });\n  const diffraction = calculateAiryDisk({\n    aperture: input.aperture,\n    wavelengthNm: input.spectralBasis.wavelengthNm\n  });\n\n  const radiusMm = Math.hypot(\n    input.fieldPointMm.x,\n    input.fieldPointMm.y\n  );\n\n  return calculatedResult(\n    {\n      context: {\n        field: {\n          imagePointMm: { ...input.fieldPointMm },\n          radiusMm,\n          normalizationRadiusMm: input.fieldNormalizationRadiusMm,\n          normalizedRadius: radiusMm / input.fieldNormalizationRadiusMm\n        },\n        depth: {\n          focusDistanceM: input.focusDistanceM,\n          subjectDistanceM: input.subjectDistanceM\n        },\n        spectralBasis: {\n          kind: \"monochromatic\",\n          wavelengthNm: input.spectralBasis.wavelengthNm\n        },\n        pupil: {\n          kind: \"ideal-circular-f-number-derived\",\n          apertureFNumber: input.aperture,\n          diameterMm: input.focalLengthMm / input.aperture\n        }\n      },\n      contributions: {\n        geometricDefocus: {\n          id: \"geometric-defocus-circle\",\n          diameterMm: defocus.value.diameterMm,\n          provenance: { ...defocus.provenance }\n        },\n        circularDiffraction: {\n          id: \"circular-diffraction-first-zero\",\n          firstZeroDiameterMicrometers:\n            diffraction.value.firstZeroDiameterMicrometers,\n          provenance: { ...diffraction.provenance }\n        }\n      },\n      composition: {\n        status: \"not-composed\",\n        note:\n          \"No combined PSF, MTF, convolution kernel, or scalar sharpness value has been calculated.\"\n      }\n    },\n    \"psf-foundation-separated-components\",\n    \"1.0.0\",\n    [\n      \"Current geometric defocus and ideal circular-pupil diffraction diagnostics are evaluated independently\",\n      \"Field position is explicit context but does not alter the current field-invariant diagnostic primitives\",\n      \"The result intentionally does not combine defocus and diffraction into one blur radius or PSF\",\n      \"Illumination vignetting is excluded because it is a separate throughput-only stage\"\n    ]\n  );\n}\n"]}

package/dist/optics/pupil-vignetting.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Physical vignetting models derived from pupil geometry. They are separate from the
+ * calculateIlluminationVignetting() polynomial, whose coefficients the caller supplies.
+ *
+ * Apply at most one field-throughput model to a signal. Do not stack these results on top of a
+ * supplied field-throughput profile.
+ *
+ * Natural vignetting (relative illumination of an aberration-free system with a uniform Lambertian
+ * exit pupil):
+ * - cosine-fourth: E(theta) / E(0) = cos^4(theta), theta the image-space chief-ray angle with
+ *   tan(theta) = h / z for image height h and exit-pupil distance z (Greivenkamp, OPTI-502 course
+ *   notes, University of Arizona, sec. 11, free. Also see: Slater 1980 Photographic Systems for
+ *   Engineers; Kingslake, Lens Design Fundamentals, 2nd ed., sec. 6.5; Ray, Applied Photographic
+ *   Optics, 3rd ed., sec. 12). It is the small-pupil limit of the next model.
+ * - finite-lambertian-pupil: exact irradiance from a uniform Lambertian disk of radius a at distance z
+ *   onto a parallel plane at lateral offset h (Foote 1915, Bull. Bureau of Standards 12:583):
+ *   E = (pi L / 2) [1 - (z^2 + h^2 - a^2) / sqrt((z^2 + h^2 + a^2)^2 - 4 a^2 h^2)],
+ *   normalised by its on-axis value pi L a^2 / (z^2 + a^2). For a -> 0 it tends to cos^4(theta).
+ *   Pupil aberration and pupil distortion are not modeled.
+ *
+ * Mechanical (optical) vignetting and the cat's-eye pupil:
+ * - At field angle theta, each clipping aperture (a lens barrel or element rim, referred to the
+ *   entrance-pupil plane) appears as a circle of its declared radius. The circle is shifted by
+ *   shiftPerTanFieldMm * tan(theta) along the field azimuth.
+ * - The open pupil is where the entrance-pupil circle overlaps every shifted circle. Off axis, the
+ *   bundle stays circular and centred on the chief ray, and an aperture passes only the part of it
+ *   that it covers (Greivenkamp, OPTI-502 course notes, University of Arizona, sec. 10, free. Also
+ *   see: Kingslake, Lens Design Fundamentals, sec. 6.4; Smith, Modern Optical Engineering, 4th ed.,
+ *   sec. 6.3).
+ * - With one aperture, the area is the exact area of the two-circle overlap.
+ * - With any number of apertures, the exact convex boundary is also returned, sampled as a polygon
+ *   in pupil-plane mm (+X right, +Y up). Use it as a polygon pupil for
+ *   calculatePolygonPupilFraunhoferPsf() or as a mask for createWavefrontPupilGrid().
+ * The combined relative illumination is cos^4(theta) x open-area ratio. This assumes an object at
+ * infinity, a stop imaged without pupil aberration, and an object-space field angle equal to the
+ * chief-ray angle.
+ * @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 type NaturalVignettingModel = "cosine-fourth" | "finite-lambertian-pupil";
+export interface CalculateNaturalVignettingInput {
+    model: NaturalVignettingModel;
+    /** Image-plane point relative to the optical axis, mm. */
+    imagePointMm: {
+        x: number;
+        y: number;
+    };
+    /** Axial distance from the exit pupil to the image plane, mm. */
+    exitPupilDistanceMm: number;
+    /** Exit-pupil diameter, mm; required for finite-lambertian-pupil. */
+    exitPupilDiameterMm?: number;
+}
+export interface NaturalVignetting {
+    model: NaturalVignettingModel;
+    /** Image-space chief-ray angle, radians. */
+    chiefRayAngleRadians: number;
+    /** Relative illumination E / E(axis), in (0, 1]. */
+    relativeIllumination: number;
+    /** Positive exposure loss, stops. */
+    attenuationStops: number;
+    /** cos^4 of the chief-ray angle, reported for comparison. */
+    cosineFourthFactor: number;
+}
+export interface MechanicalVignettingAperture {
+    /** Aperture radius referred to the entrance-pupil plane, mm. */
+    radiusMm: number;
+    /**
+     * Signed shift of the aperture's projected centre per unit tan(field angle), in mm, along the
+     * field azimuth. Positive means toward the field point.
+     */
+    shiftPerTanFieldMm: number;
+}
+export interface CalculateMechanicalVignettingInput {
+    /** Unclipped entrance-pupil diameter, mm. */
+    entrancePupilDiameterMm: number;
+    /** Object-space field angle from the optical axis, degrees, in [0, 90). */
+    fieldAngleDegrees: number;
+    /** Image-plane direction of the field point, degrees counter-clockwise from +X. */
+    fieldAzimuthDegrees: number;
+    /** One through eight clipping apertures. */
+    apertures: readonly MechanicalVignettingAperture[];
+    /** Boundary samples per circle for the polygon, from 16 to 4096 (default 256). */
+    boundarySamplesPerCircle?: number;
+}
+export interface MechanicalVignetting {
+    fieldAngleDegrees: number;
+    fieldAzimuthDegrees: number;
+    entrancePupilAreaSquareMm: number;
+    /** Open area in mm^2. Exact for a single aperture; the polygon area otherwise. */
+    openAreaSquareMm: number;
+    areaMethod: "exact-circle-circle-intersection" | "boundary-polygon";
+    /** Open area / unclipped pupil area, in [0, 1]. */
+    openAreaRatio: number;
+    /** cos^4(field angle). */
+    cosineFourthFactor: number;
+    /** cos^4(theta) x openAreaRatio. */
+    combinedRelativeIllumination: number;
+    /** Counter-clockwise convex boundary of the open pupil (empty when fully vignetted), mm. */
+    openPupilPolygonMm: readonly {
+        x: number;
+        y: number;
+    }[];
+    /** Area centroid of the boundary polygon, mm (null when fully vignetted). */
+    openPupilCentroidMm: {
+        x: number;
+        y: number;
+    } | null;
+}
+/**
+ * Natural (cos^4 or finite Lambertian pupil) relative illumination at one image point.
+ */
+export declare function calculateNaturalVignetting(input: CalculateNaturalVignettingInput): CalculationResult<NaturalVignetting>;
+/**
+ * Mechanical vignetting at one field angle: the open (cat's-eye) pupil from intersecting the
+ * entrance pupil with displaced clipping apertures, its area ratio, and cos^4 x area ratio.
+ */
+export declare function calculateMechanicalVignetting(input: CalculateMechanicalVignettingInput): CalculationResult<MechanicalVignetting>;

package/dist/optics/pupil-vignetting.js

@@ -0,0 +1,264 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Physical vignetting models derived from pupil geometry. They are separate from the
+ * calculateIlluminationVignetting() polynomial, whose coefficients the caller supplies.
+ *
+ * Apply at most one field-throughput model to a signal. Do not stack these results on top of a
+ * supplied field-throughput profile.
+ *
+ * Natural vignetting (relative illumination of an aberration-free system with a uniform Lambertian
+ * exit pupil):
+ * - cosine-fourth: E(theta) / E(0) = cos^4(theta), theta the image-space chief-ray angle with
+ *   tan(theta) = h / z for image height h and exit-pupil distance z (Greivenkamp, OPTI-502 course
+ *   notes, University of Arizona, sec. 11, free. Also see: Slater 1980 Photographic Systems for
+ *   Engineers; Kingslake, Lens Design Fundamentals, 2nd ed., sec. 6.5; Ray, Applied Photographic
+ *   Optics, 3rd ed., sec. 12). It is the small-pupil limit of the next model.
+ * - finite-lambertian-pupil: exact irradiance from a uniform Lambertian disk of radius a at distance z
+ *   onto a parallel plane at lateral offset h (Foote 1915, Bull. Bureau of Standards 12:583):
+ *   E = (pi L / 2) [1 - (z^2 + h^2 - a^2) / sqrt((z^2 + h^2 + a^2)^2 - 4 a^2 h^2)],
+ *   normalised by its on-axis value pi L a^2 / (z^2 + a^2). For a -> 0 it tends to cos^4(theta).
+ *   Pupil aberration and pupil distortion are not modeled.
+ *
+ * Mechanical (optical) vignetting and the cat's-eye pupil:
+ * - At field angle theta, each clipping aperture (a lens barrel or element rim, referred to the
+ *   entrance-pupil plane) appears as a circle of its declared radius. The circle is shifted by
+ *   shiftPerTanFieldMm * tan(theta) along the field azimuth.
+ * - The open pupil is where the entrance-pupil circle overlaps every shifted circle. Off axis, the
+ *   bundle stays circular and centred on the chief ray, and an aperture passes only the part of it
+ *   that it covers (Greivenkamp, OPTI-502 course notes, University of Arizona, sec. 10, free. Also
+ *   see: Kingslake, Lens Design Fundamentals, sec. 6.4; Smith, Modern Optical Engineering, 4th ed.,
+ *   sec. 6.3).
+ * - With one aperture, the area is the exact area of the two-circle overlap.
+ * - With any number of apertures, the exact convex boundary is also returned, sampled as a polygon
+ *   in pupil-plane mm (+X right, +Y up). Use it as a polygon pupil for
+ *   calculatePolygonPupilFraunhoferPsf() or as a mask for createWavefrontPupilGrid().
+ * The combined relative illumination is cos^4(theta) x open-area ratio. This assumes an object at
+ * infinity, a stop imaged without pupil aberration, and an object-space field angle equal to the
+ * chief-ray angle.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
+ */
+import { approximationResult, calculatedResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError, requirePositiveFinite } from "../core/validation.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+function requireFinite(name, value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new InvalidScientificInputError(`${name} must be finite.`);
+    }
+    return value;
+}
+/**
+ * Natural (cos^4 or finite Lambertian pupil) relative illumination at one image point.
+ */
+export function calculateNaturalVignetting(input) {
+    requireInputKeys(input, "calculateNaturalVignetting", ["model", "imagePointMm", "exitPupilDistanceMm", "exitPupilDiameterMm"]);
+    if (input.model !== "cosine-fourth" && input.model !== "finite-lambertian-pupil") {
+        throw new InvalidConfigurationError("model must be cosine-fourth or finite-lambertian-pupil.");
+    }
+    if (typeof input.imagePointMm !== "object" || input.imagePointMm === null) {
+        throw new InvalidConfigurationError("imagePointMm must be an object.");
+    }
+    const h = Math.hypot(requireFinite("imagePointMm.x", input.imagePointMm.x), requireFinite("imagePointMm.y", input.imagePointMm.y));
+    requirePositiveFinite("exitPupilDistanceMm", input.exitPupilDistanceMm);
+    const z = input.exitPupilDistanceMm;
+    const theta = Math.atan2(h, z);
+    const cos2 = (z * z) / (z * z + h * h);
+    const cosineFourthFactor = cos2 * cos2;
+    let relativeIllumination;
+    if (input.model === "cosine-fourth") {
+        if (input.exitPupilDiameterMm !== undefined) {
+            throw new InvalidScientificInputError("exitPupilDiameterMm is not used by the cosine-fourth model; omit it.");
+        }
+        relativeIllumination = cosineFourthFactor;
+    }
+    else {
+        requirePositiveFinite("exitPupilDiameterMm", input.exitPupilDiameterMm);
+        const a = input.exitPupilDiameterMm / 2;
+        const z2 = z * z;
+        const h2 = h * h;
+        const a2 = a * a;
+        // Bracket term written as 2 a^2 (...) / (sqrt + ...) to avoid cancellation for small pupils:
+        // 1 - P / Q = (Q - P) / Q with Q - P = (Q^2 - P^2) / (Q + P) = 4 a^2 z^2 / (Q + P).
+        const p = z2 + h2 - a2;
+        const q = Math.sqrt((z2 + h2 + a2) ** 2 - 4 * a2 * h2);
+        const offAxis = (4 * a2 * z2) / (q * (q + p)) / 2;
+        const onAxis = a2 / (z2 + a2);
+        relativeIllumination = offAxis / onAxis;
+    }
+    if (!(relativeIllumination > 0) || !Number.isFinite(relativeIllumination)) {
+        throw new InvalidScientificInputError("Natural vignetting relative illumination must remain finite and positive.");
+    }
+    relativeIllumination = Math.min(1, relativeIllumination);
+    return calculatedResult({
+        model: input.model,
+        chiefRayAngleRadians: theta,
+        relativeIllumination,
+        attenuationStops: relativeIllumination === 1 ? 0 : -Math.log2(relativeIllumination),
+        cosineFourthFactor
+    }, input.model === "cosine-fourth"
+        ? "cosine-fourth-natural-vignetting"
+        : "finite-lambertian-pupil-natural-vignetting", "1.0.0", [
+        input.model === "cosine-fourth"
+            ? "Relative illumination cos^4 of the image-space chief-ray angle from the exit-pupil centre"
+            : "Exact irradiance from a uniform Lambertian circular exit pupil onto a parallel image plane, normalised on axis",
+        "Aberration-free pupil: pupil aberration, pupil distortion and mechanical clipping are not modeled",
+        "Throughput only; apply at most one field-throughput model, in scene-linear signal"
+    ]);
+}
+/** Exact area of the intersection of two circles. */
+function circleIntersectionArea(r1, r2, d) {
+    if (d >= r1 + r2)
+        return 0;
+    if (d <= Math.abs(r1 - r2))
+        return Math.PI * Math.min(r1, r2) ** 2;
+    const clamp = (v) => Math.max(-1, Math.min(1, v));
+    const a1 = Math.acos(clamp((d * d + r1 * r1 - r2 * r2) / (2 * d * r1)));
+    const a2 = Math.acos(clamp((d * d + r2 * r2 - r1 * r1) / (2 * d * r2)));
+    const k = Math.sqrt(Math.max(0, (-d + r1 + r2) * (d + r1 - r2) * (d - r1 + r2) * (d + r1 + r2)));
+    return r1 * r1 * a1 + r2 * r2 * a2 - k / 2;
+}
+function insideAll(point, circles, skip) {
+    return circles.every((circle, index) => index === skip ||
+        Math.hypot(point.x - circle.x, point.y - circle.y) <= circle.r * (1 + 1e-12));
+}
+/** Convex boundary of the intersection of circles, sampled with vertices on the true boundary. */
+function intersectionPolygon(circles, samples) {
+    const points = [];
+    circles.forEach((circle, index) => {
+        for (let k = 0; k < samples; k += 1) {
+            const angle = (2 * Math.PI * k) / samples;
+            const point = {
+                x: circle.x + circle.r * Math.cos(angle),
+                y: circle.y + circle.r * Math.sin(angle)
+            };
+            if (insideAll(point, circles, index))
+                points.push(point);
+        }
+    });
+    // Pairwise boundary intersection points (the cusps of the cat's eye).
+    for (let i = 0; i < circles.length; i += 1) {
+        for (let j = i + 1; j < circles.length; j += 1) {
+            const a = circles[i];
+            const b = circles[j];
+            const d = Math.hypot(b.x - a.x, b.y - a.y);
+            if (d === 0 || d >= a.r + b.r || d <= Math.abs(a.r - b.r))
+                continue;
+            const along = (d * d + a.r * a.r - b.r * b.r) / (2 * d);
+            const half = Math.sqrt(Math.max(0, a.r * a.r - along * along));
+            const ux = (b.x - a.x) / d;
+            const uy = (b.y - a.y) / d;
+            for (const sign of [1, -1]) {
+                const point = {
+                    x: a.x + along * ux - sign * half * uy,
+                    y: a.y + along * uy + sign * half * ux
+                };
+                if (circles.every((c) => Math.hypot(point.x - c.x, point.y - c.y) <= c.r * (1 + 1e-9))) {
+                    points.push(point);
+                }
+            }
+        }
+    }
+    if (points.length < 3)
+        return [];
+    const cx = points.reduce((s, p) => s + p.x, 0) / points.length;
+    const cy = points.reduce((s, p) => s + p.y, 0) / points.length;
+    points.sort((p, q) => Math.atan2(p.y - cy, p.x - cx) - Math.atan2(q.y - cy, q.x - cx));
+    // Drop coincident neighbours.
+    const unique = points.filter((p, index) => {
+        const prev = points[(index + points.length - 1) % points.length];
+        return index === 0 || Math.hypot(p.x - prev.x, p.y - prev.y) > 1e-12 * (1 + Math.abs(p.x) + Math.abs(p.y));
+    });
+    return unique.length >= 3 ? unique : [];
+}
+function polygonAreaAndCentroid(polygon) {
+    let twiceArea = 0;
+    let cx = 0;
+    let cy = 0;
+    for (let i = 0; i < polygon.length; i += 1) {
+        const a = polygon[i];
+        const b = polygon[(i + 1) % polygon.length];
+        const cross = a.x * b.y - b.x * a.y;
+        twiceArea += cross;
+        cx += (a.x + b.x) * cross;
+        cy += (a.y + b.y) * cross;
+    }
+    return {
+        area: twiceArea / 2,
+        centroid: { x: cx / (3 * twiceArea), y: cy / (3 * twiceArea) }
+    };
+}
+/**
+ * Mechanical vignetting at one field angle: the open (cat's-eye) pupil from intersecting the
+ * entrance pupil with displaced clipping apertures, its area ratio, and cos^4 x area ratio.
+ */
+export function calculateMechanicalVignetting(input) {
+    requireInputKeys(input, "calculateMechanicalVignetting", ["entrancePupilDiameterMm", "fieldAngleDegrees", "fieldAzimuthDegrees", "apertures", "boundarySamplesPerCircle"]);
+    requirePositiveFinite("entrancePupilDiameterMm", input.entrancePupilDiameterMm);
+    const fieldAngleDegrees = requireFinite("fieldAngleDegrees", input.fieldAngleDegrees);
+    if (fieldAngleDegrees < 0 || fieldAngleDegrees >= 90) {
+        throw new InvalidScientificInputError("fieldAngleDegrees must lie in [0, 90).");
+    }
+    const fieldAzimuthDegrees = requireFinite("fieldAzimuthDegrees", input.fieldAzimuthDegrees);
+    if (!Array.isArray(input.apertures) || input.apertures.length < 1 || input.apertures.length > 8) {
+        throw new InvalidScientificInputError("apertures must contain 1 through 8 entries.");
+    }
+    const samples = input.boundarySamplesPerCircle ?? 256;
+    if (!Number.isSafeInteger(samples) || samples < 16 || samples > 4096) {
+        throw new InvalidScientificInputError("boundarySamplesPerCircle must be an integer from 16 through 4096.");
+    }
+    const theta = (fieldAngleDegrees * Math.PI) / 180;
+    const azimuth = (fieldAzimuthDegrees * Math.PI) / 180;
+    const tanTheta = Math.tan(theta);
+    const pupilRadius = input.entrancePupilDiameterMm / 2;
+    const circles = [{ x: 0, y: 0, r: pupilRadius }];
+    input.apertures.forEach((aperture, index) => {
+        if (typeof aperture !== "object" || aperture === null) {
+            throw new InvalidConfigurationError(`apertures[${index}] must be an object.`);
+        }
+        requirePositiveFinite(`apertures[${index}].radiusMm`, aperture.radiusMm);
+        const shift = requireFinite(`apertures[${index}].shiftPerTanFieldMm`, aperture.shiftPerTanFieldMm) *
+            tanTheta;
+        circles.push({
+            x: shift * Math.cos(azimuth),
+            y: shift * Math.sin(azimuth),
+            r: aperture.radiusMm
+        });
+    });
+    const pupilArea = Math.PI * pupilRadius * pupilRadius;
+    const polygon = intersectionPolygon(circles, samples);
+    const geometry = polygon.length >= 3 ? polygonAreaAndCentroid(polygon) : undefined;
+    let openArea;
+    let areaMethod;
+    if (circles.length === 2) {
+        const other = circles[1];
+        openArea = circleIntersectionArea(pupilRadius, other.r, Math.hypot(other.x, other.y));
+        areaMethod = "exact-circle-circle-intersection";
+    }
+    else {
+        openArea = geometry?.area ?? 0;
+        areaMethod = "boundary-polygon";
+    }
+    const openAreaRatio = Math.min(1, Math.max(0, openArea / pupilArea));
+    const cos2 = Math.cos(theta) ** 2;
+    const cosineFourthFactor = cos2 * cos2;
+    return approximationResult({
+        fieldAngleDegrees,
+        fieldAzimuthDegrees,
+        entrancePupilAreaSquareMm: pupilArea,
+        openAreaSquareMm: openArea,
+        areaMethod,
+        openAreaRatio,
+        cosineFourthFactor,
+        combinedRelativeIllumination: cosineFourthFactor * openAreaRatio,
+        openPupilPolygonMm: polygon,
+        openPupilCentroidMm: geometry?.centroid ?? null
+    }, "cats-eye-mechanical-vignetting", "1.0.0", [
+        "Clipping apertures are circles referred to the entrance-pupil plane, displaced linearly with tan(field angle) along the field azimuth",
+        "Open pupil = intersection of the entrance pupil with every displaced aperture; boundary vertices lie exactly on the circles",
+        "Combined relative illumination cos^4(theta) x open-area ratio assumes an object at infinity and no pupil aberration",
+        "Pupil coordinates are metric and aligned with the image plane (+X right, +Y up)",
+        "Geometry is caller-declared; no named-lens barrel data is implied"
+    ]);
+}
+//# sourceMappingURL=pupil-vignetting.js.map