@photivra/engine 2.20.0 → 2.22.0

package/dist/motion/subject-motion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subject-motion.js","sourceRoot":"","sources":["../../src/motion/subject-motion.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Subject motion (#551, 2.22.0): the whole scene, or one declared rectangle of it, moving on the scene plane during the\n * exposure, over a still background. Translation in m/s on the plane and, optionally, a constant rotation about an axis\n * parallel to the optical axis (through the plane's origin for the whole scene, through the rectangle's centre for a\n * region). Times are seconds from the first opening reference, the camera rotation's time reference, so each site's own\n * exposure window (shifted by its rolling-shutter offset) sees the subject where it is during that window.\n *\n * The scene at plane point p and time t: a point of the subject at rest point q is at R(θ)(q − c) + c + d at time t\n * (d = v·t, θ = ω·t, c the centre), so p shows the subject's q = R(−θ)(p − c − d) + c when q lies in the subject; else\n * a region's rest rectangle shows a neutral 18 % background (what the subject revealed), and anywhere else the still scene at p. Exact for this\n * model (rigid motion of a planar layer); the blur is the capture's temporal midpoint quadrature.\n * @see docs/QUICK_START.md, \"Subject motion\".\n */\n\nimport type { PlanarSceneRadianceProvider } from \"../facade/scene-radiance.js\";\nimport type { SceneRadianceEvaluationRequest, SceneRadianceEvaluationResult } from \"../schema/scene-radiance.js\";\n\n/** `motion.subject` of `simulateCapture`: a moving subject on the scene plane (#551). */\nexport interface SimulateCaptureSubjectMotion {\n  /** Velocity on the scene plane, m/s: +x right, +y up as seen from the camera. Missing components are 0. */\n  velocityMPerSec?: { x?: number; y?: number };\n  /** Rotation about the optical axis direction, rad/s, counter-clockwise as seen from the camera (+x toward +y). Default 0. */\n  angularVelocityRadPerSec?: number;\n  /**\n   * The moving part: a rectangle on the scene plane at rest (at the first opening reference), its centre and size in metres\n   * (+x right, +y up from the optical axis). Omitted: the whole scene moves.\n   */\n  region?: { centerXM: number; centerYM: number; widthM: number; heightM: number };\n  /** Exact or fast (2.20.0 convention): fast takes fewer temporal midpoints when the subject's streak is short (see the docs). */\n  fast?: boolean;\n}\n\n/** Internal: a validated subject motion (simulate-capture.ts parses it). */\nexport interface SubjectMotion {\n  vx: number; vy: number; omega: number;\n  /** The region's centre and half sizes in metres, or undefined for the whole scene. */\n  region: { cx: number; cy: number; hw: number; hh: number } | undefined;\n}\n\n/**\n * The farthest any subject point travels on the plane during `seconds`, in metres (translation plus rotation at the subject's\n * farthest point from its centre; `reachM` is the whole scene's reach from the axis when no region is declared).\n */\nexport function subjectTravelM(motion: SubjectMotion, seconds: number, reachM: number): number {\n  const r = motion.region, arm = r ? Math.hypot(r.hw, r.hh) : reachM;\n  return (Math.hypot(motion.vx, motion.vy) + Math.abs(motion.omega) * arm) * seconds;\n}\n\n/**\n * The plane point that shows at (x, y) at time t (in the motion's length unit), written to out[0], out[1]; returns false where a region's rest\n * rectangle shows the revealed background. Without motion at t (d = 0, θ = 0) the point is (x, y) unchanged, bit for bit.\n */\nexport function subjectSourcePoint(motion: SubjectMotion, x: number, y: number, t: number, out: Float64Array): boolean {\n  const r = motion.region, th = motion.omega * t;\n  let qx = x - motion.vx * t, qy = y - motion.vy * t;\n  if (th !== 0) {\n    const cx = r ? r.cx : 0, cy = r ? r.cy : 0, c = Math.cos(th), s = Math.sin(th), dx = qx - cx, dy = qy - cy;\n    qx = c * dx + s * dy + cx; qy = c * dy - s * dx + cy;\n  }\n  if (r && !(Math.abs(qx - r.cx) <= r.hw && Math.abs(qy - r.cy) <= r.hh)) {\n    out[0] = x; out[1] = y;\n    return !(Math.abs(x - r.cx) <= r.hw && Math.abs(y - r.cy) <= r.hh);\n  }\n  out[0] = qx; out[1] = qy;\n  return true;\n}\n\n/**\n * The scene of `base` with the subject moving: `evaluateRadiance` reads each query at its request time (the base result, with the\n * radiance read where the subject shows), and `radianceAt` takes the time as a fourth argument (default 0) for the image-space\n * lattices and the display view. It has no chart material access, so renderers read radiance. `revealedRadiance` is the revealed\n * background's spectral radiance at a plane point in frame units (an 18 % neutral reflectance under the irradiance there).\n */\nexport function createSubjectMotionProvider(base: PlanarSceneRadianceProvider, motion: SubjectMotion, distanceM: number, scale: number,\n  revealedRadiance: (u: number, v: number, nm: number) => number): PlanarSceneRadianceProvider {\n  // The motion in frame units, so a still instant reads the base at the queried point itself.\n  const r = motion.region, framed: SubjectMotion = { vx: motion.vx / scale, vy: motion.vy / scale, omega: motion.omega,\n    region: r && { cx: r.cx / scale, cy: r.cy / scale, hw: r.hw / scale, hh: r.hh / scale } }, point = new Float64Array(2);\n  const radianceAt = (u: number, v: number, nm: number, t = 0): number =>\n    subjectSourcePoint(framed, u, v, t, point) ? base.radianceAt(point[0]!, point[1]!, nm) : revealedRadiance(u, v, nm);\n  return { sceneId: base.sceneId, providerProfileId: base.providerProfileId, radianceAt, evaluateApertureRadiance: base.evaluateApertureRadiance,\n    evaluateRadiance(request: Readonly<SceneRadianceEvaluationRequest>): SceneRadianceEvaluationResult {\n      const result = base.evaluateRadiance(request), o = (request.target as { outgoingDirectionUnitVector: { x: number; y: number; z: number } }).outgoingDirectionUnitVector;\n      if (!(o.z < 0)) return result;\n      // The base provider's own plane-point arithmetic for this direction.\n      const t = distanceM / -o.z;\n      return { ...result, spectralRadianceWattsPerSquareMeterSteradianNanometer: radianceAt(-o.x * t / scale, -o.y * t / scale, request.wavelengthNanometers, request.timeSecondsFromExposureStart) };\n    } };\n}\n"]}

package/dist/optics/generic-lens-lateral-color.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Lateral colour of a catalogue lens as a fringe width (#580): the red–blue image displacement in micrometres and in pixels at
+ * one field position, for the app's Guide page on color fringing.
+ *
+ * It reads the lens's own lateral-colour model (`docs/LENS_CATALOGUE.md`, "Models"), the one `simulateCapture` renders and
+ * `createGenericLensCorrectionProfile` corrects: a radial image displacement Δr(λ) = L·R·H·D(λ), with L the lens's
+ * `lateralColor.fraction`, R the sensor's half-diagonal, H the field height (fraction of R) and D(λ) the normalised Cauchy
+ * dispersion (0 at the Fraunhofer d line, F minus C = 1). The red and blue channels are taken at the effective wavelengths of
+ * the lens corrections, `GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM` (610 and 465 nm), so the blue-minus-red displacement
+ * is L·R·H·(D(465) − D(610)). With `channelDispersion` (2.21.0, #589's `calculateChannelEffectiveDispersion` for the camera's
+ * channels and the light) it is L·R·H·(D̄_blue − D̄_red), the displacement `simulateCapture` renders in RAW. The lens's lateral
+ * colour does not change with the f-number or the focus distance.
+ *
+ * Every value is an approximation: the lens is a generic Photivra design, not a measured product, and a real channel spans a
+ * band of wavelengths, not one.
+ */
+import { type CalculationResult } from "../core/calculation-result.js";
+import { type ChannelDispersion } from "../output/developed-lens-corrections.js";
+export interface CalculateLateralColorFringeInput {
+    /** A catalogue id (`GENERIC_LENS_IDS`). */
+    lensId: string;
+    /** The sensor's active capture area, mm (the lens is scaled to it as in `resolveGenericLens`). */
+    activeImagingArea: {
+        widthMm: number;
+        heightMm: number;
+    };
+    /** The sensor's pixel pitch, µm. */
+    pixelPitchMicrometers: number;
+    /**
+     * The field position as fractions of the frame's half-width (x, +right) and half-height (y, +up) from the optical axis, each
+     * in [−1, 1]. Default `{ x: 1, y: 1 }`: the top-right corner.
+     */
+    fieldPosition?: {
+        x: number;
+        y: number;
+    };
+    /**
+     * 2.21.0: each channel's effective dispersion (`calculateChannelEffectiveDispersion` for the camera's channels and the light;
+     * only `red` and `blue` are read). Default: D at the single wavelengths 610 and 465 nm.
+     */
+    channelDispersion?: ChannelDispersion;
+}
+/** A signed displacement of the blue image from the red one: radial (positive: blue farther from the axis) and its x and y parts. */
+export interface LateralColorDisplacement {
+    radial: number;
+    x: number;
+    y: number;
+}
+export interface LateralColorFringe {
+    lensId: string;
+    /** The image-plane point, mm from the optical axis (+x right, +y up). */
+    imagePointMm: {
+        x: number;
+        y: number;
+    };
+    /** Field height H: the point's distance from the axis as a fraction of the half-diagonal (1 at the corner). */
+    fieldHeight: number;
+    /** The channel wavelengths the displacement is taken at, nm; null with a given `channelDispersion`. */
+    channelWavelengthsNm: {
+        red: number;
+        blue: number;
+    } | null;
+    /** The red and blue dispersions D used (normalized: 0 at the d line, F minus C = 1). */
+    channelDispersion: {
+        red: number;
+        blue: number;
+    };
+    /** Blue-minus-red image displacement, µm. */
+    blueMinusRedMicrometers: LateralColorDisplacement;
+    /** The same in pixels of the given pitch. */
+    blueMinusRedPixels: LateralColorDisplacement;
+    /** The fringe width: |radial| displacement, µm and pixels. */
+    fringeWidthMicrometers: number;
+    fringeWidthPixels: number;
+    /** The lens's own F-to-C (486 to 656 nm) displacement at this point, L·R·H, µm. */
+    fToCMicrometers: number;
+}
+/**
+ * The red–blue image displacement of a catalogue lens at a field position on a sensor, in micrometres and pixels, from the
+ * lens's own lateral-colour model Δr(λ) = L·R·H·D(λ) at the lens corrections' channel wavelengths (610 and 465 nm), or at the
+ * given `channelDispersion`. Exact for the model (no fast mode); an approximation of a generic lens, not a measured product.
+ */
+export declare function calculateLateralColorFringe(input: CalculateLateralColorFringeInput): CalculationResult<LateralColorFringe>;

package/dist/optics/generic-lens-lateral-color.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Lateral colour of a catalogue lens as a fringe width (#580): the red–blue image displacement in micrometres and in pixels at
+ * one field position, for the app's Guide page on color fringing.
+ *
+ * It reads the lens's own lateral-colour model (`docs/LENS_CATALOGUE.md`, "Models"), the one `simulateCapture` renders and
+ * `createGenericLensCorrectionProfile` corrects: a radial image displacement Δr(λ) = L·R·H·D(λ), with L the lens's
+ * `lateralColor.fraction`, R the sensor's half-diagonal, H the field height (fraction of R) and D(λ) the normalised Cauchy
+ * dispersion (0 at the Fraunhofer d line, F minus C = 1). The red and blue channels are taken at the effective wavelengths of
+ * the lens corrections, `GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM` (610 and 465 nm), so the blue-minus-red displacement
+ * is L·R·H·(D(465) − D(610)). With `channelDispersion` (2.21.0, #589's `calculateChannelEffectiveDispersion` for the camera's
+ * channels and the light) it is L·R·H·(D̄_blue − D̄_red), the displacement `simulateCapture` renders in RAW. The lens's lateral
+ * colour does not change with the f-number or the focus distance.
+ *
+ * Every value is an approximation: the lens is a generic Photivra design, not a measured product, and a real channel spans a
+ * band of wavelengths, not one.
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { requireInputKeys, requireInputObject } from "../core/record-validation.js";
+import { genericLensDispersion, resolveGenericLens } from "../equipment/generic-lens-catalogue.js";
+import { GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM } from "../output/developed-lens-corrections.js";
+function positiveFinite(value, name) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        throw new InvalidScientificInputError(name + " must be a positive finite number.");
+    return value;
+}
+function fieldCoordinate(value, name) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < -1 || value > 1)
+        throw new InvalidScientificInputError(name + " must be a finite number in [-1, 1].");
+    return value;
+}
+/**
+ * The red–blue image displacement of a catalogue lens at a field position on a sensor, in micrometres and pixels, from the
+ * lens's own lateral-colour model Δr(λ) = L·R·H·D(λ) at the lens corrections' channel wavelengths (610 and 465 nm), or at the
+ * given `channelDispersion`. Exact for the model (no fast mode); an approximation of a generic lens, not a measured product.
+ */
+export function calculateLateralColorFringe(input) {
+    requireInputObject(input, "calculateLateralColorFringe input");
+    requireInputKeys(input, "calculateLateralColorFringe", ["lensId", "activeImagingArea", "pixelPitchMicrometers", "fieldPosition", "channelDispersion"]);
+    const lens = resolveGenericLens({ lensId: input.lensId, activeImagingArea: input.activeImagingArea });
+    const pitch = positiveFinite(input.pixelPitchMicrometers, "pixelPitchMicrometers");
+    let u = 1, v = 1;
+    if (input.fieldPosition !== undefined) {
+        requireInputObject(input.fieldPosition, "fieldPosition");
+        requireInputKeys(input.fieldPosition, "fieldPosition", ["x", "y"]);
+        u = fieldCoordinate(input.fieldPosition.x, "fieldPosition.x");
+        v = fieldCoordinate(input.fieldPosition.y, "fieldPosition.y");
+    }
+    const x = u * input.activeImagingArea.widthMm / 2, y = v * input.activeImagingArea.heightMm / 2, r = Math.hypot(x, y);
+    const fieldHeight = r / lens.halfDiagonalMm, { red, blue } = GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM, given = input.channelDispersion;
+    let dispersion = { red: genericLensDispersion(red), blue: genericLensDispersion(blue) };
+    if (given !== undefined) {
+        requireInputObject(given, "channelDispersion");
+        requireInputKeys(given, "channelDispersion", ["red", "green", "blue"]);
+        // D spans −1.08 (1100 nm) to 4.30 (300 nm), as createGenericLensCorrectionProfile checks.
+        for (const c of ["red", "blue"])
+            if (typeof given[c] !== "number" || !(given[c] >= -1.1 && given[c] <= 4.4))
+                throw new InvalidScientificInputError("channelDispersion." + c + " must be a number in [−1.1, 4.4], D between 1100 and 300 nm.");
+        dispersion = { red: given.red, blue: given.blue };
+    }
+    const fToCMicrometers = lens.character.lateralColor.fraction * lens.halfDiagonalMm * 1000 * fieldHeight;
+    const radial = fToCMicrometers * (dispersion.blue - dispersion.red);
+    const cos = r > 0 ? x / r : 0, sin = r > 0 ? y / r : 0;
+    // `+ 0` turns a −0 (from a negative zero cosine or sine) into 0.
+    const um = { radial, x: radial * cos + 0, y: radial * sin + 0 };
+    return approximationResult({ lensId: lens.lensId, imagePointMm: { x, y }, fieldHeight, channelWavelengthsNm: given ? null : { red, blue }, channelDispersion: dispersion,
+        blueMinusRedMicrometers: um, blueMinusRedPixels: { radial: um.radial / pitch, x: um.x / pitch, y: um.y / pitch },
+        fringeWidthMicrometers: Math.abs(radial), fringeWidthPixels: Math.abs(radial) / pitch, fToCMicrometers }, "generic-lens-lateral-color-fringe", "1.0.0", [
+        "The catalogue lens's lateral-colour model: radial displacement L·R·H·D(λ), D the normalised Cauchy dispersion (Fraunhofer d, F and C lines).",
+        given ? "Red and blue at the given channel dispersions (a neutral surface's weighting of each channel's band)." :
+            "Red and blue at single effective wavelengths of 610 and 465 nm (GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM); a real channel spans a band.",
+        "A generic Photivra lens, not a measured product; lateral colour does not change with the f-number or the focus distance in this model.",
+        "Geometric displacement only: the rendered fringe also depends on the lens's blur, the demosaic and the colour conversion."
+    ]);
+}
+//# sourceMappingURL=generic-lens-lateral-color.js.map

