insomni-plot 0.1.0-alpha.0

package/src/heatmap/types.ts

@@ -0,0 +1,177 @@
+// ---------------------------------------------------------------------------
+// Shared types and helpers used by both the CPU and GPU heatmap renderers.
+// ---------------------------------------------------------------------------
+
+import type { FrameRect } from "insomni";
+import type { ContinuousPalette } from "../colors.ts";
+import type { DataViewport } from "../viewport.ts";
+
+export interface HeatmapSpec<T> {
+  /** Datum → x value (in `xDomain` units). */
+  x: (d: T) => number;
+  /** Datum → y value (in `yDomain` units). */
+  y: (d: T) => number;
+  /** Datum → weight added to its bin. Default: `() => 1`. */
+  weight?: (d: T) => number;
+  /** Grid resolution `[nx, ny]`. */
+  bins: readonly [number, number];
+  /**
+   * Data domain along x. Data outside this range is dropped.
+   * Required unless `viewport` is supplied (in which case the viewport's
+   * visible x domain is used and this field is ignored).
+   */
+  xDomain?: readonly [number, number];
+  /** Data domain along y. See `xDomain`. */
+  yDomain?: readonly [number, number];
+  /**
+   * CSS-pixel rectangle the heatmap paints into.
+   * Required unless `viewport` is supplied (in which case `viewport.frame`
+   * is used and this field is ignored).
+   */
+  frame?: FrameRect;
+  /**
+   * Optional viewport for interactive pan/zoom. When supplied, the heatmap
+   * re-bins on every viewport change against `viewport.visibleXDomain` /
+   * `visibleYDomain`, and paints into `viewport.frame`. Pair with
+   * `bindViewport` to wire mouse / wheel / touch input.
+   */
+  viewport?: DataViewport<number, number>;
+  /** Palette sampled per-cell. */
+  colorMap: ContinuousPalette;
+  /**
+   * Fixed-point divisor used to encode float weights as `atomic<i32>` on the
+   * GPU path. `round(weight * weightScale)` is added per splat. Keep
+   * `|weight| * N * weightScale` inside `i32` range per cell.
+   * Default: `1_000_000`.
+   */
+  weightScale?: number;
+  /**
+   * Output strategy used by CPU-only renderers (e.g. `SVGRenderer`):
+   * - `"rects"`: emit one vector rect per non-empty bin. Best when the grid is
+   *   small and you want an editable/inspectable SVG.
+   * - `"image"`: rasterize bins to a PNG and emit a single `<image>` element.
+   *   Keeps exports small for dense grids.
+   * - `"auto"` (default): pick `"image"` when `nx * ny > 128 * 128`,
+   *   otherwise `"rects"`.
+   */
+  svgExport?: "auto" | "rects" | "image";
+  /**
+   * How cells are sampled when the bin grid is upscaled to `frame`.
+   * - `"nearest"` (default): each cell renders as a crisp rectangle.
+   * - `"linear"`: bilinearly interpolate between cells for a smoothed look.
+   *
+   * Applies to both the GPU path (sprite sampler) and the CPU/SVG `"image"`
+   * path (CSS `image-rendering`). Has no effect on the `"rects"` SVG export.
+   */
+  interpolation?: "nearest" | "linear";
+  /**
+   * Per-cell value transform applied before color sampling. Default `"max"`
+   * — divide each bin by the grid's max so the palette spans `[0, 1]`.
+   * `"log"` and `"sqrt"` compress dynamic range so isolated hotspots don't
+   * wash out the rest of the field.
+   */
+  normalize?: "max" | "log" | "sqrt";
+}
+
+export interface ResolvedSpec<T> {
+  x: (d: T) => number;
+  y: (d: T) => number;
+  weight: (d: T) => number;
+  nx: number;
+  ny: number;
+  /** Current binning domain. Overwritten from `viewport` each build if present. */
+  x0: number;
+  x1: number;
+  y0: number;
+  y1: number;
+  /** Current output rect. Overwritten from `viewport.frame` each build if present. */
+  frame: FrameRect;
+  viewport: DataViewport<number, number> | null;
+  colorMap: ContinuousPalette;
+  weightScale: number;
+  svgExport: "auto" | "rects" | "image";
+  interpolation: "nearest" | "linear";
+  normalize: "max" | "log" | "sqrt";
+}
+
+export const LUT_SIZE = 256;
+/** Workgroup size for 1D compute passes (clear, splat, reduce). Must match
+ * the `@workgroup_size(...)` literals in the WGSL strings. */
+export const WG_1D = 256;
+/** Workgroup size per dimension for the 2D colormap pass. */
+export const WG_2D = 8;
+/**
+ * Cell budget above which the auto SVG export path falls back to a single
+ * rasterized image instead of N rect commands. ~16K rects works for vector
+ * SVG; past that, image is faster to render and produces smaller files.
+ */
+export const HEATMAP_RECT_PIXEL_BUDGET = 128 * 128;
+
+export function resolveSpec<T>(spec: HeatmapSpec<T>): ResolvedSpec<T> {
+  const [nx, ny] = spec.bins;
+  if (!Number.isInteger(nx) || !Number.isInteger(ny) || nx < 1 || ny < 1) {
+    throw new Error("heatmapLayer: `bins` entries must be positive integers.");
+  }
+  const weightScale = spec.weightScale ?? 1_000_000;
+  if (!Number.isFinite(weightScale) || weightScale <= 0) {
+    throw new Error("heatmapLayer: `weightScale` must be a positive finite number.");
+  }
+
+  const viewport = spec.viewport ?? null;
+  const xDomain =
+    spec.xDomain ?? (viewport ? (viewport.visibleXDomain as readonly [number, number]) : null);
+  const yDomain =
+    spec.yDomain ?? (viewport ? (viewport.visibleYDomain as readonly [number, number]) : null);
+  const frame = spec.frame ?? viewport?.frame ?? null;
+  if (!xDomain || !yDomain) {
+    throw new Error(
+      "heatmapLayer: `xDomain` and `yDomain` are required when no `viewport` is provided.",
+    );
+  }
+  if (!frame) {
+    throw new Error("heatmapLayer: `frame` is required when no `viewport` is provided.");
+  }
+
+  return {
+    x: spec.x,
+    y: spec.y,
+    weight: spec.weight ?? (() => 1),
+    nx,
+    ny,
+    x0: xDomain[0],
+    x1: xDomain[1],
+    y0: yDomain[0],
+    y1: yDomain[1],
+    frame,
+    viewport,
+    svgExport: spec.svgExport ?? "auto",
+    colorMap: spec.colorMap,
+    weightScale,
+    interpolation: spec.interpolation ?? "nearest",
+    normalize: spec.normalize ?? "max",
+  };
+}
+
+/**
+ * Apply the configured normalization to a raw bin value, given the grid's
+ * `max`. Returns a `[0, 1]` parameter for palette sampling.
+ */
+export function normalizeValue(value: number, max: number, mode: "max" | "log" | "sqrt"): number {
+  if (max <= 0 || value <= 0) return 0;
+  if (mode === "max") return value / max;
+  if (mode === "sqrt") return Math.sqrt(value / max);
+  // log: log(1+v) / log(1+max) — well-defined for v=0, monotonic, in [0,1].
+  return Math.log1p(value) / Math.log1p(max);
+}
+
+export function clamp01(v: number): number {
+  if (v < 0) return 0;
+  if (v > 1) return 1;
+  return v;
+}
+
+export function nextPow2(n: number): number {
+  let p = 1;
+  while (p < n) p <<= 1;
+  return p;
+}

