README.md

quadbin-js

The quadbin-js is a TypeScript library for working with the Quadbin spatial index.

Install

npm install quadbin

Usage

import {cellToParent, getResolution, hexToBigInt} from 'quadbin';

cellToParent(5210915457518796799n) // => 5206425052030959615n
getResolution(hexToBigInt('4830ffffffffffff')) // => 3

I/O types

A Quadbin index is a 64-bit integer. This library uses BigInt as a data type to represent quadbin indices, both as parameters and return values for functions.

When working with quadbin indices in other contexts (e.g. passing as a parameter in a URL or serializing as JSON), it is more appropriate to encode the index as a hexidecimal string. The library provides the bigIntToHex() & hexToBigInt() to facilitate this conversion.

API

bigIntToHex

function bigIntToHex(index: bigint): string

Encodes an index into a string, suitable for use in JSON.

hexToBigInt

function hexToBigInt(hex: string): bigint

Decodes an string into an index. Inverse of bigIntToHex().

getResolution

function getResolution(quadbin: bigint): bigint 

Calculates the resolution of a quadbin cell.

function cellToParent

function cellToParent(quadbin: bigint): bigint 

Calculates the parent cell.

tileToCell

function tileToCell(tile: {x: number, y: number, z: number}): bigint

Converts a xyz tile into a quadbin cell.

cellToTile

function cellToTile(quadbin: bigint): Tile 

Converts quadbin cell into a xyz tile.

geometryToCells

function geometryToCells(geometry: GeoJSONGeometry, resolution: bigint): bigint 

cellToBoundary

function cellToBoundary(quadbin: Quadbin): Polygon 

Converts a Quadbin cell identifier into a geographical boundary represented as a polygon

cellToOffset

function cellToOffset(quadbin: Quadbin): [number, number, number]

Converts a Quadbin cell identifier into world coordinates offset values

cellToWorldBounds

function cellToWorldBounds(quadbin: Quadbin, coverage: number): [number[], number[]]

Computes the world bounds (in Web Mercator coordinates) for a given Quadbin cell, taking into account the cell's coverage area

getCellPolygon

function getCellPolygon(quadbin: Quadbin, coverage = 1): number[]

Generates the geographical polygon (in longitude and latitude) that represents the boundaries of a Quadbin cell, optionally taking into account coverage