H3.net: A port of Uber's Hexagonal Hierarchical Geospatial Indexing System to C#

This is a port of Uber's H3 library to C#, with additional functionality to support NetTopologySuite geometries. It is based on release 3.7.1 of the library.

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's hierarchical subdivisions.

Upstream documentation is available at https://h3geo.org/. Documentation for this port of the library is unfortunately currently limited to documentation in the source and examples via unit tests.

This is a work in progress and likely contains some silly bugs and poorly performing or just plain confusing implementation choices. I have tried to make the library work and feel more "C# like" using operators, extension methods, enumerables vs. arrays and so on, but some things may be implemented more or less as straight ports of the upstream library. Other than the obvious difference in some method names and whatnot, the biggest difference vs. the upstream library is the reliance on NTS for geometries (e.g. cell boundary polygons) and algorithms such as polyfill instead of in-library classes such as the GeoBoundary and vertex graph stuff.

While the majority of the core H3 API should be here in one form or another, there's still gaps particularly in terms of documentation and tests to validate behaviour vs. upstream. My focus so far has been on getting the algorithm side of things (such as k-rings, polyfill and so on) working and tested as I needed those features for the project(s) I am working on, however given that the majority of those methods depend on the basics of the library working, test coverage is "ok". I also make use of the PostgreSQL bindings in my work, so I tend to validate results with that as well.

PRs to improve code, tests and documentation are definitely welcome, although please keep in mind I am quite busy these days and may be a bit slow to respond. Sorry in advance!

Available on nuget.org as pocketken.H3.

PM> Install-Package pocketken.H3 -Version 3.7.1

There is an extremely basic set of benchmarks using BenchmarkDotNet that I have begun to use in order to track performance and perform optimizations as things progress. You can check the code out to run the benchmarks locally if you want, e.g.:

$ dotnet run --configuration Release --project .\test\H3.Benchmarks\H3.Benchmarks.csproj --filter *Uncompact* --join

All numbers here are from my primary Windows development VM:

BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042
AMD Ryzen 9 3900X, 1 CPU, 12 logical and 6 physical cores
.NET Core SDK=5.0.201
  [Host]        : .NET Core 5.0.4 (CoreCLR 5.0.421.11614, CoreFX 5.0.421.11614), X64 RyuJIT
  .NET Core 5.0 : .NET Core 5.0.4 (CoreCLR 5.0.421.11614, CoreFX 5.0.421.11614), X64 RyuJIT

Job=.NET Core 5.0  Runtime=.NET Core 5.0

While there are some comparisons here against H3Lib, I still need to work on getting some benchmarks for the other H3 package which wraps the native library; if anyone is interested in assisting PRs are welcome!

Using 89283080dcbffff (Uber's SF Test index @ resolution 9) to get all children at resolution 15.

Line from 8e283080dc80007 to 8e48e1d7038d527 (DistanceTo of 554,625 cells).

hex is a hexagon index (8f48e1d7038d520).

pent is a pentagon index (8e0800000000007) which forces the use of the iterative (recursive in the case of H3Lib) method of generating the ring due to the fast method's inability to handle pentagons.

• Compact: Result of compacting all base cells at resolution 5.
• Uncompact: Result of uncompacting all base cells to resolution of 5.