0
Fork 0
mirror of https://github.com/uber/h3-py.git synced 2026-11-16 07:44:46 +00:00
Python bindings for H3, a hierarchical hexagonal geospatial indexing system https://uber.github.io/h3-py
  • Python 70.2%
  • Cython 27.3%
  • CMake 1.8%
  • Just 0.7%
Find a file
AJ Friend a7cac3e6df
bump version for v3.7.2 release (#178)
* bump version for v3.7.2 release

* capitalize

* catch and assert h3.unstable warning
History 2021-03-01 20:53:51 -08:00
.github/workflows h3-py release v3.7.1 (#175) 2020-12-18 14:09:02 -08:00
src bump version for v3.7.2 release (#178) 2021-03-01 20:53:51 -08:00
tests bump version for v3.7.2 release (#178) 2021-03-01 20:53:51 -08:00
.coveragerc first draft of v4 names (#146) 2020-07-15 15:45:32 -07:00
.flake8 The big Cython move (#99) 2020-05-10 11:47:45 -07:00
.gitignore The big Cython move (#99) 2020-05-10 11:47:45 -07:00
.gitmodules The big Cython move (#99) 2020-05-10 11:47:45 -07:00
CHANGELOG.md bump version for v3.7.2 release (#178) 2021-03-01 20:53:51 -08:00
CMakeLists.txt Wheels for Mac/Linux (#115) 2020-05-22 11:48:19 -07:00
dev_notes.md h3-py release v3.7.1 (#175) 2020-12-18 14:09:02 -08:00
LICENSE first commit 2018-07-30 12:24:17 -07:00
makefile bump version for v3.7.2 release (#178) 2021-03-01 20:53:51 -08:00
pyproject.toml Windows wheels (#116) 2020-05-24 11:04:55 -07:00
readme.md h3-py release v3.7.1 (#175) 2020-12-18 14:09:02 -08:00
requirements.in v3.6.4 release and add requirements.in (#157) 2020-07-20 13:55:25 -07:00
setup.py Use setup.py for optional requirements instead of requirements-dev.txt (#117) 2020-05-25 10:51:16 -07:00

H3 Logo

h3-py

PyPI version PyPI downloads conda version version

Tests codecov

Python bindings for the H3 Core Library.

For API reference, see the H3 Documentation.

Installation

From PyPI:

pip install h3

From conda:

conda config --add channels conda-forge
conda install h3-py

New since v3.6.1: We upload pre-built Python Wheels to PyPI for Linux/Mac/Windows, which should avoid many previous installation issues.

Usage

>>> import h3
>>> lat, lng = 0, 0
>>> resolution = 0
>>> h3.geo_to_h3(lat, lng, resolution)
'8075fffffffffff'

Browse a collection of example notebooks, and if you have examples or visualizations of your own, please feel free to contribute!

We also have a simple walkthrough of the API. For more information, please see the H3 Documentation.

APIs

We provide multiple APIs in h3-py. All APIs have the same set of functions, but differ in their input/output formats.

h3.api.basic_str

H3 indexes are represented as Python strs, using list and set for collections.

This is the default API provided when you import h3. That is, import h3.api.basic_str as h3 and import h3 are basically equivalent.

>>> import h3
>>> h = h3.geo_to_h3(0, 0, 0)
>>> h
'8075fffffffffff'

>>> h3.hex_ring(h, 1)
{'8055fffffffffff',
 '8059fffffffffff',
 '807dfffffffffff',
 '8083fffffffffff',
 '8099fffffffffff'}

h3.api.basic_int

H3 indexes are represented as Python ints, using list and set for collections.

>>> import h3.api.basic_int as h3
>>> h = h3.geo_to_h3(0, 0, 0)
>>> h
578536630256664575

>>> h3.hex_ring(h, 1)
{577973680303243263,
 578044049047420927,
 578677367745019903,
 578782920861286399,
 579169948954263551}

h3.api.numpy_int

H3 indexes are represented as uint64s, using numpy.ndarray for collections.

The intention is for this API to be faster and more memory-efficient by not requiring int to str conversion and by using no-copy numpy arrays instead of Python lists and sets.

>>> import h3.api.numpy_int as h3
>>> h = h3.geo_to_h3(0, 0, 0)
>>> h
578536630256664575

>>> h3.hex_ring(h, 1)
array([578782920861286399, 578044049047420927, 577973680303243263,
       578677367745019903, 579169948954263551], dtype=uint64)

Note that h3 has no runtime dependencies on other libraries, so a standard pip install will install no additional libraries. However, h3.api.numpy_int requires numpy. To have numpy installed (if it isn't already) along with h3, run pip install h3[numpy].

h3.api.memview_int

H3 indexes are represented as uint64s, using Python memoryview objects for collections.

This API has the same benefits as numpy_int, except it uses (the less well-known but dependency-free) memoryview.

>>> import h3.api.memview_int as h3
>>> h = h3.geo_to_h3(0, 0, 0)
>>> h
578536630256664575

>>> mv = h3.hex_ring(h, 1)
>>> mv
<MemoryView of 'array' at 0x11188c710>

>>> mv[0]
578782920861286399

>>> list(mv)
[578782920861286399,
 578044049047420927,
 577973680303243263,
 578677367745019903,
 579169948954263551]

When using this API with numpy, note that numpy.array creates a copy of the data, while numpy.asarray does not create a copy and the result points to the same memory location as the memoryview object.

Continuing from the example above,

>>> mv = h3.hex_ring(h, 1)
>>> a = np.array(mv)
>>> mv[0] = 0
>>> a
array([578782920861286399, 578044049047420927, 577973680303243263,
       578677367745019903, 579169948954263551], dtype=uint64)

>>> mv = h3.hex_ring(h, 1)
>>> a = np.asarray(mv)
>>> mv[0] = 0
>>> a
array([                 0, 578044049047420927, 577973680303243263,
       578677367745019903, 579169948954263551], dtype=uint64)

Versioning

h3-py wraps the H3 Core Library, which is written in C. Both projects employ semantic versioning, with versions taking the form X.Y.Z.

h3-py will match the C library in major and minor numbers (X.Y), but may be different on the patch (Z) number.

Use h3.versions() to see the version numbers for both h3-py and the C library. For example,

>>> import h3
>>> h3.versions()
{'c': '3.6.3', 'python': '3.6.1'}