@photivra/engine 1.5.0 → 2.1.0

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

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

package/dist/optics/diffraction.d.ts

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

package/dist/optics/diffraction.js

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

package/dist/optics/diffraction.js.map

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

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

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

package/dist/optics/focus-breathing.js

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

package/dist/optics/focus-breathing.js.map

@@ -1 +1 @@
-{"version":3,"file":"focus-breathing.js","sourceRoot":"","sources":["../../src/optics/focus-breathing.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"focus-breathing.js","sourceRoot":"","sources":["../../src/optics/focus-breathing.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Focus breathing: the change in framing (magnification) as a lens focuses.\n *\n * The declared-scale model applies a caller-supplied projection scale to the ideal Gaussian thin-lens\n * projection for one focus state. Photivra does not guess the scale from focal length, focus\n * distance, lens identity or marketing data. A scale of 1 keeps the thin-lens projection exactly.\n * This is a generic approximation of how projection and magnification change with focus. It is not a\n * calibrated real-lens model. The physical focal length is never changed and stays authoritative.\n *\n * The field-of-view function gives the one-axis field of view (FOV) under this model, and the ideal\n * thin-lens FOV for comparison. A breathingProjectionScale of 1 reproduces the focus-aware thin-lens\n * FOV exactly.\n *\n * The geometric model derives breathing from ideal focusing geometry instead of a declared scale.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport {\n  InvalidScientificInputError,\n  requirePositiveFinite\n} from \"../core/validation.js\";\nimport { calculateThinLensImageDistance } from \"./thin-lens.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport interface CalculateFocusBreathingProjectionInput {\n  /** Physical lens focal length in millimetres. This value is never rewritten. */\n  focalLengthMm: number;\n  /** Selected focus distance in metres. */\n  focusDistanceM: number;\n  /**\n   * Caller-declared projection scale for this focus state, relative to the\n   * ideal thin-lens image distance.\n   *\n   * 1 means no breathing beyond the thin-lens model. Values above 1 narrow the\n   * framing (more magnification). Values below 1 widen it (less\n   * magnification).\n   */\n  breathingProjectionScale: number;\n}\n\nexport interface FocusBreathingProjection {\n  /** Authoritative physical focal length supplied by the caller. */\n  physicalFocalLengthMm: number;\n  focusDistanceM: number;\n  /** Ideal Gaussian thin-lens image distance before breathing adjustment. */\n  idealProjectionDistanceMm: number;\n  /**\n   * Effective projection distance used by the generic breathing model.\n   *\n   * This is a projection (magnification) parameter. It does not replace the\n   * physical focal length.\n   */\n  effectiveProjectionDistanceMm: number;\n  /** Caller-declared scale relative to ideal thin-lens projection. */\n  breathingProjectionScale: number;\n  /** Ideal Gaussian thin-lens magnification at the selected focus distance. */\n  idealMagnification: number;\n  /** Generic breathing-adjusted magnification. */\n  effectiveMagnification: number;\n}\n\nexport interface CalculateFocusBreathingFieldOfViewInput\n  extends CalculateFocusBreathingProjectionInput {\n  /** Sensor/capture dimension corresponding to the requested FOV, in millimetres. */\n  sensorDimensionMm: number;\n}\n\nexport interface FocusBreathingFieldOfView {\n  physicalFocalLengthMm: number;\n  focusDistanceM: number;\n  sensorDimensionMm: number;\n  breathingProjectionScale: number;\n  idealProjectionDistanceMm: number;\n  effectiveProjectionDistanceMm: number;\n  idealDegrees: number;\n  effectiveDegrees: number;\n  deltaDegrees: number;\n}\n\n/**\n * Applies a caller-declared focus-breathing projection scale to the ideal\n * Gaussian thin-lens projection for one focus state.\n *\n * Photivra does not guess the scale from focal length, focus distance, lens\n * identity or marketing data. A scale of 1 keeps the thin-lens projection\n * exactly.\n *\n * This is a generic approximation of how projection and magnification change\n * with focus. It is not a calibrated real-lens model. The physical focal\n * length is never changed and stays authoritative.\n */\nexport function calculateFocusBreathingProjection(\n  input: CalculateFocusBreathingProjectionInput\n): CalculationResult<FocusBreathingProjection> {\n  requireInputKeys(input, \"calculateFocusBreathingProjection\", [\"focalLengthMm\", \"focusDistanceM\", \"breathingProjectionScale\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"focusDistanceM\", input.focusDistanceM);\n  requirePositiveFinite(\n    \"breathingProjectionScale\",\n    input.breathingProjectionScale\n  );\n\n  const thinLens = calculateThinLensImageDistance({\n    focalLengthMm: input.focalLengthMm,\n    objectDistanceM: input.focusDistanceM\n  });\n  const idealProjectionDistanceMm = thinLens.value.imageDistanceMm;\n  const effectiveProjectionDistanceMm =\n    idealProjectionDistanceMm * input.breathingProjectionScale;\n  const objectDistanceMm = input.focusDistanceM * 1000;\n\n  return approximationResult(\n    {\n      physicalFocalLengthMm: input.focalLengthMm,\n      focusDistanceM: input.focusDistanceM,\n      idealProjectionDistanceMm,\n      effectiveProjectionDistanceMm,\n      breathingProjectionScale: input.breathingProjectionScale,\n      idealMagnification: thinLens.value.magnification,\n      effectiveMagnification:\n        effectiveProjectionDistanceMm / objectDistanceMm\n    },\n    \"declared-scale-focus-breathing-projection\",\n    \"1.0.0\",\n    [\n      \"Base projection is the ideal Gaussian thin-lens image distance for the selected focus distance\",\n      \"The focus-breathing projection scale is supplied explicitly by the caller and is not inferred\",\n      \"One declared scale applies uniformly to the current focus state\",\n      \"Physical focal length remains unchanged and authoritative\",\n      \"The model represents focus-dependent framing/magnification only; distortion, pupil magnification, aberrations, and named-lens calibration are not modeled\"\n    ]\n  );\n}\n\n/**\n * Calculates the one-axis field of view under the declared-scale\n * focus-breathing model, and reports the ideal thin-lens field of view for\n * comparison.\n *\n * A breathingProjectionScale of 1 reproduces the focus-aware thin-lens field\n * of view exactly.\n */\nexport function calculateFocusBreathingFieldOfView(\n  input: CalculateFocusBreathingFieldOfViewInput\n): CalculationResult<FocusBreathingFieldOfView> {\n  requireInputKeys(input, \"calculateFocusBreathingFieldOfView\", [\"sensorDimensionMm\", \"focalLengthMm\", \"focusDistanceM\", \"breathingProjectionScale\"]);\n  requirePositiveFinite(\"sensorDimensionMm\", input.sensorDimensionMm);\n\n  const projection = calculateFocusBreathingProjection({\n    focalLengthMm: input.focalLengthMm,\n    focusDistanceM: input.focusDistanceM,\n    breathingProjectionScale: input.breathingProjectionScale\n  });\n  const idealRadians =\n    2 *\n    Math.atan(\n      input.sensorDimensionMm /\n        (2 * projection.value.idealProjectionDistanceMm)\n    );\n  const effectiveRadians =\n    2 *\n    Math.atan(\n      input.sensorDimensionMm /\n        (2 * projection.value.effectiveProjectionDistanceMm)\n    );\n  const idealDegrees = (idealRadians * 180) / Math.PI;\n  const effectiveDegrees = (effectiveRadians * 180) / Math.PI;\n\n  return approximationResult(\n    {\n      physicalFocalLengthMm: input.focalLengthMm,\n      focusDistanceM: input.focusDistanceM,\n      sensorDimensionMm: input.sensorDimensionMm,\n      breathingProjectionScale: input.breathingProjectionScale,\n      idealProjectionDistanceMm:\n        projection.value.idealProjectionDistanceMm,\n      effectiveProjectionDistanceMm:\n        projection.value.effectiveProjectionDistanceMm,\n      idealDegrees,\n      effectiveDegrees,\n      deltaDegrees: effectiveDegrees - idealDegrees\n    },\n    \"declared-scale-focus-breathing-field-of-view\",\n    \"1.0.0\",\n    [\n      ...(projection.provenance.assumptions ?? []),\n      \"Rectilinear field of view is calculated from the declared sensor/capture dimension and effective projection distance\"\n    ]\n  );\n}\n\n/** Ideal focusing geometry for {@link calculateGeometricFocusBreathing}. */\nexport type GeometricFocusingMethod =\n  | \"unit-focus\"\n  | \"fixed-image-distance-internal-focus\";\n\nexport interface CalculateGeometricFocusBreathingInput {\n  /** Focal length at infinity focus, mm. */\n  focalLengthMm: number;\n  /**\n   * Photographic focus distance measured from the subject plane to the sensor (image) plane, in\n   * metres, as marked on lens distance scales.\n   */\n  subjectToSensorDistanceM: number;\n  /** Sensor/capture dimension along the axis of interest, mm. */\n  sensorDimensionMm: number;\n  focusingMethod: GeometricFocusingMethod;\n  /**\n   * Signed distance between the front and rear principal planes (the \"hiatus\"), in mm. Default 0\n   * (thin lens). The subject-to-sensor distance is u + hiatus + v.\n   */\n  principalPlaneSeparationMm?: number;\n}\n\nexport interface GeometricFocusBreathing {\n  focusingMethod: GeometricFocusingMethod;\n  infinityFocalLengthMm: number;\n  /** Focal length of the focused system (changes only for internal focus), mm. */\n  effectiveFocalLengthMm: number;\n  /** Subject distance from the front principal plane, mm. */\n  objectDistanceMm: number;\n  /** Rear principal plane to sensor distance (projection distance), mm. */\n  imageDistanceMm: number;\n  /** Lateral magnification v / u. */\n  magnification: number;\n  /** v / f_infinity: framing scale relative to infinity focus. */\n  projectionScaleRelativeToInfinity: number;\n  /**\n   * v divided by the ideal thin-lens image distance, at objectDistanceMm, of a lens with the same\n   * infinity focal length. Exactly 1 for unit focus. You can pass it as breathingProjectionScale to\n   * calculateFocusBreathingProjection() with focusDistanceM = objectDistanceMm / 1000.\n   */\n  equivalentBreathingProjectionScale: number;\n  fieldOfViewDegrees: number;\n  infinityFieldOfViewDegrees: number;\n  deltaDegrees: number;\n}\n\n/**\n * Focus breathing derived from ideal focusing geometry, instead of a declared scale.\n *\n * - unit-focus: the whole lens moves. u + v = L - hiatus and 1/u + 1/v = 1/f, so\n *   v = (T - sqrt(T^2 - 4 f T)) / 2, where T = L - hiatus >= 4 f. The field narrows as v grows.\n * - fixed-image-distance-internal-focus: an idealised internal-focus lens keeps the rear principal\n *   plane at v = f_infinity and shortens its focal length to f' = u v / (u + v). The angular field\n *   at the rear nodal point then stays the same, and the magnification is f_infinity / u.\n * Both use paraxial Gaussian optics with the nodal points at the principal planes (unit pupil\n * magnification; Greivenkamp, OPTI-502 course notes, University of Arizona, sec. 3 and 5, free. Also\n * see: Kingslake & Johnson, Lens Design Fundamentals, 2nd ed., ch. 3; Ray, Applied Photographic\n * Optics, 3rd ed., ch. 9 and 14). Real internal-focus lenses also move their pupils and\n * principal planes, so modelling their breathing needs a calibrated profile.\n */\nexport function calculateGeometricFocusBreathing(\n  input: CalculateGeometricFocusBreathingInput\n): CalculationResult<GeometricFocusBreathing> {\n  requireInputKeys(input, \"calculateGeometricFocusBreathing\", [\"focalLengthMm\", \"subjectToSensorDistanceM\", \"sensorDimensionMm\", \"focusingMethod\", \"principalPlaneSeparationMm\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n  requirePositiveFinite(\"subjectToSensorDistanceM\", input.subjectToSensorDistanceM);\n  requirePositiveFinite(\"sensorDimensionMm\", input.sensorDimensionMm);\n  const hiatus = input.principalPlaneSeparationMm ?? 0;\n  if (typeof hiatus !== \"number\" || !Number.isFinite(hiatus)) {\n    throw new InvalidScientificInputError(\"principalPlaneSeparationMm must be finite.\");\n  }\n  const f = input.focalLengthMm;\n  const conjugateSum = input.subjectToSensorDistanceM * 1000 - hiatus;\n\n  let imageDistanceMm: number;\n  let objectDistanceMm: number;\n  let effectiveFocalLengthMm: number;\n  if (input.focusingMethod === \"unit-focus\") {\n    if (!(conjugateSum >= 4 * f)) {\n      throw new InvalidScientificInputError(\n        \"Unit focus requires subject-to-sensor distance minus hiatus of at least 4 x focal length (1:1 limit).\"\n      );\n    }\n    // Stable smaller root of v^2 - T v + f T = 0: v = 2 f T / (T + sqrt(T^2 - 4 f T)).\n    imageDistanceMm =\n      (2 * f * conjugateSum) /\n      (conjugateSum + Math.sqrt(conjugateSum * conjugateSum - 4 * f * conjugateSum));\n    objectDistanceMm = conjugateSum - imageDistanceMm;\n    effectiveFocalLengthMm = f;\n  } else if (input.focusingMethod === \"fixed-image-distance-internal-focus\") {\n    imageDistanceMm = f;\n    objectDistanceMm = conjugateSum - f;\n    if (!(objectDistanceMm > f)) {\n      throw new InvalidScientificInputError(\n        \"Internal focus requires the subject to lie more than one focal length in front of the lens.\"\n      );\n    }\n    effectiveFocalLengthMm = (objectDistanceMm * f) / (objectDistanceMm + f);\n  } else {\n    throw new InvalidConfigurationError(\n      \"focusingMethod must be unit-focus or fixed-image-distance-internal-focus.\"\n    );\n  }\n\n  const thinLens = calculateThinLensImageDistance({\n    focalLengthMm: f,\n    objectDistanceM: objectDistanceMm / 1000\n  }).value.imageDistanceMm;\n  const fov = (projection: number): number =>\n    (2 * Math.atan(input.sensorDimensionMm / (2 * projection)) * 180) / Math.PI;\n  const fieldOfViewDegrees = fov(imageDistanceMm);\n  const infinityFieldOfViewDegrees = fov(f);\n\n  return approximationResult(\n    {\n      focusingMethod: input.focusingMethod,\n      infinityFocalLengthMm: f,\n      effectiveFocalLengthMm,\n      objectDistanceMm,\n      imageDistanceMm,\n      magnification: imageDistanceMm / objectDistanceMm,\n      projectionScaleRelativeToInfinity: imageDistanceMm / f,\n      equivalentBreathingProjectionScale:\n        input.focusingMethod === \"unit-focus\" ? 1 : imageDistanceMm / thinLens,\n      fieldOfViewDegrees,\n      infinityFieldOfViewDegrees,\n      deltaDegrees: fieldOfViewDegrees - infinityFieldOfViewDegrees\n    },\n    \"geometric-focus-breathing\",\n    \"1.0.0\",\n    [\n      \"Paraxial Gaussian optics with nodal points at the principal planes (unit pupil magnification)\",\n      input.focusingMethod === \"unit-focus\"\n        ? \"Unit focus: the whole lens moves; focal length is constant\"\n        : \"Idealised internal focus: image distance fixed at the infinity focal length; focal length shortens\",\n      \"Subject-to-sensor distance = object distance + principal-plane separation + image distance\",\n      \"Rectilinear field of view from the rear-principal-plane projection distance; distortion, pupil shifts and named-lens behaviour are not modeled\"\n    ]\n  );\n}\n"]}

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

