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 (see check-list). Performance might be slower than the reference h3-js implementation in browsers, as the reference implementation compiles the C code to asm.js, which is already optimized for the browser. Performance has not been tested in Node.js yet, but it should be faster than the reference. I will add some testing soon. I'm adding the functions one by one, as time permits, but it should be complete soon. See available methods below.

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
• [x] .isValidCell(h3Index) ⇒ boolean
• [x] .isPentagon(h3Index) ⇒ boolean
• [x] .isResClassIII(h3Index) ⇒ boolean
• [x] .getBaseCellNumber(h3Index) ⇒ number
• [ ] .getIcosahedronFaces(h3Index) ⇒ Array.
• [x] .getResolution(h3Index) ⇒ number
• [x] .latLngToCell(lat, lng, res) ⇒ H3Index
• [x] .cellToLatLng(h3Index) ⇒ CoordPair
• [x] .cellToBoundary(h3Index, [formatAsGeoJson]) ⇒ Array.
• [x] .cellToParent(h3Index, res) ⇒ H3Index
• [x] .cellToChildren(h3Index, res) ⇒ Array.
• [ ] .cellToChildrenSize(h3Index, res) ⇒ number
• [x] .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.
• [x] .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
• [x] .cellArea(h3Index, unit) ⇒ number
• [x] .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();

Testing performance (browser)

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