package/dist/optics/generic-lens-lateral-color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-lens-lateral-color.js","sourceRoot":"","sources":["../../src/optics/generic-lens-lateral-color.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Lateral colour of a catalogue lens as a fringe width (#580): the red–blue image displacement in micrometres and in pixels at\n * one field position, for the app's Guide page on color fringing.\n *\n * It reads the lens's own lateral-colour model (`docs/LENS_CATALOGUE.md`, \"Models\"), the one `simulateCapture` renders and\n * `createGenericLensCorrectionProfile` corrects: a radial image displacement Δr(λ) = L·R·H·D(λ), with L the lens's\n * `lateralColor.fraction`, R the sensor's half-diagonal, H the field height (fraction of R) and D(λ) the normalised Cauchy\n * dispersion (0 at the Fraunhofer d line, F minus C = 1). The red and blue channels are taken at the effective wavelengths of\n * the lens corrections, `GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM` (610 and 465 nm), so the blue-minus-red displacement\n * is L·R·H·(D(465) − D(610)). With `channelDispersion` (2.21.0, #589's `calculateChannelEffectiveDispersion` for the camera's\n * channels and the light) it is L·R·H·(D̄_blue − D̄_red), the displacement `simulateCapture` renders in RAW. The lens's lateral\n * colour does not change with the f-number or the focus distance.\n *\n * Every value is an approximation: the lens is a generic Photivra design, not a measured product, and a real channel spans a\n * band of wavelengths, not one.\n */\n\nimport { approximationResult, type CalculationResult } from \"../core/calculation-result.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { requireInputKeys, requireInputObject } from \"../core/record-validation.js\";\nimport { genericLensDispersion, resolveGenericLens } from \"../equipment/generic-lens-catalogue.js\";\nimport { GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM, type ChannelDispersion } from \"../output/developed-lens-corrections.js\";\n\nexport interface CalculateLateralColorFringeInput {\n  /** A catalogue id (`GENERIC_LENS_IDS`). */\n  lensId: string;\n  /** The sensor's active capture area, mm (the lens is scaled to it as in `resolveGenericLens`). */\n  activeImagingArea: { widthMm: number; heightMm: number };\n  /** The sensor's pixel pitch, µm. */\n  pixelPitchMicrometers: number;\n  /**\n   * The field position as fractions of the frame's half-width (x, +right) and half-height (y, +up) from the optical axis, each\n   * in [−1, 1]. Default `{ x: 1, y: 1 }`: the top-right corner.\n   */\n  fieldPosition?: { x: number; y: number };\n  /**\n   * 2.21.0: each channel's effective dispersion (`calculateChannelEffectiveDispersion` for the camera's channels and the light;\n   * only `red` and `blue` are read). Default: D at the single wavelengths 610 and 465 nm.\n   */\n  channelDispersion?: ChannelDispersion;\n}\n\n/** A signed displacement of the blue image from the red one: radial (positive: blue farther from the axis) and its x and y parts. */\nexport interface LateralColorDisplacement {\n  radial: number;\n  x: number;\n  y: number;\n}\n\nexport interface LateralColorFringe {\n  lensId: string;\n  /** The image-plane point, mm from the optical axis (+x right, +y up). */\n  imagePointMm: { x: number; y: number };\n  /** Field height H: the point's distance from the axis as a fraction of the half-diagonal (1 at the corner). */\n  fieldHeight: number;\n  /** The channel wavelengths the displacement is taken at, nm; null with a given `channelDispersion`. */\n  channelWavelengthsNm: { red: number; blue: number } | null;\n  /** The red and blue dispersions D used (normalized: 0 at the d line, F minus C = 1). */\n  channelDispersion: { red: number; blue: number };\n  /** Blue-minus-red image displacement, µm. */\n  blueMinusRedMicrometers: LateralColorDisplacement;\n  /** The same in pixels of the given pitch. */\n  blueMinusRedPixels: LateralColorDisplacement;\n  /** The fringe width: |radial| displacement, µm and pixels. */\n  fringeWidthMicrometers: number;\n  fringeWidthPixels: number;\n  /** The lens's own F-to-C (486 to 656 nm) displacement at this point, L·R·H, µm. */\n  fToCMicrometers: number;\n}\n\nfunction positiveFinite(value: unknown, name: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) throw new InvalidScientificInputError(name + \" must be a positive finite number.\");\n  return value;\n}\nfunction fieldCoordinate(value: unknown, name: string): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value < -1 || value > 1) throw new InvalidScientificInputError(name + \" must be a finite number in [-1, 1].\");\n  return value;\n}\n\n/**\n * The red–blue image displacement of a catalogue lens at a field position on a sensor, in micrometres and pixels, from the\n * lens's own lateral-colour model Δr(λ) = L·R·H·D(λ) at the lens corrections' channel wavelengths (610 and 465 nm), or at the\n * given `channelDispersion`. Exact for the model (no fast mode); an approximation of a generic lens, not a measured product.\n */\nexport function calculateLateralColorFringe(input: CalculateLateralColorFringeInput): CalculationResult<LateralColorFringe> {\n  requireInputObject(input, \"calculateLateralColorFringe input\");\n  requireInputKeys(input, \"calculateLateralColorFringe\", [\"lensId\", \"activeImagingArea\", \"pixelPitchMicrometers\", \"fieldPosition\", \"channelDispersion\"]);\n  const lens = resolveGenericLens({ lensId: input.lensId, activeImagingArea: input.activeImagingArea });\n  const pitch = positiveFinite(input.pixelPitchMicrometers, \"pixelPitchMicrometers\");\n  let u = 1, v = 1;\n  if (input.fieldPosition !== undefined) {\n    requireInputObject(input.fieldPosition, \"fieldPosition\");\n    requireInputKeys(input.fieldPosition, \"fieldPosition\", [\"x\", \"y\"]);\n    u = fieldCoordinate(input.fieldPosition.x, \"fieldPosition.x\"); v = fieldCoordinate(input.fieldPosition.y, \"fieldPosition.y\");\n  }\n  const x = u * input.activeImagingArea.widthMm / 2, y = v * input.activeImagingArea.heightMm / 2, r = Math.hypot(x, y);\n  const fieldHeight = r / lens.halfDiagonalMm, { red, blue } = GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM, given = input.channelDispersion;\n  let dispersion = { red: genericLensDispersion(red), blue: genericLensDispersion(blue) };\n  if (given !== undefined) {\n    requireInputObject(given, \"channelDispersion\");\n    requireInputKeys(given, \"channelDispersion\", [\"red\", \"green\", \"blue\"]);\n    // D spans −1.08 (1100 nm) to 4.30 (300 nm), as createGenericLensCorrectionProfile checks.\n    for (const c of [\"red\", \"blue\"] as const) if (typeof given[c] !== \"number\" || !(given[c] >= -1.1 && given[c] <= 4.4))\n      throw new InvalidScientificInputError(\"channelDispersion.\" + c + \" must be a number in [−1.1, 4.4], D between 1100 and 300 nm.\");\n    dispersion = { red: given.red, blue: given.blue };\n  }\n  const fToCMicrometers = lens.character.lateralColor.fraction * lens.halfDiagonalMm * 1000 * fieldHeight;\n  const radial = fToCMicrometers * (dispersion.blue - dispersion.red);\n  const cos = r > 0 ? x / r : 0, sin = r > 0 ? y / r : 0;\n  // `+ 0` turns a −0 (from a negative zero cosine or sine) into 0.\n  const um: LateralColorDisplacement = { radial, x: radial * cos + 0, y: radial * sin + 0 };\n  return approximationResult({ lensId: lens.lensId, imagePointMm: { x, y }, fieldHeight, channelWavelengthsNm: given ? null : { red, blue }, channelDispersion: dispersion,\n    blueMinusRedMicrometers: um, blueMinusRedPixels: { radial: um.radial / pitch, x: um.x / pitch, y: um.y / pitch },\n    fringeWidthMicrometers: Math.abs(radial), fringeWidthPixels: Math.abs(radial) / pitch, fToCMicrometers },\n  \"generic-lens-lateral-color-fringe\", \"1.0.0\", [\n    \"The catalogue lens's lateral-colour model: radial displacement L·R·H·D(λ), D the normalised Cauchy dispersion (Fraunhofer d, F and C lines).\",\n    given ? \"Red and blue at the given channel dispersions (a neutral surface's weighting of each channel's band).\" :\n      \"Red and blue at single effective wavelengths of 610 and 465 nm (GENERIC_LENS_CORRECTION_CHANNEL_WAVELENGTHS_NM); a real channel spans a band.\",\n    \"A generic Photivra lens, not a measured product; lateral colour does not change with the f-number or the focus distance in this model.\",\n    \"Geometric displacement only: the rendered fringe also depends on the lens's blur, the demosaic and the colour conversion.\"]);\n}\n"]}

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

@@ -9,7 +9,8 @@
  * U(x) = Σ_pupil exp(i·2π·W(u)/λ)·exp(−i·2π·x·u/(λ·z)) is evaluated with a zero-padded radix-2 FFT (Cooley & Tukey 1965) on
  * an image grid of pitch δ = min(λ·N_w/2, p/4) (p the site pitch), and |U|² is integrated over each site's square cell (exact
  * overlap of each δ-square with the cell). Lateral colour displaces the PSF radially by Δr(λ). The kernel window is (2R + 1)²
