h3 3.6.2 → 3.7.1

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

@@ -20,6 +20,7 @@
  */
 
 #include <math.h>
+
 #include "geoCoord.h"
 #include "h3api.h"
 #include "test.h"

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

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2020 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 cell area functions on a few specific cases
+ *
+ *  usage: `testH3CellArea`
+ */
+
+#include <math.h>
+
+#include "h3Index.h"
+#include "test.h"
+
+static const double areasKm2[] = {
+    2.562182162955496e+06, 4.476842018179411e+05, 6.596162242711056e+04,
+    9.228872919002590e+03, 1.318694490797110e+03, 1.879593512281298e+02,
+    2.687164354763186e+01, 3.840848847060638e+00, 5.486939641329893e-01,
+    7.838600808637444e-02, 1.119834221989390e-02, 1.599777169186614e-03,
+    2.285390931423380e-04, 3.264850232091780e-05, 4.664070326136774e-06,
+    6.662957615868888e-07};
+
+SUITE(h3CellArea) {
+    TEST(specific_cell_area) {
+        GeoCoord gc = {0.0, 0.0};
+        for (int res = 0; res <= MAX_H3_RES - 1; res++) {
+            H3Index cell = H3_EXPORT(geoToH3)(&gc, res);
+            double area = H3_EXPORT(cellAreaKm2)(cell);
+
+            t_assert(fabs(area - areasKm2[res]) < 1e-8,
+                     "cell area should match expectation");
+        }
+    }
+}

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

