@photivra/engine 2.0.0 → 2.2.0

package/dist/motion/temporal-exposure-sum.js.map

@@ -1 +1 @@
-{"version":3,"file":"temporal-exposure-sum.js","sourceRoot":"","sources":["../../src/motion/temporal-exposure-sum.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Exposure and motion as a weighted sum of shifted frames (#277, image-formation step 3). The CPU\n * float64 reference for the `webgpu-f32` temporal stage; see docs/WEBGPU.md.\n *\n * A site's exposure is the time integral of its image-plane rate quantity over its own exposure window,\n * H = ∫ E(x, t) dt (EMVA Standard 1288 Release 4.0 Linear, §2, free; CIPA DC-004-2020 §5.5, free). For an\n * image that translates rigidly by d(t) on the sensor, E(x, t) = E₀(x − d(t)), so a temporal quadrature\n * with nodes t_k and weights w_k gives\n *\n *   out(x, y) = Σ_k w_k(y) · E₀(x − dx_k, y − dy_k).\n *\n * Motion blur is this superposition of displaced images (Szeliski, *Computer Vision: Algorithms and\n * Applications*, 2nd ed., 2022, free at https://szeliski.org/Book/). The weights depend on the row so a\n * rolling shutter, whose rows start and end their exposure at different times, is the same sum with\n * row-dependent windows (Meingast, Geyer & Sastry, \"Geometric Models of Rolling-Shutter Cameras\",\n * arXiv:cs/0503076, free); a global shutter uses the same weights on every row.\n *\n * Declared approximations, owned by the caller: the quadrature nodes and weights, and rigid translation\n * (no rotation, warp or occlusion). Sub-site displacements use bilinear interpolation between the four\n * nearest site centres, which is linear interpolation and slightly low-pass; it is labelled as an\n * approximation, not exact resampling. Sources outside the grid are zero; no padding or renormalization.\n */\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { requireAllowlistedRecord } from \"../core/record-validation.js\";\n\nexport const TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION = \"0.1.0\" as const;\nexport const TEMPORAL_EXPOSURE_SUM_LIMITS = Object.freeze({\n  maximumPixels: 24_000_000,\n  maximumDimension: 16_384,\n  maximumTemporalSamples: 256,\n  maximumDisplacementSites: 4_096,\n  maximumRowWeights: 4_194_304,\n  /** Keeps every float32 partial sum finite: 256 · 2^16 · 2^100 < 2^128. */\n  maximumSampleMagnitude: 2 ** 100,\n  maximumWeight: 2 ** 16\n});\n\nexport interface TemporalExposureSumInput {\n  schemaVersion: typeof TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION;\n  width: number;\n  height: number;\n  /** Row-major rate samples E₀ at site centres. Finite, non-negative, linear and additive (irradiance, photon or electron rate). */\n  samples: Float32Array | Float64Array;\n  /** Image displacement at each temporal node in grid sites, interleaved (dx₀, dy₀, dx₁, dy₁, …); +x right, +y down. */\n  displacements: Float64Array;\n  /** Quadrature weights `[k][row]` (nodes × height), finite and non-negative, for example seconds of each row's window near t_k. */\n  rowWeights: Float32Array | Float64Array;\n  boundary: \"zero-outside-grid\";\n}\n\n/** One temporal node: integer source offset of the top-left tap and the four bilinear weights (float64). */\nexport interface TemporalExposureSumNode {\n  offsetX: number;\n  offsetY: number;\n  weights: readonly [number, number, number, number];\n}\n\nexport interface TemporalExposureSumPlan {\n  width: number;\n  height: number;\n  nodeCount: number;\n  nodes: readonly TemporalExposureSumNode[];\n  maximumSampleMagnitude: number;\n  /** Largest Σ_k w_k(y) over rows; the operator's weight sum for error composition. */\n  maximumRowWeightSum: number;\n  maximumWeight: number;\n  /** True when every displacement is a whole number of sites (no interpolation). */\n  integerDisplacements: boolean;\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 temporal exposure sum geometry.\");\n  }\n  return value;\n}\n\n/** Validates the request (every value once) and returns its plan. */\nexport function calculateTemporalExposureSumPlan(input: TemporalExposureSumInput): TemporalExposureSumPlan {\n  const r = requireAllowlistedRecord(input, [\"schemaVersion\", \"width\", \"height\", \"samples\", \"displacements\", \"rowWeights\", \"boundary\"],\n    \"Invalid temporal exposure sum input.\");\n  const L = TEMPORAL_EXPOSURE_SUM_LIMITS;\n  if (r.schemaVersion !== TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION || r.boundary !== \"zero-outside-grid\") {\n    throw new InvalidConfigurationError(\"Unsupported temporal exposure sum schema or boundary.\");\n  }\n  const width = positiveInteger(r.width, L.maximumDimension), height = positiveInteger(r.height, L.maximumDimension);\n  if (width * height > L.maximumPixels) throw new InvalidConfigurationError(\"Temporal exposure sum grid exceeds the pixel limit.\");\n  const samples = r.samples, displacements = r.displacements, weights = r.rowWeights;\n  if (!(displacements instanceof Float64Array) || displacements.length < 2 || displacements.length % 2 !== 0 ||\n      displacements.length / 2 > L.maximumTemporalSamples) {\n    throw new InvalidConfigurationError(\"Temporal exposure sum needs 1 to 256 displacement pairs.\");\n  }\n  const nodeCount = displacements.length / 2;\n  if (!(samples instanceof Float32Array || samples instanceof Float64Array) || samples.length !== width * height ||\n      !(weights instanceof Float32Array || weights instanceof Float64Array) || weights.length !== nodeCount * height ||\n      weights.length > L.maximumRowWeights) {\n    throw new InvalidConfigurationError(\"Temporal exposure sum 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    if (!(v >= 0 && v <= L.maximumSampleMagnitude)) throw new InvalidConfigurationError(\"Temporal samples must be finite, non-negative and bounded.\");\n    if (v > maximumSampleMagnitude) maximumSampleMagnitude = v;\n  }\n  let maximumWeight = 0, maximumRowWeightSum = 0;\n  const rowSums = new Float64Array(height);\n  for (let k = 0; k < nodeCount; k++) {\n    for (let y = 0; y < height; y++) {\n      const w = weights[k * height + y]!;\n      if (!(w >= 0 && w <= L.maximumWeight)) throw new InvalidConfigurationError(\"Temporal row weights must be finite, non-negative and bounded.\");\n      if (w > maximumWeight) maximumWeight = w;\n      rowSums[y]! += w;\n    }\n  }\n  for (const s of rowSums) if (s > maximumRowWeightSum) maximumRowWeightSum = s;\n  let integerDisplacements = true;\n  const nodes: TemporalExposureSumNode[] = [];\n  for (let k = 0; k < nodeCount; k++) {\n    const dx = displacements[2 * k]!, dy = displacements[2 * k + 1]!;\n    if (!(Math.abs(dx) <= L.maximumDisplacementSites && Math.abs(dy) <= L.maximumDisplacementSites)) {\n      throw new InvalidConfigurationError(\"Temporal displacements must be finite and within 4096 sites.\");\n    }\n    // Source position x − dx = x + offsetX + ax with ax in [0, 1).\n    const offsetX = Math.floor(-dx), offsetY = Math.floor(-dy), ax = -dx - offsetX, ay = -dy - offsetY;\n    if (ax !== 0 || ay !== 0) integerDisplacements = false;\n    nodes.push(Object.freeze({ offsetX, offsetY,\n      weights: Object.freeze([(1 - ax) * (1 - ay), ax * (1 - ay), (1 - ax) * ay, ax * ay] as const) }));\n  }\n  return Object.freeze({ width, height, nodeCount, nodes: Object.freeze(nodes), maximumSampleMagnitude, maximumRowWeightSum, maximumWeight,\n    integerDisplacements });\n}\n\n/**\n * Reference rows `[y0, y1)` into `output` at `(y − y0)·width + x`. The order (node ascending; taps 00,\n * 10, 01, 11 summed left to right; then times the row weight) is part of the contract shared with the\n * WGSL kernel.\n * @internal\n */\nexport function sumTemporalExposureRows(plan: TemporalExposureSumPlan, samples: Float32Array | Float64Array, rowWeights: Float32Array | Float64Array,\n  y0: number, y1: number, output: Float64Array): void {\n  const { width, height, nodes } = plan;\n  for (let y = y0; y < y1; y++) {\n    for (let x = 0; x < width; x++) {\n      let sum = 0;\n      for (let k = 0; k < nodes.length; k++) {\n        const node = nodes[k]!, sx = x + node.offsetX, sy = y + node.offsetY, b = node.weights;\n        const left = sx >= 0 && sx < width, right = sx + 1 >= 0 && sx + 1 < width;\n        const top = sy >= 0 && sy < height, bottom = sy + 1 >= 0 && sy + 1 < height;\n        let inner = 0;\n        if (top && left) inner += b[0] * samples[sy * width + sx]!;\n        if (top && right) inner += b[1] * samples[sy * width + sx + 1]!;\n        if (bottom && left) inner += b[2] * samples[(sy + 1) * width + sx]!;\n        if (bottom && right) inner += b[3] * samples[(sy + 1) * width + sx + 1]!;\n        sum += rowWeights[k * height + y]! * inner;\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 calculateTemporalExposureSum(input: TemporalExposureSumInput): { plan: TemporalExposureSumPlan; values: Float64Array } {\n  const plan = calculateTemporalExposureSumPlan(input);\n  const values = new Float64Array(plan.width * plan.height);\n  sumTemporalExposureRows(plan, input.samples, input.rowWeights, 0, plan.height, values);\n  return { plan, values };\n}\n"]}
+{"version":3,"file":"temporal-exposure-sum.js","sourceRoot":"","sources":["../../src/motion/temporal-exposure-sum.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Exposure and motion as a weighted sum of shifted frames (#277, image-formation step 3). The CPU\n * float64 reference for the `webgpu-f32` temporal stage; see docs/WEBGPU.md.\n *\n * A site's exposure is the time integral of its image-plane rate quantity over its own exposure window,\n * H = ∫ E(x, t) dt (EMVA Standard 1288 Release 4.0 Linear, §2, free; CIPA DC-004-2020 §5.5, free). For an\n * image that translates rigidly by d(t) on the sensor, E(x, t) = E₀(x − d(t)), so a temporal quadrature\n * with nodes t_k and weights w_k gives\n *\n *   out(x, y) = Σ_k w_k(y) · E₀(x − dx_k, y − dy_k).\n *\n * Motion blur is this superposition of displaced images (Szeliski, *Computer Vision: Algorithms and\n * Applications*, 2nd ed., 2022, free at https://szeliski.org/Book/). The weights depend on the row so a\n * rolling shutter, whose rows start and end their exposure at different times, is the same sum with\n * row-dependent windows (Meingast, Geyer & Sastry, \"Geometric Models of Rolling-Shutter Cameras\",\n * arXiv:cs/0503076, free); a global shutter uses the same weights on every row.\n *\n * Declared approximations, owned by the caller: the quadrature nodes and weights, and rigid translation\n * (no rotation, warp or occlusion). Sub-site displacements use bilinear interpolation between the four\n * nearest site centres, which is linear interpolation and slightly low-pass; it is labelled as an\n * approximation, not exact resampling. Sources outside the grid are zero; no padding 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 TEMPORAL_EXPOSURE_SUM_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 TEMPORAL_EXPOSURE_SUM_LIMITS = Object.freeze({\n  maximumPixels: 24_000_000,\n  ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,\n  maximumDimension: 16_384,\n  maximumTemporalSamples: 256,\n  maximumDisplacementSites: 4_096,\n  maximumRowWeights: 4_194_304,\n  /** Keeps every float32 partial sum finite: 256 · 2^16 · 2^100 < 2^128. */\n  maximumSampleMagnitude: 2 ** 100,\n  maximumWeight: 2 ** 16\n});\n\nexport interface TemporalExposureSumInput {\n  schemaVersion: typeof TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION;\n  width: number;\n  height: number;\n  /** Row-major rate samples E₀ at site centres. Finite, non-negative, linear and additive (irradiance, photon or electron rate). */\n  samples: Float32Array | Float64Array;\n  /** Image displacement at each temporal node in grid sites, interleaved (dx₀, dy₀, dx₁, dy₁, …); +x right, +y down. */\n  displacements: Float64Array;\n  /** Quadrature weights `[k][row]` (nodes × height), finite and non-negative, for example seconds of each row's window near t_k. */\n  rowWeights: Float32Array | Float64Array;\n  boundary: \"zero-outside-grid\";\n  /**\n   * Optional opt-in grid limit for large images: an integer from 1 to `TEMPORAL_EXPOSURE_SUM_LIMITS.ceilingPixels`.\n   * Default `TEMPORAL_EXPOSURE_SUM_LIMITS.maximumPixels` (24 000 000). It does not change the result.\n   */\n  maximumPixels?: number;\n}\n\n/** One temporal node: integer source offset of the top-left tap and the four bilinear weights (float64). */\nexport interface TemporalExposureSumNode {\n  offsetX: number;\n  offsetY: number;\n  weights: readonly [number, number, number, number];\n}\n\nexport interface TemporalExposureSumPlan {\n  width: number;\n  height: number;\n  nodeCount: number;\n  nodes: readonly TemporalExposureSumNode[];\n  maximumSampleMagnitude: number;\n  /** Largest Σ_k w_k(y) over rows; the operator's weight sum for error composition. */\n  maximumRowWeightSum: number;\n  maximumWeight: number;\n  /** True when every displacement is a whole number of sites (no interpolation). */\n  integerDisplacements: boolean;\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 temporal exposure sum geometry.\");\n  }\n  return value;\n}\n\n/** Validates the request (every value once) and returns its plan. */\nexport function calculateTemporalExposureSumPlan(input: TemporalExposureSumInput): TemporalExposureSumPlan {\n  const r = requireAllowlistedRecord(input, [\"schemaVersion\", \"width\", \"height\", \"samples\", \"displacements\", \"rowWeights\", \"boundary\", \"maximumPixels\"],\n    \"Invalid temporal exposure sum input.\");\n  const L = TEMPORAL_EXPOSURE_SUM_LIMITS;\n  if (r.schemaVersion !== TEMPORAL_EXPOSURE_SUM_SCHEMA_VERSION || r.boundary !== \"zero-outside-grid\") {\n    throw new InvalidConfigurationError(\"Unsupported temporal exposure sum 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    \"Temporal exposure sum maximumPixels must be an integer from 1 to \" + L.ceilingPixels + \".\");\n  if (width * height > maximumPixels) throw new InvalidConfigurationError(\"Temporal exposure sum grid exceeds the pixel limit.\");\n  const samples = r.samples, displacements = r.displacements, weights = r.rowWeights;\n  if (!(displacements instanceof Float64Array) || displacements.length < 2 || displacements.length % 2 !== 0 ||\n      displacements.length / 2 > L.maximumTemporalSamples) {\n    throw new InvalidConfigurationError(\"Temporal exposure sum needs 1 to 256 displacement pairs.\");\n  }\n  const nodeCount = displacements.length / 2;\n  if (!(samples instanceof Float32Array || samples instanceof Float64Array) || samples.length !== width * height ||\n      !(weights instanceof Float32Array || weights instanceof Float64Array) || weights.length !== nodeCount * height ||\n      weights.length > L.maximumRowWeights) {\n    throw new InvalidConfigurationError(\"Temporal exposure sum 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    if (!(v >= 0 && v <= L.maximumSampleMagnitude)) throw new InvalidConfigurationError(\"Temporal samples must be finite, non-negative and bounded.\");\n    if (v > maximumSampleMagnitude) maximumSampleMagnitude = v;\n  }\n  let maximumWeight = 0, maximumRowWeightSum = 0;\n  const rowSums = new Float64Array(height);\n  for (let k = 0; k < nodeCount; k++) {\n    for (let y = 0; y < height; y++) {\n      const w = weights[k * height + y]!;\n      if (!(w >= 0 && w <= L.maximumWeight)) throw new InvalidConfigurationError(\"Temporal row weights must be finite, non-negative and bounded.\");\n      if (w > maximumWeight) maximumWeight = w;\n      rowSums[y]! += w;\n    }\n  }\n  for (const s of rowSums) if (s > maximumRowWeightSum) maximumRowWeightSum = s;\n  let integerDisplacements = true;\n  const nodes: TemporalExposureSumNode[] = [];\n  for (let k = 0; k < nodeCount; k++) {\n    const dx = displacements[2 * k]!, dy = displacements[2 * k + 1]!;\n    if (!(Math.abs(dx) <= L.maximumDisplacementSites && Math.abs(dy) <= L.maximumDisplacementSites)) {\n      throw new InvalidConfigurationError(\"Temporal displacements must be finite and within 4096 sites.\");\n    }\n    // Source position x − dx = x + offsetX + ax with ax in [0, 1).\n    const offsetX = Math.floor(-dx), offsetY = Math.floor(-dy), ax = -dx - offsetX, ay = -dy - offsetY;\n    if (ax !== 0 || ay !== 0) integerDisplacements = false;\n    nodes.push(Object.freeze({ offsetX, offsetY,\n      weights: Object.freeze([(1 - ax) * (1 - ay), ax * (1 - ay), (1 - ax) * ay, ax * ay] as const) }));\n  }\n  return Object.freeze({ width, height, nodeCount, nodes: Object.freeze(nodes), maximumSampleMagnitude, maximumRowWeightSum, maximumWeight,\n    integerDisplacements });\n}\n\n/**\n * Reference rows `[y0, y1)` into `output` at `(y − y0)·width + x`. The order (node ascending; taps 00,\n * 10, 01, 11 summed left to right; then times the row weight) is part of the contract shared with the\n * WGSL kernel.\n * @internal\n */\nexport function sumTemporalExposureRows(plan: TemporalExposureSumPlan, samples: Float32Array | Float64Array, rowWeights: Float32Array | Float64Array,\n  y0: number, y1: number, output: Float64Array): void {\n  const { width, height, nodes } = plan;\n  for (let y = y0; y < y1; y++) {\n    for (let x = 0; x < width; x++) {\n      let sum = 0;\n      for (let k = 0; k < nodes.length; k++) {\n        const node = nodes[k]!, sx = x + node.offsetX, sy = y + node.offsetY, b = node.weights;\n        const left = sx >= 0 && sx < width, right = sx + 1 >= 0 && sx + 1 < width;\n        const top = sy >= 0 && sy < height, bottom = sy + 1 >= 0 && sy + 1 < height;\n        let inner = 0;\n        if (top && left) inner += b[0] * samples[sy * width + sx]!;\n        if (top && right) inner += b[1] * samples[sy * width + sx + 1]!;\n        if (bottom && left) inner += b[2] * samples[(sy + 1) * width + sx]!;\n        if (bottom && right) inner += b[3] * samples[(sy + 1) * width + sx + 1]!;\n        sum += rowWeights[k * height + y]! * inner;\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 calculateTemporalExposureSum(input: TemporalExposureSumInput): { plan: TemporalExposureSumPlan; values: Float64Array } {\n  const plan = calculateTemporalExposureSumPlan(input);\n  const values = new Float64Array(plan.width * plan.height);\n  sumTemporalExposureRows(plan, input.samples, input.rowWeights, 0, plan.height, values);\n  return { plan, values };\n}\n"]}

