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.
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.3-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a338cd254bfb81bdd3e3d94afe9b622734354de13a7b23472ad6dee269cbdcb0 |
|
MD5 | 3d8a80674ffd4c3bec2e660016afd036 |
|
BLAKE2b-256 | f5efeae5adab3bfba20ac0d6705f88c103f3c08e22cfb469a6a556a0eb71a5db |
Hashes for h3-3.6.3-cp38-cp38-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a726728b2aff9cf2565cb17768b58c0a30850a77308befc178dc6098bb7f323f |
|
MD5 | 06a49895f12ca3c4ef7044323bf27b35 |
|
BLAKE2b-256 | aebe6d325d30b76cf6e75a82f665e62ba820e249cf62cf43cc657ec0b7ed10b4 |
Hashes for h3-3.6.3-cp38-cp38-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 36108e99d205c94a4fe62baf425a71f39fe15a305065631f14f2bb1139fbdd93 |
|
MD5 | deaab8874d5de7cd78ba2c3a93aaeb71 |
|
BLAKE2b-256 | 92e4fc93f94bf8f317ead318d1a7747c3c578960552c69d82fa5e048b45a67ef |
Hashes for h3-3.6.3-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5624e61fef2f51498d6b57b10a69534897db1c88eb9fb3d7206b11646cf490cf |
|
MD5 | 9b1b6b498f465ebcaa584fd85c17af3e |
|
BLAKE2b-256 | 8b2133d8b5b72e88c001348bb0bb4069247d040777d37d5279cde240d596e70d |
Hashes for h3-3.6.3-cp37-cp37m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 53d89b3844b3cd2e5bf8fa2a7e9d6841a587f05638b9f0643677c592bbaa0f8c |
|
MD5 | ba0a097146a2e87803facfb2f10b053e |
|
BLAKE2b-256 | 64ac2b3389c4bb5dcbb434899a2b4f054c707e3a8755eb3b103ab79050c29f74 |
Hashes for h3-3.6.3-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 84a269286f0a0022341d000bc824613e0e69d4711dfcf8740c7ac83cc9fe7610 |
|
MD5 | 15d8f5a6f8e449f41ade277a5a8e0491 |
|
BLAKE2b-256 | 8ffacd42b86442a38b94f034f2bec5513c82969f290a0311cd1d295d96e5836b |
Hashes for h3-3.6.3-cp36-cp36m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 728eeef24deec1f1494acdbd6396309991e088feca293b86b23505df80535c61 |
|
MD5 | 563b10afa18440b5e99678eaf7177d30 |
|
BLAKE2b-256 | d7266d6c9311b9f40ecd255f6e330358d6f40545e321cf44ae597555551f87b1 |
Hashes for h3-3.6.3-cp36-cp36m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3034474da0886aa6dc35d1c656875e14995fb7a0416f9c7262db871418365c4b |
|
MD5 | d1f54c0afae7cd19f13d2886b9e0899f |
|
BLAKE2b-256 | b4d792e3b3f76fb1b96db07620959380ef6d80854b23302dfbdfcd3af5372964 |
Hashes for h3-3.6.3-cp36-cp36m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8e89045839b6c584c2c84900daacf3afdbcd5535593631192b38c72ef2f87bea |
|
MD5 | 59e075b2df5ddc93d120254f6535a594 |
|
BLAKE2b-256 | 1716f97fc2484ebe3005e247be027623a31ee0df71e84cf83630023722ae04a8 |
Hashes for h3-3.6.3-cp35-cp35m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a7cca3095bcbf3e9397dbe2665f4c5346f927cd3f7f8c86518ae60b308cb449e |
|
MD5 | 4ad1ec2c8a83643e24118c128b9dcd89 |
|
BLAKE2b-256 | 0f7483f89de0683a5749a7a4b9c1f2d4fdd868b227d43229bd4573d42eca7769 |
Hashes for h3-3.6.3-cp35-cp35m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8c201ba82c4a4c57e38336b24451f66c122b9fb4953d30de83dbdc0e9350ef67 |
|
MD5 | 61da8556768b81813cd3f6279d11b041 |
|
BLAKE2b-256 | 86f1001b11387bd95b60e0965df20be7ee7ce27b208d3a9d8b01dfd3a29a4080 |
Hashes for h3-3.6.3-cp35-cp35m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 031c1900094eb49f1d81291d2f60fc77c24a0af81513d2afb2d661a0078882a6 |
|
MD5 | 1d9f88d0f551099ca3d2d6455392b08f |
|
BLAKE2b-256 | fb15e26f37b5544e16c966516f064b5f497da96c58b85eb16fb08dd97a734381 |
Hashes for h3-3.6.3-cp27-cp27mu-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 42ae1bc55eb7c6e99909aaf67c8ec788a042ed190e353cdb9bd0b83dbf676768 |
|
MD5 | 52d8fd0b0cb1d3e0a2676743a022aa6c |
|
BLAKE2b-256 | 5c659d82bee4ee6c493663fd1c1087073c3388483e6dfbfddb373de2188dcb7c |
Hashes for h3-3.6.3-cp27-cp27m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bd3fcdc610ffa3da3cc82bb2dd661ae6734da32ba94110cd9fac78175519d8be |
|
MD5 | 8cf61cb56d9672392250e5ffc2f81cc9 |
|
BLAKE2b-256 | 456bf9356bf2eb70df55797c95112bc54307d6f1caa248ed9dbf58dc1fafab03 |
Hashes for h3-3.6.3-cp27-cp27m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 264c4dae597993eeaf637efafac34c486dbeccb4dbaf3a55c8ae736a5e6ec5b1 |
|
MD5 | 570d575344cf6fdaa0367c0816dee893 |
|
BLAKE2b-256 | a07f818cac587c2969df5cd1e43b071f501f8165da702a58e496bc03db866987 |