@photivra/engine 1.4.0 → 2.0.0

package/dist/processing/hdr.js

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * HDR from linear RAW brackets and HDR output encoding.
+ *
+ * Merge (`createHdrBracketMergeTask`): for each sample, every frame whose code is below its white level
+ * and not flagged gives an independent estimate of the photo-electron rate Φ (e⁻/s):
+ *   e_k = (code_k − black_k)·K_k,  Φ̂_k = e_k / t_k,
+ *   Var[e_k] = max(Φ, 0)·t_k + σ_read,k² + K_k²/12   (Poisson shot + Gaussian read + uniform quantization,
+ *   the same shot+read variance as `calculateSignalToNoise`, plus the EMVA 1288 quantization term).
+ * The estimates are combined with inverse-variance weights w_k = t_k²/Var[e_k]. This is the
+ * lowest-noise linear combination for a linear camera (Granados et al., CVPR 2010; Hasinoff, Durand &
+ * Freeman, CVPR 2010). The Φ inside the variance is not known in advance. So it starts from the
+ * shot-noise-limited estimate Σe_k/Σt_k and is refined by a fixed number of reweighting passes.
+ * Var[Φ̂] = 1/Σw_k.
+ * - A sample saturated in every frame gets the largest representable rate (a lower bound) and a
+ *   count of 0.
+ * - Inputs must be linear RAW codes. Non-linear inputs (with a camera response curve) are not
+ *   supported, so no Debevec–Malik response recovery is done.
+ * - Works with any per-sample layout (CFA mosaic or RGB).
+ *
+ * Encoding (`createHdrImageEncodingTask`): linear RGB is converted to BT.2020 primaries (matrices from
+ * `resolveRgbColorSpace`) and returned as unclipped float32 linear BT.2020. The PQ and HLG transfer
+ * functions are not part of 2.0 (owner decision, 2026-10-17: their patent holders offer only
+ * licence-on-request declarations; see THIRD_PARTY.md).
+ * @see docs/PROCESSING.md for equations, sources and limits.
+ */
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { InvalidScientificInputError } from "../core/validation.js";
+import { resolveRgbColorSpace } from "../color/rgb-color-spaces.js";
+import { rgbSpaceOf } from "./image-ops.js";
+import { createProcessingTask, finiteRows, maximumWorkingBytes, optionalIntegerIn, processingProvenance, requireEnum, requireFiniteIn, requireImage, requireIntegerIn, requireOptions, PROCESSING_MAX_FRAMES, PROCESSING_MAX_PIXELS } from "./processing-task.js";
+/**
+ * Shortest accepted bracket exposure, 1 ns. Far below any photographic shutter (about 1/32000 s ≈ 3·10⁻⁵ s for
+ * fast electronic shutters), it keeps every merge quantity finite: t² ≥ 10⁻¹⁸ cannot underflow (at 10⁻¹⁷⁰ s it
+ * does, and the weights become 0/0), and the largest rate (white − black)·K/t ≤ 2⁵³ · 10⁹ / 10⁻⁹ ≈ 9·10³³ e⁻/s
+ * stays inside the float32 output range (≈ 3.4·10³⁸).
+ */
+const HDR_MINIMUM_EXPOSURE_TIME_SECONDS = 1e-9;
+/** Largest finite float32. */
+const FLOAT32_MAX = 3.4028234663852886e38;
+/** Noise-optimal merge of linear RAW exposure brackets into a scene-linear photo-electron rate. */
+export function createHdrBracketMergeTask(input, provider) {
+    const r = requireOptions(input, ["sampleCount", "frames", "iterations", "maximumWorkingBytes"], "createHdrBracketMergeTask input");
+    const n = requireIntegerIn(r.sampleCount, "sampleCount", 1, 3 * PROCESSING_MAX_PIXELS);
+    if (!Array.isArray(r.frames) || r.frames.length < 1 || r.frames.length > PROCESSING_MAX_FRAMES) {
+        throw new InvalidConfigurationError("frames must contain 1 to " + PROCESSING_MAX_FRAMES + " brackets.");
+    }
+    const frames = r.frames.map((value, i) => {
+        const f = requireOptions(value, ["exposureTimeSeconds", "codes", "blackLevelCode", "whiteLevelCode", "saturationFlags",
+            "conversionGainElectronsPerCode", "readNoiseElectrons"], "frames[" + i + "]");
+        if (!(f.codes instanceof Uint16Array || f.codes instanceof Float32Array) || f.codes.length !== n) {
+            throw new InvalidConfigurationError("frames[" + i + "].codes must be a Uint16Array or Float32Array of sampleCount codes.");
+        }
+        if (f.saturationFlags !== undefined && (!(f.saturationFlags instanceof Uint8Array) || f.saturationFlags.length !== n)) {
+            throw new InvalidConfigurationError("frames[" + i + "].saturationFlags must be a Uint8Array of sampleCount flags.");
+        }
+        const black = requireFiniteIn(f.blackLevelCode, "frames[" + i + "].blackLevelCode", 0, Number.MAX_SAFE_INTEGER);
+        const white = requireFiniteIn(f.whiteLevelCode, "frames[" + i + "].whiteLevelCode", black, Number.MAX_SAFE_INTEGER, true);
+        const read = requireFiniteIn(f.readNoiseElectrons, "frames[" + i + "].readNoiseElectrons", 0, 1e9);
+        return { t: requireFiniteIn(f.exposureTimeSeconds, "frames[" + i + "].exposureTimeSeconds", HDR_MINIMUM_EXPOSURE_TIME_SECONDS, 1e6), codes: f.codes, black, white,
+            flags: f.saturationFlags ?? null,
+            k: requireFiniteIn(f.conversionGainElectronsPerCode, "frames[" + i + "].conversionGainElectronsPerCode", 0, 1e9, true), read2: read * read };
+    });
+    const iterations = optionalIntegerIn(r.iterations, 2, "iterations", 0, 16);
+    // Saturated everywhere: the largest representable rate of any frame is a lower bound.
+    const ceiling = Math.max(...frames.map((f) => (f.white - f.black) * f.k / f.t));
+    const rows = Math.ceil(n / 4096);
+    return createProcessingTask({
+        provider, totalTileCount: rows * (frames.length + 1), estimatedWorkingBytes: n * 9, maximumWorkingBytes: maximumWorkingBytes(r.maximumWorkingBytes),
+        body: function* () {
+            for (const [i, f] of frames.entries())
+                for (let row = 0; row < rows; row++) {
+                    for (let j = row * 4096, end = Math.min(n, j + 4096); j < end; j++) {
+                        if (!Number.isFinite(f.codes[j]))
+                            throw new InvalidScientificInputError("frames[" + i + "].codes must be finite.");
+                    }
+                    yield;
+                }
+            const rate = new Float32Array(n), sd = new Float32Array(n), count = new Uint8Array(n);
+            let allSaturated = 0;
+            for (let row = 0; row < rows; row++) {
+                for (let j = row * 4096, end = Math.min(n, j + 4096); j < end; j++) {
+                    let sumE = 0, sumT = 0, used = 0;
+                    for (const f of frames) {
+                        const code = f.codes[j];
+                        if (code >= f.white || (f.flags !== null && f.flags[j] !== 0))
+                            continue;
+                        sumE += (code - f.black) * f.k;
+                        sumT += f.t;
+                        used++;
+                    }
+                    if (used === 0) {
+                        rate[j] = ceiling;
+                        sd[j] = 0;
+                        allSaturated++;
+                        continue;
+                    }
+                    let phi = sumE / sumT, weightSum = 0;
+                    // Pass `it` weights by the current Φ. Passes 1..iterations update Φ; the last pass also gives Var[Φ̂].
+                    for (let it = 0; it <= iterations; it++) {
+                        let num = 0;
+                        weightSum = 0;
+                        for (const f of frames) {
+                            const code = f.codes[j];
+                            if (code >= f.white || (f.flags !== null && f.flags[j] !== 0))
+                                continue;
+                            const variance = Math.max(phi, 0) * f.t + f.read2 + f.k * f.k / 12, w = f.t * f.t / variance;
+                            num += w * ((code - f.black) * f.k / f.t);
+                            weightSum += w;
+                        }
+                        if (it < iterations)
+                            phi = num / weightSum;
+                    }
+                    const deviation = Math.sqrt(1 / weightSum);
+                    // Fail closed rather than store NaN or ±Infinity (for example with a near-zero conversion gain).
+                    if (!(Math.abs(phi) <= FLOAT32_MAX) || !(deviation <= FLOAT32_MAX)) {
+                        throw new InvalidScientificInputError("HDR merge gives a non-finite rate at sample " + j + "; check exposure times, conversion gains and read noise.");
+                    }
+                    rate[j] = phi;
+                    sd[j] = deviation;
+                    count[j] = used;
+                }
+                yield;
+            }
+            return { radianceElectronsPerSecond: rate, standardDeviationElectronsPerSecond: sd, contributingFrameCount: count, saturatedInAllFramesCount: allSaturated,
+                provenance: processingProvenance("hdr-linear-raw-bracket-merge-inverse-variance", [
+                    "Linear RAW only: Phi_k = (code - black)K/t per unsaturated, unflagged frame.",
+                    "Inverse-variance weights t^2/(Phi t + read^2 + K^2/12) (Granados et al. 2010; Hasinoff et al. 2010), Phi refined by fixed reweighting iterations.",
+                    "Dark current, fixed-pattern noise and inter-frame motion are not modelled; frames must be registered.",
+                    "Samples saturated in all frames carry the largest representable rate as a lower bound."
+                ]) };
+        }
+    });
+}
+/** Converts linear RGB to unclipped float32 linear BT.2020 (relative values, no transfer function or quantization). */
+export function createHdrImageEncodingTask(input, provider) {
+    const r = requireOptions(input, ["image", "inputColorSpace", "transfer", "maximumWorkingBytes"], "createHdrImageEncodingTask input");
+    const image = requireImage(r.image, "image");
+    const space = requireEnum(r.inputColorSpace, ["linear-srgb-d65", "linear-display-p3-d65", "linear-rec2020-d65"], "inputColorSpace");
+    const transfer = requireEnum(r.transfer, ["linear-float32"], "transfer");
+    const src = resolveRgbColorSpace(rgbSpaceOf(space)).value, dst = resolveRgbColorSpace("rec2020").value;
+    const m = [0, 1, 2].map((i) => [0, 1, 2].map((j) => dst.xyzToRgb[i][0] * src.rgbToXyz[0][j] + dst.xyzToRgb[i][1] * src.rgbToXyz[1][j] +
+        dst.xyzToRgb[i][2] * src.rgbToXyz[2][j]));
+    if (space === "linear-rec2020-d65")
+        for (let i = 0; i < 3; i++)
+            for (let j = 0; j < 3; j++)
+                m[i][j] = i === j ? 1 : 0;
+    const samples = image.width * image.height * 3;
+    return createProcessingTask({
+        provider, totalTileCount: 2 * image.height, estimatedWorkingBytes: samples * 4,
+        maximumWorkingBytes: maximumWorkingBytes(r.maximumWorkingBytes),
+        body: function* () {
+            yield* finiteRows(image.data, image.width, image.height, 3, "image");
+            const linear = new Float32Array(samples);
+            const d = image.data, stride = image.width * 3;
+            for (let y = 0; y < image.height; y++) {
+                for (let i = y * stride; i < (y + 1) * stride; i += 3) {
+                    const a = d[i], b = d[i + 1], c = d[i + 2];
+                    for (let k = 0; k < 3; k++)
+                        linear[i + k] = m[k][0] * a + m[k][1] * b + m[k][2] * c;
+                }
+                yield;
+            }
+            return { width: image.width, height: image.height, colorSpace: "rec2020", transfer, linear,
+                provenance: processingProvenance("hdr-linear-rec2020-output", [
+                    "Linear input converted to BT.2020 primaries through XYZ with matrices derived from the published primaries and D65 (ITU-R BT.2020-2; method as in W3C CSS Color 4).",
+                    "Unclipped float32 linear BT.2020; no transfer function or quantization."
+                ]) };
+        }
+    });
+}
+//# sourceMappingURL=hdr.js.map