@@ -0,0 +1,180 @@
+/*
+ * Copyright 2020 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 cell area functions using tests over a large number
+ *        of indexes.
+ *
+ *  usage: `testH3CellAreaExhaustive`
+ */
+
+#include <math.h>
+
+#include "h3Index.h"
+#include "test.h"
+#include "utility.h"
+
+/**
+ * Basic checks around the great circle distance between the centers of two
+ * neighboring cells. Tests positivity and commutativity.
+ *
+ * Tests the functions:
+ *     pointDistRads
+ *     pointDistKm
+ *     pointDistM
+ *
+ * @param  edge  H3 unidirectional edge denoting neighboring cells
+ */
+static void haversine_assert(H3Index edge) {
+    GeoCoord a, b;
+    H3Index origin, destination;
+
+    origin = H3_EXPORT(getOriginH3IndexFromUnidirectionalEdge)(edge);
+    H3_EXPORT(h3ToGeo)(origin, &a);
+
+    destination = H3_EXPORT(getDestinationH3IndexFromUnidirectionalEdge)(edge);
+    H3_EXPORT(h3ToGeo)(destination, &b);
+
+    char pos[] = "distance between cell centers should be positive";
+    char comm[] = "pairwise cell distances should be commutative";
+
+    double ab, ba;
+
+    ab = H3_EXPORT(pointDistRads)(&a, &b);
+    ba = H3_EXPORT(pointDistRads)(&b, &a);
+    t_assert(ab > 0, pos);
+    t_assert(ab == ba, comm);
+
+    ab = H3_EXPORT(pointDistKm)(&a, &b);
+    ba = H3_EXPORT(pointDistKm)(&b, &a);
+    t_assert(ab > 0, pos);
+    t_assert(ab == ba, comm);
+
+    ab = H3_EXPORT(pointDistM)(&a, &b);
+    ba = H3_EXPORT(pointDistM)(&b, &a);
+    t_assert(ab > 0, pos);
+    t_assert(ab == ba, comm);
+
+    t_assert(H3_EXPORT(pointDistKm)(&a, &b) > H3_EXPORT(pointDistRads)(&a, &b),
+             "measurement in kilometers should be greater than in radians");
+    t_assert(H3_EXPORT(pointDistM)(&a, &b) > H3_EXPORT(pointDistKm)(&a, &b),
+             "measurement in meters should be greater than in kilometers");
+}
+
+/**
+ * Tests positivity of edge length calculation for the functions:
+ *
+ *      exactEdgeLengthRads
+ *      exactEdgeLengthKm
+ *      exactEdgeLengthM
+ *
+ * @param  edge  edge to compute the length of
+ */
+static void edge_length_assert(H3Index edge) {
+    char msg[] = "edge has positive length";
+
+    t_assert(H3_EXPORT(exactEdgeLengthRads)(edge) > 0, msg);
+    t_assert(H3_EXPORT(exactEdgeLengthKm)(edge) > 0, msg);
+    t_assert(H3_EXPORT(exactEdgeLengthM)(edge) > 0, msg);
+}
+
+/**
+ * Test that cell area calculations are positive for the functions:
+ *
+ *      cellAreaRads2
+ *      cellAreaKm2
+ *      cellAreaM2
+ *
+ * @param  cell  cell to compute the area of
+ */
+static void cell_area_assert(H3Index cell) {
+    char msg[] = "cell has positive area";
+
+    t_assert(H3_EXPORT(cellAreaRads2)(cell) > 0, msg);
+    t_assert(H3_EXPORT(cellAreaKm2)(cell) > 0, msg);
+    t_assert(H3_EXPORT(cellAreaM2)(cell) > 0, msg);
+}
+
+/**
+ * Apply a cell area calculation function to every cell on the earth at a given
+ * resolution, and check that it sums up the total earth area.
+ *
+ * @param  res        resolution of the cells
+ * @param  cell_area  callback to compute area of each cell
+ * @param  target     expected earth area in some units
+ * @param  tol        error tolerance allowed between expected and actual
+ */
+static void earth_area_test(int res, double (*cell_area)(H3Index),
+                            double target, double tol) {
+    double area = mapSumAllCells_double(res, cell_area);
+
+    t_assert(fabs(area - target) < tol,
+             "sum of all cells should give earth area");
+}
+
+SUITE(h3CellAreaExhaustive) {
+    TEST(haversine_distances) {
+        iterateAllUnidirectionalEdgesAtRes(0, haversine_assert);
+        iterateAllUnidirectionalEdgesAtRes(1, haversine_assert);
+        iterateAllUnidirectionalEdgesAtRes(2, haversine_assert);
+        iterateAllUnidirectionalEdgesAtRes(3, haversine_assert);
+    }
+
+    TEST(edge_length) {
+        iterateAllUnidirectionalEdgesAtRes(0, edge_length_assert);
+        iterateAllUnidirectionalEdgesAtRes(1, edge_length_assert);
+        iterateAllUnidirectionalEdgesAtRes(2, edge_length_assert);
+        iterateAllUnidirectionalEdgesAtRes(3, edge_length_assert);
+    }
+
+    TEST(cell_area_positive) {
+        iterateAllIndexesAtRes(0, cell_area_assert);
+        iterateAllIndexesAtRes(1, cell_area_assert);
+        iterateAllIndexesAtRes(2, cell_area_assert);
+        iterateAllIndexesAtRes(3, cell_area_assert);
+    }
+
+    TEST(cell_area_earth) {
+        // earth area in different units
+        double rads2 = 4 * M_PI;
+        double km2 = rads2 * EARTH_RADIUS_KM * EARTH_RADIUS_KM;
+        double m2 = km2 * 1000 * 1000;
+
+        // Notice the drop in accuracy at resolution 1.
+        // I think this has something to do with Class II vs Class III
+        // resolutions.
+
+        earth_area_test(0, H3_EXPORT(cellAreaRads2), rads2, 1e-14);
+        earth_area_test(0, H3_EXPORT(cellAreaKm2), km2, 1e-6);
+        earth_area_test(0, H3_EXPORT(cellAreaM2), m2, 1e0);
+
+        earth_area_test(1, H3_EXPORT(cellAreaRads2), rads2, 1e-9);
+        earth_area_test(1, H3_EXPORT(cellAreaKm2), km2, 1e-1);
+        earth_area_test(1, H3_EXPORT(cellAreaM2), m2, 1e5);
+
+        earth_area_test(2, H3_EXPORT(cellAreaRads2), rads2, 1e-12);
+        earth_area_test(2, H3_EXPORT(cellAreaKm2), km2, 1e-5);
+        earth_area_test(2, H3_EXPORT(cellAreaM2), m2, 1e0);
+
+        earth_area_test(3, H3_EXPORT(cellAreaRads2), rads2, 1e-11);
+        earth_area_test(3, H3_EXPORT(cellAreaKm2), km2, 1e-3);
+        earth_area_test(3, H3_EXPORT(cellAreaM2), m2, 1e3);
+
+        earth_area_test(4, H3_EXPORT(cellAreaRads2), rads2, 1e-11);
+        earth_area_test(4, H3_EXPORT(cellAreaKm2), km2, 1e-3);
+        earth_area_test(4, H3_EXPORT(cellAreaM2), m2, 1e2);
+    }
+}

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

@@ -22,6 +22,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include "algos.h"
 #include "baseCells.h"
 #include "constants.h"

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

