h3 3.6.0 → 3.7.2

data/ext/h3/src/CONTRIBUTING.md

@@ -9,7 +9,7 @@ Planned improvements and changes are listed on the [H3 Roadmap](https://github.c
 * Please include tests that show the bug is fixed or feature works as intended.
 * Please add a description of your change to the Unreleased section of the [changelog](./CHANGELOG.md).
 * Please open issues to discuss large features or changes which would break compatibility, before submitting pull requests.
-* Please keep H3 compatible with major C compilers, such as GCC, Clang, and MSVC.
+* Please keep H3 compatible with major C compilers, such as GCC, Clang, and MSVC. We use clang-format-9 for source code formatting, if you have another version the CI job may error on formatting differences.
 * Please keep code coverage of the core H3 library at 100%.
 
 Before we can merge your changes, you must agree to the [Uber Contributor License Agreement](https://cla-assistant.io/uber/h3).

data/ext/h3/src/README.md

@@ -1,24 +1,27 @@
-<img align="right" src="https://uber.github.io/res/h3Logo-color.svg" alt="H3 Logo" width="200">
+<img align="right" src="https://uber.github.io/img/h3Logo-color.svg" alt="H3 Logo" width="200">
 
 # H3: A Hexagonal Hierarchical Geospatial Indexing System
 
-[![Build Status](https://travis-ci.com/uber/h3.svg?branch=master)](https://travis-ci.com/uber/h3)
-[![Build status](https://ci.appveyor.com/api/projects/status/61431y4sc5w0tsuk/branch/master?svg=true)](https://ci.appveyor.com/project/Uber/h3/branch/master)
+[![test-linux](https://github.com/uber/h3/workflows/test-linux/badge.svg)](https://github.com/uber/h3/actions)
+[![test-macos](https://github.com/uber/h3/workflows/test-macos/badge.svg)](https://github.com/uber/h3/actions)
+[![test-windows](https://github.com/uber/h3/workflows/test-windows/badge.svg)](https://github.com/uber/h3/actions)
+[![test-website](https://github.com/uber/h3/workflows/test-website/badge.svg)](https://github.com/uber/h3/actions)
 [![Coverage Status](https://coveralls.io/repos/github/uber/h3/badge.svg?branch=master)](https://coveralls.io/github/uber/h3?branch=master)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
 
 H3 is a geospatial indexing system using a hexagonal grid that can be (approximately) subdivided into finer and finer hexagonal grids, combining the benefits of a hexagonal grid with [S2](https://code.google.com/archive/p/s2-geometry-library/)'s hierarchical subdivisions.
 
-Documentation is available at [https://uber.github.io/h3/](https://uber.github.io/h3/). Developer documentation in Markdown format is available under the [dev-docs](./dev-docs/) directory.
+Documentation is available at [https://h3geo.org/](https://h3geo.org/). Developer documentation in Markdown format is available under the [dev-docs](./dev-docs/) directory.
 
  * Post **bug reports or feature requests** to the [GitHub Issues page](https://github.com/uber/h3/issues)
  * Ask **questions** by posting to the [H3 tag on StackOverflow](https://stackoverflow.com/questions/tagged/h3)
+ * There is also an [H3 Slack workspace](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg)
 
 ## Installing
 
-We recommend using prebuilt bindings if they are available for your programming language. Bindings for [Go](https://github.com/uber/h3-go), [Java](https://github.com/uber/h3-java), [JavaScript](https://github.com/uber/h3-js), [Python](https://github.com/uber/h3-py), and [others](https://uber.github.io/h3/#/documentation/community/bindings) are available.
+We recommend using prebuilt bindings if they are available for your programming language. Bindings for [Go](https://github.com/uber/h3-go), [Java](https://github.com/uber/h3-java), [JavaScript](https://github.com/uber/h3-js), [Python](https://github.com/uber/h3-py), and [others](https://h3geo.org/docs/community/bindings) are available.
 
-On macOS, you can install H3 using brew:
+On macOS, you can install H3 using `brew`:
 ```
 brew install h3
 ```
@@ -30,7 +33,7 @@ Still here? To build the H3 C library, you'll need a C compiler (tested with `gc
 
 #### Install build-time dependencies
 
-* Alpine 
+* Alpine
 ```
 # Installing the bare build requirements
 apk add cmake make gcc libtool musl-dev
@@ -45,7 +48,7 @@ sudo apt install cmake make gcc libtool
 sudo apt install clang-format cmake-curses-gui lcov doxygen
 ```
 
-* macOS (using brew)
+* macOS (using `brew`)
 
 First make sure you [have the developer tools installed](http://osxdaily.com/2014/02/12/install-command-line-tools-mac-os-x/) and then
 
@@ -60,24 +63,71 @@ brew install clang-format lcov doxygen
 
 You will need to install CMake and Visual Studio, including the Visual C++ compiler. For building on Windows, please follow the [Windows build instructions](dev-docs/build_windows.md).
 
+* FreeBSD
+
+ ```
+# Installing the build requirements
+sudo pkg install bash cmake gmake doxygen lcov
+```
+
 #### Compilation
 
-From the repository you would then compile like so:
+From the repository root, you can compile H3 with:
 
 ```
-cmake .
+mkdir build
+cd build
+cmake ..
 make
 ```
 
+All subsequent `make` commands should be run from within the `build` directory.
+
+**Note**: There are several ways to build H3 with CMake; the method above is just one example that restricts all build artifacts to the `build` directory.
+
 You can install system-wide with:
 
 ```
 sudo make install
 ```
 
+If using the method above, from the repository root, you can clean all build artifacts with:
+
+```
+rm -rf build
+```
+
 #### Testing
 
-After making the project, you can test with `make test`, and if `lcov` is installed you can `make coverage` to generate a code coverage report.
+After making the project, you can test with `make test`.
+You can run a faster test suite that excludes the most expensive tests with `make test-fast`.
+
+#### Coverage
+
+You can generate a code coverage report if `lcov` is installed, and if the project was built with the `CMAKE_BUILD_TYPE=Debug` option.
+For example, from a clean repository, you could run:
+
+```
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Debug ..
+make
+make coverage
+```
+
+You can then view a detailed HTML coverage report by opening `coverage/index.html` in your browser.
+
+#### Benchmarks
+
+You can run timing benchmarks by building with the `CMAKE_BUILD_TYPE=Release`, and running `make benchmarks`:
+
+```
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Release ..
+make
+make benchmarks
+```
 
 #### Documentation
 

data/ext/h3/src/RELEASE.md

@@ -2,8 +2,10 @@
 
 1. Create a PR "Preparing for release X.Y.Z" against master branch
     * Alter CHANGELOG.md from `[Unreleased]` to `[X.Y.Z] YYYY-MM-DD`
-    * Run `make update-version` and give `X.Y.Z` when prompted
+    * Run `make update-version` and give `X.Y.Z` when prompted (this updates
+      the VERSION file, so don't change it manually)
     * Check that all merges that need to be in the changelog are present
+    * Get reviews and merge the PR
 
 2. Create a release "Release X.Y.Z" on Github
     * Create Tag `vX.Y.Z`

data/ext/h3/src/VERSION

@@ -1 +1 @@
-3.6.0
+3.7.2

data/ext/h3/src/dev-docs/RFCs/rfc-template.md

@@ -0,0 +1,21 @@
+# RFC: <Subject>
+
+* **Authors**: -
+* **Date**: -
+* **Status**: Draft
+
+## Abstract
+
+*Brief overview of the subject and proposal*
+
+## Motivation
+
+*Why is this important?*
+
+## Approaches
+
+*What are the various options to address this issue?*
+
+## Proposal
+
+*What is the recommended approach?*

data/ext/h3/src/dev-docs/RFCs/v4.0.0/error-handling-rfc.md

@@ -0,0 +1,21 @@
+# RFC: Consistent error handling
+
+* **Authors**: -
+* **Date**: -
+* **Status**: Draft
+
+## Abstract
+
+Error handling in the H3 library is inconsistent across functions, many of which have no explicit mechanism to indicate that an error occured. This RFC proposes updating all functions that allocate blocks of memory or that could receive invalid input to return an integer code indicating success or error.
+
+## Motivation
+
+*Why is this important?*
+
+## Approaches
+
+*What are the various options to address this issue?*
+
+## Proposal
+
+*What is the recommended approach?*

data/ext/h3/src/dev-docs/RFCs/v4.0.0/names_for_concepts_types_functions.md

@@ -0,0 +1,276 @@
+# RFC: Names for H3 Concepts, Types, and Functions
+
+- **Authors**:
+    - AJ Friend
+    - Nick Rabinowitz
+    - Isaac Brodsky
+    - David Ellis
+- **Dates**:
+    - Started: 2020-02-02
+    - Accepted: 2020-03-26
+- **Status**: Accepted
+- **Discussions**:
+    - <https://github.com/uber/h3/pull/308>
+
+## Motivation
+
+Concepts like `hexagon`, `cell`, and `index` are currently used ambiguously in the H3 codebase and in documentation.
+This can cause confusion, for example, when a function might only work on strict H3 *hexagons*, but fails when encountering H3 *pentagons*.
+
+Reaching a consensus on the precise, technical language used when discussing H3 concepts will clarify future library discussions and improve end-user documentation.
+
+We would also like to standardize a function-naming scheme.
+
+## Terminology
+
+The following technical terms should be used in the documentation, the H3 codebase, and precise technical discussions of the library.
+
+- `H3Index`:
+    - an unsigned 64-bit integer representing *any* H3 object (hexagon, pentagon, directed edge ...)
+    - often represented as a 15-character (or 16-character) hexadecimal string, like `'8928308280fffff'`
+    - the full term "H3 index" should be used to avoid confusion with other common uses of "index";
+      when a "traditional" index is needed, prefer using "number", "pos", or another term to avoid confusion
+- **mode**:
+    - an integer describing the type of object being represented by an H3 index
+    - this integer is encoded in the `H3Index`
+- **cell** or **H3 cell**:
+    - a geometric/geographic unit polygon in the H3 grid, corresponding to an `H3Index` of `mode 1` (hexagon or pentagon)
+    - for functions that can handle either hexagons or pentagons, the more general term "cell" should be used whenever possible
+- **hexagon**:
+    - an H3 **cell** that is a **topological** hexagon
+    - below, we explain that functions that *only* work with **hexagons** have an `Unsafe` suffix;
+      these functions are paired with ones having a `Safe` suffix, meaning they can handle **pentagons**, but are slower
+- **pentagon**:
+    - an H3 **cell** that is a **topological** pentagon
+- **directed edge**:
+    - represents a traversal from an origin **cell** to an adjacent destination **cell**
+    - corresponds to an `H3Index` of `mode 2`
+- **grid**:
+    - the graph with nodes corresponding to H3 cells, and edges given by pairs of adjacent cells
+    - for example, `gridDistance` is the minimal number of edges in a graph path connecting two cells
+- **point**:
+    - a representation of a geographic point in terms of a latitude/longitude pair
+- **topological**:
+    - H3 cells are **topological** pentagons or hexagons, in the sense that they have 5 or 6 neighbors, respectively, in the H3 **grid**
+    - the majority of **hexagons** are also **geometric** hexagons (similarly with **pentagons**), in that they have 6 edges and vertices when represented as polygons of lat/lng points
+    - a small number of **hexagons** are not **geometric** hexagons (similarly with **pentagons**), in that they have extra vertices and edges due to distortion around icosahedron boundaries
+    - for more details, see this [h3-js issue](https://github.com/uber/h3-js/issues/53) or this [Observable post](https://observablehq.com/@fil/h3-oddities)
+- **base cell**:
+    - one of the 122 H3 **cells** (110 hexagons and 12 pentagons) of resolution `0`
+    - every other cell in H3 is a child of a base cell
+    - each base cell has a "base cell number" (0--121), which is encoded into the `H3Index` representation of every H3 cell
+    - there is a one-to-one correspondence between the "base cell number" and the `H3Index` representation of resolution `0` cells
+        + e.g., base cell 0 has `H3Index` hexadecimal representation `'8001fffffffffff'`
+- **boundary**:
+    - all or part of the list of geometric points that enclose an H3 cell
+    - may include more than 6 points in the case that a cell is not a geometric hexagon, such as when a hexagon crosses an icosahedron boundary
+    - may also be used to describe the boundary between two geometric cells, as in the case of an edge
+    - represented in the H3 codebase with the `CellBoundary` struct (previously `GeoBoundary` before v4.0)
+- `H3_NULL`;
+    - equivalent to `0` and guaranteed to never be a valid `H3Index` (even after any future H3 **modes** are added)
+    - returned by functions to denote an error, or to denote missing data in arrays of `H3Index`
+    - analogous to `NaN` in floating point
+
+
+### Use of "hex", "hexagon", "cell", "pentagon", etc.
+
+We realize that "hex" or "hexagon" will still be used informally to refer to the concept of "cell" (As the development team, we do it ourselves!).
+This should be expected in casual, informal discussions of H3.
+However, when *precision* is required, we advise the use of strict technical terms like "index", "cell", "hexagon", "pentagon", etc.
+In the codebase and in the documentation, strictly correct terminology should *always* be used, as many functions and algorithms distinguish between hexagons and pentagons.
+
+
+## `H3_EXPORT` and C name collisions
+
+To avoid C name collisions, we should build the bindings (`h3-py`, `h3-java`, `h3-go`, and `h3-node`) with a standard function prefix, using the `H3_EXPORT` C macro.
+The `h3-js` binding would not need this.
+
+The proposed prefix is `h3_`.
+
+## Functions
+
+### Conventions for "property getters" and transforms
+
+- use `get` prefix for
+    + constant data (`getNumCells`, `getRes0Cells`)
+    + object properties (`getResolution`, `getBaseCellNumber`)
+- use `to` to denote transforms
+    + different representations of the same object
+    + when doing a lossy transformation to a new object (`cellToParent`, `pointToCell`)
+- do not use `get` or `to` for *computations*
+    + e.g., `polyfill`, `compact`, `cellAreaKm2`
+
+There is some ambiguity between property, transform, and computation, so use your best judgement with these guidelines in mind.
+
+### Validity checks
+
+- `isValid*` should mean that a *full* validity check is made
+- without `Valid` (like in the case of `isPentagon`), we do not guarantee
+  that a full validity check is made; instead, a user should assume only a
+  minimal bit mask check is done
+    - we could imagine a `isValidPengaton` function, if full verification
+      would be convenient
+- similarly, a function like `areNeighborCells` will assume each cell
+  has passed the `isValidCell` check; the function will do only minimal
+  work to determine if they are neighbors
+
+
+### General Function Names
+
+|          Current name         |     Proposed name     |
+|-------------------------------|-----------------------|
+| *Does Not Exist (DNE)*        | `isValidIndex`        |
+| `h3IsValid`                   | `isValidCell`         |
+| `h3UnidirectionalEdgeIsValid` | `isValidDirectedEdge` |
+| `h3IsPentagon`                | `isPentagon`          |
+| `h3IsResClassIII`             | `isResClassIII`       |
+| `h3IndexesAreNeighbors`       | `areNeighborCells`    |
+| `h3ToParent`                  | `cellToParent`        |
+| `h3ToCenterChild`             | `cellToCenterChild`   |
+| `h3ToChildren`                | `cellToChildren`      |
+| `numHexagons`                 | `getNumCells`         |
+| `getRes0Indexes`              | `getRes0Cells`        |
+| `getPentagonIndexes`          | `getPentagons`        |
+| `h3GetBaseCell`               | `getBaseCellNumber`   |
+| `h3GetResolution`             | `getResolution`       |
+| *DNE*                         | `getMode`             |
+| `h3GetFaces`                  | `getIcosahedronFaces` |
+| `geoToH3`                     | `pointToCell`         |
+| `h3ToGeo`                     | `cellToPoint`         |
+| `compact`                     | `compactCells`        |
+| `uncompact`                   | `uncompactCells`      |
+| `polyfill`                    | `polygonToCells`      |
+
+**Note**: `getResolution` and `getBaseCellNumber` should work for both cells and edges.
+
+
+### H3 Grid Functions
+
+Many of these functions will have three forms:
+- `<func_name>`
+- `<func_name>Unsafe`
+- `<func_name>Safe`
+
+The `Unsafe` version is fast, but may fail if it encounters a pentagon.
+It should return a failure code in this case.
+
+The `Safe` version is slower, but will work in all cases.
+
+The version without either suffix is intended to be the one typically
+used.
+This version will first attempt the `Unsafe` version, and if
+it detects failure, will fall back to the `Safe` version.
+Encountering pentagons is rare in most use-cases, so this version
+should usually be equivalent to the fast version, but with a guarantee
+that it will not fail.
+
+Initially, we **will not** expose the `Safe` versions to users in the API.
+We may expose them in the future if a need becomes clear.
+
+
+#### Distance
+
+| Current name |      Proposed name      |
+|--------------|-------------------------|
+| `h3Distance` | `gridDistance`          |
+| `h3Line`     | `gridPathCells`         |
+| *DNE*        | `gridPathEdges`         |
+| *DNE*        | `gridPathDirectedEdges` |
+
+
+#### Filled-In Disk With Distances
+
+|     Current name    |       Proposed name       |                 Calls                 |
+|---------------------|---------------------------|---------------------------------------|
+| `hexRangeDistances` | `gridDiskDistancesUnsafe` | NONE                                  |
+| `_kRingInternal`    | `gridDiskDistancesSafe`   | NONE                                  |
+| `kRingDistances`    | `gridDiskDistances`       | `hexRangeDistances`, `_kRingInternal` |
+
+
+#### Filled-In Disk Without Distances
+
+| Current name |   Proposed name   |        Calls        |
+|--------------|-------------------|---------------------|
+| `hexRange`   | `gridDiskUnsafe`  | `hexRangeDistances` |
+| *DNE*        | `gridDiskSafe`    |                     |
+| `kRing`      | `gridDisk`        | `kRingDistances`    |
+| `hexRanges`  | `gridDisksUnsafe` | N x `hexRange`      |
+
+- **Note**: We may remove `hexRanges` from the API, as it is just a very simple wrapper around
+  `hexRange`. Inclusion is a discussion separate from this RFC. We'll simply state that
+  *if we do* include it, we will rename it `gridDisksUnsafe`.
+
+
+#### Hollow Ring
+
+| Current name |  Proposed name   |              Calls               |
+|--------------|------------------|----------------------------------|
+| `hexRing`    | `gridRingUnsafe` | NONE                             |
+| *DNE*        | `gridRingSafe`   | `gridDiskDistancesSafe`          |
+| *DNE*        | `gridRing`       | `gridRingUnsafe`, `gridRingSafe` |
+
+### H3 Edge Types
+
+Instead of `UnidirectionalEdge`, use the term `DirectedEdge`.
+
+For a future undirected edge mode, use the term `Edge`.
+
+|                  Current name                 |        Proposed name         |
+|-----------------------------------------------|------------------------------|
+| `h3UnidirectionalEdgeIsValid`                 | `isValidDirectedEdge`        |
+| `getH3UnidirectionalEdge`                     | `cellsToDirectedEdge`        |
+| `getH3IndexesFromUnidirectionalEdge`          | `directedEdgeToCells`        |
+| `getH3UnidirectionalEdgesFromHexagon`         | `originToDirectedEdges`      |
+| *DNE*                                         | `destinationToDirectedEdges` |
+| `getH3UnidirectionalEdgeBoundary`             | `directedEdgeToBoundary`     |
+| `getOriginH3IndexFromUnidirectionalEdge`      | `getDirectedEdgeOrigin`      |
+| `getDestinationH3IndexFromUnidirectionalEdge` | `getDirectedEdgeDestination` |
+
+
+### Area/Length Functions
+
+|  Current name  |        Proposed name        |
+|----------------|-----------------------------|
+| `hexAreaKm2`   | `getHexagonAreaAvgKm2`      |
+| `hexAreaM2`    | `getHexagonAreaAvgM2`       |
+| `edgeLengthKm` | `getHexagonEdgeLengthAvgKm` |
+| `edgeLengthM`  | `getHexagonEdgeLengthAvgM`  |
+| *DNE*          | `getPentagonAreaAvg*`       |
+| *DNE*          | `getPentagonEdgeLengthAvg*` |
+| *DNE*          | `cellAreaKm2`               |
+| *DNE*          | `cellAreaM2`                |
+
+**Note**: `cellAreaKm2` and `cellAreaM2` would return the actual area of
+the passed-in cell.
+
+
+## Polygons
+
+**Note**: In addition to the changes listed in this section, we are considering
+removing the `Linked*` data types from the public API. However, that is a larger
+discussion requiring benchmarking, so we will defer that to a
+[separate issue](https://github.com/uber/h3/issues/323) outside of this RFC.
+
+
+### Data Structures
+
+- rename `GeoBoundary` to `CellBoundary` to indicate it is space-limited to describing the geometry of cells
+
+|    Current name   |   Proposed name   |               Notes               |
+|-------------------|-------------------|-----------------------------------|
+| `GeoBoundary`     | `CellBoundary`    | <= 10 stack-allocated `GeoPoint`s |
+| `GeoCoord`        | `GeoPoint`        |                                   |
+| `Geofence`        | `GeoLoop`         | heap-allocated `GeoPoint`s        |
+| `GeoPolygon`      | `GeoPolygon`      |                                   |
+| `GeoMultiPolygon` | `GeoMultiPolygon` | currently not used                |
+
+
+### Functions
+
+|            Current name           |      Proposed name       |         Notes          |
+|-----------------------------------|--------------------------|------------------------|
+| `h3ToGeoBoundary`                 | `cellToBoundary`         | returns `CellBoundary` |
+| *DNE*                             | `cellToLoop`             | returns `GeoLoop`      |
+| *DNE*                             | `loopToBoundary`         |                        |
+| *DNE*                             | `boundaryToLoop`         |                        |
+| `getH3UnidirectionalEdgeBoundary` | `directedEdgeToBoundary` | returns `CellBoundary` |