@photivra/engine 1.5.0 → 2.1.0

package/dist/optics/lateral-chromatic-aberration.d.ts

@@ -1,13 +1,16 @@
 /**
- * Module boundary and integration notes.
- * Calculates generic lateral chromatic-aberration field separation by mapping one ideal image-plane
- * point through a shared green-reference base distortion and red/blue radial coefficient offsets. This
- * is channel-dependent field mapping, not a blur kernel.
- * Inverse-maps one distorted output destination independently for the representative red/green/blue
- * channels. Renderers can use the returned per-channel ideal source coordinates for inverse sampling
- * without inventing chromatic-aberration equations.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Generic lateral chromatic aberration (CA): red, green and blue land at slightly different image
+ * positions.
+ *
+ * The forward mapping sends one ideal image-plane point through a base distortion shared by all
+ * channels (green is the reference), plus extra radial coefficients for red and blue. It moves each
+ * channel; it is not a blur kernel.
+ *
+ * The inverse mapping takes one distorted output point and finds the ideal source point separately
+ * for red, green and blue. Renderers can sample those per-channel source points directly, without
+ * writing their own CA equations.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type LensFieldPointMm, type RadialDistortionCoefficients } from "./radial-distortion.js";
@@ -20,8 +23,8 @@ export interface LateralChromaticAberrationProfile {
     /**
      * Green-reference base geometric distortion.
      *
-     * This common mapping is included in every channel. Red/blue CA terms are
-     * added to this base, so callers should not apply a second distortion pass.
+     * Every channel includes this shared mapping. The red and blue CA terms are
+     * added on top of it, so do not apply a second distortion pass.
      */
     baseDistortionCoefficients: RadialDistortionCoefficients;
     /** Additional red-channel radial coefficients relative to green. */
