Repository files navigation

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

Documentation is available athttps://h3geo.org/. Developer documentation in Markdown format is available under thedev-docs directory.

• Postbug reports or feature requests to theGitHub Issues page
• Askquestions by posting to theH3 tag on StackOverflow
• There is also anH3 Slack workspace

We recommend using prebuilt bindings if they are available for your programming language. Bindings forJava,JavaScript,Python, andothers are available.

On macOS, you can install H3 usingbrew:

brew install h3

Otherwise, to build H3 from source, please see the following instructions.

Still here? To build the H3 C library, you'll need a C compiler (tested withgcc andclang),CMake, andMake. If you intend to contribute to H3, you must haveclang-format installed and we recommend installingccmake andLCOV to configure thecmake arguments to build and run the tests and generate the code coverage report. We also recommend usinggcc for the code coverage as some versions ofclang generate annotations that aren't compatible withlcov.Doxygen is needed to build the API documentation.

• Alpine

# Installing the bare build requirementsapk add cmake make gcc libtool musl-dev

• Debian/Ubuntu

# Installing the bare build requirementssudo apt install cmake make gcc libtool# Installing useful tools for developmentsudo apt install clang-format cmake-curses-gui lcov doxygen

• macOS (usingbrew)

First make sure youhave the developer tools installed and then

# Installing the bare build requirementsbrew install cmake# Installing useful tools for developmentbrew install clang-format lcov doxygen

• Windows (Visual Studio)

You will need to install CMake and Visual Studio, including the Visual C++ compiler. For building on Windows, please follow theWindows build instructions.

• FreeBSD

# Installing the build requirementssudo pkg install bash cmake gmake doxygen lcov

When checking out the H3 Git repository, by default you will check out the latestdevelopment version of H3. When using H3 in an application, you will want to checkout the most recently released version:

git checkout v$(<VERSION)

From the repository root, you can compile H3 with:

mkdir buildcd buildcmake -DCMAKE_BUILD_TYPE=Release ..make

All subsequentmake commands should be run from within thebuild directory.

Note: There are several ways to build H3 with CMake; the method above is just one example that restricts all build artifacts to thebuild 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

After making the project, you can test withmake test.You can run a faster test suite that excludes the most expensive tests withmake test-fast.

You can generate a code coverage report iflcov is installed, and if the project was built with theCMAKE_BUILD_TYPE=Debug andENABLE_COVERAGE=ON options.For example, from a clean repository, you could run:

mkdir buildcd buildcmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_COVERAGE=ON ..makemake coverage

You can then view a detailed HTML coverage report by openingcoverage/index.html in your browser.

You can run timing benchmarks by building with theCMAKE_BUILD_TYPE=Release, and runningmake benchmarks:

mkdir buildcd buildcmake -DCMAKE_BUILD_TYPE=Release ..makemake benchmarks

You can build developer documentation withmake docs if Doxygen was installed when CMake was run. Index of the documentation will bedev-docs/_build/html/index.html.

After making the project, you can build KML files to visualize the hexagon grid withmake kml. The files will be placed inKML.

To build the documentation website, see thewebsite/ directory.

To get the H3 index for some location:

./bin/latLngToCell --resolution 10 --latitude 40.689167 --longitude -74.044444

10 is the H3 resolution, between 0 (coarsest) and 15 (finest). The coordinates entered are the latitude and longitude, in degrees, you want the index for (these coordinates are the Statue of Liberty). You should get an H3 index as output, like8a2a1072b59ffff.

You can then take this index and get some information about it, for example:

./bin/cellToBoundary --index 8a2a1072b59ffff

This will produce the vertices of the hexagon at this location:

8a2a1072b59ffff{   40.690058601 -74.044151762   40.689907695 -74.045061792   40.689270936 -74.045341418   40.688785091 -74.044711031   40.688935993 -74.043801021   40.689572744 -74.043521377}

You can get the center coordinate of the hexagon like so:

./bin/cellToLatLng --index 8a2a1072b59ffff

This will produce some coordinate:

40.6894218437 -74.0444313999

The above features of H3 can also be used from C. For example, you can compile and runexamples/index.c like so:

cc -lh3 examples/index.c -o example./example

You should get output like:

The index is: 8a2a1072b59ffffBoundary vertex #0: 40.690059, -74.044152Boundary vertex #1: 40.689908, -74.045062Boundary vertex #2: 40.689271, -74.045341Boundary vertex #3: 40.688785, -74.044711Boundary vertex #4: 40.688936, -74.043801Boundary vertex #5: 40.689573, -74.043521Center coordinates: 40.689422, -74.044431

Pull requests and Github issues are welcome. Please see ourcontributing guide for more information.

Before we can merge your changes, you must agree to theUber Contributor License Agreement.

H3 is licensed under theApache 2.0 License.

DGGRIDCopyright (c) 2015 Southern Oregon University