h3 3.5.1 → 3.6.0

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

@@ -0,0 +1,264 @@
+/*
+ * Copyright 2019 Uber Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** @file
+ * @brief tests H3 index to local IJ and IJK+ grid functions using
+ * tests over a large number of indexes.
+ *
+ *  usage: `testH3ToLocalIjExhaustive`
+ */
+
+#include <h3api.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "algos.h"
+#include "baseCells.h"
+#include "constants.h"
+#include "h3Index.h"
+#include "h3api.h"
+#include "localij.h"
+#include "test.h"
+#include "utility.h"
+
+static const int MAX_DISTANCES[] = {1, 2, 5, 12, 19, 26};
+
+// The same traversal constants from algos.c (for hexRange) here reused as local
+// IJ vectors.
+static const CoordIJ DIRECTIONS[6] = {{0, 1},  {-1, 0}, {-1, -1},
+                                      {0, -1}, {1, 0},  {1, 1}};
+
+static const CoordIJ NEXT_RING_DIRECTION = {1, 0};
+
+/**
+ * Test that the local coordinates for an index map to itself.
+ */
+void localIjToH3_identity_assertions(H3Index h3) {
+    CoordIJ ij;
+    t_assert(H3_EXPORT(experimentalH3ToLocalIj)(h3, h3, &ij) == 0,
+             "able to setup localIjToH3 test");
+
+    H3Index retrieved;
+    t_assert(H3_EXPORT(experimentalLocalIjToH3)(h3, &ij, &retrieved) == 0,
+             "got an index back from localIjTOh3");
+    t_assert(h3 == retrieved, "round trip through local IJ space works");
+}
+
+/**
+ * Test that coordinates for an index match some simple rules about index
+ * digits, when using the index as its own origin. That is, that the IJ
+ * coordinates are in the coordinate space of the origin's base cell.
+ */
+void h3ToLocalIj_coordinates_assertions(H3Index h3) {
+    int r = H3_GET_RESOLUTION(h3);
+
+    CoordIJ ij;
+    t_assert(H3_EXPORT(experimentalH3ToLocalIj)(h3, h3, &ij) == 0,
+             "get ij for origin");
+    CoordIJK ijk;
+    ijToIjk(&ij, &ijk);
+    if (r == 0) {
+        t_assert(_ijkMatches(&ijk, &UNIT_VECS[0]) == 1, "res 0 cell at 0,0,0");
+    } else if (r == 1) {
+        t_assert(_ijkMatches(&ijk, &UNIT_VECS[H3_GET_INDEX_DIGIT(h3, 1)]) == 1,
+                 "res 1 cell at expected coordinates");
+    } else if (r == 2) {
+        CoordIJK expected = UNIT_VECS[H3_GET_INDEX_DIGIT(h3, 1)];
+        _downAp7r(&expected);
+        _neighbor(&expected, H3_GET_INDEX_DIGIT(h3, 2));
+        t_assert(_ijkMatches(&ijk, &expected) == 1,
+                 "res 2 cell at expected coordinates");
+    } else {
+        t_assert(0, "resolution supported by test function (coordinates)");
+    }
+}
+
+/**
+ * Test the the immediate neighbors of an index are at the expected locations in
+ * the local IJ coordinate space.
+ */
+void h3ToLocalIj_neighbors_assertions(H3Index h3) {
+    CoordIJ origin = {0};
+    t_assert(H3_EXPORT(experimentalH3ToLocalIj)(h3, h3, &origin) == 0,
+             "got ij for origin");
+    CoordIJK originIjk;
+    ijToIjk(&origin, &originIjk);
+
+    for (Direction d = K_AXES_DIGIT; d < INVALID_DIGIT; d++) {
+        if (d == K_AXES_DIGIT && H3_EXPORT(h3IsPentagon)(h3)) {
+            continue;
+        }
+
+        int rotations = 0;
+        H3Index offset = h3NeighborRotations(h3, d, &rotations);
+
+        CoordIJ ij = {0};
+        t_assert(H3_EXPORT(experimentalH3ToLocalIj)(h3, offset, &ij) == 0,
+                 "got ij for destination");
+        CoordIJK ijk;
+        ijToIjk(&ij, &ijk);
+        CoordIJK invertedIjk = {0};
+        _neighbor(&invertedIjk, d);
+        for (int i = 0; i < 3; i++) {
+            _ijkRotate60ccw(&invertedIjk);
+        }
+        _ijkAdd(&invertedIjk, &ijk, &ijk);
+        _ijkNormalize(&ijk);
+
+        t_assert(_ijkMatches(&ijk, &originIjk), "back to origin");
+    }
+}
+
+/**
+ * Test that the neighbors (k-ring), if they can be found in the local IJ
+ * coordinate space, can be converted back to indexes.
+ */
+void localIjToH3_kRing_assertions(H3Index h3) {
+    int r = H3_GET_RESOLUTION(h3);
+    t_assert(r <= 5, "resolution supported by test function (kRing)");
+    int maxK = MAX_DISTANCES[r];
+
+    int sz = H3_EXPORT(maxKringSize)(maxK);
+    H3Index *neighbors = calloc(sz, sizeof(H3Index));
+    int *distances = calloc(sz, sizeof(int));
+
+    H3_EXPORT(kRingDistances)(h3, maxK, neighbors, distances);
+
+    for (int i = 0; i < sz; i++) {
+        if (neighbors[i] == 0) {
+            continue;
+        }
+
+        CoordIJ ij;
+        // Don't consider indexes which we can't unfold in the first place
+        if (H3_EXPORT(experimentalH3ToLocalIj)(h3, neighbors[i], &ij) == 0) {
+            H3Index retrieved;
+            t_assert(
+                H3_EXPORT(experimentalLocalIjToH3)(h3, &ij, &retrieved) == 0,
+                "retrieved index for unfolded coordinates");
+            t_assert(retrieved == neighbors[i],
+                     "round trip neighboring index matches expected");
+        }
+    }
+
+    free(distances);
+    free(neighbors);
+}
+
+void localIjToH3_traverse_assertions(H3Index h3) {
+    int r = H3_GET_RESOLUTION(h3);
+    t_assert(r <= 5, "resolution supported by test function (traverse)");
+    int k = MAX_DISTANCES[r];
+
+    CoordIJ ij;
+    t_assert(H3_EXPORT(experimentalH3ToLocalIj)(h3, h3, &ij) == 0,
+             "Got origin coordinates");
+
+    // This logic is from hexRangeDistances.
+    // 0 < ring <= k, current ring
+    int ring = 1;
+    // 0 <= direction < 6, current side of the ring
+    int direction = 0;
+    // 0 <= i < ring, current position on the side of the ring
+    int i = 0;
+
+    while (ring <= k) {
+        if (direction == 0 && i == 0) {
+            ij.i += NEXT_RING_DIRECTION.i;
+            ij.j += NEXT_RING_DIRECTION.j;
+        }
+
+        ij.i += DIRECTIONS[direction].i;
+        ij.j += DIRECTIONS[direction].j;
+
+        H3Index testH3;
+
+        int failed = H3_EXPORT(experimentalLocalIjToH3)(h3, &ij, &testH3);
+        if (!failed) {
+            t_assert(H3_EXPORT(h3IsValid)(testH3),
+                     "test coordinates result in valid index");
+
+            CoordIJ expectedIj;
+            int reverseFailed =
+                H3_EXPORT(experimentalH3ToLocalIj)(h3, testH3, &expectedIj);
+            // If it doesn't give a coordinate for this origin,index pair that's
+            // OK.
+            if (!reverseFailed) {
+                if (expectedIj.i != ij.i || expectedIj.j != ij.j) {
+                    // Multiple coordinates for the same index can happen due to
+                    // pentagon distortion. In that case, the other coordinates
+                    // should also belong to the same index.
+                    H3Index testTestH3;
+                    t_assert(H3_EXPORT(experimentalLocalIjToH3)(
+                                 h3, &expectedIj, &testTestH3) == 0,
+                             "converted coordinates again");
+                    t_assert(testH3 == testTestH3,
+                             "index has normalizable coordinates in "
+                             "local IJ");
+                }
+            }
+        }
+
+        i++;
+        // Check if end of this side of the k-ring
+        if (i == ring) {
+            i = 0;
+            direction++;
+            // Check if end of this ring.
+            if (direction == 6) {
+                direction = 0;
+                ring++;
+            }
+        }
+    }
+}
+
+SUITE(h3ToLocalIj) {
+    TEST(localIjToH3_identity) {
+        iterateAllIndexesAtRes(0, localIjToH3_identity_assertions);
+        iterateAllIndexesAtRes(1, localIjToH3_identity_assertions);
+        iterateAllIndexesAtRes(2, localIjToH3_identity_assertions);
+    }
+
+    TEST(h3ToLocalIj_coordinates) {
+        iterateAllIndexesAtRes(0, h3ToLocalIj_coordinates_assertions);
+        iterateAllIndexesAtRes(1, h3ToLocalIj_coordinates_assertions);
+        iterateAllIndexesAtRes(2, h3ToLocalIj_coordinates_assertions);
+    }
+
+    TEST(h3ToLocalIj_neighbors) {
+        iterateAllIndexesAtRes(0, h3ToLocalIj_neighbors_assertions);
+        iterateAllIndexesAtRes(1, h3ToLocalIj_neighbors_assertions);
+        iterateAllIndexesAtRes(2, h3ToLocalIj_neighbors_assertions);
+    }
+
+    TEST(localIjToH3_kRing) {
+        iterateAllIndexesAtRes(0, localIjToH3_kRing_assertions);
+        iterateAllIndexesAtRes(1, localIjToH3_kRing_assertions);
+        iterateAllIndexesAtRes(2, localIjToH3_kRing_assertions);
+        // Don't iterate all of res 3, to save time
+        iterateAllIndexesAtResPartial(3, localIjToH3_kRing_assertions, 27);
+        // Further resolutions aren't tested to save time.
+    }
+
+    TEST(localIjToH3_traverse) {
+        iterateAllIndexesAtRes(0, localIjToH3_traverse_assertions);
+        iterateAllIndexesAtRes(1, localIjToH3_traverse_assertions);
+        iterateAllIndexesAtRes(2, localIjToH3_traverse_assertions);
+        // Don't iterate all of res 3, to save time
+        iterateAllIndexesAtResPartial(3, localIjToH3_traverse_assertions, 27);
+        // Further resolutions aren't tested to save time.
+    }
+}

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

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2019 Uber Technologies, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *         http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <stdlib.h>
+#include "h3api.h"
+#include "test.h"
+
+#define PADDED_COUNT 16
+
+SUITE(getPentagonIndexes) {
+    TEST(propertyTests) {
+        int expectedCount = H3_EXPORT(pentagonIndexCount)();
+
+        for (int res = 0; res <= 15; res++) {
+            H3Index h3Indexes[PADDED_COUNT] = {0};
+            H3_EXPORT(getPentagonIndexes)(res, h3Indexes);
+
+            int numFound = 0;
+
+            for (int i = 0; i < PADDED_COUNT; i++) {
+                H3Index h3Index = h3Indexes[i];
+                if (h3Index) {
+                    numFound++;
+                    t_assert(H3_EXPORT(h3IsValid(h3Index)),
+                             "index should be valid");
+                    t_assert(H3_EXPORT(h3IsPentagon(h3Index)),
+                             "index should be pentagon");
+                    t_assert(H3_EXPORT(h3GetResolution(h3Index)) == res,
+                             "index should have correct resolution");
+
+                    // verify uniqueness
+                    for (int j = i + 1; j < PADDED_COUNT; j++) {
+                        if (h3Indexes[j] == h3Index) {
+                            t_assert(false, "index should be seen only once");
+                        }
+                    }
+                }
+            }
+
+            t_assert(numFound == expectedCount,
+                     "there should be exactly 12 pentagons");
+        }
+    }
+}

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

