@photivra/engine 2.14.1 → 2.16.0

package/dist/optics/lens-psf-kernels.js

@@ -34,8 +34,11 @@ import { requireAllowlistedRecord } from "../core/record-validation.js";
 import { IRRADIANCE_CONVOLUTION_LIMITS } from "./irradiance-convolution.js";
 import { markEngineOwnedLensSampledPsfProfile, resolveLensSampledPsf } from "./lens-psf-profile.js";
 export const LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION = "0.1.0";
-/** At most this many wavelengths per call. */
-export const LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS = 64;
+/**
+ * At most this many wavelengths per call: 400, the finest spectral sampling of `simulateCapture` (1 nm over 380–780 nm),
+ * as `DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS.maximumWavelengths` (64 before 2.15.0). The work is linear in the count.
+ */
+export const LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS = 400;
 function positive(value, message) {
     if (typeof value !== "number" || !(value > 0 && value <= Number.MAX_VALUE))
         throw new InvalidConfigurationError(message);
@@ -53,6 +56,19 @@ function integer(value, minimum, maximum, message) {
  * @see docs/WEBGPU.md, "Kernels from a lens PSF profile".
  */
 export function resolveLensPsfConvolutionKernels(input) {
+    return resolveKernels(input, undefined);
+}
+/**
+ * Internal (not exported from the package): `resolveLensPsfConvolutionKernels` with `ownedProfile` used in place of a fresh
+ * private clone of `input.psf.profile`. `ownedProfile` must be a structured clone of that profile that no caller code can
+ * reach, already passed to `markEngineOwnedLensSampledPsfProfile`; repeated calls then share one parse (the clone is frozen
+ * and its parse cached on the first resolve), so N one-wavelength calls cost O(N) instead of O(N²) (2.15.0).
+ * The values are the same: the public function parses its own clone the same way.
+ */
+export function resolveLensPsfConvolutionKernelsWithOwnedProfile(input, ownedProfile) {
+    return resolveKernels(input, ownedProfile);
+}
+function resolveKernels(input, ownedProfile) {
     const r = requireAllowlistedRecord(input, ["schemaVersion", "psf", "spectralWeights", "grid", "patchWidth", "patchHeight", "kernelRadius"], "Invalid lens PSF convolution kernel input.");
     if (r.schemaVersion !== LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION)
         throw new InvalidConfigurationError("Unsupported lens PSF convolution kernel schema.");
@@ -71,7 +87,7 @@ export function resolveLensPsfConvolutionKernels(input) {
         throw new InvalidConfigurationError("Too many patches.");
     const list = r.spectralWeights;
     if (!Array.isArray(list) || list.length < 1 || list.length > LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS) {
-        throw new InvalidConfigurationError("spectralWeights must list 1 to 64 wavelengths.");
+        throw new InvalidConfigurationError("spectralWeights must list 1 to " + LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS + " wavelengths.");
     }
     const spectral = list.map((entry) => {
         const e = requireAllowlistedRecord(entry, ["wavelengthNm", "weight"], "Invalid spectral weight.");
@@ -83,9 +99,10 @@ export function resolveLensPsfConvolutionKernels(input) {
     if (!(totalWeight > 0 && totalWeight <= Number.MAX_VALUE))
         throw new InvalidConfigurationError("At least one spectral weight must be positive.");
     const psf = requireAllowlistedRecord(r.psf, ["profile", "focalLengthMm", "focus", "apertureFNumber", "signedDefocusImagePlaneMicrometers"], "Invalid PSF state.");
-    // One private parse of the profile for every patch and wavelength.
-    const profile = structuredClone(psf.profile);
-    markEngineOwnedLensSampledPsfProfile(profile);
+    // One private parse of the profile for every patch and wavelength (and, with an owned profile, for every call).
+    const profile = ownedProfile ?? structuredClone(psf.profile);
+    if (!ownedProfile)
+        markEngineOwnedLensSampledPsfProfile(profile);
     const state = { ...psf, profile };
     // Resolve every patch and wavelength, splatting straight into one scratch displacement map sized for the largest
     // allowed radius; each patch keeps a copy cropped to its own reach. The common radius is known only at the end.

package/dist/optics/lens-psf-kernels.js.map

@@ -1 +1 @@
-{"version":3,"file":"lens-psf-kernels.js","sourceRoot":"","sources":["../../src/optics/lens-psf-kernels.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Samples the engine's lens PSFs (`LensSampledPsfProfile`, resolved with `resolveLensSampledPsf`) into\n * the per-patch kernels of the isoplanatic convolution (`calculateIrradianceConvolution`, #277).\n *\n * For each patch, the PSF is resolved at the patch centre's field point, in the per-site engine's own\n * coordinates: native sensor millimetres from the optical axis (+Y down), field point (x, −y). Every\n * PSF tap then maps to a site displacement with the per-site quadrature's inverse support\n * (`sensorPsfSourcePoint`): tap (kx, ky) is the source at native offset (−(kx − cx)·pₓ, +(ky − cy)·p_y)\n * from the destination, so its weight lands at displacement u = (kx − cx)·pₓ/sₓ, v = −(ky − cy)·p_y/s_y\n * sites (p: PSF sample pitch, s: site pitch). When p equals s the displacement is taken as the tap offset itself\n * (kx − cx, −(ky − cy)): the rounded quotient (n·p)/p misses the integer n by one unit in the last place for some\n * pitches (for example 3 · 1.6 / 1.6), which split the tap bilinearly or reached one site past the window (2.2.1).\n *\n * - **Exact site sampling.** When every displacement is an integer (equal pitches, integer centre), each\n *   tap's weight goes to one kernel cell. For a destination whose PSF equals its patch's, the\n *   convolution then equals the per-site PSF quadrature at site-centre sources term by term.\n * - **Otherwise (labelled approximation): bilinear splatting.** Each weight is split over the four\n *   surrounding integer displacements with bilinear weights. This is the exact adjoint of bilinear\n *   interpolation, so the convolution equals the per-site quadrature applied to the bilinear interpolant of\n *   the site-centre samples (tested). Weights are conserved.\n *\n * With several wavelengths the kernel is the weight-normalized sum of the per-wavelength kernels. For a\n * spectrally neutral scene that is exactly the per-site engine's spectral sum when the weights are its\n * spectral quadrature weights times the scene spectrum (see docs/WEBGPU.md).\n *\n * The patch approximation (one PSF per patch, indexed by source site) is the caller's choice of patch\n * size; its method error is measured, not bounded (docs/WEBGPU.md, \"Per-fixture rollout\"). Relative\n * pupil throughput stays a separate factor and is reported, never folded into the unit-energy kernels.\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 { IRRADIANCE_CONVOLUTION_LIMITS } from \"./irradiance-convolution.js\";\nimport { markEngineOwnedLensSampledPsfProfile, resolveLensSampledPsf, type ResolveLensSampledPsfInput } from \"./lens-psf-profile.js\";\n\nexport const LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION = \"0.1.0\" as const;\n/** At most this many wavelengths per call. */\nexport const LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS = 64;\n\nexport interface LensPsfConvolutionKernelsInput {\n  schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;\n  /** The optical state, as for `resolveLensSampledPsf`, without the field point and wavelength. */\n  psf: Omit<ResolveLensSampledPsfInput, \"fieldPointMm\" | \"wavelengthNm\">;\n  /** One or more wavelengths with non-negative weights (at least one positive). */\n  spectralWeights: readonly { wavelengthNm: number; weight: number }[];\n  /** The convolution grid: sites, their pitch, and the optical axis in site units (site centres at i + 0.5). */\n  grid: { width: number; height: number; sitePitchMicrometers: { x: number; y: number }; opticalAxisSite: { x: number; y: number } };\n  /** Patch size in sites; the last row and column of patches may be partial. */\n  patchWidth: number;\n  patchHeight: number;\n  /** Kernel radius to use; omitted, the smallest radius that holds every tap. A radius too small to hold the PSF is rejected. */\n  kernelRadius?: number;\n}\n\nexport interface LensPsfConvolutionKernels {\n  schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;\n  kernelRadius: number;\n  patchWidth: number;\n  patchHeight: number;\n  patchColumns: number;\n  patchRows: number;\n  /** `[patchRow][patchColumn][v + r][u + r]`, ready for `IrradianceConvolutionInput.kernels`. */\n  kernels: Float64Array;\n  /** True when every tap landed on one integer displacement (no bilinear splatting). */\n  exactSiteSampling: boolean;\n  maximumKernelSum: number;\n  /** Per patch, row-major: the field point used and the weight-averaged relative pupil throughput (not applied). */\n  patches: readonly { fieldPointMm: { x: number; y: number }; relativePupilThroughputFactor: number; interpolated: boolean }[];\n}\n\nfunction positive(value: unknown, message: string): number {\n  if (typeof value !== \"number\" || !(value > 0 && value <= Number.MAX_VALUE)) throw new InvalidConfigurationError(message);\n  return value;\n}\nfunction integer(value: unknown, minimum: number, maximum: number, message: string): number {\n  if (typeof value !== \"number\" || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new InvalidConfigurationError(message);\n  return value;\n}\n\n/**\n * Builds the per-patch convolution kernels from a sampled lens PSF profile.\n * @param input - See `LensPsfConvolutionKernelsInput`.\n * @returns The kernels and per-patch field points. Success does not imply calibration.\n * @see docs/WEBGPU.md, \"Kernels from a lens PSF profile\".\n */\nexport function resolveLensPsfConvolutionKernels(input: LensPsfConvolutionKernelsInput): CalculationResult<LensPsfConvolutionKernels> {\n  const r = requireAllowlistedRecord(input, [\"schemaVersion\", \"psf\", \"spectralWeights\", \"grid\", \"patchWidth\", \"patchHeight\", \"kernelRadius\"],\n    \"Invalid lens PSF convolution kernel input.\");\n  if (r.schemaVersion !== LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION) throw new InvalidConfigurationError(\"Unsupported lens PSF convolution kernel schema.\");\n  const L = IRRADIANCE_CONVOLUTION_LIMITS;\n  const g = requireAllowlistedRecord(r.grid, [\"width\", \"height\", \"sitePitchMicrometers\", \"opticalAxisSite\"], \"Invalid convolution grid.\");\n  const width = integer(g.width, 1, L.maximumDimension, \"Invalid convolution grid size.\"), height = integer(g.height, 1, L.maximumDimension, \"Invalid convolution grid size.\");\n  const pitch = requireAllowlistedRecord(g.sitePitchMicrometers, [\"x\", \"y\"], \"Invalid site pitch.\");\n  const sx = positive(pitch.x, \"Site pitch must be positive.\"), sy = positive(pitch.y, \"Site pitch must be positive.\");\n  const axis = requireAllowlistedRecord(g.opticalAxisSite, [\"x\", \"y\"], \"Invalid optical axis.\");\n  if (typeof axis.x !== \"number\" || typeof axis.y !== \"number\" || !Number.isFinite(axis.x) || !Number.isFinite(axis.y)) {\n    throw new InvalidConfigurationError(\"The optical axis must be finite site coordinates.\");\n  }\n  const patchWidth = integer(r.patchWidth, 1, width, \"Invalid patch size.\"), patchHeight = integer(r.patchHeight, 1, height, \"Invalid patch size.\");\n  const columns = Math.ceil(width / patchWidth), rows = Math.ceil(height / patchHeight);\n  if (columns * rows > L.maximumPatchCount) throw new InvalidConfigurationError(\"Too many patches.\");\n  const list = r.spectralWeights;\n  if (!Array.isArray(list) || list.length < 1 || list.length > LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS) {\n    throw new InvalidConfigurationError(\"spectralWeights must list 1 to 64 wavelengths.\");\n  }\n  const spectral = list.map((entry: unknown) => {\n    const e = requireAllowlistedRecord(entry, [\"wavelengthNm\", \"weight\"], \"Invalid spectral weight.\");\n    if (typeof e.weight !== \"number\" || !(e.weight >= 0 && e.weight <= Number.MAX_VALUE)) throw new InvalidConfigurationError(\"Spectral weights must be finite and non-negative.\");\n    return { wavelengthNm: positive(e.wavelengthNm, \"Wavelengths must be positive.\"), weight: e.weight };\n  });\n  const totalWeight = spectral.reduce((s, e) => s + e.weight, 0);\n  if (!(totalWeight > 0 && totalWeight <= Number.MAX_VALUE)) throw new InvalidConfigurationError(\"At least one spectral weight must be positive.\");\n  const psf = requireAllowlistedRecord(r.psf, [\"profile\", \"focalLengthMm\", \"focus\", \"apertureFNumber\", \"signedDefocusImagePlaneMicrometers\"], \"Invalid PSF state.\");\n  // One private parse of the profile for every patch and wavelength.\n  const profile = structuredClone(psf.profile);\n  markEngineOwnedLensSampledPsfProfile(profile);\n  const state = { ...(psf as unknown as Omit<ResolveLensSampledPsfInput, \"fieldPointMm\" | \"wavelengthNm\">), profile } as Omit<ResolveLensSampledPsfInput, \"fieldPointMm\" | \"wavelengthNm\">;\n\n  // Resolve every patch and wavelength, splatting straight into one scratch displacement map sized for the largest\n  // allowed radius; each patch keeps a copy cropped to its own reach. The common radius is known only at the end.\n  // Every cell receives its weights in the same order as a direct sum (taps in kernel order, then the four\n  // bilinear corners), so the kernels do not depend on the scratch layout.\n  const M = L.maximumKernelRadius, scratchSize = 2 * M + 1, scratch = new Float64Array(scratchSize * scratchSize);\n  const cropped: { reach: number; values: Float64Array }[] = [], patches: LensPsfConvolutionKernels[\"patches\"][number][] = [];\n  let reach = 0, exact = true, overflow = false;\n  for (let pr = 0; pr < rows; pr++) for (let pc = 0; pc < columns; pc++) {\n    const x0 = pc * patchWidth, y0 = pr * patchHeight, x1 = Math.min(width, x0 + patchWidth), y1 = Math.min(height, y0 + patchHeight);\n    const nativeX = ((x0 + x1) / 2 - axis.x) * sx / 1000, nativeY = ((y0 + y1) / 2 - axis.y) * sy / 1000;\n    const fieldPointMm = { x: nativeX, y: -nativeY };\n    let throughput = 0, interpolated = false, patchReach = 0;\n    for (const { wavelengthNm, weight } of spectral) {\n      if (weight === 0) continue;\n      const resolved = resolveLensSampledPsf({ ...state, fieldPointMm, wavelengthNm }).value, k = resolved.kernel, share = weight / totalWeight;\n      throughput += share * resolved.relativePupilThroughputFactor;\n      if (resolved.resolutionStatus !== \"exact-grid-sample\") interpolated = true;\n      const equalX = k.samplePitchMicrometersX === sx, equalY = k.samplePitchMicrometersY === sy;\n      for (let ky = 0; ky < k.heightSamples; ky++) for (let kx = 0; kx < k.widthSamples; kx++) {\n        const intensity = k.normalizedIntensity[ky * k.widthSamples + kx]!;\n        if (intensity === 0) continue;\n        // With equal pitches the displacement is the tap offset itself: (n·p)/p can miss n by one unit in the last place.\n        const u = equalX ? kx - k.centerSampleX : (kx - k.centerSampleX) * k.samplePitchMicrometersX / sx;\n        const v = equalY ? -(ky - k.centerSampleY) : -(ky - k.centerSampleY) * k.samplePitchMicrometersY / sy;\n        const u0 = Math.floor(u), v0 = Math.floor(v), fu = u - u0, fv = v - v0, w = share * intensity;\n        if (fu !== 0 || fv !== 0) exact = false;\n        for (let corner = 0; corner < 4; corner++) {\n          const du = corner & 1, dv = corner >> 1;\n          const b = du === 0 ? (dv === 0 ? (1 - fu) * (1 - fv) : (1 - fu) * fv) : (dv === 0 ? fu * (1 - fv) : fu * fv);\n          if (b === 0) continue;\n          const cu = u0 + du, cv = v0 + dv;\n          patchReach = Math.max(patchReach, Math.abs(cu), Math.abs(cv));\n          // Past the largest radius the call is rejected below; resolving continues so errors keep their order.\n          if (patchReach > M) { overflow = true; continue; }\n          if (!overflow) scratch[(cv + M) * scratchSize + cu + M]! += w * b;\n        }\n      }\n    }\n    reach = Math.max(reach, patchReach);\n    if (!overflow) {\n      const n = 2 * patchReach + 1, values = new Float64Array(n * n);\n      for (let v = -patchReach; v <= patchReach; v++) {\n        const row = (v + M) * scratchSize + M;\n        values.set(scratch.subarray(row - patchReach, row + patchReach + 1), (v + patchReach) * n);\n        scratch.fill(0, row - patchReach, row + patchReach + 1);\n      }\n      cropped.push({ reach: patchReach, values });\n    }\n    patches.push(Object.freeze({ fieldPointMm: Object.freeze(fieldPointMm), relativePupilThroughputFactor: throughput, interpolated }));\n  }\n  const radius = r.kernelRadius === undefined ? reach : integer(r.kernelRadius, 0, L.maximumKernelRadius, \"Invalid kernel radius.\");\n  if (reach > radius) throw new InvalidConfigurationError(\"The kernel radius is too small for the PSF support; no tap is dropped.\");\n  if (radius > L.maximumKernelRadius) throw new InvalidConfigurationError(\"The PSF support needs a kernel radius above 32 sites.\");\n  const size = 2 * radius + 1, taps = size * size;\n  if (columns * rows * taps > L.maximumKernelWeights) throw new InvalidConfigurationError(\"Too many kernel weights.\");\n  const kernels = new Float64Array(columns * rows * taps);\n  let maximumKernelSum = 0;\n  cropped.forEach(({ reach: q, values }, p) => {\n    const n = 2 * q + 1;\n    let sum = 0;\n    for (let v = 0; v < n; v++) kernels.set(values.subarray(v * n, (v + 1) * n), p * taps + (v - q + radius) * size + radius - q);\n    for (let t = 0; t < taps; t++) sum += kernels[p * taps + t]!;\n    maximumKernelSum = Math.max(maximumKernelSum, sum);\n  });\n  if (maximumKernelSum > L.maximumKernelSum) throw new InvalidConfigurationError(\"Sampled kernels exceed unit energy.\");\n  return approximationResult({ schemaVersion: LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION, kernelRadius: radius, patchWidth, patchHeight,\n    patchColumns: columns, patchRows: rows, kernels, exactSiteSampling: exact, maximumKernelSum, patches: Object.freeze(patches) },\n  \"lens-psf-convolution-kernels\", LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION, [\n    \"One PSF per patch, resolved at the patch centre with resolveLensSampledPsf; indexed by source site in the convolution (isoplanatic patches).\",\n    exact ? \"Every PSF tap maps to one integer site displacement (exact site sampling).\" :\n      \"PSF taps between sites are split bilinearly (the adjoint of bilinear interpolation of site-centre samples); a labelled approximation.\",\n    \"Relative pupil throughput is reported per patch and not applied to the unit-energy kernels.\"\n  ]);\n}\n"]}
+{"version":3,"file":"lens-psf-kernels.js","sourceRoot":"","sources":["../../src/optics/lens-psf-kernels.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Samples the engine's lens PSFs (`LensSampledPsfProfile`, resolved with `resolveLensSampledPsf`) into\n * the per-patch kernels of the isoplanatic convolution (`calculateIrradianceConvolution`, #277).\n *\n * For each patch, the PSF is resolved at the patch centre's field point, in the per-site engine's own\n * coordinates: native sensor millimetres from the optical axis (+Y down), field point (x, −y). Every\n * PSF tap then maps to a site displacement with the per-site quadrature's inverse support\n * (`sensorPsfSourcePoint`): tap (kx, ky) is the source at native offset (−(kx − cx)·pₓ, +(ky − cy)·p_y)\n * from the destination, so its weight lands at displacement u = (kx − cx)·pₓ/sₓ, v = −(ky − cy)·p_y/s_y\n * sites (p: PSF sample pitch, s: site pitch). When p equals s the displacement is taken as the tap offset itself\n * (kx − cx, −(ky − cy)): the rounded quotient (n·p)/p misses the integer n by one unit in the last place for some\n * pitches (for example 3 · 1.6 / 1.6), which split the tap bilinearly or reached one site past the window (2.2.1).\n *\n * - **Exact site sampling.** When every displacement is an integer (equal pitches, integer centre), each\n *   tap's weight goes to one kernel cell. For a destination whose PSF equals its patch's, the\n *   convolution then equals the per-site PSF quadrature at site-centre sources term by term.\n * - **Otherwise (labelled approximation): bilinear splatting.** Each weight is split over the four\n *   surrounding integer displacements with bilinear weights. This is the exact adjoint of bilinear\n *   interpolation, so the convolution equals the per-site quadrature applied to the bilinear interpolant of\n *   the site-centre samples (tested). Weights are conserved.\n *\n * With several wavelengths the kernel is the weight-normalized sum of the per-wavelength kernels. For a\n * spectrally neutral scene that is exactly the per-site engine's spectral sum when the weights are its\n * spectral quadrature weights times the scene spectrum (see docs/WEBGPU.md).\n *\n * The patch approximation (one PSF per patch, indexed by source site) is the caller's choice of patch\n * size; its method error is measured, not bounded (docs/WEBGPU.md, \"Per-fixture rollout\"). Relative\n * pupil throughput stays a separate factor and is reported, never folded into the unit-energy kernels.\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 { IRRADIANCE_CONVOLUTION_LIMITS } from \"./irradiance-convolution.js\";\nimport { markEngineOwnedLensSampledPsfProfile, resolveLensSampledPsf, type ResolveLensSampledPsfInput } from \"./lens-psf-profile.js\";\n\nexport const LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION = \"0.1.0\" as const;\n/**\n * At most this many wavelengths per call: 400, the finest spectral sampling of `simulateCapture` (1 nm over 380–780 nm),\n * as `DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS.maximumWavelengths` (64 before 2.15.0). The work is linear in the count.\n */\nexport const LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS = 400;\n\nexport interface LensPsfConvolutionKernelsInput {\n  schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;\n  /** The optical state, as for `resolveLensSampledPsf`, without the field point and wavelength. */\n  psf: Omit<ResolveLensSampledPsfInput, \"fieldPointMm\" | \"wavelengthNm\">;\n  /** One or more wavelengths with non-negative weights (at least one positive). */\n  spectralWeights: readonly { wavelengthNm: number; weight: number }[];\n  /** The convolution grid: sites, their pitch, and the optical axis in site units (site centres at i + 0.5). */\n  grid: { width: number; height: number; sitePitchMicrometers: { x: number; y: number }; opticalAxisSite: { x: number; y: number } };\n  /** Patch size in sites; the last row and column of patches may be partial. */\n  patchWidth: number;\n  patchHeight: number;\n  /** Kernel radius to use; omitted, the smallest radius that holds every tap. A radius too small to hold the PSF is rejected. */\n  kernelRadius?: number;\n}\n\nexport interface LensPsfConvolutionKernels {\n  schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;\n  kernelRadius: number;\n  patchWidth: number;\n  patchHeight: number;\n  patchColumns: number;\n  patchRows: number;\n  /** `[patchRow][patchColumn][v + r][u + r]`, ready for `IrradianceConvolutionInput.kernels`. */\n  kernels: Float64Array;\n  /** True when every tap landed on one integer displacement (no bilinear splatting). */\n  exactSiteSampling: boolean;\n  maximumKernelSum: number;\n  /** Per patch, row-major: the field point used and the weight-averaged relative pupil throughput (not applied). */\n  patches: readonly { fieldPointMm: { x: number; y: number }; relativePupilThroughputFactor: number; interpolated: boolean }[];\n}\n\nfunction positive(value: unknown, message: string): number {\n  if (typeof value !== \"number\" || !(value > 0 && value <= Number.MAX_VALUE)) throw new InvalidConfigurationError(message);\n  return value;\n}\nfunction integer(value: unknown, minimum: number, maximum: number, message: string): number {\n  if (typeof value !== \"number\" || !Number.isSafeInteger(value) || value < minimum || value > maximum) throw new InvalidConfigurationError(message);\n  return value;\n}\n\n/**\n * Builds the per-patch convolution kernels from a sampled lens PSF profile.\n * @param input - See `LensPsfConvolutionKernelsInput`.\n * @returns The kernels and per-patch field points. Success does not imply calibration.\n * @see docs/WEBGPU.md, \"Kernels from a lens PSF profile\".\n */\nexport function resolveLensPsfConvolutionKernels(input: LensPsfConvolutionKernelsInput): CalculationResult<LensPsfConvolutionKernels> {\n  return resolveKernels(input, undefined);\n}\n\n/**\n * Internal (not exported from the package): `resolveLensPsfConvolutionKernels` with `ownedProfile` used in place of a fresh\n * private clone of `input.psf.profile`. `ownedProfile` must be a structured clone of that profile that no caller code can\n * reach, already passed to `markEngineOwnedLensSampledPsfProfile`; repeated calls then share one parse (the clone is frozen\n * and its parse cached on the first resolve), so N one-wavelength calls cost O(N) instead of O(N²) (2.15.0).\n * The values are the same: the public function parses its own clone the same way.\n */\nexport function resolveLensPsfConvolutionKernelsWithOwnedProfile(input: LensPsfConvolutionKernelsInput, ownedProfile: object): CalculationResult<LensPsfConvolutionKernels> {\n  return resolveKernels(input, ownedProfile);\n}\n\nfunction resolveKernels(input: LensPsfConvolutionKernelsInput, ownedProfile: object | undefined): CalculationResult<LensPsfConvolutionKernels> {\n  const r = requireAllowlistedRecord(input, [\"schemaVersion\", \"psf\", \"spectralWeights\", \"grid\", \"patchWidth\", \"patchHeight\", \"kernelRadius\"],\n    \"Invalid lens PSF convolution kernel input.\");\n  if (r.schemaVersion !== LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION) throw new InvalidConfigurationError(\"Unsupported lens PSF convolution kernel schema.\");\n  const L = IRRADIANCE_CONVOLUTION_LIMITS;\n  const g = requireAllowlistedRecord(r.grid, [\"width\", \"height\", \"sitePitchMicrometers\", \"opticalAxisSite\"], \"Invalid convolution grid.\");\n  const width = integer(g.width, 1, L.maximumDimension, \"Invalid convolution grid size.\"), height = integer(g.height, 1, L.maximumDimension, \"Invalid convolution grid size.\");\n  const pitch = requireAllowlistedRecord(g.sitePitchMicrometers, [\"x\", \"y\"], \"Invalid site pitch.\");\n  const sx = positive(pitch.x, \"Site pitch must be positive.\"), sy = positive(pitch.y, \"Site pitch must be positive.\");\n  const axis = requireAllowlistedRecord(g.opticalAxisSite, [\"x\", \"y\"], \"Invalid optical axis.\");\n  if (typeof axis.x !== \"number\" || typeof axis.y !== \"number\" || !Number.isFinite(axis.x) || !Number.isFinite(axis.y)) {\n    throw new InvalidConfigurationError(\"The optical axis must be finite site coordinates.\");\n  }\n  const patchWidth = integer(r.patchWidth, 1, width, \"Invalid patch size.\"), patchHeight = integer(r.patchHeight, 1, height, \"Invalid patch size.\");\n  const columns = Math.ceil(width / patchWidth), rows = Math.ceil(height / patchHeight);\n  if (columns * rows > L.maximumPatchCount) throw new InvalidConfigurationError(\"Too many patches.\");\n  const list = r.spectralWeights;\n  if (!Array.isArray(list) || list.length < 1 || list.length > LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS) {\n    throw new InvalidConfigurationError(\"spectralWeights must list 1 to \" + LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS + \" wavelengths.\");\n  }\n  const spectral = list.map((entry: unknown) => {\n    const e = requireAllowlistedRecord(entry, [\"wavelengthNm\", \"weight\"], \"Invalid spectral weight.\");\n    if (typeof e.weight !== \"number\" || !(e.weight >= 0 && e.weight <= Number.MAX_VALUE)) throw new InvalidConfigurationError(\"Spectral weights must be finite and non-negative.\");\n    return { wavelengthNm: positive(e.wavelengthNm, \"Wavelengths must be positive.\"), weight: e.weight };\n  });\n  const totalWeight = spectral.reduce((s, e) => s + e.weight, 0);\n  if (!(totalWeight > 0 && totalWeight <= Number.MAX_VALUE)) throw new InvalidConfigurationError(\"At least one spectral weight must be positive.\");\n  const psf = requireAllowlistedRecord(r.psf, [\"profile\", \"focalLengthMm\", \"focus\", \"apertureFNumber\", \"signedDefocusImagePlaneMicrometers\"], \"Invalid PSF state.\");\n  // One private parse of the profile for every patch and wavelength (and, with an owned profile, for every call).\n  const profile = ownedProfile ?? structuredClone(psf.profile);\n  if (!ownedProfile) markEngineOwnedLensSampledPsfProfile(profile);\n  const state = { ...(psf as unknown as Omit<ResolveLensSampledPsfInput, \"fieldPointMm\" | \"wavelengthNm\">), profile } as Omit<ResolveLensSampledPsfInput, \"fieldPointMm\" | \"wavelengthNm\">;\n\n  // Resolve every patch and wavelength, splatting straight into one scratch displacement map sized for the largest\n  // allowed radius; each patch keeps a copy cropped to its own reach. The common radius is known only at the end.\n  // Every cell receives its weights in the same order as a direct sum (taps in kernel order, then the four\n  // bilinear corners), so the kernels do not depend on the scratch layout.\n  const M = L.maximumKernelRadius, scratchSize = 2 * M + 1, scratch = new Float64Array(scratchSize * scratchSize);\n  const cropped: { reach: number; values: Float64Array }[] = [], patches: LensPsfConvolutionKernels[\"patches\"][number][] = [];\n  let reach = 0, exact = true, overflow = false;\n  for (let pr = 0; pr < rows; pr++) for (let pc = 0; pc < columns; pc++) {\n    const x0 = pc * patchWidth, y0 = pr * patchHeight, x1 = Math.min(width, x0 + patchWidth), y1 = Math.min(height, y0 + patchHeight);\n    const nativeX = ((x0 + x1) / 2 - axis.x) * sx / 1000, nativeY = ((y0 + y1) / 2 - axis.y) * sy / 1000;\n    const fieldPointMm = { x: nativeX, y: -nativeY };\n    let throughput = 0, interpolated = false, patchReach = 0;\n    for (const { wavelengthNm, weight } of spectral) {\n      if (weight === 0) continue;\n      const resolved = resolveLensSampledPsf({ ...state, fieldPointMm, wavelengthNm }).value, k = resolved.kernel, share = weight / totalWeight;\n      throughput += share * resolved.relativePupilThroughputFactor;\n      if (resolved.resolutionStatus !== \"exact-grid-sample\") interpolated = true;\n      const equalX = k.samplePitchMicrometersX === sx, equalY = k.samplePitchMicrometersY === sy;\n      for (let ky = 0; ky < k.heightSamples; ky++) for (let kx = 0; kx < k.widthSamples; kx++) {\n        const intensity = k.normalizedIntensity[ky * k.widthSamples + kx]!;\n        if (intensity === 0) continue;\n        // With equal pitches the displacement is the tap offset itself: (n·p)/p can miss n by one unit in the last place.\n        const u = equalX ? kx - k.centerSampleX : (kx - k.centerSampleX) * k.samplePitchMicrometersX / sx;\n        const v = equalY ? -(ky - k.centerSampleY) : -(ky - k.centerSampleY) * k.samplePitchMicrometersY / sy;\n        const u0 = Math.floor(u), v0 = Math.floor(v), fu = u - u0, fv = v - v0, w = share * intensity;\n        if (fu !== 0 || fv !== 0) exact = false;\n        for (let corner = 0; corner < 4; corner++) {\n          const du = corner & 1, dv = corner >> 1;\n          const b = du === 0 ? (dv === 0 ? (1 - fu) * (1 - fv) : (1 - fu) * fv) : (dv === 0 ? fu * (1 - fv) : fu * fv);\n          if (b === 0) continue;\n          const cu = u0 + du, cv = v0 + dv;\n          patchReach = Math.max(patchReach, Math.abs(cu), Math.abs(cv));\n          // Past the largest radius the call is rejected below; resolving continues so errors keep their order.\n          if (patchReach > M) { overflow = true; continue; }\n          if (!overflow) scratch[(cv + M) * scratchSize + cu + M]! += w * b;\n        }\n      }\n    }\n    reach = Math.max(reach, patchReach);\n    if (!overflow) {\n      const n = 2 * patchReach + 1, values = new Float64Array(n * n);\n      for (let v = -patchReach; v <= patchReach; v++) {\n        const row = (v + M) * scratchSize + M;\n        values.set(scratch.subarray(row - patchReach, row + patchReach + 1), (v + patchReach) * n);\n        scratch.fill(0, row - patchReach, row + patchReach + 1);\n      }\n      cropped.push({ reach: patchReach, values });\n    }\n    patches.push(Object.freeze({ fieldPointMm: Object.freeze(fieldPointMm), relativePupilThroughputFactor: throughput, interpolated }));\n  }\n  const radius = r.kernelRadius === undefined ? reach : integer(r.kernelRadius, 0, L.maximumKernelRadius, \"Invalid kernel radius.\");\n  if (reach > radius) throw new InvalidConfigurationError(\"The kernel radius is too small for the PSF support; no tap is dropped.\");\n  if (radius > L.maximumKernelRadius) throw new InvalidConfigurationError(\"The PSF support needs a kernel radius above 32 sites.\");\n  const size = 2 * radius + 1, taps = size * size;\n  if (columns * rows * taps > L.maximumKernelWeights) throw new InvalidConfigurationError(\"Too many kernel weights.\");\n  const kernels = new Float64Array(columns * rows * taps);\n  let maximumKernelSum = 0;\n  cropped.forEach(({ reach: q, values }, p) => {\n    const n = 2 * q + 1;\n    let sum = 0;\n    for (let v = 0; v < n; v++) kernels.set(values.subarray(v * n, (v + 1) * n), p * taps + (v - q + radius) * size + radius - q);\n    for (let t = 0; t < taps; t++) sum += kernels[p * taps + t]!;\n    maximumKernelSum = Math.max(maximumKernelSum, sum);\n  });\n  if (maximumKernelSum > L.maximumKernelSum) throw new InvalidConfigurationError(\"Sampled kernels exceed unit energy.\");\n  return approximationResult({ schemaVersion: LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION, kernelRadius: radius, patchWidth, patchHeight,\n    patchColumns: columns, patchRows: rows, kernels, exactSiteSampling: exact, maximumKernelSum, patches: Object.freeze(patches) },\n  \"lens-psf-convolution-kernels\", LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION, [\n    \"One PSF per patch, resolved at the patch centre with resolveLensSampledPsf; indexed by source site in the convolution (isoplanatic patches).\",\n    exact ? \"Every PSF tap maps to one integer site displacement (exact site sampling).\" :\n      \"PSF taps between sites are split bilinearly (the adjoint of bilinear interpolation of site-centre samples); a labelled approximation.\",\n    \"Relative pupil throughput is reported per patch and not applied to the unit-energy kernels.\"\n  ]);\n}\n"]}

package/dist/optics/sensor-environment-query.d.ts

@@ -118,6 +118,37 @@ export interface SensorEnvironmentRadianceQuery {
  * computes radiance or renders.
  */
 export declare function calculateSensorEnvironmentRadianceQuery(input: CalculateSensorEnvironmentRadianceQueryInput): CalculationResult<SensorEnvironmentRadianceQuery>;
+/**
+ * @internal The ideal (undistorted) image point of a physical sensor point (+X right, +Y up, mm) and the distortion area
+ * factor 1 / det(d distorted / d ideal) there; the ideal point is the sensor point itself without distortion. Shared by
+ * the mapped query below and the image-space defocus of `simulateCapture` (#548), so both use one arithmetic.
+ */
+export declare function undistortedImagePoint(prepared: PreparedEnvironmentLensFieldMapping, imagePointMm: {
+    x: number;
+    y: number;
+}): {
+    ideal: {
+        x: number;
+        y: number;
+    };
+    distortionAreaFactor: number;
+};
+/**
+ * @internal The forward distortion of an ideal image point (+X right, +Y up, mm) to the physical sensor point, with the
+ * singular values of d distorted / d ideal there (the largest and smallest local scale of the map; 1 and 1 without
+ * distortion). The inverse of {@link undistortedImagePoint} up to its solver's rounding (#548).
+ */
+export declare function distortedImagePoint(prepared: PreparedEnvironmentLensFieldMapping, ideal: {
+    x: number;
+    y: number;
+}): {
+    pointMm: {
+        x: number;
+        y: number;
+    };
+    largestScale: number;
+    smallestScale: number;
+};
 /**
  * @internal Query with a lens field mapping that is already validated. The environment photo-signal
  * planner shares it, so profiles are validated once per plan.

package/dist/optics/sensor-environment-query.js

@@ -106,21 +106,15 @@ export function calculateSensorEnvironmentRadianceQuery(input) {
     ]);
 }
 /**
- * @internal Query with a lens field mapping that is already validated. The environment photo-signal
- * planner shares it, so profiles are validated once per plan.
+ * @internal The ideal (undistorted) image point of a physical sensor point (+X right, +Y up, mm) and the distortion area
+ * factor 1 / det(d distorted / d ideal) there; the ideal point is the sensor point itself without distortion. Shared by
+ * the mapped query below and the image-space defocus of `simulateCapture` (#548), so both use one arithmetic.
  */
-export function calculateMappedSensorEnvironmentRadianceQuery(input, prepared) {
-    if (input.timeReference !== "first-opening-boundary-phase" ||
-        input.environmentDirectionConvention !== "outgoing-radiance-toward-camera") {
-        throw new InvalidScientificInputError("Environment projection requires explicit opening-boundary time and outgoing-toward-camera direction conventions.");
-    }
-    const focus = parseFocusPlane(input.focus);
-    const sourcePointImagePlaneMm = { x: input.sourcePointNativeSensorMm.x, y: -input.sourcePointNativeSensorMm.y };
-    const mapping = prepared.mapping;
-    let ideal = sourcePointImagePlaneMm;
+export function undistortedImagePoint(prepared, imagePointMm) {
+    let ideal = imagePointMm;
     let distortionAreaFactor = 1;
     if (prepared.radial !== undefined) {
-        ideal = calculateInverseRadialSourcePointValue(sourcePointImagePlaneMm, prepared.radial, "sourcePointNativeSensorMm").sourceImagePointMm;
+        ideal = calculateInverseRadialSourcePointValue(imagePointMm, prepared.radial, "sourcePointNativeSensorMm").sourceImagePointMm;
         // Radial map p -> s(r) p: det = s (s + r ds/dr) with r ds/dr = 2 r^2 s'(r^2).
         const { k1, k2, k3 } = prepared.radial.coefficients;
         const r2 = (ideal.x * ideal.x + ideal.y * ideal.y) / prepared.radial.normalizationRadiusMm ** 2;
@@ -129,13 +123,51 @@ export function calculateMappedSensorEnvironmentRadianceQuery(input, prepared) {
         distortionAreaFactor = 1 / (scale * radialDerivative);
     }
     else if (prepared.brownConrady !== undefined) {
-        ideal = brownConradyInverseValue(prepared.brownConrady, sourcePointImagePlaneMm);
+        ideal = brownConradyInverseValue(prepared.brownConrady, imagePointMm);
         const j = brownConradyForwardValue(prepared.brownConrady, ideal).jacobian;
         distortionAreaFactor = 1 / (j[0] * j[3] - j[1] * j[2]);
     }
     if (!(distortionAreaFactor > 0) || !Number.isFinite(distortionAreaFactor)) {
         throw new InvalidScientificInputError("Distortion area factor must remain finite and positive.");
     }
+    return { ideal, distortionAreaFactor };
+}
+/**
+ * @internal The forward distortion of an ideal image point (+X right, +Y up, mm) to the physical sensor point, with the
+ * singular values of d distorted / d ideal there (the largest and smallest local scale of the map; 1 and 1 without
+ * distortion). The inverse of {@link undistortedImagePoint} up to its solver's rounding (#548).
+ */
+export function distortedImagePoint(prepared, ideal) {
+    if (prepared.radial !== undefined) {
+        const { k1, k2, k3 } = prepared.radial.coefficients;
+        const r2 = (ideal.x * ideal.x + ideal.y * ideal.y) / prepared.radial.normalizationRadiusMm ** 2;
+        const scale = 1 + k1 * r2 + k2 * r2 * r2 + k3 * r2 * r2 * r2;
+        // Tangential scale s, radial scale s + r ds/dr (the two eigenvalues of the symmetric Jacobian of p -> s(r) p).
+        const radialDerivative = 1 + 3 * k1 * r2 + 5 * k2 * r2 * r2 + 7 * k3 * r2 * r2 * r2;
+        return { pointMm: { x: ideal.x * scale, y: ideal.y * scale }, largestScale: Math.max(scale, radialDerivative), smallestScale: Math.min(scale, radialDerivative) };
+    }
+    if (prepared.brownConrady !== undefined) {
+        const forward = brownConradyForwardValue(prepared.brownConrady, ideal), [a, b, c, d] = forward.jacobian;
+        // Singular values of [[a, b], [c, d]]: sqrt of the eigenvalues of J^T J.
+        const p = a * a + b * b + c * c + d * d, q = Math.abs(a * d - b * c), root = Math.sqrt(Math.max(0, p * p - 4 * q * q));
+        const largest = Math.sqrt((p + root) / 2);
+        return { pointMm: forward.mappedImagePointMm, largestScale: largest, smallestScale: largest > 0 ? q / largest : 0 };
+    }
+    return { pointMm: { ...ideal }, largestScale: 1, smallestScale: 1 };
+}
+/**
+ * @internal Query with a lens field mapping that is already validated. The environment photo-signal
+ * planner shares it, so profiles are validated once per plan.
+ */
+export function calculateMappedSensorEnvironmentRadianceQuery(input, prepared) {
+    if (input.timeReference !== "first-opening-boundary-phase" ||
+        input.environmentDirectionConvention !== "outgoing-radiance-toward-camera") {
+        throw new InvalidScientificInputError("Environment projection requires explicit opening-boundary time and outgoing-toward-camera direction conventions.");
+    }
+    const focus = parseFocusPlane(input.focus);
+    const sourcePointImagePlaneMm = { x: input.sourcePointNativeSensorMm.x, y: -input.sourcePointNativeSensorMm.y };
+    const mapping = prepared.mapping;
+    const { ideal, distortionAreaFactor } = undistortedImagePoint(prepared, sourcePointImagePlaneMm);
     let projection = null;
     let look;
     let projectionScaleMm;

package/dist/optics/sensor-environment-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"sensor-environment-query.js","sourceRoot":"","sources":["../../src/optics/sensor-environment-query.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Builds an environment radiance request from points on the physical sensor. It uses the existing\n * focus-aware ideal projection and the analytic inverse camera rotation.\n *\n * Native Y (+Y down) is inverted explicitly. The direction sent to the provider points opposite the\n * look ray at exposure start, because radiance travels toward the camera. This module does not\n * intersect the scene, compute radiance or render anything.\n *\n * Optional lens field mapping (2.0):\n * 1. The physical sensor point is inverse-distorted (radial or Brown-Conrady) to the ideal image\n *    point.\n * 2. That point is unprojected with the declared ideal projection (rectilinear, fisheye or\n *    equirectangular), at the same focus-aware projection scale.\n * 3. The ray is rotated to the camera axes at exposure start.\n * The local area factor 1 / det(d distorted / d ideal) is reported. The caller applies it to\n * irradiance exactly once. Without the mapping, the existing rectilinear computation is unchanged.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { applyPhysicalCameraRotation, calculateInverseCameraRotationImageMapping,\n  type CameraAngularVelocityRadPerSec } from \"../motion/camera-rotation.js\";\nimport { lensProjectionDirectionValue, parseLensProjectionModel, type LensProjectionModel } from \"../camera/lens-projection.js\";\nimport {\n  calculateInverseRadialSourcePointValue, validateRadialDistortionProfile, type RadialDistortionProfile, type ValidatedRadialProfile\n} from \"./radial-distortion.js\";\nimport {\n  brownConradyForwardValue, brownConradyInverseValue, validateBrownConradyDistortionProfile,\n  type BrownConradyDistortionProfile, type ValidatedBrownConradyDistortionProfile\n} from \"./brown-conrady-distortion.js\";\nimport { calculateThinLensImageDistance } from \"./thin-lens.js\";\nimport { parseSceneRadianceEvaluationRequest, type SceneRadianceEvaluationRequest } from \"../schema/scene-radiance.js\";\nimport { parseFocusPlane, type FocusPlane } from \"./focus-state.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { hypot3 } from \"../core/portable-math.js\";\n\n/**\n * Lens field mapping between the physical (distorted) sensor point and the scene ray (2.0).\n * `radiometricAreaCorrection` states who applies the distortion area factor. The environment\n * photo signal multiplies irradiance by 1 / det(d distorted / d ideal) exactly once. A supplied\n * field-throughput profile must therefore not include it as well.\n */\nexport interface EnvironmentLensFieldMapping {\n  projectionModel: LensProjectionModel;\n  distortion:\n    | { kind: \"none\" }\n    | { kind: \"radial\"; profile: RadialDistortionProfile }\n    | { kind: \"brown-conrady\"; profile: BrownConradyDistortionProfile };\n  radiometricAreaCorrection: \"inverse-distortion-jacobian\";\n}\n\n/** @internal Parsed mapping with validated profiles, reused across one plan's queries. */\nexport interface PreparedEnvironmentLensFieldMapping {\n  mapping: EnvironmentLensFieldMapping;\n  radial?: ValidatedRadialProfile;\n  brownConrady?: ValidatedBrownConradyDistortionProfile;\n}\n\n/** @internal Strict parse and validation of a lens field mapping. Unknown fields are rejected. */\nexport function prepareEnvironmentLensFieldMapping(value: unknown): PreparedEnvironmentLensFieldMapping {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new InvalidConfigurationError(\"lensFieldMapping must be an object.\");\n  }\n  const record = value as Record<string, unknown>;\n  for (const key of Object.keys(record)) {\n    if (![\"projectionModel\", \"distortion\", \"radiometricAreaCorrection\"].includes(key)) {\n      throw new InvalidConfigurationError(`lensFieldMapping has unknown field ${JSON.stringify(key)}.`);\n    }\n  }\n  if (record.radiometricAreaCorrection !== \"inverse-distortion-jacobian\") {\n    throw new InvalidConfigurationError(\"lensFieldMapping.radiometricAreaCorrection must be \\\"inverse-distortion-jacobian\\\".\");\n  }\n  const projectionModel = parseLensProjectionModel(record.projectionModel);\n  const distortion = record.distortion as EnvironmentLensFieldMapping[\"distortion\"] | undefined;\n  if (typeof distortion !== \"object\" || distortion === null) {\n    throw new InvalidConfigurationError(\"lensFieldMapping.distortion must be an object.\");\n  }\n  if (distortion.kind === \"none\") {\n    return { mapping: { projectionModel, distortion: { kind: \"none\" }, radiometricAreaCorrection: \"inverse-distortion-jacobian\" } };\n  }\n  if (distortion.kind === \"radial\") {\n    const radial = validateRadialDistortionProfile(distortion.profile);\n    return { mapping: { projectionModel, distortion: { kind: \"radial\", profile: distortion.profile },\n      radiometricAreaCorrection: \"inverse-distortion-jacobian\" }, radial };\n  }\n  if (distortion.kind === \"brown-conrady\") {\n    const brownConrady = validateBrownConradyDistortionProfile(distortion.profile);\n    return { mapping: { projectionModel, distortion: { kind: \"brown-conrady\", profile: distortion.profile },\n      radiometricAreaCorrection: \"inverse-distortion-jacobian\" }, brownConrady };\n  }\n  throw new InvalidConfigurationError(\"lensFieldMapping.distortion.kind must be none, radial or brown-conrady.\");\n}\n\nexport interface CalculateSensorEnvironmentRadianceQueryInput {\n  /** Optical sample point before the anti-aliasing filter or PSF. Native +X right, +Y down, in mm from the optical axis. */\n  sourcePointNativeSensorMm: { x: number; y: number };\n  focalLengthMm: number;\n  focus: FocusPlane;\n  angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;\n  /** States that the moment the shutter opens is t=0 in the rotation model. */\n  timeReference: \"first-opening-boundary-phase\";\n  timeSecondsFromOpeningReference: number;\n  /** The request uses the direction radiance travels: toward the camera, opposite the look ray. */\n  environmentDirectionConvention: \"outgoing-radiance-toward-camera\";\n  request: Omit<SceneRadianceEvaluationRequest, \"target\" | \"timeSecondsFromExposureStart\">;\n  /** Optional 2.0 lens field mapping. Omit it for the ideal rectilinear, distortion-free query. */\n  lensFieldMapping?: EnvironmentLensFieldMapping;\n}\n\nexport interface SensorEnvironmentLensFieldMappingResult {\n  projectionModel: LensProjectionModel;\n  distortionKind: \"none\" | \"radial\" | \"brown-conrady\";\n  /** Ideal (undistorted) image-plane point, +X right / +Y up, mm. */\n  idealImagePointMm: { x: number; y: number };\n  /** Projection scale: thin-lens image distance at finite focus, focal length at infinity, mm. */\n  projectionScaleMm: number;\n  /** 1 / det(d distorted / d ideal) at this point; 1 without distortion. */\n  distortionAreaFactor: number;\n}\n\nexport interface SensorEnvironmentRadianceQuery {\n  request: SceneRadianceEvaluationRequest;\n  sourcePointNativeSensorMm: { x: number; y: number };\n  sourcePointImagePlaneMm: { x: number; y: number };\n  referenceLookDirectionUnitVector: { x: number; y: number; z: number };\n  /** Rectilinear rotation mapping. Null when a non-rectilinear lens field mapping is used. */\n  projection: ReturnType<typeof calculateInverseCameraRotationImageMapping> | null;\n  /** Present only when the input declared a lens field mapping. */\n  lensFieldMapping?: SensorEnvironmentLensFieldMappingResult;\n  targetMeaning: \"environment-direction-in-exposure-start-camera-axes\";\n  directionConvention: \"outgoing-radiance-toward-camera\";\n  geometricRayProjectionCalculated: true;\n  sceneIntersectionCalculated: false;\n  visibilityCalculated: false;\n  providerExecuted: false;\n}\n\n/**\n * Builds an environment radiance request from points on the physical sensor,\n * using the existing focus-aware ideal projection and the analytic inverse\n * camera rotation.\n *\n * Native Y (+Y down) is inverted explicitly. The provider direction points\n * opposite the look ray at exposure start. Nothing intersects the scene,\n * computes radiance or renders.\n */\nexport function calculateSensorEnvironmentRadianceQuery(\n  input: CalculateSensorEnvironmentRadianceQueryInput\n): CalculationResult<SensorEnvironmentRadianceQuery> {\n  requireInputKeys(input, \"calculateSensorEnvironmentRadianceQuery\", [\"sourcePointNativeSensorMm\", \"focalLengthMm\", \"focus\", \"angularVelocityRadPerSec\", \"timeReference\", \"timeSecondsFromOpeningReference\", \"environmentDirectionConvention\", \"request\", \"lensFieldMapping\"]);\n  if (input.lensFieldMapping !== undefined) {\n    return calculateMappedSensorEnvironmentRadianceQuery(input, prepareEnvironmentLensFieldMapping(input.lensFieldMapping));\n  }\n  if (input.timeReference !== \"first-opening-boundary-phase\" ||\n    input.environmentDirectionConvention !== \"outgoing-radiance-toward-camera\") {\n    throw new InvalidScientificInputError(\"Environment projection requires explicit opening-boundary time and outgoing-toward-camera direction conventions.\");\n  }\n  const focus = parseFocusPlane(input.focus);\n  const sourcePointImagePlaneMm = { x: input.sourcePointNativeSensorMm.x, y: -input.sourcePointNativeSensorMm.y };\n  const projection = calculateInverseCameraRotationImageMapping({ focalLengthMm: input.focalLengthMm,\n    imagePointMm: sourcePointImagePlaneMm, angularVelocityRadPerSec: input.angularVelocityRadPerSec,\n    timeSecondsFromExposureStart: input.timeSecondsFromOpeningReference,\n    ...(focus.kind === \"finite\" ? { focusDistanceM: focus.distanceM } : {}) });\n  const point = projection.value.referenceImagePointMm, z = projection.value.projectionDistanceMm;\n  const length = hypot3(point.x, point.y, z);\n  const referenceLookDirectionUnitVector = { x: point.x/length, y: point.y/length, z: z/length };\n  const ray = referenceLookDirectionUnitVector;\n  const request = parseSceneRadianceEvaluationRequest({ ...input.request,\n    timeSecondsFromExposureStart: input.timeSecondsFromOpeningReference,\n    target: { kind: \"environment-direction\", outgoingDirectionUnitVector: { x: -ray.x, y: -ray.y, z: -ray.z } } });\n  return approximationResult({ request, sourcePointNativeSensorMm: { ...input.sourcePointNativeSensorMm },\n    sourcePointImagePlaneMm, referenceLookDirectionUnitVector, projection,\n    targetMeaning: \"environment-direction-in-exposure-start-camera-axes\", directionConvention: \"outgoing-radiance-toward-camera\",\n    geometricRayProjectionCalculated: true, sceneIntersectionCalculated: false, visibilityCalculated: false, providerExecuted: false\n  }, \"sensor-environment-radiance-query\", \"0.1.0\", [\n    \"Ideal focus-aware rectilinear projection and constant-axis pure camera rotation; reference ray must stay in the forward hemisphere.\",\n    \"The environment and rotation reference axes coincide with camera axes at the first opening boundary by explicit convention.\",\n    \"Lens distortion, breathing, chromatic field mapping, translation/parallax and scene intersections remain separate.\"\n  ]);\n}\n\n/**\n * @internal Query with a lens field mapping that is already validated. The environment photo-signal\n * planner shares it, so profiles are validated once per plan.\n */\nexport function calculateMappedSensorEnvironmentRadianceQuery(\n  input: CalculateSensorEnvironmentRadianceQueryInput,\n  prepared: PreparedEnvironmentLensFieldMapping\n): CalculationResult<SensorEnvironmentRadianceQuery> {\n  if (input.timeReference !== \"first-opening-boundary-phase\" ||\n    input.environmentDirectionConvention !== \"outgoing-radiance-toward-camera\") {\n    throw new InvalidScientificInputError(\"Environment projection requires explicit opening-boundary time and outgoing-toward-camera direction conventions.\");\n  }\n  const focus = parseFocusPlane(input.focus);\n  const sourcePointImagePlaneMm = { x: input.sourcePointNativeSensorMm.x, y: -input.sourcePointNativeSensorMm.y };\n  const mapping = prepared.mapping;\n  let ideal = sourcePointImagePlaneMm;\n  let distortionAreaFactor = 1;\n  if (prepared.radial !== undefined) {\n    ideal = calculateInverseRadialSourcePointValue(sourcePointImagePlaneMm, prepared.radial, \"sourcePointNativeSensorMm\").sourceImagePointMm;\n    // Radial map p -> s(r) p: det = s (s + r ds/dr) with r ds/dr = 2 r^2 s'(r^2).\n    const { k1, k2, k3 } = prepared.radial.coefficients;\n    const r2 = (ideal.x*ideal.x+ideal.y*ideal.y)/prepared.radial.normalizationRadiusMm**2;\n    const scale = 1+k1*r2+k2*r2*r2+k3*r2*r2*r2;\n    const radialDerivative = 1+3*k1*r2+5*k2*r2*r2+7*k3*r2*r2*r2;\n    distortionAreaFactor = 1/(scale*radialDerivative);\n  } else if (prepared.brownConrady !== undefined) {\n    ideal = brownConradyInverseValue(prepared.brownConrady, sourcePointImagePlaneMm);\n    const j = brownConradyForwardValue(prepared.brownConrady, ideal).jacobian;\n    distortionAreaFactor = 1/(j[0]*j[3]-j[1]*j[2]);\n  }\n  if (!(distortionAreaFactor > 0) || !Number.isFinite(distortionAreaFactor)) {\n    throw new InvalidScientificInputError(\"Distortion area factor must remain finite and positive.\");\n  }\n  let projection: ReturnType<typeof calculateInverseCameraRotationImageMapping> | null = null;\n  let look: { x: number; y: number; z: number };\n  let projectionScaleMm: number;\n  if (mapping.projectionModel === \"rectilinear\") {\n    projection = calculateInverseCameraRotationImageMapping({ focalLengthMm: input.focalLengthMm,\n      imagePointMm: ideal, angularVelocityRadPerSec: input.angularVelocityRadPerSec,\n      timeSecondsFromExposureStart: input.timeSecondsFromOpeningReference,\n      ...(focus.kind === \"finite\" ? { focusDistanceM: focus.distanceM } : {}) });\n    const point = projection.value.referenceImagePointMm, z = projection.value.projectionDistanceMm;\n    const length = hypot3(point.x, point.y, z);\n    look = { x: point.x/length, y: point.y/length, z: z/length };\n    projectionScaleMm = z;\n  } else {\n    projectionScaleMm = focus.kind === \"finite\"\n      ? calculateThinLensImageDistance({ focalLengthMm: input.focalLengthMm, objectDistanceM: focus.distanceM }).value.imageDistanceMm\n      : input.focalLengthMm;\n    const velocity = input.angularVelocityRadPerSec;\n    const t = input.timeSecondsFromOpeningReference;\n    if (typeof t !== \"number\" || !Number.isFinite(t) || t < 0) {\n      throw new InvalidScientificInputError(\"timeSecondsFromOpeningReference must be finite and non-negative.\");\n    }\n    const captured = lensProjectionDirectionValue(mapping.projectionModel, projectionScaleMm, ideal.x, ideal.y);\n    const reference = applyPhysicalCameraRotation(captured,\n      { pitch: velocity.pitch*t, yaw: velocity.yaw*t, roll: velocity.roll*t }, \"camera-to-reference\");\n    const length = hypot3(reference.x, reference.y, reference.z);\n    if (!(length > 0) || !Number.isFinite(length)) throw new InvalidScientificInputError(\"Mapped reference ray must be finite.\");\n    look = { x: reference.x/length, y: reference.y/length, z: reference.z/length };\n  }\n  const request = parseSceneRadianceEvaluationRequest({ ...input.request,\n    timeSecondsFromExposureStart: input.timeSecondsFromOpeningReference,\n    target: { kind: \"environment-direction\", outgoingDirectionUnitVector: { x: -look.x, y: -look.y, z: -look.z } } });\n  return approximationResult({ request, sourcePointNativeSensorMm: { ...input.sourcePointNativeSensorMm },\n    sourcePointImagePlaneMm, referenceLookDirectionUnitVector: look, projection,\n    lensFieldMapping: { projectionModel: mapping.projectionModel, distortionKind: mapping.distortion.kind,\n      idealImagePointMm: { ...ideal }, projectionScaleMm, distortionAreaFactor },\n    targetMeaning: \"environment-direction-in-exposure-start-camera-axes\", directionConvention: \"outgoing-radiance-toward-camera\",\n    geometricRayProjectionCalculated: true, sceneIntersectionCalculated: false, visibilityCalculated: false, providerExecuted: false\n  }, \"lens-mapped-sensor-environment-radiance-query\", \"0.1.0\", [\n    \"The physical sensor point is inverse-distorted to the ideal image point, then unprojected with the declared ideal projection and rotated by the constant-axis pure camera rotation.\",\n    \"Projection scale is the thin-lens image distance at finite focus (focal length at infinity) for every projection model; a calibrated finite-focus fisheye scale is not modeled.\",\n    \"The distortion area factor 1/det(d distorted/d ideal) is reported for exactly-once application to irradiance; field throughput, PSF and pupil models are not changed by this query.\",\n    \"Breathing, chromatic field mapping, translation/parallax and scene intersections remain separate.\"\n  ]);\n}\n"]}
+{"version":3,"file":"sensor-environment-query.js","sourceRoot":"","sources":["../../src/optics/sensor-environment-query.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Builds an environment radiance request from points on the physical sensor. It uses the existing\n * focus-aware ideal projection and the analytic inverse camera rotation.\n *\n * Native Y (+Y down) is inverted explicitly. The direction sent to the provider points opposite the\n * look ray at exposure start, because radiance travels toward the camera. This module does not\n * intersect the scene, compute radiance or render anything.\n *\n * Optional lens field mapping (2.0):\n * 1. The physical sensor point is inverse-distorted (radial or Brown-Conrady) to the ideal image\n *    point.\n * 2. That point is unprojected with the declared ideal projection (rectilinear, fisheye or\n *    equirectangular), at the same focus-aware projection scale.\n * 3. The ray is rotated to the camera axes at exposure start.\n * The local area factor 1 / det(d distorted / d ideal) is reported. The caller applies it to\n * irradiance exactly once. Without the mapping, the existing rectilinear computation is unchanged.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { applyPhysicalCameraRotation, calculateInverseCameraRotationImageMapping,\n  type CameraAngularVelocityRadPerSec } from \"../motion/camera-rotation.js\";\nimport { lensProjectionDirectionValue, parseLensProjectionModel, type LensProjectionModel } from \"../camera/lens-projection.js\";\nimport {\n  calculateInverseRadialSourcePointValue, validateRadialDistortionProfile, type RadialDistortionProfile, type ValidatedRadialProfile\n} from \"./radial-distortion.js\";\nimport {\n  brownConradyForwardValue, brownConradyInverseValue, validateBrownConradyDistortionProfile,\n  type BrownConradyDistortionProfile, type ValidatedBrownConradyDistortionProfile\n} from \"./brown-conrady-distortion.js\";\nimport { calculateThinLensImageDistance } from \"./thin-lens.js\";\nimport { parseSceneRadianceEvaluationRequest, type SceneRadianceEvaluationRequest } from \"../schema/scene-radiance.js\";\nimport { parseFocusPlane, type FocusPlane } from \"./focus-state.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { hypot3 } from \"../core/portable-math.js\";\n\n/**\n * Lens field mapping between the physical (distorted) sensor point and the scene ray (2.0).\n * `radiometricAreaCorrection` states who applies the distortion area factor. The environment\n * photo signal multiplies irradiance by 1 / det(d distorted / d ideal) exactly once. A supplied\n * field-throughput profile must therefore not include it as well.\n */\nexport interface EnvironmentLensFieldMapping {\n  projectionModel: LensProjectionModel;\n  distortion:\n    | { kind: \"none\" }\n    | { kind: \"radial\"; profile: RadialDistortionProfile }\n    | { kind: \"brown-conrady\"; profile: BrownConradyDistortionProfile };\n  radiometricAreaCorrection: \"inverse-distortion-jacobian\";\n}\n\n/** @internal Parsed mapping with validated profiles, reused across one plan's queries. */\nexport interface PreparedEnvironmentLensFieldMapping {\n  mapping: EnvironmentLensFieldMapping;\n  radial?: ValidatedRadialProfile;\n  brownConrady?: ValidatedBrownConradyDistortionProfile;\n}\n\n/** @internal Strict parse and validation of a lens field mapping. Unknown fields are rejected. */\nexport function prepareEnvironmentLensFieldMapping(value: unknown): PreparedEnvironmentLensFieldMapping {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new InvalidConfigurationError(\"lensFieldMapping must be an object.\");\n  }\n  const record = value as Record<string, unknown>;\n  for (const key of Object.keys(record)) {\n    if (![\"projectionModel\", \"distortion\", \"radiometricAreaCorrection\"].includes(key)) {\n      throw new InvalidConfigurationError(`lensFieldMapping has unknown field ${JSON.stringify(key)}.`);\n    }\n  }\n  if (record.radiometricAreaCorrection !== \"inverse-distortion-jacobian\") {\n    throw new InvalidConfigurationError(\"lensFieldMapping.radiometricAreaCorrection must be \\\"inverse-distortion-jacobian\\\".\");\n  }\n  const projectionModel = parseLensProjectionModel(record.projectionModel);\n  const distortion = record.distortion as EnvironmentLensFieldMapping[\"distortion\"] | undefined;\n  if (typeof distortion !== \"object\" || distortion === null) {\n    throw new InvalidConfigurationError(\"lensFieldMapping.distortion must be an object.\");\n  }\n  if (distortion.kind === \"none\") {\n    return { mapping: { projectionModel, distortion: { kind: \"none\" }, radiometricAreaCorrection: \"inverse-distortion-jacobian\" } };\n  }\n  if (distortion.kind === \"radial\") {\n    const radial = validateRadialDistortionProfile(distortion.profile);\n    return { mapping: { projectionModel, distortion: { kind: \"radial\", profile: distortion.profile },\n      radiometricAreaCorrection: \"inverse-distortion-jacobian\" }, radial };\n  }\n  if (distortion.kind === \"brown-conrady\") {\n    const brownConrady = validateBrownConradyDistortionProfile(distortion.profile);\n    return { mapping: { projectionModel, distortion: { kind: \"brown-conrady\", profile: distortion.profile },\n      radiometricAreaCorrection: \"inverse-distortion-jacobian\" }, brownConrady };\n  }\n  throw new InvalidConfigurationError(\"lensFieldMapping.distortion.kind must be none, radial or brown-conrady.\");\n}\n\nexport interface CalculateSensorEnvironmentRadianceQueryInput {\n  /** Optical sample point before the anti-aliasing filter or PSF. Native +X right, +Y down, in mm from the optical axis. */\n  sourcePointNativeSensorMm: { x: number; y: number };\n  focalLengthMm: number;\n  focus: FocusPlane;\n  angularVelocityRadPerSec: CameraAngularVelocityRadPerSec;\n  /** States that the moment the shutter opens is t=0 in the rotation model. */\n  timeReference: \"first-opening-boundary-phase\";\n  timeSecondsFromOpeningReference: number;\n  /** The request uses the direction radiance travels: toward the camera, opposite the look ray. */\n  environmentDirectionConvention: \"outgoing-radiance-toward-camera\";\n  request: Omit<SceneRadianceEvaluationRequest, \"target\" | \"timeSecondsFromExposureStart\">;\n  /** Optional 2.0 lens field mapping. Omit it for the ideal rectilinear, distortion-free query. */\n  lensFieldMapping?: EnvironmentLensFieldMapping;\n}\n\nexport interface SensorEnvironmentLensFieldMappingResult {\n  projectionModel: LensProjectionModel;\n  distortionKind: \"none\" | \"radial\" | \"brown-conrady\";\n  /** Ideal (undistorted) image-plane point, +X right / +Y up, mm. */\n  idealImagePointMm: { x: number; y: number };\n  /** Projection scale: thin-lens image distance at finite focus, focal length at infinity, mm. */\n  projectionScaleMm: number;\n  /** 1 / det(d distorted / d ideal) at this point; 1 without distortion. */\n  distortionAreaFactor: number;\n}\n\nexport interface SensorEnvironmentRadianceQuery {\n  request: SceneRadianceEvaluationRequest;\n  sourcePointNativeSensorMm: { x: number; y: number };\n  sourcePointImagePlaneMm: { x: number; y: number };\n  referenceLookDirectionUnitVector: { x: number; y: number; z: number };\n  /** Rectilinear rotation mapping. Null when a non-rectilinear lens field mapping is used. */\n  projection: ReturnType<typeof calculateInverseCameraRotationImageMapping> | null;\n  /** Present only when the input declared a lens field mapping. */\n  lensFieldMapping?: SensorEnvironmentLensFieldMappingResult;\n  targetMeaning: \"environment-direction-in-exposure-start-camera-axes\";\n  directionConvention: \"outgoing-radiance-toward-camera\";\n  geometricRayProjectionCalculated: true;\n  sceneIntersectionCalculated: false;\n  visibilityCalculated: false;\n  providerExecuted: false;\n}\n\n/**\n * Builds an environment radiance request from points on the physical sensor,\n * using the existing focus-aware ideal projection and the analytic inverse\n * camera rotation.\n *\n * Native Y (+Y down) is inverted explicitly. The provider direction points\n * opposite the look ray at exposure start. Nothing intersects the scene,\n * computes radiance or renders.\n */\nexport function calculateSensorEnvironmentRadianceQuery(\n  input: CalculateSensorEnvironmentRadianceQueryInput\n): CalculationResult<SensorEnvironmentRadianceQuery> {\n  requireInputKeys(input, \"calculateSensorEnvironmentRadianceQuery\", [\"sourcePointNativeSensorMm\", \"focalLengthMm\", \"focus\", \"angularVelocityRadPerSec\", \"timeReference\", \"timeSecondsFromOpeningReference\", \"environmentDirectionConvention\", \"request\", \"lensFieldMapping\"]);\n  if (input.lensFieldMapping !== undefined) {\n    return calculateMappedSensorEnvironmentRadianceQuery(input, prepareEnvironmentLensFieldMapping(input.lensFieldMapping));\n  }\n  if (input.timeReference !== \"first-opening-boundary-phase\" ||\n    input.environmentDirectionConvention !== \"outgoing-radiance-toward-camera\") {\n    throw new InvalidScientificInputError(\"Environment projection requires explicit opening-boundary time and outgoing-toward-camera direction conventions.\");\n  }\n  const focus = parseFocusPlane(input.focus);\n  const sourcePointImagePlaneMm = { x: input.sourcePointNativeSensorMm.x, y: -input.sourcePointNativeSensorMm.y };\n  const projection = calculateInverseCameraRotationImageMapping({ focalLengthMm: input.focalLengthMm,\n    imagePointMm: sourcePointImagePlaneMm, angularVelocityRadPerSec: input.angularVelocityRadPerSec,\n    timeSecondsFromExposureStart: input.timeSecondsFromOpeningReference,\n    ...(focus.kind === \"finite\" ? { focusDistanceM: focus.distanceM } : {}) });\n  const point = projection.value.referenceImagePointMm, z = projection.value.projectionDistanceMm;\n  const length = hypot3(point.x, point.y, z);\n  const referenceLookDirectionUnitVector = { x: point.x/length, y: point.y/length, z: z/length };\n  const ray = referenceLookDirectionUnitVector;\n  const request = parseSceneRadianceEvaluationRequest({ ...input.request,\n    timeSecondsFromExposureStart: input.timeSecondsFromOpeningReference,\n    target: { kind: \"environment-direction\", outgoingDirectionUnitVector: { x: -ray.x, y: -ray.y, z: -ray.z } } });\n  return approximationResult({ request, sourcePointNativeSensorMm: { ...input.sourcePointNativeSensorMm },\n    sourcePointImagePlaneMm, referenceLookDirectionUnitVector, projection,\n    targetMeaning: \"environment-direction-in-exposure-start-camera-axes\", directionConvention: \"outgoing-radiance-toward-camera\",\n    geometricRayProjectionCalculated: true, sceneIntersectionCalculated: false, visibilityCalculated: false, providerExecuted: false\n  }, \"sensor-environment-radiance-query\", \"0.1.0\", [\n    \"Ideal focus-aware rectilinear projection and constant-axis pure camera rotation; reference ray must stay in the forward hemisphere.\",\n    \"The environment and rotation reference axes coincide with camera axes at the first opening boundary by explicit convention.\",\n    \"Lens distortion, breathing, chromatic field mapping, translation/parallax and scene intersections remain separate.\"\n  ]);\n}\n\n/**\n * @internal The ideal (undistorted) image point of a physical sensor point (+X right, +Y up, mm) and the distortion area\n * factor 1 / det(d distorted / d ideal) there; the ideal point is the sensor point itself without distortion. Shared by\n * the mapped query below and the image-space defocus of `simulateCapture` (#548), so both use one arithmetic.\n */\nexport function undistortedImagePoint(prepared: PreparedEnvironmentLensFieldMapping, imagePointMm: { x: number; y: number }):\n  { ideal: { x: number; y: number }; distortionAreaFactor: number } {\n  let ideal = imagePointMm;\n  let distortionAreaFactor = 1;\n  if (prepared.radial !== undefined) {\n    ideal = calculateInverseRadialSourcePointValue(imagePointMm, prepared.radial, \"sourcePointNativeSensorMm\").sourceImagePointMm;\n    // Radial map p -> s(r) p: det = s (s + r ds/dr) with r ds/dr = 2 r^2 s'(r^2).\n    const { k1, k2, k3 } = prepared.radial.coefficients;\n    const r2 = (ideal.x*ideal.x+ideal.y*ideal.y)/prepared.radial.normalizationRadiusMm**2;\n    const scale = 1+k1*r2+k2*r2*r2+k3*r2*r2*r2;\n    const radialDerivative = 1+3*k1*r2+5*k2*r2*r2+7*k3*r2*r2*r2;\n    distortionAreaFactor = 1/(scale*radialDerivative);\n  } else if (prepared.brownConrady !== undefined) {\n    ideal = brownConradyInverseValue(prepared.brownConrady, imagePointMm);\n    const j = brownConradyForwardValue(prepared.brownConrady, ideal).jacobian;\n    distortionAreaFactor = 1/(j[0]*j[3]-j[1]*j[2]);\n  }\n  if (!(distortionAreaFactor > 0) || !Number.isFinite(distortionAreaFactor)) {\n    throw new InvalidScientificInputError(\"Distortion area factor must remain finite and positive.\");\n  }\n  return { ideal, distortionAreaFactor };\n}\n\n/**\n * @internal The forward distortion of an ideal image point (+X right, +Y up, mm) to the physical sensor point, with the\n * singular values of d distorted / d ideal there (the largest and smallest local scale of the map; 1 and 1 without\n * distortion). The inverse of {@link undistortedImagePoint} up to its solver's rounding (#548).\n */\nexport function distortedImagePoint(prepared: PreparedEnvironmentLensFieldMapping, ideal: { x: number; y: number }):\n  { pointMm: { x: number; y: number }; largestScale: number; smallestScale: number } {\n  if (prepared.radial !== undefined) {\n    const { k1, k2, k3 } = prepared.radial.coefficients;\n    const r2 = (ideal.x*ideal.x+ideal.y*ideal.y)/prepared.radial.normalizationRadiusMm**2;\n    const scale = 1+k1*r2+k2*r2*r2+k3*r2*r2*r2;\n    // Tangential scale s, radial scale s + r ds/dr (the two eigenvalues of the symmetric Jacobian of p -> s(r) p).\n    const radialDerivative = 1+3*k1*r2+5*k2*r2*r2+7*k3*r2*r2*r2;\n    return { pointMm: { x: ideal.x*scale, y: ideal.y*scale }, largestScale: Math.max(scale, radialDerivative), smallestScale: Math.min(scale, radialDerivative) };\n  }\n  if (prepared.brownConrady !== undefined) {\n    const forward = brownConradyForwardValue(prepared.brownConrady, ideal), [a, b, c, d] = forward.jacobian;\n    // Singular values of [[a, b], [c, d]]: sqrt of the eigenvalues of J^T J.\n    const p = a*a+b*b+c*c+d*d, q = Math.abs(a*d-b*c), root = Math.sqrt(Math.max(0, p*p-4*q*q));\n    const largest = Math.sqrt((p+root)/2);\n    return { pointMm: forward.mappedImagePointMm, largestScale: largest, smallestScale: largest > 0 ? q/largest : 0 };\n  }\n  return { pointMm: { ...ideal }, largestScale: 1, smallestScale: 1 };\n}\n\n/**\n * @internal Query with a lens field mapping that is already validated. The environment photo-signal\n * planner shares it, so profiles are validated once per plan.\n */\nexport function calculateMappedSensorEnvironmentRadianceQuery(\n  input: CalculateSensorEnvironmentRadianceQueryInput,\n  prepared: PreparedEnvironmentLensFieldMapping\n): CalculationResult<SensorEnvironmentRadianceQuery> {\n  if (input.timeReference !== \"first-opening-boundary-phase\" ||\n    input.environmentDirectionConvention !== \"outgoing-radiance-toward-camera\") {\n    throw new InvalidScientificInputError(\"Environment projection requires explicit opening-boundary time and outgoing-toward-camera direction conventions.\");\n  }\n  const focus = parseFocusPlane(input.focus);\n  const sourcePointImagePlaneMm = { x: input.sourcePointNativeSensorMm.x, y: -input.sourcePointNativeSensorMm.y };\n  const mapping = prepared.mapping;\n  const { ideal, distortionAreaFactor } = undistortedImagePoint(prepared, sourcePointImagePlaneMm);\n  let projection: ReturnType<typeof calculateInverseCameraRotationImageMapping> | null = null;\n  let look: { x: number; y: number; z: number };\n  let projectionScaleMm: number;\n  if (mapping.projectionModel === \"rectilinear\") {\n    projection = calculateInverseCameraRotationImageMapping({ focalLengthMm: input.focalLengthMm,\n      imagePointMm: ideal, angularVelocityRadPerSec: input.angularVelocityRadPerSec,\n      timeSecondsFromExposureStart: input.timeSecondsFromOpeningReference,\n      ...(focus.kind === \"finite\" ? { focusDistanceM: focus.distanceM } : {}) });\n    const point = projection.value.referenceImagePointMm, z = projection.value.projectionDistanceMm;\n    const length = hypot3(point.x, point.y, z);\n    look = { x: point.x/length, y: point.y/length, z: z/length };\n    projectionScaleMm = z;\n  } else {\n    projectionScaleMm = focus.kind === \"finite\"\n      ? calculateThinLensImageDistance({ focalLengthMm: input.focalLengthMm, objectDistanceM: focus.distanceM }).value.imageDistanceMm\n      : input.focalLengthMm;\n    const velocity = input.angularVelocityRadPerSec;\n    const t = input.timeSecondsFromOpeningReference;\n    if (typeof t !== \"number\" || !Number.isFinite(t) || t < 0) {\n      throw new InvalidScientificInputError(\"timeSecondsFromOpeningReference must be finite and non-negative.\");\n    }\n    const captured = lensProjectionDirectionValue(mapping.projectionModel, projectionScaleMm, ideal.x, ideal.y);\n    const reference = applyPhysicalCameraRotation(captured,\n      { pitch: velocity.pitch*t, yaw: velocity.yaw*t, roll: velocity.roll*t }, \"camera-to-reference\");\n    const length = hypot3(reference.x, reference.y, reference.z);\n    if (!(length > 0) || !Number.isFinite(length)) throw new InvalidScientificInputError(\"Mapped reference ray must be finite.\");\n    look = { x: reference.x/length, y: reference.y/length, z: reference.z/length };\n  }\n  const request = parseSceneRadianceEvaluationRequest({ ...input.request,\n    timeSecondsFromExposureStart: input.timeSecondsFromOpeningReference,\n    target: { kind: \"environment-direction\", outgoingDirectionUnitVector: { x: -look.x, y: -look.y, z: -look.z } } });\n  return approximationResult({ request, sourcePointNativeSensorMm: { ...input.sourcePointNativeSensorMm },\n    sourcePointImagePlaneMm, referenceLookDirectionUnitVector: look, projection,\n    lensFieldMapping: { projectionModel: mapping.projectionModel, distortionKind: mapping.distortion.kind,\n      idealImagePointMm: { ...ideal }, projectionScaleMm, distortionAreaFactor },\n    targetMeaning: \"environment-direction-in-exposure-start-camera-axes\", directionConvention: \"outgoing-radiance-toward-camera\",\n    geometricRayProjectionCalculated: true, sceneIntersectionCalculated: false, visibilityCalculated: false, providerExecuted: false\n  }, \"lens-mapped-sensor-environment-radiance-query\", \"0.1.0\", [\n    \"The physical sensor point is inverse-distorted to the ideal image point, then unprojected with the declared ideal projection and rotated by the constant-axis pure camera rotation.\",\n    \"Projection scale is the thin-lens image distance at finite focus (focal length at infinity) for every projection model; a calibrated finite-focus fisheye scale is not modeled.\",\n    \"The distortion area factor 1/det(d distorted/d ideal) is reported for exactly-once application to irradiance; field throughput, PSF and pupil models are not changed by this query.\",\n    \"Breathing, chromatic field mapping, translation/parallax and scene intersections remain separate.\"\n  ]);\n}\n"]}

package/dist/optics/site-diffraction-kernel.d.ts

@@ -1,4 +1,4 @@
-import { resolveLensPsfConvolutionKernels } from "./lens-psf-kernels.js";
+import { type resolveLensPsfConvolutionKernels } from "./lens-psf-kernels.js";
 type Psf = Parameters<typeof resolveLensPsfConvolutionKernels>[0]["psf"];
 /** PSF records kept by value: at most 20 kernels of (2·32 + 1)² doubles each (676 KB) per record at the default spectral sampling. */
 export declare const SITE_DIFFRACTION_KERNEL_CACHE_SIZE = 4;

package/dist/optics/site-diffraction-kernel.js

@@ -11,17 +11,27 @@
  * own fields (everything the kernel is a function of besides the wavelength, pitch and radius of the query). Records with an equal
  * string share their kernels, in a least-recently-used cache of `SITE_DIFFRACTION_KERNEL_CACHE_SIZE` records. A record that was not
  * registered (a caller's own profile) keeps its kernels while it lives, by identity, as before.
+ *
+ * 2.15.0: the most recently used entry also keeps one private, engine-owned clone of the profile, taken on its first resolve,
+ * and every later wavelength resolves from it (`resolveLensPsfConvolutionKernelsWithOwnedProfile`), so a request's profile is
+ * cloned and parsed once rather than once per wavelength; only one clone is held at a time. Before, N wavelengths cost N clones
+ * and parses of an N-wavelength profile, O(N²): at radius 32, 124 s for the 400 nodes of a 1 nm spectral step and 5.1 s for 80
+ * nodes, against 1.4 s and 0.12 s now (one machine, docs/PSF_FOUNDATION.md "Spectral nodes (2.15.0)"). The kernels are the same
+ * numbers (test/diffraction-spectral-grid.test.ts): both paths parse a structured clone of the same profile, and the clone is never changed.
  */
 import { InvalidConfigurationError } from "../core/configuration-error.js";
-import { resolveLensPsfConvolutionKernels } from "./lens-psf-kernels.js";
+import { resolveLensPsfConvolutionKernelsWithOwnedProfile } from "./lens-psf-kernels.js";
+import { markEngineOwnedLensSampledPsfProfile } from "./lens-psf-profile.js";
 /** PSF records kept by value: at most 20 kernels of (2·32 + 1)² doubles each (676 KB) per record at the default spectral sampling. */
 export const SITE_DIFFRACTION_KERNEL_CACHE_SIZE = 4;
 /** Canonical value key of each registered PSF record. */
 const keys = new WeakMap();
-/** Kernels per registered value key (least recently used first), then per wavelength, pitch and radius. */
+/** Entries per registered value key (least recently used first). */
 const byValue = new Map();
-/** Kernels per unregistered PSF record (by identity: the record is large, so it is not serialized), then per wavelength, pitch and radius. */
+/** Entries per unregistered PSF record (by identity: the record is large, so it is not serialized). */
 const byIdentity = new WeakMap();
+/** The one entry that holds its private clone of the profile. */
+let lastOwner;
 /** Kernels resolved so far (test hook). */
 let resolves = 0;
 /** JSON with every number spelled exactly: shortest round-trip digits, and -0, NaN and ±Infinity kept apart from 0 and null. */
@@ -37,34 +47,43 @@ export function registerDiffractionPsfKey(psf, profileInput) {
     const fields = Object.entries(psf).filter(([name]) => name !== "profile").sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
     keys.set(psf, canonical(["createDiffractionLimitedPsfProfile", profileInput, fields]));
 }
-/** The kernels kept for `psf`, made the most recently used. */
-function kernelsOf(psf) {
+/** The entry kept for `psf`, made the most recently used. */
+function entryOf(psf) {
     const key = keys.get(psf);
     if (key === undefined) {
-        let kernels = byIdentity.get(psf);
-        if (!kernels)
-            byIdentity.set(psf, (kernels = new Map()));
-        return kernels;
+        let entry = byIdentity.get(psf);
+        if (!entry)
+            byIdentity.set(psf, (entry = { kernels: new Map() }));
+        return entry;
     }
-    let kernels = byValue.get(key);
-    if (kernels)
+    let entry = byValue.get(key);
+    if (entry)
         byValue.delete(key);
     else
-        kernels = new Map();
-    byValue.set(key, kernels);
+        entry = { kernels: new Map() };
+    byValue.set(key, entry);
     while (byValue.size > SITE_DIFFRACTION_KERNEL_CACHE_SIZE)
         byValue.delete(byValue.keys().next().value);
-    return kernels;
+    return entry;
 }
 /** The (2·radius + 1)² kernel of `psf` at `wavelengthNm` on a square site grid of `pitchMicrometers`; `failure` is the error message when the kernel cannot sample the pitch exactly. */
 export function siteDiffractionKernel(psf, wavelengthNm, pitchMicrometers, radius, failure) {
-    const kernels = kernelsOf(psf);
+    const entry = entryOf(psf), kernels = entry.kernels;
     const key = canonical([wavelengthNm, pitchMicrometers, radius]);
     let kernel = kernels.get(key);
     if (!kernel) {
-        const k = resolveLensPsfConvolutionKernels({ schemaVersion: "0.1.0", psf, spectralWeights: [{ wavelengthNm, weight: 1 }],
+        if (!entry.ownedProfile) {
+            const owned = structuredClone(psf.profile);
+            markEngineOwnedLensSampledPsfProfile(owned);
+            // Only the most recent entry keeps its clone (a request resolves its wavelengths in one run), so at most one is held.
+            if (lastOwner)
+                delete lastOwner.ownedProfile;
+            entry.ownedProfile = owned;
+            lastOwner = entry;
+        }
+        const k = resolveLensPsfConvolutionKernelsWithOwnedProfile({ schemaVersion: "0.1.0", psf, spectralWeights: [{ wavelengthNm, weight: 1 }],
             grid: { width: 1, height: 1, sitePitchMicrometers: { x: pitchMicrometers, y: pitchMicrometers }, opticalAxisSite: { x: 0.5, y: 0.5 } }, patchWidth: 1, patchHeight: 1,
-            kernelRadius: radius }).value;
+            kernelRadius: radius }, entry.ownedProfile).value;
         if (!k.exactSiteSampling || k.kernelRadius !== radius)
             throw new InvalidConfigurationError(failure);
         kernel = Float64Array.from(k.kernels);
@@ -80,5 +99,6 @@ export function siteDiffractionKernelCacheState(psf) {
 /** Test hook: forgets every kernel kept by value. */
 export function clearSiteDiffractionKernelCache() {
     byValue.clear();
+    lastOwner = undefined;
 }
 //# sourceMappingURL=site-diffraction-kernel.js.map

package/dist/optics/site-diffraction-kernel.js.map

@@ -1 +1 @@
-{"version":3,"file":"site-diffraction-kernel.js","sourceRoot":"","sources":["../../src/optics/site-diffraction-kernel.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Internal (not exported from the package): one wavelength's diffraction kernel sampled on the site pitch, as the object-space\n * convolution (facade/diffraction-provider.ts) and the tabulated expected signal (facade/expected-signal-setup.ts) use it.\n *\n * `resolveLensPsfConvolutionKernels` parses and samples the PSF profile on every call (about 10 ms per wavelength), and both users\n * ask for the same kernels. The kernel is a function of its inputs alone; each caller gets its own copy.\n *\n * The facade builds a new PSF record for every request, so kernels are kept by value: `registerDiffractionPsfKey` records, for a\n * record whose profile `createDiffractionLimitedPsfProfile` built, a canonical string of that call's whole input and of the record's\n * own fields (everything the kernel is a function of besides the wavelength, pitch and radius of the query). Records with an equal\n * string share their kernels, in a least-recently-used cache of `SITE_DIFFRACTION_KERNEL_CACHE_SIZE` records. A record that was not\n * registered (a caller's own profile) keeps its kernels while it lives, by identity, as before.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { resolveLensPsfConvolutionKernels } from \"./lens-psf-kernels.js\";\n\ntype Psf = Parameters<typeof resolveLensPsfConvolutionKernels>[0][\"psf\"];\n\n/** PSF records kept by value: at most 20 kernels of (2·32 + 1)² doubles each (676 KB) per record at the default spectral sampling. */\nexport const SITE_DIFFRACTION_KERNEL_CACHE_SIZE = 4;\n\n/** Canonical value key of each registered PSF record. */\nconst keys = new WeakMap<object, string>();\n/** Kernels per registered value key (least recently used first), then per wavelength, pitch and radius. */\nconst byValue = new Map<string, Map<string, Float64Array>>();\n/** Kernels per unregistered PSF record (by identity: the record is large, so it is not serialized), then per wavelength, pitch and radius. */\nconst byIdentity = new WeakMap<object, Map<string, Float64Array>>();\n/** Kernels resolved so far (test hook). */\nlet resolves = 0;\n\n/** JSON with every number spelled exactly: shortest round-trip digits, and -0, NaN and ±Infinity kept apart from 0 and null. */\nfunction canonical(value: unknown): string {\n  return JSON.stringify(value, (_key, v: unknown) => (typeof v === \"number\" && (Object.is(v, -0) || !Number.isFinite(v)) ? \"number:\" + (Object.is(v, -0) ? \"-0\" : String(v)) : v));\n}\n\n/**\n * Records that `psf.profile` is the profile `createDiffractionLimitedPsfProfile(profileInput)` returned, unmodified, so that the\n * kernels of `psf` are those of any record with the same `profileInput` and the same other fields. Call it right after building the\n * record; neither the record nor `profileInput` may change afterwards.\n */\nexport function registerDiffractionPsfKey(psf: Psf, profileInput: object): void {\n  const fields = Object.entries(psf as object).filter(([name]) => name !== \"profile\").sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n  keys.set(psf as object, canonical([\"createDiffractionLimitedPsfProfile\", profileInput, fields]));\n}\n\n/** The kernels kept for `psf`, made the most recently used. */\nfunction kernelsOf(psf: Psf): Map<string, Float64Array> {\n  const key = keys.get(psf as object);\n  if (key === undefined) {\n    let kernels = byIdentity.get(psf as object);\n    if (!kernels) byIdentity.set(psf as object, (kernels = new Map()));\n    return kernels;\n  }\n  let kernels = byValue.get(key);\n  if (kernels) byValue.delete(key);\n  else kernels = new Map();\n  byValue.set(key, kernels);\n  while (byValue.size > SITE_DIFFRACTION_KERNEL_CACHE_SIZE) byValue.delete(byValue.keys().next().value!);\n  return kernels;\n}\n\n/** The (2·radius + 1)² kernel of `psf` at `wavelengthNm` on a square site grid of `pitchMicrometers`; `failure` is the error message when the kernel cannot sample the pitch exactly. */\nexport function siteDiffractionKernel(psf: Psf, wavelengthNm: number, pitchMicrometers: number, radius: number, failure: string): Float64Array {\n  const kernels = kernelsOf(psf);\n  const key = canonical([wavelengthNm, pitchMicrometers, radius]);\n  let kernel = kernels.get(key);\n  if (!kernel) {\n    const k = resolveLensPsfConvolutionKernels({ schemaVersion: \"0.1.0\", psf, spectralWeights: [{ wavelengthNm, weight: 1 }],\n      grid: { width: 1, height: 1, sitePitchMicrometers: { x: pitchMicrometers, y: pitchMicrometers }, opticalAxisSite: { x: 0.5, y: 0.5 } }, patchWidth: 1, patchHeight: 1,\n      kernelRadius: radius }).value;\n    if (!k.exactSiteSampling || k.kernelRadius !== radius) throw new InvalidConfigurationError(failure);\n    kernel = Float64Array.from(k.kernels);\n    resolves++;\n    kernels.set(key, kernel);\n  }\n  return Float64Array.from(kernel);\n}\n\n/** Test hook: the number of PSF records kept by value, the kernels resolved so far, and whether `psf` is registered. */\nexport function siteDiffractionKernelCacheState(psf?: Psf): { valueEntries: number; resolves: number; registered: boolean } {\n  return { valueEntries: byValue.size, resolves, registered: psf !== undefined && keys.has(psf as object) };\n}\n\n/** Test hook: forgets every kernel kept by value. */\nexport function clearSiteDiffractionKernelCache(): void {\n  byValue.clear();\n}\n"]}
+{"version":3,"file":"site-diffraction-kernel.js","sourceRoot":"","sources":["../../src/optics/site-diffraction-kernel.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Internal (not exported from the package): one wavelength's diffraction kernel sampled on the site pitch, as the object-space\n * convolution (facade/diffraction-provider.ts) and the tabulated expected signal (facade/expected-signal-setup.ts) use it.\n *\n * `resolveLensPsfConvolutionKernels` parses and samples the PSF profile on every call (about 10 ms per wavelength), and both users\n * ask for the same kernels. The kernel is a function of its inputs alone; each caller gets its own copy.\n *\n * The facade builds a new PSF record for every request, so kernels are kept by value: `registerDiffractionPsfKey` records, for a\n * record whose profile `createDiffractionLimitedPsfProfile` built, a canonical string of that call's whole input and of the record's\n * own fields (everything the kernel is a function of besides the wavelength, pitch and radius of the query). Records with an equal\n * string share their kernels, in a least-recently-used cache of `SITE_DIFFRACTION_KERNEL_CACHE_SIZE` records. A record that was not\n * registered (a caller's own profile) keeps its kernels while it lives, by identity, as before.\n *\n * 2.15.0: the most recently used entry also keeps one private, engine-owned clone of the profile, taken on its first resolve,\n * and every later wavelength resolves from it (`resolveLensPsfConvolutionKernelsWithOwnedProfile`), so a request's profile is\n * cloned and parsed once rather than once per wavelength; only one clone is held at a time. Before, N wavelengths cost N clones\n * and parses of an N-wavelength profile, O(N²): at radius 32, 124 s for the 400 nodes of a 1 nm spectral step and 5.1 s for 80\n * nodes, against 1.4 s and 0.12 s now (one machine, docs/PSF_FOUNDATION.md \"Spectral nodes (2.15.0)\"). The kernels are the same\n * numbers (test/diffraction-spectral-grid.test.ts): both paths parse a structured clone of the same profile, and the clone is never changed.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { resolveLensPsfConvolutionKernelsWithOwnedProfile, type resolveLensPsfConvolutionKernels } from \"./lens-psf-kernels.js\";\nimport { markEngineOwnedLensSampledPsfProfile } from \"./lens-psf-profile.js\";\n\ntype Psf = Parameters<typeof resolveLensPsfConvolutionKernels>[0][\"psf\"];\n\n/** PSF records kept by value: at most 20 kernels of (2·32 + 1)² doubles each (676 KB) per record at the default spectral sampling. */\nexport const SITE_DIFFRACTION_KERNEL_CACHE_SIZE = 4;\n\n/** Canonical value key of each registered PSF record. */\nconst keys = new WeakMap<object, string>();\n/** One entry's kernels per wavelength, pitch and radius, and its private clone of the profile (taken on the first resolve). */\ninterface Entry { kernels: Map<string, Float64Array>; ownedProfile?: object }\n/** Entries per registered value key (least recently used first). */\nconst byValue = new Map<string, Entry>();\n/** Entries per unregistered PSF record (by identity: the record is large, so it is not serialized). */\nconst byIdentity = new WeakMap<object, Entry>();\n/** The one entry that holds its private clone of the profile. */\nlet lastOwner: Entry | undefined;\n/** Kernels resolved so far (test hook). */\nlet resolves = 0;\n\n/** JSON with every number spelled exactly: shortest round-trip digits, and -0, NaN and ±Infinity kept apart from 0 and null. */\nfunction canonical(value: unknown): string {\n  return JSON.stringify(value, (_key, v: unknown) => (typeof v === \"number\" && (Object.is(v, -0) || !Number.isFinite(v)) ? \"number:\" + (Object.is(v, -0) ? \"-0\" : String(v)) : v));\n}\n\n/**\n * Records that `psf.profile` is the profile `createDiffractionLimitedPsfProfile(profileInput)` returned, unmodified, so that the\n * kernels of `psf` are those of any record with the same `profileInput` and the same other fields. Call it right after building the\n * record; neither the record nor `profileInput` may change afterwards.\n */\nexport function registerDiffractionPsfKey(psf: Psf, profileInput: object): void {\n  const fields = Object.entries(psf as object).filter(([name]) => name !== \"profile\").sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));\n  keys.set(psf as object, canonical([\"createDiffractionLimitedPsfProfile\", profileInput, fields]));\n}\n\n/** The entry kept for `psf`, made the most recently used. */\nfunction entryOf(psf: Psf): Entry {\n  const key = keys.get(psf as object);\n  if (key === undefined) {\n    let entry = byIdentity.get(psf as object);\n    if (!entry) byIdentity.set(psf as object, (entry = { kernels: new Map() }));\n    return entry;\n  }\n  let entry = byValue.get(key);\n  if (entry) byValue.delete(key);\n  else entry = { kernels: new Map() };\n  byValue.set(key, entry);\n  while (byValue.size > SITE_DIFFRACTION_KERNEL_CACHE_SIZE) byValue.delete(byValue.keys().next().value!);\n  return entry;\n}\n\n/** The (2·radius + 1)² kernel of `psf` at `wavelengthNm` on a square site grid of `pitchMicrometers`; `failure` is the error message when the kernel cannot sample the pitch exactly. */\nexport function siteDiffractionKernel(psf: Psf, wavelengthNm: number, pitchMicrometers: number, radius: number, failure: string): Float64Array {\n  const entry = entryOf(psf), kernels = entry.kernels;\n  const key = canonical([wavelengthNm, pitchMicrometers, radius]);\n  let kernel = kernels.get(key);\n  if (!kernel) {\n    if (!entry.ownedProfile) {\n      const owned = structuredClone((psf as { profile: unknown }).profile) as object;\n      markEngineOwnedLensSampledPsfProfile(owned);\n      // Only the most recent entry keeps its clone (a request resolves its wavelengths in one run), so at most one is held.\n      if (lastOwner) delete lastOwner.ownedProfile;\n      entry.ownedProfile = owned;\n      lastOwner = entry;\n    }\n    const k = resolveLensPsfConvolutionKernelsWithOwnedProfile({ schemaVersion: \"0.1.0\", psf, spectralWeights: [{ wavelengthNm, weight: 1 }],\n      grid: { width: 1, height: 1, sitePitchMicrometers: { x: pitchMicrometers, y: pitchMicrometers }, opticalAxisSite: { x: 0.5, y: 0.5 } }, patchWidth: 1, patchHeight: 1,\n      kernelRadius: radius }, entry.ownedProfile).value;\n    if (!k.exactSiteSampling || k.kernelRadius !== radius) throw new InvalidConfigurationError(failure);\n    kernel = Float64Array.from(k.kernels);\n    resolves++;\n    kernels.set(key, kernel);\n  }\n  return Float64Array.from(kernel);\n}\n\n/** Test hook: the number of PSF records kept by value, the kernels resolved so far, and whether `psf` is registered. */\nexport function siteDiffractionKernelCacheState(psf?: Psf): { valueEntries: number; resolves: number; registered: boolean } {\n  return { valueEntries: byValue.size, resolves, registered: psf !== undefined && keys.has(psf as object) };\n}\n\n/** Test hook: forgets every kernel kept by value. */\nexport function clearSiteDiffractionKernelCache(): void {\n  byValue.clear();\n  lastOwner = undefined;\n}\n"]}