@photivra/engine 2.7.0 → 2.8.0

package/dist/facade/expected-signal-setup.d.ts

@@ -0,0 +1,65 @@
+import { resolveLensPsfConvolutionKernels } from "../optics/lens-psf-kernels.js";
+import type { DisplayViewExpectedSignalInput } from "./display-view.js";
+type Psf = Parameters<typeof resolveLensPsfConvolutionKernels>[0]["psf"];
+export interface ExpectedSignalSetupInput {
+    nativeWidth: number;
+    nativeHeight: number;
+    /** Frame output width (plane coordinates are 2 / width frame units per site). */
+    width: number;
+    wavelengths: readonly number[];
+    /** Per CFA channel (red, green, blue): expected electrons per unit spectral radiance at each node. */
+    perNode: readonly [Float64Array, Float64Array, Float64Array];
+    /** Pixel-aperture nodes in sites from the site centre (`apertureNodeOffsets(boxSamples)`) and the box sample count. */
+    apertureNodes: readonly {
+        x: number;
+        y: number;
+    }[];
+    boxSamples: number;
+    antiAliasing?: {
+        components: readonly {
+            offsetMicrometers: {
+                x: number;
+                y: number;
+            };
+            normalizedWeight: number;
+        }[];
+    } | undefined;
+    pitch: number;
+    /** Object-space diffraction: the kernel radius, the PSF and its profile wavelengths. */
+    diffraction?: {
+        radius: number;
+        psf: Psf;
+        profileWavelengths: readonly number[];
+    } | undefined;
+    /** Material scenes: the materials (neutral reflectances, or radiance per wavelength), the material lookup and the white radiance. */
+    materials?: {
+        list: readonly ({
+            neutral: number;
+        } | {
+            radiance: (nm: number) => number;
+        })[];
+        materialAt(u: number, v: number): number;
+        whiteRadiance(nm: number): number;
+    } | undefined;
+    radianceAt(u: number, v: number, nm: number): number;
+    imagingArea: {
+        widthMm: number;
+        heightMm: number;
+    };
+    focalLengthMm: number;
+    focusDistanceM: number;
+    subjectDistanceM: number;
+    metresPerFrameUnit: number;
+    /** Prefix of the error messages ("simulateDisplayView", "simulateCapture"). */
+    caller: string;
+}
+/** The query offsets of each site and the expected-signal input (see the module comment). */
+export declare function buildExpectedSignalInput(input: ExpectedSignalSetupInput): {
+    offsets: {
+        x: number;
+        y: number;
+        weight: number;
+    }[];
+    signalInput: DisplayViewExpectedSignalInput;
+};
+export {};

