@photivra/engine 1.5.0 → 2.1.0

package/dist/optics/sensor-psf-quadrature.d.ts

@@ -7,7 +7,7 @@ export interface SensorPsfSourceSample {
     timeSecondsFromOpeningReference: number;
     kernelSampleX: number;
     kernelSampleY: number;
-    /** Optical-axis origin, +X right/+Y down, millimetres; no native crop clipping. */
+    /** Origin on the optical axis, +X right, +Y down, in millimetres. Not clipped to the native crop. */
     sourcePointNativeSensorMm: {
         x: number;
         y: number;
@@ -15,18 +15,18 @@ export interface SensorPsfSourceSample {
     spectralIrradianceWattsPerSquareMeterPerNanometer: number;
 }
 export interface CalculateSensorPsfIrradianceQuadratureInput {
-    /** One instant on the explicitly declared shutter opening reference. */
+    /** One instant, measured on the declared shutter-opening time reference. */
     timeSecondsFromOpeningReference: number;
     spatialQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spatialQuadrature"];
     spectralQuadrature: ReduceSensorSpatioSpectralIrradianceInput["spectralQuadrature"];
-    /** The adapter owns wavelength and image-plane field position for each node. */
+    /** The adapter supplies the wavelength and image-plane field position for each node. */
     psf: Omit<ResolveLensSampledPsfInput, "fieldPointMm" | "wavelengthNm">;
-    /** Schema 0.1.0 PSF profiles lack a basis field; bind that source meaning explicitly. */
+    /** Schema 0.1.0 PSF profiles have no basis field, so the caller states what the source means. */
     psfWavelengthBasis: {
         value: "air" | "vacuum";
         evidence: readonly EvidenceProvenance[];
     };
-    /** Explicit local approximation; a varying PSF grid is not a global convolution. */
+    /** Explicit local approximation. A PSF that varies across a grid is not a global convolution. */
     spatialModel: {
         kind: "destination-local-shift-invariant-approximation";
         evidence: readonly EvidenceProvenance[];
@@ -61,10 +61,12 @@ export interface SensorPsfIrradianceQuadrature {
     }[];
 }
 /**
- * Apply each resolved unit-energy PSF as a destination-local inverse sample sum.
- * Native +Y-down support converts explicitly to optical +Y-up kernel orientation.
- * No boundary extension, missing-support renormalization or extra throughput is
- * applied. This approximation is not a field-dependent forward energy transport.
+ * Applies each resolved unit-energy PSF as an inverse sum of samples around
+ * each destination pixel.
+ *
+ * Support in native coordinates (+Y down) is converted explicitly to the
+ * optical kernel orientation (+Y up). The edges are not extended, missing
+ * support is not renormalized and no extra throughput is applied. This
+ * approximation is not a field-dependent forward transport of energy.
  */
 export declare function calculateSensorPsfIrradianceQuadrature(input: CalculateSensorPsfIrradianceQuadratureInput): CalculationResult<SensorPsfIrradianceQuadrature>;
-//# sourceMappingURL=sensor-psf-quadrature.d.ts.map

package/dist/optics/sensor-psf-quadrature.js

@@ -1,12 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Apply each resolved unit-energy PSF as a destination-local inverse sample sum. Native +Y-down
- * support converts explicitly to optical +Y-up kernel orientation. No boundary extension,
- * missing-support renormalization or extra throughput is applied. This approximation is not a
- * field-dependent forward energy transport.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Applies each resolved PSF (point-spread function, normalized to unit energy) as an inverse sum of
+ * samples around each destination pixel.
+ *
+ * Support offsets in native sensor coordinates (+Y down) are converted explicitly to the optical
+ * kernel orientation (+Y up). The edges are not extended. Missing support is not renormalized. No
+ * extra throughput is applied. This approximation is not a field-dependent forward transport of
+ * energy.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { sensorPsfSourcePoint } from "./sensor-psf-support.js";
 import { approximationResult } from "../core/calculation-result.js";
@@ -15,13 +17,18 @@ import { InvalidScientificInputError, InvalidScientificResultError } from "../co
 import { bindSensorSpatioSpectralSamples, reduceSensorSpatioSpectralIrradiance } from "../sensor/spatio-spectral-reduction.js";
 import { sensorSpatialQuadratureNodeIdentityKey } from "../sensor/spatial-sample-reduction.js";
 import { resolveLensSampledPsf } from "./lens-psf-profile.js";
+import { requireInputKeys } from "../core/record-validation.js";
 /**
- * Apply each resolved unit-energy PSF as a destination-local inverse sample sum.
- * Native +Y-down support converts explicitly to optical +Y-up kernel orientation.
- * No boundary extension, missing-support renormalization or extra throughput is
- * applied. This approximation is not a field-dependent forward energy transport.
+ * Applies each resolved unit-energy PSF as an inverse sum of samples around
+ * each destination pixel.
+ *
+ * Support in native coordinates (+Y down) is converted explicitly to the
+ * optical kernel orientation (+Y up). The edges are not extended, missing
+ * support is not renormalized and no extra throughput is applied. This
+ * approximation is not a field-dependent forward transport of energy.
  */
 export function calculateSensorPsfIrradianceQuadrature(input) {
+    requireInputKeys(input, "calculateSensorPsfIrradianceQuadrature", ["timeSecondsFromOpeningReference", "spatialQuadrature", "spectralQuadrature", "psf", "psfWavelengthBasis", "spatialModel", "inputMeaning", "samples"]);
     if (!Number.isFinite(input.timeSecondsFromOpeningReference) || input.timeSecondsFromOpeningReference < 0) {
         throw new InvalidScientificInputError("PSF source time must be finite and nonnegative.");
     }

package/dist/optics/sensor-psf-quadrature.js.map

@@ -1 +1 @@
-{"version":3,"file":"sensor-psf-quadrature.js","sourceRoot":"","sources":["../../src/optics/sensor-psf-quadrature.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sensor-psf-quadrature.js","sourceRoot":"","sources":["../../src/optics/sensor-psf-quadrature.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Applies each resolved PSF (point-spread function, normalized to unit energy) as an inverse sum of\n * samples around each destination pixel.\n *\n * Support offsets in native sensor coordinates (+Y down) are converted explicitly to the optical\n * kernel orientation (+Y up). The edges are not extended. Missing support is not renormalized. No\n * extra throughput is applied. This approximation is not a field-dependent forward transport of\n * energy.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport { sensorPsfSourcePoint } from \"./sensor-psf-support.js\";\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { parseEvidenceList, type EvidenceProvenance } from \"../core/evidence-provenance.js\";\nimport { InvalidScientificInputError, InvalidScientificResultError } from \"../core/validation.js\";\nimport { bindSensorSpatioSpectralSamples, reduceSensorSpatioSpectralIrradiance,\n  type ReduceSensorSpatioSpectralIrradianceInput, type SensorSpatioSpectralNodeIdentity } from \"../sensor/spatio-spectral-reduction.js\";\nimport { sensorSpatialQuadratureNodeIdentityKey } from \"../sensor/spatial-sample-reduction.js\";\nimport { resolveLensSampledPsf, type ResolveLensSampledPsfInput } from \"./lens-psf-profile.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\n/** One pre-PSF incident irradiance value per explicitly identified kernel tap. */\nexport interface SensorPsfSourceSample {\n  timeSecondsFromOpeningReference: number;\n  kernelSampleX: number;\n  kernelSampleY: number;\n  /** Origin on the optical axis, +X right, +Y down, in millimetres. Not clipped to the native crop. */\n  sourcePointNativeSensorMm: { x: number; y: number };\n  spectralIrradianceWattsPerSquareMeterPerNanometer: number;\n}\n\nexport interface CalculateSensorPsfIrradianceQuadratureInput {\n  /** One instant, measured on the declared shutter-opening time reference. */\n  timeSecondsFromOpeningReference: number;\n  spatialQuadrature: ReduceSensorSpatioSpectralIrradianceInput[\"spatialQuadrature\"];\n  spectralQuadrature: ReduceSensorSpatioSpectralIrradianceInput[\"spectralQuadrature\"];\n  /** The adapter supplies the wavelength and image-plane field position for each node. */\n  psf: Omit<ResolveLensSampledPsfInput, \"fieldPointMm\" | \"wavelengthNm\">;\n  /** Schema 0.1.0 PSF profiles have no basis field, so the caller states what the source means. */\n  psfWavelengthBasis: { value: \"air\" | \"vacuum\"; evidence: readonly EvidenceProvenance[] };\n  /** Explicit local approximation. A PSF that varies across a grid is not a global convolution. */\n  spatialModel: { kind: \"destination-local-shift-invariant-approximation\";\n    evidence: readonly EvidenceProvenance[]; limitation: string };\n  inputMeaning: \"pre-psf-pre-sensor-stack-pre-aa-spectral-irradiance\";\n  /** All nodes and all kernel taps, including zero weights, must be supplied. */\n  samples: readonly { node: SensorSpatioSpectralNodeIdentity; sourceSamples: readonly SensorPsfSourceSample[] }[];\n}\n\nexport interface SensorPsfIrradianceQuadrature {\n  timeSecondsFromOpeningReference: number;\n  wavelengthBasis: \"air\" | \"vacuum\";\n  sourcePlane: \"sensor-package-incident\";\n  outputMeaning: \"post-psf-pre-sensor-stack-pre-aa-irradiance-quadrature\";\n  psfRedistributionApplied: true;\n  localShiftInvarianceEstablished: false;\n  globalFieldEnergyConservationEstablished: false;\n  pupilThroughputApplied: false;\n  sceneProviderExecutionVerified: false;\n  spatialModelEvidence: readonly EvidenceProvenance[];\n  wavelengthBasisEvidence: readonly EvidenceProvenance[];\n  spatialModelLimitation: string;\n  irradianceSamples: ReduceSensorSpatioSpectralIrradianceInput[\"sampleValues\"];\n  reduction: ReturnType<typeof reduceSensorSpatioSpectralIrradiance>;\n  samples: readonly { node: SensorSpatioSpectralNodeIdentity;\n    psf: ReturnType<typeof resolveLensSampledPsf>; sourceSamples: readonly SensorPsfSourceSample[] }[];\n}\n\n/**\n * Applies each resolved unit-energy PSF as an inverse sum of samples around\n * each destination pixel.\n *\n * Support in native coordinates (+Y down) is converted explicitly to the\n * optical kernel orientation (+Y up). The edges are not extended, missing\n * support is not renormalized and no extra throughput is applied. This\n * approximation is not a field-dependent forward transport of energy.\n */\nexport function calculateSensorPsfIrradianceQuadrature(\n  input: CalculateSensorPsfIrradianceQuadratureInput\n): CalculationResult<SensorPsfIrradianceQuadrature> {\n  requireInputKeys(input, \"calculateSensorPsfIrradianceQuadrature\", [\"timeSecondsFromOpeningReference\", \"spatialQuadrature\", \"spectralQuadrature\", \"psf\", \"psfWavelengthBasis\", \"spatialModel\", \"inputMeaning\", \"samples\"]);\n  if (!Number.isFinite(input.timeSecondsFromOpeningReference) || input.timeSecondsFromOpeningReference < 0) {\n    throw new InvalidScientificInputError(\"PSF source time must be finite and nonnegative.\");\n  }\n  if (input.inputMeaning !== \"pre-psf-pre-sensor-stack-pre-aa-spectral-irradiance\" ||\n    input.spatialModel?.kind !== \"destination-local-shift-invariant-approximation\" ||\n    typeof input.spatialModel.limitation !== \"string\" || !input.spatialModel.limitation.trim()) {\n    throw new InvalidScientificInputError(\"PSF execution requires explicit pre-PSF light and a limited local shift-invariant approximation.\");\n  }\n  if ((input.psfWavelengthBasis?.value !== \"air\" && input.psfWavelengthBasis?.value !== \"vacuum\") ||\n    input.psfWavelengthBasis.value !== input.spectralQuadrature.wavelengthBasis) {\n    throw new InvalidScientificInputError(\"PSF wavelength basis must explicitly match the spectral plan.\");\n  }\n  const spatialModelEvidence = parseEvidenceList(input.spatialModel.evidence, \"psfSpatialModel.evidence\");\n  const wavelengthBasisEvidence = parseEvidenceList(input.psfWavelengthBasis.evidence, \"psfWavelengthBasis.evidence\");\n  const bound = bindSensorSpatioSpectralSamples({ ...input, sampleValues: input.samples }, s => s);\n  let count = 0;\n  for (const sample of input.samples) {\n    if (!Array.isArray(sample.sourceSamples)) throw new InvalidScientificInputError(\"PSF source samples must be a dense array.\");\n    count += sample.sourceSamples.length;\n    if (count > 100000) throw new InvalidScientificInputError(\"PSF support exceeds the 100000-source-node budget.\");\n  }\n  const samples: SensorPsfIrradianceQuadrature[\"samples\"][number][] = [];\n  const irradianceSamples: ReduceSensorSpatioSpectralIrradianceInput[\"sampleValues\"][number][] = [];\n  for (const spectral of input.spectralQuadrature.nodes) {\n    for (const spatial of input.spatialQuadrature.nodes) {\n      const spatialNode = { antiAliasingComponentIndex: spatial.antiAliasingComponentIndex,\n        apertureSampleXIndex: spatial.apertureSampleXIndex, apertureSampleYIndex: spatial.apertureSampleYIndex };\n      const node = { spatialNode, spectralSampleIndex: spectral.spectralSampleIndex, wavelengthNanometers: spectral.wavelengthNanometers };\n      const declared = bound.valuesByKey.get(sensorSpatialQuadratureNodeIdentityKey(spatialNode) + \"|\" + spectral.spectralSampleIndex)!;\n      const destination = spatial.preAntiAliasingSourcePointMm;\n      const psf = resolveLensSampledPsf({ ...input.psf, wavelengthNm: spectral.wavelengthNanometers,\n        fieldPointMm: { x: destination.x, y: -destination.y } });\n      const kernel = psf.value.kernel;\n      if (declared.sourceSamples.length !== kernel.widthSamples * kernel.heightSamples) {\n        throw new InvalidScientificInputError(\"PSF source coverage must include every kernel tap without renormalization.\");\n      }\n      const byIndex = new Map<number, SensorPsfSourceSample>();\n      for (const source of declared.sourceSamples) {\n        if (!source || source.timeSecondsFromOpeningReference !== input.timeSecondsFromOpeningReference ||\n          !Number.isSafeInteger(source.kernelSampleX) || !Number.isSafeInteger(source.kernelSampleY) ||\n          source.kernelSampleX < 0 || source.kernelSampleX >= kernel.widthSamples ||\n          source.kernelSampleY < 0 || source.kernelSampleY >= kernel.heightSamples ||\n          !Number.isFinite(source.spectralIrradianceWattsPerSquareMeterPerNanometer) || source.spectralIrradianceWattsPerSquareMeterPerNanometer < 0) {\n          throw new InvalidScientificInputError(\"PSF support requires valid unique tap indices and finite nonnegative irradiance.\");\n        }\n        const index = source.kernelSampleY * kernel.widthSamples + source.kernelSampleX;\n        const { x, y } = sensorPsfSourcePoint(destination, kernel, source.kernelSampleX, source.kernelSampleY);\n        if (byIndex.has(index) || source.sourcePointNativeSensorMm?.x !== x || source.sourcePointNativeSensorMm?.y !== y) {\n          throw new InvalidScientificInputError(\"PSF source coordinate must match the exact inverse kernel offset in native sensor axes.\");\n        }\n        byIndex.set(index, { ...source, sourcePointNativeSensorMm: { x, y } });\n      }\n      const sourceSamples = Array.from({ length: declared.sourceSamples.length }, (_, i) => byIndex.get(i)!);\n      const irradiance = sourceSamples.reduce((sum, s, i) => sum + kernel.normalizedIntensity[i]! * s.spectralIrradianceWattsPerSquareMeterPerNanometer, 0);\n      if (!Number.isFinite(irradiance)) throw new InvalidScientificResultError(\"PSF weighted irradiance must remain finite.\");\n      samples.push({ node, psf, sourceSamples });\n      irradianceSamples.push({ node, spectralIrradianceWattsPerSquareMeterPerNanometer: irradiance });\n    }\n  }\n  const reduction = reduceSensorSpatioSpectralIrradiance({ spatialQuadrature: input.spatialQuadrature,\n    spectralQuadrature: input.spectralQuadrature, sampleValues: irradianceSamples });\n  return approximationResult({ timeSecondsFromOpeningReference: input.timeSecondsFromOpeningReference,\n    wavelengthBasis: input.psfWavelengthBasis.value,\n    sourcePlane: \"sensor-package-incident\", outputMeaning: \"post-psf-pre-sensor-stack-pre-aa-irradiance-quadrature\",\n    psfRedistributionApplied: true, localShiftInvarianceEstablished: false, globalFieldEnergyConservationEstablished: false,\n    pupilThroughputApplied: false, sceneProviderExecutionVerified: false, spatialModelEvidence, wavelengthBasisEvidence,\n    spatialModelLimitation: input.spatialModel.limitation, samples, irradianceSamples, reduction\n  }, \"sensor-local-psf-irradiance-quadrature\", \"0.1.0\", [\n    \"Destination-local shift invariance is a declared approximation, not a proof of full field-dependent energy transport.\",\n    \"Normalized PSF shape is applied once; separate pupil throughput and source transport remain upstream responsibilities.\",\n    \"Complete finite-kernel support does not establish infinite-support convergence or calibrated photographic accuracy.\"\n  ]);\n}\n"]}

package/dist/optics/sensor-psf-support.d.ts

@@ -1,10 +1,13 @@
 /**
- * Module boundary and integration notes.
- * Shared inverse PSF support in native +Y-down coordinates; kernel +Y is up.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Shared inverse support for a PSF (point-spread function). Support offsets use native sensor
+ * coordinates, where +Y is down; the PSF kernel itself uses +Y up.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
+ */
+/**
+ * Shared inverse support for a PSF (point-spread function), in native sensor coordinates (+Y down).
+ * The PSF kernel itself uses +Y up.
  */
-/** Shared inverse PSF support in native +Y-down coordinates; kernel +Y is up. */
 export declare function sensorPsfSourcePoint(destination: {
     x: number;
     y: number;
@@ -17,4 +20,3 @@ export declare function sensorPsfSourcePoint(destination: {
     x: number;
     y: number;
 };
-//# sourceMappingURL=sensor-psf-support.d.ts.map

package/dist/optics/sensor-psf-support.js

@@ -1,11 +1,14 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Shared inverse PSF support in native +Y-down coordinates; kernel +Y is up.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Shared inverse support for a PSF (point-spread function). Support offsets use native sensor
+ * coordinates, where +Y is down; the PSF kernel itself uses +Y up.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
+ */
+/**
+ * Shared inverse support for a PSF (point-spread function), in native sensor coordinates (+Y down).
+ * The PSF kernel itself uses +Y up.
  */
-/** Shared inverse PSF support in native +Y-down coordinates; kernel +Y is up. */
 export function sensorPsfSourcePoint(destination, kernel, kernelSampleX, kernelSampleY) {
     return { x: destination.x - (kernelSampleX - kernel.centerSampleX) * kernel.samplePitchMicrometersX / 1000,
         y: destination.y + (kernelSampleY - kernel.centerSampleY) * kernel.samplePitchMicrometersY / 1000 };

package/dist/optics/sensor-psf-support.js.map

@@ -1 +1 @@
-{"version":3,"file":"sensor-psf-support.js","sourceRoot":"","sources":["../../src/optics/sensor-psf-support.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;GAKG;AAEH,iFAAiF;AACjF,MAAM,UAAU,oBAAoB,CAAC,WAAqC,EAAE,MAE3E,EAAE,aAAqB,EAAE,aAAqB;IAC7C,OAAO,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,GAAG,CAAC,aAAa,GAAC,MAAM,CAAC,aAAa,CAAC,GAAC,MAAM,CAAC,uBAAuB,GAAC,IAAI;QAClG,CAAC,EAAE,WAAW,CAAC,CAAC,GAAG,CAAC,aAAa,GAAC,MAAM,CAAC,aAAa,CAAC,GAAC,MAAM,CAAC,uBAAuB,GAAC,IAAI,EAAE,CAAC;AAClG,CAAC"}
+{"version":3,"file":"sensor-psf-support.js","sourceRoot":"","sources":["../../src/optics/sensor-psf-support.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAqC,EAAE,MAE3E,EAAE,aAAqB,EAAE,aAAqB;IAC7C,OAAO,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,GAAG,CAAC,aAAa,GAAC,MAAM,CAAC,aAAa,CAAC,GAAC,MAAM,CAAC,uBAAuB,GAAC,IAAI;QAClG,CAAC,EAAE,WAAW,CAAC,CAAC,GAAG,CAAC,aAAa,GAAC,MAAM,CAAC,aAAa,CAAC,GAAC,MAAM,CAAC,uBAAuB,GAAC,IAAI,EAAE,CAAC;AAClG,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Shared inverse support for a PSF (point-spread function). Support offsets use native sensor\n * coordinates, where +Y is down; the PSF kernel itself uses +Y up.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\n/**\n * Shared inverse support for a PSF (point-spread function), in native sensor coordinates (+Y down).\n * The PSF kernel itself uses +Y up.\n */\nexport function sensorPsfSourcePoint(destination: { x: number; y: number }, kernel: {\n  centerSampleX: number; centerSampleY: number; samplePitchMicrometersX: number; samplePitchMicrometersY: number;\n}, kernelSampleX: number, kernelSampleY: number): { x: number; y: number } {\n  return { x: destination.x - (kernelSampleX-kernel.centerSampleX)*kernel.samplePitchMicrometersX/1000,\n    y: destination.y + (kernelSampleY-kernel.centerSampleY)*kernel.samplePitchMicrometersY/1000 };\n}\n"]}

package/dist/optics/stray-light.d.ts

@@ -1,17 +1,20 @@
 /**
- * Module boundary and integration notes.
- * Strict generic profile parser; bounds passivity across the whole angular envelope.
- * Adds off-path spectral irradiance before sensor/exposure integration, never after tone mapping.
- * Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant/wavelength.
- * Gaussian templates are independently parameterized approximations, not lens prescription ray
- * tracing.
- * @see docs/DIGITAL_OPTICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and
- * support limits.
+ * Stray light (flare and veiling glare) from bright sources.
+ *
+ * The profile parser is strict. It checks that the profile stays passive (adds no energy) across the
+ * whole range of source angles.
+ *
+ * The model adds off-path spectral irradiance before the sensor integrates the exposure. It never
+ * adds it after tone mapping. Source powers are integrated over profile.referenceEntranceAreaMm2 at
+ * one instant and one wavelength. The Gaussian templates are independently parameterized
+ * approximations, not ray tracing through a lens prescription.
+ * @see docs/DIGITAL_OPTICS_FOUNDATION.md for the equations, units, coordinate conventions, known
+ * blockers and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type GenericOpticalEvidence, type OpticalProfileState } from "./profile-contract.js";
 import type { LensFieldPointMm } from "./radial-distortion.js";
-/** One reflected-path or broad scatter response, normalized over the infinite image plane. */
+/** One ghost (reflection path) or veil (broad scatter) response. Its shape is normalized over the infinite image plane. */
 export interface ParametricStrayLightResponse {
     id: string;
     kind: "ghost" | "veil";
@@ -21,10 +24,10 @@ export interface ParametricStrayLightResponse {
     sigmaMm: number;
     /** Fraction of source power entering this response at the axis. */
     axisPowerFraction: number;
-    /** F(rho)=F(0)*(1+slope*rho²), rho=source angle/max angle. */
+    /** Power fraction versus angle: F(rho) = F(0) * (1 + slope * rho²), where rho = source angle / maximum angle. */
     angularSlope: number;
 }
-/** Single explicit wavelength and exact generic camera state; clean optics only. */
+/** One explicit wavelength and an exact generic camera state. Models clean optics only. */
 export interface LensStrayLightProfile {
     schemaVersion: "0.1.0";
     id: string;
@@ -39,13 +42,13 @@ export interface LensStrayLightProfile {
     referenceEntranceAreaMm2: number;
     responses: readonly ParametricStrayLightResponse[];
 }
-/** Direction remains available beyond the active frame; no crop clipping. */
+/** The direction can lie outside the active frame. It is not clipped to the crop. */
 export interface StrayLightSource {
     id: string;
     fieldAngleXDegrees: number;
     fieldAngleYDegrees: number;
     incidentSpectralPowerWPerNm: number;
-    /** Explicit source/path admission, e.g. a flag/hood decision; not a global hood scalar. */
+    /** Fraction of this source let in, for example after a flag or hood decision. Not a global hood factor. */
     admittedFraction: number;
 }
 export interface StrayLightIrradiance {
@@ -60,7 +63,7 @@ export interface StrayLightIrradiance {
     ghostSpectralIrradianceWPerM2PerNm: number;
     veilSpectralIrradianceWPerM2PerNm: number;
     totalSpectralIrradianceWPerM2PerNm: number;
-    /** If primary-only, the meter excludes these additions; sensor always receives total. */
+    /** If primary-only, the meter leaves these additions out. The sensor always receives the total. */
     meterDomain: "primary-only" | "primary-plus-stray";
     meterSpectralIrradianceWPerM2PerNm: number;
     contributions: readonly {
@@ -70,11 +73,12 @@ export interface StrayLightIrradiance {
         spectralIrradianceWPerM2PerNm: number;
     }[];
 }
-/** Strict generic profile parser; bounds passivity across the whole angular envelope. */
+/** Strict generic profile parser. Checks that the profile adds no energy at any source angle in its range. */
 export declare function parseLensStrayLightProfile(value: unknown): LensStrayLightProfile;
-/** Adds off-path spectral irradiance before sensor/exposure integration, never after tone mapping.
- * Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant/wavelength.
- * Gaussian templates are independently parameterized approximations, not lens prescription ray tracing.
+/** Adds off-path spectral irradiance before the sensor integrates the exposure, never after tone mapping.
+ * Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant and wavelength.
+ * The Gaussian templates are independently parameterized approximations, not ray tracing through a
+ * lens prescription.
  */
 export declare function calculateLensStrayLightIrradiance(input: {
     profile: LensStrayLightProfile;
@@ -88,4 +92,3 @@ export declare function calculateLensStrayLightIrradiance(input: {
     sources: readonly StrayLightSource[];
     meterDomain: "primary-only" | "primary-plus-stray";
 }): CalculationResult<StrayLightIrradiance>;
-//# sourceMappingURL=stray-light.d.ts.map

package/dist/optics/stray-light.js

@@ -1,17 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Strict generic profile parser; bounds passivity across the whole angular envelope.
- * Adds off-path spectral irradiance before sensor/exposure integration, never after tone mapping.
- * Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant/wavelength.
- * Gaussian templates are independently parameterized approximations, not lens prescription ray
- * tracing.
- * @see docs/DIGITAL_OPTICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and
- * support limits.
+ * Stray light (flare and veiling glare) from bright sources.
+ *
+ * The profile parser is strict. It checks that the profile stays passive (adds no energy) across the
+ * whole range of source angles.
+ *
+ * The model adds off-path spectral irradiance before the sensor integrates the exposure. It never
+ * adds it after tone mapping. Source powers are integrated over profile.referenceEntranceAreaMm2 at
+ * one instant and one wavelength. The Gaussian templates are independently parameterized
+ * approximations, not ray tracing through a lens prescription.
+ * @see docs/DIGITAL_OPTICS_FOUNDATION.md for the equations, units, coordinate conventions, known
+ * blockers and support limits.
  */
 import { approximationResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError } from "../core/validation.js";
 import { choice, finite, list, parseEvidence, parseOpticalProfileState, positive, record, requireSameState, textValue } from "./profile-contract.js";
+import { requireInputKeys } from "../core/record-validation.js";
 function fraction(value, name) {
     const n = finite(value, name);
     if (n < 0 || n > 1)
@@ -22,7 +26,7 @@ function point(value) {
     const p = record(value, ["x", "y"]);
     return { x: finite(p.x, "x"), y: finite(p.y, "y") };
 }
-/** Strict generic profile parser; bounds passivity across the whole angular envelope. */
+/** Strict generic profile parser. Checks that the profile adds no energy at any source angle in its range. */
 export function parseLensStrayLightProfile(value) {
     const r = record(value, ["schemaVersion", "id", "version", "state", "evidence", "interaction",
         "wavelengthNm", "wavelengthBasis", "maximumSourceAngleDegrees", "referenceEntranceAreaMm2", "responses"]);
@@ -52,11 +56,13 @@ export function parseLensStrayLightProfile(value) {
         wavelengthNm: positive(r.wavelengthNm, "wavelengthNm"), wavelengthBasis: choice(r.wavelengthBasis, ["air", "vacuum"]),
         maximumSourceAngleDegrees: maximum, referenceEntranceAreaMm2: positive(r.referenceEntranceAreaMm2, "referenceEntranceAreaMm2"), responses };
 }
-/** Adds off-path spectral irradiance before sensor/exposure integration, never after tone mapping.
- * Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant/wavelength.
- * Gaussian templates are independently parameterized approximations, not lens prescription ray tracing.
+/** Adds off-path spectral irradiance before the sensor integrates the exposure, never after tone mapping.
+ * Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant and wavelength.
+ * The Gaussian templates are independently parameterized approximations, not ray tracing through a
+ * lens prescription.
  */
 export function calculateLensStrayLightIrradiance(input) {
+    requireInputKeys(input, "calculateLensStrayLightIrradiance", ["profile", "state", "enabled", "imagePointMm", "wavelengthNm", "wavelengthBasis", "timeSeconds", "primarySpectralIrradianceWPerM2PerNm", "sources", "meterDomain"]);
     const profile = parseLensStrayLightProfile(input.profile);
     requireSameState(profile.state, input.state);
     const p = point(input.imagePointMm), time = finite(input.timeSeconds, "timeSeconds");

package/dist/optics/stray-light.js.map

@@ -1 +1 @@
-{"version":3,"file":"stray-light.js","sourceRoot":"","sources":["../../src/optics/stray-light.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stray-light.js","sourceRoot":"","sources":["../../src/optics/stray-light.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Stray light (flare and veiling glare) from bright sources.\n *\n * The profile parser is strict. It checks that the profile stays passive (adds no energy) across the\n * whole range of source angles.\n *\n * The model adds off-path spectral irradiance before the sensor integrates the exposure. It never\n * adds it after tone mapping. Source powers are integrated over profile.referenceEntranceAreaMm2 at\n * one instant and one wavelength. The Gaussian templates are independently parameterized\n * approximations, not ray tracing through a lens prescription.\n * @see docs/DIGITAL_OPTICS_FOUNDATION.md for the equations, units, coordinate conventions, known\n * blockers and support limits.\n */\n\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport {\n  choice, finite, list, parseEvidence, parseOpticalProfileState, positive, record,\n  requireSameState, textValue, type GenericOpticalEvidence, type OpticalProfileState\n} from \"./profile-contract.js\";\nimport type { LensFieldPointMm } from \"./radial-distortion.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\n/** One ghost (reflection path) or veil (broad scatter) response. Its shape is normalized over the infinite image plane. */\nexport interface ParametricStrayLightResponse {\n  id: string;\n  kind: \"ghost\" | \"veil\";\n  /** Centroid response in mm per degree of the two declared source field angles. */\n  centroidMmPerDegree: readonly [number, number, number, number];\n  offsetMm: LensFieldPointMm;\n  sigmaMm: number;\n  /** Fraction of source power entering this response at the axis. */\n  axisPowerFraction: number;\n  /** Power fraction versus angle: F(rho) = F(0) * (1 + slope * rho²), where rho = source angle / maximum angle. */\n  angularSlope: number;\n}\n/** One explicit wavelength and an exact generic camera state. Models clean optics only. */\nexport interface LensStrayLightProfile {\n  schemaVersion: \"0.1.0\";\n  id: string;\n  version: string;\n  state: OpticalProfileState;\n  evidence: GenericOpticalEvidence;\n  interaction: \"lens-reflections\" | \"sensor-lens-reflections\";\n  wavelengthNm: number;\n  wavelengthBasis: \"air\" | \"vacuum\";\n  maximumSourceAngleDegrees: number;\n  /** Area over which the caller's incident source power was integrated. */\n  referenceEntranceAreaMm2: number;\n  responses: readonly ParametricStrayLightResponse[];\n}\n/** The direction can lie outside the active frame. It is not clipped to the crop. */\nexport interface StrayLightSource {\n  id: string;\n  fieldAngleXDegrees: number;\n  fieldAngleYDegrees: number;\n  incidentSpectralPowerWPerNm: number;\n  /** Fraction of this source let in, for example after a flag or hood decision. Not a global hood factor. */\n  admittedFraction: number;\n}\nexport interface StrayLightIrradiance {\n  profileId: string;\n  profileVersion: string;\n  interaction: LensStrayLightProfile[\"interaction\"];\n  imagePointMm: LensFieldPointMm;\n  wavelengthNm: number;\n  wavelengthBasis: \"air\" | \"vacuum\";\n  timeSeconds: number;\n  primarySpectralIrradianceWPerM2PerNm: number;\n  ghostSpectralIrradianceWPerM2PerNm: number;\n  veilSpectralIrradianceWPerM2PerNm: number;\n  totalSpectralIrradianceWPerM2PerNm: number;\n  /** If primary-only, the meter leaves these additions out. The sensor always receives the total. */\n  meterDomain: \"primary-only\" | \"primary-plus-stray\";\n  meterSpectralIrradianceWPerM2PerNm: number;\n  contributions: readonly { sourceId: string; responseId: string; kind: \"ghost\" | \"veil\"; spectralIrradianceWPerM2PerNm: number }[];\n}\nfunction fraction(value: unknown, name: string): number {\n  const n = finite(value, name);\n  if (n < 0 || n > 1) throw new InvalidScientificInputError(`${name} must lie in [0,1].`);\n  return n;\n}\nfunction point(value: unknown): LensFieldPointMm {\n  const p = record(value, [\"x\", \"y\"]); return { x: finite(p.x, \"x\"), y: finite(p.y, \"y\") };\n}\n/** Strict generic profile parser. Checks that the profile adds no energy at any source angle in its range. */\nexport function parseLensStrayLightProfile(value: unknown): LensStrayLightProfile {\n  const r = record(value, [\"schemaVersion\", \"id\", \"version\", \"state\", \"evidence\", \"interaction\",\n    \"wavelengthNm\", \"wavelengthBasis\", \"maximumSourceAngleDegrees\", \"referenceEntranceAreaMm2\", \"responses\"]);\n  const responses = list(r.responses, 32).map((value): ParametricStrayLightResponse => {\n    const s = record(value, [\"id\", \"kind\", \"centroidMmPerDegree\", \"offsetMm\", \"sigmaMm\", \"axisPowerFraction\", \"angularSlope\"]);\n    const matrix = list(s.centroidMmPerDegree, 4).map((v) => finite(v, \"centroid coefficient\"));\n    if (matrix.length !== 4) throw new InvalidScientificInputError(\"Centroid matrix requires four entries.\");\n    const slope = finite(s.angularSlope, \"angularSlope\");\n    if (slope < -1) throw new InvalidScientificInputError(\"Angular response must be nonnegative.\");\n    return { id: textValue(s.id), kind: choice(s.kind, [\"ghost\", \"veil\"]),\n      centroidMmPerDegree: matrix as [number, number, number, number], offsetMm: point(s.offsetMm),\n      sigmaMm: positive(s.sigmaMm, \"sigmaMm\"), axisPowerFraction: fraction(s.axisPowerFraction, \"axisPowerFraction\"), angularSlope: slope };\n  });\n  if (new Set(responses.map((s) => s.id)).size !== responses.length ||\n      responses.reduce((sum, s) => sum+s.axisPowerFraction, 0) > 1 ||\n      responses.reduce((sum, s) => sum+s.axisPowerFraction*(1+s.angularSlope), 0) > 1) {\n    throw new InvalidScientificInputError(\"Duplicate response or nonpassive total response.\");\n  }\n  const maximum = positive(r.maximumSourceAngleDegrees, \"maximumSourceAngleDegrees\");\n  if (maximum >= 90) throw new InvalidScientificInputError(\"Source angular domain must be below 90 degrees.\");\n  return { schemaVersion: choice(r.schemaVersion, [\"0.1.0\"]), id: textValue(r.id), version: textValue(r.version),\n    state: parseOpticalProfileState(r.state), evidence: parseEvidence(r.evidence),\n    interaction: choice(r.interaction, [\"lens-reflections\", \"sensor-lens-reflections\"]),\n    wavelengthNm: positive(r.wavelengthNm, \"wavelengthNm\"), wavelengthBasis: choice(r.wavelengthBasis, [\"air\", \"vacuum\"]),\n    maximumSourceAngleDegrees: maximum, referenceEntranceAreaMm2: positive(r.referenceEntranceAreaMm2, \"referenceEntranceAreaMm2\"), responses };\n}\n\n/** Adds off-path spectral irradiance before the sensor integrates the exposure, never after tone mapping.\n * Source powers are integrated over profile.referenceEntranceAreaMm2 at this instant and wavelength.\n * The Gaussian templates are independently parameterized approximations, not ray tracing through a\n * lens prescription.\n */\nexport function calculateLensStrayLightIrradiance(input: {\n  profile: LensStrayLightProfile; state: OpticalProfileState; enabled: boolean;\n  imagePointMm: LensFieldPointMm; wavelengthNm: number; wavelengthBasis: \"air\" | \"vacuum\";\n  timeSeconds: number; primarySpectralIrradianceWPerM2PerNm: number;\n  sources: readonly StrayLightSource[]; meterDomain: \"primary-only\" | \"primary-plus-stray\";\n}): CalculationResult<StrayLightIrradiance> {\n  requireInputKeys(input, \"calculateLensStrayLightIrradiance\", [\"profile\", \"state\", \"enabled\", \"imagePointMm\", \"wavelengthNm\", \"wavelengthBasis\", \"timeSeconds\", \"primarySpectralIrradianceWPerM2PerNm\", \"sources\", \"meterDomain\"]);\n  const profile = parseLensStrayLightProfile(input.profile);\n  requireSameState(profile.state, input.state);\n  const p = point(input.imagePointMm), time = finite(input.timeSeconds, \"timeSeconds\");\n  const primary = finite(input.primarySpectralIrradianceWPerM2PerNm, \"primary irradiance\");\n  if (time < 0 || primary < 0 || typeof input.enabled !== \"boolean\") throw new InvalidScientificInputError(\"Invalid time, primary irradiance or enabled state.\");\n  if (input.wavelengthNm !== profile.wavelengthNm || input.wavelengthBasis !== profile.wavelengthBasis) {\n    throw new InvalidScientificInputError(\"Wavelength/basis mismatch; select an explicit profile slice.\");\n  }\n  const meter = choice(input.meterDomain, [\"primary-only\", \"primary-plus-stray\"]);\n  const sources = list(input.sources, 128).map((value): StrayLightSource => {\n    const s = record(value, [\"id\", \"fieldAngleXDegrees\", \"fieldAngleYDegrees\", \"incidentSpectralPowerWPerNm\", \"admittedFraction\"]);\n    const x = finite(s.fieldAngleXDegrees, \"source angle X\"), y = finite(s.fieldAngleYDegrees, \"source angle Y\");\n    const power = finite(s.incidentSpectralPowerWPerNm, \"source power\");\n    if (Math.hypot(x, y) > profile.maximumSourceAngleDegrees || power < 0) throw new InvalidScientificInputError(\"Source outside profile domain or negative power.\");\n    return { id: textValue(s.id), fieldAngleXDegrees: x, fieldAngleYDegrees: y,\n      incidentSpectralPowerWPerNm: power, admittedFraction: fraction(s.admittedFraction, \"admittedFraction\") };\n  });\n  if (new Set(sources.map((s) => s.id)).size !== sources.length) throw new InvalidScientificInputError(\"Duplicate source IDs.\");\n  const contributions: StrayLightIrradiance[\"contributions\"][number][] = [];\n  let ghost = 0, veil = 0;\n  if (input.enabled) for (const s of sources) for (const r of profile.responses) {\n    const m = r.centroidMmPerDegree;\n    const center = { x: m[0]*s.fieldAngleXDegrees+m[1]*s.fieldAngleYDegrees+r.offsetMm.x,\n      y: m[2]*s.fieldAngleXDegrees+m[3]*s.fieldAngleYDegrees+r.offsetMm.y };\n    const rho = Math.hypot(s.fieldAngleXDegrees, s.fieldAngleYDegrees)/profile.maximumSourceAngleDegrees;\n    const response = r.axisPowerFraction*(1+r.angularSlope*rho*rho);\n    // Infinite-plane unit-integral density in 1/mm², converted to 1/m².\n    const densityPerM2 = Math.exp(-((p.x-center.x)**2+(p.y-center.y)**2)/(2*r.sigmaMm**2))/(2*Math.PI*r.sigmaMm**2)*1e6;\n    const irradiance = s.incidentSpectralPowerWPerNm*s.admittedFraction*response*densityPerM2;\n    contributions.push({ sourceId: s.id, responseId: r.id, kind: r.kind, spectralIrradianceWPerM2PerNm: irradiance });\n    if (r.kind === \"ghost\") ghost += irradiance; else veil += irradiance;\n  }\n  const total = primary+ghost+veil;\n  return approximationResult({ profileId: profile.id, profileVersion: profile.version, interaction: profile.interaction,\n    imagePointMm: p, wavelengthNm: profile.wavelengthNm, wavelengthBasis: profile.wavelengthBasis,\n    timeSeconds: time, primarySpectralIrradianceWPerM2PerNm: primary, ghostSpectralIrradianceWPerM2PerNm: ghost,\n    veilSpectralIrradianceWPerM2PerNm: veil, totalSpectralIrradianceWPerM2PerNm: total,\n    meterDomain: meter, meterSpectralIrradianceWPerM2PerNm: meter === \"primary-only\" ? primary : total, contributions },\n  \"parametric-clean-lens-stray-light\", \"0.1.0\", [profile.evidence.basis, profile.evidence.residualNote,\n    \"Additive pre-sensor irradiance; exposure, saturation and noise remain downstream\",\n    \"No diffraction, primary PSF, contamination, cosmetic sprites or calibrated branded signature\",\n    \"One instant and one wavelength slice; no implicit temporal or spectral averaging\"]);\n}\n"]}

package/dist/optics/thin-lens.d.ts

@@ -1,10 +1,11 @@
 /**
- * Module boundary and integration notes.
- * Calculates Gaussian thin-lens image distance: 1/f = 1/s + 1/v where f is focal length, s is object
- * distance, and v is image distance. This is a paraxial ideal-lens model. It does not model real-lens
- * focus breathing, pupil magnification, principal-plane movement, or aberrations.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Gaussian thin-lens image distance: 1/f = 1/s + 1/v, where f is the focal length, s the object
+ * distance and v the image distance.
+ *
+ * This is a paraxial (small-angle) ideal-lens model. It does not model real-lens focus breathing,
+ * pupil magnification, principal-plane movement or aberrations.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 export interface CalculateThinLensImageDistanceInput {
@@ -31,8 +32,8 @@ export interface ThinLensImageDistance {
  *
  * where f is focal length, s is object distance, and v is image distance.
  *
- * This is a paraxial ideal-lens model. It does not model real-lens focus
- * breathing, pupil magnification, principal-plane movement, or aberrations.
+ * This is a paraxial (small-angle) ideal-lens model. It does not model
+ * real-lens focus breathing, pupil magnification, principal-plane movement
+ * or aberrations.
  */
 export declare function calculateThinLensImageDistance(input: CalculateThinLensImageDistanceInput): CalculationResult<ThinLensImageDistance>;
-//# sourceMappingURL=thin-lens.d.ts.map

package/dist/optics/thin-lens.js

@@ -1,14 +1,16 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates Gaussian thin-lens image distance: 1/f = 1/s + 1/v where f is focal length, s is object
- * distance, and v is image distance. This is a paraxial ideal-lens model. It does not model real-lens
- * focus breathing, pupil magnification, principal-plane movement, or aberrations.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Gaussian thin-lens image distance: 1/f = 1/s + 1/v, where f is the focal length, s the object
+ * distance and v the image distance.
+ *
+ * This is a paraxial (small-angle) ideal-lens model. It does not model real-lens focus breathing,
+ * pupil magnification, principal-plane movement or aberrations.
+ * @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 { requireInputKeys } from "../core/record-validation.js";
 /**
  * Calculates Gaussian thin-lens image distance:
  *
@@ -16,10 +18,12 @@ import { InvalidScientificInputError, requirePositiveFinite } from "../core/vali
  *
  * where f is focal length, s is object distance, and v is image distance.
  *
- * This is a paraxial ideal-lens model. It does not model real-lens focus
- * breathing, pupil magnification, principal-plane movement, or aberrations.
+ * This is a paraxial (small-angle) ideal-lens model. It does not model
+ * real-lens focus breathing, pupil magnification, principal-plane movement
+ * or aberrations.
  */
 export function calculateThinLensImageDistance(input) {
+    requireInputKeys(input, "calculateThinLensImageDistance", ["focalLengthMm", "objectDistanceM"]);
     requirePositiveFinite("focalLengthMm", input.focalLengthMm);
     requirePositiveFinite("objectDistanceM", input.objectDistanceM);
     const objectDistanceMm = input.objectDistanceM * 1000;

package/dist/optics/thin-lens.js.map

@@ -1 +1 @@
-{"version":3,"file":"thin-lens.js","sourceRoot":"","sources":["../../src/optics/thin-lens.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;GAOG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAqB/B;;;;;;;;;GASG;AACH,MAAM,UAAU,8BAA8B,CAC5C,KAA0C;IAE1C,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAEhE,MAAM,gBAAgB,GAAG,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC;IACtD,IAAI,gBAAgB,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QAC5C,MAAM,IAAI,2BAA2B,CACnC,sEAAsE,CACvE,CAAC;IACJ,CAAC;IAED,MAAM,eAAe,GACnB,CAAC,KAAK,CAAC,aAAa,GAAG,gBAAgB,CAAC;QACxC,CAAC,gBAAgB,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;IAE3C,OAAO,gBAAgB,CACrB;QACE,eAAe;QACf,aAAa,EAAE,eAAe,GAAG,gBAAgB;QACjD,uBAAuB,EAAE,eAAe,GAAG,KAAK,CAAC,aAAa;KAC/D,EACD,mCAAmC,EACnC,OAAO,EACP;QACE,mCAAmC;QACnC,oDAAoD;QACpD,mEAAmE;KACpE,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"thin-lens.js","sourceRoot":"","sources":["../../src/optics/thin-lens.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;GAQG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAqBhE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,8BAA8B,CAC5C,KAA0C;IAE1C,gBAAgB,CAAC,KAAK,EAAE,gCAAgC,EAAE,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAC,CAAC;IAChG,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAC5D,qBAAqB,CAAC,iBAAiB,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;IAEhE,MAAM,gBAAgB,GAAG,KAAK,CAAC,eAAe,GAAG,IAAI,CAAC;IACtD,IAAI,gBAAgB,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QAC5C,MAAM,IAAI,2BAA2B,CACnC,sEAAsE,CACvE,CAAC;IACJ,CAAC;IAED,MAAM,eAAe,GACnB,CAAC,KAAK,CAAC,aAAa,GAAG,gBAAgB,CAAC;QACxC,CAAC,gBAAgB,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;IAE3C,OAAO,gBAAgB,CACrB;QACE,eAAe;QACf,aAAa,EAAE,eAAe,GAAG,gBAAgB;QACjD,uBAAuB,EAAE,eAAe,GAAG,KAAK,CAAC,aAAa;KAC/D,EACD,mCAAmC,EACnC,OAAO,EACP;QACE,mCAAmC;QACnC,oDAAoD;QACpD,mEAAmE;KACpE,CACF,CAAC;AACJ,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Gaussian thin-lens image distance: 1/f = 1/s + 1/v, where f is the focal length, s the object\n * distance and v the image distance.\n *\n * This is a paraxial (small-angle) ideal-lens model. It does not model real-lens focus breathing,\n * pupil magnification, principal-plane movement or aberrations.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\nexport interface CalculateThinLensImageDistanceInput {\n  /** Lens focal length in millimetres. */\n  focalLengthMm: number;\n  /** Object/focus-plane distance from the lens principal plane in metres. */\n  objectDistanceM: number;\n}\n\nexport interface ThinLensImageDistance {\n  /** Image/sensor-plane distance from the lens principal plane in millimetres. */\n  imageDistanceMm: number;\n  /** Absolute paraxial magnification at the supplied object distance. */\n  magnification: number;\n  /**\n   * Image-distance scale relative to the infinity-focus approximation f.\n   * Values approach 1 as object distance becomes large.\n   */\n  infinityProjectionScale: number;\n}\n\n/**\n * Calculates Gaussian thin-lens image distance:\n *\n * 1/f = 1/s + 1/v\n *\n * where f is focal length, s is object distance, and v is image distance.\n *\n * This is a paraxial (small-angle) ideal-lens model. It does not model\n * real-lens focus breathing, pupil magnification, principal-plane movement\n * or aberrations.\n */\nexport function calculateThinLensImageDistance(\n  input: CalculateThinLensImageDistanceInput\n): CalculationResult<ThinLensImageDistance> {\n  requireInputKeys(input, \"calculateThinLensImageDistance\", [\"focalLengthMm\", \"objectDistanceM\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"objectDistanceM\", input.objectDistanceM);\n\n  const objectDistanceMm = input.objectDistanceM * 1000;\n  if (objectDistanceMm <= input.focalLengthMm) {\n    throw new InvalidScientificInputError(\n      \"objectDistanceM must place the object plane beyond the focal length.\"\n    );\n  }\n\n  const imageDistanceMm =\n    (input.focalLengthMm * objectDistanceMm) /\n    (objectDistanceMm - input.focalLengthMm);\n\n  return calculatedResult(\n    {\n      imageDistanceMm,\n      magnification: imageDistanceMm / objectDistanceMm,\n      infinityProjectionScale: imageDistanceMm / input.focalLengthMm\n    },\n    \"gaussian-thin-lens-image-distance\",\n    \"1.0.0\",\n    [\n      \"Paraxial Gaussian thin-lens model\",\n      \"Distances are measured from ideal principal planes\",\n      \"Real-lens focus breathing and pupil magnification are not modeled\"\n    ]\n  );\n}\n"]}