package/dist/processing/hdr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hdr.js","sourceRoot":"","sources":["../../src/processing/hdr.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * HDR from linear RAW brackets and HDR output encoding.\n *\n * Merge (`createHdrBracketMergeTask`): for each sample, every frame whose code is below its white level\n * and not flagged gives an independent estimate of the photo-electron rate Φ (e⁻/s):\n *   e_k = (code_k − black_k)·K_k,  Φ̂_k = e_k / t_k,\n *   Var[e_k] = max(Φ, 0)·t_k + σ_read,k² + K_k²/12   (Poisson shot + Gaussian read + uniform quantization,\n *   the same shot+read variance as `calculateSignalToNoise`, plus the EMVA 1288 quantization term).\n * The estimates are combined with inverse-variance weights w_k = t_k²/Var[e_k]. This is the\n * lowest-noise linear combination for a linear camera (Granados et al., CVPR 2010; Hasinoff, Durand &\n * Freeman, CVPR 2010). The Φ inside the variance is not known in advance. So it starts from the\n * shot-noise-limited estimate Σe_k/Σt_k and is refined by a fixed number of reweighting passes.\n * Var[Φ̂] = 1/Σw_k.\n * - A sample saturated in every frame gets the largest representable rate (a lower bound) and a\n *   count of 0.\n * - Inputs must be linear RAW codes. Non-linear inputs (with a camera response curve) are not\n *   supported, so no Debevec–Malik response recovery is done.\n * - Works with any per-sample layout (CFA mosaic or RGB).\n *\n * Encoding (`createHdrImageEncodingTask`): linear RGB is converted to BT.2020 primaries (matrices from\n * `resolveRgbColorSpace`) and returned as unclipped float32 linear BT.2020. The PQ and HLG transfer\n * functions are not part of 2.0 (owner decision, 2026-10-17: their patent holders offer only\n * licence-on-request declarations; see THIRD_PARTY.md).\n * @see docs/PROCESSING.md for equations, sources and limits.\n */\n\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\nimport { InvalidScientificInputError } from \"../core/validation.js\";\nimport { resolveRgbColorSpace } from \"../color/rgb-color-spaces.js\";\nimport { rgbSpaceOf } from \"./image-ops.js\";\nimport {\n  createProcessingTask, finiteRows, maximumWorkingBytes, optionalIntegerIn, processingProvenance, requireEnum, requireFiniteIn,\n  requireImage, requireIntegerIn, requireOptions, PROCESSING_MAX_FRAMES, PROCESSING_MAX_PIXELS,\n  type ProcessingBody, type ProcessingLinearColorSpace, type ProcessingProvenance, type ProcessingProvider, type ProcessingRgbImage, type ProcessingTask\n} from \"./processing-task.js\";\n\nexport interface HdrBracketFrame {\n  exposureTimeSeconds: number;\n  /** Linear RAW codes, one per sample. */\n  codes: Uint16Array | Float32Array;\n  blackLevelCode: number;\n  /** Codes at or above this level are saturated and excluded. */\n  whiteLevelCode: number;\n  /** Optional per-sample flags. Non-zero excludes the sample (for example physical saturation before the ADC). */\n  saturationFlags?: Uint8Array;\n  /** System conversion gain K, electrons per code (includes the frame's ISO gain). */\n  conversionGainElectronsPerCode: number;\n  /** RMS read noise in electrons for this frame's readout regime. */\n  readNoiseElectrons: number;\n}\n\nexport interface HdrBracketMergeInput {\n  /** Samples per frame (e.g. width·height for a mosaic, width·height·3 for RGB). */\n  sampleCount: number;\n  frames: readonly HdrBracketFrame[];\n  /** Variance reweighting iterations after the shot-noise-limited start; default 2. */\n  iterations?: number;\n  maximumWorkingBytes?: number;\n}\n\nexport interface HdrBracketMergeOutput {\n  /** Scene-linear photo-electron rate per sample, e⁻/s (relative scene radiance; not absolute). */\n  radianceElectronsPerSecond: Float32Array;\n  /** Model standard deviation of each estimate, e⁻/s. */\n  standardDeviationElectronsPerSecond: Float32Array;\n  /** Frames that contributed; 0 marks a sample saturated in every frame (value is a lower bound). */\n  contributingFrameCount: Uint8Array;\n  saturatedInAllFramesCount: number;\n  provenance: ProcessingProvenance;\n}\n\n/**\n * Shortest accepted bracket exposure, 1 ns. Far below any photographic shutter (about 1/32000 s ≈ 3·10⁻⁵ s for\n * fast electronic shutters), it keeps every merge quantity finite: t² ≥ 10⁻¹⁸ cannot underflow (at 10⁻¹⁷⁰ s it\n * does, and the weights become 0/0), and the largest rate (white − black)·K/t ≤ 2⁵³ · 10⁹ / 10⁻⁹ ≈ 9·10³³ e⁻/s\n * stays inside the float32 output range (≈ 3.4·10³⁸).\n */\nconst HDR_MINIMUM_EXPOSURE_TIME_SECONDS = 1e-9;\n/** Largest finite float32. */\nconst FLOAT32_MAX = 3.4028234663852886e38;\n\ninterface ParsedFrame { t: number; codes: Uint16Array | Float32Array; black: number; white: number; flags: Uint8Array | null; k: number; read2: number }\n\n/** Noise-optimal merge of linear RAW exposure brackets into a scene-linear photo-electron rate. */\nexport function createHdrBracketMergeTask(input: HdrBracketMergeInput, provider: ProcessingProvider): ProcessingTask<HdrBracketMergeOutput> {\n  const r = requireOptions(input, [\"sampleCount\", \"frames\", \"iterations\", \"maximumWorkingBytes\"], \"createHdrBracketMergeTask input\");\n  const n = requireIntegerIn(r.sampleCount, \"sampleCount\", 1, 3 * PROCESSING_MAX_PIXELS);\n  if (!Array.isArray(r.frames) || r.frames.length < 1 || r.frames.length > PROCESSING_MAX_FRAMES) {\n    throw new InvalidConfigurationError(\"frames must contain 1 to \" + PROCESSING_MAX_FRAMES + \" brackets.\");\n  }\n  const frames: ParsedFrame[] = r.frames.map((value: unknown, i: number) => {\n    const f = requireOptions(value, [\"exposureTimeSeconds\", \"codes\", \"blackLevelCode\", \"whiteLevelCode\", \"saturationFlags\",\n      \"conversionGainElectronsPerCode\", \"readNoiseElectrons\"], \"frames[\" + i + \"]\");\n    if (!(f.codes instanceof Uint16Array || f.codes instanceof Float32Array) || f.codes.length !== n) {\n      throw new InvalidConfigurationError(\"frames[\" + i + \"].codes must be a Uint16Array or Float32Array of sampleCount codes.\");\n    }\n    if (f.saturationFlags !== undefined && (!(f.saturationFlags instanceof Uint8Array) || f.saturationFlags.length !== n)) {\n      throw new InvalidConfigurationError(\"frames[\" + i + \"].saturationFlags must be a Uint8Array of sampleCount flags.\");\n    }\n    const black = requireFiniteIn(f.blackLevelCode, \"frames[\" + i + \"].blackLevelCode\", 0, Number.MAX_SAFE_INTEGER);\n    const white = requireFiniteIn(f.whiteLevelCode, \"frames[\" + i + \"].whiteLevelCode\", black, Number.MAX_SAFE_INTEGER, true);\n    const read = requireFiniteIn(f.readNoiseElectrons, \"frames[\" + i + \"].readNoiseElectrons\", 0, 1e9);\n    return { t: requireFiniteIn(f.exposureTimeSeconds, \"frames[\" + i + \"].exposureTimeSeconds\", HDR_MINIMUM_EXPOSURE_TIME_SECONDS, 1e6), codes: f.codes, black, white,\n      flags: (f.saturationFlags as Uint8Array | undefined) ?? null,\n      k: requireFiniteIn(f.conversionGainElectronsPerCode, \"frames[\" + i + \"].conversionGainElectronsPerCode\", 0, 1e9, true), read2: read * read };\n  });\n  const iterations = optionalIntegerIn(r.iterations, 2, \"iterations\", 0, 16);\n  // Saturated everywhere: the largest representable rate of any frame is a lower bound.\n  const ceiling = Math.max(...frames.map((f) => (f.white - f.black) * f.k / f.t));\n  const rows = Math.ceil(n / 4096);\n  return createProcessingTask({\n    provider, totalTileCount: rows * (frames.length + 1), estimatedWorkingBytes: n * 9, maximumWorkingBytes: maximumWorkingBytes(r.maximumWorkingBytes),\n    body: function* (): ProcessingBody<HdrBracketMergeOutput> {\n      for (const [i, f] of frames.entries()) for (let row = 0; row < rows; row++) {\n        for (let j = row * 4096, end = Math.min(n, j + 4096); j < end; j++) {\n          if (!Number.isFinite(f.codes[j]!)) throw new InvalidScientificInputError(\"frames[\" + i + \"].codes must be finite.\");\n        }\n        yield;\n      }\n      const rate = new Float32Array(n), sd = new Float32Array(n), count = new Uint8Array(n);\n      let allSaturated = 0;\n      for (let row = 0; row < rows; row++) {\n        for (let j = row * 4096, end = Math.min(n, j + 4096); j < end; j++) {\n          let sumE = 0, sumT = 0, used = 0;\n          for (const f of frames) {\n            const code = f.codes[j]!;\n            if (code >= f.white || (f.flags !== null && f.flags[j] !== 0)) continue;\n            sumE += (code - f.black) * f.k; sumT += f.t; used++;\n          }\n          if (used === 0) { rate[j] = ceiling; sd[j] = 0; allSaturated++; continue; }\n          let phi = sumE / sumT, weightSum = 0;\n          // Pass `it` weights by the current Φ. Passes 1..iterations update Φ; the last pass also gives Var[Φ̂].\n          for (let it = 0; it <= iterations; it++) {\n            let num = 0; weightSum = 0;\n            for (const f of frames) {\n              const code = f.codes[j]!;\n              if (code >= f.white || (f.flags !== null && f.flags[j] !== 0)) continue;\n              const variance = Math.max(phi, 0) * f.t + f.read2 + f.k * f.k / 12, w = f.t * f.t / variance;\n              num += w * ((code - f.black) * f.k / f.t); weightSum += w;\n            }\n            if (it < iterations) phi = num / weightSum;\n          }\n          const deviation = Math.sqrt(1 / weightSum);\n          // Fail closed rather than store NaN or ±Infinity (for example with a near-zero conversion gain).\n          if (!(Math.abs(phi) <= FLOAT32_MAX) || !(deviation <= FLOAT32_MAX)) {\n            throw new InvalidScientificInputError(\"HDR merge gives a non-finite rate at sample \" + j + \"; check exposure times, conversion gains and read noise.\");\n          }\n          rate[j] = phi; sd[j] = deviation; count[j] = used;\n        }\n        yield;\n      }\n      return { radianceElectronsPerSecond: rate, standardDeviationElectronsPerSecond: sd, contributingFrameCount: count, saturatedInAllFramesCount: allSaturated,\n        provenance: processingProvenance(\"hdr-linear-raw-bracket-merge-inverse-variance\", [\n          \"Linear RAW only: Phi_k = (code - black)K/t per unsaturated, unflagged frame.\",\n          \"Inverse-variance weights t^2/(Phi t + read^2 + K^2/12) (Granados et al. 2010; Hasinoff et al. 2010), Phi refined by fixed reweighting iterations.\",\n          \"Dark current, fixed-pattern noise and inter-frame motion are not modelled; frames must be registered.\",\n          \"Samples saturated in all frames carry the largest representable rate as a lower bound.\"]) };\n    }\n  });\n}\n\n// ------------------------------------------------------------------ HDR output encoding\n\n/** The only output transfer in 2.0: unclipped float32 linear values (PQ and HLG are not shipped). */\nexport type HdrTransfer = \"linear-float32\";\n\nexport interface HdrImageEncodingInput {\n  image: ProcessingRgbImage;\n  inputColorSpace: ProcessingLinearColorSpace;\n  transfer: HdrTransfer;\n  maximumWorkingBytes?: number;\n}\n\nexport interface HdrImageEncodingOutput {\n  width: number;\n  height: number;\n  colorSpace: \"rec2020\";\n  transfer: HdrTransfer;\n  /** Interleaved linear BT.2020 RGB (relative, unclipped). */\n  linear: Float32Array;\n  provenance: ProcessingProvenance;\n}\n\n/** Converts linear RGB to unclipped float32 linear BT.2020 (relative values, no transfer function or quantization). */\nexport function createHdrImageEncodingTask(input: HdrImageEncodingInput, provider: ProcessingProvider): ProcessingTask<HdrImageEncodingOutput> {\n  const r = requireOptions(input, [\"image\", \"inputColorSpace\", \"transfer\", \"maximumWorkingBytes\"], \"createHdrImageEncodingTask input\");\n  const image = requireImage(r.image, \"image\");\n  const space = requireEnum(r.inputColorSpace, [\"linear-srgb-d65\", \"linear-display-p3-d65\", \"linear-rec2020-d65\"] as const, \"inputColorSpace\");\n  const transfer = requireEnum(r.transfer, [\"linear-float32\"] as const, \"transfer\");\n  const src = resolveRgbColorSpace(rgbSpaceOf(space)).value, dst = resolveRgbColorSpace(\"rec2020\").value;\n  const m = [0, 1, 2].map((i) => [0, 1, 2].map((j) => dst.xyzToRgb[i]![0] * src.rgbToXyz[0][j]! + dst.xyzToRgb[i]![1] * src.rgbToXyz[1][j]! +\n    dst.xyzToRgb[i]![2] * src.rgbToXyz[2][j]!));\n  if (space === \"linear-rec2020-d65\") for (let i = 0; i < 3; i++) for (let j = 0; j < 3; j++) m[i]![j] = i === j ? 1 : 0;\n  const samples = image.width * image.height * 3;\n  return createProcessingTask({\n    provider, totalTileCount: 2 * image.height, estimatedWorkingBytes: samples * 4,\n    maximumWorkingBytes: maximumWorkingBytes(r.maximumWorkingBytes),\n    body: function* (): ProcessingBody<HdrImageEncodingOutput> {\n      yield* finiteRows(image.data, image.width, image.height, 3, \"image\");\n      const linear = new Float32Array(samples);\n      const d = image.data, stride = image.width * 3;\n      for (let y = 0; y < image.height; y++) {\n        for (let i = y * stride; i < (y + 1) * stride; i += 3) {\n          const a = d[i]!, b = d[i + 1]!, c = d[i + 2]!;\n          for (let k = 0; k < 3; k++) linear[i + k] = m[k]![0]! * a + m[k]![1]! * b + m[k]![2]! * c;\n        }\n        yield;\n      }\n      return { width: image.width, height: image.height, colorSpace: \"rec2020\", transfer, linear,\n        provenance: processingProvenance(\"hdr-linear-rec2020-output\", [\n          \"Linear input converted to BT.2020 primaries through XYZ with matrices derived from the published primaries and D65 (ITU-R BT.2020-2; method as in W3C CSS Color 4).\",\n          \"Unclipped float32 linear BT.2020; no transfer function or quantization.\"]) };\n    }\n  });\n}\n"]}