package/dist/facade/expected-signal-setup.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Internal (#394, not exported from the package): the input of the tabulated expected signal (`createDisplayViewExpectedSignal`)
+ * for a resolved `simulateCapture` request, shared by the display view and the capture's tabulated RAW path so both build it
+ * the same way: query offsets of each site, the environment's query points, the diffraction kernels and the scene tables.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { resolveLensPsfConvolutionKernels } from "../optics/lens-psf-kernels.js";
+import { resolveProjectionDistanceMm } from "../motion/camera-rotation.js";
+/** The query offsets of each site and the expected-signal input (see the module comment). */
+export function buildExpectedSignalInput(input) {
+    const { boxSamples, pitch, wavelengths, imagingArea, subjectDistanceM, metresPerFrameUnit } = input;
+    // Query offsets of each site: pixel-aperture nodes minus anti-aliasing split offsets (sites, +x right, +y down), as the environment forms them.
+    const spots = input.antiAliasing ? input.antiAliasing.components : [{ offsetMicrometers: { x: 0, y: 0 }, normalizedWeight: 1 }];
+    const offsets = input.apertureNodes.flatMap((node) => spots.map((c) => ({ x: node.x - c.offsetMicrometers.x / pitch, y: node.y - c.offsetMicrometers.y / pitch,
+        weight: c.normalizedWeight / (boxSamples * boxSamples) })));
+    // Diffraction: the same per-node site kernels as the object-space convolution (createDiffractedPlanarProvider).
+    let kernels;
+    const diffraction = input.diffraction;
+    if (diffraction) {
+        const radius = diffraction.radius;
+        kernels = { radius, perNode: wavelengths.map((wavelengthNm) => {
+                if (!diffraction.profileWavelengths.includes(wavelengthNm))
+                    throw new InvalidConfigurationError(input.caller + ": a spectral node has no diffraction kernel.");
+                const k = resolveLensPsfConvolutionKernels({ schemaVersion: "0.1.0", psf: diffraction.psf, spectralWeights: [{ wavelengthNm, weight: 1 }],
+                    grid: { width: 1, height: 1, sitePitchMicrometers: { x: pitch, y: pitch }, opticalAxisSite: { x: 0.5, y: 0.5 } }, patchWidth: 1, patchHeight: 1, kernelRadius: radius }).value;
+                if (!k.exactSiteSampling || k.kernelRadius !== radius)
+                    throw new InvalidConfigurationError(input.caller + ": diffraction kernels must sample the site pitch exactly.");
+                return Float64Array.from(k.kernels);
+            }) };
+    }
+    // Chart presets and (2.7) caller material scenes take the material path: each material tabulated once per node.
+    const materials = input.materials;
+    const scene = materials ? { kind: "materials", materialAt: materials.materialAt,
+        materials: materials.list.map((m) => ("neutral" in m ? { neutral: m.neutral } : { radiance: Float64Array.from(wavelengths, (nm) => m.radiance(nm)) })),
+        whiteRadiance: Float64Array.from(wavelengths, (nm) => materials.whiteRadiance(nm)) } :
+        { kind: "radiance", radianceAt: input.radianceAt };
+    const channelIndex = (x, y) => ((y & 1) === 0 ? ((x & 1) === 0 ? 0 : 1) : ((x & 1) === 0 ? 1 : 2));
+    // Without diffraction the environment's own query arithmetic (native-environment-lean.ts `geometry`, then the rectilinear
+    // still-camera ray and the planar provider's plane point), so boundary points resolve as in the capture.
+    const projectionDistance = resolveProjectionDistanceMm(input.focalLengthMm, input.focusDistanceM).projectionDistanceMm, siteWidthMm = pitch / 1000;
+    const nodePhases = input.apertureNodes.flatMap((_, index) => spots.map((c) => ({ xPhase: (index % boxSamples + 0.5) / boxSamples, yPhase: (Math.floor(index / boxSamples) + 0.5) / boxSamples,
+        aaX: c.offsetMicrometers.x / 1000, aaY: c.offsetMicrometers.y / 1000 })));
+    const queryPoint = (x, y, o, out) => {
+        const node = nodePhases[o];
+        const centerX = -imagingArea.widthMm / 2 + (pitch / 2 + x * pitch + 0) / 1000, centerY = -imagingArea.heightMm / 2 + (pitch / 2 + y * pitch + 0) / 1000;
+        const sourceX = (centerX - siteWidthMm / 2 + node.xPhase * siteWidthMm) - node.aaX, sourceY = (centerY - siteWidthMm / 2 + node.yPhase * siteWidthMm) - node.aaY;
+        const rx = projectionDistance * (sourceX / projectionDistance), ry = projectionDistance * (-sourceY / projectionDistance);
+        const length = Math.hypot(rx, ry, projectionDistance), t = subjectDistanceM / (projectionDistance / length);
+        out[0] = rx / length * t / metresPerFrameUnit;
+        out[1] = ry / length * t / metresPerFrameUnit;
+    };
+    return { offsets, signalInput: { nativeWidth: input.nativeWidth, nativeHeight: input.nativeHeight, outputWidth: input.width, wavelengthsNm: wavelengths,
+            electronsPerRadiance: input.perNode, offsets, ...(kernels ? { kernels } : { queryPoint }), scene, channelAt: channelIndex } };
+}
+//# sourceMappingURL=expected-signal-setup.js.map

package/dist/facade/expected-signal-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expected-signal-setup.js","sourceRoot":"","sources":["../../src/facade/expected-signal-setup.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Internal (#394, not exported from the package): the input of the tabulated expected signal (`createDisplayViewExpectedSignal`)\n * for a resolved `simulateCapture` request, shared by the display view and the capture's tabulated RAW path so both build it\n * the same way: query offsets of each site, the environment's query points, the diffraction kernels and the scene tables.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { resolveLensPsfConvolutionKernels } from \"../optics/lens-psf-kernels.js\";\nimport { resolveProjectionDistanceMm } from \"../motion/camera-rotation.js\";\nimport type { DisplayViewExpectedSignalInput, DisplayViewScene } from \"./display-view.js\";\n\ntype Psf = Parameters<typeof resolveLensPsfConvolutionKernels>[0][\"psf\"];\n\nexport interface ExpectedSignalSetupInput {\n  nativeWidth: number;\n  nativeHeight: number;\n  /** Frame output width (plane coordinates are 2 / width frame units per site). */\n  width: number;\n  wavelengths: readonly number[];\n  /** Per CFA channel (red, green, blue): expected electrons per unit spectral radiance at each node. */\n  perNode: readonly [Float64Array, Float64Array, Float64Array];\n  /** Pixel-aperture nodes in sites from the site centre (`apertureNodeOffsets(boxSamples)`) and the box sample count. */\n  apertureNodes: readonly { x: number; y: number }[];\n  boxSamples: number;\n  antiAliasing?: { components: readonly { offsetMicrometers: { x: number; y: number }; normalizedWeight: number }[] } | undefined;\n  pitch: number;\n  /** Object-space diffraction: the kernel radius, the PSF and its profile wavelengths. */\n  diffraction?: { radius: number; psf: Psf; profileWavelengths: readonly number[] } | undefined;\n  /** Material scenes: the materials (neutral reflectances, or radiance per wavelength), the material lookup and the white radiance. */\n  materials?: { list: readonly ({ neutral: number } | { radiance: (nm: number) => number })[]; materialAt(u: number, v: number): number; whiteRadiance(nm: number): number } | undefined;\n  radianceAt(u: number, v: number, nm: number): number;\n  imagingArea: { widthMm: number; heightMm: number };\n  focalLengthMm: number;\n  focusDistanceM: number;\n  subjectDistanceM: number;\n  metresPerFrameUnit: number;\n  /** Prefix of the error messages (\"simulateDisplayView\", \"simulateCapture\"). */\n  caller: string;\n}\n\n/** The query offsets of each site and the expected-signal input (see the module comment). */\nexport function buildExpectedSignalInput(input: ExpectedSignalSetupInput): { offsets: { x: number; y: number; weight: number }[]; signalInput: DisplayViewExpectedSignalInput } {\n  const { boxSamples, pitch, wavelengths, imagingArea, subjectDistanceM, metresPerFrameUnit } = input;\n  // Query offsets of each site: pixel-aperture nodes minus anti-aliasing split offsets (sites, +x right, +y down), as the environment forms them.\n  const spots = input.antiAliasing ? input.antiAliasing.components : [{ offsetMicrometers: { x: 0, y: 0 }, normalizedWeight: 1 }];\n  const offsets = input.apertureNodes.flatMap((node) => spots.map((c) => ({ x: node.x - c.offsetMicrometers.x / pitch, y: node.y - c.offsetMicrometers.y / pitch,\n    weight: c.normalizedWeight / (boxSamples * boxSamples) })));\n  // Diffraction: the same per-node site kernels as the object-space convolution (createDiffractedPlanarProvider).\n  let kernels: { radius: number; perNode: Float64Array[] } | undefined;\n  const diffraction = input.diffraction;\n  if (diffraction) {\n    const radius = diffraction.radius;\n    kernels = { radius, perNode: wavelengths.map((wavelengthNm) => {\n      if (!diffraction.profileWavelengths.includes(wavelengthNm)) throw new InvalidConfigurationError(input.caller + \": a spectral node has no diffraction kernel.\");\n      const k = resolveLensPsfConvolutionKernels({ schemaVersion: \"0.1.0\", psf: diffraction.psf, spectralWeights: [{ wavelengthNm, weight: 1 }],\n        grid: { width: 1, height: 1, sitePitchMicrometers: { x: pitch, y: pitch }, opticalAxisSite: { x: 0.5, y: 0.5 } }, patchWidth: 1, patchHeight: 1, kernelRadius: radius }).value;\n      if (!k.exactSiteSampling || k.kernelRadius !== radius) throw new InvalidConfigurationError(input.caller + \": diffraction kernels must sample the site pitch exactly.\");\n      return Float64Array.from(k.kernels);\n    }) };\n  }\n  // Chart presets and (2.7) caller material scenes take the material path: each material tabulated once per node.\n  const materials = input.materials;\n  const scene: DisplayViewScene = materials ? { kind: \"materials\", materialAt: materials.materialAt,\n    materials: materials.list.map((m) => (\"neutral\" in m ? { neutral: m.neutral } : { radiance: Float64Array.from(wavelengths, (nm) => m.radiance(nm)) })),\n    whiteRadiance: Float64Array.from(wavelengths, (nm) => materials.whiteRadiance(nm)) } :\n    { kind: \"radiance\", radianceAt: input.radianceAt };\n  const channelIndex = (x: number, y: number): number => ((y & 1) === 0 ? ((x & 1) === 0 ? 0 : 1) : ((x & 1) === 0 ? 1 : 2));\n  // Without diffraction the environment's own query arithmetic (native-environment-lean.ts `geometry`, then the rectilinear\n  // still-camera ray and the planar provider's plane point), so boundary points resolve as in the capture.\n  const projectionDistance = resolveProjectionDistanceMm(input.focalLengthMm, input.focusDistanceM).projectionDistanceMm, siteWidthMm = pitch / 1000;\n  const nodePhases = input.apertureNodes.flatMap((_, index) => spots.map((c) => ({ xPhase: (index % boxSamples + 0.5) / boxSamples, yPhase: (Math.floor(index / boxSamples) + 0.5) / boxSamples,\n    aaX: c.offsetMicrometers.x / 1000, aaY: c.offsetMicrometers.y / 1000 })));\n  const queryPoint = (x: number, y: number, o: number, out: Float64Array): void => {\n    const node = nodePhases[o]!;\n    const centerX = -imagingArea.widthMm / 2 + (pitch / 2 + x * pitch + 0) / 1000, centerY = -imagingArea.heightMm / 2 + (pitch / 2 + y * pitch + 0) / 1000;\n    const sourceX = (centerX - siteWidthMm / 2 + node.xPhase * siteWidthMm) - node.aaX, sourceY = (centerY - siteWidthMm / 2 + node.yPhase * siteWidthMm) - node.aaY;\n    const rx = projectionDistance * (sourceX / projectionDistance), ry = projectionDistance * (-sourceY / projectionDistance);\n    const length = Math.hypot(rx, ry, projectionDistance), t = subjectDistanceM / (projectionDistance / length);\n    out[0] = rx / length * t / metresPerFrameUnit; out[1] = ry / length * t / metresPerFrameUnit;\n  };\n  return { offsets, signalInput: { nativeWidth: input.nativeWidth, nativeHeight: input.nativeHeight, outputWidth: input.width, wavelengthsNm: wavelengths,\n    electronsPerRadiance: input.perNode, offsets, ...(kernels ? { kernels } : { queryPoint }), scene, channelAt: channelIndex } };\n}\n"]}

package/dist/facade/expected-signal.d.ts

@@ -0,0 +1,83 @@
+/** A query offset from a site centre in sites (+x right, +y down) and its weight (pixel-aperture node × filter spot). */
+export interface DisplayViewQueryOffset {
+    x: number;
+    y: number;
+    weight: number;
+}
+/** Scene access for the expected signal: chart materials (fast tables) or a radiance function. */
+export type DisplayViewScene = {
+    kind: "materials";
+    materialAt(u: number, v: number): number;
+    /** Per material: `{ neutral: reflectance }` (radiance = reflectance × illuminant) or the spectral radiance at each node. */
+    materials: readonly ({
+        neutral: number;
+    } | {
+        radiance: Float64Array;
+    })[];
+    /** Illuminant radiance of a perfect white diffuser at each spectral node: irradianceScale·shape(λ)/π. */
+    whiteRadiance: Float64Array;
+} | {
+    kind: "radiance";
+    radianceAt(u: number, v: number, nm: number): number;
+};
+export interface DisplayViewExpectedSignalInput {
+    nativeWidth: number;
+    nativeHeight: number;
+    /** Frame output width: plane coordinates are 2 / outputWidth frame units per site. */
+    outputWidth: number;
+    /** Spectral nodes and, per CFA channel (red, green, blue), the expected electrons per unit spectral radiance at each node. */
+    wavelengthsNm: readonly number[];
+    electronsPerRadiance: readonly [Float64Array, Float64Array, Float64Array];
+    offsets: readonly DisplayViewQueryOffset[];
+    /** Diffraction: per-node kernels on the site lattice, (2R + 1)² taps in row-major order, out(x) = Σ in(x − t)·K(t). */
+    kernels?: {
+        radius: number;
+        perNode: readonly Float64Array[];
+    };
+    scene: DisplayViewScene;
+    /** CFA channel index (0 red, 1 green, 2 blue) of native site (x, y). */
+    channelAt(x: number, y: number): number;
+    /**
+     * Without diffraction: the plane point (frame units) that the environment queries for offset `o` of native site (x, y),
+     * computed with the environment's own arithmetic, so points that fall exactly on a chart boundary resolve to the same
+     * material as in the capture. With diffraction the facade's object-space convolution uses the lattice formula, as here.
+     */
+    queryPoint?(x: number, y: number, offset: number, out: Float64Array): void;
+}
+/** Expected photo electrons of real native sites. */
+export interface DisplayViewExpectedSignal {
+    /**
+     * Starts a new cache window: native sites [x0, x1) × [y0, y1) that the following `site` calls mostly read. Sites and
+     * scene lookups inside it are computed once; anything outside is computed without caching.
+     */
+    window(x0: number, y0: number, x1: number, y1: number): void;
+    /** Expected photo electrons of native site (x, y) for its own CFA channel (x, y inside the native raster). */
+    site(x: number, y: number): number;
+    /** A cheap classifier value of the scene at plane point (u, v) frame units: the material, or the radiance at one node. */
+    pilot(u: number, v: number): number;
+    /** Scene lookups performed so far (material or radiance queries), for diagnostics. */
+    readonly lookups: number;
+    /**
+     * The chart material that every kernel tap of the last `site` call read, when they all read one material (its value is
+     * then a function of that material and the site's CFA channel only); −1 when unknown or mixed.
+     */
+    readonly uniformMaterial: number;
+    /** Whether `uniformMaterial` is tracked in the current window (otherwise it is not meaningful). */
+    readonly tracksMaterial: boolean;
+    /**
+     * Whether the current window caches its sites: a second `site` call for a site inside the window then returns the stored
+     * value without any work or lookup (#392).
+     */
+    readonly cachesSites: boolean;
+}
+/**
+ * Expected photo electrons per site: μ_c(i, j) = Σ_o w_o Σ_λ A_c(λ) Σ_t K_λ(t)·L(p_o(i, j) − t, λ), where p_o is the
+ * query point of offset o and K the diffraction kernel (a single unit tap without diffraction). This is the sum the
+ * facade's environment chain forms for a still, rectilinear, distortion-free planar scene, where the
+ * radiance-to-irradiance factor is the same at every site (docs/DISPLAY_VIEW.md, "Expected signal").
+ *
+ * With diffraction, offsets that share a fractional shift read one lattice, and their kernels are combined in advance:
+ * C_c(d) = Σ_members w·Σ_λ A_c(λ)·K_λ(t)·L(λ) over the taps t that reach lattice offset d. A neutral material's radiance
+ * is its reflectance times the white radiance, so all neutral materials share one combined kernel per channel.
+ */
+export declare function createDisplayViewExpectedSignal(input: DisplayViewExpectedSignalInput): DisplayViewExpectedSignal;