h3o-wasm

A Rust implementation of the H3 geospatial indexing system, compiled to WebAssembly for use in JavaScript projects.

Design

Experimental: this package compiles some functions from h3o to WASM. Performance might be slower than the reference h3-js implementation.

H3 should also be easy to compile to Wasm, using the emscripten toolchain, changing the flags to use the wasm target instead of asm.js.

h3o is a Rust reimplementation of the H3 geospatial indexing system, designed with the following goals:

• Leverage Rust's strong typing for safer usage.
• Provide a 100% Rust solution, eliminating C dependencies for painless compilation to WebAssembly and easier link-time optimization.
• Match or exceed the performance of the reference H3 library.

h3o-wasm exposes h3o functions to Javascript

Available methods and properties

The goal is to provide equivalent functions to all H3 functions

h3o

• .UNITS
• .h3IndexToSplitLong(h3Index) ⇒ SplitLong
• .splitLongToH3Index(lower, upper) ⇒ H3Index
• .isValidCell(h3Index) ⇒ boolean
• .isPentagon(h3Index) ⇒ boolean
• .isResClassIII(h3Index) ⇒ boolean
• .getBaseCellNumber(h3Index) ⇒ number
• .getIcosahedronFaces(h3Index) ⇒ Array.
• .getResolution(h3Index) ⇒ number
• .latLngToCell(lat, lng, res) ⇒ H3Index
• .cellToLatLng(h3Index) ⇒ CoordPair
• .cellToBoundary(h3Index, [formatAsGeoJson]) ⇒ Array.
• .cellToParent(h3Index, res) ⇒ H3Index
• .cellToChildren(h3Index, res) ⇒ Array.
• .cellToChildrenSize(h3Index, res) ⇒ number
• .cellToCenterChild(h3Index, res) ⇒ H3Index
• .cellToChildPos(h3Index, parentRes) ⇒ number
• .childPosToCell(childPos, h3Index, childRes) ⇒ H3Index
• .gridDisk(h3Index, ringSize) ⇒ Array.
• .gridDiskDistances(h3Index, ringSize) ⇒ Array.<Array.>
• .gridRingUnsafe(h3Index, ringSize) ⇒ Array.
• .polygonToCells(coordinates, res, [isGeoJson]) ⇒ Array.
• .cellsToMultiPolygon(h3Indexes, [formatAsGeoJson]) ⇒ Array.<Array.<Array.>>
• .compactCells(h3Set) ⇒ Array.
• .uncompactCells(compactedSet, res) ⇒ Array.
• .areNeighborCells(origin, destination) ⇒ boolean
• .cellsToDirectedEdge(origin, destination) ⇒ H3Index
• .getDirectedEdgeOrigin(edgeIndex) ⇒ H3Index
• .getDirectedEdgeDestination(edgeIndex) ⇒ H3Index
• .isValidDirectedEdge(edgeIndex) ⇒ boolean
• .directedEdgeToCells(edgeIndex) ⇒ Array.
• .originToDirectedEdges(h3Index) ⇒ Array.
• .directedEdgeToBoundary(edgeIndex, [formatAsGeoJson]) ⇒ Array.
• .gridDistance(origin, destination) ⇒ number
• .gridPathCells(origin, destination) ⇒ Array.
• .cellToLocalIj(origin, destination) ⇒ CoordIJ
• .localIjToCell(origin, coords) ⇒ H3Index
• .greatCircleDistance(latLng1, latLng2, unit) ⇒ number
• .cellArea(h3Index, unit) ⇒ number
• .edgeLength(edge, unit) ⇒ number
• .getHexagonAreaAvg(res, unit) ⇒ number
• .getHexagonEdgeLengthAvg(res, unit) ⇒ number
• .cellToVertex(h3Index, vertexNum) ⇒ H3Index
• .cellToVertexes(h3Index) ⇒ Array.
• .vertexToLatLng(h3Index) ⇒ CoordPair
• .isValidVertex(h3Index) ⇒ boolean
• .getNumCells(res) ⇒ number
• .getRes0Cells() ⇒ Array.
• .getPentagons(res) ⇒ Array.
• .degsToRads(deg) ⇒ number
• .radsToDegs(rad) ⇒ number
• .H3Index : string
• .H3IndexInput : string | Array.
• .CoordIJ
• .H3Error
• .CoordPair : Array.
• .SplitLong : Array.

Installation

The h3o-wasm package is distributed via npm.

npm install h3o-wasm

Building

• Install the rust toolchain in order to have cargo installed by following this guide.
• run cargo install wasm-bindgen-cli
• run wasm-pack build --target web

Usage

import init, * as h3o from "h3o-wasm";

async function run() {
  await init(); // Initialize the WASM module
  const h3Index = h3o.latLngToCell(37.3615593, -122.0553238, 7);
  console.log("H3 Index: ", h3Index);
}

run();

An example file is available in the root of the repository, to run it you can use a simple http server like http-server:

npm -g install http-server
http-server .

Why this name?

Rust is an iron oxide. A Rust version of H3 is an H3 oxide, in other word $H_3O$ (a.k.a hydronium). Chemically speaking this is wrong ( $H_3O$ is produced by protonation of $H_2O$, not oxidation of $H_3$), but ¯\(ツ)/¯

License

BSD 3-Clause