@photivra/engine 2.9.0 → 2.11.1

package/dist/optics/defocus-disc-kernel.js

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Internal (not exported from the package): the geometric defocus disc of a flat scene, sampled on the square site
+ * lattice, for `lens.defocus: { model: "geometric-disc" }` (#492).
+ *
+ * Model. For a scene plane at the subject distance d and a thin lens focused at s, an ideal uniform circular pupil
+ * spreads every in-focus image point into a uniform disc of diameter c = f²·|s − d| / (N·d·(s − f)) on the sensor
+ * (`calculateDefocusCircle`, thin-lens model 1.1.0; geometric optics, no diffraction or aberrations). The defocused
+ * image of the plane is therefore the in-focus image convolved with that disc: one fixed, wavelength-independent
+ * kernel. It is an approximation (geometric optics, ideal uniform circular pupil, no vignetting of the pupil).
+ *
+ * Sampling. The disc of diameter c/p sites (p the site pitch) is centred on a site centre. The weight of the site at
+ * offset (i, j) is the exact area of the disc inside that site's square cell [i − ½, i + ½] × [j − ½, j + ½], divided
+ * by the area of the disc. The area of a disc inside a rectangle is a signed sum over the rectangle's four corners of
+ * the area Q(x, y) of the disc inside the quadrant [0, x] × [0, y] (inclusion–exclusion), and for x, y ≥ 0 with
+ * x, y clamped to the radius r
+ *   Q = x·y                                                when x² + y² ≤ r²,
+ *   Q = ½·(x_a·y + x·y_a + r²·(arcsin(x/r) − arcsin(x_a/r)))  otherwise,
+ * with x_a = √(r² − y²) and y_a = √(r² − x²) the arc's crossings of the quadrant's edges: the rectangle left of the
+ * crossing plus the area under the arc, ∫ √(r² − t²) dt = ½·(t·√(r² − t²) + r²·arcsin(t/r)) (elementary geometry
+ * and calculus; NIST DLMF 4.24.1 for the arcsine, free). The arcsine difference is the angle between the two arc
+ * points, evaluated as arcsin((x·y − x_a·y_a)/r²) (the sine of a difference). Q is extended to negative x or y as an
+ * odd function.
+ *
+ * Determinism. Only correctly rounded operations and `portableAsin` are used, so the weights are the same bits in
+ * every JavaScript engine. One octant (0 ≤ j ≤ i) is computed and mirrored, so the kernel has the exact 8-fold
+ * symmetry of the disc and the square lattice. The weights are divided by their float64 sum, then the centre weight
+ * takes up the remaining rounding, so their exact sum is 1 within half a unit in the last place of the centre weight.
+ *
+ * Limits. The window is (2R + 1)² sites with R = ⌈r − ½⌉ (0 when r ≤ ½: a disc inside one cell is the identity, a
+ * valid kernel). R is capped at {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES}; past it the call fails, naming the
+ * cap and the radius asked for, instead of clipping the disc.
+ */
+import { portableAsin } from "../core/portable-math.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { calculateDefocusCircle } from "./depth-of-field.js";
+/**
+ * Largest kernel radius in sites, R ≤ 64 (a 129 × 129 window, 16 641 taps per site; the diffraction kernels stop at 32).
+ * Set from the cost measured in the capture (#492, step 2a; docs/QUICK_START.md, "Optics"): the capture's time grows with
+ * R² at every site the disc sees an edge from, and a 0.7 MP Siemens star took 0.37 s in focus, 2.9 s at R = 32, 4.7 s at
+ * R = 41 and 11.6 s at R = 64 (Node, one thread). 64 keeps the issue's 1.4 µm example (50 mm f/2.8, subject 2 m, focus
+ * 1.6 m: R = 41) with room for larger blurs, at a cost the caller chooses and the docs state; past it the call fails.
+ */
+export const DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES = 64;
+/** Kernel radius in sites for a disc of `diameterSites`: the cells [i − ½, i + ½] the disc reaches with positive area. */
+export function defocusDiscKernelRadius(diameterSites) {
+    requireDiameter(diameterSites);
+    const r = diameterSites / 2;
+    return r <= 0.5 ? 0 : Math.ceil(r - 0.5);
+}
+/**
+ * {@link defocusDiscKernelRadius}, failing with `InvalidScientificInputError` (naming the cap and the radius asked for)
+ * when it exceeds {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES}. The disc is never clipped to fit.
+ */
+export function requireDefocusDiscKernelRadius(diameterSites) {
+    const radius = defocusDiscKernelRadius(diameterSites);
+    if (radius > DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES)
+        throw new InvalidScientificInputError("The defocus disc of " + diameterSites + " sites needs a kernel radius of " + radius +
+            " sites; the limit is " + DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES + " sites (DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES).");
+    return radius;
+}
+function requireDiameter(diameterSites) {
+    if (typeof diameterSites !== "number" || !Number.isFinite(diameterSites) || diameterSites < 0)
+        throw new InvalidScientificInputError("The defocus disc diameter must be a finite number of sites, zero or more.");
+}
+/** Area of the disc of radius r (centred at the origin) inside [0, x] × [0, y], for x, y ≥ 0. */
+function quadrantArea(x, y, r) {
+    if (x > r)
+        x = r;
+    if (y > r)
+        y = r;
+    if (x * x + y * y <= r * r)
+        return x * y;
+    const xa = Math.sqrt((r - y) * (r + y)), ya = Math.sqrt((r - x) * (r + x));
+    // arcsin(x/r) − arcsin(x_a/r) is the angle between the arc points (x_a, y) and (x, y_a), whose sine is (x·y − x_a·y_a)/r².
+    return 0.5 * (xa * y + x * ya + r * r * portableAsin(Math.min(1, (x * y - xa * ya) / (r * r))));
+}
+/** {@link quadrantArea} extended as an odd function of x and of y. */
+function signedQuadrantArea(x, y, r) {
+    const q = quadrantArea(x < 0 ? -x : x, y < 0 ? -y : y, r);
+    return (x < 0) !== (y < 0) ? -q : q;
+}
+/**
+ * Area of the disc inside the cell [i − ½, i + ½] × [j − ½, j + ½], for i ≥ j ≥ 0. Exactly 0 when the cell's point nearest
+ * the centre lies on or outside the circle. Otherwise the four corner terms are up to r² in size, so the difference
+ * carries an absolute rounding error of a few r²·2^-53 (below 10^-11 at the radius cap, under 10^-15 of the disc's area);
+ * a cell that barely touches the disc can come out a rounding error below zero and is set to 0.
+ */
+function cellArea(i, j, r) {
+    const x0 = i - 0.5, x1 = i + 0.5, y0 = j - 0.5, y1 = j + 0.5;
+    const nx = i === 0 ? 0 : x0, ny = j === 0 ? 0 : y0;
+    if (nx * nx + ny * ny >= r * r)
+        return 0;
+    const area = (signedQuadrantArea(x1, y1, r) - signedQuadrantArea(x0, y1, r)) - (signedQuadrantArea(x1, y0, r) - signedQuadrantArea(x0, y0, r));
+    return area > 0 ? area : 0;
+}
+/**
+ * The defocus disc of `diameterSites` (c / pitch) sampled on the site lattice, or null for a zero diameter (in focus:
+ * callers apply no kernel). Fails with `InvalidScientificInputError` for a negative or non-finite diameter, and when
+ * the kernel radius exceeds {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES}.
+ */
+export function createDefocusDiscSiteKernel(diameterSites) {
+    const radius = requireDefocusDiscKernelRadius(diameterSites);
+    if (diameterSites === 0)
+        return null;
+    const r = diameterSites / 2, width = 2 * radius + 1, weights = new Float64Array(width * width);
+    // One octant, mirrored into the eight symmetric cells.
+    for (let i = 0; i <= radius; i++)
+        for (let j = 0; j <= i; j++) {
+            const a = cellArea(i, j, r);
+            for (const [u, v] of [[i, j], [j, i]])
+                for (const su of u === 0 ? [1] : [1, -1])
+                    for (const sv of v === 0 ? [1] : [1, -1])
+                        weights[(sv * v + radius) * width + su * u + radius] = a;
+        }
+    normalize(weights, (width * width - 1) / 2);
+    return { diameterSites, radius, width, weights };
+}
+/**
+ * Divides by the float64 sum, then sets the centre weight to 1 minus the exact sum of the others (accumulated as a
+ * double-double with Knuth's TwoSum), rounded once. The exact real sum of the weights is then 1 within half a unit in
+ * the last place of the centre weight. (No float64 summation order can promise exactly 1: a one-ulp change of one weight
+ * can move a rounded sum from just below 1 to just above it.)
+ */
+function normalize(weights, centre) {
+    let total = 0;
+    for (let k = 0; k < weights.length; k++)
+        total += weights[k];
+    for (let k = 0; k < weights.length; k++)
+        weights[k] /= total;
+    let hi = 0, lo = 0;
+    for (let k = 0; k < weights.length; k++) {
+        if (k === centre)
+            continue;
+        const w = weights[k], s = hi + w, b = s - hi;
+        lo += (hi - (s - b)) + (w - b);
+        hi = s;
+    }
+    // 1 − (hi + lo): TwoSum of 1 and −hi, then the low parts.
+    const s = 1 - hi, b = s - 1, e = (1 - (s - b)) + (-hi - b);
+    weights[centre] = s + (e - lo);
+}
+/**
+ * Resolves the defocus disc for a thin lens focused at `focusDistanceM` imaging a plane at `subjectDistanceM`, on a
+ * lattice of `pitchMicrometers`. Exactly zero when the two distances are equal. It does not check the radius cap.
+ */
+export function resolveDefocusDisc(input) {
+    const { pitchMicrometers, ...circle } = input;
+    if (!Number.isFinite(pitchMicrometers) || pitchMicrometers <= 0)
+        throw new InvalidScientificInputError("pitchMicrometers must be a positive finite number.");
+    const diameterMicrometers = calculateDefocusCircle(circle).value.diameterMm * 1000;
+    const diameterSites = diameterMicrometers / pitchMicrometers;
+    return { diameterMicrometers, diameterSites, kernelRadiusSites: defocusDiscKernelRadius(diameterSites) };
+}
+/**
+ * The full 2-D convolution of two square site kernels (row-major, radii `radiusA` and `radiusB`): a kernel of radius
+ * radiusA + radiusB with out(t) = Σ_s a(s)·b(t − s), each output summed over the taps of `a` in row-major order (zero taps
+ * of either kernel skipped, which adds exact zeros only). Used for lens.defocus with lens.diffraction (#492): each spectral
+ * node's diffraction kernel convolved with the defocus disc. That combination is an approximation: the defocused wave PSF
+ * of a circular pupil is not exactly the in-focus Airy pattern convolved with the geometric disc. Both inputs here are
+ * centred and non-negative, so the result is too; its sum is the product of the inputs' sums up to rounding.
+ */
+export function convolveSiteKernels(a, radiusA, b, radiusB) {
+    const wa = 2 * radiusA + 1, wb = 2 * radiusB + 1, radius = radiusA + radiusB, width = 2 * radius + 1;
+    if (a.length !== wa * wa || b.length !== wb * wb)
+        throw new InvalidScientificInputError("Site kernels must be (2R + 1)² taps.");
+    const out = new Float64Array(width * width);
+    // Non-zero taps of b, as (row, column, weight).
+    const bRows = [], bColumns = [], bWeights = [];
+    for (let j = 0; j < wb; j++)
+        for (let i = 0; i < wb; i++) {
+            const w = b[j * wb + i];
+            if (w !== 0) {
+                bRows.push(j);
+                bColumns.push(i);
+                bWeights.push(w);
+            }
+        }
+    for (let sj = 0; sj < wa; sj++)
+        for (let si = 0; si < wa; si++) {
+            const w = a[sj * wa + si];
+            if (w === 0)
+                continue;
+            for (let k = 0; k < bWeights.length; k++) {
+                const index = (sj + bRows[k]) * width + si + bColumns[k];
+                out[index] = out[index] + w * bWeights[k];
+            }
+        }
+    return out;
+}
+//# sourceMappingURL=defocus-disc-kernel.js.map

package/dist/optics/defocus-disc-kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defocus-disc-kernel.js","sourceRoot":"","sources":["../../src/optics/defocus-disc-kernel.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Internal (not exported from the package): the geometric defocus disc of a flat scene, sampled on the square site\n * lattice, for `lens.defocus: { model: \"geometric-disc\" }` (#492).\n *\n * Model. For a scene plane at the subject distance d and a thin lens focused at s, an ideal uniform circular pupil\n * spreads every in-focus image point into a uniform disc of diameter c = f²·|s − d| / (N·d·(s − f)) on the sensor\n * (`calculateDefocusCircle`, thin-lens model 1.1.0; geometric optics, no diffraction or aberrations). The defocused\n * image of the plane is therefore the in-focus image convolved with that disc: one fixed, wavelength-independent\n * kernel. It is an approximation (geometric optics, ideal uniform circular pupil, no vignetting of the pupil).\n *\n * Sampling. The disc of diameter c/p sites (p the site pitch) is centred on a site centre. The weight of the site at\n * offset (i, j) is the exact area of the disc inside that site's square cell [i − ½, i + ½] × [j − ½, j + ½], divided\n * by the area of the disc. The area of a disc inside a rectangle is a signed sum over the rectangle's four corners of\n * the area Q(x, y) of the disc inside the quadrant [0, x] × [0, y] (inclusion–exclusion), and for x, y ≥ 0 with\n * x, y clamped to the radius r\n *   Q = x·y                                                when x² + y² ≤ r²,\n *   Q = ½·(x_a·y + x·y_a + r²·(arcsin(x/r) − arcsin(x_a/r)))  otherwise,\n * with x_a = √(r² − y²) and y_a = √(r² − x²) the arc's crossings of the quadrant's edges: the rectangle left of the\n * crossing plus the area under the arc, ∫ √(r² − t²) dt = ½·(t·√(r² − t²) + r²·arcsin(t/r)) (elementary geometry\n * and calculus; NIST DLMF 4.24.1 for the arcsine, free). The arcsine difference is the angle between the two arc\n * points, evaluated as arcsin((x·y − x_a·y_a)/r²) (the sine of a difference). Q is extended to negative x or y as an\n * odd function.\n *\n * Determinism. Only correctly rounded operations and `portableAsin` are used, so the weights are the same bits in\n * every JavaScript engine. One octant (0 ≤ j ≤ i) is computed and mirrored, so the kernel has the exact 8-fold\n * symmetry of the disc and the square lattice. The weights are divided by their float64 sum, then the centre weight\n * takes up the remaining rounding, so their exact sum is 1 within half a unit in the last place of the centre weight.\n *\n * Limits. The window is (2R + 1)² sites with R = ⌈r − ½⌉ (0 when r ≤ ½: a disc inside one cell is the identity, a\n * valid kernel). R is capped at {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES}; past it the call fails, naming the\n * cap and the radius asked for, instead of clipping the disc.\n */\n\nimport { portableAsin } from \"../core/portable-math.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { calculateDefocusCircle } from \"./depth-of-field.js\";\n\n/**\n * Largest kernel radius in sites, R ≤ 64 (a 129 × 129 window, 16 641 taps per site; the diffraction kernels stop at 32).\n * Set from the cost measured in the capture (#492, step 2a; docs/QUICK_START.md, \"Optics\"): the capture's time grows with\n * R² at every site the disc sees an edge from, and a 0.7 MP Siemens star took 0.37 s in focus, 2.9 s at R = 32, 4.7 s at\n * R = 41 and 11.6 s at R = 64 (Node, one thread). 64 keeps the issue's 1.4 µm example (50 mm f/2.8, subject 2 m, focus\n * 1.6 m: R = 41) with room for larger blurs, at a cost the caller chooses and the docs state; past it the call fails.\n */\nexport const DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES = 64;\n\n/** The disc sampled on the site lattice. */\nexport interface DefocusDiscSiteKernel {\n  /** Disc diameter in sites (c / pitch). */\n  readonly diameterSites: number;\n  /** Kernel radius R in sites: the window is (2R + 1) × (2R + 1). */\n  readonly radius: number;\n  /** Window side, 2R + 1. */\n  readonly width: number;\n  /** Row-major weights, index (j + R)·width + (i + R) for the site offset (i, j); their row-major float64 sum is 1. */\n  readonly weights: Float64Array;\n}\n\n/** Kernel radius in sites for a disc of `diameterSites`: the cells [i − ½, i + ½] the disc reaches with positive area. */\nexport function defocusDiscKernelRadius(diameterSites: number): number {\n  requireDiameter(diameterSites);\n  const r = diameterSites / 2;\n  return r <= 0.5 ? 0 : Math.ceil(r - 0.5);\n}\n\n/**\n * {@link defocusDiscKernelRadius}, failing with `InvalidScientificInputError` (naming the cap and the radius asked for)\n * when it exceeds {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES}. The disc is never clipped to fit.\n */\nexport function requireDefocusDiscKernelRadius(diameterSites: number): number {\n  const radius = defocusDiscKernelRadius(diameterSites);\n  if (radius > DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES)\n    throw new InvalidScientificInputError(\"The defocus disc of \" + diameterSites + \" sites needs a kernel radius of \" + radius +\n      \" sites; the limit is \" + DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES + \" sites (DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES).\");\n  return radius;\n}\n\nfunction requireDiameter(diameterSites: number): void {\n  if (typeof diameterSites !== \"number\" || !Number.isFinite(diameterSites) || diameterSites < 0)\n    throw new InvalidScientificInputError(\"The defocus disc diameter must be a finite number of sites, zero or more.\");\n}\n\n/** Area of the disc of radius r (centred at the origin) inside [0, x] × [0, y], for x, y ≥ 0. */\nfunction quadrantArea(x: number, y: number, r: number): number {\n  if (x > r) x = r;\n  if (y > r) y = r;\n  if (x * x + y * y <= r * r) return x * y;\n  const xa = Math.sqrt((r - y) * (r + y)), ya = Math.sqrt((r - x) * (r + x));\n  // arcsin(x/r) − arcsin(x_a/r) is the angle between the arc points (x_a, y) and (x, y_a), whose sine is (x·y − x_a·y_a)/r².\n  return 0.5 * (xa * y + x * ya + r * r * portableAsin(Math.min(1, (x * y - xa * ya) / (r * r))));\n}\n/** {@link quadrantArea} extended as an odd function of x and of y. */\nfunction signedQuadrantArea(x: number, y: number, r: number): number {\n  const q = quadrantArea(x < 0 ? -x : x, y < 0 ? -y : y, r);\n  return (x < 0) !== (y < 0) ? -q : q;\n}\n/**\n * Area of the disc inside the cell [i − ½, i + ½] × [j − ½, j + ½], for i ≥ j ≥ 0. Exactly 0 when the cell's point nearest\n * the centre lies on or outside the circle. Otherwise the four corner terms are up to r² in size, so the difference\n * carries an absolute rounding error of a few r²·2^-53 (below 10^-11 at the radius cap, under 10^-15 of the disc's area);\n * a cell that barely touches the disc can come out a rounding error below zero and is set to 0.\n */\nfunction cellArea(i: number, j: number, r: number): number {\n  const x0 = i - 0.5, x1 = i + 0.5, y0 = j - 0.5, y1 = j + 0.5;\n  const nx = i === 0 ? 0 : x0, ny = j === 0 ? 0 : y0;\n  if (nx * nx + ny * ny >= r * r) return 0;\n  const area = (signedQuadrantArea(x1, y1, r) - signedQuadrantArea(x0, y1, r)) - (signedQuadrantArea(x1, y0, r) - signedQuadrantArea(x0, y0, r));\n  return area > 0 ? area : 0;\n}\n\n/**\n * The defocus disc of `diameterSites` (c / pitch) sampled on the site lattice, or null for a zero diameter (in focus:\n * callers apply no kernel). Fails with `InvalidScientificInputError` for a negative or non-finite diameter, and when\n * the kernel radius exceeds {@link DEFOCUS_DISC_KERNEL_MAXIMUM_RADIUS_SITES}.\n */\nexport function createDefocusDiscSiteKernel(diameterSites: number): DefocusDiscSiteKernel | null {\n  const radius = requireDefocusDiscKernelRadius(diameterSites);\n  if (diameterSites === 0) return null;\n  const r = diameterSites / 2, width = 2 * radius + 1, weights = new Float64Array(width * width);\n  // One octant, mirrored into the eight symmetric cells.\n  for (let i = 0; i <= radius; i++) for (let j = 0; j <= i; j++) {\n    const a = cellArea(i, j, r);\n    for (const [u, v] of [[i, j], [j, i]] as const) for (const su of u === 0 ? [1] : [1, -1]) for (const sv of v === 0 ? [1] : [1, -1])\n      weights[(sv * v + radius) * width + su * u + radius] = a;\n  }\n  normalize(weights, (width * width - 1) / 2);\n  return { diameterSites, radius, width, weights };\n}\n\n/**\n * Divides by the float64 sum, then sets the centre weight to 1 minus the exact sum of the others (accumulated as a\n * double-double with Knuth's TwoSum), rounded once. The exact real sum of the weights is then 1 within half a unit in\n * the last place of the centre weight. (No float64 summation order can promise exactly 1: a one-ulp change of one weight\n * can move a rounded sum from just below 1 to just above it.)\n */\nfunction normalize(weights: Float64Array, centre: number): void {\n  let total = 0;\n  for (let k = 0; k < weights.length; k++) total += weights[k]!;\n  for (let k = 0; k < weights.length; k++) weights[k]! /= total;\n  let hi = 0, lo = 0;\n  for (let k = 0; k < weights.length; k++) {\n    if (k === centre) continue;\n    const w = weights[k]!, s = hi + w, b = s - hi;\n    lo += (hi - (s - b)) + (w - b);\n    hi = s;\n  }\n  // 1 − (hi + lo): TwoSum of 1 and −hi, then the low parts.\n  const s = 1 - hi, b = s - 1, e = (1 - (s - b)) + (-hi - b);\n  weights[centre] = s + (e - lo);\n}\n\n/** The geometric defocus disc of one request, in micrometres and in sites. */\nexport interface ResolvedDefocusDisc {\n  /** Blur-circle diameter c at the sensor, µm (`calculateDefocusCircle`, thin-lens model 1.1.0). */\n  readonly diameterMicrometers: number;\n  /** c / pitch. */\n  readonly diameterSites: number;\n  /** Kernel radius R in sites (0 when c = 0). */\n  readonly kernelRadiusSites: number;\n}\n\n/**\n * Resolves the defocus disc for a thin lens focused at `focusDistanceM` imaging a plane at `subjectDistanceM`, on a\n * lattice of `pitchMicrometers`. Exactly zero when the two distances are equal. It does not check the radius cap.\n */\nexport function resolveDefocusDisc(input: { focalLengthMm: number; aperture: number; focusDistanceM: number; subjectDistanceM: number;\n  pitchMicrometers: number }): ResolvedDefocusDisc {\n  const { pitchMicrometers, ...circle } = input;\n  if (!Number.isFinite(pitchMicrometers) || pitchMicrometers <= 0) throw new InvalidScientificInputError(\"pitchMicrometers must be a positive finite number.\");\n  const diameterMicrometers = calculateDefocusCircle(circle).value.diameterMm * 1000;\n  const diameterSites = diameterMicrometers / pitchMicrometers;\n  return { diameterMicrometers, diameterSites, kernelRadiusSites: defocusDiscKernelRadius(diameterSites) };\n}\n\n/**\n * The full 2-D convolution of two square site kernels (row-major, radii `radiusA` and `radiusB`): a kernel of radius\n * radiusA + radiusB with out(t) = Σ_s a(s)·b(t − s), each output summed over the taps of `a` in row-major order (zero taps\n * of either kernel skipped, which adds exact zeros only). Used for lens.defocus with lens.diffraction (#492): each spectral\n * node's diffraction kernel convolved with the defocus disc. That combination is an approximation: the defocused wave PSF\n * of a circular pupil is not exactly the in-focus Airy pattern convolved with the geometric disc. Both inputs here are\n * centred and non-negative, so the result is too; its sum is the product of the inputs' sums up to rounding.\n */\nexport function convolveSiteKernels(a: Float64Array, radiusA: number, b: Float64Array, radiusB: number): Float64Array {\n  const wa = 2 * radiusA + 1, wb = 2 * radiusB + 1, radius = radiusA + radiusB, width = 2 * radius + 1;\n  if (a.length !== wa * wa || b.length !== wb * wb) throw new InvalidScientificInputError(\"Site kernels must be (2R + 1)² taps.\");\n  const out = new Float64Array(width * width);\n  // Non-zero taps of b, as (row, column, weight).\n  const bRows: number[] = [], bColumns: number[] = [], bWeights: number[] = [];\n  for (let j = 0; j < wb; j++) for (let i = 0; i < wb; i++) { const w = b[j * wb + i]!; if (w !== 0) { bRows.push(j); bColumns.push(i); bWeights.push(w); } }\n  for (let sj = 0; sj < wa; sj++) for (let si = 0; si < wa; si++) {\n    const w = a[sj * wa + si]!;\n    if (w === 0) continue;\n    for (let k = 0; k < bWeights.length; k++) {\n      const index = (sj + bRows[k]!) * width + si + bColumns[k]!;\n      out[index] = out[index]! + w * bWeights[k]!;\n    }\n  }\n  return out;\n}\n"]}

package/dist/optics/irradiance-convolution.d.ts

@@ -64,3 +64,14 @@ export declare function calculateIrradianceConvolution(input: IrradianceConvolut
     plan: IrradianceConvolutionPlan;
     values: Float64Array;
 };
+/**
+ * Internal (#453; not exported from the package): runs several convolutions that share one geometry (width, height,
+ * kernel radius, patch size, boundary, pixel limit) with one validation of that geometry. The first call is
+ * `calculateIrradianceConvolution` itself, with every check. Each later call checks its own arrays exactly as the plan
+ * does (array types and lengths against the geometry, every sample, every kernel weight and kernel sum, with the same
+ * messages) and then runs the same gather (`convolveIrradianceRows`) with the first call's plan, whose geometry fields are
+ * the same numbers a full validation of this call would give. The values are therefore identical to one
+ * `calculateIrradianceConvolution` per call; only the repeated record and geometry checks are skipped.
+ * @internal
+ */
+export declare function createIrradianceConvolutionRunner(geometry: Omit<IrradianceConvolutionInput, "samples" | "kernels">): (samples: Float32Array | Float64Array, kernels: Float32Array | Float64Array) => Float64Array;

package/dist/optics/irradiance-convolution.js

@@ -49,6 +49,38 @@ function positiveInteger(value, maximum) {
     }
     return value;
 }
+/** Checks every sample (finite, non-negative, within the declared magnitude) and returns the largest. */
+function checkedMaximumSampleMagnitude(samples) {
+    let maximumSampleMagnitude = 0;
+    for (let i = 0; i < samples.length; i++) {
+        const v = samples[i];
+        // Negated comparison also rejects NaN.
+        if (!(v >= 0 && v <= IRRADIANCE_CONVOLUTION_LIMITS.maximumSampleMagnitude)) {
+            throw new InvalidConfigurationError("Irradiance samples must be finite, non-negative and within the declared magnitude.");
+        }
+        if (v > maximumSampleMagnitude)
+            maximumSampleMagnitude = v;
+    }
+    return maximumSampleMagnitude;
+}
+/** Checks every kernel weight (finite, in [0, 1]) and kernel sum (at most 1 plus slack) and returns the largest sum. */
+function checkedMaximumKernelSum(kernels, patchCount, tapCount) {
+    let maximumKernelSum = 0;
+    for (let p = 0; p < patchCount; p++) {
+        let sum = 0;
+        for (let t = p * tapCount, end = t + tapCount; t < end; t++) {
+            const w = kernels[t];
+            if (!(w >= 0 && w <= 1))
+                throw new InvalidConfigurationError("PSF kernel weights must be finite and within [0, 1].");
+            sum += w;
+        }
+        if (sum > IRRADIANCE_CONVOLUTION_LIMITS.maximumKernelSum)
+            throw new InvalidConfigurationError("A PSF kernel may not create energy (sum exceeds 1).");
+        if (sum > maximumKernelSum)
+            maximumKernelSum = sum;
+    }
+    return maximumKernelSum;
+}
 /** Validates the request and returns its plan. Every sample and weight is checked once. */
 export function calculateIrradianceConvolutionPlan(input) {
     const r = requireAllowlistedRecord(input, ["schemaVersion", "width", "height", "samples", "kernelRadius", "patchWidth",
@@ -76,30 +108,8 @@ export function calculateIrradianceConvolutionPlan(input) {
         !(kernels instanceof Float32Array || kernels instanceof Float64Array) || kernels.length !== patchCount * tapCount) {
         throw new InvalidConfigurationError("Irradiance convolution arrays do not match the declared geometry.");
     }
-    let maximumSampleMagnitude = 0;
-    for (let i = 0; i < samples.length; i++) {
-        const v = samples[i];
-        // Negated comparison also rejects NaN.
-        if (!(v >= 0 && v <= L.maximumSampleMagnitude)) {
-            throw new InvalidConfigurationError("Irradiance samples must be finite, non-negative and within the declared magnitude.");
-        }
-        if (v > maximumSampleMagnitude)
-            maximumSampleMagnitude = v;
-    }
-    let maximumKernelSum = 0;
-    for (let p = 0; p < patchCount; p++) {
-        let sum = 0;
-        for (let t = p * tapCount, end = t + tapCount; t < end; t++) {
-            const w = kernels[t];
-            if (!(w >= 0 && w <= 1))
-                throw new InvalidConfigurationError("PSF kernel weights must be finite and within [0, 1].");
-            sum += w;
-        }
-        if (sum > L.maximumKernelSum)
-            throw new InvalidConfigurationError("A PSF kernel may not create energy (sum exceeds 1).");
-        if (sum > maximumKernelSum)
-            maximumKernelSum = sum;
-    }
+    const maximumSampleMagnitude = checkedMaximumSampleMagnitude(samples);
+    const maximumKernelSum = checkedMaximumKernelSum(kernels, patchCount, tapCount);
     return Object.freeze({ width, height, kernelRadius: radius, kernelSize, tapCount, patchWidth, patchHeight, patchColumns, patchRows,
         maximumKernelSum, maximumSampleMagnitude });
 }
@@ -139,4 +149,34 @@ export function calculateIrradianceConvolution(input) {
     convolveIrradianceRows(plan, input.samples, input.kernels, 0, plan.height, values);
     return { plan, values };
 }
+/**
+ * Internal (#453; not exported from the package): runs several convolutions that share one geometry (width, height,
+ * kernel radius, patch size, boundary, pixel limit) with one validation of that geometry. The first call is
+ * `calculateIrradianceConvolution` itself, with every check. Each later call checks its own arrays exactly as the plan
+ * does (array types and lengths against the geometry, every sample, every kernel weight and kernel sum, with the same
+ * messages) and then runs the same gather (`convolveIrradianceRows`) with the first call's plan, whose geometry fields are
+ * the same numbers a full validation of this call would give. The values are therefore identical to one
+ * `calculateIrradianceConvolution` per call; only the repeated record and geometry checks are skipped.
+ * @internal
+ */
+export function createIrradianceConvolutionRunner(geometry) {
+    let plan;
+    return (samples, kernels) => {
+        if (plan === undefined) {
+            const first = calculateIrradianceConvolution({ ...geometry, samples, kernels });
+            plan = first.plan;
+            return first.values;
+        }
+        const patchCount = plan.patchColumns * plan.patchRows;
+        if (!(samples instanceof Float32Array || samples instanceof Float64Array) || samples.length !== plan.width * plan.height ||
+            !(kernels instanceof Float32Array || kernels instanceof Float64Array) || kernels.length !== patchCount * plan.tapCount) {
+            throw new InvalidConfigurationError("Irradiance convolution arrays do not match the declared geometry.");
+        }
+        checkedMaximumSampleMagnitude(samples);
+        checkedMaximumKernelSum(kernels, patchCount, plan.tapCount);
+        const values = new Float64Array(plan.width * plan.height);
+        convolveIrradianceRows(plan, samples, kernels, 0, plan.height, values);
+        return values;
+    };
+}
 //# sourceMappingURL=irradiance-convolution.js.map

package/dist/optics/irradiance-convolution.js.map

@@ -1 +1 @@
-{"version":3,"file":"irradiance-convolution.js","sourceRoot":"","sources":["../../src/optics/irradiance-convolution.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Blurs a sampled image-plane quantity with caller-supplied PSF (point-spread function) kernels, one\n * kernel per patch of the image. The quantity must be linear and additive (for example irradiance).\n * Each patch is treated as shift-invariant (\"isoplanatic\"): the same PSF applies everywhere inside it.\n * The PSFs are incoherent intensity PSFs.\n *\n * This is the CPU float64 reference for the optics-as-convolution step (#277). The `webgpu-f32`\n * path runs the same equation; see docs/WEBGPU.md.\n *\n * Equation (indexed by source site; an energy-conserving scatter written as a gather):\n *   out(x, y) = Σ_{v=-r..r} Σ_{u=-r..r} in(x − u, y − v) · K_{p(x − u, y − v)}(u, v)\n * where `p(s)` is the patch containing the **source** site and `K_p(u, v)` is the fraction of the source\n * site's quantity that lands at displacement (+u right, +v down), in grid sites.\n *\n * Incoherent imaging is a linear sum of intensity PSFs: the output intensity is the input intensity\n * convolved with the intensity PSF (MIT OpenCourseWare 2.71 Optics, Spring 2009, lecture 22, free).\n * A PSF that varies across the field is approximated as constant inside each patch, as in methods\n * that divide the image into isoplanatic subsections (van de Ketterij et al., arXiv:2011.01738,\n * sec. 1, free). Also see: Goodman, Introduction to Fourier Optics, 4th ed., 2017, §7.1. Camera\n * simulators such as ISETCam use the same piecewise shift-invariant method\n * (Farrell et al., Proc. SPIE 8299, 2012). The caller chooses the patch size and kernels, and so\n * owns the patch approximation.\n *\n * Edges: the grid holds every source. Sources outside the grid are not represented. Anything\n * scattered outside the grid is lost; compare `inputSum` with `outputSum` to see how much. There is no\n * padding, reflection or renormalization.\n */\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { requireAllowlistedRecord } from \"../core/record-validation.js\";\nimport { FULL_RESOLUTION_CEILING_PIXELS, resolveRaisedLimit } from \"../core/pixel-limits.js\";\n\nexport const IRRADIANCE_CONVOLUTION_SCHEMA_VERSION = \"0.1.0\" as const;\n/** `maximumPixels` is the default grid limit; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`. */\nexport const IRRADIANCE_CONVOLUTION_LIMITS = Object.freeze({\n  maximumPixels: 24_000_000,\n  ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,\n  maximumDimension: 16_384,\n  maximumKernelRadius: 32,\n  maximumPatchCount: 4_096,\n  maximumKernelWeights: 4_194_304,\n  /** A kernel may lose energy (vignetting, transmission) but may not create it, beyond rounding slack. */\n  maximumKernelSum: 1 + 2 ** -20,\n  /** Inputs larger than this are rejected so that float32 execution cannot overflow. */\n  maximumSampleMagnitude: 2 ** 100\n});\n\nexport interface IrradianceConvolutionInput {\n  schemaVersion: typeof IRRADIANCE_CONVOLUTION_SCHEMA_VERSION;\n  width: number;\n  height: number;\n  /** Row-major samples. Finite, non-negative, linear and additive (for example irradiance, or expected photons per site). */\n  samples: Float32Array | Float64Array;\n  /** Kernel half-width in grid sites. Each kernel is (2r+1)×(2r+1). */\n  kernelRadius: number;\n  /** Patch size in grid sites. The last row and column of patches may be partial. */\n  patchWidth: number;\n  patchHeight: number;\n  /**\n   * Finite non-negative weights, `[patchRow][patchColumn][v + r][u + r]`, one kernel per patch in\n   * row-major patch order. Each kernel sums to at most 1 (+2^-20 rounding slack).\n   */\n  kernels: Float32Array | Float64Array;\n  boundary: \"zero-outside-grid\";\n  /**\n   * Optional opt-in grid limit for large images: an integer from 1 to `IRRADIANCE_CONVOLUTION_LIMITS.ceilingPixels`.\n   * Default `IRRADIANCE_CONVOLUTION_LIMITS.maximumPixels` (24 000 000). It does not change the result.\n   */\n  maximumPixels?: number;\n}\n\n/** Validated, immutable geometry of a convolution request. Sample arrays are borrowed, not copied. */\nexport interface IrradianceConvolutionPlan {\n  width: number;\n  height: number;\n  kernelRadius: number;\n  kernelSize: number;\n  tapCount: number;\n  patchWidth: number;\n  patchHeight: number;\n  patchColumns: number;\n  patchRows: number;\n  /** Largest kernel sum and largest input magnitude. The float32 error bound uses them. */\n  maximumKernelSum: number;\n  maximumSampleMagnitude: number;\n}\n\nfunction positiveInteger(value: unknown, maximum: number): number {\n  if (typeof value !== \"number\" || !Number.isSafeInteger(value) || value <= 0 || value > maximum) {\n    throw new InvalidConfigurationError(\"Invalid irradiance convolution geometry.\");\n  }\n  return value;\n}\n\n/** Validates the request and returns its plan. Every sample and weight is checked once. */\nexport function calculateIrradianceConvolutionPlan(input: IrradianceConvolutionInput): IrradianceConvolutionPlan {\n  const r = requireAllowlistedRecord(input, [\"schemaVersion\", \"width\", \"height\", \"samples\", \"kernelRadius\", \"patchWidth\",\n    \"patchHeight\", \"kernels\", \"boundary\", \"maximumPixels\"], \"Invalid irradiance convolution input.\");\n  const L = IRRADIANCE_CONVOLUTION_LIMITS;\n  if (r.schemaVersion !== IRRADIANCE_CONVOLUTION_SCHEMA_VERSION || r.boundary !== \"zero-outside-grid\") {\n    throw new InvalidConfigurationError(\"Unsupported irradiance convolution schema or boundary.\");\n  }\n  const width = positiveInteger(r.width, L.maximumDimension), height = positiveInteger(r.height, L.maximumDimension);\n  const maximumPixels = resolveRaisedLimit(r.maximumPixels, L.maximumPixels, L.ceilingPixels,\n    \"Irradiance convolution maximumPixels must be an integer from 1 to \" + L.ceilingPixels + \".\");\n  if (width * height > maximumPixels) throw new InvalidConfigurationError(\"Irradiance convolution grid exceeds the pixel limit.\");\n  const radius = r.kernelRadius;\n  if (typeof radius !== \"number\" || !Number.isSafeInteger(radius) || radius < 0 || radius > L.maximumKernelRadius) {\n    throw new InvalidConfigurationError(\"Invalid irradiance convolution kernel radius.\");\n  }\n  const patchWidth = positiveInteger(r.patchWidth, width), patchHeight = positiveInteger(r.patchHeight, height);\n  const patchColumns = Math.ceil(width / patchWidth), patchRows = Math.ceil(height / patchHeight);\n  const kernelSize = 2 * radius + 1, tapCount = kernelSize * kernelSize, patchCount = patchColumns * patchRows;\n  if (patchCount > L.maximumPatchCount || patchCount * tapCount > L.maximumKernelWeights) {\n    throw new InvalidConfigurationError(\"Irradiance convolution kernels exceed the declared limits.\");\n  }\n  const samples = r.samples, kernels = r.kernels;\n  if (!(samples instanceof Float32Array || samples instanceof Float64Array) || samples.length !== width * height ||\n      !(kernels instanceof Float32Array || kernels instanceof Float64Array) || kernels.length !== patchCount * tapCount) {\n    throw new InvalidConfigurationError(\"Irradiance convolution arrays do not match the declared geometry.\");\n  }\n  let maximumSampleMagnitude = 0;\n  for (let i = 0; i < samples.length; i++) {\n    const v = samples[i]!;\n    // Negated comparison also rejects NaN.\n    if (!(v >= 0 && v <= L.maximumSampleMagnitude)) {\n      throw new InvalidConfigurationError(\"Irradiance samples must be finite, non-negative and within the declared magnitude.\");\n    }\n    if (v > maximumSampleMagnitude) maximumSampleMagnitude = v;\n  }\n  let maximumKernelSum = 0;\n  for (let p = 0; p < patchCount; p++) {\n    let sum = 0;\n    for (let t = p * tapCount, end = t + tapCount; t < end; t++) {\n      const w = kernels[t]!;\n      if (!(w >= 0 && w <= 1)) throw new InvalidConfigurationError(\"PSF kernel weights must be finite and within [0, 1].\");\n      sum += w;\n    }\n    if (sum > L.maximumKernelSum) throw new InvalidConfigurationError(\"A PSF kernel may not create energy (sum exceeds 1).\");\n    if (sum > maximumKernelSum) maximumKernelSum = sum;\n  }\n  return Object.freeze({ width, height, kernelRadius: radius, kernelSize, tapCount, patchWidth, patchHeight, patchColumns, patchRows,\n    maximumKernelSum, maximumSampleMagnitude });\n}\n\n/**\n * Reference gather for output rows `[y0, y1)`, written into `output` at `(y - y0) * width + x`.\n * The summation order (v outer, u inner, both ascending) is part of the contract shared with the\n * WGSL (WebGPU shader) kernel.\n * @internal\n */\nexport function convolveIrradianceRows(plan: IrradianceConvolutionPlan, samples: Float32Array | Float64Array,\n  kernels: Float32Array | Float64Array, y0: number, y1: number, output: Float64Array): void {\n  const { width, height, kernelRadius: r, kernelSize, tapCount, patchWidth, patchHeight, patchColumns, patchRows } = plan;\n  for (let y = y0; y < y1; y++) {\n    for (let x = 0; x < width; x++) {\n      let sum = 0;\n      for (let v = -r; v <= r; v++) {\n        const sy = y - v;\n        if (sy < 0 || sy >= height) continue;\n        const patchRowBase = Math.min(Math.floor(sy / patchHeight), patchRows - 1) * patchColumns;\n        const kernelRow = (v + r) * kernelSize + r, sampleRow = sy * width;\n        for (let u = -r; u <= r; u++) {\n          const sx = x - u;\n          if (sx < 0 || sx >= width) continue;\n          const patch = patchRowBase + Math.min(Math.floor(sx / patchWidth), patchColumns - 1);\n          sum += samples[sampleRow + sx]! * kernels[patch * tapCount + kernelRow + u]!;\n        }\n      }\n      output[(y - y0) * width + x] = sum;\n    }\n  }\n}\n\n/** Synchronous float64 reference for bounded grids. Use the image-kernel accelerator for large grids. */\nexport function calculateIrradianceConvolution(input: IrradianceConvolutionInput): { plan: IrradianceConvolutionPlan; values: Float64Array } {\n  const plan = calculateIrradianceConvolutionPlan(input);\n  const values = new Float64Array(plan.width * plan.height);\n  convolveIrradianceRows(plan, input.samples, input.kernels, 0, plan.height, values);\n  return { plan, values };\n}\n"]}
+{"version":3,"file":"irradiance-convolution.js","sourceRoot":"","sources":["../../src/optics/irradiance-convolution.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Blurs a sampled image-plane quantity with caller-supplied PSF (point-spread function) kernels, one\n * kernel per patch of the image. The quantity must be linear and additive (for example irradiance).\n * Each patch is treated as shift-invariant (\"isoplanatic\"): the same PSF applies everywhere inside it.\n * The PSFs are incoherent intensity PSFs.\n *\n * This is the CPU float64 reference for the optics-as-convolution step (#277). The `webgpu-f32`\n * path runs the same equation; see docs/WEBGPU.md.\n *\n * Equation (indexed by source site; an energy-conserving scatter written as a gather):\n *   out(x, y) = Σ_{v=-r..r} Σ_{u=-r..r} in(x − u, y − v) · K_{p(x − u, y − v)}(u, v)\n * where `p(s)` is the patch containing the **source** site and `K_p(u, v)` is the fraction of the source\n * site's quantity that lands at displacement (+u right, +v down), in grid sites.\n *\n * Incoherent imaging is a linear sum of intensity PSFs: the output intensity is the input intensity\n * convolved with the intensity PSF (MIT OpenCourseWare 2.71 Optics, Spring 2009, lecture 22, free).\n * A PSF that varies across the field is approximated as constant inside each patch, as in methods\n * that divide the image into isoplanatic subsections (van de Ketterij et al., arXiv:2011.01738,\n * sec. 1, free). Also see: Goodman, Introduction to Fourier Optics, 4th ed., 2017, §7.1. Camera\n * simulators such as ISETCam use the same piecewise shift-invariant method\n * (Farrell et al., Proc. SPIE 8299, 2012). The caller chooses the patch size and kernels, and so\n * owns the patch approximation.\n *\n * Edges: the grid holds every source. Sources outside the grid are not represented. Anything\n * scattered outside the grid is lost; compare `inputSum` with `outputSum` to see how much. There is no\n * padding, reflection or renormalization.\n */\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { requireAllowlistedRecord } from \"../core/record-validation.js\";\nimport { FULL_RESOLUTION_CEILING_PIXELS, resolveRaisedLimit } from \"../core/pixel-limits.js\";\n\nexport const IRRADIANCE_CONVOLUTION_SCHEMA_VERSION = \"0.1.0\" as const;\n/** `maximumPixels` is the default grid limit; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`. */\nexport const IRRADIANCE_CONVOLUTION_LIMITS = Object.freeze({\n  maximumPixels: 24_000_000,\n  ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,\n  maximumDimension: 16_384,\n  maximumKernelRadius: 32,\n  maximumPatchCount: 4_096,\n  maximumKernelWeights: 4_194_304,\n  /** A kernel may lose energy (vignetting, transmission) but may not create it, beyond rounding slack. */\n  maximumKernelSum: 1 + 2 ** -20,\n  /** Inputs larger than this are rejected so that float32 execution cannot overflow. */\n  maximumSampleMagnitude: 2 ** 100\n});\n\nexport interface IrradianceConvolutionInput {\n  schemaVersion: typeof IRRADIANCE_CONVOLUTION_SCHEMA_VERSION;\n  width: number;\n  height: number;\n  /** Row-major samples. Finite, non-negative, linear and additive (for example irradiance, or expected photons per site). */\n  samples: Float32Array | Float64Array;\n  /** Kernel half-width in grid sites. Each kernel is (2r+1)×(2r+1). */\n  kernelRadius: number;\n  /** Patch size in grid sites. The last row and column of patches may be partial. */\n  patchWidth: number;\n  patchHeight: number;\n  /**\n   * Finite non-negative weights, `[patchRow][patchColumn][v + r][u + r]`, one kernel per patch in\n   * row-major patch order. Each kernel sums to at most 1 (+2^-20 rounding slack).\n   */\n  kernels: Float32Array | Float64Array;\n  boundary: \"zero-outside-grid\";\n  /**\n   * Optional opt-in grid limit for large images: an integer from 1 to `IRRADIANCE_CONVOLUTION_LIMITS.ceilingPixels`.\n   * Default `IRRADIANCE_CONVOLUTION_LIMITS.maximumPixels` (24 000 000). It does not change the result.\n   */\n  maximumPixels?: number;\n}\n\n/** Validated, immutable geometry of a convolution request. Sample arrays are borrowed, not copied. */\nexport interface IrradianceConvolutionPlan {\n  width: number;\n  height: number;\n  kernelRadius: number;\n  kernelSize: number;\n  tapCount: number;\n  patchWidth: number;\n  patchHeight: number;\n  patchColumns: number;\n  patchRows: number;\n  /** Largest kernel sum and largest input magnitude. The float32 error bound uses them. */\n  maximumKernelSum: number;\n  maximumSampleMagnitude: number;\n}\n\nfunction positiveInteger(value: unknown, maximum: number): number {\n  if (typeof value !== \"number\" || !Number.isSafeInteger(value) || value <= 0 || value > maximum) {\n    throw new InvalidConfigurationError(\"Invalid irradiance convolution geometry.\");\n  }\n  return value;\n}\n\n/** Checks every sample (finite, non-negative, within the declared magnitude) and returns the largest. */\nfunction checkedMaximumSampleMagnitude(samples: Float32Array | Float64Array): number {\n  let maximumSampleMagnitude = 0;\n  for (let i = 0; i < samples.length; i++) {\n    const v = samples[i]!;\n    // Negated comparison also rejects NaN.\n    if (!(v >= 0 && v <= IRRADIANCE_CONVOLUTION_LIMITS.maximumSampleMagnitude)) {\n      throw new InvalidConfigurationError(\"Irradiance samples must be finite, non-negative and within the declared magnitude.\");\n    }\n    if (v > maximumSampleMagnitude) maximumSampleMagnitude = v;\n  }\n  return maximumSampleMagnitude;\n}\n\n/** Checks every kernel weight (finite, in [0, 1]) and kernel sum (at most 1 plus slack) and returns the largest sum. */\nfunction checkedMaximumKernelSum(kernels: Float32Array | Float64Array, patchCount: number, tapCount: number): number {\n  let maximumKernelSum = 0;\n  for (let p = 0; p < patchCount; p++) {\n    let sum = 0;\n    for (let t = p * tapCount, end = t + tapCount; t < end; t++) {\n      const w = kernels[t]!;\n      if (!(w >= 0 && w <= 1)) throw new InvalidConfigurationError(\"PSF kernel weights must be finite and within [0, 1].\");\n      sum += w;\n    }\n    if (sum > IRRADIANCE_CONVOLUTION_LIMITS.maximumKernelSum) throw new InvalidConfigurationError(\"A PSF kernel may not create energy (sum exceeds 1).\");\n    if (sum > maximumKernelSum) maximumKernelSum = sum;\n  }\n  return maximumKernelSum;\n}\n\n/** Validates the request and returns its plan. Every sample and weight is checked once. */\nexport function calculateIrradianceConvolutionPlan(input: IrradianceConvolutionInput): IrradianceConvolutionPlan {\n  const r = requireAllowlistedRecord(input, [\"schemaVersion\", \"width\", \"height\", \"samples\", \"kernelRadius\", \"patchWidth\",\n    \"patchHeight\", \"kernels\", \"boundary\", \"maximumPixels\"], \"Invalid irradiance convolution input.\");\n  const L = IRRADIANCE_CONVOLUTION_LIMITS;\n  if (r.schemaVersion !== IRRADIANCE_CONVOLUTION_SCHEMA_VERSION || r.boundary !== \"zero-outside-grid\") {\n    throw new InvalidConfigurationError(\"Unsupported irradiance convolution schema or boundary.\");\n  }\n  const width = positiveInteger(r.width, L.maximumDimension), height = positiveInteger(r.height, L.maximumDimension);\n  const maximumPixels = resolveRaisedLimit(r.maximumPixels, L.maximumPixels, L.ceilingPixels,\n    \"Irradiance convolution maximumPixels must be an integer from 1 to \" + L.ceilingPixels + \".\");\n  if (width * height > maximumPixels) throw new InvalidConfigurationError(\"Irradiance convolution grid exceeds the pixel limit.\");\n  const radius = r.kernelRadius;\n  if (typeof radius !== \"number\" || !Number.isSafeInteger(radius) || radius < 0 || radius > L.maximumKernelRadius) {\n    throw new InvalidConfigurationError(\"Invalid irradiance convolution kernel radius.\");\n  }\n  const patchWidth = positiveInteger(r.patchWidth, width), patchHeight = positiveInteger(r.patchHeight, height);\n  const patchColumns = Math.ceil(width / patchWidth), patchRows = Math.ceil(height / patchHeight);\n  const kernelSize = 2 * radius + 1, tapCount = kernelSize * kernelSize, patchCount = patchColumns * patchRows;\n  if (patchCount > L.maximumPatchCount || patchCount * tapCount > L.maximumKernelWeights) {\n    throw new InvalidConfigurationError(\"Irradiance convolution kernels exceed the declared limits.\");\n  }\n  const samples = r.samples, kernels = r.kernels;\n  if (!(samples instanceof Float32Array || samples instanceof Float64Array) || samples.length !== width * height ||\n      !(kernels instanceof Float32Array || kernels instanceof Float64Array) || kernels.length !== patchCount * tapCount) {\n    throw new InvalidConfigurationError(\"Irradiance convolution arrays do not match the declared geometry.\");\n  }\n  const maximumSampleMagnitude = checkedMaximumSampleMagnitude(samples);\n  const maximumKernelSum = checkedMaximumKernelSum(kernels, patchCount, tapCount);\n  return Object.freeze({ width, height, kernelRadius: radius, kernelSize, tapCount, patchWidth, patchHeight, patchColumns, patchRows,\n    maximumKernelSum, maximumSampleMagnitude });\n}\n\n/**\n * Reference gather for output rows `[y0, y1)`, written into `output` at `(y - y0) * width + x`.\n * The summation order (v outer, u inner, both ascending) is part of the contract shared with the\n * WGSL (WebGPU shader) kernel.\n * @internal\n */\nexport function convolveIrradianceRows(plan: IrradianceConvolutionPlan, samples: Float32Array | Float64Array,\n  kernels: Float32Array | Float64Array, y0: number, y1: number, output: Float64Array): void {\n  const { width, height, kernelRadius: r, kernelSize, tapCount, patchWidth, patchHeight, patchColumns, patchRows } = plan;\n  for (let y = y0; y < y1; y++) {\n    for (let x = 0; x < width; x++) {\n      let sum = 0;\n      for (let v = -r; v <= r; v++) {\n        const sy = y - v;\n        if (sy < 0 || sy >= height) continue;\n        const patchRowBase = Math.min(Math.floor(sy / patchHeight), patchRows - 1) * patchColumns;\n        const kernelRow = (v + r) * kernelSize + r, sampleRow = sy * width;\n        for (let u = -r; u <= r; u++) {\n          const sx = x - u;\n          if (sx < 0 || sx >= width) continue;\n          const patch = patchRowBase + Math.min(Math.floor(sx / patchWidth), patchColumns - 1);\n          sum += samples[sampleRow + sx]! * kernels[patch * tapCount + kernelRow + u]!;\n        }\n      }\n      output[(y - y0) * width + x] = sum;\n    }\n  }\n}\n\n/** Synchronous float64 reference for bounded grids. Use the image-kernel accelerator for large grids. */\nexport function calculateIrradianceConvolution(input: IrradianceConvolutionInput): { plan: IrradianceConvolutionPlan; values: Float64Array } {\n  const plan = calculateIrradianceConvolutionPlan(input);\n  const values = new Float64Array(plan.width * plan.height);\n  convolveIrradianceRows(plan, input.samples, input.kernels, 0, plan.height, values);\n  return { plan, values };\n}\n\n/**\n * Internal (#453; not exported from the package): runs several convolutions that share one geometry (width, height,\n * kernel radius, patch size, boundary, pixel limit) with one validation of that geometry. The first call is\n * `calculateIrradianceConvolution` itself, with every check. Each later call checks its own arrays exactly as the plan\n * does (array types and lengths against the geometry, every sample, every kernel weight and kernel sum, with the same\n * messages) and then runs the same gather (`convolveIrradianceRows`) with the first call's plan, whose geometry fields are\n * the same numbers a full validation of this call would give. The values are therefore identical to one\n * `calculateIrradianceConvolution` per call; only the repeated record and geometry checks are skipped.\n * @internal\n */\nexport function createIrradianceConvolutionRunner(geometry: Omit<IrradianceConvolutionInput, \"samples\" | \"kernels\">):\n  (samples: Float32Array | Float64Array, kernels: Float32Array | Float64Array) => Float64Array {\n  let plan: IrradianceConvolutionPlan | undefined;\n  return (samples, kernels) => {\n    if (plan === undefined) {\n      const first = calculateIrradianceConvolution({ ...geometry, samples, kernels });\n      plan = first.plan;\n      return first.values;\n    }\n    const patchCount = plan.patchColumns * plan.patchRows;\n    if (!(samples instanceof Float32Array || samples instanceof Float64Array) || samples.length !== plan.width * plan.height ||\n        !(kernels instanceof Float32Array || kernels instanceof Float64Array) || kernels.length !== patchCount * plan.tapCount) {\n      throw new InvalidConfigurationError(\"Irradiance convolution arrays do not match the declared geometry.\");\n    }\n    checkedMaximumSampleMagnitude(samples);\n    checkedMaximumKernelSum(kernels, patchCount, plan.tapCount);\n    const values = new Float64Array(plan.width * plan.height);\n    convolveIrradianceRows(plan, samples, kernels, 0, plan.height, values);\n    return values;\n  };\n}\n"]}

package/dist/optics/scene-to-sensor-irradiance.d.ts

@@ -212,6 +212,19 @@ export declare function parseSceneToSensorIrradianceProfile(value: unknown): Sce
  * factor 1/(1 + m)² from it, so the two cannot drift apart.
  */
 export declare function thinLensWorkingFNumberFactor(focalLengthMm: number, objectDistanceM: number): number;
+/**
+ * Internal (#453; not exported from the package): the sensor-plane spectral irradiance that
+ * {@link calculateSceneRadianceToSensorIrradiance} returns, for repeated queries of one optical state. This call runs the
+ * request-independent checks once (the public function's own code, in its order); each call of the returned function then
+ * runs the public function's per-query steps on an engine-built request and a result already parsed by the caller: the identity
+ * match, the wavelength-basis check, the transmission or T-stop path, the front-of-lens filters, the field throughput and
+ * the finite, non-negative irradiance, with the same operations, order and errors. It skips only the re-validation of the
+ * unchanged optical inputs, the re-parse of the request and result, and the result envelope.
+ */
+export declare function prepareSceneRadianceToSensorIrradianceValue(optics: Pick<CalculateSceneRadianceToSensorIrradianceInput, "profile" | "focalLengthMm" | "nominalFNumber" | "focus" | "frontOfLensFilters">): (request: SceneRadianceEvaluationRequest, result: SceneRadianceEvaluationResult, imagePointMm: {
+    x: number;
+    y: number;
+}, fieldThroughput: OpticalBridgeFieldThroughput) => number;
 /**
  * Applies the declared pupil acceptance and exactly one transmission or field-throughput path to
  * spectral scene radiance. Returns the irradiance before the sensor stack, with conservative

package/dist/optics/scene-to-sensor-irradiance.js

@@ -484,30 +484,7 @@ function validateSceneIdentity(request, result) {
         throw new InvalidScientificInputError("Scene-radiance request/result identity must match exactly.");
     }
 }
-/**
- * Applies the declared pupil acceptance and exactly one transmission or field-throughput path to
- * spectral scene radiance. Returns the irradiance before the sensor stack, with conservative
- * evidence.
- *
- * The optical bridge turns outgoing scene radiance (W/m²/sr/nm) into irradiance (W/m²/nm) arriving
- * at the front of the sensor stack.
- * - Circular paraxial acceptance is pi/(4*Nworking²). At finite focus with unit pupil magnification,
- *   the working f-number is N*(1+m).
- * - Spectral transmission and an effective working T-stop are alternative paths; use one.
- * - Field throughput is applied exactly once.
- * - Sensor response and PSF (point-spread function) blur happen later in the pipeline.
- * @param input - CalculateSceneRadianceToSensorIrradianceInput. See that type for coordinates, units and profile binding.
- * @returns CalculationResult<
-  SceneToSensorIrradianceResult
->. The result states its shape and scientific status; a successful call does not imply calibration.
- *
- * @see docs/API_REFERENCE.md for the root export and exact type graph.
- */
-export function calculateSceneRadianceToSensorIrradiance(input) {
-    requireInputKeys(input, "calculateSceneRadianceToSensorIrradiance", ["sceneRadianceRequest", "sceneRadianceResult", "profile", "focalLengthMm", "nominalFNumber", "focus", "imagePointMm", "fieldThroughput", "frontOfLensFilters"]);
-    const request = parseSceneRadianceEvaluationRequest(input.sceneRadianceRequest);
-    const sceneResult = parseSceneRadianceEvaluationResult(input.sceneRadianceResult);
-    validateSceneIdentity(request, sceneResult);
+function prepareSceneRadianceToSensorIrradiance(input) {
     const profile = parseSceneToSensorIrradianceProfile(input.profile);
     const focalLengthMm = requirePositiveFiniteScientific(input.focalLengthMm, "focalLengthMm");
     const nominalFNumber = requirePositiveFiniteScientific(input.nominalFNumber, "nominalFNumber");
@@ -535,6 +512,15 @@ export function calculateSceneRadianceToSensorIrradiance(input) {
         throw new InvalidScientificInputError("Paraxial geometric acceptance must remain finite and greater than zero.");
     }
     const transmission = profile.transmission;
+    return { profile, focalLengthMm, nominalFNumber, working, workingFNumberValue, geometricAcceptance, transmission };
+}
+/**
+ * The per-query part of {@link calculateSceneRadianceToSensorIrradiance}, after the request and result are parsed and their
+ * identities matched: the wavelength-basis check, the transmission or T-stop path, the front-of-lens filters, the field
+ * throughput and the irradiance, with the same operations in the same order.
+ */
+function applySceneRadianceToSensorIrradiance(prepared, input, request, sceneResult) {
+    const { workingFNumberValue, geometricAcceptance, transmission } = prepared;
     if (request.wavelengthBasis !==
         transmission.wavelengthBasis) {
         throw new InvalidScientificInputError("Scene-radiance and optical-transmission wavelength bases must match; implicit air/vacuum conversion is not performed.");
@@ -616,6 +602,54 @@ export function calculateSceneRadianceToSensorIrradiance(input) {
         irradiance < 0) {
         throw new InvalidScientificInputError("Sensor-plane spectral irradiance must remain finite and non-negative.");
     }
+    return { spectralTransmissionFactor, effectiveWorkingTStop, tStopEquivalentTransmissionFactor, effectiveAcceptance, transmissionEvidence,
+        frontOfLensFilterCount, frontOfLensFilterPolarizationModeled, frontOfLensFilterTransmissionFactor, frontOfLensFilterAttenuationStops,
+        frontOfLensFilterEvidence, frontOfLensFilterLimitations, fieldThroughputFactor, sceneRadiance, irradiance };
+}
+/**
+ * Internal (#453; not exported from the package): the sensor-plane spectral irradiance that
+ * {@link calculateSceneRadianceToSensorIrradiance} returns, for repeated queries of one optical state. This call runs the
+ * request-independent checks once (the public function's own code, in its order); each call of the returned function then
+ * runs the public function's per-query steps on an engine-built request and a result already parsed by the caller: the identity
+ * match, the wavelength-basis check, the transmission or T-stop path, the front-of-lens filters, the field throughput and
+ * the finite, non-negative irradiance, with the same operations, order and errors. It skips only the re-validation of the
+ * unchanged optical inputs, the re-parse of the request and result, and the result envelope.
+ */
+export function prepareSceneRadianceToSensorIrradianceValue(optics) {
+    const prepared = prepareSceneRadianceToSensorIrradiance(optics);
+    const frontOfLensFilters = optics.frontOfLensFilters;
+    return (request, result, imagePointMm, fieldThroughput) => {
+        validateSceneIdentity(request, result);
+        return applySceneRadianceToSensorIrradiance(prepared, { imagePointMm, fieldThroughput, frontOfLensFilters }, request, result).irradiance;
+    };
+}
+/**
+ * Applies the declared pupil acceptance and exactly one transmission or field-throughput path to
+ * spectral scene radiance. Returns the irradiance before the sensor stack, with conservative
+ * evidence.
+ *
+ * The optical bridge turns outgoing scene radiance (W/m²/sr/nm) into irradiance (W/m²/nm) arriving
+ * at the front of the sensor stack.
+ * - Circular paraxial acceptance is pi/(4*Nworking²). At finite focus with unit pupil magnification,
+ *   the working f-number is N*(1+m).
+ * - Spectral transmission and an effective working T-stop are alternative paths; use one.
+ * - Field throughput is applied exactly once.
+ * - Sensor response and PSF (point-spread function) blur happen later in the pipeline.
+ * @param input - CalculateSceneRadianceToSensorIrradianceInput. See that type for coordinates, units and profile binding.
+ * @returns CalculationResult<
+  SceneToSensorIrradianceResult
+>. The result states its shape and scientific status; a successful call does not imply calibration.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function calculateSceneRadianceToSensorIrradiance(input) {
+    requireInputKeys(input, "calculateSceneRadianceToSensorIrradiance", ["sceneRadianceRequest", "sceneRadianceResult", "profile", "focalLengthMm", "nominalFNumber", "focus", "imagePointMm", "fieldThroughput", "frontOfLensFilters"]);
+    const request = parseSceneRadianceEvaluationRequest(input.sceneRadianceRequest);
+    const sceneResult = parseSceneRadianceEvaluationResult(input.sceneRadianceResult);
+    validateSceneIdentity(request, sceneResult);
+    const prepared = prepareSceneRadianceToSensorIrradiance(input);
+    const { profile, focalLengthMm, nominalFNumber, working, workingFNumberValue, geometricAcceptance, transmission } = prepared;
+    const { spectralTransmissionFactor, effectiveWorkingTStop, tStopEquivalentTransmissionFactor, effectiveAcceptance, transmissionEvidence, frontOfLensFilterCount, frontOfLensFilterPolarizationModeled, frontOfLensFilterTransmissionFactor, frontOfLensFilterAttenuationStops, frontOfLensFilterEvidence, frontOfLensFilterLimitations, fieldThroughputFactor, sceneRadiance, irradiance } = applySceneRadianceToSensorIrradiance(prepared, input, request, sceneResult);
     const limitations = [
         ...profile.limitations,
         ...frontOfLensFilterLimitations,