# quadbin

> Utility functions for working with Quadbins

Latest version **0.4.2** (published 2025-03-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install quadbin
pnpm add quadbin
yarn add quadbin
bun add quadbin
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.4.2 |
| Published | 2025-03-31 |
| First published | 2022-09-09 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 176.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Maintainers | jmtorrescartodb, juanra-carto, cartodb, shylpx, jaragon, aaranadev, zbigg, josmorsot, vmilan, felixpalmer, donmccurdy, moicalcob, aalmonacid, jmgaya, menusal |
| Keywords | quadbin, webgl, visualization |

## Links

- npm: https://www.npmjs.com/package/quadbin
- Repository: https://github.com/CartoDB/quadbin-js
- npm.io page: https://npm.io/package/quadbin

## Dependencies (1)

- [@math.gl/web-mercator](https://npm.io/package/@math.gl/web-mercator.md) ^4.1.0

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 0.4.2 (latest) — 2025-03-31
- 0.4.1-alpha.0 (alpha) — 2025-03-24
- 0.4.0 — 2025-02-11
- 0.4.0-alpha.2 — 2025-01-31
- 0.4.0-alpha.1 — 2025-01-31
- 0.4.0-alpha.0 — 2025-01-23
- 0.3.0 — 2024-10-07
- 0.2.0 — 2024-01-31
- 0.1.9 — 2023-04-20
- 0.1.8 — 2023-04-19
- 0.1.7 — 2023-04-19
- 0.1.6 — 2023-04-19
- 0.1.5 — 2022-09-14
- 0.1.4 — 2022-09-13
- 0.1.3 — 2022-09-13
- … 2 more at https://npm.io/package/quadbin/versions

## README

# quadbin-js

The `quadbin-js` is a TypeScript library for working with the [Quadbin](https://docs.carto.com/analytics-toolbox-bigquery/overview/spatial-indexes/) spatial index.

# Install

```sh
npm install quadbin
```

# Usage

```javascript
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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

```javascript
function bigIntToHex(index: bigint): string
```

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

## hexToBigInt

```javascript
function hexToBigInt(hex: string): bigint
```

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

## getResolution

```javascript
function getResolution(quadbin: bigint): bigint
```

Calculates the resolution of a quadbin cell.

## function cellToParent

```javascript
function cellToParent(quadbin: bigint): bigint
```

Calculates the parent cell.

## function cellToChildren

```javascript
function cellToChildren(quadbin: bigint, resolution: bigint): bigint[]
```

Calculates the child cells at given resolution.

## tileToCell

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

Converts a xyz tile into a quadbin cell.

## cellToTile

```javascript
function cellToTile(quadbin: bigint): Tile
```

Converts quadbin cell into a xyz tile.

## geometryToCells

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

## cellToBoundary

```javascript
function cellToBoundary(quadbin: Quadbin): Polygon
```

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

## cellToOffset

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

Converts a Quadbin cell identifier into world coordinates offset values

## cellToWorldBounds

```javascript
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

```javascript
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

---
_Source: https://npm.io/package/quadbin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._