package/dist/processing/image-ops.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Internal image operations on typed arrays, shared by the processing operators. Not exported from
+ * the package root.
+ *
+ * Every spatial operation uses symmetric whole-sample (reflect-101) borders, the same mapping as the
+ * RAW mirror border handling. Row generators yield once per output row of each pass. The matching
+ * `*Rows` functions return exactly that count, so task plans know their total in advance.
+ *
+ * Pyramids follow Burt & Adelson (1983):
+ * - REDUCE blurs with the separable 5-tap kernel w = [1, 4, 6, 4, 1]/16 (a = 0.375) and keeps every
+ *   second sample (size ⌈n/2⌉).
+ * - EXPAND upsamples with the same kernel, times two per axis.
+ * - A Laplacian level is G_l − EXPAND(G_{l+1}). Collapsing with the same EXPAND rebuilds G_0 exactly,
+ *   up to float32 rounding, whatever the border rule.
+ */
+import { reflectRawSiteIndex as reflect } from "../sensor/raw-reconstruction.js";
+import type { ProcessingBody, ProcessingLinearColorSpace } from "./processing-task.js";
+import { type RgbColorSpaceId } from "../color/rgb-color-spaces.js";
+export { reflect };
+/** Normalized 1-D Gaussian taps for standard deviation σ (pixels), truncated at ⌈3σ⌉; σ = 0 → [1]. */
+export declare function gaussianKernel(sigma: number): Float64Array;
+/** Rows yielded by `convolveSeparable`. */
+export declare const convolveRows: (height: number) => number;
+/** Separable convolution of a `channels`-interleaved plane with a symmetric kernel; `tmp` and `dst` have the source length. */
+export declare function convolveSeparable(src: Float32Array, width: number, height: number, channels: number, kernel: Float64Array, tmp: Float32Array, dst: Float32Array): ProcessingBody<void>;
+/** Size of the next coarser pyramid level. */
+export declare const half: (n: number) => number;
+/** Level dimensions for `levels` levels starting at (width, height). */
+export declare function levelSizes(width: number, height: number, levels: number): {
+    width: number;
+    height: number;
+}[];
+/** Automatic level count: halve until the smaller side is 1 (at most `cap`). */
+export declare function autoLevels(width: number, height: number, cap: number): number;
+export declare const reduceRows: (height: number) => number;
+/** REDUCE: blur with the Burt–Adelson kernel and keep even samples. */
+export declare function reduce(src: Float32Array, width: number, height: number, channels: number, dst: Float32Array): ProcessingBody<void>;
+export declare const expandRows: (coarseHeight: number, height: number) => number;
+/**
+ * EXPAND a (cw × ch) level to (width × height): out(x) = 2 Σ_k w(k) in((x − k)/2) per axis over even
+ * x − k, coarse indices mirrored. `mode` "set" writes, "add" adds, "subtract-from" writes dst − expand.
+ */
+export declare function expand(src: Float32Array, cw: number, ch: number, width: number, height: number, channels: number, dst: Float32Array, mode: "set" | "add" | "subtract-from"): ProcessingBody<void>;
+export interface Pyramid {
+    levels: Float32Array[];
+    sizes: {
+        width: number;
+        height: number;
+    }[];
+    channels: number;
+}
+export declare function gaussianPyramidRows(width: number, height: number, levels: number): number;
+/** Gaussian pyramid; level 0 is a copy of `src`. */
+export declare function gaussianPyramid(src: Float32Array, width: number, height: number, channels: number, levels: number): ProcessingBody<Pyramid>;
+export declare function laplacianPyramidRows(width: number, height: number, levels: number): number;
+/** Laplacian pyramid: L_l = G_l − EXPAND(G_{l+1}); the last level is the coarsest Gaussian level. */
+export declare function laplacianPyramid(src: Float32Array, width: number, height: number, channels: number, levels: number): ProcessingBody<Pyramid>;
+export declare function collapseRows(width: number, height: number, levels: number): number;
+/** Collapses a Laplacian pyramid in place (level 0 becomes the image). */
+export declare function collapse(p: Pyramid): ProcessingBody<Float32Array>;
+/** Bytes of a pyramid of `levels` levels for float32 storage. */
+export declare function pyramidBytes(width: number, height: number, channels: number, levels: number): number;
+/** Named colour space of a processing linear space. */
+export declare function rgbSpaceOf(space: ProcessingLinearColorSpace): RgbColorSpaceId;
+/** Luminance weights: the Y row of the space's RGB→XYZ matrix (derived from primaries and white, white Y = 1). */
+export declare function luminanceWeights(space: ProcessingLinearColorSpace): readonly [number, number, number];

