gpu-heatmap

⚠️ WORK IN PROGRESS ⚠️

A high-performance heatmap renderer powered by WebGPU with automatic WebGL2 fallback.
Optimized for visualizing hundreds of thousands to millions of points in real time.

• 🚀 Fast — WebGPU compute shaders + optimized WebGL2 fallback
• 🔥 Automatic engine selection (auto)
• 🎛️ Simple API — demo mode or real data
• 📦 Framework-agnostic (JS/TS/React/Vue/Svelte/etc.)
• 🎨 CRO-style color palette (blue → green → yellow → red)

Installation

npm install gpu-heatmap

Basic Usage

import { createHeatmapApp } from 'gpu-heatmap'

const canvas = document.querySelector('#heat')

const data = {
  x: new Float32Array([0.1, 0.3, 0.7]),
  y: new Float32Array([0.2, 0.5, 0.9])
}

const app = await createHeatmapApp({
  canvas,
  mode: {
    kind: 'data',
    data
  }
})

// update later
await app.setData(newData)

// cleanup
app.dispose()

Demo Mode

Use auto-generated blobs of points for testing:

const app = await createHeatmapApp({
  canvas,
  mode: {
    kind: 'demo',
    demo: {
      points: 200_000,
      clusters: 8,
      minSpread: 0.05,
      maxSpread: 0.15
    }
  }
})

// regenerate demo data
await app.rerenderDemo()

Engine Selection

The engine can be chosen manually or automatically:

engine: 'webgpu'   // force WebGPU only
engine: 'webgl2'   // force WebGL2 only
engine: 'auto'     // DEFAULT — WebGPU first → fallback to WebGL2

Example:

const app = await createHeatmapApp({
  canvas,
  engine: 'auto',
  mode: { kind: 'data', data }
})

Data Format

Heatmap input format:

type HeatmapData = {
  x: Float32Array
  y: Float32Array
  w?: Float32Array   // optional per-point weight
}

Important:

• Coordinates must be normalized (0–1)
• All arrays must be equal length
• If w is included, weights are automatically normalized per dataset

Example:

const data = {
  x: new Float32Array(N),
  y: new Float32Array(N),
  w: new Float32Array(N) // optional
}

Heatmap Options

Passed through heatmap: { ... }:

heatmap: {
  gridSize: { width: 1024, height: 1024 },
  kernelRadiusPx: 14,
  extent: { xMin: 0, xMax: 1, yMin: 0, yMax: 1 }
}

Available Options

| Option | Type | Description | | ---------------- | ---------------------------- | ------------------------------ | | gridSize | { width, height } | GPU grid resolution | | kernelRadiusPx | number | Gaussian radius for each point | | extent | { xMin, xMax, yMin, yMax } | Input spatial bounds |

Running the Demo Locally

The repo includes a standalone demo using Vite.

Start dev server

npm run dev

Build the demo

npm run preview

API Summary

createHeatmapApp(opts): Promise<HeatmapApp>

High-level helper recommended for most users.

HeatmapApp

type HeatmapApp = {
  heatmap: Heatmap
  setData(data): Promise<void>
  rerenderDemo?: () => Promise<void>
  dispose(): void
}

Low-Level Engine API

If you want direct control:

import { createHeatmap } from 'gpu-heatmap'

const heat = await createHeatmap(canvas, {
  engine: 'auto',
  gridSize: { width: 1024, height: 1024 }
})

heat.setData(data)
await heat.render()

Browser Compatibility

| Engine | Requirement | | ---------- | --------------------------------------- | | WebGPU | Chrome 113+, Edge 113+, modern GPU | | WebGL2 | Supported by nearly all modern browsers |

License

MIT © 2025