@@ -74,6 +74,8 @@
 #define NUM_HEX_VERTS 6
 /** The number of vertices in a pentagon */
 #define NUM_PENT_VERTS 5
+/** The number of pentagons per resolution **/
+#define NUM_PENTAGONS 12
 
 /** H3 index modes */
 #define H3_HEXAGON_MODE 1

data/ext/h3/src/src/h3lib/include/h3api.h.in

@@ -293,6 +293,17 @@ int H3_EXPORT(res0IndexCount)();
 void H3_EXPORT(getRes0Indexes)(H3Index *out);
 /** @} */
 
+/** @defgroup getPentagonIndexes getPentagonIndexes
+ * Functions for getPentagonIndexes
+ * @{
+ */
+/** @brief returns the number of pentagons per resolution */
+int H3_EXPORT(pentagonIndexCount)();
+
+/** @brief generates all pentagons at the specified resolution */
+void H3_EXPORT(getPentagonIndexes)(int res, H3Index *out);
+/** @} */
+
 /** @defgroup h3GetResolution h3GetResolution
  * Functions for h3GetResolution
  * @{
@@ -355,6 +366,15 @@ int H3_EXPORT(maxH3ToChildrenSize)(H3Index h, int childRes);
 void H3_EXPORT(h3ToChildren)(H3Index h, int childRes, H3Index *children);
 /** @} */
 
