h3 3.5.0 → 3.7.1

data/ext/h3/src/dev-docs/RFCs/v4.0.0/polyfill-modes-rfc.md

@@ -0,0 +1,21 @@
+# RFC: Polyfill modes
+
+* **Authors**: -
+* **Date**: -
+* **Status**: Draft
+
+## Abstract
+
+Our current polyfill algorithm allocates cells to polygons based on whether the center of the cell falls within the polygon, using Cartesian geometry. This proposal outlines options for expanding the polyfill algorithm to allow for different containment modes (e.g. wholly contained cells, intersecting cells) and spherical geometry.
+
+## 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/vertex-mode-rfc.md

@@ -0,0 +1,50 @@
+# RFC: Vertex mode
+
+* **Authors**: Nick Rabinowitz
+* **Date**: -
+* **Status**: Draft
+
+## Abstract
+
+This proposal would add a new H3 index mode, Vertex Mode, to provide a canonical id for a vertex in a cell boundary. Each vertex shared by 3 adjacent cells would be represented by a single index.
+
+## Motivation
+
+The advantages of this approach:
+
+* Shared vertices can be compared between hexagons with a strict equality check
+* Vertices can be represented and stored without the trig calls required to produce a lat/lon point
+* Vertex to lat/lon can be guaranteed to return the same result across different cells that share the vertex
+
+At a minimum, this should open up significant performance and correctness gains in `h3SetToLinkedGeo` and `directedEdgeToBoundary`, and there are likely other uses as well.
+
+## Approaches
+
+The proposed approach below is fairly straightforward. The main questions are:
+
+* Whether to have one vertex mode, `H3_VERTEX_MODE`, representing the 5 or 6 topological vertices of each cell, or whether to additionally offer a second vertex mode, `H3_ICOSAEDGE_VERTEX_MODE`, to represent distortion vertices shared by two cells whose edge crosses an edge of the icosahedron. 
+
+* If we have two different modes, which functions return both types, in order, and which functions return only one type.
+
+These two modes are largely orthogonal, and it would be possible to implement only `H3_VERTEX_MODE` first without considering `H3_ICOSAEDGE_VERTEX_MODE`. This simplifies the implementation and keeps the new mode wholly in the topological space, without considering the geometric issues posed by the distortion vertices. However this may make it harder or more expensive to implement transformations from sets of vertices to the geometry of a polygon or edge.
+
+## Proposal
+
+### Format of the index
+
+* The H3 index of the "owner" cell. The owner would be one of the cells that share the vertex (see below).
+* The mode set to `H3_VERTEX_MODE`
+* The reserved bits used to identify the index (0-6) of the vertex on the owner cell, using the index order used by `cellToBoundary`
+
+### Choice of owner
+
+Proposed simple algorithm for determining ownership:
+
+* Find all three neighbors that share a vertex
+* Use the one with the numerically lowest index as the owner
+
+### New library functions
+
+* `void getCellVertexes(H3Index cell, H3Vertex *vertices)`
+* `H3Vertex getCellVertex(H3Index cell, int vertIndex)`
+* `GeoCoord vertexToGeoPoint(H3Vertex vertex)`

data/ext/h3/src/dev-docs/build_windows.md

@@ -10,9 +10,14 @@ cd build
 cmake ..
 ```
 
-You can now open `h3.sln` and build the `ALL_BUILD` project to build the H3 library, filter applications, and tests. Tests can be run by building the `RUN_TESTS` project. From the command line:
+You can now open `h3.sln` and build the `ALL_BUILD` project to build the H3 library, filter applications, and tests. From the command line:
 
 ```
 msbuild ALL_BUILD.vcxproj
