h3-js - npm Package Compare versions

Comparing version 3.1.1 to 3.2.0

CHANGELOG.md

@@ -8,2 +8,8 @@ # Change Log
 
+## [3.2.0] - 2018-10-31
+### Changed
+- Updated the core library to v3.2.0 (#26)
+### Added
+- Added `experimentalH3ToLocalIj` and `experimentalLocalIjToH3` bindings (#26)
+
 ## [3.1.1] - 2018-08-30
@@ -10,0 +16,0 @@ ### Fixed

dist/lib/bindings.js

@@ -38,2 +38,3 @@ /*
     ['sizeOfLinkedGeoPolygon', NUMBER],
+    ['sizeOfCoordIJ', NUMBER],
     // The remaining functions are defined in the core lib in h3Api.h
@@ -70,2 +71,4 @@ ['h3IsValid', BOOLEAN, [H3_LOWER, H3_UPPER]],
     ['h3Distance', NUMBER, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER]],
+    ['experimentalH3ToLocalIj', NUMBER, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER, POINTER]],
+    ['experimentalLocalIjToH3', NUMBER, [H3_LOWER, H3_UPPER, POINTER, POINTER]],
     ['hexAreaM2', NUMBER, [RESOLUTION]],
@@ -72,0 +75,0 @@ ['hexAreaKm2', NUMBER, [RESOLUTION]],

dist/lib/h3core.js

@@ -46,2 +46,3 @@ /*
 var SZ_LINKED_GEOPOLYGON = H3.sizeOfLinkedGeoPolygon();
+var SZ_COORDIJ = H3.sizeOfCoordIJ();
 
@@ -225,3 +226,3 @@ // ----------------------------------------------------------------------------
  * Read an H3 index from a C return value. As with readLong, the argument to this function
- * is intended to be an invocation, e.g. readh3Index(H3.getSomeAddress()), to help ensure that
+ * is intended to be an invocation, e.g. readH3Index(H3.getSomeAddress()), to help ensure that
  * the temp value storing the upper bits of the long is still set.
@@ -232,8 +233,8 @@ * @private
  */
-function readh3Index(invocation) {
+function readH3Index(invocation) {
     var ref = readLong(invocation);
     var lower = ref[0];
     var upper = ref[1];
-    // The lower bits are allowed to be 0s, but if the upper bits are 0 this represents
-    // an invalid H3 index
+    // The lower bits are allowed to be 0s, but if the upper bits are 0
+    // this represents an invalid H3 index
     return upper ? splitLongToh3Index(lower, upper) : null;
@@ -243,2 +244,39 @@ }
 /**
+ * Read an H3 index from a pointer to C memory.
+ * @private
+ * @param  {Number} cAddress  Pointer to allocated C memory
+ * @param {Number} offset     Offset, in number of H3 indexes, in case we're
+ *                            reading an array
+ * @return {H3Index}          H3 index, or null if index was invalid
+ */
+function readH3IndexFromPointer(cAddress, offset) {
+    if ( offset === void 0 ) offset = 0;
+
+    var lower = C.getValue(cAddress + SZ_INT * offset * 2, 'i32');
+    var upper = C.getValue(cAddress + SZ_INT * (offset * 2 + 1), 'i32');
+    // The lower bits are allowed to be 0s, but if the upper bits are 0
+    // this represents an invalid H3 index
+    return upper ? splitLongToh3Index(lower, upper) : null;
+}
+
+/**
+ * Store an H3 index in C memory.
+ * @private
+ * @param  {H3Index} h3Index  H3 index to store
+ * @param  {Number} cAddress  Pointer to allocated C memory
+ * @param {Number} offset     Offset, in number of H3 indexes, in case we're
+ *                            writing an array
+ */
+function storeH3Index(h3Index, cAddress, offset) {
+    if ( offset === void 0 ) offset = 0;
+
+    // HEAPU32 is a typed array projection on the index space
+    // as unsigned 32-bit integers. This means the index needs
+    // to be divided by SZ_INT (4) to access correctly. Also,
+    // the H3 index is 64 bits, so we skip by twos as we're writing
+    // to 32-bit integers in the proper order.
+    C.HEAPU32.set(h3IndexToSplitLong(h3Index), cAddress / SZ_INT + 2 * offset);
+}
+
+/**
  * Read an array of 64-bit H3 indexes from C and convert to a JS array of
@@ -255,7 +293,6 @@ * H3 index strings
     var out = [];
-    for (var i = 0; i < maxCount * 2; i += 2) {
-        var lower = C.getValue(cAddress + SZ_INT * i, 'i32');
-        var upper = C.getValue(cAddress + SZ_INT * (i + 1), 'i32');
-        if (lower !== 0 || upper !== 0) {
-            out.push(splitLongToh3Index(lower, upper));
+    for (var i = 0; i < maxCount; i++) {
+        var h3Index = readH3IndexFromPointer(cAddress, i);
+        if (h3Index !== null) {
+            out.push(h3Index);
         }
@@ -277,8 +314,3 @@ }
     for (var i = 0; i < count; i++) {
-        // HEAPU32 is a typed array projection on the index space
-        // as unsigned 32-bit integers. This means the index needs
-        // to be divided by 4 to access correctly. Also, the hexagon
-        // index is 64-bits, so we skip by twos as we're writing
-        // to 32-bit integers in the proper order.
-        C.HEAPU32.set(h3IndexToSplitLong(hexagons[i]), cAddress / SZ_INT + 2 * i);
+        storeH3Index(hexagons[i], cAddress, i);
     }
@@ -378,2 +410,29 @@ }
 
+/**
+ * Read a CoordIJ from C and return an {i, j} pair.
+ * @private
+ * @param  {Number} cAddress    Pointer to C struct
+ * @return {Object}             {i, j} pair
+ */
+function readCoordIJ(cAddress) {
+    return {
+        i: C.getValue(cAddress, 'i32'),
+        j: C.getValue(cAddress + SZ_INT, 'i32')
+    };
+}
+
+/**
+ * Store an {i, j} pair to a C CoordIJ struct.
+ * @private
+ * @param  {Number} cAddress    Pointer to C struct
+ * @return {Object}             {i, j} pair
+ */
+function storeCoordIJ(cAddress, ref) {
+    var i = ref.i;
+    var j = ref.j;
+
+    C.setValue(cAddress, i, 'i32');
+    C.setValue(cAddress + SZ_INT, j, 'i32');
+}
+
 // ----------------------------------------------------------------------------
@@ -462,3 +521,3 @@ // Public API functions: Core
     // Read value as a split long
-    var h3Index = readh3Index(H3.geoToH3(latlng, res));
+    var h3Index = readH3Index(H3.geoToH3(latlng, res));
     C._free(latlng);
@@ -519,3 +578,3 @@ return h3Index;
     var upper = ref[1];
-    return readh3Index(H3.h3ToParent(lower, upper, res));
+    return readH3Index(H3.h3ToParent(lower, upper, res));
 }
@@ -783,3 +842,3 @@
     var dUpper = ref$1[1];
-    return readh3Index(H3.getH3UnidirectionalEdge(oLower, oUpper, dLower, dUpper));
+    return readH3Index(H3.getH3UnidirectionalEdge(oLower, oUpper, dLower, dUpper));
 }
@@ -797,3 +856,3 @@
     var upper = ref[1];
-    return readh3Index(H3.getOriginH3IndexFromUnidirectionalEdge(lower, upper));
+    return readH3Index(H3.getOriginH3IndexFromUnidirectionalEdge(lower, upper));
 }