- * sites; the energy outside it is reported and put back by unit-sum renormalisation, as for `lens.diffraction`.
+ * sites; the energy outside it is reported and put back by unit-sum renormalisation, as for `lens.diffraction`. Each kernel's
+ * centroid is then moved onto the PSF's own first moment (#589, `alignKernelCentroid`): the lateral colour and coma's mean tilt.
  *
  * Nodes: a 5 × 5 regular grid of field points (0, ±half the frame, ±the frame edge plus the kernel reach) × 5 wavelengths
  * (380, 450, 550, 650, 780 nm), each computed at its own field azimuth (no rotation of a radial node), interpolated by the
@@ -21,7 +22,7 @@
  */
 import { InvalidScientificInputError } from "../core/validation.js";
 import { genericLensDispersion } from "../equipment/generic-lens-catalogue.js";
-import { markEngineOwnedLensSampledPsfProfile } from "./lens-psf-profile.js";
+import { kernelCentroid, markEngineOwnedLensSampledPsfProfile } from "./lens-psf-profile.js";
 import { convolveSiteKernels } from "./defocus-disc-kernel.js";
 import { createDefocusBokehSiteKernel } from "./defocus-bokeh-kernel.js";
 /** Wavelength nodes of a catalogue PSF profile, nm (they span the facade's 380–780 nm quadrature). */
