Array Heatmap

Real-time visualization of a streaming signal source — the kind of dense, per-channel event feed a sensor or electrode array produces. A Python WebSocket server emits a stream of nonnegative integers, and a web client bins them into an N×N grid and renders a live blue→red heatmap.

The project doubles as a front-end performance exploration: the same grid renders through a DOM/SVG (D3) path and a WebGL path, with an in-app perf overlay and benchmark to compare them (see the docs site's Performance page).

• server/ — Python WebSocket data server
• web/ — Vite + React + TypeScript frontend

The binning rule

For each integer v and grid size N:

1. idx = (v - 1) mod N²
2. cell = ⟨ idx ÷ N , idx mod N ⟩ — i.e. ⟨quotient, remainder⟩

Worked examples on a 4×4 grid: 17 → ⟨0,0⟩ and 8 → ⟨1,3⟩. Each hit increments that cell's cumulative count, and cells shade by count relative to the running max.

Run with Docker (recommended)

Requires Docker Desktop (or any Docker engine with Compose v2).

docker compose up --build

Then open:

• Web app: http://localhost:5174
• Docs site: http://localhost:5174/docs/index.html
• WebSocket server: ws://localhost:8765

Stop everything:

docker compose down

Configuring ports

The host ports default to 5174 (web) and 8765 (server). Override them with environment variables (the web client automatically targets SERVER_PORT):

SERVER_PORT=9000 WEB_PORT=3000 docker compose up --build

Or put them in a .env file next to docker-compose.yml:

SERVER_PORT=9000
WEB_PORT=3000

Run the unit tests

The web client's binning math and grid rendering are covered by a Vitest suite. Run it in a throwaway container (no server needed):

docker compose run --rm web-test

Or locally, without Docker:

cd web && npm install && npm test

Run locally without Docker

Server:

cd server
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python server.py            # ws://localhost:8765

Web (in another terminal):

cd web
npm install
npm run dev                 # http://localhost:5173

By default the web client connects to ws://localhost:8765. Point it elsewhere with VITE_STREAM_URL, e.g. VITE_STREAM_URL=ws://localhost:9000 npm run dev.

Deploy to Cloudflare

Cloudflare (worker/) is used to spin up a quick preview:

cd web && npm install && npm run build      # the Worker serves web/dist
cd ../worker && npm install && npx wrangler deploy

Or preview locally without deploying: npx wrangler dev in worker/.

Documentation

The docs site is served by the web app once it's running — open /docs/index.html at the web app's address:

• Docker: http://localhost:5174/docs/index.html
• Local dev: http://localhost:5173/docs/index.html

It covers the architecture overview, a performance deep-dive, code documentation, and forward-looking design notes.

Open work

Known gaps and design explorations are tracked in TODO.md.