+/** @defgroup h3ToCenterChild h3ToCenterChild
+ * Functions for h3ToCenterChild
+ * @{
+ */
+/** @brief returns the center child of the given hexagon at the specified
+ * resolution */
+H3Index H3_EXPORT(h3ToCenterChild)(H3Index h, int childRes);
+/** @} */
+
 /** @defgroup compact compact
  * Functions for compact
  * @{

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2018 Uber Technologies, Inc.
+ * Copyright 2016-2019 Uber Technologies, Inc.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -469,7 +469,7 @@ int H3_EXPORT(hexRangeDistances)(H3Index origin, int k, H3Index* out,
             // the end of this ring.
             origin =
                 h3NeighborRotations(origin, NEXT_RING_DIRECTION, &rotations);
-            if (origin == 0) {
+            if (origin == 0) {  // LCOV_EXCL_BR_LINE
                 // Should not be possible because `origin` would have to be a
                 // pentagon
                 return HEX_RANGE_K_SUBSEQUENCE;  // LCOV_EXCL_LINE
@@ -482,7 +482,7 @@ int H3_EXPORT(hexRangeDistances)(H3Index origin, int k, H3Index* out,
         }
 
         origin = h3NeighborRotations(origin, DIRECTIONS[direction], &rotations);
-        if (origin == 0) {
+        if (origin == 0) {  // LCOV_EXCL_BR_LINE
             // Should not be possible because `origin` would have to be a
             // pentagon
             return HEX_RANGE_K_SUBSEQUENCE;  // LCOV_EXCL_LINE
@@ -569,7 +569,7 @@ int H3_EXPORT(hexRing)(H3Index origin, int k, H3Index* out) {
 
     for (int ring = 0; ring < k; ring++) {
         origin = h3NeighborRotations(origin, NEXT_RING_DIRECTION, &rotations);
-        if (origin == 0) {
+        if (origin == 0) {  // LCOV_EXCL_BR_LINE
             // Should not be possible because `origin` would have to be a
             // pentagon
             return HEX_RANGE_K_SUBSEQUENCE;  // LCOV_EXCL_LINE
@@ -589,7 +589,7 @@ int H3_EXPORT(hexRing)(H3Index origin, int k, H3Index* out) {
         for (int pos = 0; pos < k; pos++) {
             origin =
                 h3NeighborRotations(origin, DIRECTIONS[direction], &rotations);
-            if (origin == 0) {
+            if (origin == 0) {  // LCOV_EXCL_BR_LINE
                 // Should not be possible because `origin` would have to be a
                 // pentagon
                 return HEX_RANGE_K_SUBSEQUENCE;  // LCOV_EXCL_LINE

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

@@ -684,14 +684,14 @@ void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
     // edge-crossing vertices as needed
     g->numVerts = 0;
     int lastFace = -1;
-    int lastOverage = 0;  // 0: none; 1: edge; 2: overage
+    Overage lastOverage = NO_OVERAGE;
     for (int vert = 0; vert < NUM_HEX_VERTS + 1; vert++) {
         int v = vert % NUM_HEX_VERTS;
 
         FaceIJK fijk = fijkVerts[v];
 
         int pentLeading4 = 0;
-        int overage = _adjustOverageClassII(&fijk, adjRes, pentLeading4, 1);
+        Overage overage = _adjustOverageClassII(&fijk, adjRes, pentLeading4, 1);
 
         /*
         Check for edge-crossing. Each face of the underlying icosahedron is a
@@ -703,7 +703,7 @@ void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
         edge, with no edge line intersections.
         */
         if (isResClassIII(res) && vert > 0 && fijk.face != lastFace &&
-            lastOverage != 1) {
+            lastOverage != FACE_EDGE) {
             // find hex2d of the two vertexes on original face
             int lastV = (v + 5) % NUM_HEX_VERTS;
             Vec2d orig2d0;

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

@@ -145,6 +145,22 @@ H3Index H3_EXPORT(h3ToParent)(H3Index h, int parentRes) {
     return parentH;
 }
 
+/**
+ * Determines whether one resolution is a valid child resolution of another.
+ * Each resolution is considered a valid child resolution of itself.
+ *
+ * @param parentRes int resolution of the parent
+ * @param childRes int resolution of the child
+ *
+ * @return The validity of the child resolution
+ */
+static bool _isValidChildRes(int parentRes, int childRes) {
+    if (childRes < parentRes || childRes > MAX_H3_RES) {
+        return false;
+    }
+    return true;
+}
+
 /**
  * maxH3ToChildrenSize returns the maximum number of children possible for a
  * given child level.
@@ -157,7 +173,7 @@ H3Index H3_EXPORT(h3ToParent)(H3Index h, int parentRes) {
  */
 int H3_EXPORT(maxH3ToChildrenSize)(H3Index h, int childRes) {
     int parentRes = H3_GET_RESOLUTION(h);
-    if (parentRes > childRes) {
+    if (!_isValidChildRes(parentRes, childRes)) {
         return 0;
     }
     return _ipow(7, (childRes - parentRes));
@@ -191,7 +207,7 @@ H3Index makeDirectChild(H3Index h, int cellNumber) {
  */
 void H3_EXPORT(h3ToChildren)(H3Index h, int childRes, H3Index* children) {
     int parentRes = H3_GET_RESOLUTION(h);
-    if (parentRes > childRes) {
+    if (!_isValidChildRes(parentRes, childRes)) {
         return;
     } else if (parentRes == childRes) {
         *children = h;
@@ -214,6 +230,29 @@ void H3_EXPORT(h3ToChildren)(H3Index h, int childRes, H3Index* children) {
     }
 }
 
+/**
+ * h3ToCenterChild produces the center child index for a given H3 index at
+ * the specified resolution
+ *
+ * @param h H3Index to find center child of
+ * @param childRes The resolution to switch to
+ *
+ * @return H3Index of the center child, or 0 if you actually asked for a parent
+ */
+H3Index H3_EXPORT(h3ToCenterChild)(H3Index h, int childRes) {
+    int parentRes = H3_GET_RESOLUTION(h);
+    if (!_isValidChildRes(parentRes, childRes)) {
+        return H3_INVALID_INDEX;
+    } else if (childRes == parentRes) {
+        return h;
+    }
+    H3Index child = H3_SET_RESOLUTION(h, childRes);
+    for (int i = parentRes + 1; i <= childRes; i++) {
+        H3_SET_INDEX_DIGIT(child, i, 0);
+    }
+    return child;
+}
+
 /**
  * compact takes a set of hexagons all at the same resolution and compresses
  * them by pruning full child branches to the parent level. This is also done
@@ -254,7 +293,7 @@ int H3_EXPORT(compact)(const H3Index* h3Set, H3Index* compactedSet,
                 int loc = (int)(parent % numRemainingHexes);
                 int loopCount = 0;
                 while (hashSetArray[loc] != 0) {
-                    if (loopCount > numRemainingHexes) {
+                    if (loopCount > numRemainingHexes) {  // LCOV_EXCL_BR_LINE
                         // LCOV_EXCL_START
                         // This case should not be possible because at most one
                         // index is placed into hashSetArray per
@@ -330,7 +369,7 @@ int H3_EXPORT(compact)(const H3Index* h3Set, H3Index* compactedSet,
                 int loopCount = 0;
                 bool isUncompactable = true;
                 do {
-                    if (loopCount > numRemainingHexes) {
+                    if (loopCount > numRemainingHexes) {  // LCOV_EXCL_BR_LINE
                         // LCOV_EXCL_START
                         // This case should not be possible because at most one
                         // index is placed into hashSetArray per input hexagon.
@@ -393,7 +432,7 @@ int H3_EXPORT(uncompact)(const H3Index* compactedSet, const int numHexes,
             return -1;
         }
         int currentRes = H3_GET_RESOLUTION(compactedSet[i]);
-        if (currentRes > res) {
+        if (!_isValidChildRes(currentRes, res)) {
             // Nonsensical. Abort.
             return -2;
         }
@@ -431,7 +470,7 @@ int H3_EXPORT(maxUncompactSize)(const H3Index* compactedSet, const int numHexes,
     for (int i = 0; i < numHexes; i++) {
         if (compactedSet[i] == 0) continue;
         int currentRes = H3_GET_RESOLUTION(compactedSet[i]);
-        if (currentRes > res) {
+        if (!_isValidChildRes(currentRes, res)) {
             // Nonsensical. Abort.
             return -1;
         }
@@ -860,6 +899,30 @@ void H3_EXPORT(h3GetFaces)(H3Index h3, int* out) {
     }
 }
 
+/**
+ * pentagonIndexCount returns the number of pentagons (same at any resolution)
+ *
+ * @return int count of pentagon indexes
+ */
+int H3_EXPORT(pentagonIndexCount)() { return NUM_PENTAGONS; }
+
+/**
+ * Generates all pentagons at the specified resolution
+ *
+ * @param res The resolution to produce pentagons at.
+ * @param out Output array. Must be of size pentagonIndexCount().
+ */
+void H3_EXPORT(getPentagonIndexes)(int res, H3Index* out) {
+    int i = 0;
+    for (int bc = 0; bc < NUM_BASE_CELLS; bc++) {
+        if (_isBaseCellPentagon(bc)) {
+            H3Index pentagon;
+            setH3Index(&pentagon, res, bc, 0);
+            out[i++] = pentagon;
+        }
+    }
+}
+
 /**
  * Returns whether or not a resolution is a Class III grid. Note that odd
  * resolutions are Class III and even resolutions are Class II.