@@ -22,6 +22,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include "algos.h"
 #include "baseCells.h"
 #include "constants.h"

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

@@ -19,6 +19,7 @@
 
 #include <stdio.h>
 #include <stdlib.h>
+
 #include "baseCells.h"
 #include "h3Index.h"
 #include "h3api.h"

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

@@ -22,6 +22,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include "constants.h"
 #include "h3Index.h"
 #include "test.h"
@@ -109,12 +110,41 @@ SUITE(h3Index) {
         for (int i = 0; i <= 0xf; i++) {
             H3Index h = H3_INIT;
             H3_SET_MODE(h, i);
-            char failureMessage[BUFF_SIZE];
-            sprintf(failureMessage, "h3IsValid failed on mode %d", i);
-            t_assert(!H3_EXPORT(h3IsValid)(h) || i == 1, failureMessage);
+            if (i == H3_HEXAGON_MODE) {
+                t_assert(H3_EXPORT(h3IsValid)(h),
+                         "h3IsValid succeeds on valid mode");
+            } else {
+                char failureMessage[BUFF_SIZE];
+                sprintf(failureMessage, "h3IsValid failed on mode %d", i);
+                t_assert(!H3_EXPORT(h3IsValid)(h), failureMessage);
+            }
         }
     }
 
+    TEST(h3IsValidReservedBits) {
+        for (int i = 0; i < 8; i++) {
+            H3Index h = H3_INIT;
+            H3_SET_MODE(h, H3_HEXAGON_MODE);
+            H3_SET_RESERVED_BITS(h, i);
+            if (i == 0) {
+                t_assert(H3_EXPORT(h3IsValid)(h),
+                         "h3IsValid succeeds on valid reserved bits");
+            } else {
+                char failureMessage[BUFF_SIZE];
+                sprintf(failureMessage, "h3IsValid failed on reserved bits %d",
+                        i);
+                t_assert(!H3_EXPORT(h3IsValid)(h), failureMessage);
+            }
+        }
+    }
+
+    TEST(h3IsValidHighBit) {
+        H3Index h = H3_INIT;
+        H3_SET_MODE(h, H3_HEXAGON_MODE);
+        H3_SET_HIGH_BIT(h, 1);
+        t_assert(!H3_EXPORT(h3IsValid)(h), "h3IsValid failed on high bit");
+    }
+
     TEST(h3BadDigitInvalid) {
         H3Index h = H3_INIT;
         // By default the first index digit is out of range.

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

@@ -22,6 +22,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include "h3Index.h"
 #include "h3api.h"
 #include "localij.h"

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

@@ -22,6 +22,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include "h3Index.h"
 #include "h3api.h"
 #include "localij.h"

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

@@ -0,0 +1,175 @@
+/*
+ * Copyright 2020 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 main H3 core library memory management.
+ *
+ *  usage: `testH3Memory`
+ */
+
+#include <math.h>
+#include <string.h>
+
+#include "geoCoord.h"
+#include "h3Index.h"
+#include "h3api.h"
+#include "test.h"
+#include "utility.h"
+
+// Whether to fail all allocations
+static bool failAlloc = false;
+// Actual number of malloc/calloc/realloc calls observed
+static int actualAllocCalls = 0;
+// Actual number of free calls observed
+static int actualFreeCalls = 0;
+// Set to non-zero to begin failing allocations after a certain number of calls
+static int permittedAllocCalls = 0;
+
+void resetMemoryCounters(int permitted) {
+    failAlloc = false;
+    actualAllocCalls = 0;
+    actualFreeCalls = 0;
+    permittedAllocCalls = permitted;
+}
+
+void* test_prefix_malloc(size_t size) {
+    actualAllocCalls++;
+    if (permittedAllocCalls && actualAllocCalls > permittedAllocCalls) {
+        failAlloc = true;
+    }
+    if (failAlloc) {
+        return NULL;
+    }
+    return malloc(size);
+}
+
+void* test_prefix_calloc(size_t num, size_t size) {
+    actualAllocCalls++;
+    if (permittedAllocCalls && actualAllocCalls > permittedAllocCalls) {
+        failAlloc = true;
+    }
+    if (failAlloc) {
+        return NULL;
+    }
+    return calloc(num, size);
+}
+
+void* test_prefix_realloc(void* ptr, size_t size) {
+    actualAllocCalls++;
+    if (permittedAllocCalls && actualAllocCalls > permittedAllocCalls) {
+        failAlloc = true;
+    }
+    if (failAlloc) {
+        return NULL;
+    }
+    return realloc(ptr, size);
+}
+
+void test_prefix_free(void* ptr) {
+    actualFreeCalls++;
+    return free(ptr);
+}
+
+H3Index sunnyvale = 0x89283470c27ffff;
+H3Index pentagon = 0x89080000003ffff;
+
+SUITE(h3Memory) {
+    TEST(kRing) {
+        int k = 2;
+        int hexCount = H3_EXPORT(maxKringSize)(k);
+        H3Index* kRingOutput = calloc(hexCount, sizeof(H3Index));
+
+        resetMemoryCounters(0);
+        H3_EXPORT(kRing)(sunnyvale, k, kRingOutput);
+        t_assert(actualAllocCalls == 0, "kRing did not call alloc");
+        t_assert(actualFreeCalls == 0, "kRing did not call free");
+
+        resetMemoryCounters(0);
+        H3_EXPORT(kRing)(pentagon, k, kRingOutput);
+        t_assert(actualAllocCalls == 1, "kRing called alloc");
+        t_assert(actualFreeCalls == 1, "kRing called free");
+
+        resetMemoryCounters(0);
+        failAlloc = true;
+        memset(kRingOutput, 0, hexCount * sizeof(H3Index));
+        H3_EXPORT(kRing)(pentagon, k, kRingOutput);
+        t_assert(actualAllocCalls == 1, "kRing called alloc");
+        t_assert(actualFreeCalls == 0, "kRing did not call free");
+
+        for (int i = 0; i < hexCount; i++) {
+            t_assert(!kRingOutput[i],
+                     "kRing did not produce output without alloc");
+        }
+
+        free(kRingOutput);
+    }
+
+    TEST(compact) {
+        int k = 9;
+        int hexCount = H3_EXPORT(maxKringSize)(k);
+        int expectedCompactCount = 73;
+
+        // Generate a set of hexagons to compact
+        H3Index* sunnyvaleExpanded = calloc(hexCount, sizeof(H3Index));
+        resetMemoryCounters(0);
+        H3_EXPORT(kRing)(sunnyvale, k, sunnyvaleExpanded);
+        t_assert(actualAllocCalls == 0, "kRing did not call alloc");
+        t_assert(actualFreeCalls == 0, "kRing did not call free");
+
+        H3Index* compressed = calloc(hexCount, sizeof(H3Index));
+
+        resetMemoryCounters(0);
+        failAlloc = true;
+        int err = H3_EXPORT(compact)(sunnyvaleExpanded, compressed, hexCount);
+        t_assert(err == COMPACT_ALLOC_FAILED, "malloc failed (1)");
+        t_assert(actualAllocCalls == 1, "alloc called once");
+        t_assert(actualFreeCalls == 0, "free not called");
+
+        resetMemoryCounters(1);
+        err = H3_EXPORT(compact)(sunnyvaleExpanded, compressed, hexCount);
+        t_assert(err == COMPACT_ALLOC_FAILED, "malloc failed (2)");
+        t_assert(actualAllocCalls == 2, "alloc called twice");
+        t_assert(actualFreeCalls == 1, "free called once");
+
+        resetMemoryCounters(2);
+        err = H3_EXPORT(compact)(sunnyvaleExpanded, compressed, hexCount);
+        t_assert(err == COMPACT_ALLOC_FAILED, "malloc failed (3)");
+        t_assert(actualAllocCalls == 3, "alloc called three times");
+        t_assert(actualFreeCalls == 2, "free called twice");
+
+        resetMemoryCounters(3);
+        err = H3_EXPORT(compact)(sunnyvaleExpanded, compressed, hexCount);
+        t_assert(err == COMPACT_ALLOC_FAILED, "compact failed (4)");
+        t_assert(actualAllocCalls == 4, "alloc called four times");
+        t_assert(actualFreeCalls == 3, "free called three times");
+
+        resetMemoryCounters(4);
+        err = H3_EXPORT(compact)(sunnyvaleExpanded, compressed, hexCount);
+        t_assert(err == COMPACT_SUCCESS, "compact using successful malloc");
+        t_assert(actualAllocCalls == 4, "alloc called four times");
+        t_assert(actualFreeCalls == 4, "free called four times");
+
+        int count = 0;
+        for (int i = 0; i < hexCount; i++) {
+            if (compressed[i] != 0) {
+                count++;
+            }
+        }
+        t_assert(count == expectedCompactCount, "got expected compacted count");
+
+        free(compressed);
+        free(sunnyvaleExpanded);
+    }
+}