h3 3.6.2 → 3.7.1

data/ext/h3/src/docs/core-library/overview.md

@@ -1,5 +1,4 @@
-Overview of the H3 Geospatial Indexing System
----
+# Overview of the H3 Geospatial Indexing System
 
 The **H3** geospatial indexing system is a discrete global grid system (see [Sahr et al., 2003](http://webpages.sou.edu/~sahrk/sqspc/pubs/gdggs03.pdf)) consisting of a multi-precision hexagonal tiling of the sphere with hierarchical indexes. The hexagonal grid system is created on the planar faces of a sphere-circumscribed icosahedron, and the grid cells are then projected to the surface of the sphere using an inverse face-centered polyhedral gnomonic projection.
 
@@ -9,6 +8,6 @@ The **H3** grid is constructed on the icosahedron by recursively creating increa
 
 The first **H3** resolution (resolution 0) consists of 122 cells (110 hexagons and 12 icosahedron vertex-centered pentagons), referred to as the *base cells*. These were chosen to capture as much of the symmetry of the spherical icosahedron as possible. These base cells are assigned numbers from 0 to 121 based on the latitude of their center points; base cell 0 has the northern most center point, while base cell 121 has the southern most center point.
 
-Each subsequent resolution beyond resolution 0 is created using an aperture 7 resolution spacing (aperture refers to the number of cells in the next finer resolution grid for each cell); as resolution increases the unit length is scaled by \\(\sqrt{7}\\) and each hexagon has \\(1/7th\\) the area of a hexagon at the next coarser resolution (as measured on the icosahedron). **H3** provides 15 finer grid resolutions in addition to the resolution 0 base cells. The finest resolution, resolution 15, has cells with an area of less than 1 \\(m^2\\). A table detailing the average cell area for each H3 resolution is available <a href="#/documentation/core-library/resolution-table">here</a>.
+Each subsequent resolution beyond resolution 0 is created using an aperture 7 resolution spacing (aperture refers to the number of cells in the next finer resolution grid for each cell); as resolution increases the unit length is scaled by $\sqrt{7}$ and each hexagon has $1/7th$ the area of a hexagon at the next coarser resolution (as measured on the icosahedron). **H3** provides 15 finer grid resolutions in addition to the resolution 0 base cells. The finest resolution, resolution 15, has cells with an area of less than $1 m^2$. A table detailing the average cell area for each H3 resolution is available [here](/docs/core-library/restable).
 
 *Note:* you can create KML files to visualize the **H3** grids by running the `kml` make target. It will place the files in the `KML` output sub-directory.

data/ext/h3/src/docs/core-library/restable.md

@@ -1,5 +1,4 @@
-Table of Cell Areas for H3 Resolutions
----
+# Table of Cell Areas for H3 Resolutions
 
 | H3 Resolution | Average Hexagon Area (km<sup>2</sup>) | Average Hexagon Edge Length (km) | Number of unique indexes
 | ------------- | ------------------------------------: | -------------------------------: | -----------------------:

data/ext/h3/src/docs/core-library/usage.md

@@ -1,5 +1,4 @@
-How to use H3
----
+# How to use H3
 
 The public API of the **H3 Core Library** is defined in the file h3api.h. The functions defined in h3api.h adhere to [Semantic Versioning](http://semver.org/).
 

data/ext/h3/src/docs/table-of-contents.json

@@ -0,0 +1,47 @@
+{
+  "id": "table-of-contents",
+  "chapters": [
+    {
+      "title": "Overview",
+      "entries": [
+        {"entry": "docs/README"},
+        {"entry": "docs/usecases"}
+      ]
+    },
+    {
+      "title": "Core Library",
+      "entries": [
+        {"entry": "docs/core-library/overview"},
+        {"entry": "docs/core-library/h3indexing"},
+        {"entry": "docs/core-library/coordsystems"},
+        {"entry": "docs/core-library/geoToH3desc"},
+        {"entry": "docs/core-library/h3ToGeoDesc"},
+        {"entry": "docs/core-library/h3ToGeoBoundaryDesc"},
+        {"entry": "docs/core-library/filters"},
+        {"entry": "docs/core-library/usage"},
+        {"entry": "docs/core-library/restable"}
+      ]
+    },
+    {
+      "title": "API Reference",
+      "entries": [
+        {"entry": "docs/api/indexing"},
+        {"entry": "docs/api/inspection"},
+        {"entry": "docs/api/traversal"},
+        {"entry": "docs/api/hierarchy"},
+        {"entry": "docs/api/regions"},
+        {"entry": "docs/api/uniedge"},
+        {"entry": "docs/api/misc"}
+      ]
+    },
+    {
+      "title": "Community",
+      "entries": [
+        {"entry": "docs/community/bindings"},
+        {"entry": "docs/community/libraries"},
+        {"entry": "docs/community/tutorials"},
+        {"entry": "docs/community/applications"}
+      ]
+    }
+  ]
+}

data/ext/h3/src/docs/{overview/usecases.md → usecases.md}

@@ -1,8 +1,4 @@
-Why H3
----
-
-Use cases
----
+# Use cases
 
 Analysis of data sets of locations, such as locations of cars in a city, may be done by bucketing locations. ([Sahr et al., 2003](http://webpages.sou.edu/~sahrk/sqspc/pubs/gdggs03.pdf)) There are several options for partitioning an area into buckets, such as manually drawing regions using human knowledge, or to partition the surface using a regular grid.
 
@@ -16,7 +12,7 @@ Using a regular grid can avoid these drawbacks by providing smooth gradients and
 
 | Triangle | Square | Hexagon
 | -------- | ------ | -------
-| <img src="images/neighbors-triangle.png" style="width:400px"> | <img src="images/neighbors-square.png" style="width:400px"> | <img src="images/neighbors-hexagon.png" style="width:400px">
+| <img src="/images/neighbors-triangle.png" style="width:400px"> | <img src="/images/neighbors-square.png" style="width:400px"> | <img src="/images/neighbors-hexagon.png" style="width:400px">
 | Triangles have 12 neighbors | Squares have 8 neighbors | Hexagons have 6 neighbors
 
 In addition to indexing locations to cells, **H3** provides a number of algorithms operating on indexes.
@@ -24,14 +20,14 @@ In addition to indexing locations to cells, **H3** provides a number of algorith
 Hexagons have the property of expanding rings of neighbors (`kRing`) approximating circles:
 
 <div align="center">
-  <img src="images/neighbors.png" style="width:400px"><br>
+  <img src="/images/neighbors.png" style="width:400px"><br>
   <i>All six neighbors of a hexagon (ring 1)</i>
 </div>
 
 Squares cleanly subdivide into four finer squares. Hexagons do not cleanly subdivide into seven finer hexagons. However, by alternating the orientation of grids a subdivision into seven cells (referred to as *aperture 7*) can be approximated. This makes it possible to truncate the precision (within a fixed margin of error) of an **H3** index using a few bitwise operations (`h3ToParent`). It is also possible to determine all the children of a parent **H3** index (`h3ToChildren`). Approximate containment only applies when truncating the precision of an **H3** index. The borders of hexagons indexed at a specific resolution are not approximate.
 
 <div align="center">
-  <img src="images/parent-child.png" style="width:400px"><br>
+  <img src="/images/parent-child.png" style="width:400px"><br>
   <i>A parent hexagon approximately contains seven children</i>
 </div>
 
@@ -39,11 +35,10 @@ Hierarchical containment allows for use cases like making contiguous sets of hex
 
 | Uncompact (dense) | Compact (sparse)
 | ----------------- | ----------------
-| <img src="images/ca_uncompact_6_10633.png" style="width:500px"> | <img src="images/ca_compact_6_901.png" style="width:500px">
+| <img src="/images/ca_uncompact_6_10633.png" style="width:500px"> | <img src="/images/ca_compact_6_901.png" style="width:500px">
 | California represented by 10633 uncompact hexagons | California represented by 901 compact hexagons
 
-Comparisons
----
+## Comparisons
 
 | System    | Index representation | Cell shape | Projection system
 | --------- | -------------------- | ---------- | -----------------

data/ext/h3/src/scripts/binding_functions.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Copyright 2017 Uber Technologies, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

data/ext/h3/src/scripts/coverage.sh.in

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
 # Copyright 2018-2019 Uber Technologies, Inc.
 #

data/ext/h3/src/scripts/update_version.sh

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Copyright 2019 Uber Technologies, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This script is used interactively as part of the H3 release process 
+# This script is used interactively as part of the H3 release process
 # (RELEASE.md) to update the version number in the VERSION file. Before
 # writing the new version to the file, changelog information is presented
 # for verification. It is invoked by the make target `update-version`.

data/ext/h3/src/src/apps/applib/include/args.h

@@ -23,6 +23,7 @@
 #include <inttypes.h>
 #include <stdbool.h>
 #include <stdio.h>
+
 #include "utility.h"
 
 /** Maximum number of names an argument may have. */

data/ext/h3/src/src/apps/applib/include/test.h

@@ -21,6 +21,7 @@
 #define TEST_H
 
 #include <stdio.h>
+
 #include "geoCoord.h"
 #include "h3api.h"
 

data/ext/h3/src/src/apps/applib/include/utility.h

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2019 Uber Technologies, Inc.
+ * Copyright 2016-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.
@@ -21,6 +21,7 @@
 #define UTILITY_H
 
 #include <stdio.h>
+
 #include "coordijk.h"
 #include "h3api.h"
 
@@ -54,5 +55,10 @@ void iterateAllIndexesAtResPartial(int res, void (*callback)(H3Index),
                                    int maxBaseCell);
 void iterateBaseCellIndexesAtRes(int res, void (*callback)(H3Index),
                                  int baseCell);
+void iterateAllUnidirectionalEdgesAtRes(int res, void (*callback)(H3Index));
+double mapSumAllCells_double(int res, double (*callback)(H3Index));
+size_t packNonzeros(H3Index* a, size_t n);
+
+int countActualHexagons(H3Index* hexagons, int numHexagons);
 
 #endif

data/ext/h3/src/src/apps/applib/lib/args.c

@@ -18,10 +18,12 @@
  */
 
 #include "args.h"
+
 #include <stdbool.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include "h3api.h"
 
 /*

data/ext/h3/src/src/apps/applib/lib/kml.c

@@ -18,7 +18,9 @@
  */
 
 #include "kml.h"
+
 #include <stdio.h>
+
 #include "h3api.h"
 
 void kmlPtsHeader(const char* name, const char* desc) {

data/ext/h3/src/src/apps/applib/lib/test.c

@@ -18,6 +18,7 @@
  */
 
 #include "test.h"
+
 #include <assert.h>
 #include <stdio.h>
 

data/ext/h3/src/src/apps/applib/lib/utility.c

@@ -1,5 +1,5 @@
 /*
- * Copyright 2016-2019 Uber Technologies, Inc.
+ * Copyright 2016-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.
@@ -18,12 +18,14 @@
  */
 
 #include "utility.h"
+
 #include <assert.h>
 #include <inttypes.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <time.h>
+
 #include "coordijk.h"
 #include "h3Index.h"
 #include "h3api.h"
@@ -175,6 +177,122 @@ int readBoundary(FILE* f, GeoBoundary* b) {
     return 0;
 }
 
+/**
+ * Move nonzero elements to the front of array `a` of length `n`.
+ *
+ * Loop invariant: Everything *before* `i` or *after* `j` is "done".
+ * Move `i` and `j` inwards until they equal, and exit.
+ * You can move `i` forward until there's a zero in front of it.
+ * You can move `j` backward until there's a nonzero to the left of it.
+ * Anything to the right of `j` is "junk" that can be reallocated.
+ *
+ * Before:
+ *   | a | b | 0 | c | d | ... |
+ *           ^           ^
+ *           i           j
+ * After:
+ *   | a | b | d | c | d | ... |
+ *           ^       ^
+ *           i       j
+ *
+ * todo: should this function be in the public API?
+ * todo: add tests for this function
+ *
+ * @param   a  H3Index array to whose elements will be moved
+ * @param   n  length of the input array
+ * @return     number of nonzero elements (length of new array); can reallocate
+ *             memory after this point
+ */
+size_t packNonzeros(H3Index* a, size_t n) {
+    size_t i = 0;
+    size_t j = n;
+
+    while (i < j) {
+        // move j to the left until the first nonzero
+        if (a[j - 1] == 0) {
+            j -= 1;
+            continue;
+        }
+
+        // move i to the right until the first zero
+        if (a[i] != 0) {
+            i += 1;
+            continue;
+        }
+
+        // if we get to this point, we know:
+        // a[i] == 0
+        // a[j-1] != 0
+        // i < j
+        // so we can swap! (actually, move a[j-1] -> a[i])
+        a[i] = a[j - 1];
+        j -= 1;
+    }
+
+    return i;
+}
+
+/**
+ * Array of all cells at a given resolution.
+ *
+ * @param   res  resolution
+ *
+ * @return       array of H3 cells at resolution res
+ */
+H3Index* getCellsAtRes(int res) {
+    int num0 = H3_EXPORT(res0IndexCount)();
+    H3Index* cells0 = calloc(num0, sizeof(H3Index));
+    H3_EXPORT(getRes0Indexes)(cells0);
+
+    int numRes = H3_EXPORT(maxUncompactSize)(cells0, num0, res);
+
+    H3Index* cellsRes = calloc(numRes, sizeof(H3Index));
+    H3_EXPORT(uncompact)(cells0, num0, cellsRes, numRes, res);
+
+    free(cells0);
+
+    numRes = packNonzeros(cellsRes, numRes);
+    cellsRes = realloc(cellsRes, numRes * sizeof(H3Index));
+
+    return cellsRes;
+}
+
+/**
+ * Apply callback to every cell for a given resolution, and sum the results.
+ */
+double mapSumAllCells_double(int res, double (*callback)(H3Index)) {
+    H3Index* cells = getCellsAtRes(res);
+    int N = H3_EXPORT(numHexagons)(res);
+
+    double total = 0.0;
+    for (int i = 0; i < N; i++) {
+        total += (*callback)(cells[i]);
+    }
+    free(cells);
+
+    return total;
+}
+
+/**
+ * Apply callback for every unidirectional edge at the given resolution.
+ */
+void iterateAllUnidirectionalEdgesAtRes(int res, void (*callback)(H3Index)) {
+    H3Index* cells = getCellsAtRes(res);
+    int N = H3_EXPORT(numHexagons)(res);
+
+    for (int i = 0; i < N; i++) {
+        H3Index edges[6] = {H3_NULL};
+        int isPentagon = H3_EXPORT(h3IsPentagon)(cells[i]);
+        H3_EXPORT(getH3UnidirectionalEdgesFromHexagon)(cells[i], edges);
+
+        for (int j = 0; j < 6; j++) {
+            if (isPentagon && j == 0) continue;
+            (*callback)(edges[j]);
+        }
+    }
+    free(cells);
+}
+
 /**
  * Call the callback for every index at the given resolution.
  */
@@ -207,7 +325,7 @@ void iterateBaseCellIndexesAtRes(int res, void (*callback)(H3Index),
     H3_EXPORT(uncompact)(&bc, 1, children, childrenSz, res);
 
     for (int j = 0; j < childrenSz; j++) {
-        if (children[j] == 0) {
+        if (children[j] == H3_NULL) {
             continue;
         }
 
@@ -233,3 +351,16 @@ void randomGeo(GeoCoord* g) {
         (((float)rand() / (float)(RAND_MAX)) * 180.0) - 90.0);
     g->lon = H3_EXPORT(degsToRads)((float)rand() / (float)(RAND_MAX)) * 360.0;
 }
+
+/**
+ * Returns the number of non-invalid indexes in the array.
+ */
+int countActualHexagons(H3Index* hexagons, int numHexagons) {
+    int actualNumHexagons = 0;
+    for (int i = 0; i < numHexagons; i++) {
+        if (hexagons[i] != H3_NULL) {
+            actualNumHexagons++;
+        }
+    }
+    return actualNumHexagons;
+}

data/ext/h3/src/src/apps/benchmarks/benchmarkH3Api.c

@@ -17,7 +17,7 @@
 #include "geoCoord.h"
 #include "h3api.h"
 
-// Fixtures
+// Fixtures (arbitrary res 9 hexagon)
 GeoCoord coord = {0.659966917655, -2.1364398519396};
 H3Index hex = 0x89283080ddbffff;
 

data/ext/h3/src/{website/html.config.js → src/apps/benchmarks/benchmarkH3UniEdge.c}

@@ -1,5 +1,5 @@
 /*
- * Copyright 2018 Uber Technologies, Inc.
+ * 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.
@@ -13,19 +13,22 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+#include "benchmark.h"
+#include "geoCoord.h"
+#include "h3api.h"
 
-module.exports = {
+// Fixtures (arbitrary res 9 hexagon)
+H3Index edges[6] = {0};
+H3Index hex = 0x89283080ddbffff;
 
-  title: 'H3',
+BEGIN_BENCHMARKS();
 
-  meta: [{
-    name: 'description',
-    content: 'A hexagonal hierarchical geospatial indexing system'
-  }],
+GeoBoundary outBoundary;
+H3_EXPORT(getH3UnidirectionalEdgesFromHexagon)(hex, edges);
 
-  scripts: [
-    // Adds Mathjax support
-    'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js?config=TeX-MML-AM_CHTML'
-  ]
+BENCHMARK(getH3UnidirectionalEdgeBoundary, 10000, {
+    for (int i = 0; i < 6; i++)
+        H3_EXPORT(getH3UnidirectionalEdgeBoundary)(edges[i], &outBoundary);
+});
 
-};
+END_BENCHMARKS();