+```
+
+Tests can be run by building the `RUN_TESTS` project. Tests require `bash` be available, which is usually supplied by Git for Windows. From the command line:
+
+```
 msbuild RUN_TESTS.vcxproj
 ```

data/ext/h3/src/dev-docs/creating_bindings.md

@@ -2,13 +2,13 @@
 
 H3 is a C library, in part to make it simpler to create bindings for different programming languages. Each language usually has its own way to bind to C functions, but this document can serve as a starting point and list of tips.
 
-There may already be [H3 bindings](https://uber.github.io/h3/#/documentation/community/bindings) available for your language of choice.
+There may already be [H3 bindings](https://h3geo.org/docs/community/bindings) available for your language of choice.
 
 ## Function naming
 
 The `make binding-functions` target produces a file `binding-functions` containing a list of function in the H3 public API, one per line. You can use this as part of your build process to check how much of the H3 public API your bindings expose. This list does not include memory management functions that are needed to allocate arrays to be passed to the H3 API.
 
-Keeping similar names and purposes for functions can make it easier for your users to use the H3 [API Reference](https://uber.github.io/h3/#/documentation/api-reference/).
+Keeping similar names and purposes for functions can make it easier for your users to use the H3 [API Reference](https://h3geo.org/docs/api/indexing).
 
 ## Community
 
@@ -16,7 +16,7 @@ When ready, make a [pull request](https://github.com/uber/h3/edit/master/docs/co
 
 ## Documentation
 
-To be included in the H3 [API reference](https://uber.github.io/h3/#/documentation/api-reference/), your binding should:
+To be included in the H3 [API reference](https://h3geo.org/docs/api/indexing), your binding should:
 
 * Be reasonably up to date with uber/h3.
 * Include bindings for the relevant functions in the output of `make binding-functions`. For example, `stringToH3` may not be necessary if your bindings only supports string H3 indexes.

data/ext/h3/src/dev-docs/custom_alloc.md

@@ -0,0 +1,27 @@
+# Custom Memory Allocators
+
+H3 supports replacing the memory management functions (`malloc`, `calloc`, `realloc`, `free`) used by the library at build time. This can be used to integrate H3 within a managed framework.
+
+When using custom memory allocators, H3 prefixes the names of memory allocation functions with the string you specify. The application linking H3 must have the prefixed replacement functions defined.
+
+When building H3, specify the `H3_ALLOC_PREFIX` option to your prefix of choice, as below:
+
+```
+cmake -DH3_ALLOC_PREFIX=my_prefix_ .
+```
+
+Then, in your application using H3, implement the following functions (replacing `my_prefix_` with the prefix you chose above):
+
+```
+void* my_prefix_malloc(size_t size);
+void* my_prefix_calloc(size_t num, size_t size);
+void* my_prefix_realloc(void* ptr, size_t size);
+void my_prefix_free(void* ptr);
+```
+
+Link to H3 as you would have without the custom allocators. The custom allocators will be used for allocating heap memory in H3.
+
+## Notes/Caveats
+
+* There are a few algorithms like `kRing` that still use the call stack to recurse and could run out of memory that way.
+* H3 does not currently use `realloc`.

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

@@ -1,5 +1,4 @@
-H3 Core
----
+# Introduction
 
 The **H3** geospatial indexing system is a multi-precision hexagonal tiling of the sphere indexed with hierarchical linear indexes. The **H3 Core Library** provides functions for converting between latitude/longitude coordinates and **H3** geospatial indexes. Specifically, the major library entry point functions (defined in `h3api.h`) provide the functionality:
 
@@ -8,4 +7,4 @@ The **H3** geospatial indexing system is a multi-precision hexagonal tiling of t
 * given an **H3** index, determine the cell boundary in latitude/longitude coordinates
 * and more.
 
-The **H3 Core Library** is written entirely in *C*. <a href="#/documentation/community/bindings">Bindings for other languages</a> are available.
+The **H3 Core Library** is written entirely in *C*. [Bindings for other languages](/docs/community/bindings) are available.

data/ext/h3/src/docs/api/hierarchy.md

@@ -26,6 +26,14 @@ int maxH3ToChildrenSize(H3Index h, int childRes);
 
 Returns the size of the array needed by `h3ToChildren` for these inputs.
 
+## h3ToCenterChild
+
+```
+H3Index h3ToCenterChild(H3Index h, int childRes);
+```
+
+Returns the center child (finer) index contained by `h` at resolution `childRes`.
+
 ## compact
 
 ```

data/ext/h3/src/docs/api/misc.md

@@ -34,6 +34,30 @@ double hexAreaM2(int res);
 
 Average hexagon area in square meters at the given resolution.
 