@@ -106,12 +107,35 @@ function geometricRadiusMicrometers(lens, H, lambdaUm, workingF) {
             const px = -1 + 2 * i / (n - 1), py = -1 + 2 * j / (n - 1);
             if (px * px + py * py > 1)
                 continue;
-            const gx = (opdMicrometers(lens, H, 1, 0, lambdaUm, px + h, py) - opdMicrometers(lens, H, 1, 0, lambdaUm, px - h, py)) / (2 * h);
-            const gy = (opdMicrometers(lens, H, 1, 0, lambdaUm, px, py + h) - opdMicrometers(lens, H, 1, 0, lambdaUm, px, py - h)) / (2 * h);
-            largest = Math.max(largest, Math.hypot(gx, gy));
+            const slope = (dx, dy) => (opdMicrometers(lens, H, 1, 0, lambdaUm, px + dx, py + dy) - opdMicrometers(lens, H, 1, 0, lambdaUm, px - dx, py - dy)) / (2 * h);
+            largest = Math.max(largest, Math.hypot(slope(h, 0), slope(0, h)));
         }
     return 2 * workingF * largest;
 }
+/**
+ * #589: moves a unit-sum kernel's intensity centroid to `target` (sites from the centre tap, +x right, +y up = the row index), each
+ * axis by a linear-interpolation shift of the whole kernel; energy that would leave the window stays on its edge tap, so the shift
+ * repeats (at most 8 passes per axis) while that leaves a residual. Cell integration alone quantises the centroid of a PSF narrower than a
+ * site, and the window's truncation pulls a wide one inwards: either moves the rendered lateral colour and coma off the lens's
+ * model. The shift keeps the sum and the other axis's moment, and widens the kernel by f·(1 − f) site² of variance for a move of f.
+ */
+function alignKernelCentroid(kernel, radius, target) {
+    const w = 2 * radius + 1;
+    const shape = { widthSamples: w, heightSamples: w, centerSampleX: radius, centerSampleY: radius, normalizedIntensity: kernel };
+    for (let axis = 0; axis < 2; axis++)
+        for (let pass = 0; pass < 8; pass++) {
+            const c = kernelCentroid(shape), r = axis ? target.y - c.y : target.x - c.x, whole = Math.floor(r), f = r - whole, moved = new Float64Array(kernel.length);
+            if (Math.abs(r) < 1e-9)
+                break;
+            kernel.forEach((v, k) => {
+                // Tap k's index t along the axis moves to t + whole and t + whole + 1, held at the window's edges.
+                const t = axis ? Math.floor(k / w) : k % w, step = axis ? w : 1;
+                moved[k + (Math.min(w - 1, Math.max(0, t + whole)) - t) * step] += v * (1 - f);
+                moved[k + (Math.min(w - 1, Math.max(0, t + whole + 1)) - t) * step] += v * f;
+            });
+            kernel.set(moved);
+        }
+}
 function nodeKernel(lens, xMm, yMm, lambdaNm, workingF, pupilDiameterMm, zMm, pitch, radius) {
     const lambdaUm = lambdaNm / 1000, r = Math.hypot(xMm, yMm), H = Math.min(1, r / lens.halfDiagonalMm);
     const cosPhi = r > 0 ? xMm / r : 1, sinPhi = r > 0 ? yMm / r : 0;
@@ -145,17 +169,14 @@ function nodeKernel(lens, xMm, yMm, lambdaNm, workingF, pupilDiameterMm, zMm, pi
                 rowUsed[(v + size) % size] = 1;
                 open++;
             }
+        // The largest step to the next sample in a row and in a column (outside the pupil the OPD is NaN, and so is the step: skipped).
         const width = 2 * reach + 1;
-        for (let j = 0; j < width; j++)
-            for (let i = 0; i < width; i++) {
-                const w = opd[j * width + i];
-                if (Number.isNaN(w))
-                    continue;
-                if (i + 1 < width && !Number.isNaN(opd[j * width + i + 1]))
-                    phaseStep = Math.max(phaseStep, Math.abs(opd[j * width + i + 1] - w) / lambdaUm);
-                if (j + 1 < width && !Number.isNaN(opd[(j + 1) * width + i]))
-                    phaseStep = Math.max(phaseStep, Math.abs(opd[(j + 1) * width + i] - w) / lambdaUm);
-            }
+        for (let k = 0; k < opd.length; k++) {
+            if ((k + 1) % width)
+                phaseStep = Math.max(phaseStep, Math.abs(opd[k + 1] - opd[k]) / lambdaUm || 0);
+            if (k + width < opd.length)
+                phaseStep = Math.max(phaseStep, Math.abs(opd[k + width] - opd[k]) / lambdaUm || 0);
+        }
         if (open < 9)
             throw new InvalidScientificInputError("The catalogue lens PSF pupil has fewer than 9 samples.");
         if (phaseStep > MAXIMUM_PHASE_STEP_WAVES) {
@@ -167,20 +188,13 @@ function nodeKernel(lens, xMm, yMm, lambdaNm, workingF, pupilDiameterMm, zMm, pi
             cos[k] = Math.cos(2 * Math.PI * k / size);
             sin[k] = Math.sin(2 * Math.PI * k / size);
         }
-        const rowRe = new Float64Array(size), rowIm = new Float64Array(size);
-        for (let y = 0; y < size; y++) {
-            if (!rowUsed[y])
-                continue;
-            rowRe.set(re.subarray(y * size, (y + 1) * size));
-            rowIm.set(im.subarray(y * size, (y + 1) * size));
-            radix2Fft(rowRe, rowIm, size, cos, sin);
-            re.set(rowRe, y * size);
-            im.set(rowIm, y * size);
-        }
+        for (let y = 0; y < size; y++)
+            if (rowUsed[y])
+                radix2Fft(re.subarray(y * size, (y + 1) * size), im.subarray(y * size, (y + 1) * size), size, cos, sin);
         const colRe = new Float64Array(size), colIm = new Float64Array(size);
         const ox = overlaps(size, delta, shift * cosPhi, pitch, radius), oy = overlaps(size, delta, shift * sinPhi, pitch, radius);
         const w2 = 2 * radius + 1, kernel = new Float64Array(w2 * w2);
-        let total = 0, inside = 0;
+        let total = 0;
         for (let x = 0; x < size; x++) {
             for (let y = 0; y < size; y++) {
                 colRe[y] = re[y * size + x];
@@ -199,33 +213,24 @@ function nodeKernel(lens, xMm, yMm, lambdaNm, workingF, pupilDiameterMm, zMm, pi
                 const cy2 = oy.cell2[y], wy = oy.weight[y], wy2 = oy.weight2[y];
                 // Row index increases with image +Y (the quadrature's orientation).
                 kernel[cy * w2 + cx] += intensity * wx * wy;
-                inside += intensity * wx * wy;
-                if (cx2 >= 0) {
+                if (cx2 >= 0)
                     kernel[cy * w2 + cx2] += intensity * wx2 * wy;
-                    inside += intensity * wx2 * wy;
-                }
                 if (cy2 >= 0) {
                     kernel[cy2 * w2 + cx] += intensity * wx * wy2;
-                    inside += intensity * wx * wy2;
-                    if (cx2 >= 0) {
+                    if (cx2 >= 0)
                         kernel[cy2 * w2 + cx2] += intensity * wx2 * wy2;
-                        inside += intensity * wx2 * wy2;
-                    }
                 }
             }
         }
-        if (!(total > 0) || !(inside > 0))
+        if (!(total > 0) || !kernel.some((v) => v > 0))
             throw new InvalidScientificInputError("The catalogue lens PSF has no energy in its window.");
-        return { kernel, total, transform: size, phaseStep };
+        // #589: the PSF's first moment is the pupil-mean wavefront tilt 2·N_w·⟨∇W⟩ (the Fourier transform's moment theorem; Goodman,
+        // Introduction to Fourier Optics, ch. 4). Of the Seidel terms only coma has a mean tilt, ⟨∇(W131·H·ρ²·ρcos(θ − φ))⟩ = W131·H
+        // along the field azimuth (⟨ρ²⟩ = 1/2, ⟨x²⟩ = 1/4 on the unit disc); the lateral colour adds its displacement. Sites.
+        const moment = (shift + 2 * workingF * DESIGN_WAVELENGTH_UM * lens.character.aberrations.comaWaves * H) / pitch;
+        return { kernel, total, transform: size, phaseStep, centroid: { x: moment * cosPhi, y: moment * sinPhi } };
     }
 }
-function mirror(kernel, radius, flipX, flipY) {
-    const w = 2 * radius + 1, out = new Float64Array(kernel.length);
-    for (let j = 0; j < w; j++)
-        for (let i = 0; i < w; i++)
-            out[(flipY ? w - 1 - j : j) * w + (flipX ? w - 1 - i : i)] = kernel[j * w + i];
-    return out;
-}
 /** Thin-lens image distance z (mm), pupil diameter D = f/N (mm) and working f-number z/D at a finite focus. */
 function pupilGeometry(lens, focusDistanceM) {
     const f = lens.focalLengthMm, d = focusDistanceM * 1000;
@@ -290,17 +295,20 @@ export function createGenericLensPsfProfile(input) {
     while (radius < bound && outside(radius) > GENERIC_LENS_PSF_WINDOW_TRUNCATION)
         radius++;
     const truncated = Math.max(0, outside(radius));
-    const crop = (node) => {
+    /** The node's kernel cropped to the window, unit-sum, mirrored for a field point with x or y < 0. */
+    const crop = (node, flipX, flipY) => {
         const w0 = 2 * bound + 1, w1 = 2 * radius + 1, out = new Float64Array(w1 * w1);
         let sum = 0;
         for (let j = 0; j < w1; j++)
             for (let i = 0; i < w1; i++) {
                 const v = node.kernel[(j + bound - radius) * w0 + i + bound - radius];
-                out[j * w1 + i] = v;
+                out[(flipY ? w1 - 1 - j : j) * w1 + (flipX ? w1 - 1 - i : i)] = v;
                 sum += v;
             }
         for (let k = 0; k < out.length; k++)
             out[k] = out[k] / sum;
+        // #589: the kernel's first moment is the PSF's (lateral colour and coma), not the cells' quantised or truncated one.
+        alignKernelCentroid(out, radius, { x: flipX ? -node.centroid.x : node.centroid.x, y: flipY ? -node.centroid.y : node.centroid.y });
         return out;
     };
     const extra = input.extraKernel, kernelRadius = radius + (extra ? extra.radius : 0), w = 2 * kernelRadius + 1;
@@ -312,7 +320,7 @@ export function createGenericLensPsfProfile(input) {
         for (const y of fieldY)
             for (const nm of GENERIC_LENS_PSF_WAVELENGTHS_NM) {
                 const base = quadrant.get(Math.abs(x) + ":" + Math.abs(y) + ":" + nm);
-                let kernel = mirror(crop(base), radius, x < 0, y < 0);
+                let kernel = crop(base, x < 0, y < 0);
                 if (extra)
                     kernel = convolveSiteKernels(kernel, radius, extra.at(x, y), extra.radius);
                 nodes.push({ nodeId: "pv-" + x.toFixed(6) + "-" + y.toFixed(6) + "-" + nm,