h3 3.6.1 → 3.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32f9595b2e8746f59aaef1c082fc3527a7eb3d7594d7eac1a59cb5875df6af3d
-  data.tar.gz: 8fd9c4ed2317a0211b4d3fa6360aede580bff5db691605b7fdd33b299720ba3f
+  metadata.gz: c5f225736d5df411fd63eb2cad74c153ba96d6a659cf603ba781bab3497dfcc9
+  data.tar.gz: cc45bd99735019ae9d8442ca948df0ce64dd70aa82fa47eabfe2966ea0d76ea2
 SHA512:
-  metadata.gz: 4e0a51a2bdcf92096406af99d3823359768b99291f96be9ac6d113363c09efb71513cf09944eca1155549b63bbab4c628e2a6f89f8d77817df4029155375072e
-  data.tar.gz: 1c672e3d6d2262dee4bae5bf65587a870c9053b1815ec7ee34798fae228aed5bd338d57883ebb594f81b6c959006af86c460ddca473e4db401631e2400a11dcd
+  metadata.gz: 84d534f96a5772628a642ac773224af9d907319a4a576cbb7c772773ba8b2ea3814c9118b90e69f617834484b7e10f117da9f9f4a98be99124238ba105532767
+  data.tar.gz: '098daf9d6a37dfe0a1a7b4458a2d9875ff9456c1f264b61328006f7bc45ac91031f6f24aebd508c1826e884b9f0cbf457daf75691026da83031bf0312d7dd422'

data/CHANGELOG.md

@@ -6,6 +6,18 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 We track the MAJOR and MINOR version levels of Uber's H3 project (https://github.com/uber/h3) but maintain independent patch levels so we can make small fixes and non breaking changes.
 