package/src/heatmap.browser.test.ts

@@ -0,0 +1,308 @@
+// Phase 1 GPU verification: heatmap interop → v3 sprite port.
+//
+// This test confirms that the heatmap GPU path (binning compute passes +
+// sprite layer drawn via the v3 renderer) actually rasterizes colored pixels
+// onto the framebuffer. It would CATCH a regression where:
+//   - The sprite layer is returned but never drawn (blank output).
+//   - The compute passes run but write no colormap output.
+//   - The output texture is never bound to the sprite (all-transparent quad).
+//
+// Run ONLY via the browser GPU suite on a machine with real GPU or SwiftShader:
+//   vp run --filter insomni-plot test:browser
+
+import { beforeAll, describe, expect, test } from "vite-plus/test";
+
+import { initGPU, createRenderer, type GPUHandle, type Renderer2D } from "insomni";
+
+import { heatmapLayer } from "./heatmap.ts";
+import { inferno } from "./colors.ts";
+
+// ---------------------------------------------------------------------------
+// Skip guard — mirrors packages/insomni/src/renderer.browser.test.ts exactly.
+// Two-level guard:
+//   1. `hasWebGPU` — synchronous module-load check. The whole suite is
+//      `describe.skip` when false (Node / no-GPU environment).
+//   2. `gpuReady` — set in `beforeAll` after `initGPU` resolves. Individual
+//      tests return early when false (handles headless where navigator.gpu
+//      exists but no adapter is available, which would otherwise hang).
+// ---------------------------------------------------------------------------
+const hasWebGPU = typeof navigator !== "undefined" && !!(navigator as Navigator).gpu;
+const describeWithGPU = hasWebGPU ? describe : describe.skip;
+
+// Canvas / readback dimensions — small for fast pixel readback.
+const W = 128;
+const H = 128;
+
+// The heatmap fills the full canvas.
+const FRAME = { x: 0, y: 0, width: W, height: H };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeCanvas(w = W, h = H): HTMLCanvasElement {
+  const el = document.createElement("canvas");
+  el.width = w;
+  el.height = h;
+  return el;
+}
+
+function getDevice(renderer: Renderer2D): GPUDevice {
+  const r = renderer as unknown as { root: { device: GPUDevice } };
+  return r.root.device;
+}
+
+function getBackbuffer(renderer: Renderer2D): GPUTexture {
+  const r = renderer as unknown as { ctx: { backbuffer: GPUTexture | null } };
+  const bb = r.ctx.backbuffer;
+  if (!bb) throw new Error("getBackbuffer: not in persistent mode (backbuffer is null)");
+  return bb;
+}
+
+/**
+ * Read back the full pixel contents of a GPU texture as a tight RGBA
+ * Uint8Array (row-major, width*height*4 bytes). Inlined here because
+ * `readTextureToPixels` is insomni-internal and not part of the public API.
+ */
+async function readPixels(
+  device: GPUDevice,
+  texture: GPUTexture,
+  w: number,
+  h: number,
+): Promise<Uint8Array> {
+  const bytesPerRow = Math.ceil((w * 4) / 256) * 256;
+  const buf = device.createBuffer({
+    size: bytesPerRow * h,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+  });
+  const encoder = device.createCommandEncoder();
+  encoder.copyTextureToBuffer({ texture }, { buffer: buf, bytesPerRow, rowsPerImage: h }, [
+    w,
+    h,
+    1,
+  ]);
+  device.queue.submit([encoder.finish()]);
+  await buf.mapAsync(GPUMapMode.READ);
+  const src = new Uint8Array(buf.getMappedRange());
+  // De-stride: extract only the active bytes (w*4) from each padded row.
+  const out = new Uint8Array(w * h * 4);
+  const rowBytes = w * 4;
+  for (let row = 0; row < h; row++) {
+    out.set(src.subarray(row * bytesPerRow, row * bytesPerRow + rowBytes), row * rowBytes);
+  }
+  buf.unmap();
+  buf.destroy();
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// GPU handle shared across tests
+// ---------------------------------------------------------------------------
+
+let gpu: GPUHandle | null = null;
+let gpuReady = false;
+
+beforeAll(async () => {
+  if (!hasWebGPU) return;
+  try {
+    // 10 s timeout — fast on machines with a real GPU, fails fast in headless.
+    gpu = await new Promise<GPUHandle>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error("initGPU timed out — no WebGPU adapter")),
+        10_000,
+      );
+      initGPU()
+        .then((h) => {
+          clearTimeout(timer);
+          resolve(h);
+        })
+        .catch((e: unknown) => {
+          clearTimeout(timer);
+          reject(e);
+        });
+    });
+    gpuReady = true;
+  } catch {
+    gpu = null;
+    gpuReady = false;
+  }
+}, 15_000);
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describeWithGPU("heatmap GPU pixel tests — Phase 1 v3 sprite port", () => {
+  // -------------------------------------------------------------------------
+  // HEATMAP-SPRITE-DRAWS: the v3 sprite path writes colored pixels
+  //
+  // Build a small heatmap over a dense cluster of 400 points in the domain
+  // center. Run a frame (compute + render). Read back the framebuffer and
+  // assert:
+  //   - The canvas is NOT all-background (the sprite drew something).
+  //   - The cluster region contains non-transparent pixels (colormap ran).
+  //   - The cluster region has higher total color signal than empty corners.
+  //   - At least one pixel in the cluster interior has a red channel > 128,
+  //     consistent with the inferno colormap (which goes from black through
+  //     purple/red to yellow at t=1). At high density t ≈ 1, inferno yields
+  //     near-yellow (R≈252, G≈255, B≈164) or orange/red (R>200, G~100, B~0);
+  //     any channel above threshold confirms colormap was applied.
+  //
+  // This test would FAIL if:
+  //   - The sprite layer is returned but `renderer.render()` skips it.
+  //   - The compute callback is never invoked (compute seam broken).
+  //   - The output texture remains at its cleared/zero state.
+  //   - The sprite quad draws transparent (texture binding mismatch).
+  // -------------------------------------------------------------------------
+  test("HEATMAP-SPRITE-DRAWS: dense cluster produces non-background colored region", async () => {
+    if (!gpuReady) return;
+
+    const canvas = makeCanvas();
+    const renderer = createRenderer(gpu!.root, canvas, {
+      config: { persistent: true, oit: false },
+      dpr: 1,
+    });
+
+    // Dense cluster: 400 points tightly packed at (0.5, 0.5) in [0,1]×[0,1].
+    // At 16×16 bins the cluster saturates the center cells → t ≈ 1 → inferno
+    // hot end (bright yellow / orange) — easily distinguishable from background.
+    interface Point {
+      x: number;
+      y: number;
+    }
+    const data: Point[] = [];
+    for (let i = 0; i < 400; i++) {
+      // Tight cluster — all within ±0.05 of center.
+      const theta = (i / 400) * Math.PI * 2;
+      const r = 0.03 + (i % 7) * 0.003;
+      data.push({ x: 0.5 + Math.cos(theta) * r, y: 0.5 + Math.sin(theta) * r });
+    }
+
+    const producer = heatmapLayer(data, {
+      x: (d) => d.x,
+      y: (d) => d.y,
+      bins: [16, 16],
+      xDomain: [0, 1],
+      yDomain: [0, 1],
+      frame: FRAME,
+      colorMap: inferno,
+    });
+
+    // buildGPU queues the compute passes onto renderer.compute() and returns
+    // the sprite Layer. The sprite layer covers the full canvas (FRAME).
+    const spriteLayer = producer.buildGPU({ renderer });
+
+    // Run one frame: compute passes fire, then the render pass draws the sprite.
+    renderer.render([spriteLayer]);
+    const device = getDevice(renderer);
+    await device.queue.onSubmittedWorkDone();
+    const pixels = await readPixels(device, getBackbuffer(renderer), W, H);
+
+    // -----------------------------------------------------------------------
+    // Assertion 1: canvas is NOT all-background (0,0,0,0).
+    // Any non-zero pixel proves the sprite pipeline ran.
+    // -----------------------------------------------------------------------
+    let anyNonZero = false;
+    for (let i = 0; i < pixels.length; i++) {
+      if (pixels[i]! > 0) {
+        anyNonZero = true;
+        break;
+      }
+    }
+    expect(anyNonZero).toBe(true);
+
+    // -----------------------------------------------------------------------
+    // Assertion 2: the cluster region (center quarter) contains non-transparent
+    // pixels. Inferno at high density (t≈1) produces near-yellow (a≈1), so
+    // the alpha channel must be substantially above zero in the cluster cells.
+    // -----------------------------------------------------------------------
+    // Center quarter: x=[32,96), y=[32,96) — spans the 8 center cells of the
+    // 16×16 grid when projected onto the 128×128 canvas (each cell = 8px).
+    let clusterNonTransparent = 0;
+    for (let py = 32; py < 96; py++) {
+      for (let px = 32; px < 96; px++) {
+        const idx = (py * W + px) * 4;
+        if (pixels[idx + 3]! > 32) clusterNonTransparent++;
+      }
+    }
+    // At least 10% of the 64×64 center square must be non-transparent.
+    // A working heatmap fills nearly all cluster cells (≥ 4096 * 0.1 ≈ 410 px).
+    expect(clusterNonTransparent).toBeGreaterThan(400);
+
+    // -----------------------------------------------------------------------
+    // Assertion 3: the cluster interior has a meaningful RED signal.
+    // Inferno at t>0.5 has R>100 (purple/red range); at t≈1 R>250 (yellow).
+    // Empty bins map to t=0 → inferno black (R≈0). So R>100 distinguishes
+    // cluster cells from background/empty cells without pinning exact values.
+    // -----------------------------------------------------------------------
+    let hotPixels = 0;
+    for (let py = 40; py < 88; py++) {
+      for (let px = 40; px < 88; px++) {
+        const idx = (py * W + px) * 4;
+        if (pixels[idx]! > 100) hotPixels++; // red channel above inferno mid-range
+      }
+    }
+    // The dense cluster (all 400 points in ~3 cell radii) should saturate
+    // many center cells to t≈1 (bright yellow: R≈252). Require ≥ 20 hot pixels
+    // — robust to minor SwiftShader differences in bin distribution.
+    expect(hotPixels).toBeGreaterThan(20);
+
+    producer.destroy();
+    renderer.destroy();
+  }, 30_000);
+
+  // -------------------------------------------------------------------------
+  // HEATMAP-EMPTY-STAYS-DARK: zero-data heatmap produces background pixels
+  //
+  // A complementary canary: with NO data points the compute passes write all
+  // bins to 0 (t=0 everywhere) → inferno maps t=0 to near-black (R≈0,G≈0,B≈4,
+  // A≈255 — inferno has a non-zero alpha even at t=0 because it is opaque).
+  // The sprite still draws (alpha>0) but the color is near-black, NOT hot.
+  //
+  // We assert the center region has NO hot red (R < 50) — proving the colormap
+  // fired with t=0 rather than missing entirely and leaving a random texture.
+  // -------------------------------------------------------------------------
+  test("HEATMAP-EMPTY-STAYS-DARK: empty dataset yields no hot pixels", async () => {
+    if (!gpuReady) return;
+
+    interface Point {
+      x: number;
+      y: number;
+    }
+
+    const canvas = makeCanvas();
+    const renderer = createRenderer(gpu!.root, canvas, {
+      config: { persistent: true, oit: false },
+      dpr: 1,
+    });
+
+    const producer = heatmapLayer<Point>([], {
+      x: (d) => d.x,
+      y: (d) => d.y,
+      bins: [16, 16],
+      xDomain: [0, 1],
+      yDomain: [0, 1],
+      frame: FRAME,
+      colorMap: inferno,
+    });
+
+    const spriteLayer = producer.buildGPU({ renderer });
+    renderer.render([spriteLayer]);
+    const device = getDevice(renderer);
+    await device.queue.onSubmittedWorkDone();
+    const pixels = await readPixels(device, getBackbuffer(renderer), W, H);
+
+    // No hot red in the center region — inferno at t=0 has R≈0 (near-black).
+    let hotPixels = 0;
+    for (let py = 32; py < 96; py++) {
+      for (let px = 32; px < 96; px++) {
+        const idx = (py * W + px) * 4;
+        if (pixels[idx]! > 50) hotPixels++;
+      }
+    }
+    expect(hotPixels).toBe(0);
+
+    producer.destroy();
+    renderer.destroy();
+  }, 30_000);
+});