package/dist/processing/image-ops.js

@@ -0,0 +1,192 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Internal image operations on typed arrays, shared by the processing operators. Not exported from
+ * the package root.
+ *
+ * Every spatial operation uses symmetric whole-sample (reflect-101) borders, the same mapping as the
+ * RAW mirror border handling. Row generators yield once per output row of each pass. The matching
+ * `*Rows` functions return exactly that count, so task plans know their total in advance.
+ *
+ * Pyramids follow Burt & Adelson (1983):
+ * - REDUCE blurs with the separable 5-tap kernel w = [1, 4, 6, 4, 1]/16 (a = 0.375) and keeps every
+ *   second sample (size ⌈n/2⌉).
+ * - EXPAND upsamples with the same kernel, times two per axis.
+ * - A Laplacian level is G_l − EXPAND(G_{l+1}). Collapsing with the same EXPAND rebuilds G_0 exactly,
+ *   up to float32 rounding, whatever the border rule.
+ */
+import { reflectRawSiteIndex as reflect } from "../sensor/raw-reconstruction.js";
+import { resolveRgbColorSpace } from "../color/rgb-color-spaces.js";
+export { reflect };
+/** Normalized 1-D Gaussian taps for standard deviation σ (pixels), truncated at ⌈3σ⌉; σ = 0 → [1]. */
+export function gaussianKernel(sigma) {
+    if (sigma === 0)
+        return Float64Array.of(1);
+    const radius = Math.max(1, Math.ceil(3 * sigma)), k = new Float64Array(2 * radius + 1);
+    let sum = 0;
+    for (let i = -radius; i <= radius; i++)
+        sum += (k[i + radius] = Math.exp(-(i * i) / (2 * sigma * sigma)));
+    for (let i = 0; i < k.length; i++)
+        k[i] = k[i] / sum;
+    return k;
+}
+/** Rows yielded by `convolveSeparable`. */
+export const convolveRows = (height) => 2 * height;
+/** Separable convolution of a `channels`-interleaved plane with a symmetric kernel; `tmp` and `dst` have the source length. */
+export function* convolveSeparable(src, width, height, channels, kernel, tmp, dst) {
+    const r = (kernel.length - 1) / 2, stride = width * channels;
+    for (let y = 0; y < height; y++) {
+        const row = y * stride;
+        for (let x = 0; x < width; x++)
+            for (let c = 0; c < channels; c++) {
+                let s = 0;
+                for (let k = -r; k <= r; k++)
+                    s += kernel[k + r] * src[row + reflect(x + k, width) * channels + c];
+                tmp[row + x * channels + c] = s;
+            }
+        yield;
+    }
+    for (let y = 0; y < height; y++) {
+        const row = y * stride;
+        for (let k = -r; k <= r; k++) {
+            const w = kernel[k + r], from = reflect(y + k, height) * stride;
+            if (k === -r)
+                for (let i = 0; i < stride; i++)
+                    dst[row + i] = w * tmp[from + i];
+            else
+                for (let i = 0; i < stride; i++)
+                    dst[row + i] = dst[row + i] + w * tmp[from + i];
+        }
+        yield;
+    }
+}
+const BURT = [0.0625, 0.25, 0.375, 0.25, 0.0625];
+/** Size of the next coarser pyramid level. */
+export const half = (n) => Math.ceil(n / 2);
+/** Level dimensions for `levels` levels starting at (width, height). */
+export function levelSizes(width, height, levels) {
+    const out = [{ width, height }];
+    for (let l = 1; l < levels; l++)
+        out.push({ width: half(out[l - 1].width), height: half(out[l - 1].height) });
+    return out;
+}
+/** Automatic level count: halve until the smaller side is 1 (at most `cap`). */
+export function autoLevels(width, height, cap) {
+    return Math.min(cap, 1 + Math.floor(Math.log2(Math.min(width, height))));
+}
+export const reduceRows = (height) => height + half(height);
+/** REDUCE: blur with the Burt–Adelson kernel and keep even samples. */
+export function* reduce(src, width, height, channels, dst) {
+    const w2 = half(width), h2 = half(height), tmp = new Float32Array(w2 * height * channels);
+    for (let y = 0; y < height; y++) {
+        const row = y * width * channels, out = y * w2 * channels;
+        for (let x = 0; x < w2; x++)
+            for (let c = 0; c < channels; c++) {
+                let s = 0;
+                for (let k = -2; k <= 2; k++)
+                    s += BURT[k + 2] * src[row + reflect(2 * x + k, width) * channels + c];
+                tmp[out + x * channels + c] = s;
+            }
+        yield;
+    }
+    const stride = w2 * channels;
+    for (let y = 0; y < h2; y++) {
+        for (let i = 0; i < stride; i++) {
+            let s = 0;
+            for (let k = -2; k <= 2; k++)
+                s += BURT[k + 2] * tmp[reflect(2 * y + k, height) * stride + i];
+            dst[y * stride + i] = s;
+        }
+        yield;
+    }
+}
+export const expandRows = (coarseHeight, height) => coarseHeight + height;
+/**
+ * EXPAND a (cw × ch) level to (width × height): out(x) = 2 Σ_k w(k) in((x − k)/2) per axis over even
+ * x − k, coarse indices mirrored. `mode` "set" writes, "add" adds, "subtract-from" writes dst − expand.
+ */
+export function* expand(src, cw, ch, width, height, channels, dst, mode) {
+    const tmp = new Float32Array(width * ch * channels);
+    for (let y = 0; y < ch; y++) {
+        const row = y * cw * channels, out = y * width * channels;
+        for (let x = 0; x < width; x++)
+            for (let c = 0; c < channels; c++) {
+                let s = 0;
+                for (let k = -2; k <= 2; k++)
+                    if (((x - k) & 1) === 0)
+                        s += BURT[k + 2] * src[row + reflect((x - k) / 2, cw) * channels + c];
+                tmp[out + x * channels + c] = 2 * s;
+            }
+        yield;
+    }
+    const stride = width * channels;
+    for (let y = 0; y < height; y++) {
+        const at = y * stride;
+        for (let i = 0; i < stride; i++) {
+            let s = 0;
+            for (let k = -2; k <= 2; k++)
+                if (((y - k) & 1) === 0)
+                    s += BURT[k + 2] * tmp[reflect((y - k) / 2, ch) * stride + i];
+            const v = 2 * s;
+            dst[at + i] = mode === "set" ? v : mode === "add" ? dst[at + i] + v : dst[at + i] - v;
+        }
+        yield;
+    }
+}
+export function gaussianPyramidRows(width, height, levels) {
+    return levelSizes(width, height, levels).slice(0, -1).reduce((s, l) => s + reduceRows(l.height), 0);
+}
+/** Gaussian pyramid; level 0 is a copy of `src`. */
+export function* gaussianPyramid(src, width, height, channels, levels) {
+    const sizes = levelSizes(width, height, levels), out = [src.slice()];
+    for (let l = 1; l < levels; l++) {
+        const s = sizes[l], dst = new Float32Array(s.width * s.height * channels);
+        yield* reduce(out[l - 1], sizes[l - 1].width, sizes[l - 1].height, channels, dst);
+        out.push(dst);
+    }
+    return { levels: out, sizes, channels };
+}
+export function laplacianPyramidRows(width, height, levels) {
+    const sizes = levelSizes(width, height, levels);
+    let rows = gaussianPyramidRows(width, height, levels);
+    for (let l = 0; l < levels - 1; l++)
+        rows += expandRows(sizes[l + 1].height, sizes[l].height);
+    return rows;
+}
+/** Laplacian pyramid: L_l = G_l − EXPAND(G_{l+1}); the last level is the coarsest Gaussian level. */
+export function* laplacianPyramid(src, width, height, channels, levels) {
+    const g = yield* gaussianPyramid(src, width, height, channels, levels);
+    for (let l = 0; l < levels - 1; l++) {
+        const a = g.sizes[l], b = g.sizes[l + 1];
+        yield* expand(g.levels[l + 1], b.width, b.height, a.width, a.height, channels, g.levels[l], "subtract-from");
+    }
+    return g;
+}
+export function collapseRows(width, height, levels) {
+    const sizes = levelSizes(width, height, levels);
+    let rows = 0;
+    for (let l = 0; l < levels - 1; l++)
+        rows += expandRows(sizes[l + 1].height, sizes[l].height);
+    return rows;
+}
+/** Collapses a Laplacian pyramid in place (level 0 becomes the image). */
+export function* collapse(p) {
+    for (let l = p.levels.length - 2; l >= 0; l--) {
+        const a = p.sizes[l], b = p.sizes[l + 1];
+        yield* expand(p.levels[l + 1], b.width, b.height, a.width, a.height, p.channels, p.levels[l], "add");
+    }
+    return p.levels[0];
+}
+/** Bytes of a pyramid of `levels` levels for float32 storage. */
+export function pyramidBytes(width, height, channels, levels) {
+    return levelSizes(width, height, levels).reduce((s, l) => s + l.width * l.height * channels * 4, 0);
+}
+/** Named colour space of a processing linear space. */
+export function rgbSpaceOf(space) {
+    return space === "linear-srgb-d65" ? "srgb" : space === "linear-display-p3-d65" ? "display-p3" : "rec2020";
+}
+/** Luminance weights: the Y row of the space's RGB→XYZ matrix (derived from primaries and white, white Y = 1). */
+export function luminanceWeights(space) {
+    const row = resolveRgbColorSpace(rgbSpaceOf(space)).value.rgbToXyz[1];
+    return [row[0], row[1], row[2]];
+}
+//# sourceMappingURL=image-ops.js.map