+## cellAreaKm2
+
+```
+double cellAreaKm2(H3Index h);
+```
+
+Exact area of specific cell in square kilometers.
+
+## cellAreaM2
+
+```
+double cellAreaM2(H3Index h);
+```
+
+Exact area of specific cell in square meters.
+
+## cellAreaRads2
+
+```
+double cellAreaRads2(H3Index h);
+```
+
+Exact area of specific cell in square radians.
+
 ## edgeLengthKm
 
 ```
@@ -50,6 +74,31 @@ double edgeLengthM(int res);
 
 Average hexagon edge length in meters at the given resolution.
 
+
+## exactEdgeLengthKm
+
+```
+double exactEdgeLengthKm(H3Index edge);
+```
+
+Exact edge length of specific unidirectional edge in kilometers.
+
+## exactEdgeLengthM
+
+```
+double exactEdgeLengthM(H3Index edge);
+```
+
+Exact edge length of specific unidirectional edge in meters.
+
+## exactEdgeLengthRads
+
+```
+double exactEdgeLengthRads(H3Index edge);
+```
+
+Exact edge length of specific unidirectional edge in radians.
+
 ## numHexagons
 
 ```
@@ -65,6 +114,7 @@ void getRes0Indexes(H3Index *out);
 ```
 
 All the resolution 0 **H3** indexes.
+`out` must be an array of at least size `res0IndexCount()`.
 
 ## res0IndexCount
 
@@ -73,3 +123,47 @@ int res0IndexCount();
 ```
 
 Number of resolution 0 **H3** indexes.
+
+## getPentagonIndexes
+
+```
+void getPentagonIndexes(int res, H3Index *out);
+```
+
+All the pentagon **H3** indexes at the specified resolution.
+`out` must be an array of at least size `pentagonIndexCount()`.
+
+## pentagonIndexCount
+
+```
+int pentagonIndexCount();
+```
+
+Number of pentagon **H3** indexes per resolution. This is always 12, but provided as a convenience.
+
+## pointDistKm
+
+```
+double pointDistKm(const GeoCoord *a, const GeoCoord *b);
+```
+
+Gives the "great circle" or "haversine" distance between pairs of
+GeoCoord points (lat/lng pairs) in kilometers.
+
+## pointDistM
+
+```
+double pointDistM(const GeoCoord *a, const GeoCoord *b);
+```
+
+Gives the "great circle" or "haversine" distance between pairs of
+GeoCoord points (lat/lng pairs) in meters.
+
+## pointDistRads
+
+```
+double pointDistRads(const GeoCoord *a, const GeoCoord *b);
+```
+
+Gives the "great circle" or "haversine" distance between pairs of
+GeoCoord points (lat/lng pairs) in radians.

data/ext/h3/src/docs/community/applications.md

