h3-js

What is h3-js?

The h3-js npm package is a JavaScript library for working with the H3 (Hexagonal Hierarchical Geospatial Indexing System) developed by Uber. It allows for efficient spatial indexing and querying of geographic data using hexagonal grids.

What are h3-js's main functionalities?

Geo to H3

Converts a latitude and longitude to an H3 index at a specified resolution. This is useful for spatial indexing and querying.

const h3 = require('h3-js');
const lat = 37.775938728915946;
const lng = -122.41795063018799;
const resolution = 9;
const h3Index = h3.geoToH3(lat, lng, resolution);
console.log(h3Index);

H3 to Geo

Converts an H3 index back to a latitude and longitude. This is useful for decoding spatial indexes back to geographic coordinates.

const h3 = require('h3-js');
const h3Index = '8928308280fffff';
const [lat, lng] = h3.h3ToGeo(h3Index);
console.log(lat, lng);

Get Hexagon Boundary

Gets the boundary of an H3 hexagon as an array of latitude/longitude pairs. This is useful for visualizing the hexagonal grid.

const h3 = require('h3-js');
const h3Index = '8928308280fffff';
const boundary = h3.h3ToGeoBoundary(h3Index);
console.log(boundary);

K-Ring

Finds all hexagons within a given k distance from a specified H3 index. This is useful for neighborhood queries.

const h3 = require('h3-js');
const h3Index = '8928308280fffff';
const k = 1;
const kRing = h3.kRing(h3Index, k);
console.log(kRing);

Hex Ring

Finds all hexagons in a ring of a given k distance from a specified H3 index. This is useful for ring-based queries.

const h3 = require('h3-js');
const h3Index = '8928308280fffff';
const k = 1;
const hexRing = h3.hexRing(h3Index, k);
console.log(hexRing);

Other packages similar to h3-js

s2-geometry

The s2-geometry library provides tools for working with the S2 Geometry Library, which uses spherical geometry to index geographic data. Unlike H3, which uses hexagonal grids, S2 uses hierarchical cells based on the faces of a cube projected onto a sphere. This can result in different trade-offs in terms of cell shape and size consistency.

geohash

The geohash library provides tools for encoding and decoding geohashes, which are a hierarchical spatial data structure that subdivides space into buckets of grid shape. Geohashes are less uniform in cell shape compared to H3's hexagons, but they are widely used for spatial indexing and querying.

quadkey

The quadkey library provides tools for working with QuadKeys, which are a hierarchical spatial data structure used by Bing Maps. QuadKeys divide the world into a grid of squares, which can be more intuitive for certain types of spatial queries compared to H3's hexagons.

README

h3-js

The h3-js library provides a pure-JavaScript version of the H3 Core Library, a hexagon-based geographic grid system. It can be used either in Node >= 4 or in the browser. The core library is transpiled from C using emscripten, offering full parity with the C API and highly efficient operations.

For more information on H3 and for the full API documentation, please see the H3 Documentation.

• Post bug reports or feature requests to the Github Issues page
• Ask questions by posting to the H3 tag on StackOverflow

Install

npm install h3-js

Usage

The library uses CommonJS modules. It can run natively in Node, but will require a bundler like Browserify or Webpack for use in the browser.

Core functions

const h3 = require("h3-js");

// Convert a lat/lng point to a hexagon address at resolution 7
const h3Address = h3.geoToH3(37.3615593, -122.0553238, 7);
// -> '87283472bffffff'

// Get the center of the hexagon
const hexCenterCoordinates = h3.h3ToGeo(h3Address);
// -> [37.35171820183272, -122.05032565263946]

// Get the vertices of the hexagon
const hexBoundary = h3.h3ToGeoBoundary(h3Address);
// -> [ [37.341099093235684, -122.04156135164334 ], ...]

Useful algorithms

// Get all neighbors within 1 step of the hexagon
const kRing = h3.kRing(h3Address, 1);
// -> ['87283472bffffff', '87283472affffff', ...]

