Hyperbolic Map

A JavaScript map widget that draws vector graphics on the hyperbolic plane, projected as a Poincaré disk. Think of it like Google Earth for a negatively curved surface, rather than a sphere, which is positively curved.

Use it like a normal web-based map: scroll by dragging one finger or the mouse, pinch or mouse wheel to zoom, and rotate by twisting two fingers (or dragging the outer ring with a mouse).

The library is pure JavaScript (ES2020) without any runtime dependencies. It has been modernized and packaged from my 2012 blog post, Lost in Hyperbolia (with associated GitHub repo).

Examples

Install

npm install hyperbolic-map

import { HyperbolicViewport } from "hyperbolic-map";

or drop in the bundle and use the HyperbolicMap global:

<script src="hyperbolic-map.iife.js"></script>
<script>
  const viewport = new HyperbolicMap.HyperbolicViewport({ /* ... */ });
</script>

Quick start

const viewport = new HyperbolicViewport({
  container: "#map",
  width: 500,
  height: 500,
  data: {
    version: 1,
    coordinates: "local",
    drawables: [
      { type: "path", points: [[0, 0, "L"], [1, 0, "L"], [0.5, 1, "L"]], closed: true,
        fill: "#cde", stroke: "#036" },
      { type: "text", text: "hello", at: [0, 1.5], up: [0, 1.8], fill: "#036" },
    ],
  },
});

Replace drawables with your own vector art, and use scripts from the tools/ directory to convert between JSON and SVG.

The coordinates $(x, y)$ are projected onto the screen as $(\frac{x}{w}, \frac{y}{w})$ with $w = \sqrt{1 + x^2 + y^2}$ when the viewport is at the origin.

There are two primary drawing modes:

• a single coordinate system, as above (specify data or dataProvider);
• an atlas of tiles (specify atlas), the space is divided into regular tiles, each with its own local coordinate system. A tiling scheme defines the placement of tiles, such as regular polygons or a binary tree, and you write a tileData function that returns drawables by tile index. This makes it easier to express repeating patterns and avoids floating-point errors at large distances from the origin.

Documentation

Software reference: options, method, JSON graphics format, and infinite tiling.

Mathematical reference: projections, isometries, and transformations.

Development

npm test          # node:test, no dependencies
npm run check     # enforce the source constraints the bundler relies on
npm run build     # produce dist/ and refresh docs/lib/
npm run serve     # serve docs/ at http://localhost:8000

This project has an AGENTS.md for coding agents and everything in the notes/ directory is maintained by agents. In particular, notes/math-audit.md records the mathematical formulas that have been verified.

Pull requests are welcome!

Alternatives

As of August 2026, I could find no other libraries that provide this functionality: generic vector art in a hyperbolic plane. Here are some similar projects.

| project | what it is | how it differs | |---|---|---| | hyperbolic-canvas | a Poincaré-disk drawing interface for HTML canvas (MIT, no dependencies) | closest in spirit, but it is a geometry-and-paths layer: Point, Line, Circle, Polygon, and fill/stroke. There is no view to pan, zoom or rotate, no data format, and no widget—you drive the canvas yourself | | d3-hypertree | an interactive hyperbolic tree browser for the web (MIT, SVG, built on d3) | the closest thing to a drop-in widget, and it does pan and cull at scale—but the data model is a hierarchy, which the library lays out for you. You bring a tree, not arbitrary vector art | | Cinderella / CindyJS | interactive geometry software with native hyperbolic views (Poincaré and Beltrami–Klein) | for constructions—points, lines, incidences you build and drag—rather than rendering a dataset someone else produced | | HyperRogue and its RogueViz engine | a mature non-Euclidean engine (GPL-2.0, C++) covering H², H³, S³, Nil, Solv and more | far more geometry than this library, and used for real visualization and research—but it is a desktop application and engine, not something you embed in a page | | HyperEngine | the non-Euclidean Unity backend behind the game Hyperbolica (MIT, C#) | a game engine for first-person 3D, not a 2D map viewer | | EscherSketch and similar tessellation generators | tools that produce hyperbolic tilings and Escher-like art | they generate a picture; they are not a viewer for your own data |

My original hyperbolic-storage-space from 2012 was directly inspired by Lamping and Rao's Hyperbolic Browser at Xerox PARC from 1996 (general paper, visualizing trees, video demo). Xerox PARC introduced most of the graphical user interfaces that we take for granted today: windows, icons, menus, the mouse, drag-and-drop, cut-copy-paste, etc. Hyperbolic Browser was intended as a user interface widget for focus and context, for exploring graphs that grow too quickly to comfortably project on a flat plane. It was commercialized as StarTree, and d3-hypertree is its modern-day descendant.