@@ -811,3 +870,3 @@
     var upper = ref[1];
-    return readh3Index(H3.getDestinationH3IndexFromUnidirectionalEdge(lower, upper));
+    return readH3Index(H3.getDestinationH3IndexFromUnidirectionalEdge(lower, upper));
 }
@@ -904,2 +963,87 @@
 
+/**
+ * Produces IJ coordinates for an H3 index anchored by an origin.
+ *
+ * - The coordinate space used by this function may have deleted
+ * regions or warping due to pentagonal distortion.
+ * - Coordinates are only comparable if they come from the same
+ * origin index.
+ * - Failure may occur if the index is too far away from the origin
+ * or if the index is on the other side of a pentagon.
+ * - This function is experimental, and its output is not guaranteed
+ * to be compatible across different versions of H3.
+ * @static
+ * @param  {H3Index} origin      Origin H3 index
+ * @param  {H3Index} destination H3 index for which to find relative coordinates
+ * @return {Object}              Coordinates as an `{i, j}` pair
+ * @throws {Error}               If the IJ coordinates cannot be calculated
+ */
+function experimentalH3ToLocalIj(origin, destination) {
+    var ij = C._malloc(SZ_COORDIJ);
+    var retVal = H3.experimentalH3ToLocalIj.apply(
+        H3, h3IndexToSplitLong(origin).concat( h3IndexToSplitLong(destination),
+        [ij] )
+    );
+    var coords = readCoordIJ(ij);
+    C._free(ij);
+    // Return the pair, or throw if an error code was returned.
+    // Switch statement and error codes cribbed from h3-java's implementation.
+    switch (retVal) {
+        case 0:
+            return coords;
+        case 1:
+            throw new Error('Incompatible origin and index.');
+        case 2:
+        default:
+            throw new Error(
+                'Local IJ coordinates undefined for this origin and index pair. ' +
+                    'The index may be too far from the origin.'
+            );
+        case 3:
+        case 4:
+        case 5:
+            throw new Error('Encountered possible pentagon distortion');
+    }
+}
+
+/**
+ * Produces an H3 index for IJ coordinates anchored by an origin.
+ *
+ * - The coordinate space used by this function may have deleted
+ * regions or warping due to pentagonal distortion.
+ * - Coordinates are only comparable if they come from the same
+ * origin index.
+ * - Failure may occur if the index is too far away from the origin
+ * or if the index is on the other side of a pentagon.
+ * - This function is experimental, and its output is not guaranteed
+ * to be compatible across different versions of H3.
+ * @static
+ * @param  {H3Index} origin     Origin H3 index
+ * @param  {Object} coords      Coordinates as an `{i, j}` pair
+ * @return {H3Index}            H3 index at the relative coordinates
+ * @throws {Error}              If the H3 index cannot be calculated
+ */
+function experimentalLocalIjToH3(origin, coords) {
+    // Validate input coords
+    if (!coords || typeof coords.i !== 'number' || typeof coords.j !== 'number') {
+        throw new Error('Coordinates must be provided as an {i, j} object');
+    }
+    // Allocate memory for the CoordIJ struct and an H3 index to hold the return value
+    var ij = C._malloc(SZ_COORDIJ);
+    var out = C._malloc(SZ_H3INDEX);
+    storeCoordIJ(ij, coords);
+    var retVal = H3.experimentalLocalIjToH3.apply(H3, h3IndexToSplitLong(origin).concat( [ij], [out] ));
+    var h3Index = readH3IndexFromPointer(out);
+    C._free(ij);
+    C._free(out);
+    if (retVal !== 0) {
+        throw new Error(
+            'Index not defined for this origin and IJ coordinates pair. ' +
+                'IJ coordinates may be too far from origin, or ' +
+                'a pentagon distortion was encountered.'
+        );
+    }
+    return h3Index;
+}
+
 // ----------------------------------------------------------------------------
