Getting Started

Installation

npm install webdggrid
# or
yarn add webdggrid

Browser (ES Module)

import { Webdggrid } from 'https://cdn.jsdelivr.net/npm/webdggrid/dist/index.js';

const dggs = await Webdggrid.load();

Node.js

import { Webdggrid } from 'webdggrid';

const dggs = await Webdggrid.load();

Basic Usage

Convert coordinates to cell IDs

// coordinates are [lng, lat] pairs
const seqNums = dggs.geoToSequenceNum([[0, 0], [-73.9, 40.7]], 3);
console.log(seqNums); // [1n, 42n, ...]

Get cell center from ID

const centers = dggs.sequenceNumToGeo([1n, 2n], 3);
// [[lng, lat], [lng, lat]]

Get grid polygons as GeoJSON

const seqNums = dggs.geoToSequenceNum([[0, 0]], 5);
const geojson = dggs.sequenceNumToGridFeatureCollection(seqNums, 5);
// Standard GeoJSON FeatureCollection — ready for Leaflet, MapLibre, deck.gl, etc.

Configure the grid system

// Standard single-aperture grid
dggs.setDggs({
  poleCoordinates: { lat: 0, lng: 0 },
  azimuth: 0,
  topology: 'HEXAGON',
  projection: 'ISEA',
  aperture: 4,
}, /* resolution */ 3);

// Multi-aperture grid (NEW!)
dggs.setDggs({
  poleCoordinates: { lat: 0, lng: 0 },
  azimuth: 0,
  topology: 'HEXAGON',
  projection: 'ISEA',
  apertureSequence: "434747",  // Different aperture per resolution
}, /* resolution */ 5);

See the multi-aperture documentation for more details.

Grid Statistics

const cellCount = dggs.nCells(3);       // total cells at resolution 3
const areakm    = dggs.cellAreaKM(3);   // average cell area in km²
const distkm    = dggs.cellDistKM(3);   // average cell spacing in km

Live Demo

• Globe Demo — interactive MapLibre globe with topology switching, multi-aperture grids, and hierarchical cell selection
• Hierarchical Operations Demo — explore parent, children, and neighbor relationships
• Address Types Demo — compare index types and see bitwise digit breakdowns
• Index Arithmetic Demo — live demonstration of digit manipulation on Z3, Z7, and ZORDER indices

API Overview

Lifecycle

Method	Description
Webdggrid.load()	Compile and instantiate the WASM module
Webdggrid.unload()	Free WASM memory

Configuration

Method	Description
setDggs()	Configure grid projection, aperture, topology, and resolution
getResolution()	Get current resolution
setResolution()	Set current resolution
version()	Get DGGRID version string

Coordinate Conversion

Method	Description
geoToSequenceNum()	Convert [lng, lat] points to cell IDs
sequenceNumToGeo()	Convert cell IDs to [lng, lat] centers
geoToGeo()	Snap [lng, lat] points to cell centers
sequenceNumToGrid()	Get polygon rings for cell IDs
sequenceNumToGridFeatureCollection()	Get GeoJSON FeatureCollection for cell IDs

Grid Statistics

Method	Description
nCells()	Total cell count at a resolution
cellAreaKM()	Average cell area in km²
cellDistKM()	Average cell spacing in km
gridStatCLS()	Characteristic length scale

Hierarchical Operations

Method	Description
sequenceNumNeighbors()	Find edge-sharing neighbor cells
sequenceNumParent()	Get primary (containing) parent at coarser resolution
sequenceNumAllParents()	Get all touching parent cells (primary first)
sequenceNumChildren()	Get child cells at finer resolution

Hierarchical Address Types

Method	Description
sequenceNumToVertex2DD()	SEQNUM → VERTEX2DD (all apertures)
vertex2DDToSequenceNum()	VERTEX2DD → SEQNUM
sequenceNumToZOrder()	SEQNUM → ZORDER (aperture 3, 4)
zOrderToSequenceNum()	ZORDER → SEQNUM
sequenceNumToZ3()	SEQNUM → Z3 (aperture 3 hexagons)
z3ToSequenceNum()	Z3 → SEQNUM
sequenceNumToZ7()	SEQNUM → Z7 (aperture 7 hexagons)
z7ToSequenceNum()	Z7 → SEQNUM

Index Digit Manipulation

Method	Description
z7GetQuad()	Get quad (icosahedron face) from Z7 index
z7GetDigit()	Read digit at resolution level from Z7 index
z7SetDigit()	Write digit at resolution level in Z7 index
z7ExtractDigits()	Extract quad + all digits from Z7 index
z3GetQuad()	Get quad from Z3 index
z3GetDigit()	Read digit at resolution level from Z3 index
z3SetDigit()	Write digit at resolution level in Z3 index
z3ExtractDigits()	Extract quad + all digits from Z3 index
zOrderGetQuad()	Get quad from ZORDER index
zOrderGetDigit()	Read digit at resolution level from ZORDER index
zOrderSetDigit()	Write digit at resolution level in ZORDER index
zOrderExtractDigits()	Extract quad + all digits from ZORDER index

Low-Level Coordinate Systems

Method	Description
geoToPlane()	Geographic → PLANE
geoToProjtri()	Geographic → PROJTRI
geoToQ2dd()	Geographic → Q2DD
geoToQ2di()	Geographic → Q2DI
sequenceNumToPlane()	SEQNUM → PLANE
sequenceNumToProjtri()	SEQNUM → PROJTRI
sequenceNumToQ2dd()	SEQNUM → Q2DD
sequenceNumToQ2di()	SEQNUM → Q2DI

Q2DI Conversions

Method	Description
q2diToGeo()	Q2DI → Geographic
q2diToSequenceNum()	Q2DI → SEQNUM
q2diToPlane()	Q2DI → PLANE
q2diToProjtri()	Q2DI → PROJTRI
q2diToQ2dd()	Q2DI → Q2DD

Q2DD Conversions

Method	Description
q2ddToGeo()	Q2DD → Geographic
q2ddToSequenceNum()	Q2DD → SEQNUM
q2ddToPlane()	Q2DD → PLANE
q2ddToProjtri()	Q2DD → PROJTRI
q2ddToQ2di()	Q2DD → Q2DI

PROJTRI Conversions

Method	Description
projtriToGeo()	PROJTRI → Geographic
projtriToSequenceNum()	PROJTRI → SEQNUM
projtriToPlane()	PROJTRI → PLANE
projtriToQ2dd()	PROJTRI → Q2DD
projtriToQ2di()	PROJTRI → Q2DI

For full parameter details and examples, see the complete API reference.

Examples

More examples can be found in the test suite:

• geo.test.ts — Basic grid operations
• transforms.test.ts — Coordinate transformations
• hierarchy.test.ts — Parent, children, neighbors
• hierarchical-addresses.test.ts — VERTEX2DD, ZORDER, Z3, Z7
• index-digits.test.ts — Index digit manipulation
• multi-aperture.test.ts — Multi-aperture grids