package/dist/optics/diffraction-psf-profile.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Builds a `LensSampledPsfProfile` for an ideal, aberration-free, in-focus lens with a uniformly lit
+ * circular pupil: the Airy pattern of scalar Fraunhofer diffraction, one unit-sum kernel per declared
+ * wavelength on ONE shared sample grid (2.1.0).
+ *
+ * **Model.** The pupil diameter is D = f/N (entrance pupil = exit pupil, unity pupil magnification) and
+ * the pupil-to-image distance z is the thin-lens image distance for the focus (f at infinity), so the
+ * image-side (working) f-number is N_w = z/D. The incoherent optical transfer function (OTF) of a
+ * uniform circular pupil is the normalized autocorrelation of the pupil,
+ *   H(ρ) = (2/π)·(acos ρ − ρ·√(1 − ρ²)),  ρ = |f|/f_c ≤ 1,  f_c = 1/(λ·N_w),
+ * and the intensity PSF is its inverse Fourier transform (the Airy pattern, first zero at 1.21967·λ·N_w)
+ * (MIT OpenCourseWare 2.71 Optics, Spring 2009, lectures 21–22, free: the intensity PSF as the transform of
+ * the pupil autocorrelation and the circular-pupil MTF; also see: Goodman, Introduction to Fourier Optics,
+ * 4th ed., 2017, §6.3).
+ *
+ * **Cell integration (exact, no Bessel functions).** Kernel sample (i, j) is the PSF energy inside the
+ * square cell of side p centred on (i·p, j·p). The cell integral is the PSF convolved with the cell's
+ * indicator, evaluated at the cell centre, so in the frequency domain
+ *   K(i, j) = p² ∫∫ H(|f|/f_c)·sinc(p·f_x)·sinc(p·f_y)·cos(2π·p·i·f_x)·cos(2π·p·j·f_y) d²f,
+ * with sinc(x) = sin(πx)/(πx) (the sine terms vanish because H is even). It is evaluated in polar
+ * coordinates: a trapezoid rule in angle (exponentially convergent for this smooth periodic integrand) and
+ * Gauss–Legendre in t with ρ = 1 − t², which removes the (1 − ρ)^{3/2} edge behaviour of H. The node counts
+ * follow from the integrand's bandwidth with a fixed margin; the tests check convergence by doubling them and
+ * check the values against an independent real-space integration of `calculateIdealPolygonDiffractionPsf` in
+ * its many-blade (circular) limit. The sum of all cells is exactly 1 (Parseval), so the energy captured by
+ * the finite kernel is Σ K over its window and the truncated energy is 1 − Σ K.
+ *
+ * **Truncation and normalization.** The kernel is the (2R+1)² window of cells. The Airy tails fall only as
+ * r⁻³, so a finite window always misses some energy: it is reported per wavelength, and the window is then
+ * renormalized to unit sum because the sampled-profile contract requires unit-energy kernels. The missing
+ * tail energy is thereby put back inside the window (an approximation that slightly raises low-frequency
+ * contrast compared with the untruncated pattern).
+ *
+ * **Approximations (labelled):** scalar (no polarization), aberration-free, uniform pupil amplitude, exactly in
+ * focus (no defocus), thin lens with unity pupil magnification, the on-axis PSF used across the declared field
+ * (isoplanatic), PSF energy binned into the sample cells, finite window renormalized. Not a measured lens.
+ * @see docs/PSF_FOUNDATION.md, "Diffraction-limited sampled profile (2.1)".
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import type { FocusPlane } from "./focus-state.js";
+import { type LensSampledPsfProfile } from "./lens-psf-profile.js";
+export declare const DIFFRACTION_LIMITED_PSF_PROFILE_MODEL: Readonly<{
+    modelId: "photivra-diffraction-limited-circular-pupil-psf";
+    modelVersion: "1.0.0";
+}>;
+/** Input limits: at most 64 wavelengths, kernel radius 0–32 samples (the irradiance-convolution limit). */
+export declare const DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS: Readonly<{
+    maximumWavelengths: 64;
+    maximumKernelRadiusSamples: 32;
+}>;
+export interface CreateDiffractionLimitedPsfProfileInput {
+    /** Only `circular` in 2.1.0 (polygon pupils: `calculateIdealPolygonDiffractionPsf` gives point densities). */
+    aperture: "circular";
+    focalLengthMm: number;
+    apertureFNumber: number;
+    focus: FocusPlane;
+    /** Strictly increasing wavelengths, nm, in the medium of propagation (no air/vacuum conversion is applied). 1–64. */
+    wavelengthsNm: readonly number[];
+    /** Square sample pitch of every kernel, µm. */
+    samplePitchMicrometers: number;
+    /** Kernel half-width in samples; each kernel is (2R + 1)². 0–32. */
+    kernelRadiusSamples: number;
+    /** Half-extent of the image field over which the on-axis PSF is declared (profile field axes ±x, ±y), mm. */
+    fieldHalfExtentMm: {
+        x: number;
+        y: number;
+    };
+    profileId: string;
+}
+export interface DiffractionLimitedPsfWavelength {
+    wavelengthNm: number;
+    /** f_c = 1/(λ·N_w), cycles per µm. */
+    cutoffFrequencyCyclesPerMicrometer: number;
+    /** 1.21967·λ·N_w, µm. */
+    firstZeroRadiusMicrometers: number;
+    /** Σ of the cell energies inside the window before renormalization (of a total of 1). */
+    capturedEnergyFraction: number;
+    /** 1 − capturedEnergyFraction: the Airy tail energy outside the window, put back by renormalization. */
+    truncatedEnergyFraction: number;
+    /** Fraction of the renormalized kernel in the centre sample. */
+    centreSampleFraction: number;
+}
+export interface DiffractionLimitedPsfProfile {
+    profile: LensSampledPsfProfile;
+    model: typeof DIFFRACTION_LIMITED_PSF_PROFILE_MODEL;
+    pupilDiameterMm: number;
+    pupilToImageDistanceMm: number;
+    workingFNumber: number;
+    kernelRadiusSamples: number;
+    samplePitchMicrometers: number;
+    wavelengths: readonly DiffractionLimitedPsfWavelength[];
+    /** Largest truncated energy over the wavelengths. */
+    maximumTruncatedEnergyFraction: number;
+    quadrature: {
+        method: "polar-frequency-domain-trapezoid-gauss-legendre";
+        maximumRadialNodes: number;
+        maximumAngularNodes: number;
+    };
+}
+/**
+ * Cell energies K(i, j), 0 ≤ i, j ≤ R, of the Airy pattern for β = p·f_c (cell side in units of the cut-off
+ * period). `scale` multiplies the node counts (1 in production; the tests use 2 to check convergence).
+ */
+export declare function calculateAiryCellEnergies(beta: number, radius: number, scale?: number): {
+    cells: Float64Array;
+    radialNodes: number;
+    angularNodes: number;
+};
+/**
+ * Creates a sampled lens PSF profile for an ideal diffraction-limited lens with a circular pupil: one
+ * unit-sum Airy kernel per wavelength on one shared (2R+1)² grid, with the truncated energy reported per
+ * wavelength. The profile declares the given focal length, f-number and focus exactly, and the field axes
+ * ±`fieldHalfExtentMm` with the same kernel at every field node.
+ * @param input - See `CreateDiffractionLimitedPsfProfileInput`.
+ * @returns The profile and its diffraction record. An approximation; not a measured lens.
+ * @see docs/PSF_FOUNDATION.md, "Diffraction-limited sampled profile (2.1)".
+ */
+export declare function createDiffractionLimitedPsfProfile(input: CreateDiffractionLimitedPsfProfileInput): CalculationResult<DiffractionLimitedPsfProfile>;

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"diffraction-psf-profile.js","sourceRoot":"","sources":["../../src/optics/diffraction-psf-profile.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,mBAAmB,EAA0B,MAAM,+BAA+B,CAAC;AAC5F,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAGxE,OAAO,EAAE,8BAA8B,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAA8B,MAAM,uBAAuB,CAAC;AAE/F,MAAM,CAAC,MAAM,qCAAqC,GAAG,MAAM,CAAC,MAAM,CAAC;IACjE,OAAO,EAAE,iDAA0D,EAAE,YAAY,EAAE,OAAgB;CAAE,CAAC,CAAC;AACzG,2GAA2G;AAC3G,MAAM,CAAC,MAAM,sCAAsC,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,kBAAkB,EAAE,EAAE,EAAE,0BAA0B,EAAE,EAAE,EAAE,CAAC,CAAC;AAChI,2HAA2H;AAC3H,MAAM,4BAA4B,GAAG,kBAAkB,GAAG,IAAI,CAAC,EAAE,CAAC;AA+ClE,MAAM,QAAQ,GAAkC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,UAAmB;QAC9G,eAAe,EAAE,0CAA0C,EAAE,WAAW,EAAE,gBAAyB,EAAE,CAAC,CAAC,CAAC,CAAC;AAC3G,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC;IAChC,kJAAkJ;IAClJ,wJAAwJ;IACxJ,wHAAwH;IACxH,qJAAqJ;IACrJ,sFAAsF;CACvF,CAAC,CAAC;AAEH,SAAS,QAAQ,CAAC,KAAc,EAAE,IAAY;IAC5C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,MAAM,IAAI,yBAAyB,CAAC,IAAI,GAAG,oCAAoC,CAAC,CAAC;IACzJ,OAAO,KAAK,CAAC;AACf,CAAC;AAED,uGAAuG;AACvG,MAAM,cAAc,GAAG,IAAI,GAAG,EAA0D,CAAC;AACzF,SAAS,aAAa,CAAC,CAAS;IAC9B,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACrC,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,YAAY,CAAC,CAAC,CAAC,CAAC;IACjE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QACnD,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC;YACrD,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;gBAAC,EAAE,GAAG,EAAE,CAAC;gBAAC,EAAE,GAAG,EAAE,CAAC;YAAC,CAAC;YACxG,MAAM,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACpD,CAAC,IAAI,IAAI,CAAC;YACV,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK;gBAAE,MAAM;QACpC,CAAC;QACD,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;YAAC,EAAE,GAAG,EAAE,CAAC;YAAC,EAAE,GAAG,EAAE,CAAC;QAAC,CAAC;QACxG,MAAM,UAAU,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACnD,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,GAAG,UAAU,CAAC,CAAC;QACtD,uEAAuE;QACvE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACvC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QAAC,OAAO,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACzD,CAAC;IACD,MAAM,MAAM,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAClC,IAAI,cAAc,CAAC,IAAI,GAAG,EAAE;QAAE,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC;AAChB,CAAC;AACD,SAAS,IAAI,CAAC,CAAS;IACrB,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtB,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY,EAAE,MAAc,EAAE,KAAK,GAAG,CAAC;IAC/E,iHAAiH;IACjH,MAAM,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;IAC1F,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IACnG,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC,WAAW,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,YAAY,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChH,MAAM,EAAE,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC;IACtG,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrC,4FAA4F;QAC5F,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC7F,qGAAqG;QACrG,MAAM,YAAY,GAAG,OAAO,CAAC,CAAC,CAAE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG,WAAW,CAAC;QACvE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,CAAC,GAAG,WAAW,EAAE,CAAC,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAClG,MAAM,CAAC,GAAG,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YAClF,2DAA2D;YAC3D,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YACrE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACrB,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;gBAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;gBAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;YAAC,CAAC;YACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;gBAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;YAAC,CAAC;YACtH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC9B,MAAM,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC;gBACtB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;oBAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;oBAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAE,CAAC;gBAAC,CAAC;YAChG,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC;IACnE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC,GAAG,OAAO,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kCAAkC,CAAC,KAA8C;IAC/F,MAAM,CAAC,GAAG,wBAAwB,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,eAAe,EAAE,iBAAiB,EAAE,OAAO,EAAE,eAAe,EAAE,wBAAwB;QAC3I,qBAAqB,EAAE,mBAAmB,EAAE,WAAW,CAAC,EAAE,gDAAgD,CAAC,CAAC;IAC9G,IAAI,CAAC,CAAC,QAAQ,KAAK,UAAU;QAAE,MAAM,IAAI,yBAAyB,CAAC,gCAAgC,CAAC,CAAC;IACrG,MAAM,aAAa,GAAG,QAAQ,CAAC,CAAC,CAAC,aAAa,EAAE,eAAe,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAC;IAC3H,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,sBAAsB,EAAE,wBAAwB,CAAC,CAAC;IAC3E,MAAM,CAAC,GAAG,sCAAsC,CAAC;IACjD,MAAM,MAAM,GAAG,CAAC,CAAC,mBAAmB,CAAC;IACrC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,0BAA0B,EAAE,CAAC;QACvH,MAAM,IAAI,yBAAyB,CAAC,mDAAmD,GAAG,CAAC,CAAC,0BAA0B,GAAG,GAAG,CAAC,CAAC;IAChI,CAAC;IACD,MAAM,KAAK,GAAG,wBAAwB,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,gBAAgB,CAAC,CAAC;IACzF,IAAI,aAAqB,EAAE,UAAkB,CAAC;IAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC9B,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;YAAE,MAAM,IAAI,yBAAyB,CAAC,qCAAqC,CAAC,CAAC;QAC9G,aAAa,GAAG,CAAC,CAAC;QAAC,UAAU,GAAG,aAAa,CAAC;IAChD,CAAC;SAAM,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACnC,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;QAC/D,aAAa,GAAG,CAAC,GAAG,SAAS,CAAC;QAC9B,UAAU,GAAG,8BAA8B,CAAC,EAAE,aAAa,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;IACnH,CAAC;;QAAM,MAAM,IAAI,yBAAyB,CAAC,wCAAwC,CAAC,CAAC;IACrF,MAAM,KAAK,GAAG,wBAAwB,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,4BAA4B,CAAC,CAAC;IACtG,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;IAC3G,MAAM,IAAI,GAAG,CAAC,CAAC,aAAa,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,kBAAkB;QAAE,MAAM,IAAI,yBAAyB,CAAC,8CAA8C,CAAC,CAAC;IACvK,MAAM,WAAW,GAAI,IAAkB,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC;IAC/G,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,GAAG,WAAW,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC;YAAE,MAAM,IAAI,yBAAyB,CAAC,4CAA4C,CAAC,CAAC;IAC7K,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,qCAAqC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;QAAE,MAAM,IAAI,yBAAyB,CAAC,uCAAuC,CAAC,CAAC;IAE9K,MAAM,eAAe,GAAG,aAAa,GAAG,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,eAAe,EAAE,IAAI,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC;IACtH,IAAI,kBAAkB,GAAG,CAAC,EAAE,mBAAmB,GAAG,CAAC,EAAE,gBAAgB,GAAG,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAsC,EAAE,EAAE,OAAO,GAAe,EAAE,CAAC;IAChF,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,EAAE,GAAG,IAAI,GAAG,cAAc,EAAE,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC;QACjE,MAAM,IAAI,GAAG,yBAAyB,CAAC,KAAK,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/D,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAAC,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QAC5I,MAAM,MAAM,GAAa,IAAI,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;QAChD,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE;YAAE,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC;gBACnE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,MAAM,CAAC,CAAE,CAAC;gBACxF,uGAAuG;gBACvG,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC;oBAAE,MAAM,IAAI,yBAAyB,CAAC,kDAAkD,CAAC,CAAC;gBAC/G,MAAM,CAAC,EAAE,GAAG,IAAI,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;gBAC5C,QAAQ,IAAI,MAAM,CAAC,EAAE,GAAG,IAAI,GAAG,EAAE,CAAE,CAAC;YACtC,CAAC;QACD,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,IAAI,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC;YAAE,MAAM,IAAI,yBAAyB,CAAC,kDAAkD,CAAC,CAAC;QACrI,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC;QAC5C,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC;QAC/C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,OAAO,CAAC,IAAI,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,kCAAkC,EAAE,MAAM,EAAE,0BAA0B,EAAE,4BAA4B,GAAG,OAAO;YAC7I,sBAAsB,EAAE,QAAQ,EAAE,uBAAuB,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,CAAC,MAAM,GAAG,IAAI,GAAG,MAAM,CAAE,EAAE,CAAC,CAAC;IACnI,CAAC;IACD,MAAM,WAAW,GAAG,EAAE,IAAI,EAAE,gBAAyB,EAAE,UAAU,EAAE,8EAA8E,EAAE,CAAC;IACpJ,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAChH,MAAM,EAAE,OAAO,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,KAAK;QACrF,UAAU,EAAE,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,kCAAkC,EAAE,CAAC,EAAE;QAC3J,MAAM,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,uBAAuB,EAAE,KAAK,EAAE,uBAAuB,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM;YAC7J,mBAAmB,EAAE,OAAO,CAAC,KAAK,CAAE,EAAE;QACxC,oCAAoC,EAAE,CAAC,EAAE,6BAA6B,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW;KAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACnH,MAAM,OAAO,GAAG,0BAA0B,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,cAAc,EAAE,qCAAqC,CAAC,YAAY;QAC7J,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,gCAAgC,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,SAAS,EAAE,iBAAiB;QACxJ,yBAAyB,EAAE,mBAAmB,EAAE,aAAa,EAAE,kCAAkC,EAAE,mBAAmB,EAAE,2CAA2C;QACnK,gBAAgB,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,EAAE;QACrG,0BAA0B,EAAE,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,sBAAsB,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK;QAC1H,IAAI,EAAE,EAAE,aAAa,EAAE,CAAC,aAAa,CAAC,EAAE,aAAa,EAAE,CAAC,aAAa,CAAC,EAAE,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC;YAC1J,YAAY,EAAE,WAAW,EAAE,kCAAkC,EAAE,CAAC,CAAC,CAAC,EAAE;QACtE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;IAC9D,OAAO,mBAAmB,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,qCAAqC,EAAE,eAAe,EAAE,sBAAsB,EAAE,UAAU,EAAE,cAAc;QACrJ,mBAAmB,EAAE,MAAM,EAAE,sBAAsB,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,8BAA8B,EAAE,gBAAgB;QAClI,UAAU,EAAE,EAAE,MAAM,EAAE,iDAA0D,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,EAAE,EAC/H,qCAAqC,CAAC,OAAO,EAAE,qCAAqC,CAAC,YAAY,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;AACvH,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Builds a `LensSampledPsfProfile` for an ideal, aberration-free, in-focus lens with a uniformly lit\n * circular pupil: the Airy pattern of scalar Fraunhofer diffraction, one unit-sum kernel per declared\n * wavelength on ONE shared sample grid (2.1.0).\n *\n * **Model.** The pupil diameter is D = f/N (entrance pupil = exit pupil, unity pupil magnification) and\n * the pupil-to-image distance z is the thin-lens image distance for the focus (f at infinity), so the\n * image-side (working) f-number is N_w = z/D. The incoherent optical transfer function (OTF) of a\n * uniform circular pupil is the normalized autocorrelation of the pupil,\n *   H(ρ) = (2/π)·(acos ρ − ρ·√(1 − ρ²)),  ρ = |f|/f_c ≤ 1,  f_c = 1/(λ·N_w),\n * and the intensity PSF is its inverse Fourier transform (the Airy pattern, first zero at 1.21967·λ·N_w)\n * (MIT OpenCourseWare 2.71 Optics, Spring 2009, lectures 21–22, free: the intensity PSF as the transform of\n * the pupil autocorrelation and the circular-pupil MTF; also see: Goodman, Introduction to Fourier Optics,\n * 4th ed., 2017, §6.3).\n *\n * **Cell integration (exact, no Bessel functions).** Kernel sample (i, j) is the PSF energy inside the\n * square cell of side p centred on (i·p, j·p). The cell integral is the PSF convolved with the cell's\n * indicator, evaluated at the cell centre, so in the frequency domain\n *   K(i, j) = p² ∫∫ H(|f|/f_c)·sinc(p·f_x)·sinc(p·f_y)·cos(2π·p·i·f_x)·cos(2π·p·j·f_y) d²f,\n * with sinc(x) = sin(πx)/(πx) (the sine terms vanish because H is even). It is evaluated in polar\n * coordinates: a trapezoid rule in angle (exponentially convergent for this smooth periodic integrand) and\n * Gauss–Legendre in t with ρ = 1 − t², which removes the (1 − ρ)^{3/2} edge behaviour of H. The node counts\n * follow from the integrand's bandwidth with a fixed margin; the tests check convergence by doubling them and\n * check the values against an independent real-space integration of `calculateIdealPolygonDiffractionPsf` in\n * its many-blade (circular) limit. The sum of all cells is exactly 1 (Parseval), so the energy captured by\n * the finite kernel is Σ K over its window and the truncated energy is 1 − Σ K.\n *\n * **Truncation and normalization.** The kernel is the (2R+1)² window of cells. The Airy tails fall only as\n * r⁻³, so a finite window always misses some energy: it is reported per wavelength, and the window is then\n * renormalized to unit sum because the sampled-profile contract requires unit-energy kernels. The missing\n * tail energy is thereby put back inside the window (an approximation that slightly raises low-frequency\n * contrast compared with the untruncated pattern).\n *\n * **Approximations (labelled):** scalar (no polarization), aberration-free, uniform pupil amplitude, exactly in\n * focus (no defocus), thin lens with unity pupil magnification, the on-axis PSF used across the declared field\n * (isoplanatic), PSF energy binned into the sample cells, finite window renormalized. Not a measured lens.\n * @see docs/PSF_FOUNDATION.md, \"Diffraction-limited sampled profile (2.1)\".\n */\n\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { requireAllowlistedRecord } from \"../core/record-validation.js\";\nimport type { EvidenceProvenance } from \"../core/evidence-provenance.js\";\nimport type { FocusPlane } from \"./focus-state.js\";\nimport { calculateThinLensImageDistance } from \"./thin-lens.js\";\nimport { parseLensSampledPsfProfile, type LensSampledPsfProfile } from \"./lens-psf-profile.js\";\n\nexport const DIFFRACTION_LIMITED_PSF_PROFILE_MODEL = Object.freeze({\n  modelId: \"photivra-diffraction-limited-circular-pupil-psf\" as const, modelVersion: \"1.0.0\" as const });\n/** Input limits: at most 64 wavelengths, kernel radius 0–32 samples (the irradiance-convolution limit). */\nexport const DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS = Object.freeze({ maximumWavelengths: 64, maximumKernelRadiusSamples: 32 });\n/** Radius of the first dark ring of the Airy pattern in units of λ·N_w: j₁,₁/π, j₁,₁ = 3.8317059702 (first zero of J₁). */\nconst AIRY_FIRST_ZERO_PER_LAMBDA_N = 3.8317059702075125 / Math.PI;\n\nexport interface CreateDiffractionLimitedPsfProfileInput {\n  /** Only `circular` in 2.1.0 (polygon pupils: `calculateIdealPolygonDiffractionPsf` gives point densities). */\n  aperture: \"circular\";\n  focalLengthMm: number;\n  apertureFNumber: number;\n  focus: FocusPlane;\n  /** Strictly increasing wavelengths, nm, in the medium of propagation (no air/vacuum conversion is applied). 1–64. */\n  wavelengthsNm: readonly number[];\n  /** Square sample pitch of every kernel, µm. */\n  samplePitchMicrometers: number;\n  /** Kernel half-width in samples; each kernel is (2R + 1)². 0–32. */\n  kernelRadiusSamples: number;\n  /** Half-extent of the image field over which the on-axis PSF is declared (profile field axes ±x, ±y), mm. */\n  fieldHalfExtentMm: { x: number; y: number };\n  profileId: string;\n}\n\nexport interface DiffractionLimitedPsfWavelength {\n  wavelengthNm: number;\n  /** f_c = 1/(λ·N_w), cycles per µm. */\n  cutoffFrequencyCyclesPerMicrometer: number;\n  /** 1.21967·λ·N_w, µm. */\n  firstZeroRadiusMicrometers: number;\n  /** Σ of the cell energies inside the window before renormalization (of a total of 1). */\n  capturedEnergyFraction: number;\n  /** 1 − capturedEnergyFraction: the Airy tail energy outside the window, put back by renormalization. */\n  truncatedEnergyFraction: number;\n  /** Fraction of the renormalized kernel in the centre sample. */\n  centreSampleFraction: number;\n}\n\nexport interface DiffractionLimitedPsfProfile {\n  profile: LensSampledPsfProfile;\n  model: typeof DIFFRACTION_LIMITED_PSF_PROFILE_MODEL;\n  pupilDiameterMm: number;\n  pupilToImageDistanceMm: number;\n  workingFNumber: number;\n  kernelRadiusSamples: number;\n  samplePitchMicrometers: number;\n  wavelengths: readonly DiffractionLimitedPsfWavelength[];\n  /** Largest truncated energy over the wavelengths. */\n  maximumTruncatedEnergyFraction: number;\n  quadrature: { method: \"polar-frequency-domain-trapezoid-gauss-legendre\"; maximumRadialNodes: number; maximumAngularNodes: number };\n}\n\nconst EVIDENCE: readonly EvidenceProvenance[] = Object.freeze([Object.freeze({ sourceOrigin: \"photivra\" as const,\n  sourceReference: \"photivra:diffraction-limited-psf-profile\", reuseStatus: \"photivra-owned\" as const })]);\nconst LIMITATIONS = Object.freeze([\n  \"Scalar Fraunhofer diffraction of an ideal, uniformly lit circular pupil (Airy pattern); no aberration, apodization, polarization or stray light.\",\n  \"Exactly in focus: no defocus or depth of field. Thin lens with unity pupil magnification; the pupil-to-image distance is the thin-lens image distance.\",\n  \"The on-axis PSF is declared unchanged across the field (isoplanatic); no field-dependent aberration or pupil clipping.\",\n  \"PSF energy is binned into square sample cells; the finite window misses the Airy tail energy listed per wavelength and is renormalized to unit sum.\",\n  \"Wavelengths are used as given, in the declared basis, without air/vacuum conversion.\"\n]);\n\nfunction positive(value: unknown, name: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) throw new InvalidConfigurationError(name + \" must be a positive finite number.\");\n  return value;\n}\n\n/** Gauss–Legendre nodes and weights on [0, 1] (Newton iteration on Pₙ; DLMF §3.5(v)). Cached per n. */\nconst GAUSS_LEGENDRE = new Map<number, { nodes: Float64Array; weights: Float64Array }>();\nfunction gaussLegendre(n: number): { nodes: Float64Array; weights: Float64Array } {\n  const cached = GAUSS_LEGENDRE.get(n);\n  if (cached) return cached;\n  const nodes = new Float64Array(n), weights = new Float64Array(n);\n  for (let k = 0; k < Math.ceil(n / 2); k++) {\n    let x = Math.cos(Math.PI * (k + 0.75) / (n + 0.5));\n    for (let iteration = 0; iteration < 100; iteration++) {\n      let p0 = 1, p1 = x;\n      for (let m = 2; m <= n; m++) { const p2 = ((2 * m - 1) * x * p1 - (m - 1) * p0) / m; p0 = p1; p1 = p2; }\n      const step = p1 / (n * (x * p1 - p0) / (x * x - 1));\n      x -= step;\n      if (Math.abs(step) < 1e-16) break;\n    }\n    let p0 = 1, p1 = x;\n    for (let m = 2; m <= n; m++) { const p2 = ((2 * m - 1) * x * p1 - (m - 1) * p0) / m; p0 = p1; p1 = p2; }\n    const derivative = n * (x * p1 - p0) / (x * x - 1);\n    const w = 1 / ((1 - x * x) * derivative * derivative);\n    // Map [-1, 1] to [0, 1]: t = (1 ± x)/2, weight w (2/(1-x²)P'² halved).\n    nodes[k] = (1 - x) / 2; weights[k] = w;\n    nodes[n - 1 - k] = (1 + x) / 2; weights[n - 1 - k] = w;\n  }\n  const result = { nodes, weights };\n  if (GAUSS_LEGENDRE.size < 64) GAUSS_LEGENDRE.set(n, result);\n  return result;\n}\nfunction sinc(x: number): number {\n  if (x === 0) return 1;\n  const a = Math.PI * x;\n  return Math.sin(a) / a;\n}\n\n/**\n * Cell energies K(i, j), 0 ≤ i, j ≤ R, of the Airy pattern for β = p·f_c (cell side in units of the cut-off\n * period). `scale` multiplies the node counts (1 in production; the tests use 2 to check convergence).\n */\nexport function calculateAiryCellEnergies(beta: number, radius: number, scale = 1): { cells: Float64Array; radialNodes: number; angularNodes: number } {\n  // Bandwidth of the angular and radial integrands: c = π·β·(2R + 1)·√2 (the sinc factors and the highest cosine).\n  const c = Math.PI * beta * (2 * radius + 1) * Math.SQRT2, margin = 10 * Math.cbrt(c) + 24;\n  const quarter = Math.ceil(scale * (c + margin) / 4), radialNodes = Math.ceil(scale * (c + margin));\n  const { nodes, weights } = gaussLegendre(radialNodes), size = radius + 1, cells = new Float64Array(size * size);\n  const ca = new Float64Array(size), cb = new Float64Array(size), angularStep = (Math.PI / 2) / quarter;\n  for (let r = 0; r < radialNodes; r++) {\n    const t = nodes[r]!, rho = 1 - t * t;\n    // H(1 − t²) without cancellation: acos(1 − t²) = 2·asin(t/√2), ρ·√(1 − ρ²) = ρ·t·√(2 − t²).\n    const otf = (2 / Math.PI) * (2 * Math.asin(t / Math.SQRT2) - rho * t * Math.sqrt(2 - t * t));\n    // ∫₀¹ g(ρ) dρ = ∫₀¹ g(1 − t²)·2t dt; the 4 is the four symmetric quadrants of the angular trapezoid.\n    const radialWeight = weights[r]! * 2 * t * rho * otf * 4 * angularStep;\n    for (let k = 0; k <= quarter; k++) {\n      const theta = k * angularStep, x = beta * rho * Math.cos(theta), y = beta * rho * Math.sin(theta);\n      const w = radialWeight * (k === 0 || k === quarter ? 0.5 : 1) * sinc(x) * sinc(y);\n      // cos(2π·i·x) and cos(2π·j·y) by the Chebyshev recurrence.\n      const cx = Math.cos(2 * Math.PI * x), cy = Math.cos(2 * Math.PI * y);\n      ca[0] = 1; cb[0] = 1;\n      if (size > 1) { ca[1] = cx; cb[1] = cy; }\n      for (let i = 2; i < size; i++) { ca[i] = 2 * cx * ca[i - 1]! - ca[i - 2]!; cb[i] = 2 * cy * cb[i - 1]! - cb[i - 2]!; }\n      for (let j = 0; j < size; j++) {\n        const wj = w * cb[j]!;\n        for (let i = 0; i < size; i++) { const o = j * size + i; cells[o] = cells[o]! + wj * ca[i]!; }\n      }\n    }\n  }\n  const area = beta * beta;\n  for (let i = 0; i < cells.length; i++) cells[i] = cells[i]! * area;\n  return { cells, radialNodes, angularNodes: 4 * quarter };\n}\n\n/**\n * Creates a sampled lens PSF profile for an ideal diffraction-limited lens with a circular pupil: one\n * unit-sum Airy kernel per wavelength on one shared (2R+1)² grid, with the truncated energy reported per\n * wavelength. The profile declares the given focal length, f-number and focus exactly, and the field axes\n * ±`fieldHalfExtentMm` with the same kernel at every field node.\n * @param input - See `CreateDiffractionLimitedPsfProfileInput`.\n * @returns The profile and its diffraction record. An approximation; not a measured lens.\n * @see docs/PSF_FOUNDATION.md, \"Diffraction-limited sampled profile (2.1)\".\n */\nexport function createDiffractionLimitedPsfProfile(input: CreateDiffractionLimitedPsfProfileInput): CalculationResult<DiffractionLimitedPsfProfile> {\n  const r = requireAllowlistedRecord(input, [\"aperture\", \"focalLengthMm\", \"apertureFNumber\", \"focus\", \"wavelengthsNm\", \"samplePitchMicrometers\",\n    \"kernelRadiusSamples\", \"fieldHalfExtentMm\", \"profileId\"], \"Invalid diffraction-limited PSF profile input.\");\n  if (r.aperture !== \"circular\") throw new InvalidConfigurationError(\"aperture must be \\\"circular\\\".\");\n  const focalLengthMm = positive(r.focalLengthMm, \"focalLengthMm\"), fNumber = positive(r.apertureFNumber, \"apertureFNumber\");\n  const pitch = positive(r.samplePitchMicrometers, \"samplePitchMicrometers\");\n  const L = DIFFRACTION_LIMITED_PSF_PROFILE_LIMITS;\n  const radius = r.kernelRadiusSamples;\n  if (typeof radius !== \"number\" || !Number.isSafeInteger(radius) || radius < 0 || radius > L.maximumKernelRadiusSamples) {\n    throw new InvalidConfigurationError(\"kernelRadiusSamples must be an integer from 0 to \" + L.maximumKernelRadiusSamples + \".\");\n  }\n  const focus = requireAllowlistedRecord(r.focus, [\"kind\", \"distanceM\"], \"Invalid focus.\");\n  let focusDiopters: number, distanceMm: number;\n  if (focus.kind === \"infinity\") {\n    if (focus.distanceM !== undefined) throw new InvalidConfigurationError(\"An infinity focus has no distanceM.\");\n    focusDiopters = 0; distanceMm = focalLengthMm;\n  } else if (focus.kind === \"finite\") {\n    const distanceM = positive(focus.distanceM, \"focus.distanceM\");\n    focusDiopters = 1 / distanceM;\n    distanceMm = calculateThinLensImageDistance({ focalLengthMm, objectDistanceM: distanceM }).value.imageDistanceMm;\n  } else throw new InvalidConfigurationError(\"focus.kind must be finite or infinity.\");\n  const field = requireAllowlistedRecord(r.fieldHalfExtentMm, [\"x\", \"y\"], \"Invalid fieldHalfExtentMm.\");\n  const fieldX = positive(field.x, \"fieldHalfExtentMm.x\"), fieldY = positive(field.y, \"fieldHalfExtentMm.y\");\n  const list = r.wavelengthsNm;\n  if (!Array.isArray(list) || list.length < 1 || list.length > L.maximumWavelengths) throw new InvalidConfigurationError(\"wavelengthsNm must list 1 to 64 wavelengths.\");\n  const wavelengths = (list as unknown[]).map((value, index) => positive(value, \"wavelengthsNm[\" + index + \"]\"));\n  for (let i = 1; i < wavelengths.length; i++) if (!(wavelengths[i]! > wavelengths[i - 1]!)) throw new InvalidConfigurationError(\"wavelengthsNm must be strictly increasing.\");\n  if (typeof r.profileId !== \"string\" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(r.profileId)) throw new InvalidConfigurationError(\"profileId must be a public opaque ID.\");\n\n  const pupilDiameterMm = focalLengthMm / fNumber, workingFNumber = distanceMm / pupilDiameterMm, size = 2 * radius + 1;\n  let maximumRadialNodes = 0, maximumAngularNodes = 0, maximumTruncated = 0;\n  const records: DiffractionLimitedPsfWavelength[] = [], kernels: number[][] = [];\n  for (const nm of wavelengths) {\n    const lambdaN = nm / 1000 * workingFNumber, cutoff = 1 / lambdaN;\n    const airy = calculateAiryCellEnergies(pitch * cutoff, radius);\n    maximumRadialNodes = Math.max(maximumRadialNodes, airy.radialNodes); maximumAngularNodes = Math.max(maximumAngularNodes, airy.angularNodes);\n    const values: number[] = new Array(size * size);\n    let captured = 0;\n    for (let ky = 0; ky < size; ky++) for (let kx = 0; kx < size; kx++) {\n      const value = airy.cells[Math.abs(ky - radius) * (radius + 1) + Math.abs(kx - radius)]!;\n      // Every cell energy of a non-negative PSF is positive; a negative value would be a quadrature failure.\n      if (!(value > -1e-13)) throw new InvalidConfigurationError(\"Diffraction cell integration failed to converge.\");\n      values[ky * size + kx] = Math.max(0, value);\n      captured += values[ky * size + kx]!;\n    }\n    if (!(captured > 0 && captured <= 1 + 1e-9)) throw new InvalidConfigurationError(\"Diffraction cell integration failed to converge.\");\n    const truncated = Math.max(0, 1 - captured);\n    maximumTruncated = Math.max(maximumTruncated, truncated);\n    const kernel = values.map((v) => v / captured);\n    kernels.push(kernel);\n    records.push({ wavelengthNm: nm, cutoffFrequencyCyclesPerMicrometer: cutoff, firstZeroRadiusMicrometers: AIRY_FIRST_ZERO_PER_LAMBDA_N * lambdaN,\n      capturedEnergyFraction: captured, truncatedEnergyFraction: truncated, centreSampleFraction: kernel[radius * size + radius]! });\n  }\n  const uncertainty = { kind: \"not-quantified\" as const, limitation: \"Ideal diffraction-limited model; no measured lens or quadrature error bound.\" };\n  const nodes = [-fieldX, fieldX].flatMap((fx) => [-fieldY, fieldY].flatMap((fy) => wavelengths.map((nm, index) => ({\n    nodeId: \"airy-\" + (fx < 0 ? \"xm\" : \"xp\") + \"-\" + (fy < 0 ? \"ym\" : \"yp\") + \"-\" + index,\n    coordinate: { focalLengthMm, focusDiopters, apertureFNumber: fNumber, fieldXmm: fx, fieldYmm: fy, wavelengthNm: nm, signedDefocusImagePlaneMicrometers: 0 },\n    kernel: { widthSamples: size, heightSamples: size, samplePitchMicrometersX: pitch, samplePitchMicrometersY: pitch, centerSampleX: radius, centerSampleY: radius,\n      normalizedIntensity: kernels[index]! },\n    bestFocusImagePlaneOffsetMicrometers: 0, relativePupilThroughputFactor: 1, evidence: EVIDENCE, uncertainty }))));\n  const profile = parseLensSampledPsfProfile({ schemaVersion: \"0.1.0\", profileId: r.profileId, profileVersion: DIFFRACTION_LIMITED_PSF_PROFILE_MODEL.modelVersion,\n    scientificStatus: \"approximation\", opticalDomain: \"lens-primary-optical-path-only\", coordinateSystem: \"image-plane-metric\", fieldAxes: \"+X right, +Y up\",\n    kernelEnergyNormalization: \"unit-energy-shape\", interpolation: \"bounded-regular-grid-multilinear\", throughputOwnership: \"separate-relative-pupil-throughput-factor\",\n    responseIncludes: { diffraction: true, aberration: false, defocus: false, pupilClippingShape: false },\n    sensorOpticalStackIncluded: false, sensorSamplingIncluded: false, reconstructionIncluded: false, strayLightIncluded: false,\n    axes: { focalLengthMm: [focalLengthMm], focusDiopters: [focusDiopters], apertureFNumber: [fNumber], fieldXmm: [-fieldX, fieldX], fieldYmm: [-fieldY, fieldY],\n      wavelengthNm: wavelengths, signedDefocusImagePlaneMicrometers: [0] },\n    nodes, evidence: EVIDENCE, limitations: [...LIMITATIONS] });\n  return approximationResult({ profile, model: DIFFRACTION_LIMITED_PSF_PROFILE_MODEL, pupilDiameterMm, pupilToImageDistanceMm: distanceMm, workingFNumber,\n    kernelRadiusSamples: radius, samplePitchMicrometers: pitch, wavelengths: records, maximumTruncatedEnergyFraction: maximumTruncated,\n    quadrature: { method: \"polar-frequency-domain-trapezoid-gauss-legendre\" as const, maximumRadialNodes, maximumAngularNodes } },\n  DIFFRACTION_LIMITED_PSF_PROFILE_MODEL.modelId, DIFFRACTION_LIMITED_PSF_PROFILE_MODEL.modelVersion, [...LIMITATIONS]);\n}\n"]}

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

