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 since v3.6.1: We upload pre-built Python Wheels to PyPI for Linux/Mac/Windows, which should avoid many previous installation issues.
Installation
From PyPI:
pip install h3
From conda:
conda config --add channels conda-forge
conda install h3-py
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.4-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3155cd5bce14164a6afb0e4b2ac4485620196cd2ebdc54d5e21c0771aa7d3774 |
|
MD5 | 7885b04b6c1c47b487fb5fad6548a25c |
|
BLAKE2b-256 | a1c19325831ebf626a350e604226b0b80cfdb2a47454bdfd8089884c0e818e50 |
Hashes for h3-3.6.4-cp38-cp38-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5d6a9dbcbc9e3acb19e5238e52ebb5ead7dd9a5d3c1af427da391bbaf8408306 |
|
MD5 | 05473332063510497f8cf48c512b21e3 |
|
BLAKE2b-256 | 53f67fc08a798f26e7910f770a56486139c20ae14ab73266c74baa0b33b52817 |
Hashes for h3-3.6.4-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 89c68d6e94c881fb50f6d374cc00ccf146995acfb6a2cce41c4bb48c93b95445 |
|
MD5 | d41f6a6735284faea42fb0afd7f66a29 |
|
BLAKE2b-256 | 162f76d6481b39cf318064a767fc1b4bc62565cc33d789d7a7732fa37270f88c |
Hashes for h3-3.6.4-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b4aaa2ee1dc5b0f748cb9193c4b67e618fb3aef80353ae15a47e6ddfa58adea4 |
|
MD5 | 7a71c0ad6ac66f049e531cdf0f48dcfd |
|
BLAKE2b-256 | 4b730bf01fc69f91f1bac886ef2cfbb26e1ffcde2986129333151b7c4a134551 |
Hashes for h3-3.6.4-cp37-cp37m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8e73224f0370baf38bd0c9c0f8201d94508e4750c25252b12e19c9fd36c7cfa2 |
|
MD5 | a4f34c7fb049e1a74cd54d8fcb2bd539 |
|
BLAKE2b-256 | 602c0b24256ed7032703fb3c6d406c8ca59da00a3f48d95cd7b771f52114fd43 |
Hashes for h3-3.6.4-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c08fa2e46b2ef5296fbf631315af8a03df19b939cb60066f6b81e55ed2a4c1cb |
|
MD5 | 86920fc0f2746348f198e4f2b716ec88 |
|
BLAKE2b-256 | 83664a062ac2670243498ac692365a87160985bca9c6406c842cd619a8a2f855 |
Hashes for h3-3.6.4-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 17622f7d35f9efd32a9447ee18c6ffef899282aa55c880713ef309a207e3d1e8 |
|
MD5 | 26040139f5d07e574eecdbf7f89efad7 |
|
BLAKE2b-256 | c03c2834939c3a9b54bd1d3ea9f473e57c96f5d11e13967577ea26006475ae06 |
Hashes for h3-3.6.4-cp36-cp36m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9711d05e8676540fba6842482bd7d694f0e181764738434641a971e727f67063 |
|
MD5 | aa115b70abd5c805733cefdabae2d859 |
|
BLAKE2b-256 | bf77df4b7b3f989cbd3aec5894f6058a31981f05f151f9bbfc3f5827178eeedc |
Hashes for h3-3.6.4-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4b143ed8b21812d34af7683ce191a51c36d502fb5ce125a14f1f76e3bfcf0e2d |
|
MD5 | 4efa52faa108fc7c9607e463d58a0472 |
|
BLAKE2b-256 | edc57e33ab836d21ff7e15cd55e8f3de37d8501895e3f9358366c86d0f7ed7ce |
Hashes for h3-3.6.4-cp35-cp35m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f37ec4d20c9f353de01d2e330ea6bebc2213b9c4a6111ebe2f257626e75f915f |
|
MD5 | 879d58ca9a305a99daec26ef98349446 |
|
BLAKE2b-256 | 614fd63c74a1f87160c32f6f360ffa2ce4de4b2044951b9c4322726806e69eba |
Hashes for h3-3.6.4-cp35-cp35m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1a4e7b6cdf5142ac12f8f3d2089204eabfcafb0b323e380de5449c0c3561f214 |
|
MD5 | ea10cacced5ec406ba1e9f071da99f53 |
|
BLAKE2b-256 | e884660ee25c381afbff4cd780ff11c7b7f511c6b1761bd53b06464858306750 |
Hashes for h3-3.6.4-cp35-cp35m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a40c01f7f6e6b5f7da0404944d0e04dd64a74684d5b3c8ad6676e5435f909067 |
|
MD5 | 49220800a51ec5a28445542a38c715b7 |
|
BLAKE2b-256 | e8f55ab1d3fc87e6cf4f8f7e04d55ce6ef6e98d347a22878ddbb378377aaf104 |
Hashes for h3-3.6.4-cp27-cp27mu-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1be4b26e6d23a47211a1e98849e7242c91b9ad11215ec6d2b737539d8d8bc567 |
|
MD5 | 682460668afd62a515814eb0d77f2bdd |
|
BLAKE2b-256 | d0ccd8d95f0bd6f0004cb4c4ee6d0c2db95ebd38cc296f04f2aa20a47ad7c909 |
Hashes for h3-3.6.4-cp27-cp27m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0ba060c99a3d5c5e7bef146075f66776c4a65e946db0fe7b4f387c1e803f18ea |
|
MD5 | a79921d762803133bcc0d956e6f04e5e |
|
BLAKE2b-256 | 3f831176325b1d99195c0722f27b3f823baf08f75f0dbdef2e324428e11058f7 |
Hashes for h3-3.6.4-cp27-cp27m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 67f5cf3697276038bfde0bb6b4ba08a10ba9525cfa82213551e48c50a6306f5a |
|
MD5 | 5e4e42570465590f45c8d266e01c3bf7 |
|
BLAKE2b-256 | 26f7eb830e2b504f4108998eb9e686cd9115f504dd84045687f33ff3b785d36e |