+## [3.6.2] - 2020-1-8
+### Changed
+- Revert new polyfill algorithm until reported issues are fixed.
+- Remove deprecated methods: (#66)
+
+## [3.6.1] - 2019-11-23
+### Fixed
+- `compact` handles zero length input correctly.
+- `bboxHexRadius` scaling factor adjusted to guarantee containment for `polyfill`.
+- `polyfill` new algorithm for up to 3x perf boost.
+- Fix CMake targets for KML generation.
+
 ## [3.6.0] - 2019-8-14
 ### Added
 - `center_child` method to find center child at given resolution (#62).

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    h3 (3.6.1)
+    h3 (3.6.2)
       ffi (~> 1.9)
       rgeo-geojson (~> 2.1)
       zeitwerk (~> 2.1)
@@ -17,7 +17,7 @@ GEM
       tins (~> 1.6)
     diff-lcs (1.3)
     docile (1.3.1)
-    ffi (1.11.2)
+    ffi (1.11.3)
     json (2.1.0)
     rake (12.3.2)
     rgeo (2.1.1)
@@ -46,7 +46,7 @@ GEM
     thor (0.19.4)
     tins (1.20.2)
     yard (0.9.20)
-    zeitwerk (2.2.1)
+    zeitwerk (2.2.2)
 
 PLATFORMS
   ruby
@@ -59,4 +59,4 @@ DEPENDENCIES
   yard (~> 0.9)
 
 BUNDLED WITH
-   1.17.2
+   1.17.3

data/ext/h3/src/.travis.yml

@@ -31,7 +31,7 @@ addons:
 matrix:
   include:
       # Check that clang-format doesn't detect some files are not formatted.
-    - env: NAME="Formatting check"
+    - name: "Formatting check"
       compiler: clang
       addons:
         apt:
@@ -41,7 +41,7 @@ matrix:
             - clang-format-5.0
       script: make format && git diff --exit-code
       # Submit coverage report to Coveralls.io, also test that prefixing works.
-    - env: NAME="Coverage report"
+    - name: "Coverage and FOSSA report"
       compiler: gcc
       addons:
         apt:
@@ -50,12 +50,20 @@ matrix:
       install:
         - gem install coveralls-lcov
       before_script:
+        - "curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | sudo bash"
         - cmake -DCMAKE_BUILD_TYPE=Debug -DWARNINGS_AS_ERRORS=ON -DH3_PREFIX=testprefix_ .
       script:
-        - make && make coverage
+        - make
+        - make coverage
+        # Test building the website also - needed for FOSSA to pick up dependencies
+        - cd website
+        - npm install
+        - npm run build
+        - cd ..
+        - 'if [ -n "$FOSSA_API_KEY" ]; then fossa; fi'
       after_success:
         - coveralls-lcov coverage.cleaned.info
-    - env: NAME="Valgrind test"
+    - name: "Valgrind test"
       compiler: gcc
       addons:
         apt:
@@ -66,9 +74,9 @@ matrix:
       script:
         - make
         - CTEST_OUTPUT_ON_FAILURE=1 make test-fast
-    - env: NAME="Mac OSX (Xcode 8)"
+    - name: "Mac OSX (Xcode 8)"
       os: osx
-    - env: NAME="binding-functions target"
+    - name: "binding-functions target"
       script:
         - make binding-functions
         # Check that the file exists and has contents

data/ext/h3/src/CHANGELOG.md

@@ -7,6 +7,9 @@ The public API of this library consists of the functions declared in file
 
 ## [Unreleased]
 
+## [3.6.2] - 2019-12-9
+- Revert new `polyfill` algorithm until reported issues are fixed. (#293)
+
 ## [3.6.1] - 2019-11-11
 ### Fixed
 - `compact` handles zero length input correctly. (#278)

data/ext/h3/src/VERSION

@@ -1 +1 @@
-3.6.1
+3.6.2

data/ext/h3/src/src/apps/testapps/testPolyfill.c

@@ -64,13 +64,13 @@ SUITE(polyfill) {
 
     TEST(maxPolyfillSize) {
         int numHexagons = H3_EXPORT(maxPolyfillSize)(&sfGeoPolygon, 9);
-        t_assert(numHexagons == 3457, "got expected max polyfill size");
+        t_assert(numHexagons == 7057, "got expected max polyfill size");
 
         numHexagons = H3_EXPORT(maxPolyfillSize)(&holeGeoPolygon, 9);
-        t_assert(numHexagons == 3457, "got expected max polyfill size (hole)");
+        t_assert(numHexagons == 7057, "got expected max polyfill size (hole)");
 
         numHexagons = H3_EXPORT(maxPolyfillSize)(&emptyGeoPolygon, 9);
-        t_assert(numHexagons == 3, "got expected max polyfill size (empty)");
+        t_assert(numHexagons == 1, "got expected max polyfill size (empty)");
     }
 
     TEST(polyfill) {

data/ext/h3/src/src/h3lib/include/algos.h

@@ -40,12 +40,4 @@ void h3SetToVertexGraph(const H3Index* h3Set, const int numHexes,
 // Create a LinkedGeoPolygon from a vertex graph
 void _vertexGraphToLinkedGeo(VertexGraph* graph, LinkedGeoPolygon* out);
 
-// Internal function for polyfill that traces a geofence with hexagons of a
-// specific size
-int _getEdgeHexagons(const Geofence* geofence, int numHexagons, int res,
-                     int* numSearchHexes, H3Index* search, H3Index* found);
-
-// The new polyfill algorithm. Separated out because it can theoretically fail
-int _polyfillInternal(const GeoPolygon* geoPolygon, int res, H3Index* out);
-
 #endif

data/ext/h3/src/src/h3lib/include/bbox.h

@@ -37,8 +37,6 @@ bool bboxIsTransmeridian(const BBox* bbox);
 void bboxCenter(const BBox* bbox, GeoCoord* center);
 bool bboxContains(const BBox* bbox, const GeoCoord* point);
 bool bboxEquals(const BBox* b1, const BBox* b2);
-int bboxHexEstimate(const BBox* bbox, int res);
-int lineHexEstimate(const GeoCoord* origin, const GeoCoord* destination,
-                    int res);
+int bboxHexRadius(const BBox* bbox, int res);
 
 #endif

data/ext/h3/src/src/h3lib/lib/algos.c

@@ -41,7 +41,6 @@
 #define HEX_RANGE_SUCCESS 0
 #define HEX_RANGE_PENTAGON 1
 #define HEX_RANGE_K_SUBSEQUENCE 2
-#define MAX_ONE_RING_SIZE 7
 
 /**
  * Directions used for traversing a hexagonal ring counterclockwise around
@@ -624,8 +623,9 @@ int H3_EXPORT(hexRing)(H3Index origin, int k, H3Index* out) {
  * maxPolyfillSize returns the number of hexagons to allocate space for when
  * performing a polyfill on the given GeoJSON-like data structure.
  *
- * The size is the maximum of either the number of points in the geofence or the
- * number of hexagons in the bounding box of the geofence.
+ * Currently a laughably padded response, being a k-ring that wholly contains
+ * a bounding box of the GeoJSON, but still less wasted memory than initializing
+ * a Python application? ;)
  *
  * @param geoPolygon A GeoJSON-like data structure indicating the poly to fill
  * @param res Hexagon resolution (0-15)
@@ -634,18 +634,12 @@ int H3_EXPORT(hexRing)(H3Index origin, int k, H3Index* out) {
 int H3_EXPORT(maxPolyfillSize)(const GeoPolygon* geoPolygon, int res) {
     // Get the bounding box for the GeoJSON-like struct
     BBox bbox;
-    const Geofence geofence = geoPolygon->geofence;
-    bboxFromGeofence(&geofence, &bbox);
-    int numHexagons = bboxHexEstimate(&bbox, res);
-    // This algorithm assumes that the number of vertices is usually less than
-    // the number of hexagons, but when it's wrong, this will keep it from
-    // failing
-    int totalVerts = geofence.numVerts;
-    for (int i = 0; i < geoPolygon->numHoles; i++) {
-        totalVerts += geoPolygon->holes[i].numVerts;
-    }
-    if (numHexagons < totalVerts) numHexagons = totalVerts;
-    return numHexagons;
+    bboxFromGeofence(&geoPolygon->geofence, &bbox);
+    int minK = bboxHexRadius(&bbox, res);
+
+    // The total number of hexagons to allocate can now be determined by
+    // the k-ring hex allocation helper function.
+    return H3_EXPORT(maxKringSize)(minK);
 }
 
 /**
@@ -653,108 +647,15 @@ int H3_EXPORT(maxPolyfillSize)(const GeoPolygon* geoPolygon, int res) {
  * zeroed memory, and fills it with the hexagons that are contained by
  * the GeoJSON-like data structure.
  *
- * This implementation traces the GeoJSON geofence(s) in cartesian space with
- * hexagons, tests them and their neighbors to be contained by the geofence(s),
- * and then any newly found hexagons are used to test again until no new
- * hexagons are found.
+ * The current implementation is very primitive and slow, but correct,
+ * performing a point-in-poly operation on every hexagon in a k-ring defined
+ * around the given geofence.
  *
  * @param geoPolygon The geofence and holes defining the relevant area
  * @param res The Hexagon resolution (0-15)
  * @param out The slab of zeroed memory to write to. Assumed to be big enough.
  */
 void H3_EXPORT(polyfill)(const GeoPolygon* geoPolygon, int res, H3Index* out) {
-    // TODO: Eliminate this wrapper with the H3 4.0.0 release
-    int failure = _polyfillInternal(geoPolygon, res, out);
-    // The polyfill algorithm can theoretically fail if the allocated memory is
-    // not large enough for the polygon, but this should be impossible given the
-    // conservative overestimation of the number of hexagons possible.
-    // LCOV_EXCL_START
-    if (failure) {
-        int numHexagons = H3_EXPORT(maxPolyfillSize)(geoPolygon, res);
-        for (int i = 0; i < numHexagons; i++) out[i] = H3_INVALID_INDEX;
-    }
-    // LCOV_EXCL_STOP
-}
-
-/**
- * _getEdgeHexagons takes a given geofence ring (either the main geofence or
- * one of the holes) and traces it with hexagons and updates the search and
- * found memory blocks. This is used for determining the initial hexagon set
- * for the polyfill algorithm to execute on.
- *
- * @param geofence The geofence (or hole) to be traced
- * @param numHexagons The maximum number of hexagons possible for the geofence
- *                    (also the bounds of the search and found arrays)
- * @param res The hexagon resolution (0-15)
- * @param numSearchHexes The number of hexagons found so far to be searched
- * @param search The block of memory containing the hexagons to search from
- * @param found The block of memory containing the hexagons found from the
- * search
- *
- * @return An error code if the hash function cannot insert a found hexagon
- *         into the found array.
- */
-int _getEdgeHexagons(const Geofence* geofence, int numHexagons, int res,
-                     int* numSearchHexes, H3Index* search, H3Index* found) {
-    for (int i = 0; i < geofence->numVerts; i++) {
-        GeoCoord origin = geofence->verts[i];
-        GeoCoord destination = i == geofence->numVerts - 1
-                                   ? geofence->verts[0]
-                                   : geofence->verts[i + 1];
-        const int numHexesEstimate =
-            lineHexEstimate(&origin, &destination, res);
-        for (int j = 0; j < numHexesEstimate; j++) {
-            GeoCoord interpolate;
-            interpolate.lat =
-                (origin.lat * (numHexesEstimate - j) / numHexesEstimate) +
-                (destination.lat * j / numHexesEstimate);
-            interpolate.lon =
-                (origin.lon * (numHexesEstimate - j) / numHexesEstimate) +
-                (destination.lon * j / numHexesEstimate);
-            H3Index pointHex = H3_EXPORT(geoToH3)(&interpolate, res);
-            // A simple hash to store the hexagon, or move to another place if
-            // needed
-            int loc = (int)(pointHex % numHexagons);
-            int loopCount = 0;
-            while (found[loc] != 0) {
-                // If this conditional is reached, the `found` memory block is
-                // too small for the given polygon. This should not happen.
-                if (loopCount > numHexagons) return -1;  // LCOV_EXCL_LINE
-                if (found[loc] == pointHex)
-                    break;  // At least two points of the geofence index to the
-                            // same cell
-                loc = (loc + 1) % numHexagons;
-                loopCount++;
-            }
-            if (found[loc] == pointHex)
-                continue;  // Skip this hex, already exists in the found hash
-            // Otherwise, set it in the found hash for now
-            found[loc] = pointHex;
-
-            search[*numSearchHexes] = pointHex;
-            (*numSearchHexes)++;
-        }
-    }
-    return 0;
-}
-
-/**
- * _polyfillInternal traces the provided geoPolygon data structure with hexagons
- * and then iteratively searches through these hexagons and their immediate
- * neighbors to see if they are contained within the polygon or not. Those that
- * are found are added to the out array as well as the found array. Once all
- * hexagons to search are checked, the found hexagons become the new search
- * array and the found array is wiped and the process repeats until no new
- * hexagons can be found.
- *
- * @param geoPolygon The geofence and holes defining the relevant area
- * @param res The Hexagon resolution (0-15)
- * @param out The slab of zeroed memory to write to. Assumed to be big enough.
- *
- * @return An error code if any of the hash operations fails to insert a hexagon
- *         into an array of memory.
- */
-int _polyfillInternal(const GeoPolygon* geoPolygon, int res, H3Index* out) {
     // One of the goals of the polyfill algorithm is that two adjacent polygons
     // with zero overlap have zero overlapping hexagons. That the hexagons are
     // uniquely assigned. There are a few approaches to take here, such as
@@ -776,139 +677,36 @@ int _polyfillInternal(const GeoPolygon* geoPolygon, int res, H3Index* out) {
     BBox* bboxes = malloc((geoPolygon->numHoles + 1) * sizeof(BBox));
     assert(bboxes != NULL);
     bboxesFromGeoPolygon(geoPolygon, bboxes);
-
-    // Get the estimated number of hexagons and allocate some temporary memory
-    // for the hexagons
-    int numHexagons = H3_EXPORT(maxPolyfillSize)(geoPolygon, res);
-    H3Index* search = calloc(numHexagons, sizeof(H3Index));
-    H3Index* found = calloc(numHexagons, sizeof(H3Index));
-
-    // Some metadata for tracking the state of the search and found memory
-    // blocks
-    int numSearchHexes = 0;
-    int numFoundHexes = 0;
-
-    // 1. Trace the hexagons along the polygon defining the outer geofence and
-    // add them to the search hash. The hexagon containing the geofence point
-    // may or may not be contained by the geofence (as the hexagon's center
-    // point may be outside of the boundary.)
-    const Geofence geofence = geoPolygon->geofence;
-    int failure = _getEdgeHexagons(&geofence, numHexagons, res, &numSearchHexes,
-                                   search, found);
-    // If this branch is reached, we have exceeded the maximum number of
-    // hexagons possible and need to clean up the allocated memory.
-    // LCOV_EXCL_START
-    if (failure) {
-        free(search);
-        free(found);
-        free(bboxes);
-        return failure;
-    }
-    // LCOV_EXCL_STOP
-
-    // 2. Iterate over all holes, trace the polygons defining the holes with
-    // hexagons and add to only the search hash. We're going to temporarily use
-    // the `found` hash to use for dedupe purposes and then re-zero it once
-    // we're done here, otherwise we'd have to scan the whole set on each insert
-    // to make sure there's no duplicates, which is very inefficient.
-    for (int i = 0; i < geoPolygon->numHoles; i++) {
-        Geofence* hole = &(geoPolygon->holes[i]);
-        failure = _getEdgeHexagons(hole, numHexagons, res, &numSearchHexes,
-                                   search, found);
-        // If this branch is reached, we have exceeded the maximum number of
-        // hexagons possible and need to clean up the allocated memory.
-        // LCOV_EXCL_START
-        if (failure) {
-            free(search);
-            free(found);
-            free(bboxes);
-            return failure;
+    int minK = bboxHexRadius(&bboxes[0], res);
+    int numHexagons = H3_EXPORT(maxKringSize)(minK);
+
+    // Get the center hex
+    GeoCoord center;
+    bboxCenter(&bboxes[0], &center);
+    H3Index centerH3 = H3_EXPORT(geoToH3)(&center, res);
+
+    // From here on it works differently, first we get all potential
+    // hexagons inserted into the available memory
+    H3_EXPORT(kRing)(centerH3, minK, out);
+
+    // Next we iterate through each hexagon, and test its center point to see if
+    // it's contained in the GeoJSON-like struct
+    for (int i = 0; i < numHexagons; i++) {
+        // Skip records that are already zeroed
+        if (out[i] == 0) {
+            continue;
         }
-        // LCOV_EXCL_STOP
-    }
-
-    // 3. Re-zero the found hash so it can be used in the main loop below
-    for (int i = 0; i < numHexagons; i++) found[i] = 0;
-
-    // 4. Begin main loop. While the search hash is not empty do the following
-    while (numSearchHexes > 0) {
-        // Iterate through all hexagons in the current search hash, then loop
-        // through all neighbors and test Point-in-Poly, if point-in-poly
-        // succeeds, add to out and found hashes if not already there.
-        int currentSearchNum = 0;
-        int i = 0;
-        while (currentSearchNum < numSearchHexes) {
-            H3Index ring[MAX_ONE_RING_SIZE] = {0};
-            H3Index searchHex = search[i];
-            H3_EXPORT(kRing)(searchHex, 1, ring);
-            for (int j = 0; j < MAX_ONE_RING_SIZE; j++) {
-                if (ring[j] == H3_INVALID_INDEX) {
-                    continue;  // Skip if this was a pentagon and only had 5
-                               // neighbors
-                }
-
-                H3Index hex = ring[j];
-
-                // A simple hash to store the hexagon, or move to another place
-                // if needed. This MUST be done before the point-in-poly check
-                // since that's far more expensive
-                int loc = (int)(hex % numHexagons);
-                int loopCount = 0;
-                while (out[loc] != 0) {
-                    // If this branch is reached, we have exceeded the maximum
-                    // number of hexagons possible and need to clean up the
-                    // allocated memory.
-                    // LCOV_EXCL_START
-                    if (loopCount > numHexagons) {
-                        free(search);
-                        free(found);
-                        free(bboxes);
-                        return -1;
-                    }
-                    // LCOV_EXCL_STOP
-                    if (out[loc] == hex) break;  // Skip duplicates found
-                    loc = (loc + 1) % numHexagons;
-                    loopCount++;
-                }
-                if (out[loc] == hex) {
-                    continue;  // Skip this hex, already exists in the out hash
-                }
-
-                // Check if the hexagon is in the polygon or not
-                GeoCoord hexCenter;
-                H3_EXPORT(h3ToGeo)(hex, &hexCenter);
-
-                // If not, skip
-                if (!pointInsidePolygon(geoPolygon, bboxes, &hexCenter)) {
-                    continue;
-                }
-
-                // Otherwise set it in the output array
-                out[loc] = hex;
-
-                // Set the hexagon in the found hash
-                found[numFoundHexes] = hex;
-                numFoundHexes++;
-            }
-            currentSearchNum++;
-            i++;
+        // Check if hexagon is inside of polygon
+        GeoCoord hexCenter;
+        H3_EXPORT(h3ToGeo)(out[i], &hexCenter);
+        hexCenter.lat = constrainLat(hexCenter.lat);
+        hexCenter.lon = constrainLng(hexCenter.lon);
+        // And remove from list if not
+        if (!pointInsidePolygon(geoPolygon, bboxes, &hexCenter)) {
+            out[i] = H3_INVALID_INDEX;
         }
-
-        // Swap the search and found pointers, copy the found hex count to the
-        // search hex count, and zero everything related to the found memory.
-        H3Index* temp = search;
-        search = found;
-        found = temp;
-        for (int j = 0; j < numSearchHexes; j++) found[j] = 0;
-        numSearchHexes = numFoundHexes;
-        numFoundHexes = 0;
-        // Repeat until no new hexagons are found
     }
-    // The out memory structure should be complete, end it here
     free(bboxes);
-    free(search);
-    free(found);
-    return 0;
 }
 
 /**

data/ext/h3/src/src/h3lib/lib/bbox.c

@@ -88,59 +88,38 @@ double _hexRadiusKm(H3Index h3Index) {
 }
 
 /**
- * bboxHexEstimate returns an estimated number of hexagons that fit
- *                 within the cartesian-projected bounding box
- *
- * @param bbox the bounding box to estimate the hexagon fill level
- * @param res the resolution of the H3 hexagons to fill the bounding box
- * @return the estimated number of hexagons to fill the bounding box
+ * Get the radius of the bbox in hexagons - i.e. the radius of a k-ring centered
+ * on the bbox center and covering the entire bbox.
+ * @param  bbox Bounding box to measure
+ * @param  res  Resolution of hexagons to use in measurement
+ * @return      Radius in hexagons
  */
-int bboxHexEstimate(const BBox* bbox, int res) {
-    // Get the area of the pentagon as the maximally-distorted area possible
-    H3Index pentagons[12] = {0};
-    H3_EXPORT(getPentagonIndexes)(res, pentagons);
-    double pentagonRadiusKm = _hexRadiusKm(pentagons[0]);
-    // Area of a regular hexagon is 3/2*sqrt(3) * r * r
-    // The pentagon has the most distortion (smallest edges) and shares its
-    // edges with hexagons, so the most-distorted hexagons have this area
-    double pentagonAreaKm2 =
-        2.59807621135 * pentagonRadiusKm * pentagonRadiusKm;
+int bboxHexRadius(const BBox* bbox, int res) {
+    // Determine the center of the bounding box
+    GeoCoord center;
+    bboxCenter(bbox, &center);
 
-    // Then get the area of the bounding box of the geofence in question
-    GeoCoord p1, p2;
-    p1.lat = bbox->north;
-    p1.lon = bbox->east;
-    p2.lat = bbox->south;
-    p2.lon = bbox->east;
-    double h = _geoDistKm(&p1, &p2);
-    p2.lat = bbox->north;
-    p2.lon = bbox->west;
-    double w = _geoDistKm(&p1, &p2);
+    // Use a vertex on the side closest to the equator, to ensure the longest
+    // radius in cases with significant distortion. East/west is arbitrary.
+    double lat =
+        fabs(bbox->north) > fabs(bbox->south) ? bbox->south : bbox->north;
+    GeoCoord vertex = {lat, bbox->east};
 
-    // Divide the two to get an estimate of the number of hexagons needed
-    int estimate = (int)ceil(w * h / pentagonAreaKm2);
-    if (estimate == 0) estimate = 1;
-    return estimate;
-}
+    // Determine the length of the bounding box "radius" to then use
+    // as a circle on the earth that the k-rings must be greater than
+    double bboxRadiusKm = _geoDistKm(&center, &vertex);
 
-/**
- * lineHexEstimate returns an estimated number of hexagons that trace
- *                 the cartesian-projected line
- *
- *  @param origin the origin coordinates
- *  @param destination the destination coordinates
- *  @param res the resolution of the H3 hexagons to trace the line
- *  @return the estimated number of hexagons required to trace the line
- */
-int lineHexEstimate(const GeoCoord* origin, const GeoCoord* destination,
-                    int res) {
-    // Get the area of the pentagon as the maximally-distorted area possible
-    H3Index pentagons[12] = {0};
-    H3_EXPORT(getPentagonIndexes)(res, pentagons);
-    double pentagonRadiusKm = _hexRadiusKm(pentagons[0]);
+    // Determine the radius of the center hexagon
+    double centerHexRadiusKm = _hexRadiusKm(H3_EXPORT(geoToH3)(&center, res));
 
-    double dist = _geoDistKm(origin, destination);
-    int estimate = (int)ceil(dist / (2 * pentagonRadiusKm));
-    if (estimate == 0) estimate = 1;
-    return estimate;
+    // We use centerHexRadiusKm un-scaled and rounded *up* to guarantee
+    // containment ot the bbox.  Ideal, undistorted hexagons could scale
+    // centerHexRadiusKm by a factor of up to 1.5, reducing bboxHexRadius.
+    // This is because the closest point along an undistorted hexagon drawn
+    // through the center points of a k-ring aggregation is exactly 1.5 radii
+    // of the hexagon.  But there is distortion near pentagons, and for those
+    // cases, the scaling needs to be less than 1.5.  Using the un-scaled value
+    // conservatively guarantees containment for all cases, at the expense of a
+    // larger bboxHexRadius.
+    return (int)ceil(bboxRadiusKm / centerHexRadiusKm);
 }

data/lib/h3/bindings/base.rb

@@ -12,11 +12,21 @@ module H3
         base.include Types
         base.ffi_lib ["#{lib_path}/libh3.dylib", "#{lib_path}/libh3.so"]
         base.typedef :ulong_long, :h3_index
-        base.typedef :int, :size
         base.typedef :int, :k_distance
-        base.typedef :pointer, :h3_set
-        base.typedef :pointer, :output_buffer
-        base.const_set("H3_INDEX", :ulong_long)
+      end
+
+      def attach_predicate_function(name, *args)
+        stripped_name = name.to_s.gsub("?", "")
+        attach_function(stripped_name, *args).tap do
+          rename_function stripped_name, name
+        end
+      end
+
+      private
+
+      def rename_function(from, to)
+        alias_method to, from
+        undef_method from
       end
     end
   end

data/lib/h3/bindings/private.rb

@@ -7,11 +7,11 @@ module H3
     module Private
       extend H3::Bindings::Base
 
-      attach_function :compact, [H3IndexesIn, H3IndexesOut, :size], :bool
+      attach_function :compact, [H3IndexesIn, H3IndexesOut, :size_t], :bool
       attach_function :destroy_linked_polygon, :destroyLinkedPolygon, [LinkedGeoPolygon], :void
       attach_function :geo_to_h3, :geoToH3, [GeoCoord, Resolution], :h3_index
       attach_function :get_pentagon_indexes, :getPentagonIndexes, [:int, H3IndexesOut], :void
-      attach_function :h3_faces, :h3GetFaces, %i[h3_index output_buffer], :void
+      attach_function :h3_faces, :h3GetFaces, %i[h3_index buffer_out], :void
       attach_function :h3_indexes_from_unidirectional_edge,
                       :getH3IndexesFromUnidirectionalEdge,
                       [:h3_index, H3IndexesOut], :void
@@ -21,11 +21,11 @@ module H3
                       [:h3_index, H3IndexesOut], :void
       attach_function :h3_set_to_linked_geo,
                       :h3SetToLinkedGeo,
-                      [H3IndexesIn, :size, LinkedGeoPolygon],
+                      [H3IndexesIn, :size_t, LinkedGeoPolygon],
                       :void
       attach_function :h3_to_children, :h3ToChildren, [:h3_index, Resolution, H3IndexesOut], :void
       attach_function :h3_to_geo, :h3ToGeo, [:h3_index, GeoCoord], :void
-      attach_function :h3_to_string, :h3ToString, %i[h3_index output_buffer size], :void
+      attach_function :h3_to_string, :h3ToString, %i[h3_index buffer_out size_t], :void
       attach_function :h3_to_geo_boundary,
                       :h3ToGeoBoundary,
                       [:h3_index, GeoBoundary],
@@ -36,25 +36,25 @@ module H3
       attach_function :hex_range, :hexRange, [:h3_index, :k_distance, H3IndexesOut], :bool
       attach_function :hex_range_distances,
                       :hexRangeDistances,
-                      [:h3_index, :k_distance, H3IndexesOut, :output_buffer], :bool
+                      [:h3_index, :k_distance, H3IndexesOut, :buffer_out], :bool
       attach_function :hex_ranges,
                       :hexRanges,
-                      [H3IndexesIn, :size, :k_distance, H3IndexesOut],
+                      [H3IndexesIn, :size_t, :k_distance, H3IndexesOut],
                       :bool
       attach_function :hex_ring, :hexRing, [:h3_index, :k_distance, H3IndexesOut], :bool
       attach_function :k_ring, :kRing, [:h3_index, :k_distance, H3IndexesOut], :void
       attach_function :k_ring_distances,
                       :kRingDistances,
-                      [:h3_index, :k_distance, H3IndexesOut, :output_buffer],
+                      [:h3_index, :k_distance, H3IndexesOut, :buffer_out],
                       :bool
       attach_function :max_polyfill_size,
                       :maxPolyfillSize,
                       [GeoPolygon, Resolution],
                       :int
-      attach_function :max_uncompact_size, :maxUncompactSize, [H3IndexesIn, :size, Resolution], :int
+      attach_function :max_uncompact_size, :maxUncompactSize, [H3IndexesIn, :size_t, Resolution], :int
       attach_function :polyfill, [GeoPolygon, Resolution, H3IndexesOut], :void
       attach_function :res_0_indexes, :getRes0Indexes, [H3IndexesOut], :void
-      attach_function :uncompact, [H3IndexesIn, :size, H3IndexesOut, :size, Resolution], :bool
+      attach_function :uncompact, [H3IndexesIn, :size_t, H3IndexesOut, :size_t, Resolution], :bool
     end
   end
 end

data/lib/h3/hierarchy.rb

@@ -19,12 +19,6 @@ module H3
     # @return [Integer] H3 index of parent hexagon.
     attach_function :parent, :h3ToParent, [:h3_index, Resolution], :h3_index
 
-    # @deprecated Please use {#parent} instead.
-    def h3_to_parent(h3_index, resolution)
-      parent(h3_index, resolution)
-    end
-    deprecate :h3_to_parent, :parent, 2020, 1
-
     # @!method max_children(h3_index, child_resolution)
     #
     # Derive maximum number of child hexagons possible at given resolution.
@@ -54,12 +48,6 @@ module H3
     # @return [Integer] H3 index of center child hexagon.
     attach_function :center_child, :h3ToCenterChild, [:h3_index, Resolution], :h3_index
 
-    # @deprecated Please use {#max_children} instead.
-    def max_h3_to_children_size(h3_index, resolution)
-      max_children(h3_index, resolution)
-    end
-    deprecate :max_h3_to_children_size, :max_children, 2020, 1
-
     # Derive child hexagons contained within the hexagon at the given H3 index.
     #
     # @param [Integer] h3_index A valid H3 index.
@@ -80,12 +68,6 @@ module H3
       out.read
     end
 
-    # @deprecated Please use {#children} instead.
-    def h3_to_children(h3_index, resolution)
-      children(h3_index, resolution)
-    end
-    deprecate :h3_to_children, :children, 2020, 1
-
     # Find the maximum uncompacted size of the given set of H3 indexes.
     #
     # @param [Array<Integer>] compacted_set An array of valid H3 indexes.

data/lib/h3/indexing.rb

@@ -35,12 +35,6 @@ module H3
       Bindings::Private.geo_to_h3(coords, resolution)
     end
 
-    # @deprecated Please use {#from_geo_coordinates} instead.
-    def geo_to_h3(coords, resolution)
-      from_geo_coordinates(coords, resolution)
-    end
-    deprecate :geo_to_h3, :from_geo_coordinates, 2020, 1
-
     # Derive coordinates for a given H3 index.
     #
     # The coordinates map to the centre of the hexagon at the given index.
@@ -58,12 +52,6 @@ module H3
       [rads_to_degs(coords[:lat]), rads_to_degs(coords[:lon])]
     end
 
-    # @deprecated Please use {#to_geo_coordinates} instead.
-    def h3_to_geo(h3_index)
-      to_geo_coordinates(h3_index)
-    end
-    deprecate :h3_to_geo, :to_geo_coordinates, 2020, 1
-
     # Derive the geographical boundary as coordinates for a given H3 index.
     #
     # This will be a set of 6 coordinate pairs matching the vertexes of the
@@ -89,11 +77,5 @@ module H3
         [rads_to_degs(d[:lat]), rads_to_degs(d[:lon])]
       end
     end
-
-    # @deprecated Please use {#to_boundary} instead.
-    def h3_to_geo_boundary(h3_index)
-      to_boundary(h3_index)
-    end
-    deprecate :h3_to_geo_boundary, :to_boundary, 2020, 1
   end
 end

data/lib/h3/inspection.rb

@@ -21,12 +21,6 @@ module H3
     # @return [Integer] Resolution of H3 index
     attach_function :resolution, :h3GetResolution, %i[h3_index], Resolution
 
-    # @deprecated Please use {#resolution} instead.
-    def h3_resolution(h3_index)
-      resolution(h3_index)
-    end
-    deprecate :h3_resolution, :resolution, 2020, 1
-
     # @!method base_cell(h3_index)
     #
     # Derives the base cell number of the given H3 index
@@ -40,12 +34,6 @@ module H3
     # @return [Integer] Base cell number
     attach_function :base_cell, :h3GetBaseCell, %i[h3_index], :int
 
-    # @deprecated Please use {#base_cell} instead.
-    def h3_base_cell(h3_index)
-      base_cell(h3_index)
-    end
-    deprecate :h3_base_cell, :base_cell, 2020, 1
-
     # @!method from_string(h3_string)
     #
     # Derives the H3 index for a given hexadecimal string representation.
@@ -59,12 +47,6 @@ module H3
     # @return [Integer] H3 index
     attach_function :from_string, :stringToH3, %i[string], :h3_index
 
-    # @deprecated Please use {#from_string} instead.
-    def string_to_h3(string)
-      from_string(string)
-    end
-    deprecate :string_to_h3, :from_string, 2020, 1
-
     # @!method pentagon?(h3_index)
     #
     # Determine whether the given H3 index is a pentagon.
@@ -76,15 +58,7 @@ module H3
     #   true
     #
     # @return [Boolean] True if the H3 index is a pentagon.
-    attach_function :pentagon, :h3IsPentagon, %i[h3_index], :bool
-    alias_method :pentagon?, :pentagon
-    undef_method :pentagon
-
-    # @deprecated Please use {#pentagon?} instead.
-    def h3_pentagon?(h3_index)
-      pentagon?(h3_index)
-    end
-    deprecate :h3_pentagon?, :pentagon?, 2020, 1
+    attach_predicate_function :pentagon?, :h3IsPentagon, %i[h3_index], :bool
 
     # @!method class_3_resolution?(h3_index)
     #
@@ -98,15 +72,7 @@ module H3
     #   true
     #
     # @return [Boolean] True if the H3 index has a class III resolution.
-    attach_function :class_3_resolution, :h3IsResClassIII, %i[h3_index], :bool
-    alias_method :class_3_resolution?, :class_3_resolution
-    undef_method :class_3_resolution
-
-    # @deprecated Please use {#class_3_resolution?} instead.
-    def h3_res_class_3?(h3_index)
-      class_3_resolution?(h3_index)
-    end
-    deprecate :h3_res_class_3?, :class_3_resolution?, 2020, 1
+    attach_predicate_function :class_3_resolution?, :h3IsResClassIII, %i[h3_index], :bool
 
     # @!method valid?(h3_index)
     #
@@ -119,15 +85,7 @@ module H3
     #   true
     #
     # @return [Boolean] True if the H3 index is valid.
-    attach_function :valid, :h3IsValid, %i[h3_index], :bool
-    alias_method :valid?, :valid
-    undef_method :valid
-
-    # @deprecated Please use {#valid?} instead.
-    def h3_valid?(h3_index)
-      valid?(h3_index)
-    end
-    deprecate :h3_valid?, :valid?, 2020, 1
+    attach_predicate_function :valid?, :h3IsValid, %i[h3_index], :bool
 
     # Derives the hexadecimal string representation for a given H3 index.
     #
@@ -144,12 +102,6 @@ module H3
       h3_str.read_string
     end
 
-    # @deprecated Please use {#to_string} instead.
-    def h3_to_string(h3_index)
-      to_string(h3_index)
-    end
-    deprecate :h3_to_string, :to_strings, 2020, 1
-
     # @!method max_face_count(h3_index)
     #
     # Returns the maximum number of icosahedron faces the given H3 index may intersect.
@@ -163,8 +115,6 @@ module H3
     # @return [Integer] Maximum possible number of faces
     attach_function :max_face_count, :maxFaceCount, %i[h3_index], :int
 
-    # @!method faces(h3_index)
-    #
     # Find all icosahedron faces intersected by a given H3 index.
     #
     # @param [Integer] h3_index A H3 index.
@@ -181,11 +131,5 @@ module H3
       # The C function returns a sparse array whose holes are represented by -1.
       out.read_array_of_int(max_faces).reject(&:negative?).sort
     end
-
-    # @deprecated Please use {#faces} instead.
-    def h3_faces(h3_index)
-      faces(h3_index)
-    end
-    deprecate :h3_faces, :faces, 2020, 1
   end
 end

data/lib/h3/miscellaneous.rb

@@ -83,12 +83,6 @@ module H3
     # @return [Integer] Number of unique hexagons
     attach_function :hexagon_count, :numHexagons, [Resolution], :ulong_long
 
-    # @deprecated Please use {#hexagon_count} instead.
-    def num_hexagons(resolution)
-      hexagon_count(resolution)
-    end
-    deprecate :num_hexagons, :hexagon_count, 2020, 1
-
     # @!method rads_to_degs(rads)
     #
     # Convert a number expressed in radians to its equivalent in degrees.
@@ -125,12 +119,6 @@ module H3
     # @return [Integer] The number of pentagons per resolution.
     attach_function :pentagon_count, :pentagonIndexCount, [], :int
 
-    # @deprecated Please use {#base_cell_count} instead.
-    def res_0_index_count
-      base_cell_count
-    end
-    deprecate :res_0_index_count, :base_cell_count, 2020, 1
-
     # Returns all resolution 0 hexagons (base cells).
     #
     # @example Return all base cells.
@@ -156,11 +144,5 @@ module H3
       Bindings::Private.get_pentagon_indexes(resolution, out)
       out.read
     end
-
-    # @deprecated Please use {#base_cells} instead.
-    def res_0_indexes
-      base_cells
-    end
-    deprecate :res_0_indexes, :base_cells, 2020, 1
   end
 end

data/lib/h3/regions.rb

@@ -141,6 +141,7 @@ module H3
       linked_geo_polygon = LinkedGeoPolygon.new
       Bindings::Private.h3_set_to_linked_geo(h3_set, h3_indexes.size, linked_geo_polygon)
 
+      # The algorithm in h3 currently only handles 1 polygon
       extract_linked_geo_polygon(linked_geo_polygon).first
     ensure
       Bindings::Private.destroy_linked_polygon(linked_geo_polygon)
@@ -154,6 +155,8 @@ module H3
       geo_polygons = [linked_geo_polygon]
 
       until linked_geo_polygon[:next].null?
+        # Until the h3 algorithm is updated to handle multiple polygons,
+        # this block will never run.
         geo_polygons << linked_geo_polygon[:next]
         linked_geo_polygon = linked_geo_polygon[:next]
       end

data/lib/h3/traversal.rb

@@ -32,12 +32,6 @@ module H3
     # @return [Integer] Distance between indexes.
     attach_function :distance, :h3Distance, %i[h3_index h3_index], :k_distance
 
-    # @deprecated Please use {#distance} instead.
-    def h3_distance(origin, destination)
-      distance(origin, destination)
-    end
-    deprecate :h3_distance, :distance, 2020, 1
-
     # @!method line_size(origin, destination)
     #
     # Derive the number of hexagons present in a line between two H3 indexes.
@@ -57,12 +51,6 @@ module H3
     # @return [Integer] Number of hexagons found between indexes.
     attach_function :line_size, :h3LineSize, %i[h3_index h3_index], :int
 
-    # @deprecated Please use {#line_size} instead.
-    def h3_line_size(origin, destination)
-      line_size(origin, destination)
-    end
-    deprecate :h3_line_size, :line_size, 2020, 1
-
     # Derives H3 indexes within k distance of the origin H3 index.
     #
     # Similar to {k_ring}, except that an error is raised when one of the indexes
@@ -317,12 +305,6 @@ module H3
       hexagons.read
     end
 
-    # @deprecated Please use {#line} instead.
-    def h3_line(origin, destination)
-      line(origin, destination)
-    end
-    deprecate :h3_line, :line, 2020, 1
-
     private
 
     def k_rings_for_hex_range(indexes, k)

data/lib/h3/unidirectional_edges.rb

@@ -17,16 +17,7 @@ module H3
     #   true
     #
     # @return [Boolean] True if indexes are neighbors
-    attach_function :neighbors, :h3IndexesAreNeighbors, %i[h3_index h3_index], :bool
-    alias_method :neighbors?, :neighbors
-    undef_method :neighbors
-
-    # @deprecated Please use {#neighbors?} instead.
-    def h3_indexes_neighbors?(origin, destination)
-      neighbors?(origin, destination)
-    end
-
-    deprecate :h3_indexes_neighbors?, :neighbors?, 2020, 1
+    attach_predicate_function :neighbors?, :h3IndexesAreNeighbors, %i[h3_index h3_index], :bool
 
     # @!method unidirectional_edge_valid?(h3_index)
     #
@@ -39,19 +30,10 @@ module H3
     #   true
     #
     # @return [Boolean] True if H3 index is a valid unidirectional edge
-    attach_function :unidirectional_edge_valid,
-                    :h3UnidirectionalEdgeIsValid,
-                    %i[h3_index],
-                    :bool
-    alias_method :unidirectional_edge_valid?, :unidirectional_edge_valid
-    undef_method :unidirectional_edge_valid
-
-    # @deprecated Please use {#unidirectional_edge_valid?} instead.
-    def h3_unidirectional_edge_valid?(h3_index)
-      unidirectional_edge_valid?(h3_index)
-    end
-
-    deprecate :h3_unidirectional_edge_valid?, :unidirectional_edge_valid?, 2020, 1
+    attach_predicate_function :unidirectional_edge_valid?,
+                              :h3UnidirectionalEdgeIsValid,
+                              %i[h3_index],
+                              :bool
 
     # @!method unidirectional_edge(origin, destination)
     #
@@ -70,13 +52,6 @@ module H3
                     %i[h3_index h3_index],
                     :h3_index
 
-    # @deprecated Please use {#unidirectional_edge} instead.
-    def h3_unidirectional_edge(origin, destination)
-      unidirectional_edge(origin, destination)
-    end
-
-    deprecate :h3_unidirectional_edge, :unidirectional_edge, 2020, 1
-
     # @!method destination_from_unidirectional_edge(edge)
     #
     # Derive destination H3 index from edge.
@@ -129,16 +104,6 @@ module H3
       out.read
     end
 
-    # @deprecated Please use {#origin_and_destination_from_unidirectional_edge} instead.
-    def h3_indexes_from_unidirectional_edge(edge)
-      origin_and_destination_from_unidirectional_edge(edge)
-    end
-
-    deprecate :h3_indexes_from_unidirectional_edge,
-              :origin_and_destination_from_unidirectional_edge,
-              2020,
-              1
-
     # Derive unidirectional edges for a H3 index.
     #
     # @param [Integer] origin H3 index
@@ -158,16 +123,6 @@ module H3
       out.read
     end
 
-    # @deprecated Please use {#unidirectional_edges_from_hexagon} instead.
-    def h3_unidirectional_edges_from_hexagon(origin)
-      unidirectional_edges_from_hexagon(origin)
-    end
-
-    deprecate :h3_unidirectional_edges_from_hexagon,
-              :unidirectional_edges_from_hexagon,
-              2020,
-              1
-
     # Derive coordinates for edge boundary.
     #
     # @param [Integer] edge H3 edge index
@@ -188,15 +143,5 @@ module H3
         [rads_to_degs(d[:lat]), rads_to_degs(d[:lon])]
       end
     end
-
-    # @deprecated Please use {#unidirectional_edge_boundary} instead.
-    def h3_unidirectional_edge_boundary(edge)
-      unidirectional_edge_boundary(edge)
-    end
-
-    deprecate :h3_unidirectional_edge_boundary,
-              :unidirectional_edge_boundary,
-              2020,
-              1
   end
 end

data/lib/h3/version.rb

@@ -1,3 +1,3 @@
 module H3
-  VERSION = "3.6.1".freeze
+  VERSION = "3.6.2".freeze
 end

data/spec/geo_json_spec.rb

@@ -60,6 +60,14 @@ RSpec.describe H3 do
         expect { geo_json_to_coordinates }.to raise_error(ArgumentError)
       end
     end
+
+    context "when given JSON with the wrong structure" do
+      let(:input) { { blah: "blah" }.to_json }
+
+      it "raises an error" do
+        expect { geo_json_to_coordinates }.to raise_error(ArgumentError)
+      end
+    end
   end
 
   describe ".coordinates_to_geo_json" do

data/spec/{region_spec.rb → regions_spec.rb}

@@ -42,7 +42,7 @@ RSpec.describe H3 do
       File.read(File.join(File.dirname(__FILE__), "support/fixtures/banbury.json"))
     end
     let(:resolution) { 9 }
-    let(:expected_count) { 36_193 }
+    let(:expected_count) { 75_367 }
 
     subject(:max_polyfill_size) { H3.max_polyfill_size(geojson, resolution) }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: h3
 version: !ruby/object:Gem::Version
-  version: 3.6.1
+  version: 3.6.2
 platform: ruby
 authors:
 - Lachlan Laycock
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-23 00:00:00.000000000 Z
+date: 2020-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -412,7 +412,7 @@ files:
 - spec/indexing_spec.rb
 - spec/inspection_spec.rb
 - spec/miscellaneous_spec.rb
-- spec/region_spec.rb
+- spec/regions_spec.rb
 - spec/spec_helper.rb
 - spec/support/fixtures/australia.json
 - spec/support/fixtures/banbury.json