@@ -36,17 +39,17 @@ export interface CalculateLateralChromaticAberrationMappingInput {
 }
 export interface CalculateInverseLateralChromaticAberrationMappingInput {
     /**
-     * Distorted output image-plane destination. Each output channel is inverse-
-     * mapped independently to its ideal source coordinate.
+     * Distorted output image-plane point. Each channel is inverse-mapped on its
+     * own to its ideal source point.
      */
     distortedImagePointMm: LensFieldPointMm;
     profile: LateralChromaticAberrationProfile;
 }
 export interface CalculateInverseLateralChromaticAberrationMappingsInput {
     /**
-     * Distorted output image-plane destinations. Each destination is inverse-
-     * mapped independently for red, green, and blue after one profile-resolution
-     * step for the batch.
+     * Distorted output image-plane points. The profile is resolved once for the
+     * batch. Then each point is inverse-mapped separately for red, green and
+     * blue.
      */
     distortedImagePointsMm: readonly LensFieldPointMm[];
     profile: LateralChromaticAberrationProfile;
@@ -101,28 +104,28 @@ export interface InverseLateralChromaticAberrationMappings {
     pointCount: number;
 }
 /**
- * Calculates generic lateral chromatic-aberration field separation by mapping
- * one ideal image-plane point through a shared green-reference base distortion
- * and red/blue radial coefficient offsets.
+ * Calculates how far lateral chromatic aberration (CA) separates the colour
+ * channels at one ideal image-plane point. The point goes through a shared
+ * base distortion (green is the reference) plus extra radial coefficients for
+ * red and blue.
  *
- * This is channel-dependent field mapping, not a blur kernel.
+ * This moves each channel; it is not a blur kernel.
  */
 export declare function calculateLateralChromaticAberrationMapping(input: CalculateLateralChromaticAberrationMappingInput): CalculationResult<LateralChromaticAberrationMapping>;
 /**
- * Inverse-maps one distorted output destination independently for the
- * representative red/green/blue channels.
+ * Inverse-maps one distorted output point separately for the representative
+ * red, green and blue channels.
  *
- * Renderers can use the returned per-channel ideal source coordinates for
- * inverse sampling without inventing chromatic-aberration equations.
+ * Renderers can sample the returned per-channel ideal source points directly,
+ * without writing their own chromatic-aberration equations.
  */
 export declare function calculateInverseLateralChromaticAberrationMapping(input: CalculateInverseLateralChromaticAberrationMappingInput): CalculationResult<InverseLateralChromaticAberrationMapping>;
 /**
- * Inverse-maps multiple distorted destinations while resolving the shared CA
- * profile once and validating each combined channel profile once for the
- * complete batch.
+ * Inverse-maps many distorted points at once. The shared CA profile is
+ * resolved once, and each combined channel profile is validated once, for
+ * the whole batch.
  *
- * Per-point values match calculateInverseLateralChromaticAberrationMapping();
- * provenance is shared once at the batch boundary.
+ * Each point's values match calculateInverseLateralChromaticAberrationMapping().
+ * Provenance is reported once for the batch.
  */
 export declare function calculateInverseLateralChromaticAberrationMappings(input: CalculateInverseLateralChromaticAberrationMappingsInput): CalculationResult<InverseLateralChromaticAberrationMappings>;
-//# sourceMappingURL=lateral-chromatic-aberration.d.ts.map

package/dist/optics/lateral-chromatic-aberration.js

@@ -1,18 +1,23 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates generic lateral chromatic-aberration field separation by mapping one ideal image-plane
- * point through a shared green-reference base distortion and red/blue radial coefficient offsets. This
- * is channel-dependent field mapping, not a blur kernel.
- * Inverse-maps one distorted output destination independently for the representative red/green/blue
- * channels. Renderers can use the returned per-channel ideal source coordinates for inverse sampling
- * without inventing chromatic-aberration equations.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Generic lateral chromatic aberration (CA): red, green and blue land at slightly different image
+ * positions.
+ *
+ * The forward mapping sends one ideal image-plane point through a base distortion shared by all
+ * channels (green is the reference), plus extra radial coefficients for red and blue. It moves each
+ * channel; it is not a blur kernel.
+ *
+ * The inverse mapping takes one distorted output point and finds the ideal source point separately
+ * for red, green and blue. Renderers can sample those per-channel source points directly, without
+ * writing their own CA equations.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { approximationResult } from "../core/calculation-result.js";
 import { InvalidScientificInputError } from "../core/validation.js";
 import { calculateInverseRadialDistortionMapping, calculateInverseRadialSourcePointValue, calculateRadialDistortionMapping, validateRadialDistortionProfile } from "./radial-distortion.js";
+import { requireInputObject, requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 function requireFiniteCoefficients(path, coefficients) {
     for (const key of ["k1", "k2", "k3"]) {
         if (!Number.isFinite(coefficients[key])) {
@@ -28,6 +33,7 @@ function addCoefficients(base, offset) {
     };
 }
 function resolveProfiles(profile) {
+    requireInputObject(profile, "profile input");
     requireFiniteCoefficients("profile.baseDistortionCoefficients", profile.baseDistortionCoefficients);
     requireFiniteCoefficients("profile.redCoefficientOffset", profile.redCoefficientOffset);
     requireFiniteCoefficients("profile.blueCoefficientOffset", profile.blueCoefficientOffset);
@@ -93,13 +99,15 @@ function assumptions() {
     ];
 }
 /**
- * Calculates generic lateral chromatic-aberration field separation by mapping
- * one ideal image-plane point through a shared green-reference base distortion
- * and red/blue radial coefficient offsets.
+ * Calculates how far lateral chromatic aberration (CA) separates the colour
+ * channels at one ideal image-plane point. The point goes through a shared
+ * base distortion (green is the reference) plus extra radial coefficients for
+ * red and blue.
  *
- * This is channel-dependent field mapping, not a blur kernel.
+ * This moves each channel; it is not a blur kernel.
  */
 export function calculateLateralChromaticAberrationMapping(input) {
+    requireInputKeys(input, "calculateLateralChromaticAberrationMapping", ["imagePointMm", "profile"]);
     const profiles = resolveProfiles(input.profile);
     const red = withChannelContext("red", () => calculateRadialDistortionMapping({
         imagePointMm: input.imagePointMm,
@@ -138,13 +146,14 @@ export function calculateLateralChromaticAberrationMapping(input) {
     }, "generic-green-reference-lateral-chromatic-aberration", "1.0.0", assumptions());
 }
 /**
- * Inverse-maps one distorted output destination independently for the
- * representative red/green/blue channels.
+ * Inverse-maps one distorted output point separately for the representative
+ * red, green and blue channels.
  *
- * Renderers can use the returned per-channel ideal source coordinates for
- * inverse sampling without inventing chromatic-aberration equations.
+ * Renderers can sample the returned per-channel ideal source points directly,
+ * without writing their own chromatic-aberration equations.
  */
 export function calculateInverseLateralChromaticAberrationMapping(input) {
+    requireInputKeys(input, "calculateInverseLateralChromaticAberrationMapping", ["distortedImagePointMm", "profile"]);
     const profiles = resolveProfiles(input.profile);
     const red = withChannelContext("red", () => calculateInverseRadialDistortionMapping({
         distortedImagePointMm: input.distortedImagePointMm,
@@ -183,14 +192,15 @@ export function calculateInverseLateralChromaticAberrationMapping(input) {
     }, "generic-inverse-green-reference-lateral-chromatic-aberration", "1.0.0", assumptions());
 }
 /**
- * Inverse-maps multiple distorted destinations while resolving the shared CA
- * profile once and validating each combined channel profile once for the
- * complete batch.
+ * Inverse-maps many distorted points at once. The shared CA profile is
+ * resolved once, and each combined channel profile is validated once, for
+ * the whole batch.
  *
- * Per-point values match calculateInverseLateralChromaticAberrationMapping();
- * provenance is shared once at the batch boundary.
+ * Each point's values match calculateInverseLateralChromaticAberrationMapping().
+ * Provenance is reported once for the batch.
  */
 export function calculateInverseLateralChromaticAberrationMappings(input) {
+    requireInputKeys(input, "calculateInverseLateralChromaticAberrationMappings", ["distortedImagePointsMm", "profile"]);
     const profiles = resolveProfiles(input.profile);
     const validatedProfiles = {
         red: withChannelContext("red", () => validateRadialDistortionProfile(profiles.red)),
@@ -198,7 +208,7 @@ export function calculateInverseLateralChromaticAberrationMappings(input) {
         blue: withChannelContext("blue", () => validateRadialDistortionProfile(profiles.blue))
     };
     if (!Array.isArray(input.distortedImagePointsMm)) {
-        throw new InvalidScientificInputError("distortedImagePointsMm must be an array of image-plane points.");
+        throw new InvalidConfigurationError("distortedImagePointsMm must be an array of image-plane points.");
     }
     const mappings = [];
     for (let index = 0; index < input.distortedImagePointsMm.length; index += 1) {

package/dist/optics/lateral-chromatic-aberration.js.map

@@ -1 +1 @@
-{"version":3,"file":"lateral-chromatic-aberration.js","sourceRoot":"","sources":["../../src/optics/lateral-chromatic-aberration.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lateral-chromatic-aberration.js","sourceRoot":"","sources":["../../src/optics/lateral-chromatic-aberration.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Generic lateral chromatic aberration (CA): red, green and blue land at slightly different image\n * positions.\n *\n * The forward mapping sends one ideal image-plane point through a base distortion shared by all\n * channels (green is the reference), plus extra radial coefficients for red and blue. It moves each\n * channel; it is not a blur kernel.\n *\n * The inverse mapping takes one distorted output point and finds the ideal source point separately\n * for red, green and blue. Renderers can sample those per-channel source points directly, without\n * writing their own CA equations.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  approximationResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport {\n  calculateInverseRadialDistortionMapping,\n  calculateInverseRadialSourcePointValue,\n  calculateRadialDistortionMapping,\n  validateRadialDistortionProfile,\n  type LensFieldPointMm,\n  type RadialDistortionCoefficients,\n  type RadialDistortionProfile\n} from \"./radial-distortion.js\";\nimport { requireInputObject, requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport type LateralChromaticAberrationChannel = \"red\" | \"green\" | \"blue\";\n\nexport interface LateralChromaticAberrationProfile {\n  /** Shared physical image-plane normalization radius in millimetres. */\n  normalizationRadiusMm: number;\n  /** Shared undistorted normalized-radius operating envelope. */\n  maximumNormalizedRadius: number;\n  /**\n   * Green-reference base geometric distortion.\n   *\n   * Every channel includes this shared mapping. The red and blue CA terms are\n   * added on top of it, so do not apply a second distortion pass.\n   */\n  baseDistortionCoefficients: RadialDistortionCoefficients;\n  /** Additional red-channel radial coefficients relative to green. */\n  redCoefficientOffset: RadialDistortionCoefficients;\n  /** Additional blue-channel radial coefficients relative to green. */\n  blueCoefficientOffset: RadialDistortionCoefficients;\n}\n\nexport interface CalculateLateralChromaticAberrationMappingInput {\n  /** Ideal/undistorted image-plane point shared by all channels. */\n  imagePointMm: LensFieldPointMm;\n  profile: LateralChromaticAberrationProfile;\n}\n\nexport interface CalculateInverseLateralChromaticAberrationMappingInput {\n  /**\n   * Distorted output image-plane point. Each channel is inverse-mapped on its\n   * own to its ideal source point.\n   */\n  distortedImagePointMm: LensFieldPointMm;\n  profile: LateralChromaticAberrationProfile;\n}\n\nexport interface CalculateInverseLateralChromaticAberrationMappingsInput {\n  /**\n   * Distorted output image-plane points. The profile is resolved once for the\n   * batch. Then each point is inverse-mapped separately for red, green and\n   * blue.\n   */\n  distortedImagePointsMm: readonly LensFieldPointMm[];\n  profile: LateralChromaticAberrationProfile;\n}\n\nexport interface LateralChromaticAberrationChannelMapping {\n  mappedImagePointMm: LensFieldPointMm;\n  radialScale: number;\n  combinedCoefficients: RadialDistortionCoefficients;\n}\n\nexport interface InverseLateralChromaticAberrationChannelMapping {\n  sourceImagePointMm: LensFieldPointMm;\n  radialScaleAtSource: number;\n  combinedCoefficients: RadialDistortionCoefficients;\n}\n\nexport interface ChannelSeparationVectorMm {\n  x: number;\n  y: number;\n  distance: number;\n}\n\nexport interface LateralChromaticAberrationSeparation {\n  redGreen: ChannelSeparationVectorMm;\n  blueGreen: ChannelSeparationVectorMm;\n  redBlue: ChannelSeparationVectorMm;\n  maximumPairDistanceMm: number;\n}\n\nexport interface LateralChromaticAberrationMapping {\n  direction: \"undistorted-to-channel-distorted\";\n  referenceChannel: \"green\";\n  sourceImagePointMm: LensFieldPointMm;\n  channels: {\n    red: LateralChromaticAberrationChannelMapping;\n    green: LateralChromaticAberrationChannelMapping;\n    blue: LateralChromaticAberrationChannelMapping;\n  };\n  separation: LateralChromaticAberrationSeparation;\n}\n\nexport interface InverseLateralChromaticAberrationMapping {\n  direction: \"distorted-output-to-channel-sources\";\n  referenceChannel: \"green\";\n  distortedImagePointMm: LensFieldPointMm;\n  channels: {\n    red: InverseLateralChromaticAberrationChannelMapping;\n    green: InverseLateralChromaticAberrationChannelMapping;\n    blue: InverseLateralChromaticAberrationChannelMapping;\n  };\n  sourceSeparation: LateralChromaticAberrationSeparation;\n}\n\nexport interface InverseLateralChromaticAberrationMappings {\n  direction: \"distorted-output-to-channel-sources-batch\";\n  referenceChannel: \"green\";\n  mappings: readonly InverseLateralChromaticAberrationMapping[];\n  pointCount: number;\n}\n\ninterface ChannelProfiles {\n  red: RadialDistortionProfile;\n  green: RadialDistortionProfile;\n  blue: RadialDistortionProfile;\n}\n\nfunction requireFiniteCoefficients(\n  path: string,\n  coefficients: RadialDistortionCoefficients\n): void {\n  for (const key of [\"k1\", \"k2\", \"k3\"] as const) {\n    if (!Number.isFinite(coefficients[key])) {\n      throw new InvalidScientificInputError(\n        `${path}.${key} must be finite.`\n      );\n    }\n  }\n}\n\nfunction addCoefficients(\n  base: RadialDistortionCoefficients,\n  offset: RadialDistortionCoefficients\n): RadialDistortionCoefficients {\n  return {\n    k1: base.k1 + offset.k1,\n    k2: base.k2 + offset.k2,\n    k3: base.k3 + offset.k3\n  };\n}\n\nfunction resolveProfiles(\n  profile: LateralChromaticAberrationProfile\n): ChannelProfiles {\n  requireInputObject(profile, \"profile input\");\n  requireFiniteCoefficients(\n    \"profile.baseDistortionCoefficients\",\n    profile.baseDistortionCoefficients\n  );\n  requireFiniteCoefficients(\n    \"profile.redCoefficientOffset\",\n    profile.redCoefficientOffset\n  );\n  requireFiniteCoefficients(\n    \"profile.blueCoefficientOffset\",\n    profile.blueCoefficientOffset\n  );\n\n  const shared = {\n    normalizationRadiusMm: profile.normalizationRadiusMm,\n    maximumNormalizedRadius: profile.maximumNormalizedRadius\n  };\n\n  return {\n    red: {\n      ...shared,\n      coefficients: addCoefficients(\n        profile.baseDistortionCoefficients,\n        profile.redCoefficientOffset\n      )\n    },\n    green: {\n      ...shared,\n      coefficients: { ...profile.baseDistortionCoefficients }\n    },\n    blue: {\n      ...shared,\n      coefficients: addCoefficients(\n        profile.baseDistortionCoefficients,\n        profile.blueCoefficientOffset\n      )\n    }\n  };\n}\n\nfunction withChannelContext<T>(\n  channel: LateralChromaticAberrationChannel,\n  calculate: () => T\n): T {\n  try {\n    return calculate();\n  } catch (error: unknown) {\n    if (error instanceof InvalidScientificInputError) {\n      throw new InvalidScientificInputError(\n        `Lateral chromatic aberration ${channel} channel: ${error.message}`\n      );\n    }\n    throw error;\n  }\n}\n\nfunction separationVector(\n  first: LensFieldPointMm,\n  second: LensFieldPointMm\n): ChannelSeparationVectorMm {\n  const x = first.x - second.x;\n  const y = first.y - second.y;\n  return {\n    x,\n    y,\n    distance: Math.hypot(x, y)\n  };\n}\n\nfunction separations(\n  red: LensFieldPointMm,\n  green: LensFieldPointMm,\n  blue: LensFieldPointMm\n): LateralChromaticAberrationSeparation {\n  const redGreen = separationVector(red, green);\n  const blueGreen = separationVector(blue, green);\n  const redBlue = separationVector(red, blue);\n\n  return {\n    redGreen,\n    blueGreen,\n    redBlue,\n    maximumPairDistanceMm: Math.max(\n      redGreen.distance,\n      blueGreen.distance,\n      redBlue.distance\n    )\n  };\n}\n\nfunction assumptions(): readonly string[] {\n  return [\n    \"Generic lateral chromatic aberration is represented as independent radial field mapping for abstract red, green, and blue renderer channels\",\n    \"Green is the reference field mapping; red and blue coefficient offsets are added to the green-reference base distortion rather than applied as a second warp\",\n    \"All channel mappings share one physical normalization radius and declared operating envelope\",\n    \"Each combined channel radial profile must remain one-to-one over the declared operating envelope\",\n    \"The RGB channel labels are representative rendering channels, not calibrated wavelengths, sensor spectral responses, or CFA primaries\",\n    \"This model changes channel field coordinates only; it does not blur, change PSF shape, modify channel intensity, or model longitudinal chromatic aberration\",\n    \"Profiles are generic caller inputs and do not represent a named lens unless separately calibrated with defensible provenance\"\n  ];\n}\n\n/**\n * Calculates how far lateral chromatic aberration (CA) separates the colour\n * channels at one ideal image-plane point. The point goes through a shared\n * base distortion (green is the reference) plus extra radial coefficients for\n * red and blue.\n *\n * This moves each channel; it is not a blur kernel.\n */\nexport function calculateLateralChromaticAberrationMapping(\n  input: CalculateLateralChromaticAberrationMappingInput\n): CalculationResult<LateralChromaticAberrationMapping> {\n  requireInputKeys(input, \"calculateLateralChromaticAberrationMapping\", [\"imagePointMm\", \"profile\"]);\n  const profiles = resolveProfiles(input.profile);\n\n  const red = withChannelContext(\"red\", () =>\n    calculateRadialDistortionMapping({\n      imagePointMm: input.imagePointMm,\n      profile: profiles.red\n    })\n  ).value;\n  const green = withChannelContext(\"green\", () =>\n    calculateRadialDistortionMapping({\n      imagePointMm: input.imagePointMm,\n      profile: profiles.green\n    })\n  ).value;\n  const blue = withChannelContext(\"blue\", () =>\n    calculateRadialDistortionMapping({\n      imagePointMm: input.imagePointMm,\n      profile: profiles.blue\n    })\n  ).value;\n\n  return approximationResult(\n    {\n      direction: \"undistorted-to-channel-distorted\",\n      referenceChannel: \"green\",\n      sourceImagePointMm: { ...input.imagePointMm },\n      channels: {\n        red: {\n          mappedImagePointMm: { ...red.mappedImagePointMm },\n          radialScale: red.radialScale,\n          combinedCoefficients: { ...profiles.red.coefficients }\n        },\n        green: {\n          mappedImagePointMm: { ...green.mappedImagePointMm },\n          radialScale: green.radialScale,\n          combinedCoefficients: { ...profiles.green.coefficients }\n        },\n        blue: {\n          mappedImagePointMm: { ...blue.mappedImagePointMm },\n          radialScale: blue.radialScale,\n          combinedCoefficients: { ...profiles.blue.coefficients }\n        }\n      },\n      separation: separations(\n        red.mappedImagePointMm,\n        green.mappedImagePointMm,\n        blue.mappedImagePointMm\n      )\n    },\n    \"generic-green-reference-lateral-chromatic-aberration\",\n    \"1.0.0\",\n    assumptions()\n  );\n}\n\n/**\n * Inverse-maps one distorted output point separately for the representative\n * red, green and blue channels.\n *\n * Renderers can sample the returned per-channel ideal source points directly,\n * without writing their own chromatic-aberration equations.\n */\nexport function calculateInverseLateralChromaticAberrationMapping(\n  input: CalculateInverseLateralChromaticAberrationMappingInput\n): CalculationResult<InverseLateralChromaticAberrationMapping> {\n  requireInputKeys(input, \"calculateInverseLateralChromaticAberrationMapping\", [\"distortedImagePointMm\", \"profile\"]);\n  const profiles = resolveProfiles(input.profile);\n\n  const red = withChannelContext(\"red\", () =>\n    calculateInverseRadialDistortionMapping({\n      distortedImagePointMm: input.distortedImagePointMm,\n      profile: profiles.red\n    })\n  ).value;\n  const green = withChannelContext(\"green\", () =>\n    calculateInverseRadialDistortionMapping({\n      distortedImagePointMm: input.distortedImagePointMm,\n      profile: profiles.green\n    })\n  ).value;\n  const blue = withChannelContext(\"blue\", () =>\n    calculateInverseRadialDistortionMapping({\n      distortedImagePointMm: input.distortedImagePointMm,\n      profile: profiles.blue\n    })\n  ).value;\n\n  return approximationResult(\n    {\n      direction: \"distorted-output-to-channel-sources\",\n      referenceChannel: \"green\",\n      distortedImagePointMm: { ...input.distortedImagePointMm },\n      channels: {\n        red: {\n          sourceImagePointMm: { ...red.sourceImagePointMm },\n          radialScaleAtSource: red.radialScaleAtSource,\n          combinedCoefficients: { ...profiles.red.coefficients }\n        },\n        green: {\n          sourceImagePointMm: { ...green.sourceImagePointMm },\n          radialScaleAtSource: green.radialScaleAtSource,\n          combinedCoefficients: { ...profiles.green.coefficients }\n        },\n        blue: {\n          sourceImagePointMm: { ...blue.sourceImagePointMm },\n          radialScaleAtSource: blue.radialScaleAtSource,\n          combinedCoefficients: { ...profiles.blue.coefficients }\n        }\n      },\n      sourceSeparation: separations(\n        red.sourceImagePointMm,\n        green.sourceImagePointMm,\n        blue.sourceImagePointMm\n      )\n    },\n    \"generic-inverse-green-reference-lateral-chromatic-aberration\",\n    \"1.0.0\",\n    assumptions()\n  );\n}\n\n/**\n * Inverse-maps many distorted points at once. The shared CA profile is\n * resolved once, and each combined channel profile is validated once, for\n * the whole batch.\n *\n * Each point's values match calculateInverseLateralChromaticAberrationMapping().\n * Provenance is reported once for the batch.\n */\nexport function calculateInverseLateralChromaticAberrationMappings(\n  input: CalculateInverseLateralChromaticAberrationMappingsInput\n): CalculationResult<InverseLateralChromaticAberrationMappings> {\n  requireInputKeys(input, \"calculateInverseLateralChromaticAberrationMappings\", [\"distortedImagePointsMm\", \"profile\"]);\n  const profiles = resolveProfiles(input.profile);\n  const validatedProfiles = {\n    red: withChannelContext(\"red\", () =>\n      validateRadialDistortionProfile(profiles.red)\n    ),\n    green: withChannelContext(\"green\", () =>\n      validateRadialDistortionProfile(profiles.green)\n    ),\n    blue: withChannelContext(\"blue\", () =>\n      validateRadialDistortionProfile(profiles.blue)\n    )\n  };\n  if (!Array.isArray(input.distortedImagePointsMm)) {\n    throw new InvalidConfigurationError(\n      \"distortedImagePointsMm must be an array of image-plane points.\"\n    );\n  }\n\n  const mappings: InverseLateralChromaticAberrationMapping[] = [];\n  for (\n    let index = 0;\n    index < input.distortedImagePointsMm.length;\n    index += 1\n  ) {\n    const point = input.distortedImagePointsMm[index];\n    if (point === undefined) {\n      throw new InvalidScientificInputError(\n        `distortedImagePointsMm[${index}] must be an image-plane point.`\n      );\n    }\n\n    const red = withChannelContext(\"red\", () =>\n      calculateInverseRadialSourcePointValue(\n        point,\n        validatedProfiles.red,\n        `distortedImagePointsMm[${index}]`\n      )\n    );\n    const green = withChannelContext(\"green\", () =>\n      calculateInverseRadialSourcePointValue(\n        point,\n        validatedProfiles.green,\n        `distortedImagePointsMm[${index}]`\n      )\n    );\n    const blue = withChannelContext(\"blue\", () =>\n      calculateInverseRadialSourcePointValue(\n        point,\n        validatedProfiles.blue,\n        `distortedImagePointsMm[${index}]`\n      )\n    );\n\n    mappings.push({\n      direction: \"distorted-output-to-channel-sources\" as const,\n      referenceChannel: \"green\" as const,\n      distortedImagePointMm: { ...point },\n      channels: {\n        red: {\n          sourceImagePointMm: { ...red.sourceImagePointMm },\n          radialScaleAtSource: red.radialScaleAtSource,\n          combinedCoefficients: { ...profiles.red.coefficients }\n        },\n        green: {\n          sourceImagePointMm: { ...green.sourceImagePointMm },\n          radialScaleAtSource: green.radialScaleAtSource,\n          combinedCoefficients: { ...profiles.green.coefficients }\n        },\n        blue: {\n          sourceImagePointMm: { ...blue.sourceImagePointMm },\n          radialScaleAtSource: blue.radialScaleAtSource,\n          combinedCoefficients: { ...profiles.blue.coefficients }\n        }\n      },\n      sourceSeparation: separations(\n        red.sourceImagePointMm,\n        green.sourceImagePointMm,\n        blue.sourceImagePointMm\n      )\n    });\n  }\n\n  return approximationResult(\n    {\n      direction: \"distorted-output-to-channel-sources-batch\",\n      referenceChannel: \"green\",\n      mappings,\n      pointCount: mappings.length\n    },\n    \"generic-inverse-green-reference-lateral-chromatic-aberration-batch\",\n    \"1.0.0\",\n    [\n      ...assumptions(),\n      \"Combined red/green/blue radial profiles are resolved once for the batch\",\n      \"Each channel profile is validated once before batch point sampling\"\n    ]\n  );\n}\n"]}

package/dist/optics/lens-psf-kernels.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Samples the engine's lens PSFs (`LensSampledPsfProfile`, resolved with `resolveLensSampledPsf`) into
+ * the per-patch kernels of the isoplanatic convolution (`calculateIrradianceConvolution`, #277).
+ *
+ * For each patch, the PSF is resolved at the patch centre's field point, in the per-site engine's own
+ * coordinates: native sensor millimetres from the optical axis (+Y down), field point (x, −y). Every
+ * PSF tap then maps to a site displacement with the per-site quadrature's inverse support
+ * (`sensorPsfSourcePoint`): tap (kx, ky) is the source at native offset (−(kx − cx)·pₓ, +(ky − cy)·p_y)
+ * from the destination, so its weight lands at displacement u = (kx − cx)·pₓ/sₓ, v = −(ky − cy)·p_y/s_y
+ * sites (p: PSF sample pitch, s: site pitch).
+ *
+ * - **Exact site sampling.** When every displacement is an integer (equal pitches, integer centre), each
+ *   tap's weight goes to one kernel cell. For a destination whose PSF equals its patch's, the
+ *   convolution then equals the per-site PSF quadrature at site-centre sources term by term.
+ * - **Otherwise (labelled approximation): bilinear splatting.** Each weight is split over the four
+ *   surrounding integer displacements with bilinear weights. This is the exact adjoint of bilinear
+ *   interpolation, so the convolution equals the per-site quadrature applied to the bilinear interpolant of
+ *   the site-centre samples (tested). Weights are conserved.
+ *
+ * With several wavelengths the kernel is the weight-normalized sum of the per-wavelength kernels. For a
+ * spectrally neutral scene that is exactly the per-site engine's spectral sum when the weights are its
+ * spectral quadrature weights times the scene spectrum (see docs/WEBGPU.md).
+ *
+ * The patch approximation (one PSF per patch, indexed by source site) is the caller's choice of patch
+ * size; its method error is measured, not bounded (docs/WEBGPU.md, "Per-fixture rollout"). Relative
+ * pupil throughput stays a separate factor and is reported, never folded into the unit-energy kernels.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type ResolveLensSampledPsfInput } from "./lens-psf-profile.js";
+export declare const LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION: "0.1.0";
+/** At most this many wavelengths per call. */
+export declare const LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS = 64;
+export interface LensPsfConvolutionKernelsInput {
+    schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;
+    /** The optical state, as for `resolveLensSampledPsf`, without the field point and wavelength. */
+    psf: Omit<ResolveLensSampledPsfInput, "fieldPointMm" | "wavelengthNm">;
+    /** One or more wavelengths with non-negative weights (at least one positive). */
+    spectralWeights: readonly {
+        wavelengthNm: number;
+        weight: number;
+    }[];
+    /** The convolution grid: sites, their pitch, and the optical axis in site units (site centres at i + 0.5). */
+    grid: {
+        width: number;
+        height: number;
+        sitePitchMicrometers: {
+            x: number;
+            y: number;
+        };
+        opticalAxisSite: {
+            x: number;
+            y: number;
+        };
+    };
+    /** Patch size in sites; the last row and column of patches may be partial. */
+    patchWidth: number;
+    patchHeight: number;
+    /** Kernel radius to use; omitted, the smallest radius that holds every tap. A radius too small to hold the PSF is rejected. */
+    kernelRadius?: number;
+}
+export interface LensPsfConvolutionKernels {
+    schemaVersion: typeof LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION;
+    kernelRadius: number;
+    patchWidth: number;
+    patchHeight: number;
+    patchColumns: number;
+    patchRows: number;
+    /** `[patchRow][patchColumn][v + r][u + r]`, ready for `IrradianceConvolutionInput.kernels`. */
+    kernels: Float64Array;
+    /** True when every tap landed on one integer displacement (no bilinear splatting). */
+    exactSiteSampling: boolean;
+    maximumKernelSum: number;
+    /** Per patch, row-major: the field point used and the weight-averaged relative pupil throughput (not applied). */
+    patches: readonly {
+        fieldPointMm: {
+            x: number;
+            y: number;
+        };
+        relativePupilThroughputFactor: number;
+        interpolated: boolean;
+    }[];
+}
+/**
+ * Builds the per-patch convolution kernels from a sampled lens PSF profile.
+ * @param input - See `LensPsfConvolutionKernelsInput`.
+ * @returns The kernels and per-patch field points. Success does not imply calibration.
+ * @see docs/WEBGPU.md, "Kernels from a lens PSF profile".
+ */
+export declare function resolveLensPsfConvolutionKernels(input: LensPsfConvolutionKernelsInput): CalculationResult<LensPsfConvolutionKernels>;

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

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Samples the engine's lens PSFs (`LensSampledPsfProfile`, resolved with `resolveLensSampledPsf`) into
+ * the per-patch kernels of the isoplanatic convolution (`calculateIrradianceConvolution`, #277).
+ *
+ * For each patch, the PSF is resolved at the patch centre's field point, in the per-site engine's own
+ * coordinates: native sensor millimetres from the optical axis (+Y down), field point (x, −y). Every
+ * PSF tap then maps to a site displacement with the per-site quadrature's inverse support
+ * (`sensorPsfSourcePoint`): tap (kx, ky) is the source at native offset (−(kx − cx)·pₓ, +(ky − cy)·p_y)
+ * from the destination, so its weight lands at displacement u = (kx − cx)·pₓ/sₓ, v = −(ky − cy)·p_y/s_y
+ * sites (p: PSF sample pitch, s: site pitch).
+ *
+ * - **Exact site sampling.** When every displacement is an integer (equal pitches, integer centre), each
+ *   tap's weight goes to one kernel cell. For a destination whose PSF equals its patch's, the
+ *   convolution then equals the per-site PSF quadrature at site-centre sources term by term.
+ * - **Otherwise (labelled approximation): bilinear splatting.** Each weight is split over the four
+ *   surrounding integer displacements with bilinear weights. This is the exact adjoint of bilinear
+ *   interpolation, so the convolution equals the per-site quadrature applied to the bilinear interpolant of
+ *   the site-centre samples (tested). Weights are conserved.
+ *
+ * With several wavelengths the kernel is the weight-normalized sum of the per-wavelength kernels. For a
+ * spectrally neutral scene that is exactly the per-site engine's spectral sum when the weights are its
+ * spectral quadrature weights times the scene spectrum (see docs/WEBGPU.md).
+ *
+ * The patch approximation (one PSF per patch, indexed by source site) is the caller's choice of patch
+ * size; its method error is measured, not bounded (docs/WEBGPU.md, "Per-fixture rollout"). Relative
+ * pupil throughput stays a separate factor and is reported, never folded into the unit-energy kernels.
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { requireAllowlistedRecord } from "../core/record-validation.js";
+import { IRRADIANCE_CONVOLUTION_LIMITS } from "./irradiance-convolution.js";
+import { markEngineOwnedLensSampledPsfProfile, resolveLensSampledPsf } from "./lens-psf-profile.js";
+export const LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION = "0.1.0";
+/** At most this many wavelengths per call. */
+export const LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS = 64;
+function positive(value, message) {
+    if (typeof value !== "number" || !(value > 0 && value <= Number.MAX_VALUE))
+        throw new InvalidConfigurationError(message);
+    return value;
+}
+function integer(value, minimum, maximum, message) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum)
+        throw new InvalidConfigurationError(message);
+    return value;
+}
+/**
+ * Builds the per-patch convolution kernels from a sampled lens PSF profile.
+ * @param input - See `LensPsfConvolutionKernelsInput`.
+ * @returns The kernels and per-patch field points. Success does not imply calibration.
+ * @see docs/WEBGPU.md, "Kernels from a lens PSF profile".
+ */
+export function resolveLensPsfConvolutionKernels(input) {
+    const r = requireAllowlistedRecord(input, ["schemaVersion", "psf", "spectralWeights", "grid", "patchWidth", "patchHeight", "kernelRadius"], "Invalid lens PSF convolution kernel input.");
+    if (r.schemaVersion !== LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION)
+        throw new InvalidConfigurationError("Unsupported lens PSF convolution kernel schema.");
+    const L = IRRADIANCE_CONVOLUTION_LIMITS;
+    const g = requireAllowlistedRecord(r.grid, ["width", "height", "sitePitchMicrometers", "opticalAxisSite"], "Invalid convolution grid.");
+    const width = integer(g.width, 1, L.maximumDimension, "Invalid convolution grid size."), height = integer(g.height, 1, L.maximumDimension, "Invalid convolution grid size.");
+    const pitch = requireAllowlistedRecord(g.sitePitchMicrometers, ["x", "y"], "Invalid site pitch.");
+    const sx = positive(pitch.x, "Site pitch must be positive."), sy = positive(pitch.y, "Site pitch must be positive.");
+    const axis = requireAllowlistedRecord(g.opticalAxisSite, ["x", "y"], "Invalid optical axis.");
+    if (typeof axis.x !== "number" || typeof axis.y !== "number" || !Number.isFinite(axis.x) || !Number.isFinite(axis.y)) {
+        throw new InvalidConfigurationError("The optical axis must be finite site coordinates.");
+    }
+    const patchWidth = integer(r.patchWidth, 1, width, "Invalid patch size."), patchHeight = integer(r.patchHeight, 1, height, "Invalid patch size.");
+    const columns = Math.ceil(width / patchWidth), rows = Math.ceil(height / patchHeight);
+    if (columns * rows > L.maximumPatchCount)
+        throw new InvalidConfigurationError("Too many patches.");
+    const list = r.spectralWeights;
+    if (!Array.isArray(list) || list.length < 1 || list.length > LENS_PSF_CONVOLUTION_KERNELS_MAXIMUM_WAVELENGTHS) {
+        throw new InvalidConfigurationError("spectralWeights must list 1 to 64 wavelengths.");
+    }
+    const spectral = list.map((entry) => {
+        const e = requireAllowlistedRecord(entry, ["wavelengthNm", "weight"], "Invalid spectral weight.");
+        if (typeof e.weight !== "number" || !(e.weight >= 0 && e.weight <= Number.MAX_VALUE))
+            throw new InvalidConfigurationError("Spectral weights must be finite and non-negative.");
+        return { wavelengthNm: positive(e.wavelengthNm, "Wavelengths must be positive."), weight: e.weight };
+    });
+    const totalWeight = spectral.reduce((s, e) => s + e.weight, 0);
+    if (!(totalWeight > 0 && totalWeight <= Number.MAX_VALUE))
+        throw new InvalidConfigurationError("At least one spectral weight must be positive.");
+    const psf = requireAllowlistedRecord(r.psf, ["profile", "focalLengthMm", "focus", "apertureFNumber", "signedDefocusImagePlaneMicrometers"], "Invalid PSF state.");
+    // One private parse of the profile for every patch and wavelength.
+    const profile = structuredClone(psf.profile);
+    markEngineOwnedLensSampledPsfProfile(profile);
+    const state = { ...psf, profile };
+    // Resolve every patch and wavelength, splatting straight into one scratch displacement map sized for the largest
+    // allowed radius; each patch keeps a copy cropped to its own reach. The common radius is known only at the end.
+    // Every cell receives its weights in the same order as a direct sum (taps in kernel order, then the four
+    // bilinear corners), so the kernels do not depend on the scratch layout.
+    const M = L.maximumKernelRadius, scratchSize = 2 * M + 1, scratch = new Float64Array(scratchSize * scratchSize);
+    const cropped = [], patches = [];
+    let reach = 0, exact = true, overflow = false;
+    for (let pr = 0; pr < rows; pr++)
+        for (let pc = 0; pc < columns; pc++) {
+            const x0 = pc * patchWidth, y0 = pr * patchHeight, x1 = Math.min(width, x0 + patchWidth), y1 = Math.min(height, y0 + patchHeight);
+            const nativeX = ((x0 + x1) / 2 - axis.x) * sx / 1000, nativeY = ((y0 + y1) / 2 - axis.y) * sy / 1000;
+            const fieldPointMm = { x: nativeX, y: -nativeY };
+            let throughput = 0, interpolated = false, patchReach = 0;
+            for (const { wavelengthNm, weight } of spectral) {
+                if (weight === 0)
+                    continue;
+                const resolved = resolveLensSampledPsf({ ...state, fieldPointMm, wavelengthNm }).value, k = resolved.kernel, share = weight / totalWeight;
+                throughput += share * resolved.relativePupilThroughputFactor;
+                if (resolved.resolutionStatus !== "exact-grid-sample")
+                    interpolated = true;
+                for (let ky = 0; ky < k.heightSamples; ky++)
+                    for (let kx = 0; kx < k.widthSamples; kx++) {
+                        const intensity = k.normalizedIntensity[ky * k.widthSamples + kx];
+                        if (intensity === 0)
+                            continue;
+                        const u = (kx - k.centerSampleX) * k.samplePitchMicrometersX / sx, v = -(ky - k.centerSampleY) * k.samplePitchMicrometersY / sy;
+                        const u0 = Math.floor(u), v0 = Math.floor(v), fu = u - u0, fv = v - v0, w = share * intensity;
+                        if (fu !== 0 || fv !== 0)
+                            exact = false;
+                        for (let corner = 0; corner < 4; corner++) {
+                            const du = corner & 1, dv = corner >> 1;
+                            const b = du === 0 ? (dv === 0 ? (1 - fu) * (1 - fv) : (1 - fu) * fv) : (dv === 0 ? fu * (1 - fv) : fu * fv);
+                            if (b === 0)
+                                continue;
+                            const cu = u0 + du, cv = v0 + dv;
+                            patchReach = Math.max(patchReach, Math.abs(cu), Math.abs(cv));
+                            // Past the largest radius the call is rejected below; resolving continues so errors keep their order.
+                            if (patchReach > M) {
+                                overflow = true;
+                                continue;
+                            }
+                            if (!overflow)
+                                scratch[(cv + M) * scratchSize + cu + M] += w * b;
+                        }
+                    }
+            }
+            reach = Math.max(reach, patchReach);
+            if (!overflow) {
+                const n = 2 * patchReach + 1, values = new Float64Array(n * n);
+                for (let v = -patchReach; v <= patchReach; v++) {
+                    const row = (v + M) * scratchSize + M;
+                    values.set(scratch.subarray(row - patchReach, row + patchReach + 1), (v + patchReach) * n);
+                    scratch.fill(0, row - patchReach, row + patchReach + 1);
+                }
+                cropped.push({ reach: patchReach, values });
+            }
+            patches.push(Object.freeze({ fieldPointMm: Object.freeze(fieldPointMm), relativePupilThroughputFactor: throughput, interpolated }));
+        }
+    const radius = r.kernelRadius === undefined ? reach : integer(r.kernelRadius, 0, L.maximumKernelRadius, "Invalid kernel radius.");
+    if (reach > radius)
+        throw new InvalidConfigurationError("The kernel radius is too small for the PSF support; no tap is dropped.");
+    if (radius > L.maximumKernelRadius)
+        throw new InvalidConfigurationError("The PSF support needs a kernel radius above 32 sites.");
+    const size = 2 * radius + 1, taps = size * size;
+    if (columns * rows * taps > L.maximumKernelWeights)
+        throw new InvalidConfigurationError("Too many kernel weights.");
+    const kernels = new Float64Array(columns * rows * taps);
+    let maximumKernelSum = 0;
+    cropped.forEach(({ reach: q, values }, p) => {
+        const n = 2 * q + 1;
+        let sum = 0;
+        for (let v = 0; v < n; v++)
+            kernels.set(values.subarray(v * n, (v + 1) * n), p * taps + (v - q + radius) * size + radius - q);
+        for (let t = 0; t < taps; t++)
+            sum += kernels[p * taps + t];
+        maximumKernelSum = Math.max(maximumKernelSum, sum);
+    });
+    if (maximumKernelSum > L.maximumKernelSum)
+        throw new InvalidConfigurationError("Sampled kernels exceed unit energy.");
+    return approximationResult({ schemaVersion: LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION, kernelRadius: radius, patchWidth, patchHeight,
+        patchColumns: columns, patchRows: rows, kernels, exactSiteSampling: exact, maximumKernelSum, patches: Object.freeze(patches) }, "lens-psf-convolution-kernels", LENS_PSF_CONVOLUTION_KERNELS_SCHEMA_VERSION, [
+        "One PSF per patch, resolved at the patch centre with resolveLensSampledPsf; indexed by source site in the convolution (isoplanatic patches).",
+        exact ? "Every PSF tap maps to one integer site displacement (exact site sampling)." :
+            "PSF taps between sites are split bilinearly (the adjoint of bilinear interpolation of site-centre samples); a labelled approximation.",
+        "Relative pupil throughput is reported per patch and not applied to the unit-energy kernels."
+    ]);
+}
+//# sourceMappingURL=lens-psf-kernels.js.map

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

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