h3 3.4.4 → 3.5.0

data/ext/h3/src/src/apps/miscapps/h3ToHier.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2017 Uber Technologies, Inc.
+ * Copyright 2016-2017, 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.
@@ -17,7 +17,7 @@
  * @brief takes an optional H3 index and generates all descendant cells at the
  * specified resolution.
  *
- *  usage: `h3ToHier [resolution H3Index]`
+ *  See `h3ToHier --help` for usage.
  *
  *  The program generates all cells at the specified resolution, optionally
  *  only the children of the given index.
@@ -25,30 +25,25 @@
  *  `resolution` should be a positive integer. The default is 0 (i.e., only the
  *       base cells).
  *
- *  `H3Index` should be an H3Index. By default, all indices at the specified
+ *  `parent` should be an H3Index. By default, all indices at the specified
  *       resolution are generated.
  */
 
+#include <inttypes.h>
 #include <stdio.h>
 #include <stdlib.h>
-#include <string.h>
+#include "args.h"
 #include "baseCells.h"
-#include "coordijk.h"
-#include "geoCoord.h"
 #include "h3Index.h"
 #include "h3api.h"
 #include "kml.h"
 #include "utility.h"
-#include "vec2d.h"
-
-#include "algos.h"
 
 void recursiveH3IndexToHier(H3Index h, int res) {
     for (int d = 0; d < 7; d++) {
         H3_SET_INDEX_DIGIT(h, res, d);
 
         // skip the pentagonal deleted subsequence
-
         if (_isBaseCellPentagon(H3_GET_BASE_CELL(h)) &&
             _h3LeadingNonZeroDigit(h) == 1) {
             continue;
@@ -62,28 +57,54 @@ void recursiveH3IndexToHier(H3Index h, int res) {
     }
 }
 
-int main(int argc, char* argv[]) {
-    // check command line args
-    if (argc < 2 || argc > 3) {
-        fprintf(stderr, "usage: %s [resolution H3Index]\n", argv[0]);
-        exit(1);
-    }
+int main(int argc, char *argv[]) {
+    int res;
+    H3Index parentIndex = 0;
 
-    int res = 0;
-    if (!sscanf(argv[1], "%d", &res)) error("resolution must be an integer");
+    Arg helpArg = ARG_HELP;
+    Arg resArg = {.names = {"-r", "--resolution"},
+                  .scanFormat = "%d",
+                  .valueName = "res",
+                  .value = &res,
+                  .required = true,
+                  .helpText = "Resolution, 0-15 inclusive."};
+    Arg parentArg = {
+        .names = {"-p", "--parent"},
+        .scanFormat = "%" PRIx64,
+        .valueName = "parent",
+        .value = &parentIndex,
+        .helpText = "Print only indexes descendent from this index."};
 
-    if (res > MAX_H3_RES) error("specified resolution exceeds max resolution");
+    Arg *args[] = {&helpArg, &resArg, &parentArg};
+    const int numArgs = 3;
+    const char *helpText = "Print all indexes at the specified resolution";
 
-    H3Index prefixIndex = 0;
-    if (argc > 2) {
-        prefixIndex = H3_EXPORT(stringToH3)(argv[2]);
-        int h3BaseCell = H3_GET_BASE_CELL(prefixIndex);
-        if (h3BaseCell < 0 || h3BaseCell >= NUM_BASE_CELLS) {
-            error("invalid base cell number");
-        }
+    if (parseArgs(argc, argv, numArgs, args, &helpArg, helpText)) {
+        return helpArg.found ? 0 : 1;
+    }
+
+    if (res > MAX_H3_RES) {
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "Resolution exceeds maximum resolution.", NULL);
+        return 1;
+    }
+
+    if (parentArg.found && !H3_EXPORT(h3IsValid)(parentIndex)) {
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "Parent index is invalid.", NULL);
+        return 1;
     }
 
-    if (prefixIndex == 0) {
+    if (parentArg.found) {
+        // parent is the same or higher resolution than the target.
+        if (res <= H3_GET_RESOLUTION(parentIndex)) {
+            h3Println(parentIndex);
+        } else {
+            int rootRes = H3_GET_RESOLUTION(parentIndex);
+            H3_SET_RESOLUTION(parentIndex, res);
+            recursiveH3IndexToHier(parentIndex, rootRes + 1);
+        }
+    } else {
         // Generate all
         for (int bc = 0; bc < NUM_BASE_CELLS; bc++) {
             H3Index rootCell = H3_INIT;
@@ -96,15 +117,5 @@ int main(int argc, char* argv[]) {
                 recursiveH3IndexToHier(rootCell, 1);
             }
         }
-    } else {
-        // prefix is the same or higher resolution than
-        // the target.
-        if (res <= H3_GET_RESOLUTION(prefixIndex)) {
-            h3Println(prefixIndex);
-        } else {
-            int rootRes = H3_GET_RESOLUTION(prefixIndex);
-            H3_SET_RESOLUTION(prefixIndex, res);
-            recursiveH3IndexToHier(prefixIndex, rootRes + 1);
-        }
     }
 }

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

@@ -17,7 +17,7 @@
  * @brief generates random lat/lon pairs and bins them at the specified
  * resolution
  *
- *  usage: `mkRandGeo numPoints resolution`
+ *  See `mkRandGeo --help` for usage.
  *
  *  The program generates `numPoints` random lat/lon coordinates and outputs
  *  them along with the corresponding H3Index at the specified `resolution`.
@@ -25,38 +25,43 @@
 
 #include <stdio.h>
 #include <stdlib.h>
-#include <time.h>
-#include "baseCells.h"
-#include "h3Index.h"
+#include "args.h"
 #include "utility.h"
 
-void randomGeo(GeoCoord* g) {
-    static int init = 0;
-    if (!init) {
-        srand((unsigned int)time(0));
-        init = 1;
-    }
-
-    g->lat = H3_EXPORT(degsToRads)(
-        (((float)rand() / (float)(RAND_MAX)) * 180.0) - 90.0);
-    g->lon = H3_EXPORT(degsToRads)((float)rand() / (float)(RAND_MAX)) * 360.0;
-}
-
 int main(int argc, char* argv[]) {
-    // check command line args
-    if (argc > 3) {
-        fprintf(stderr, "usage: %s numPoints resolution\n", argv[0]);
-        exit(1);
-    }
-
+    int res = 0;
     int numPoints = 0;
-    if (!sscanf(argv[1], "%d", &numPoints))
-        error("numPoints must be an integer");
 
-    int res = 0;
-    if (!sscanf(argv[2], "%d", &res)) error("resolution must be an integer");
+    Arg helpArg = ARG_HELP;
+    Arg numPointsArg = {
+        .names = {"-n", "--num-points"},
+        .required = true,
+        .scanFormat = "%d",
+        .valueName = "num",
+        .value = &numPoints,
+        .helpText = "Number of random lat/lon pairs to generate."};
+    Arg resArg = {.names = {"-r", "--resolution"},
+                  .required = true,
+                  .scanFormat = "%d",
+                  .valueName = "res",
+                  .value = &res,
+                  .helpText = "Resolution, 0-15 inclusive."};
+
+    Arg* args[] = {&helpArg, &numPointsArg, &resArg};
+    const int numArgs = 3;
+    const char* helpText =
+        "Generates random lat/lon pairs and indexes them at the specified "
+        "resolution.";
 
-    if (res > MAX_H3_RES) error("specified resolution exceeds max resolution");
+    if (parseArgs(argc, argv, numArgs, args, &helpArg, helpText)) {
+        return helpArg.found ? 0 : 1;
+    }
+
+    if (res > MAX_H3_RES) {
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "Resolution exceeds maximum resolution.", NULL);
+        return 1;
+    }
 
     for (int i = 0; i < numPoints; i++) {
         GeoCoord g;

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2017 Uber Technologies, Inc.
+ * Copyright 2016-2017, 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.
@@ -16,7 +16,7 @@
 /** @file
  * @brief generates random cell indexes and the corresponding cell boundaries
  *
- *  usage: `mkRandGeoBoundary numPoints resolution`
+ *  See `mkRandGeoBoundary --help` for usage.
  *
  *  The program generates `numPoints` random lat/lon coordinates and outputs
  *  them along with the corresponding H3Index at the specified `resolution`.
@@ -24,38 +24,43 @@
 
 #include <stdio.h>
 #include <stdlib.h>
-#include <time.h>
-#include "baseCells.h"
-#include "h3Index.h"
+#include "args.h"
 #include "utility.h"
 
-void randomGeo(GeoCoord* g) {
-    static int init = 0;
-    if (!init) {
-        srand((unsigned int)time(0));
-        init = 1;
-    }
-
-    g->lat = H3_EXPORT(degsToRads)(
-        (((float)rand() / (float)(RAND_MAX)) * 180.0) - 90.0);
-    g->lon = H3_EXPORT(degsToRads)((float)rand() / (float)(RAND_MAX)) * 360.0;
-}
-
 int main(int argc, char* argv[]) {
-    // check command line args
-    if (argc > 3) {
-        fprintf(stderr, "usage: %s numPoints resolution\n", argv[0]);
-        exit(1);
-    }
-
+    int res = 0;
     int numPoints = 0;
-    if (!sscanf(argv[1], "%d", &numPoints))
-        error("numPoints must be an integer");
 
-    int res = 0;
-    if (!sscanf(argv[2], "%d", &res)) error("resolution must be an integer");
+    Arg helpArg = ARG_HELP;
+    Arg numPointsArg = {
+        .names = {"-n", "--num-points"},
+        .required = true,
+        .scanFormat = "%d",
+        .valueName = "num",
+        .value = &numPoints,
+        .helpText = "Number of random lat/lon pairs to generate."};
+    Arg resArg = {.names = {"-r", "--resolution"},
+                  .required = true,
+                  .scanFormat = "%d",
+                  .valueName = "res",
+                  .value = &res,
+                  .helpText = "Resolution, 0-15 inclusive."};
+
+    Arg* args[] = {&helpArg, &numPointsArg, &resArg};
+    const int numArgs = 3;
+    const char* helpText =
+        "Generates random cell indexes and cell boundaries at the specified "
+        "resolution.";
 
-    if (res > MAX_H3_RES) error("specified resolution exceeds max resolution");
+    if (parseArgs(argc, argv, numArgs, args, &helpArg, helpText)) {
+        return helpArg.found ? 0 : 1;
+    }
+
+    if (res > MAX_H3_RES) {
+        printHelp(stderr, argv[0], helpText, numArgs, args,
+                  "Resolution exceeds maximum resolution.", NULL);
+        return 1;
+    }
 
     for (int i = 0; i < numPoints; i++) {
         GeoCoord g;

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

@@ -0,0 +1,136 @@
+/*
+ * 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 the h3GetFaces function
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include "baseCells.h"
+#include "h3Index.h"
+#include "h3api.h"
+#include "test.h"
+#include "utility.h"
+
+static int countFaces(H3Index h3, int expectedMax) {
+    int sz = H3_EXPORT(maxFaceCount)(h3);
+    t_assert(sz == expectedMax, "got expected max face count");
+    int *faces = calloc(sz, sizeof(int));
+
+    H3_EXPORT(h3GetFaces)(h3, faces);
+
+    int validCount = 0;
+    for (int i = 0; i < sz; i++) {
+        if (faces[i] >= 0 && faces[i] <= 19) validCount++;
+    }
+
+    free(faces);
+    return validCount;
+}
+
+static void assertSingleHexFace(H3Index h3) {
+    int validCount = countFaces(h3, 2);
+    t_assert(validCount == 1, "got a single valid face");
+}
+
+static void assertMultipleHexFaces(H3Index h3) {
+    int validCount = countFaces(h3, 2);
+    t_assert(validCount == 2, "got multiple valid faces for a hexagon");
+}
+
+static void assertPentagonFaces(H3Index h3) {
+    t_assert(H3_EXPORT(h3IsPentagon)(h3), "got a pentagon");
+    int validCount = countFaces(h3, 5);
+    t_assert(validCount == 5, "got 5 valid faces for a pentagon");
+}
+
+SUITE(h3GetFaces) {
+    TEST(singleFaceHexes) {
+        // base cell 16 is at the center of an icosahedron face,
+        // so all children should have the same face
+        iterateBaseCellIndexesAtRes(2, assertSingleHexFace, 16);
+        iterateBaseCellIndexesAtRes(3, assertSingleHexFace, 16);
+    }
+
+    TEST(hexagonWithEdgeVertices) {
+        // Class II pentagon neighbor - one face, two adjacent vertices on edge
+        H3Index h3 = 0x821c37fffffffff;
+        assertSingleHexFace(h3);
+    }
+
+    TEST(hexagonWithDistortion) {
+        // Class III pentagon neighbor, distortion across faces
+        H3Index h3 = 0x831c06fffffffff;
+        assertMultipleHexFaces(h3);
+    }
+
+    TEST(hexagonCrossingFaces) {
+        // Class II hex with two vertices on edge
+        H3Index h3 = 0x821ce7fffffffff;
+        assertMultipleHexFaces(h3);
+    }
+
+    TEST(classIIIPentagon) {
+        H3Index pentagon;
+        setH3Index(&pentagon, 1, 4, 0);
+        assertPentagonFaces(pentagon);
+    }
+
+    TEST(classIIPentagon) {
+        H3Index pentagon;
+        setH3Index(&pentagon, 2, 4, 0);
+        assertPentagonFaces(pentagon);
+    }
+
+    TEST(res15Pentagon) {
+        H3Index pentagon;
+        setH3Index(&pentagon, 15, 4, 0);
+        assertPentagonFaces(pentagon);
+    }
+
+    TEST(baseCellHexagons) {
+        int singleCount = 0;
+        int multipleCount = 0;
+        for (int i = 0; i < NUM_BASE_CELLS; i++) {
+            if (!_isBaseCellPentagon(i)) {
+                // Make the base cell index
+                H3Index baseCell;
+                setH3Index(&baseCell, 0, i, 0);
+                int validCount = countFaces(baseCell, 2);
+                t_assert(validCount > 0, "got at least one face");
+                if (validCount == 1)
+                    singleCount++;
+                else
+                    multipleCount++;
+            }
+        }
+        t_assert(singleCount == 4 * 20,
+                 "got single face for 4 aligned hex base cells per face");
+        t_assert(multipleCount == 1.5 * 20,
+                 "got multiple faces for non-aligned hex base cells");
+    }
+
+    TEST(baseCellPentagons) {
+        for (int i = 0; i < NUM_BASE_CELLS; i++) {
+            if (_isBaseCellPentagon(i)) {
+                // Make the base cell index
+                H3Index baseCell;
+                setH3Index(&baseCell, 0, i, 0);
+                assertPentagonFaces(baseCell);
+            }
+        }
+    }
+}

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

@@ -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.
@@ -50,10 +50,6 @@ typedef struct {
 extern const GeoCoord faceCenterGeo[NUM_ICOSA_FACES];
 
 // indexes for faceNeighbors table
-/** Invalid faceNeighbors table direction */
-#define INVALID -1
-/** Center faceNeighbors table direction */
-#define CENTER 0
 /** IJ quadrant faceNeighbors table direction */
 #define IJ 1
 /** KI quadrant faceNeighbors table direction */
@@ -61,6 +57,19 @@ extern const GeoCoord faceCenterGeo[NUM_ICOSA_FACES];
 /** JK quadrant faceNeighbors table direction */
 #define JK 3
 
+/** Invalid face index */
+#define INVALID_FACE -1
+
+/** Digit representing overage type */
+typedef enum {
+    /** No overage (on original face) */
+    NO_OVERAGE = 0,
+    /** On face edge (only occurs on substrate grids) */
+    FACE_EDGE = 1,
+    /** Overage on new face interior */
+    NEW_FACE = 2
+} Overage;
+
 // Internal functions
 
 void _geoToFaceIjk(const GeoCoord* g, int res, FaceIJK* h);
@@ -69,8 +78,11 @@ void _faceIjkToGeo(const FaceIJK* h, int res, GeoCoord* g);
 void _faceIjkToGeoBoundary(const FaceIJK* h, int res, int isPentagon,
                            GeoBoundary* g);
 void _faceIjkPentToGeoBoundary(const FaceIJK* h, int res, GeoBoundary* g);
+void _faceIjkToVerts(FaceIJK* fijk, int* res, FaceIJK* fijkVerts);
+void _faceIjkPentToVerts(FaceIJK* fijk, int* res, FaceIJK* fijkVerts);
 void _hex2dToGeo(const Vec2d* v, int face, int res, int substrate, GeoCoord* g);
-int _adjustOverageClassII(FaceIJK* fijk, int res, int pentLeading4,
-                          int substrate);
+Overage _adjustOverageClassII(FaceIJK* fijk, int res, int pentLeading4,
+                              int substrate);
+Overage _adjustPentVertOverage(FaceIJK* fijk, int res);
 
 #endif