// Get the set of hexagons within a polygon
const polygon = [
    [37.813318999983238, -122.4089866999972145],
    [37.7198061999978478, -122.3544736999993603],
    [37.8151571999998453, -122.4798767000009008]
];
const hexagons = h3.polyfill(polygon, 7);
// -> ['872830828ffffff', '87283082effffff', ...]

// Get the outline of a set of hexagons, as a GeoJSON-style MultiPolygon
const coordinates = h3.h3SetToMultiPolygon(hexagons, true);
// -> [[[
//      [-122.37681938644465, 37.76546768434345],
//      [-122.3856345540363,37.776004200673846],
//      ...
//    ]]]

Development

The h3-js library uses yarn as the preferred package manager. To install the dev dependencies, just run:

yarn

To lint the code:

yarn lint

To run the tests in both native ES6 (requires Node >= 6) and transpiled ES5:

yarn test

Benchmarks

The h3-js library includes a basic benchmark suite using Benchmark.js. Because many of the functions may be called over thousands of hexagons in a "hot loop", performance is an important concern. Benchmarks are run against the transpiled ES5 code by default. To run the benchmarks:

yarn run benchmarks

Sample output (Macbook Pro running Node 6):

h3IsValid x 3,725,046 ops/sec ±0.47% (90 runs sampled)
geoToH3 x 227,458 ops/sec ±0.84% (89 runs sampled)
h3ToGeo x 843,167 ops/sec ±0.96% (87 runs sampled)
h3ToGeoBoundary x 220,797 ops/sec ±2.56% (86 runs sampled)
kRing x 144,955 ops/sec ±3.06% (85 runs sampled)
polyfill x 9,291 ops/sec ±1.12% (88 runs sampled)
h3SetToMultiPolygon x 311 ops/sec ±1.56% (82 runs sampled)
compact x 1,336 ops/sec ±4.51% (86 runs sampled)
uncompact x 574 ops/sec ±0.91% (85 runs sampled)
h3IndexesAreNeighbors x 670,031 ops/sec ±1.36% (88 runs sampled)
getH3UnidirectionalEdge x 356,089 ops/sec ±1.17% (85 runs sampled)
getOriginH3IndexFromUnidirectionalEdge x 1,052,652 ops/sec ±0.54% (89 runs sampled)
getDestinationH3IndexFromUnidirectionalEdge x 891,680 ops/sec ±0.90% (91 runs sampled)
h3UnidirectionalEdgeIsValid x 3,551,111 ops/sec ±0.69% (85 runs sampled)

When making code changes that may affect performance, please run benchmarks against master and then against your branch to identify any regressions.

Transpiling the C Source

The core library is transpiled using emscripten. The easiest way to build from source locally is by using Docker. Make sure Docker is installed, then:

yarn init-docker
yarn run build-emscripten

The build script uses the H3_VERSION file to determine the version of the core library to build.

NOTE: The current h3-js is built with emscripten-1.37.40. Earlier or later versions MAY NOT WORK (emscripten does not follow semver, so patch updates may include breaking changes).

Contributing

Pull requests and Github issues are welcome. Please include tests for new work, and keep the library test coverage at 100%. Please note that the purpose of this module is to expose the API of the H3 Core library, so we will rarely accept new features that are not part of that API. New proposed feature work is more appropriate in the core C library or in a new JS library that depends on h3-js.

Before we can merge your changes, you must agree to the Uber Contributor License Agreement.

Versioning

The H3 core library adheres to Semantic Versioning. The h3-js library has a major.minor.patch version scheme. The major and minor version numbers of h3-js are the major and minor version of the bound core library, respectively. The patch version is incremented independently of the core library.

Legal and Licensing

The h3-js library is licensed under the Apache 2.0 License.

DGGRID Copyright (c) 2015 Southern Oregon University

Changelog

[3.1.0] - 2018-08-13

Added

• Added binding for h3Distance (#15)

Changed

• Updated the core library to v3.1.0 (#15)
• Moved emscripten build to docker (#14)