h3 3.6.0 → 3.7.2

data/ext/h3/src/dev-docs/RFCs/v4.0.0/overrideable-allocators-rfc.md

@@ -0,0 +1,141 @@
+# RFC: Overrideable allocation functions for H3
+
+* **Authors**: Isaac Brodsky (@isaacbrodsky)
+* **Date**: February 7, 2020
+* **Status**: Draft
+
+## Overview
+
+This is a proposal for adding a mechanism for users of the H3 library to provide heap allocator instead of the default
+malloc implementation.
+
+## Motivation
+
+This will address the following use cases:
+
+* H3 is used inside of another application which has its own heap management scheme. For example, using the allocation
+  functions provided by Postgres or the Java Virtual Machine.
+* Testing of failure cases of H3, by simulating allocation failures.
+
+Most H3 functions accept memory from the caller in order to avoid this problem. This will still be the preferred way
+to handle memory management in H3. Stack allocation is avoided because H3 cannot know whether there is sufficient stack
+memory available. (Note that `_kRingInternal`/`kRingDistances` implicitly uses stack allocation because it implements DFS
+recursively.)
+
+A few functions in H3 do heap allocate memory because it is not feasible to do otherwise, or as a convenience. The
+functions that heap allocate are:
+
+| Function | Reason
+| --- | ---
+| `kRing`| Convenience wrapper around `kRingDistances`
+| `polyfill` | Convenience (could be passed in, requires internal knowledge)
+| `compact` | Convenience (could be passed in, requires internal knowledge)
+| `h3SetToLinkedGeo` | Requires knowledge of how to initialize the internal struct
+| `destroyLinkedPolygon` | Required for `h3SetToLinkedGeo`
+
+## Prior Art
+
+Reading materials to reference:
+
+* [C++ `vector`](http://www.cplusplus.com/reference/vector/vector/) (via templates)
+* [SDL](https://discourse.libsdl.org/t/sdl-2-0-7-prerelease/23232) (via `SDL_SetMemoryFunctions`)
+* [PostgreSQL](https://www.postgresql.org/docs/10/xfunc-c.html) (via `palloc`)
+* [SQLite](https://sqlite.org/malloc.html)
+
+## Approaches
+
+All approaches assume the user has defined the following functions:
+
+```
+void* my_malloc(size_t size);
+void* my_calloc(size_t count, size_t size);
+void my_free(void* pointer);
+
+// TODO: Do we want my_realloc?
+```
+
+### Global statics
+
+In this approach, H3 stores the allocation functions in a set of static variables.
+
+```
+h3SetAllocator(&my_alloc, &my_calloc, &my_free);
+
+// call into H3 as before
+polyfill(geoPolygon, res, out);
+```
+
+Pro:
+* Allows the user to replace allocators at run time.
+
+Con:
+* Not thread safe, or an additional, complicated dependency is needed to ensure thread safety.
+* Global state.
+
+### Templates
+
+This approach is similar to how C++ handles allocator replacement in its standard library, by accepting the allocator
+as a template argument. However, H3 is written in C and must implement templates using macros.
+
+```
+POLYFILL_WITH_ALLLOCATORS(my_polyfill, my_malloc, my_calloc, my_free);
+
+// Call the function created by the template
+my_polyfill(geoPolygon, res, out);
+```
+
+Pro:
+* Allows the user to have multiple allocator replacements in use at once.
+
+Con:
+* Exposes a complicated build process to the user in the form of macros.
+
+### Allocator argument approach
+
+In this approach, every function call includes allocators.
+
+```
+H3MemoryManager allocFunctions = {
+  .malloc = &my_malloc,
+  .calloc = &my_calloc,
+  .free = &my_free
+};
+
+polyfill(geoPolygon, res, out, &allocFunctions);
+```
+
+Pro:
+* Allowing replacement on a per-call basis allows for maximum control by the user.
+
+Con:
+* The user must always specify allocators, which is unlikely to be needed by most users.
+* Alternately, additional overloads of all H3 functions that heap-allocate are needed.
+
+### `#define` approach
+
+In this approach, the allocators are specified at build time.
+
+```
+# In build process:
+cmake -DH3_ALLOC_PREFIX=my_ ...
+
+// in source file, functions are used as before.
+```
+
+Alternately, instead of setting a prefix, the build could accept individual options
+for functions, such as `-DH3_MALLOC=my_malloc -DH3_CALLOC=my_calloc`. (Although this
+could allow a user to accidentally override `malloc` but not `free`, which is generally
+very bad.)
+
+Pro:
+* Minimal overhead for users and developers when allocator replacement is not needed.
+
+Con:
+* Complex allocator replacement (i.e. different allocators for different calls) is possible but requires implementation
+  by the user.
+
+## Proposal
+
+`#define` based allocator replacement seems like the clearest and lowest overhead to implement, while still supporting
+the full range of use cases. A user could optionally implement a more complicated replacement inside their custom
+allocator functions.

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/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
 
 ```
@@ -91,3 +140,30 @@ 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)