@@ -1020,2 +1164,4 @@ // Public informational utilities
     h3Distance: h3Distance,
+    experimentalH3ToLocalIj: experimentalH3ToLocalIj,
+    experimentalLocalIjToH3: experimentalLocalIjToH3,
     hexArea: hexArea,
@@ -1022,0 +1168,0 @@ edgeLength: edgeLength,

doc-files/README.tmpl.md

 # h3-js
 
-[![Build Status](https://travis-ci.org/uber/h3-js.svg?branch=master)](https://travis-ci.org/uber/h3-js) [![Coverage Status](https://coveralls.io/repos/github/uber/h3-js/badge.svg?branch=master)](https://coveralls.io/github/uber/h3-js?branch=master)
+[![H3 Version](https://img.shields.io/badge/h3_api-v{{h3Version}}-blue.svg)](https://github.com/uber/h3/releases/tag/v{{h3Version}}) [![Build Status](https://travis-ci.org/uber/h3-js.svg?branch=master)](https://travis-ci.org/uber/h3-js) [![Coverage Status](https://coveralls.io/repos/github/uber/h3-js/badge.svg?branch=master)](https://coveralls.io/github/uber/h3-js?branch=master)
 
@@ -5,0 +5,0 @@ The `h3-js` library provides a pure-JavaScript version of the [H3 Core Library](https://github.com/uber/h3), 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](http://kripken.github.io/emscripten-site), offering full parity with the C API and highly efficient operations.

lib/bindings.js

@@ -38,2 +38,3 @@ /*
     ['sizeOfLinkedGeoPolygon', NUMBER],
+    ['sizeOfCoordIJ', NUMBER],
     // The remaining functions are defined in the core lib in h3Api.h
@@ -70,2 +71,4 @@ ['h3IsValid', BOOLEAN, [H3_LOWER, H3_UPPER]],
     ['h3Distance', NUMBER, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER]],
+    ['experimentalH3ToLocalIj', NUMBER, [H3_LOWER, H3_UPPER, H3_LOWER, H3_UPPER, POINTER]],
+    ['experimentalLocalIjToH3', NUMBER, [H3_LOWER, H3_UPPER, POINTER, POINTER]],
     ['hexAreaM2', NUMBER, [RESOLUTION]],
@@ -72,0 +75,0 @@ ['hexAreaKm2', NUMBER, [RESOLUTION]],

lib/h3core.js

@@ -46,2 +46,3 @@ /*
 const SZ_LINKED_GEOPOLYGON = H3.sizeOfLinkedGeoPolygon();
+const SZ_COORDIJ = H3.sizeOfCoordIJ();
 
@@ -225,3 +226,3 @@ // ----------------------------------------------------------------------------
  * Read an H3 index from a C return value. As with readLong, the argument to this function
- * is intended to be an invocation, e.g. readh3Index(H3.getSomeAddress()), to help ensure that
+ * is intended to be an invocation, e.g. readH3Index(H3.getSomeAddress()), to help ensure that
  * the temp value storing the upper bits of the long is still set.
@@ -232,6 +233,6 @@ * @private
  */
-function readh3Index(invocation) {
+function readH3Index(invocation) {
     const [lower, upper] = readLong(invocation);
-    // The lower bits are allowed to be 0s, but if the upper bits are 0 this represents
-    // an invalid H3 index
+    // The lower bits are allowed to be 0s, but if the upper bits are 0
+    // this represents an invalid H3 index
     return upper ? splitLongToh3Index(lower, upper) : null;
@@ -241,2 +242,35 @@ }
 /**
+ * Read an H3 index from a pointer to C memory.
+ * @private
+ * @param  {Number} cAddress  Pointer to allocated C memory
+ * @param {Number} offset     Offset, in number of H3 indexes, in case we're
+ *                            reading an array
+ * @return {H3Index}          H3 index, or null if index was invalid
+ */
+function readH3IndexFromPointer(cAddress, offset = 0) {
+    const lower = C.getValue(cAddress + SZ_INT * offset * 2, 'i32');
+    const upper = C.getValue(cAddress + SZ_INT * (offset * 2 + 1), 'i32');
+    // The lower bits are allowed to be 0s, but if the upper bits are 0
+    // this represents an invalid H3 index
+    return upper ? splitLongToh3Index(lower, upper) : null;
+}
+
+/**
+ * Store an H3 index in C memory.
+ * @private
+ * @param  {H3Index} h3Index  H3 index to store
+ * @param  {Number} cAddress  Pointer to allocated C memory
+ * @param {Number} offset     Offset, in number of H3 indexes, in case we're
+ *                            writing an array
+ */
+function storeH3Index(h3Index, cAddress, offset = 0) {
+    // HEAPU32 is a typed array projection on the index space
+    // as unsigned 32-bit integers. This means the index needs
+    // to be divided by SZ_INT (4) to access correctly. Also,
+    // the H3 index is 64 bits, so we skip by twos as we're writing
+    // to 32-bit integers in the proper order.
+    C.HEAPU32.set(h3IndexToSplitLong(h3Index), cAddress / SZ_INT + 2 * offset);
+}
+
+/**
  * Read an array of 64-bit H3 indexes from C and convert to a JS array of
@@ -253,7 +287,6 @@ * H3 index strings
     const out = [];
-    for (let i = 0; i < maxCount * 2; i += 2) {
-        const lower = C.getValue(cAddress + SZ_INT * i, 'i32');
-        const upper = C.getValue(cAddress + SZ_INT * (i + 1), 'i32');
-        if (lower !== 0 || upper !== 0) {
-            out.push(splitLongToh3Index(lower, upper));
+    for (let i = 0; i < maxCount; i++) {
+        const h3Index = readH3IndexFromPointer(cAddress, i);
+        if (h3Index !== null) {
+            out.push(h3Index);
         }
@@ -275,8 +308,3 @@ }
     for (let i = 0; i < count; i++) {
-        // HEAPU32 is a typed array projection on the index space
-        // as unsigned 32-bit integers. This means the index needs
-        // to be divided by 4 to access correctly. Also, the hexagon
-        // index is 64-bits, so we skip by twos as we're writing
-        // to 32-bit integers in the proper order.
-        C.HEAPU32.set(h3IndexToSplitLong(hexagons[i]), cAddress / SZ_INT + 2 * i);
+        storeH3Index(hexagons[i], cAddress, i);
     }
@@ -376,2 +404,26 @@ }
 
+/**
+ * Read a CoordIJ from C and return an {i, j} pair.
+ * @private
+ * @param  {Number} cAddress    Pointer to C struct
+ * @return {Object}             {i, j} pair
+ */
+function readCoordIJ(cAddress) {
+    return {
+        i: C.getValue(cAddress, 'i32'),
+        j: C.getValue(cAddress + SZ_INT, 'i32')
+    };
+}
+
+/**
+ * Store an {i, j} pair to a C CoordIJ struct.
+ * @private
+ * @param  {Number} cAddress    Pointer to C struct
+ * @return {Object}             {i, j} pair
+ */
+function storeCoordIJ(cAddress, {i, j}) {
+    C.setValue(cAddress, i, 'i32');
+    C.setValue(cAddress + SZ_INT, j, 'i32');
+}
+
 // ----------------------------------------------------------------------------
@@ -452,3 +504,3 @@ // Public API functions: Core
     // Read value as a split long
-    const h3Index = readh3Index(H3.geoToH3(latlng, res));
+    const h3Index = readH3Index(H3.geoToH3(latlng, res));
     C._free(latlng);
@@ -503,3 +555,3 @@ return h3Index;
     const [lower, upper] = h3IndexToSplitLong(h3Index);
-    return readh3Index(H3.h3ToParent(lower, upper, res));
+    return readH3Index(H3.h3ToParent(lower, upper, res));
 }
@@ -753,3 +805,3 @@
     const [dLower, dUpper] = h3IndexToSplitLong(destination);
-    return readh3Index(H3.getH3UnidirectionalEdge(oLower, oUpper, dLower, dUpper));
+    return readH3Index(H3.getH3UnidirectionalEdge(oLower, oUpper, dLower, dUpper));
 }
@@ -765,3 +817,3 @@
     const [lower, upper] = h3IndexToSplitLong(edgeIndex);
-    return readh3Index(H3.getOriginH3IndexFromUnidirectionalEdge(lower, upper));
+    return readH3Index(H3.getOriginH3IndexFromUnidirectionalEdge(lower, upper));
 }
@@ -777,3 +829,3 @@
     const [lower, upper] = h3IndexToSplitLong(edgeIndex);
-    return readh3Index(H3.getDestinationH3IndexFromUnidirectionalEdge(lower, upper));
+    return readH3Index(H3.getDestinationH3IndexFromUnidirectionalEdge(lower, upper));
 }
@@ -858,2 +910,88 @@
 
+/**
+ * Produces IJ coordinates for an H3 index anchored by an origin.
+ *
+ * - The coordinate space used by this function may have deleted
+ * regions or warping due to pentagonal distortion.
+ * - Coordinates are only comparable if they come from the same
+ * origin index.
+ * - Failure may occur if the index is too far away from the origin
+ * or if the index is on the other side of a pentagon.
+ * - This function is experimental, and its output is not guaranteed
+ * to be compatible across different versions of H3.
+ * @static
+ * @param  {H3Index} origin      Origin H3 index
+ * @param  {H3Index} destination H3 index for which to find relative coordinates
+ * @return {Object}              Coordinates as an `{i, j}` pair
+ * @throws {Error}               If the IJ coordinates cannot be calculated
+ */
+function experimentalH3ToLocalIj(origin, destination) {
+    const ij = C._malloc(SZ_COORDIJ);
+    const retVal = H3.experimentalH3ToLocalIj(
+        ...h3IndexToSplitLong(origin),
+        ...h3IndexToSplitLong(destination),
+        ij
+    );
+    const coords = readCoordIJ(ij);
+    C._free(ij);
+    // Return the pair, or throw if an error code was returned.
+    // Switch statement and error codes cribbed from h3-java's implementation.
+    switch (retVal) {
+        case 0:
+            return coords;
+        case 1:
+            throw new Error('Incompatible origin and index.');
+        case 2:
+        default:
+            throw new Error(
+                'Local IJ coordinates undefined for this origin and index pair. ' +
+                    'The index may be too far from the origin.'
+            );
+        case 3:
+        case 4:
+        case 5:
+            throw new Error('Encountered possible pentagon distortion');
+    }
+}
+
+/**
+ * Produces an H3 index for IJ coordinates anchored by an origin.
+ *
+ * - The coordinate space used by this function may have deleted
+ * regions or warping due to pentagonal distortion.
+ * - Coordinates are only comparable if they come from the same
+ * origin index.
+ * - Failure may occur if the index is too far away from the origin
+ * or if the index is on the other side of a pentagon.
+ * - This function is experimental, and its output is not guaranteed
+ * to be compatible across different versions of H3.
+ * @static
+ * @param  {H3Index} origin     Origin H3 index
+ * @param  {Object} coords      Coordinates as an `{i, j}` pair
+ * @return {H3Index}            H3 index at the relative coordinates
+ * @throws {Error}              If the H3 index cannot be calculated
+ */
+function experimentalLocalIjToH3(origin, coords) {
+    // Validate input coords
+    if (!coords || typeof coords.i !== 'number' || typeof coords.j !== 'number') {
+        throw new Error('Coordinates must be provided as an {i, j} object');
+    }
+    // Allocate memory for the CoordIJ struct and an H3 index to hold the return value
+    const ij = C._malloc(SZ_COORDIJ);
+    const out = C._malloc(SZ_H3INDEX);
+    storeCoordIJ(ij, coords);
+    const retVal = H3.experimentalLocalIjToH3(...h3IndexToSplitLong(origin), ij, out);
+    const h3Index = readH3IndexFromPointer(out);
+    C._free(ij);
+    C._free(out);
+    if (retVal !== 0) {
+        throw new Error(
+            'Index not defined for this origin and IJ coordinates pair. ' +
+                'IJ coordinates may be too far from origin, or ' +
+                'a pentagon distortion was encountered.'
+        );
+    }
+    return h3Index;
+}
+
 // ----------------------------------------------------------------------------
@@ -972,2 +1110,4 @@ // Public informational utilities
     h3Distance,
+    experimentalH3ToLocalIj,
+    experimentalLocalIjToH3,
     hexArea,
@@ -974,0 +1114,0 @@ edgeLength,

package.json

 {
   "name": "h3-js",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Emscripten transpiled libh3 'bindings' for Node/Web JS",
@@ -31,13 +31,15 @@ "author": "David Ellis <[e-mail]>",
     "cover": "istanbul cover -x out/*.js -- test/index.js",
+    "view-cover": "istanbul cover -x out/*.js --report=html -- test/index.js && open coverage/index.html",
     "check-prettier": "yarn prettier && git diff --exit-code",
     "check-docs": "yarn build-docs && git diff --exit-code",
-    "benchmarks-es6": "node test/benchmarks.js",
     "dist": "yarn dist-clean && mkdir -p dist/out && buble -i lib -o dist/lib && cp out/libh3.js dist/out",
     "dist-clean": "rm -rf dist",
     "dist-test": "yarn dist && buble -i test -o dist/test",
-    "benchmarks": "yarn dist-test && node dist/test/benchmarks.js",
+    "dist-benchmark": "yarn dist && buble -i benchmark -o dist/benchmark",
+    "benchmark-node": "yarn dist-benchmark && node dist/benchmark/node.js",
+    "benchmark-browser": "yarn dist-benchmark && budo dist/benchmark/browser.js -t babelify --open --title 'h3-js benchmarks'",
     "prepublish": "yarn dist",
     "init-docker": "docker run -dit --name emscripten -v $(pwd):/src trzeci/emscripten:sdk-tag-1.37.40-64bit bash",
     "build-emscripten": "docker exec -it emscripten bash .build-emscripten.sh",
-    "build-docs": "jsdoc2md --global-index-format grouped --partial doc-files/scope.hbs --separators --template doc-files/README.tmpl.md lib/h3core.js > README.md",
+    "build-docs": "jsdoc2md --global-index-format grouped --partial doc-files/scope.hbs --helper ./doc-files/insert-version.js --separators --template doc-files/README.tmpl.md lib/h3core.js > README.md",
     "prettier": "prettier --write --single-quote --no-bracket-spacing --print-width=100 'lib/**/*.js' 'build/**/*.js' 'test/**/*.js'"
@@ -48,2 +50,3 @@ },
     "buble": "^0.19.3",
+    "budo": "^11.5.0",
     "eslint": "^4.19.1",
@@ -50,0 +53,0 @@ "eslint-config-prettier": "^2.9.0",

README.md

 # h3-js
 
-[![Build Status](https://travis-ci.org/uber/h3-js.svg?branch=master)](https://travis-ci.org/uber/h3-js) [![Coverage Status](https://coveralls.io/repos/github/uber/h3-js/badge.svg?branch=master)](https://coveralls.io/github/uber/h3-js?branch=master)
+[![H3 Version](https://img.shields.io/badge/h3_api-v3.2.0-blue.svg)](https://github.com/uber/h3/releases/tag/v3.2.0) [![Build Status](https://travis-ci.org/uber/h3-js.svg?branch=master)](https://travis-ci.org/uber/h3-js) [![Coverage Status](https://coveralls.io/repos/github/uber/h3-js/badge.svg?branch=master)](https://coveralls.io/github/uber/h3-js?branch=master)
 
@@ -96,2 +96,4 @@ The `h3-js` library provides a pure-JavaScript version of the [H3 Core Library](https://github.com/uber/h3), 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](http://kripken.github.io/emscripten-site), offering full parity with the C API and highly efficient operations.
     * [.h3Distance(origin, destination)](#module_h3.h3Distance) ⇒ <code>Number</code>
+    * [.experimentalH3ToLocalIj(origin, destination)](#module_h3.experimentalH3ToLocalIj) ⇒ <code>Object</code>
+    * [.experimentalLocalIjToH3(origin, coords)](#module_h3.experimentalLocalIjToH3) ⇒ <code>H3Index</code>
     * [.hexArea(res, unit)](#module_h3.hexArea) ⇒ <code>Number</code>
@@ -517,2 +519,58 @@ * [.edgeLength(res, unit)](#module_h3.edgeLength) ⇒ <code>Number</code>
 
+<a name="module_h3.experimentalH3ToLocalIj"></a>
+
+### h3.experimentalH3ToLocalIj(origin, destination) ⇒ <code>Object</code>
+Produces IJ coordinates for an H3 index anchored by an origin.
+
+- The coordinate space used by this function may have deleted
+regions or warping due to pentagonal distortion.
+- Coordinates are only comparable if they come from the same
+origin index.
+- Failure may occur if the index is too far away from the origin
+or if the index is on the other side of a pentagon.
+- This function is experimental, and its output is not guaranteed
+to be compatible across different versions of H3.
+
+**Returns**: <code>Object</code> - Coordinates as an `{i, j}` pair  
+**Throws**:
+
+- <code>Error</code> If the IJ coordinates cannot be calculated
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| origin | <code>H3Index</code> | Origin H3 index |
+| destination | <code>H3Index</code> | H3 index for which to find relative coordinates |
+
+
+* * *
+
+<a name="module_h3.experimentalLocalIjToH3"></a>
+
+### h3.experimentalLocalIjToH3(origin, coords) ⇒ <code>H3Index</code>
+Produces an H3 index for IJ coordinates anchored by an origin.
+
+- The coordinate space used by this function may have deleted
+regions or warping due to pentagonal distortion.
+- Coordinates are only comparable if they come from the same
+origin index.
+- Failure may occur if the index is too far away from the origin
+or if the index is on the other side of a pentagon.
+- This function is experimental, and its output is not guaranteed
+to be compatible across different versions of H3.
+
+**Returns**: <code>H3Index</code> - H3 index at the relative coordinates  
+**Throws**:
+
+- <code>Error</code> If the H3 index cannot be calculated
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| origin | <code>H3Index</code> | Origin H3 index |
+| coords | <code>Object</code> | Coordinates as an `{i, j}` pair |
+
+
+* * *
+
 <a name="module_h3.hexArea"></a>
@@ -519,0 +577,0 @@

New alerts

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

588974

increased by22.97%

Number of package files

24

increased by20%

Lines of code

3608

increased by14.39%

Number of lines in readme file

724

increased by8.71%

Worsened metrics

Dev dependency count

12

increased by9.09%

Number of low supply chain risk alerts

5

increased by25%

No dependency changes