Pan, Zoom and Culling
Problem
You are building a pan/zoom canvas and need the two halves every editor shares: a camera that converts screen input to world coordinates without drift, and a hit-test that stays fast as the scene grows.
Solution
Create a camera and a spatial index, feed pointer input through the camera, and answer hover, marquee, and culling queries from the index.
ts
import { createCamera, createSpatialIndex, type Rect } from '@vielzeug/atlas';
interface Shape {
bounds: Rect;
id: string;
}
const camera = createCamera({
maxZoom: 10,
minZoom: 0.1,
viewport: { height: viewport.clientHeight, width: viewport.clientWidth },
});
const index = createSpatialIndex();
const shapes = new Map<string, Shape>();
// Wheel zoom anchored at the cursor (offsetX/Y are viewport-relative already).
viewport.addEventListener('wheel', (event) => {
event.preventDefault();
camera.zoomAt({ x: event.offsetX, y: event.offsetY }, Math.exp(-event.deltaY * 0.0015));
});
// Drag-to-pan on the background.
let panning = false;
viewport.addEventListener('pointerdown', () => (panning = true));
viewport.addEventListener('pointermove', (event) => {
if (panning) camera.panBy(event.movementX, event.movementY);
});
viewport.addEventListener('pointerup', () => (panning = false));
// Hover: convert to world, then ask the index.
viewport.addEventListener('pointermove', (event) => {
const world = camera.toWorld({ x: event.offsetX, y: event.offsetY });
const hitId = index.queryPoint(world, { tolerance: 4 / camera.state.zoom })[0];
viewport.style.cursor = hitId ? 'pointer' : 'default';
});
// Frame loop: cull to what the viewport can actually see.
function render(): void {
for (const id of index.queryRect(camera.visibleRect)) draw(shapes.get(id), camera.matrix);
}Pitfalls
camera.state.x/camera.state.yis the world point at the viewport centre — not a translation you add. ReadtoScreen()/toWorld()instead of composing offsets by hand, and keep the camera's size current withcamera.resize()(aResizeObserveron the viewport element).- Pointer
clientX/clientYare client-space: subtractviewport.getBoundingClientRect()before callingtoWorld()orzoomAt().offsetX/offsetYalready are viewport-relative. - After moving a shape, call
index.set(id, nextBounds); a stale index silently misses marquee and hover hits. The index holds ids only, so yourMapof shapes is always the single source of truth.
Related
- Usage Guide
- API Reference
- Gesture: pinch and wheel handles that drive
zoomAt()from real multi-touch input.