package/dist/processing/image-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-ops.js","sourceRoot":"","sources":["../../src/processing/image-ops.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Internal image operations on typed arrays, shared by the processing operators. Not exported from\n * the package root.\n *\n * Every spatial operation uses symmetric whole-sample (reflect-101) borders, the same mapping as the\n * RAW mirror border handling. Row generators yield once per output row of each pass. The matching\n * `*Rows` functions return exactly that count, so task plans know their total in advance.\n *\n * Pyramids follow Burt & Adelson (1983):\n * - REDUCE blurs with the separable 5-tap kernel w = [1, 4, 6, 4, 1]/16 (a = 0.375) and keeps every\n *   second sample (size ⌈n/2⌉).\n * - EXPAND upsamples with the same kernel, times two per axis.\n * - A Laplacian level is G_l − EXPAND(G_{l+1}). Collapsing with the same EXPAND rebuilds G_0 exactly,\n *   up to float32 rounding, whatever the border rule.\n */\n\nimport { reflectRawSiteIndex as reflect } from \"../sensor/raw-reconstruction.js\";\nimport type { ProcessingBody, ProcessingLinearColorSpace } from \"./processing-task.js\";\nimport { resolveRgbColorSpace, type RgbColorSpaceId } from \"../color/rgb-color-spaces.js\";\n\nexport { reflect };\n\n/** Normalized 1-D Gaussian taps for standard deviation σ (pixels), truncated at ⌈3σ⌉; σ = 0 → [1]. */\nexport function gaussianKernel(sigma: number): Float64Array {\n  if (sigma === 0) return Float64Array.of(1);\n  const radius = Math.max(1, Math.ceil(3 * sigma)), k = new Float64Array(2 * radius + 1);\n  let sum = 0;\n  for (let i = -radius; i <= radius; i++) sum += (k[i + radius] = Math.exp(-(i * i) / (2 * sigma * sigma)));\n  for (let i = 0; i < k.length; i++) k[i] = k[i]! / sum;\n  return k;\n}\n\n/** Rows yielded by `convolveSeparable`. */\nexport const convolveRows = (height: number): number => 2 * height;\n\n/** Separable convolution of a `channels`-interleaved plane with a symmetric kernel; `tmp` and `dst` have the source length. */\nexport function* convolveSeparable(src: Float32Array, width: number, height: number, channels: number, kernel: Float64Array,\n  tmp: Float32Array, dst: Float32Array): ProcessingBody<void> {\n  const r = (kernel.length - 1) / 2, stride = width * channels;\n  for (let y = 0; y < height; y++) {\n    const row = y * stride;\n    for (let x = 0; x < width; x++) for (let c = 0; c < channels; c++) {\n      let s = 0;\n      for (let k = -r; k <= r; k++) s += kernel[k + r]! * src[row + reflect(x + k, width) * channels + c]!;\n      tmp[row + x * channels + c] = s;\n    }\n    yield;\n  }\n  for (let y = 0; y < height; y++) {\n    const row = y * stride;\n    for (let k = -r; k <= r; k++) {\n      const w = kernel[k + r]!, from = reflect(y + k, height) * stride;\n      if (k === -r) for (let i = 0; i < stride; i++) dst[row + i] = w * tmp[from + i]!;\n      else for (let i = 0; i < stride; i++) dst[row + i] = dst[row + i]! + w * tmp[from + i]!;\n    }\n    yield;\n  }\n}\n\nconst BURT = [0.0625, 0.25, 0.375, 0.25, 0.0625] as const;\n\n/** Size of the next coarser pyramid level. */\nexport const half = (n: number): number => Math.ceil(n / 2);\n\n/** Level dimensions for `levels` levels starting at (width, height). */\nexport function levelSizes(width: number, height: number, levels: number): { width: number; height: number }[] {\n  const out = [{ width, height }];\n  for (let l = 1; l < levels; l++) out.push({ width: half(out[l - 1]!.width), height: half(out[l - 1]!.height) });\n  return out;\n}\n\n/** Automatic level count: halve until the smaller side is 1 (at most `cap`). */\nexport function autoLevels(width: number, height: number, cap: number): number {\n  return Math.min(cap, 1 + Math.floor(Math.log2(Math.min(width, height))));\n}\n\nexport const reduceRows = (height: number): number => height + half(height);\n/** REDUCE: blur with the Burt–Adelson kernel and keep even samples. */\nexport function* reduce(src: Float32Array, width: number, height: number, channels: number, dst: Float32Array): ProcessingBody<void> {\n  const w2 = half(width), h2 = half(height), tmp = new Float32Array(w2 * height * channels);\n  for (let y = 0; y < height; y++) {\n    const row = y * width * channels, out = y * w2 * channels;\n    for (let x = 0; x < w2; x++) for (let c = 0; c < channels; c++) {\n      let s = 0;\n      for (let k = -2; k <= 2; k++) s += BURT[k + 2]! * src[row + reflect(2 * x + k, width) * channels + c]!;\n      tmp[out + x * channels + c] = s;\n    }\n    yield;\n  }\n  const stride = w2 * channels;\n  for (let y = 0; y < h2; y++) {\n    for (let i = 0; i < stride; i++) {\n      let s = 0;\n      for (let k = -2; k <= 2; k++) s += BURT[k + 2]! * tmp[reflect(2 * y + k, height) * stride + i]!;\n      dst[y * stride + i] = s;\n    }\n    yield;\n  }\n}\n\nexport const expandRows = (coarseHeight: number, height: number): number => coarseHeight + height;\n/**\n * EXPAND a (cw × ch) level to (width × height): out(x) = 2 Σ_k w(k) in((x − k)/2) per axis over even\n * x − k, coarse indices mirrored. `mode` \"set\" writes, \"add\" adds, \"subtract-from\" writes dst − expand.\n */\nexport function* expand(src: Float32Array, cw: number, ch: number, width: number, height: number, channels: number, dst: Float32Array,\n  mode: \"set\" | \"add\" | \"subtract-from\"): ProcessingBody<void> {\n  const tmp = new Float32Array(width * ch * channels);\n  for (let y = 0; y < ch; y++) {\n    const row = y * cw * channels, out = y * width * channels;\n    for (let x = 0; x < width; x++) for (let c = 0; c < channels; c++) {\n      let s = 0;\n      for (let k = -2; k <= 2; k++) if (((x - k) & 1) === 0) s += BURT[k + 2]! * src[row + reflect((x - k) / 2, cw) * channels + c]!;\n      tmp[out + x * channels + c] = 2 * s;\n    }\n    yield;\n  }\n  const stride = width * channels;\n  for (let y = 0; y < height; y++) {\n    const at = y * stride;\n    for (let i = 0; i < stride; i++) {\n      let s = 0;\n      for (let k = -2; k <= 2; k++) if (((y - k) & 1) === 0) s += BURT[k + 2]! * tmp[reflect((y - k) / 2, ch) * stride + i]!;\n      const v = 2 * s;\n      dst[at + i] = mode === \"set\" ? v : mode === \"add\" ? dst[at + i]! + v : dst[at + i]! - v;\n    }\n    yield;\n  }\n}\n\nexport interface Pyramid { levels: Float32Array[]; sizes: { width: number; height: number }[]; channels: number }\n\nexport function gaussianPyramidRows(width: number, height: number, levels: number): number {\n  return levelSizes(width, height, levels).slice(0, -1).reduce((s, l) => s + reduceRows(l.height), 0);\n}\n/** Gaussian pyramid; level 0 is a copy of `src`. */\nexport function* gaussianPyramid(src: Float32Array, width: number, height: number, channels: number, levels: number): ProcessingBody<Pyramid> {\n  const sizes = levelSizes(width, height, levels), out = [src.slice()];\n  for (let l = 1; l < levels; l++) {\n    const s = sizes[l]!, dst = new Float32Array(s.width * s.height * channels);\n    yield* reduce(out[l - 1]!, sizes[l - 1]!.width, sizes[l - 1]!.height, channels, dst);\n    out.push(dst);\n  }\n  return { levels: out, sizes, channels };\n}\n\nexport function laplacianPyramidRows(width: number, height: number, levels: number): number {\n  const sizes = levelSizes(width, height, levels);\n  let rows = gaussianPyramidRows(width, height, levels);\n  for (let l = 0; l < levels - 1; l++) rows += expandRows(sizes[l + 1]!.height, sizes[l]!.height);\n  return rows;\n}\n/** Laplacian pyramid: L_l = G_l − EXPAND(G_{l+1}); the last level is the coarsest Gaussian level. */\nexport function* laplacianPyramid(src: Float32Array, width: number, height: number, channels: number, levels: number): ProcessingBody<Pyramid> {\n  const g = yield* gaussianPyramid(src, width, height, channels, levels);\n  for (let l = 0; l < levels - 1; l++) {\n    const a = g.sizes[l]!, b = g.sizes[l + 1]!;\n    yield* expand(g.levels[l + 1]!, b.width, b.height, a.width, a.height, channels, g.levels[l]!, \"subtract-from\");\n  }\n  return g;\n}\n\nexport function collapseRows(width: number, height: number, levels: number): number {\n  const sizes = levelSizes(width, height, levels);\n  let rows = 0;\n  for (let l = 0; l < levels - 1; l++) rows += expandRows(sizes[l + 1]!.height, sizes[l]!.height);\n  return rows;\n}\n/** Collapses a Laplacian pyramid in place (level 0 becomes the image). */\nexport function* collapse(p: Pyramid): ProcessingBody<Float32Array> {\n  for (let l = p.levels.length - 2; l >= 0; l--) {\n    const a = p.sizes[l]!, b = p.sizes[l + 1]!;\n    yield* expand(p.levels[l + 1]!, b.width, b.height, a.width, a.height, p.channels, p.levels[l]!, \"add\");\n  }\n  return p.levels[0]!;\n}\n\n/** Bytes of a pyramid of `levels` levels for float32 storage. */\nexport function pyramidBytes(width: number, height: number, channels: number, levels: number): number {\n  return levelSizes(width, height, levels).reduce((s, l) => s + l.width * l.height * channels * 4, 0);\n}\n\n/** Named colour space of a processing linear space. */\nexport function rgbSpaceOf(space: ProcessingLinearColorSpace): RgbColorSpaceId {\n  return space === \"linear-srgb-d65\" ? \"srgb\" : space === \"linear-display-p3-d65\" ? \"display-p3\" : \"rec2020\";\n}\n/** Luminance weights: the Y row of the space's RGB→XYZ matrix (derived from primaries and white, white Y = 1). */\nexport function luminanceWeights(space: ProcessingLinearColorSpace): readonly [number, number, number] {\n  const row = resolveRgbColorSpace(rgbSpaceOf(space)).value.rgbToXyz[1];\n  return [row[0], row[1], row[2]];\n}\n"]}

