h3 3.5.0 → 3.7.1

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

@@ -1,9 +1,8 @@
-Determine the latitude/longitude coordinates of the center point of an H3Index cell
----
+# Determine the latitude/longitude coordinates of the center point of an H3Index cell
 
 This operation is performed by function `h3ToGeo`. See the comments in the function source code for more detail.
 
-The conversion is performed as a series of coordinate system conversions described below. See the page <a href="#/documentation/core-library/coordinate-systems">Coordinate Systems used by the **H3 Core Library**</a> for more information on each of these coordinate systems.
+The conversion is performed as a series of coordinate system conversions described below. See the page [Coordinate Systems used by the **H3 Core Library**](/docs/core-library/coordsystems) for more information on each of these coordinate systems.
 
 *  The function `_h3ToFaceIjk` then converts the **H3** index to the appropriate icosahedron face number and normalized *ijk* coordinate's on that face's coordinate system as follows:
    * We start by assuming that the cell center point falls on the same icosahedron face as its base cell.
@@ -11,7 +10,7 @@ The conversion is performed as a series of coordinate system conversions describ
      We determine whether an overage exists by taking the sum of the *ijk* components, and if there is an overage the positive *ijk* components indicate which adjacent face the cell center lies on. A lookup operation is then performed to find the appropriate rotation and translation to transform the *ijk* coordinates into the adjacent face-centered *ijk* system.
 
 <div align="center">
-  <img height="300" src="images/triEdge.png" />
+  <img height="300" src="/images/triEdge.png" />
 </div>
 
 * The face-centered *ijk* coordinates are then converted into corresponding *Hex2d* coordinates using the function `_ijkToHex2d`.

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

@@ -1,45 +1,54 @@
-H3 Index Representations
----
+# H3 Index Representations
 