@@ -1,22 +1,23 @@
 /**
- * Module boundary and integration notes.
- * Parses an explicit focus-plane state from an untrusted JSON boundary. Missing/unknown focus is
- * rejected rather than being interpreted as infinity.
- * Calculates the ideal image-plane distance for an explicit focus state. Finite focus delegates to the
- * existing Gaussian thin-lens calculation, so its numerical result and provenance are unchanged.
- * Infinity focus resolves exactly to the nominal focal length with zero limiting magnification.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Explicit focus state: a finite focus distance, or infinity.
+ *
+ * The parser reads the state from untrusted JSON. Missing or unknown focus is rejected; it is never
+ * read as infinity.
+ *
+ * The image-distance function uses the existing Gaussian thin-lens calculation for finite focus, so
+ * its numbers and provenance are unchanged. Infinity focus gives exactly the nominal focal length,
+ * with a limiting magnification of zero.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type ThinLensImageDistance } from "./thin-lens.js";
 /**
  * Explicit ideal focus-plane state.
  *
- * Finite distance is the longitudinal object-plane distance from the ideal
- * lens principal plane along the camera optical axis. Infinity is a semantic
- * state and is never represented with JavaScript Infinity or a fabricated
- * large distance.
+ * A finite distance is measured along the camera's optical axis, from the
+ * ideal lens principal plane to the object plane. Infinity is a named state.
+ * It is never stored as JavaScript Infinity or as a made-up large distance.
  */
 export type FocusPlane = {
     kind: "finite";
@@ -31,17 +32,16 @@ export interface CalculateFocusPlaneImageDistanceInput {
     focus: FocusPlane;
 }
 /**
- * Parses an explicit focus-plane state from an untrusted JSON boundary.
+ * Parses an explicit focus-plane state from untrusted JSON.
  *
- * Missing/unknown focus is rejected rather than being interpreted as infinity.
+ * Missing or unknown focus is rejected. It is never read as infinity.
  */
 export declare function parseFocusPlane(value: unknown): FocusPlane;
 /**
  * Calculates the ideal image-plane distance for an explicit focus state.
  *
- * Finite focus delegates to the existing Gaussian thin-lens calculation, so
- * its numerical result and provenance are unchanged. Infinity focus resolves
- * exactly to the nominal focal length with zero limiting magnification.
+ * Finite focus uses the existing Gaussian thin-lens calculation, so its
+ * numbers and provenance are unchanged. Infinity focus gives exactly the
+ * nominal focal length, with a limiting magnification of zero.
  */
 export declare function calculateFocusPlaneImageDistance(input: CalculateFocusPlaneImageDistanceInput): CalculationResult<ThinLensImageDistance>;
-//# sourceMappingURL=focus-state.d.ts.map