package/dist/processing/panorama.d.ts

@@ -0,0 +1,51 @@
+import { type ProcessingProvenance, type ProcessingProvider, type ProcessingRgbImage, type ProcessingTask } from "./processing-task.js";
+export interface PanoramaFrame {
+    image: ProcessingRgbImage;
+    /** Rectilinear focal length in pixels (same pixel pitch on both axes). */
+    focalLengthPixels: number;
+    /** Principal point in pixel coordinates (pixel centres at i + 0.5); default the image centre. */
+    principalPointPixels?: {
+        x: number;
+        y: number;
+    };
+    /** Camera rotation relative to the reference camera: pitch/yaw/roll radians, engine sign convention. */
+    rotationRad: {
+        pitch: number;
+        yaw: number;
+        roll: number;
+    };
+}
+export interface PanoramaCanvas {
+    projection: "equirectangular" | "cylindrical";
+    width: number;
+    height: number;
+    /** [min, max] longitude θ in radians across the canvas columns (left → right). */
+    longitudeRangeRad: readonly [number, number];
+    /** [min, max] latitude φ in radians (bottom → top); cylindrical rows are linear in tan φ. */
+    latitudeRangeRad: readonly [number, number];
+}
+export interface PanoramaInput {
+    frames: readonly PanoramaFrame[];
+    canvas: PanoramaCanvas;
+    /** Default `feather`. */
+    blending?: "feather" | "multi-band";
+    /** Default `gain` (Brown & Lowe 2007); `none` keeps frame intensities. */
+    exposureCompensation?: "none" | "gain";
+    /** Normalized intensity noise σ_N; default 0.04 (≈ 10/255, the published 8-bit value). */
+    gainNoiseSigma?: number;
+    /** Gain prior σ_g; default 0.1. */
+    gainPriorSigma?: number;
+    /** Multi-band pyramid levels; default min(4, auto). Coarse bands wider than the frame overlap mix
+     * low frequencies that were normalized differently, so keep 2^(levels−1) well below the overlap width. */
+    pyramidLevels?: number;
+    maximumWorkingBytes?: number;
+}
+export interface PanoramaOutput extends ProcessingRgbImage {
+    /** Number of frames covering each canvas pixel; 0 = uncovered (value 0). */
+    coverage: Uint8Array;
+    /** Gain applied to each frame (1 when compensation is off). */
+    gains: readonly number[];
+    provenance: ProcessingProvenance;
+}
+/** Stitches frames with known rotations onto a cylindrical or equirectangular canvas. */
+export declare function createPanoramaTask(input: PanoramaInput, provider: ProcessingProvider): ProcessingTask<PanoramaOutput>;