Skip to content
atlas logoAtlasUtilities
Camera transforms, matrix and rect math, polygon hit-testing, and a dynamic R-tree spatial index for infinite 2D canvases.
Version
v26.11.26
Size
5.8 KB gzip
Dependencies
Zero dependencies
BrowserNode ≥22SSRDeno
createCameracreateSpatialIndexmultiplyinvertrectsIntersect View all 7 exports

Why Atlas? ​

Every infinite canvas re-implements the same three things badly: a camera that keeps the point under your cursor fixed while zooming, a hit-test that stops being O(n) once the scene grows, and selection and snapping math for moving rects. Atlas ships them as pure, headless primitives: a viewport-centred camera with anchor-preserving transforms and injectable animation scheduling, matrix/rect math, exact polygon narrow-phase, and a dynamic R-tree for O(log n) queries.

ts
// Before
// Hand-rolled transform stacks, linear scans on every pointermove, and
// selection boxes that drift while zooming.

// After
import { createCamera, createSpatialIndex } from '@vielzeug/atlas';

const camera = createCamera();
camera.zoomAt({ x: 400, y: 300 }, 1.2); // world point under (400,300) stays put

const index = createSpatialIndex();
index.set('shape-1', { height: 40, width: 60, x: 12, y: 8 });
const hits = index.queryRect(camera.visibleRect); // viewport culling, returns ids
FeatureAtlasAd-hoc mathFull scene libraries
Bundle size5.8 KBn/aTypically 20–100 kB
External dependenciesn/aVaries
Anchor-preserving zoom/rotateBuilt inDriftsYes
Dynamic R-tree hit-testingBuilt inO(n) scansYes
Headless: no DOM, canvas, or rendererVariesUsually coupled

Use Atlas when you own the render loop and scene model but want correct, tested camera, geometry, and spatial-query math without writing it yourself.

Consider a full canvas engine when you want a retained scene graph, built-in rendering, and event routing wholesale instead of headless primitives.

Installation ​

sh
pnpm add @vielzeug/atlas
sh
npm install @vielzeug/atlas
sh
yarn add @vielzeug/atlas

Quick Start ​

ts
import { createCamera, createSpatialIndex } from '@vielzeug/atlas';

// state.x/y is the world point at the viewport centre
const camera = createCamera({ initial: { x: 0, y: 0, zoom: 1 } });
camera.resize({ height: 600, width: 800 });
camera.panBy(20, 0); // content follows the drag
camera.fitBounds({ height: 400, width: 600, x: -50, y: -50 }, { padding: 40 });

const index = createSpatialIndex();
index.set('a', { height: 10, width: 10, x: 0, y: 0 });
index.queryPoint({ x: 5, y: 5 }); // ['a']

Features ​

  • createCamera(): viewport-centred state, pan, anchor-preserving zoom/rotate, fitBounds(), rotated visibleRect, and animateTo() with an injectable frame scheduler
  • createSpatialIndex(): dynamic R-tree (Guttman quadratic split) with set/delete/get/queryRect/queryPoint over ids
  • Matrix helpers: multiply, invert, apply, translate, scale, rotate, around, scaleOf, toCssMatrix in Canvas2D element order
  • Rect math: union, closed-interval intersection, containment, inflation, and bounds-from-points
  • Snapping: snapRect() alignment/grid/equal-gap guides with kind-tagged targets, plus pure alignRects()/distributeRects()
  • Narrow-phase geometry: pointInPolygon, distanceToPolyline, pointNearPolygon for exact stroke and polygon hit-testing
  • @vielzeug/atlas/grid subpath: square-tile and axial-hex coordinate math, viewport culling, computeFov/computeHexFov visibility, three-state fog, grid topologies, and findPath/reachable search
  • Frames: frameMatrix() local→world placement, boundsOfFrame() world AABBs, and resizeRect() editor resize math with min and aspect locks
  • AtlasError / AtlasConfigError: typed errors; the camera follows the Vielzeug disposal contract
  • Zero runtime dependencies, no DOM requirement: works in Node, Workers, and SSR

Documentation ​

See Also ​

  • Gesture: pinch and wheel handles feed zoomAt() and panBy() directly.
  • Ink: stroke geometry whose bounds and outlines Atlas hit-tests.
  • Wire: edge routing for node editors sharing the same world coordinates.