@@ -5,3 +5,4 @@ The following applications use H3. Contributions to this list are welcome, pleas
 ## Visualization
 
 - [kepler.gl](http://kepler.gl/) - An open source geospatial analysis tool
+- [pydeck](https://pydeck.gl/) - High-scale spatial rendering in Python, powered by deck.gl

data/ext/h3/src/docs/community/bindings.md

@@ -2,6 +2,10 @@
 
 As a C library, bindings can be made to call H3 functions from different programming languages. This page lists different bindings currently available. Contributions to this list are welcome, please feel free to open a [pull request](https://github.com/uber/h3/tree/master/docs/community/bindings.md).
 
+## BigQuery
+
+- [cartodb/bigquery-jslibs](https://github.com/CartoDB/bigquery-jslibs)
+
 ## C#
 
 - [entrepreneur-interet-general/h3.standard](https://github.com/entrepreneur-interet-general/H3.Standard)
@@ -30,6 +34,7 @@ As a C library, bindings can be made to call H3 functions from different program
 
 - [uber/h3-js](https://github.com/uber/h3-js)
 - [dfellis/h3-node](https://github.com/dfellis/h3-node)
+- [realPrimoh/h3-reactnative](https://github.com/realPrimoh/h3-reactnative)
 
 ## Julia
 
@@ -60,3 +65,8 @@ As a C library, bindings can be made to call H3 functions from different program
 ## Ruby
 
 - [StuartApp/h3_ruby](https://github.com/StuartApp/h3_ruby)
+
+## Rust
+
+- [rustyconover/libh3-sys](https://github.com/rustyconover/libh3-sys)
+- [rustyconover/libh3](https://github.com/rustyconover/libh3)

data/ext/h3/src/docs/community/tutorials.md

@@ -1,7 +1,11 @@
-# Tutorials
+# Learning Resources
 
 This page lists further learning materials and code walkthroughs for the H3 library and bindings. Contributions to this list are welcome, please feel free to open a [pull request](https://github.com/uber/h3/tree/master/docs/community/tutorials.md).
 
+## Community
+
+- [H3 Slack workspace](https://join.slack.com/t/h3-core/shared_invite/zt-g6u5r1hf-W_~uVJmfeiWtMQuBGc1NNg)
+
 ## Videos
 
 - [Introduction to H3](https://www.youtube.com/watch?v=wDuKeUkNLkQ) (June 2019)
@@ -24,5 +28,6 @@ This page lists further learning materials and code walkthroughs for the H3 libr
 
 ## Python
 
-- [Usage (IPython Notebook)](https://github.com/uber/h3-py/blob/master/docs/Usage.ipynb)
-- [Unified Data Layers (IPython Notebook)](https://github.com/uber/h3-py/blob/master/docs/UnifiedDataLayers.ipynb)
+- [Usage (IPython Notebook)](https://github.com/uber/h3-py-notebooks/blob/master/notebooks/usage.ipynb)
+- [Unified Data Layers (IPython Notebook)](https://github.com/uber/h3-py-notebooks/blob/master/notebooks/unified_data_layers.ipynb)
+- [H3 API examples on Urban Analytics(IPython Notebook)](https://github.com/uber/h3-py-notebooks/blob/master/notebooks/urban_analytics.ipynb)

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

@@ -1,5 +1,6 @@
-Coordinate Systems used by the H3 Core Library
----
+# Coordinate systems
+
+The **H3 Core Library** uses the following coordinate systems internally.
 
 IJK Coordinates
 ---
@@ -9,7 +10,7 @@ Discrete hexagon planar grid systems naturally have 3 coordinate axes spaced 120
 Using an *ijk* coordinate system to address hexagon grid cells provides multiple valid addresses for each cell. *Normalizing* an *ijk* address (function `_ijkNormalize`) creates a unique address consisting of the minimal positive *ijk* components; this always results in at most two non-zero components.
 
 <div align="center">
-  <img height="300" src="images/ijkp.png" />
+  <img height="300" src="/images/ijkp.png" />
 </div>
 
 FaceIJK Coordinates
@@ -20,7 +21,7 @@ The **H3 Core Library** centers an *ijk* coordinate system on each face of the i
 Each grid resolution is rotated ~19.1&deg; relative to the next coarser resolution. The rotation alternates between counterclockwise and clockwise at each successive resolution, so that each resolution will have one of two possible orientations: *Class II* or *Class III* (using a terminology coined by R. Buckminster Fuller). The base cells, which make up resolution 0, are *Class II*.
 
 <div align="center">
-  <img height="300" src="images/classII.III.png" />
+  <img height="300" src="/images/classII.III.png" />
 </div>
 
 Hex2d Coordinates

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

@@ -1,11 +1,10 @@
-Unix-style Filters for Address Conversion
----
+# Unix-style Filters for H3
 
 The directory `src/apps/filters` contains unix-style stdin/stdout filters that perform conversions between integer **H3** indexes and other useful types. It currently contains the filters listed in the table below. See the header comments in each application source code file for more information.
 
 Filters are experimental and are not part of the semantic version of the H3 library.
 
-All latitude/longitude coordinates are in decimal degrees. See the <a href="#/documentation/core-library/h3-index-representations"> **H3** Index Representations</a> page for information on the integer `H3Index`.
+All latitude/longitude coordinates are in decimal degrees. See the [**H3** Index Representations](/docs/core-library/h3indexing) page for information on the integer `H3Index`.
 
 
 | filter           | input     | outputs
@@ -22,26 +21,26 @@ Unix Command Line Examples
 
 * find the index for coordinates at resolution 5
 
-     `echo 40.689167 -74.044444 | geoToH3 5`
+     `geoToH3 --resolution 5 --latitude 40.689167 --longitude -74.044444`
 
 * output the cell center point for `H3Index` 845ad1bffffffff
 
-     `echo 845ad1bffffffff | h3ToGeo`
+     `h3ToGeo --index 845ad1bffffffff`
 
 * output the cell boundary for `H3Index` 845ad1bffffffff
 
-     `echo 845ad1bffffffff | h3ToGeoBoundary`
+     `h3ToGeoBoundary --index 845ad1bffffffff`
 
 * find the components for the `H3Index` 845ad1bffffffff
 
-     `echo 845ad1bffffffff | h3ToComponents`
+     `h3ToComponents --index 845ad1bffffffff`
 
 * output all indexes within distance 1 of the `H3Index` 845ad1bffffffff
 
-     `echo 845ad1bffffffff | kRing 1`
+     `kRing -k 1 --origin 845ad1bffffffff`
 
 * output all hexagon indexes within distance 2 of the `H3Index` 845ad1bffffffff
 
-     `echo 845ad1bffffffff | hexRange 2`
+     `hexRange -k 2 --origin 845ad1bffffffff`
 
 Note that the filters `h3ToGeo` and `h3ToGeoBoundary` take optional arguments that allow them to generate `kml` output. See the header comments in the corresponding source code files for details.

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

@@ -1,9 +1,8 @@
-Conversion from latitude/longitude to containing H3 cell index
----
+# Conversion from latitude/longitude to containing H3 cell index
 
 This operation is performed by function `geoToH3`. See the comments in the function 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.
 
 1. The input latitude/longitude coordinate is first converted into the containing icosahedron face and a *Hex2d* coordinate on that face using function `_geoToHex2d`, which determines the correct face and then performs a face-centered gnomonic projection into face-centered polar coordinates. These polar coordinates are then scaled appropriately to a *Hex2d* coordinate on the input grid resolution *r*.
 2. The *Hex2d* coordinate is converted into resolution *r* normalized *ijk* coordinates using function `_hex2dToCoordIJK`.

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

@@ -1,15 +1,14 @@
-Generate the cell boundary in latitude/longitude coordinates of an H3Index cell
----
+# Generate the cell boundary in latitude/longitude coordinates of an H3Index cell
 
 This operation is performed by function `h3ToGeoBoundary`. 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.
 
 * We note that the cell vertices are the center points of cells in an aperture 3 grid one resolution finer than the cell resolution, which we term a *substrate* grid. We precalculate the substrate *ijk* coordinates of a cell with *ijk* coordinates (0,0,0), adding additional aperture 3 and aperture 7 (if required, by Class III cell grid) substrate grid resolutions as required to transform the vertex coordinates into a Class II substrate grid.
 
 <div align="center">
-  <img height="300" src="images/substrate3.png" />
+  <img height="300" src="/images/substrate3.png" />
 </div>
 
-* The function `_faceIjkToGeoBoundary` calculates the *ijk* coordinates of the cell center point in the appropriate substrate grid (determined in the last step), and each of the substrate vertices is translated using the cell center point *ijk*. Each vertex *ijk* is then transformed onto the appropriate face and *Hex2d* coordinate system using the approach taken in <a href="#/documentation/core-library/walkthrough-of-h3togeo">finding a cell center point</a>. If adjacent vertices lie on different icosahedron faces a point is introduced at the intersection of the cell edge and icosahedron face edge.
+* The function `_faceIjkToGeoBoundary` calculates the *ijk* coordinates of the cell center point in the appropriate substrate grid (determined in the last step), and each of the substrate vertices is translated using the cell center point *ijk*. Each vertex *ijk* is then transformed onto the appropriate face and *Hex2d* coordinate system using the approach taken in [finding a cell center point](/docs/core-library/h3ToGeoDesc). If adjacent vertices lie on different icosahedron faces a point is introduced at the intersection of the cell edge and icosahedron face edge.
 * The *Hex2d* coordinates are then converted to latitude/longitude using `_hex2dToGeo`.