-Introduction
----
+## Introduction
 
 The **H3** system assigns a unique hierarchical index to each cell. The **H3** index of a resolution *r* cell begins with the appropriate resolution 0 base cell number. This is followed by a sequence of *r* digits 0-6, where each *i*<sup>th</sup> digit *d*<sub>i</sub> specifies one of the 7 cells centered on the cell indicated by the coarser resolution digits *d*<sub>1</sub> through *d*<sub>i-1</sub>. A local hexagon coordinate system is assigned to each of the resolution 0 base cells and is used to orient all hierarchical indexing child cells of that base cell. The assignment of digits 0-6 at each resolution uses a *Central Place Indexing* arrangement (see [Sahr, 2014](http://webpages.sou.edu/~sahrk/sqspc/pubs/autocarto14.pdf)). In the case of the 12 pentagonal cells the indexing hierarchy produced by sub-digit 1 is removed at all resolutions.
 
 Child hexagons are linearly smaller than their parent hexagons.
 
 <div align="center">
-  <img height="300" src="images/cpidigits.png" />
+  <img height="300" src="/images/cpidigits.png" />
 </div>
 
 
-H3Index Representation
----
+## H3Index Representation
 
-The **H3Index** is the integer representation of an **H3** index, which can be placed into multiple modes to indicate the kind of concept being indexed. Mode 1 is an **H3** Cell (Hexagon) Index, mode 2 is an **H3** Unidirectional Edge (Hexagon A -> Hexagon B) Index, mode 3 is planned to be a bidirectional edge (Hexagon A <-> Hexagon B). Mode 0 is reserved and indicates an invalid **H3** index.
+The **H3Index** is the integer representation of an **H3** index, which can be placed into multiple modes to indicate the concept being indexed.
 
-The components of the **H3** cell index (mode 1) are packed into the lowest order 63 bits of a 64-bit integer in order as follows:
+* Mode 1 is an **H3** Cell (Hexagon/Pentagon) index.
+* Mode 2 is an **H3** Unidirectional Edge (Cell A -> Cell B) index.
+* Mode 3 is planned to be a bidirectional edge (Cell A <-> Cell B).
+* Mode 0 is reserved and indicates an invalid **H3** index.
+  * This mode remains, partially, for backwards compatibility with an older version of H3.
 
+Mode 0 contains a special index, `H3_NULL`, which is unique: it is bit-equivalent to `0`.
+This index indicates, *specifically*, an invalid, missing, or uninitialized **H3** index;
+it is analogous to `NaN` in floating point.
+It should be used instead of an arbitrary Mode 0 index, due to its uniqueness and easy identifiability.
+
+The components of the **H3** cell index (mode 1) are packed into a 64-bit integer in order, highest bit first, as follows:
+
+* 1 bit reserved and set to 0,
 * 4 bits to indicate the index mode,
-* 3 bits reserved,
+* 3 bits reserved and set to 0,
 * 4 bits to indicate the cell resolution 0-15,
 * 7 bits to indicate the base cell 0-121, and
-* 3 bits to indicate each subsequent digit 0-6 from resolution 1 up to the resolution of the cell (45 bits total is reserved for resolutions 1-15)
+* 3 bits to indicate each subsequent digit 0-6 from resolution 1 up to the resolution of the cell (45 bits total are reserved for resolutions 1-15)
 
-The components of the **H3** unidirectional edge index (mode 2) are packed into the lowest order 63 bits of a 64-bit integer in order as follows:
+The components of the **H3** unidirectional edge index (mode 2) are packed into a 64-bit integer in order, highest bit first, as follows:
 
+* 1 bit reserved and set to 0,
 * 4 bits to indicate the index mode,
 * 3 bits to indicate the edge 1-6 of the cell to traverse,
 * 4 bits to indicate the cell resolution 0-15,
 * 7 bits to indicate the base cell 0-121, and
-* 3 bits to indicate each subsequent digit 0-6 from resolution 1 up to the resolution of the cell (45 bits total is reserved for resolutions 1-15)
+* 3 bits to indicate each subsequent digit 0-6 from resolution 1 up to the resolution of the cell (45 bits total are reserved for resolutions 1-15)
 
-The canonical string representation of an **H3Index** is the hexadecimal representation of the integer.
+The canonical string representation of an **H3Index** is the hexadecimal representation of the integer, using lowercase letters. The string representation is variable length (no zero padding) and is not prefixed or suffixed.
 
 The three bits for each unused digit are set to 7.
 
-Bit layout of H3Index
----
+## Bit layout of H3Index
 
 The layout of an **H3Index** is shown below in table form. The interpretation of the "Reserved/edge" field differs depending on the mode of the index.
 
@@ -65,7 +74,7 @@ The layout of an **H3Index** is shown below in table form. The interpretation of
 </tr>
 <tr>
   <th>0x30</th>
-  <td></td>
+  <td>Reserved</td>
   <td colspan="4">Mode</td>
   <td colspan="3">Reserved/edge</td>
   <td colspan="4">Resolution</td>

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,6 +1,6 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
-# Copyright 2018 Uber Technologies, Inc.
+# Copyright 2018-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.
@@ -44,7 +44,11 @@ fi
 src_dir=${1:-"Missing source directory"}
 binary_dir=${2:-"Missing binary directory"}
 
+# Exclude the usual LCOV exclusion comment, and also
+# do not require branch coverage for assertions.
+br_exclusion='LCOV_EXCL_BR_LINE|assert\('
+
 cd "${binary_dir}"
-lcov --rc lcov_branch_coverage=1 --directory . --capture --output-file coverage.info
-lcov --rc lcov_branch_coverage=1 --extract coverage.info "${src_dir}/src/h3lib/*" --output-file coverage.cleaned.info
+lcov --rc lcov_branch_coverage=1 --rc "lcov_excl_br_line=$br_exclusion" --directory . --capture --output-file coverage.info
+lcov --rc lcov_branch_coverage=1 --rc "lcov_excl_br_line=$br_exclusion" --extract coverage.info "${src_dir}/src/h3lib/*" --output-file coverage.cleaned.info
 genhtml --branch-coverage -o coverage coverage.cleaned.info --title 'h3 coverage'

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;
+}