@@ -1,6 +1,8 @@
 export declare const IRRADIANCE_CONVOLUTION_SCHEMA_VERSION: "0.1.0";
+/** `maximumPixels` is the default grid limit; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`. */
 export declare const IRRADIANCE_CONVOLUTION_LIMITS: Readonly<{
     maximumPixels: 24000000;
+    ceilingPixels: 134217728;
     maximumDimension: 16384;
     maximumKernelRadius: 32;
     maximumPatchCount: 4096;
@@ -27,6 +29,11 @@ export interface IrradianceConvolutionInput {
      */
     kernels: Float32Array | Float64Array;
     boundary: "zero-outside-grid";
+    /**
+     * Optional opt-in grid limit for large images: an integer from 1 to `IRRADIANCE_CONVOLUTION_LIMITS.ceilingPixels`.
+     * Default `IRRADIANCE_CONVOLUTION_LIMITS.maximumPixels` (24 000 000). It does not change the result.
+     */
+    maximumPixels?: number;
 }
 /** Validated, immutable geometry of a convolution request. Sample arrays are borrowed, not copied. */
 export interface IrradianceConvolutionPlan {

package/dist/optics/irradiance-convolution.js

@@ -28,9 +28,12 @@
  */
 import { InvalidConfigurationError } from "../core/configuration-error.js";
 import { requireAllowlistedRecord } from "../core/record-validation.js";
+import { FULL_RESOLUTION_CEILING_PIXELS, resolveRaisedLimit } from "../core/pixel-limits.js";
 export const IRRADIANCE_CONVOLUTION_SCHEMA_VERSION = "0.1.0";
+/** `maximumPixels` is the default grid limit; a request may raise it with its own `maximumPixels`, up to `ceilingPixels`. */
 export const IRRADIANCE_CONVOLUTION_LIMITS = Object.freeze({
     maximumPixels: 24_000_000,
+    ceilingPixels: FULL_RESOLUTION_CEILING_PIXELS,
     maximumDimension: 16_384,
     maximumKernelRadius: 32,
     maximumPatchCount: 4_096,
@@ -49,13 +52,14 @@ function positiveInteger(value, maximum) {
 /** 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",
-        "patchHeight", "kernels", "boundary"], "Invalid irradiance convolution input.");
+        "patchHeight", "kernels", "boundary", "maximumPixels"], "Invalid irradiance convolution input.");
     const L = IRRADIANCE_CONVOLUTION_LIMITS;
     if (r.schemaVersion !== IRRADIANCE_CONVOLUTION_SCHEMA_VERSION || r.boundary !== "zero-outside-grid") {
         throw new InvalidConfigurationError("Unsupported irradiance convolution schema or boundary.");
     }
     const width = positiveInteger(r.width, L.maximumDimension), height = positiveInteger(r.height, L.maximumDimension);
-    if (width * height > L.maximumPixels)
+    const maximumPixels = resolveRaisedLimit(r.maximumPixels, L.maximumPixels, L.ceilingPixels, "Irradiance convolution maximumPixels must be an integer from 1 to " + L.ceilingPixels + ".");
+    if (width * height > maximumPixels)
         throw new InvalidConfigurationError("Irradiance convolution grid exceeds the pixel limit.");
     const radius = r.kernelRadius;
     if (typeof radius !== "number" || !Number.isSafeInteger(radius) || radius < 0 || radius > L.maximumKernelRadius) {