Hierarchical hexagonal geospatial indexing system
Project description
h3-py
Python bindings for the H3 Core Library.
For API reference, please see the H3 Documentation.
New in v3.6.1: We upload pre-built Python Wheels to PyPI for Linux/Mac/Windows, which should avoid many previous installation issues.
Install from PyPI
pip install h3
Usage
>>> import h3
>>> lat, lng = 0, 0
>>> resolution = 0
>>> h3.geo_to_h3(lat, lng, resolution)
'8075fffffffffff'
Example gallery
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 str
s, 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 int
s, 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 uint64
s, 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 list
s and set
s.
>>> 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 uint64
s, 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'}
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for h3-3.6.1-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fbfd7f103b74b2d57e5e2f21e68cc32e2d7df2019bb5d2d0d2c56888b691ffaf |
|
MD5 | 57f04083cc13b7dbc3a843ec544875ef |
|
BLAKE2b-256 | d2d7fb62b0ec22c827919ecc47be496aaea97eba9d99007c5d0f7ac244345d2e |
Hashes for h3-3.6.1-cp38-cp38-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 833f0f4cd081bafefd4da2b15b6c2e08d870b2ced7fd364ac76f254f8dd79ed8 |
|
MD5 | 39ec10359d716f8e8e347d06edca5e09 |
|
BLAKE2b-256 | 119d137f41c5870104ee3225f24ccd1a5bcbef8c70a7ab45107ad3c5e0a00209 |
Hashes for h3-3.6.1-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 777f2f3dcee2780f44b8f7627781d2b82489ec4928634f5b9df5798cfef7115a |
|
MD5 | e8463a33d7924f4c2d03124bf904c154 |
|
BLAKE2b-256 | f501741c9d5844e824ff8ccf7ed57dfe5a33ba4ba8c71dd59ad5949b91621830 |
Hashes for h3-3.6.1-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9568a572f6e966bb2bafaac94ea5b9cf32035c190a03ad5a34ddf04fb69e42fe |
|
MD5 | a1aaec4f8c436070a0ffaaaa0008aa41 |
|
BLAKE2b-256 | b5e2611ccbeb7ce9090519e704b7a4f827ce766294f14368cc01650e73c64edb |
Hashes for h3-3.6.1-cp37-cp37m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 691a261471e9f7993ccfcd189035b215de87741b8cc87226f1bf39089344caae |
|
MD5 | 79a864fc6d671ae1251ca5ce6446fdd9 |
|
BLAKE2b-256 | 566fad843fb16645916e398ce00d52e44ebf3c318286054fb0094c818ebb4bd6 |
Hashes for h3-3.6.1-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a7c4aaae1f9b6a3199b40e8483cfc7855e741b5e3739264a6d61254e47475357 |
|
MD5 | 19ba751a7ebf8ef537b57afda899395a |
|
BLAKE2b-256 | d35a7ac9807a489b9ddd605e4af608c2db88dac1b580313d4832027e77c144b9 |
Hashes for h3-3.6.1-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a651c06486b04f2c421a7b9805a6768261e79d8a947d5ee9d8ae76188f242f9c |
|
MD5 | 5465bcb42855af3e97c6882a20af84dd |
|
BLAKE2b-256 | 36304a136fbcd7ead63b9e8aab69a6e4381d519bca854b5af82841e9f1a566de |
Hashes for h3-3.6.1-cp36-cp36m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d867e14db912a83cc32b17c96d89af720f187d1892ce00ab2221b05e142a3e23 |
|
MD5 | 8debb0bedf1b7459c23ef2e9a9b1fad0 |
|
BLAKE2b-256 | fc38f32e8e9a9d73ff906a6dbbfffeea0be359f27da51c3f996e13e0523f2bab |
Hashes for h3-3.6.1-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5662a5477ef477848ec87c354cabc21a6ffb6bb822fa45a9e70c282c65816a95 |
|
MD5 | d67c36f21c827e23b4f7eb89ab2f7a4e |
|
BLAKE2b-256 | e6eb938b7636e5b2f3aa204ecd2e34601a146216b079a1b575ac367b3a0296f9 |
Hashes for h3-3.6.1-cp35-cp35m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3a86c456735506c3f2181d44d46f7f626bffb533a44b06f12029227878e521a2 |
|
MD5 | 04ee07dde8539de031e2f4a80077a134 |
|
BLAKE2b-256 | 7cb6f6ae904a77639721f35a2efd5e1ddd7c5d024bacf926214dee81c65e541a |
Hashes for h3-3.6.1-cp35-cp35m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7150d4627e3806b5fe2d3a480937da4c9a83a5e9e3378f9fbef8322883414361 |
|
MD5 | 48d84a017601f4d214013e01b49d9bbf |
|
BLAKE2b-256 | a08410454bc261b56764898e822879ef3a24d4badfdbc86716df6af4299555a8 |
Hashes for h3-3.6.1-cp35-cp35m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 112108b74245e74d73bd8a0e2768f0bac8904516aec8f7a2dfd6ad54498b4456 |
|
MD5 | 8ac216d4432f133b4cd5b19445b23a16 |
|
BLAKE2b-256 | 5f43ccfb3c2e87c2d55c65c5edd828741106c355cc8187d98dd55a2d5739b107 |
Hashes for h3-3.6.1-cp27-cp27m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e0e2c7b7f9aa193b03fc264c754df75e6beba090fe6e68f85bb6915c448443a1 |
|
MD5 | dcf85043248959ae8af495ba6274733c |
|
BLAKE2b-256 | bdfac7f2d1c9998d5484c2fd6d9c4af8c3a9d75d9fb3ef0b6da4a3112f93f6f6 |