h3 3.4.4 → 3.5.0

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

@@ -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.
@@ -394,6 +394,17 @@ int H3_EXPORT(h3IsResClassIII)(H3Index h);
 int H3_EXPORT(h3IsPentagon)(H3Index h);
 /** @} */
 
+/** @defgroup h3GetFaces h3GetFaces
+ * Functions for h3GetFaces
+ * @{
+ */
+/** @brief Max number of icosahedron faces intersected by an index */
+int H3_EXPORT(maxFaceCount)(H3Index h3);
+
+/** @brief Find all icosahedron faces intersected by a given H3 index */
+void H3_EXPORT(h3GetFaces)(H3Index h3, int *out);
+/** @} */
+
 /** @defgroup h3IndexesAreNeighbors h3IndexesAreNeighbors
  * Functions for h3IndexesAreNeighbors
  * @{

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

@@ -539,12 +539,17 @@ int H3_EXPORT(hexRanges)(H3Index* h3Set, int length, int k, H3Index* out) {
 }
 
 /**
- * Returns the hollow hexagonal ring centered at origin with sides of length k.
+ * Returns the "hollow" ring of hexagons at exactly grid distance k from
+ * the origin hexagon. In particular, k=0 returns just the origin hexagon.
+ *
+ * A nonzero failure code may be returned in some cases, for example,
+ * if a pentagon is encountered.
+ * Failure cases may be fixed in future versions.
  *
  * @param origin Origin location.
  * @param k k >= 0
  * @param out Array which must be of size 6 * k (or 1 if k == 0)
- * @return 0 if no pentagonal distortion was encountered.
+ * @return 0 if successful; nonzero otherwise.
  */
 int H3_EXPORT(hexRing)(H3Index origin, int k, H3Index* out) {
     // Short-circuit on 'identity' ring

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2017 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.
@@ -502,60 +502,10 @@ void _faceIjkToGeo(const FaceIJK* h, int res, GeoCoord* g) {
  * @param g The spherical coordinates of the cell boundary.
  */
 void _faceIjkPentToGeoBoundary(const FaceIJK* h, int res, GeoBoundary* g) {
-    // the vertexes of an origin-centered pentagon in a Class II resolution on a
-    // substrate grid with aperture sequence 33r. The aperture 3 gets us the
-    // vertices, and the 3r gets us back to Class II.
-    // vertices listed ccw from the i-axes
-    CoordIJK vertsCII[NUM_PENT_VERTS] = {
-        {2, 1, 0},  // 0
-        {1, 2, 0},  // 1
-        {0, 2, 1},  // 2
-        {0, 1, 2},  // 3
-        {1, 0, 2},  // 4
-    };
-
-    // the vertexes of an origin-centered pentagon in a Class III resolution on
-    // a substrate grid with aperture sequence 33r7r. The aperture 3 gets us the
-    // vertices, and the 3r7r gets us to Class II. vertices listed ccw from the
-    // i-axes
-    CoordIJK vertsCIII[NUM_PENT_VERTS] = {
-        {5, 4, 0},  // 0
-        {1, 5, 0},  // 1
-        {0, 5, 4},  // 2
-        {0, 1, 5},  // 3
-        {4, 0, 5},  // 4
-    };
-
-    // get the correct set of substrate vertices for this resolution
-    CoordIJK* verts;
-    if (isResClassIII(res))
-        verts = vertsCIII;
-    else
-        verts = vertsCII;
-
-    // adjust the center point to be in an aperture 33r substrate grid
-    // these should be composed for speed
-    FaceIJK centerIJK = *h;
-    _downAp3(&centerIJK.coord);
-    _downAp3r(&centerIJK.coord);
-
-    // if res is Class III we need to add a cw aperture 7 to get to
-    // icosahedral Class II
     int adjRes = res;
-    if (isResClassIII(res)) {
-        _downAp7r(&centerIJK.coord);
-        adjRes++;
-    }
-
-    // The center point is now in the same substrate grid as the origin
-    // cell vertices. Add the center point substate coordinates
-    // to each vertex to translate the vertices to that cell.
+    FaceIJK centerIJK = *h;
     FaceIJK fijkVerts[NUM_PENT_VERTS];
-    for (int v = 0; v < NUM_PENT_VERTS; v++) {
-        fijkVerts[v].face = centerIJK.face;
-        _ijkAdd(&centerIJK.coord, &verts[v], &fijkVerts[v].coord);
-        _ijkNormalize(&fijkVerts[v].coord);
-    }
+    _faceIjkPentToVerts(&centerIJK, &adjRes, fijkVerts);
 
     // convert each vertex to lat/lon
     // adjust the face of each vertex as appropriate and introduce
@@ -567,16 +517,7 @@ void _faceIjkPentToGeoBoundary(const FaceIJK* h, int res, GeoBoundary* g) {
 
         FaceIJK fijk = fijkVerts[v];
 
-        int pentLeading4 = 0;
-        int overage = _adjustOverageClassII(&fijk, adjRes, pentLeading4, 1);
-        if (overage == 2)  // in a different triangle
-        {
-            while (1) {
-                overage = _adjustOverageClassII(&fijk, adjRes, pentLeading4, 1);
-                if (overage != 2)  // not in a different triangle
-                    break;
-            }
-        }
+        _adjustPentVertOverage(&fijk, adjRes);
 
         // all Class III pentagon edges cross icosa edges
         // note that Class II pentagons have vertices on the edge,
@@ -656,77 +597,87 @@ void _faceIjkPentToGeoBoundary(const FaceIJK* h, int res, GeoBoundary* g) {
 }
 
 /**
- * Generates the cell boundary in spherical coordinates for a cell given by a
- * FaceIJK address at a specified resolution.
+ * Get the vertices of a pentagon cell as substrate FaceIJK addresses
  *
- * @param h The FaceIJK address of the cell.
- * @param res The H3 resolution of the cell.
- * @param isPentagon Whether or not the cell is a pentagon.
- * @param g The spherical coordinates of the cell boundary.
+ * @param fijk The FaceIJK address of the cell.
+ * @param res The H3 resolution of the cell. This may be adjusted if
+ *            necessary for the substrate grid resolution.
+ * @param fijkVerts Output array for the vertices
  */
-void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
-                           GeoBoundary* g) {
-    if (isPentagon) {
-        _faceIjkPentToGeoBoundary(h, res, g);
-        return;
-    }
-
-    // the vertexes of an origin-centered cell in a Class II resolution on a
+void _faceIjkPentToVerts(FaceIJK* fijk, int* res, FaceIJK* fijkVerts) {
+    // the vertexes of an origin-centered pentagon in a Class II resolution on a
     // substrate grid with aperture sequence 33r. The aperture 3 gets us the
     // vertices, and the 3r gets us back to Class II.
     // vertices listed ccw from the i-axes
-    CoordIJK vertsCII[NUM_HEX_VERTS] = {
+    CoordIJK vertsCII[NUM_PENT_VERTS] = {
         {2, 1, 0},  // 0
         {1, 2, 0},  // 1
         {0, 2, 1},  // 2
         {0, 1, 2},  // 3
         {1, 0, 2},  // 4
-        {2, 0, 1}   // 5
     };
 
-    // the vertexes of an origin-centered cell in a Class III resolution on a
-    // substrate grid with aperture sequence 33r7r. The aperture 3 gets us the
-    // vertices, and the 3r7r gets us to Class II.
-    // vertices listed ccw from the i-axes
-    CoordIJK vertsCIII[NUM_HEX_VERTS] = {
+    // the vertexes of an origin-centered pentagon in a Class III resolution on
+    // a substrate grid with aperture sequence 33r7r. The aperture 3 gets us the
+    // vertices, and the 3r7r gets us to Class II. vertices listed ccw from the
+    // i-axes
+    CoordIJK vertsCIII[NUM_PENT_VERTS] = {
         {5, 4, 0},  // 0
         {1, 5, 0},  // 1
         {0, 5, 4},  // 2
         {0, 1, 5},  // 3
         {4, 0, 5},  // 4
-        {5, 0, 1}   // 5
     };
 
     // get the correct set of substrate vertices for this resolution
     CoordIJK* verts;
-    if (isResClassIII(res))
+    if (isResClassIII(*res))
         verts = vertsCIII;
     else
         verts = vertsCII;
 
     // adjust the center point to be in an aperture 33r substrate grid
     // these should be composed for speed
-    FaceIJK centerIJK = *h;
-    _downAp3(&centerIJK.coord);
-    _downAp3r(&centerIJK.coord);
+    _downAp3(&fijk->coord);
+    _downAp3r(&fijk->coord);
 
     // if res is Class III we need to add a cw aperture 7 to get to
     // icosahedral Class II
-    int adjRes = res;
-    if (isResClassIII(res)) {
-        _downAp7r(&centerIJK.coord);
-        adjRes++;
+    if (isResClassIII(*res)) {
+        _downAp7r(&fijk->coord);
+        *res += 1;
     }
 
     // The center point is now in the same substrate grid as the origin
     // cell vertices. Add the center point substate coordinates
     // to each vertex to translate the vertices to that cell.
-    FaceIJK fijkVerts[NUM_HEX_VERTS];
-    for (int v = 0; v < NUM_HEX_VERTS; v++) {
-        fijkVerts[v].face = centerIJK.face;
-        _ijkAdd(&centerIJK.coord, &verts[v], &fijkVerts[v].coord);
+    for (int v = 0; v < NUM_PENT_VERTS; v++) {
+        fijkVerts[v].face = fijk->face;
+        _ijkAdd(&fijk->coord, &verts[v], &fijkVerts[v].coord);
         _ijkNormalize(&fijkVerts[v].coord);
     }
+}
+
+/**
+ * Generates the cell boundary in spherical coordinates for a cell given by a
+ * FaceIJK address at a specified resolution.
+ *
+ * @param h The FaceIJK address of the cell.
+ * @param res The H3 resolution of the cell.
+ * @param isPentagon Whether or not the cell is a pentagon.
+ * @param g The spherical coordinates of the cell boundary.
+ */
+void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
+                           GeoBoundary* g) {
+    if (isPentagon) {
+        _faceIjkPentToGeoBoundary(h, res, g);
+        return;
+    }
+
+    int adjRes = res;
+    FaceIJK centerIJK = *h;
+    FaceIJK fijkVerts[NUM_HEX_VERTS];
+    _faceIjkToVerts(&centerIJK, &adjRes, fijkVerts);
 
     // convert each vertex to lat/lon
     // adjust the face of each vertex as appropriate and introduce
@@ -819,6 +770,70 @@ void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
     }
 }
 
+/**
+ * Get the vertices of a cell as substrate FaceIJK addresses
+ *
+ * @param fijk The FaceIJK address of the cell.
+ * @param res The H3 resolution of the cell. This may be adjusted if
+ *            necessary for the substrate grid resolution.
+ * @param fijkVerts Output array for the vertices
+ */
+void _faceIjkToVerts(FaceIJK* fijk, int* res, FaceIJK* fijkVerts) {
+    // the vertexes of an origin-centered cell in a Class II resolution on a
+    // substrate grid with aperture sequence 33r. The aperture 3 gets us the
+    // vertices, and the 3r gets us back to Class II.
+    // vertices listed ccw from the i-axes
+    CoordIJK vertsCII[NUM_HEX_VERTS] = {
+        {2, 1, 0},  // 0
+        {1, 2, 0},  // 1
+        {0, 2, 1},  // 2
+        {0, 1, 2},  // 3
+        {1, 0, 2},  // 4
+        {2, 0, 1}   // 5
+    };
+
+    // the vertexes of an origin-centered cell in a Class III resolution on a
+    // substrate grid with aperture sequence 33r7r. The aperture 3 gets us the
+    // vertices, and the 3r7r gets us to Class II.
+    // vertices listed ccw from the i-axes
+    CoordIJK vertsCIII[NUM_HEX_VERTS] = {
+        {5, 4, 0},  // 0
+        {1, 5, 0},  // 1
+        {0, 5, 4},  // 2
+        {0, 1, 5},  // 3
+        {4, 0, 5},  // 4
+        {5, 0, 1}   // 5
+    };
+
+    // get the correct set of substrate vertices for this resolution
+    CoordIJK* verts;
+    if (isResClassIII(*res))
+        verts = vertsCIII;
+    else
+        verts = vertsCII;
+
+    // adjust the center point to be in an aperture 33r substrate grid
+    // these should be composed for speed
+    _downAp3(&fijk->coord);
+    _downAp3r(&fijk->coord);
+
+    // if res is Class III we need to add a cw aperture 7 to get to
+    // icosahedral Class II
+    if (isResClassIII(*res)) {
+        _downAp7r(&fijk->coord);
+        *res += 1;
+    }
+
+    // The center point is now in the same substrate grid as the origin
+    // cell vertices. Add the center point substate coordinates
+    // to each vertex to translate the vertices to that cell.
+    for (int v = 0; v < NUM_HEX_VERTS; v++) {
+        fijkVerts[v].face = fijk->face;
+        _ijkAdd(&fijk->coord, &verts[v], &fijkVerts[v].coord);
+        _ijkNormalize(&fijkVerts[v].coord);
+    }
+}
+
 /**
  * Adjusts a FaceIJK address in place so that the resulting cell address is
  * relative to the correct icosahedral face.
@@ -831,9 +846,9 @@ void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
  * @return 0 if on original face (no overage); 1 if on face edge (only occurs
  *         on substrate grids); 2 if overage on new face interior
  */
-int _adjustOverageClassII(FaceIJK* fijk, int res, int pentLeading4,
-                          int substrate) {
-    int overage = 0;
+Overage _adjustOverageClassII(FaceIJK* fijk, int res, int pentLeading4,
+                              int substrate) {
+    Overage overage = NO_OVERAGE;
 
     CoordIJK* ijk = &fijk->coord;
 
@@ -843,10 +858,10 @@ int _adjustOverageClassII(FaceIJK* fijk, int res, int pentLeading4,
 
     // check for overage
     if (substrate && ijk->i + ijk->j + ijk->k == maxDim)  // on edge
-        overage = 1;
+        overage = FACE_EDGE;
     else if (ijk->i + ijk->j + ijk->k > maxDim)  // overage
     {
-        overage = 2;
+        overage = NEW_FACE;
 
         const FaceOrientIJK* fijkOrient;
         if (ijk->k > 0) {
@@ -886,8 +901,25 @@ int _adjustOverageClassII(FaceIJK* fijk, int res, int pentLeading4,
 
         // overage points on pentagon boundaries can end up on edges
         if (substrate && ijk->i + ijk->j + ijk->k == maxDim)  // on edge
-            overage = 1;
+            overage = FACE_EDGE;
     }
 
     return overage;
 }
+
+/**
+ * Adjusts a FaceIJK address for a pentagon vertex in a substrate grid in
+ * place so that the resulting cell address is relative to the correct
+ * icosahedral face.
+ *
+ * @param fijk The FaceIJK address of the cell.
+ * @param res The H3 resolution of the cell.
+ */
+Overage _adjustPentVertOverage(FaceIJK* fijk, int res) {
+    int pentLeading4 = 0;
+    Overage overage;
+    do {
+        overage = _adjustOverageClassII(fijk, res, pentLeading4, 1);
+    } while (overage == NEW_FACE);
+    return overage;
+}

data/ext/h3/src/src/h3lib/lib/h3Index.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.
@@ -739,13 +739,12 @@ void _h3ToFaceIjk(H3Index h, FaceIJK* fijk) {
     // a pentagon base cell with a leading 4 digit requires special handling
     int pentLeading4 =
         (_isBaseCellPentagon(baseCell) && _h3LeadingNonZeroDigit(h) == 4);
-    if (_adjustOverageClassII(fijk, res, pentLeading4, 0)) {
+    if (_adjustOverageClassII(fijk, res, pentLeading4, 0) != NO_OVERAGE) {
         // if the base cell is a pentagon we have the potential for secondary
         // overages
         if (_isBaseCellPentagon(baseCell)) {
-            while (1) {
-                if (!_adjustOverageClassII(fijk, res, 0, 0)) break;
-            }
+            while (_adjustOverageClassII(fijk, res, 0, 0) != NO_OVERAGE)
+                continue;
         }
 
         if (res != H3_GET_RESOLUTION(h)) _upAp7r(&fijk->coord);
@@ -779,6 +778,88 @@ void H3_EXPORT(h3ToGeoBoundary)(H3Index h3, GeoBoundary* gb) {
                           H3_EXPORT(h3IsPentagon)(h3), gb);
 }
 
+/**
+ * Returns the max number of possible icosahedron faces an H3 index
+ * may intersect.
+ *
+ * @return int count of faces
+ */
+int H3_EXPORT(maxFaceCount)(H3Index h3) {
+    // a pentagon always intersects 5 faces, a hexagon never intersects more
+    // than 2 (but may only intersect 1)
+    return H3_EXPORT(h3IsPentagon)(h3) ? 5 : 2;
+}
+
+/**
+ * Find all icosahedron faces intersected by a given H3 index, represented
+ * as integers from 0-19. The array is sparse; since 0 is a valid value,
+ * invalid array values are represented as -1. It is the responsibility of
+ * the caller to filter out invalid values.
+ *
+ * @param h3 The H3 index
+ * @param out Output array. Must be of size maxFaceCount(h3).
+ */
+void H3_EXPORT(h3GetFaces)(H3Index h3, int* out) {
+    int res = H3_GET_RESOLUTION(h3);
+    int isPentagon = H3_EXPORT(h3IsPentagon)(h3);
+
+    // We can't use the vertex-based approach here for class II pentagons,
+    // because all their vertices are on the icosahedron edges. Their
+    // direct child pentagons cross the same faces, so use those instead.
+    if (isPentagon && !isResClassIII(res)) {
+        // Note that this would not work for res 15, but this is only run on
+        // Class II pentagons, it should never be invoked for a res 15 index.
+        H3Index childPentagon = makeDirectChild(h3, 0);
+        H3_EXPORT(h3GetFaces)(childPentagon, out);
+        return;
+    }
+
+    // convert to FaceIJK
+    FaceIJK fijk;
+    _h3ToFaceIjk(h3, &fijk);
+
+    // Get all vertices as FaceIJK addresses. For simplicity, always
+    // initialize the array with 6 verts, ignoring the last one for pentagons
+    FaceIJK fijkVerts[NUM_HEX_VERTS];
+    int vertexCount;
+
+    if (isPentagon) {
+        vertexCount = NUM_PENT_VERTS;
+        _faceIjkPentToVerts(&fijk, &res, fijkVerts);
+    } else {
+        vertexCount = NUM_HEX_VERTS;
+        _faceIjkToVerts(&fijk, &res, fijkVerts);
+    }
+
+    // We may not use all of the slots in the output array,
+    // so fill with invalid values to indicate unused slots
+    int faceCount = H3_EXPORT(maxFaceCount)(h3);
+    for (int i = 0; i < faceCount; i++) {
+        out[i] = INVALID_FACE;
+    }
+
+    // add each vertex face, using the output array as a hash set
+    for (int i = 0; i < vertexCount; i++) {
+        FaceIJK* vert = &fijkVerts[i];
+
+        // Adjust overage, determining whether this vertex is
+        // on another face
+        if (isPentagon) {
+            _adjustPentVertOverage(vert, res);
+        } else {
+            _adjustOverageClassII(vert, res, 0, 1);
+        }
+
+        // Save the face to the output array
+        int face = vert->face;
+        int pos = 0;
+        // Find the first empty output position, or the first position
+        // matching the current face
+        while (out[pos] != INVALID_FACE && out[pos] != face) pos++;
+        out[pos] = face;
+    }
+}
+
 /**
  * Returns whether or not a resolution is a Class III grid. Note that odd
  * resolutions are Class III and even resolutions are Class II.