quad-hexer
Version:
A library for converting between quad and hex representations of geocodes.
94 lines (67 loc) • 3.75 kB
Markdown
# quad-hexer
[](https://github.com/sanak/quad-hexer/actions/workflows/verify.yml)
[](https://www.npmjs.com/package/quad-hexer)
[](LICENSE)
## Overview
**quad-hexer** is a JavaScript library that losslessly compresses location coordinate encodings by approximately 50% by converting the quaternary part (base-4 expression) of geocode formats such as [Quadkey](https://learn.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system?redirectedfrom=MSDN#tile-coordinates-and-quadkeys), [S2 Hilbert Quadkey](http://s2geometry.io/devguide/s2cell_hierarchy.html), and [Spatial ID](https://github.com/spatial-id/javascript-sdk) Tilehash (Z-order curve) into a hexadecimal format starting with `x`.
When converting each quaternary digit (2 bits) into hexadecimal (4 bits), if the total number of digits (level) is odd, a `#` symbol is added as an indicator, followed by a single quaternary character (0–3).
This mechanism preserves both prefix-matching searchability and sort order of the original quaternary representation.
Example (latitude/longitude `35.675, 139.762`):
| Geocode Type | Level | Original Value | Encoded Value |
|--------------|-------|----------------|---------------|
| Quadkey | 22 | 1330021123120010111021 | x7c25b604549 |
| Quadkey | 23 | 13300211231200101110210 | x7c25b604549#0 |
| Quadkey | 24 | 133002112312001011102101 | x7c25b6045491 |
| S2 Hilbert Quadkey | 20 | 3/00003010113313330121 | 3x00c45f7f19 |
| S2 Hilbert Quadkey | 21 | 3/000030101133133301211 | 3x00c45f7f19#1 |
| S2 Hilbert Quadkey | 22 | 3/0000301011331333012112 | 3x00c45f7f196 |
| Spatial ID Tilehash (Z-order curve) | 22 | 2441132234231121222132 | x7c25b604549 |
| Spatial ID Tilehash (Z-order curve) | 23 | 24411322342311212221321 | x7c25b604549#0 |
| Spatial ID Tilehash (Z-order curve) | 24 | 244113223423112122213212 | x7c25b6045491 |
When using Spatial ID with a nonzero F (Floor / Altitude) component, the hexadecimal encoding appends a `+` or `-` to indicate the sign, followed by the hexadecimal value of the F component after the XYZ part.
* Example: Latitude/longitude `35.675, 139.762` with altitude `100` meters at zoom level `23`
* ZFXY format: `23/25/7450994/3303428`
* Tilehash (Z-order curve): `24411322342311212265325`
* Encoded value: `x7c25b604549#0+19`
## Demo
https://sanak.github.io/quad-hexer/
## Installation
```sh
npm install quad-hexer
# or
# yarn add quad-hexer
# pnpm add quad-hexer
```
## Usage
### Quadkey
```ts
import { quadHexer } from 'quad-hexer';
const hexQuadkey = quadHexer.encodeQuadkey('13300211231200101110210');
console.log(hexQuadkey);
// => x7c25b604549#0
console.log(quadHexer.decodeHexQuadkey(hexQuadkey));
// => 13300211231200101110210
```
### S2 Hilbert Quadkey
```ts
import { quadHexer } from 'quad-hexer';
const hexS2HilbertQuadkey = quadHexer.encodeS2HilbertQuadkey('3/000030101133133301211');
console.log(hexS2HilbertQuadkey);
// => 3x00c45f7f19#1
console.log(quadHexer.decodeHexS2HilbertQuadkey(hexS2HilbertQuadkey));
// => 3/000030101133133301211
```
### Spatial ID Tilehash (Z-order curve)
```ts
import { quadHexer } from 'quad-hexer';
const hexSpatialIdTileHash = quadHexer.encodeSpatialIdTilehash('24411322342311212221321');
console.log(hexSpatialIdTileHash);
// => x7c25b604549#0
console.log(quadHexer.decodeHexSpatialIdTilehash(hexSpatialIdTileHash));
// => 24411322342311212221321
```
## License
MIT License
## Contribution
Bug reports and feature requests are welcome via GitHub Issues.
Pull requests are also highly appreciated!