added gitea activity for fun

This commit is contained in:
Joren de Graaf
2026-10-03 17:11:31 +02:00
parent 184e9d18f3
commit c0eda95f26
78 changed files with 11461 additions and 8 deletions
+1 -1
View File
@@ -1 +1 @@
/usr/bin/python
/usr/bin/python3.13
@@ -0,0 +1 @@
pip
@@ -0,0 +1,329 @@
Metadata-Version: 2.2
Name: h3
Version: 4.5.0
Summary: Uber's hierarchical hexagonal geospatial indexing system
Author-Email: Uber Technologies <ajfriend@gmail.com>
Maintainer-Email: AJ Friend <ajfriend@gmail.com>
License:
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: C
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Scientific/Engineering :: GIS
Project-URL: Homepage, https://github.com/uber/h3-py
Project-URL: Documentation, https://uber.github.io/h3-py/
Project-URL: Bug Tracker, https://github.com/uber/h3-py/issues
Project-URL: Discussions, https://github.com/uber/h3-py/discussions
Project-URL: Changelog, https://uber.github.io/h3-py/_changelog.html
Requires-Python: >=3.10
Provides-Extra: numpy
Requires-Dist: numpy; extra == "numpy"
Description-Content-Type: text/markdown
<img align="right" src="https://uber.github.io/img/h3Logo-color.svg" alt="H3 Logo" width="130">
# **h3-py**: Uber's H3 Hexagonal Hierarchical Geospatial Indexing System in Python
[![PyPI version](https://badge.fury.io/py/h3.svg)](https://badge.fury.io/py/h3)
[![PyPI downloads](https://img.shields.io/pypi/dm/h3.svg)](https://pypistats.org/packages/h3)
[![conda](https://img.shields.io/conda/vn/conda-forge/h3-py.svg)](https://anaconda.org/conda-forge/h3-py)
[![version](https://img.shields.io/badge/h3-v4.5.0-blue.svg)](https://github.com/uber/h3/releases/tag/v4.5.0)
[![version](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/uber/h3-py/blob/master/LICENSE)
[![Tests](https://github.com/uber/h3-py/workflows/tests/badge.svg)](https://github.com/uber/h3-py/actions)
[![Coverage 100%](https://img.shields.io/badge/coverage-100%25-green.svg)](https://github.com/uber/h3-py/blob/master/.github/workflows/lint_and_coverage.yml#L31) <!-- 100% coverage is enforced in CI -->
Python bindings for the [H3 core library](https://h3geo.org/).
- Documentation: [uber.github.io/h3-py](https://uber.github.io/h3-py)
- GitHub repo: [github.com/uber/h3-py](https://github.com/uber/h3-py)
## Installation
From [PyPI](https://pypi.org/project/h3/):
```console
pip install h3
```
From [conda](https://github.com/conda-forge/h3-py-feedstock):
```console
conda config --add channels conda-forge
conda install h3-py
```
## Usage
```python
>>> import h3
>>> lat, lng = 37.769377, -122.388903
>>> resolution = 9
>>> h3.latlng_to_cell(lat, lng, resolution)
'89283082e73ffff'
```
## APIs
[api_comparison]: https://uber.github.io/h3-py/api_comparison
[api_quick]: https://uber.github.io/h3-py/api_quick
We provide [multiple APIs][api_comparison] in `h3-py`.
- All APIs have the same set of functions;
see the [API reference][api_quick].
- The APIs differ only in their input/output formats;
see the [API comparison page][api_comparison].
## Example gallery
Browse [a collection of example notebooks](https://github.com/uber/h3-py-notebooks),
and if you have examples or visualizations of your own, please feel free
to contribute!
[walkthrough]: https://nbviewer.jupyter.org/github/uber/h3-py-notebooks/blob/master/notebooks/usage.ipynb
We also have an introductory [walkthrough of the API][walkthrough].
## Versioning
<!-- todo: this should just be the h3.versions() docstring, yeah? -->
`h3-py` wraps the [H3 core library](https://github.com/uber/h3),
which is written in C.
The C and Python projects each employ
[semantic versioning](https://semver.org/),
where versions take the form `X.Y.Z`.
The `h3-py` version string is guaranteed to match the C library string
in both *major* and *minor* numbers (`X.Y`), but may differ on the
*patch* (`Z`) number.
This convention provides users with information on breaking changes and
feature additions, while providing downstream bindings (like this one!)
with the versioning freedom to fix bugs.
Use `h3.versions()` to see the version numbers for both
`h3-py` and the C library. For example,
```python
>>> import h3
>>> h3.versions()
{'c': '4.1.0', 'python': '4.1.1'}
```
@@ -0,0 +1,66 @@
h3-4.5.0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
h3-4.5.0.dist-info/METADATA,sha256=CZ2OFvSyk7c9Rn73zKqGNviyWWt7FFSItvR1J3aRguY,17745
h3-4.5.0.dist-info/RECORD,,
h3-4.5.0.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
h3-4.5.0.dist-info/WHEEL,sha256=HeoYcPHRCguXCwN2mAQhgON4qq7h0X-NddTDMZDf1bo,195
h3-4.5.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
h3/CMakeLists.txt,sha256=8zQ0011t8bmsJw_GiKOFbkTZnquBh6ESCMZyLrm9u_U,22
h3/__init__.py,sha256=81gxWFGdRcNCG8DCGNbrtToHcN6fWDqruJcCTXhlpO4,676
h3/__pycache__/__init__.cpython-313.pyc,,
h3/__pycache__/_h3shape.cpython-313.pyc,,
h3/__pycache__/_version.cpython-313.pyc,,
h3/_cy/CMakeLists.txt,sha256=-h6Dk_V8VYydmDht9zCOv7wbSOl_G4MtlajIrj2D8hE,1528
h3/_cy/__init__.py,sha256=9NbeEjytaOV_ooX_p-gWmiAd2GZGCSKq9UbZ3HG_9eM,2702
h3/_cy/__pycache__/__init__.cpython-313.pyc,,
h3/_cy/cells.cpython-313-x86_64-linux-gnu.so,sha256=WzZ2xVJj5OJxqy1E75uBnusFJ1YG-Z7e8dbc3OIhzCU,387056
h3/_cy/cells.pxd,sha256=Lq7HHO-5_fwctjksq8vzQ6SVjnT1S8uz3gRa9h_3Vck,1492
h3/_cy/cells.pyx,sha256=CVtowYXpJnX42YmXffPHsZ-wN0CVAw0VL20N73Mcbdk,10263
h3/_cy/edges.cpython-313-x86_64-linux-gnu.so,sha256=Lxz_kYJgxy8TtVHuOEBBing4KDbe1S0qjDEWNb6noBM,296080
h3/_cy/edges.pxd,sha256=_zUOkV8aeWhk_xjicSWBDHNOp3vMEeg8o2Da06iYn38,561
h3/_cy/edges.pyx,sha256=1ECoK-OP3_BplwLZqwqNwItMLNIja6kVMzMeo7maHz8,2487
h3/_cy/error_system.cpython-313-x86_64-linux-gnu.so,sha256=4_7w4eY2NYheSV1CyqkolUQ_r3y2FXmGIGJWSEOOy8A,100112
h3/_cy/error_system.pxd,sha256=hhHh2IFfEQs0tWGk7Dy8eYX9q92MZWuFyFvc3vgOfPU,186
h3/_cy/error_system.pyx,sha256=Vu2iRR3iSeNjWVhGaMbeEXQQnBOLFWCU0WahFXh7X9Y,7863
h3/_cy/h3api.h,sha256=3Btq4lHCMtJgxkXVAq1fr5doEHY3TK5GIUl5krMAbUI,28084
h3/_cy/h3lib.pxd,sha256=i5Vbovo2HmxrYDOohcdwCYI9nBu_4h_9VyFozWRMbTg,7015
h3/_cy/latlng.cpython-313-x86_64-linux-gnu.so,sha256=uH3k2GVwE9AKuPckdXBRT758EoJltvQyrx7lb6LeZU4,364920
h3/_cy/latlng.pxd,sha256=WjOjY4jH_2lK6hnaVXCusqLg2DvvZ4rvAJyXeCQd2uk,266
h3/_cy/latlng.pyx,sha256=FW8L4LEr6l7qhsRL28mFakVLHnfqSCKQDQ6Ued-nLks,8370
h3/_cy/memory.cpython-313-x86_64-linux-gnu.so,sha256=BfQnN9yQWKPH1E471qPSzWzuAvRkfjmHALJg-ACEvd0,217488
h3/_cy/memory.pxd,sha256=jXGN68hdcPUyA_yFCesZxCksHwmHMO4Ah-I9ZwYBvXs,236
h3/_cy/memory.pyx,sha256=KZo65H3rXn290iH05ZNkyt78mKEGIaVjzmgYdOon_PU,7103
h3/_cy/to_multipoly.cpython-313-x86_64-linux-gnu.so,sha256=sC_ZjNswMesh1jc8g-Mg70f5tZiyQ0qyzrpOHPEVCtg,295792
h3/_cy/to_multipoly.pyx,sha256=QaDvvh-g8Ad5u-UX9_i6k55K61FdI870ShphchTtZCo,1011
h3/_cy/util.cpython-313-x86_64-linux-gnu.so,sha256=LMePiy5FWY2ZiIQuNknVw7p62k_4iPI_XmsYZMhodv8,169424
h3/_cy/util.pxd,sha256=xUjm1N9iOV2rGSwBeWNSCbvzqBNvmTzykAURj-aaBOU,372
h3/_cy/util.pyx,sha256=LiCAuRFgVwi01HTd5FnglwiGUYPXcIjurFm9u6sU6Dc,2562
h3/_cy/vertex.cpython-313-x86_64-linux-gnu.so,sha256=NunenG4zZHoAPM3MgwmEGIzphCYSVJdctT5fjUjRsRc,287696
h3/_cy/vertex.pxd,sha256=lnRECjEFpohFr7iB6d2UrTN-s37UzXnSpaP_UV5866I,229
h3/_cy/vertex.pyx,sha256=_26ur2q3CZzb0BGQ85Lvbjq9dRWscvjAsKlgmCAqVHc,910
h3/_h3shape.py,sha256=hhsBJyuy5MqDhG_BixzbCTOfQgaO6Gf2olFEYd6iLKE,8559
h3/_version.py,sha256=Tjq_BBPmWroGgfnrf7u9TpAWss9iA5PnWSv8kkZkJY8,88
h3/api/__init__.py,sha256=X6P438-1N_2jWlFKNZ8q_jUop7ICRhwwa4I0RuxtQIQ,114
h3/api/__pycache__/__init__.cpython-313.pyc,,
h3/api/basic_int/__init__.py,sha256=CWSi2Z05wVodD4YGi2i1BzIJzBDztQJDpY8D1cSO1ak,28852
h3/api/basic_int/__pycache__/__init__.cpython-313.pyc,,
h3/api/basic_int/__pycache__/_convert.cpython-313.pyc,,
h3/api/basic_int/_convert.py,sha256=GmVFFTT-mMHJ_Newx-6aF8TAtKBTrXglMx5RNV9w0Nk,187
h3/api/basic_str/__init__.py,sha256=CWSi2Z05wVodD4YGi2i1BzIJzBDztQJDpY8D1cSO1ak,28852
h3/api/basic_str/__pycache__/__init__.cpython-313.pyc,,
h3/api/basic_str/__pycache__/_convert.cpython-313.pyc,,
h3/api/basic_str/_convert.py,sha256=9B7uHdbUJhDb0GUEdSg-dUQpNCmvPviK6_DX99YS5UE,256
h3/api/memview_int/__init__.py,sha256=CWSi2Z05wVodD4YGi2i1BzIJzBDztQJDpY8D1cSO1ak,28852
h3/api/memview_int/__pycache__/__init__.cpython-313.pyc,,
h3/api/memview_int/__pycache__/_convert.cpython-313.pyc,,
h3/api/memview_int/_convert.py,sha256=ef5Omw0GJsUlR8r66O1p8f9IEEhCeTdDjlvN2A0urjA,105
h3/api/numpy_int/__init__.py,sha256=CWSi2Z05wVodD4YGi2i1BzIJzBDztQJDpY8D1cSO1ak,28852
h3/api/numpy_int/__pycache__/__init__.cpython-313.pyc,,
h3/api/numpy_int/__pycache__/_convert.cpython-313.pyc,,
h3/api/numpy_int/_convert.py,sha256=dhZLocPjucl6Uu872k1tAcuWXBRT29oUG8qFMoleulE,288
include/h3/h3api.h,sha256=3Btq4lHCMtJgxkXVAq1fr5doEHY3TK5GIUl5krMAbUI,28084
lib64/cmake/h3/h3Config.cmake,sha256=QwISc49jy-ZH9Ba1YCQnick54sapi_pZDEJjDJyMrb4,959
lib64/cmake/h3/h3ConfigVersion.cmake,sha256=AHn71cNuUHpvp6rM-5YujlrlRFQo-r2kix9PJwlwzfI,2762
lib64/cmake/h3/h3Targets-release.cmake,sha256=pnJffyu5LDg0GeSMTTwBoVLamlDKo8XrjrCEyN7aP0w,797
lib64/cmake/h3/h3Targets.cmake,sha256=YgVkLyka3gn8uUxw1xNzZXLrLKlepZcWLmPlUdQLtQY,4216
lib64/libh3.a,sha256=OrSOeUShUvbLDTFP8WNRD8HkV5zv5qJUtgaJaGU4KOg,185890
lib64/pkgconfig/h3.pc,sha256=ahuKcAzoTBU4Ym9DLsK9teEiC2eLGsi2XuAIcYwLTw0,315
@@ -0,0 +1,7 @@
Wheel-Version: 1.0
Generator: scikit-build-core 0.12.2
Root-Is-Purelib: false
Tag: cp313-cp313-manylinux_2_17_x86_64
Tag: cp313-cp313-manylinux2014_x86_64
Tag: cp313-cp313-manylinux_2_28_x86_64
@@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
@@ -0,0 +1 @@
add_subdirectory(_cy)
@@ -0,0 +1,33 @@
# flake8: noqa
from .api.basic_str import *
from ._version import __version__
from ._cy import (
UnknownH3ErrorCode,
H3BaseException,
H3GridNavigationError,
H3MemoryError,
H3ValueError,
H3FailedError,
H3DomainError,
H3LatLngDomainError,
H3ResDomainError,
H3CellInvalidError,
H3DirEdgeInvalidError,
H3UndirEdgeInvalidError,
H3VertexInvalidError,
H3PentagonError,
H3DuplicateInputError,
H3NotNeighborsError,
H3ResMismatchError,
H3MemoryAllocError,
H3MemoryBoundsError,
H3OptionInvalidError,
H3IndexInvalidError,
H3BaseCellDomainError,
H3DigitDomainError,
H3DeletedDigitError,
)
@@ -0,0 +1,53 @@
list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR})
include_directories(${CMAKE_CURRENT_SOURCE_DIR})
macro(add_cython_file filename)
add_custom_command(
OUTPUT "${filename}.c"
COMMENT
"Making ${CMAKE_CURRENT_BINARY_DIR}/${filename}.c from ${CMAKE_CURRENT_SOURCE_DIR}/${filename}.pyx"
COMMAND Python::Interpreter -m cython
"${CMAKE_CURRENT_SOURCE_DIR}/${filename}.pyx" --output-file "${filename}.c" -I ${CMAKE_CURRENT_SOURCE_DIR}
DEPENDS "${filename}.pyx"
VERBATIM)
python_add_library(${filename} MODULE "${filename}.c" WITH_SOABI)
set_property(TARGET ${filename} PROPERTY C_STANDARD 99)
target_link_libraries(${filename} PRIVATE h3)
install(TARGETS ${filename} LIBRARY DESTINATION ${SKBUILD_PROJECT_NAME}/_cy)
endmacro()
# GLOB pattern is recommended against
# https://cmake.org/cmake/help/v3.14/command/file.html?highlight=file#filesystem
add_cython_file(cells)
add_cython_file(edges)
add_cython_file(error_system)
add_cython_file(latlng)
add_cython_file(memory)
add_cython_file(vertex)
add_cython_file(to_multipoly)
add_cython_file(util)
# Include pyx and pxd files in distribution for use by Cython API
install(
FILES
cells.pxd
cells.pyx
edges.pxd
edges.pyx
error_system.pyx
h3lib.pxd
latlng.pxd
latlng.pyx
memory.pxd
memory.pyx
util.pxd
util.pyx
vertex.pxd
vertex.pyx
DESTINATION
${SKBUILD_PROJECT_NAME}/_cy
)
@@ -0,0 +1,122 @@
# flake8: noqa
"""
This module should serve as the interface between the C/Cython code and
the Python code. That is, it is an internal API.
This module should import all the Cython functions we
intend to expose to be used in pure Python code, and each of the H3-py
APIs should *only* reference functions and symbols listed here.
These functions should handle input validation, guard against the
possibility of segfaults, raise appropriate errors, and handle memory
management. The API wrapping code around this should focus on the cosmetic
function interface and input conversion (string to int, for instance).
"""
from .cells import (
is_valid_index,
is_valid_cell,
is_pentagon,
get_base_cell_number,
get_resolution,
get_index_digit,
construct_cell,
cell_to_parent,
grid_distance,
grid_disk,
grid_ring,
cell_to_children_size,
cell_to_children,
cell_to_child_pos,
child_pos_to_cell,
compact_cells,
uncompact_cells,
get_num_cells,
average_hexagon_area,
cell_area,
grid_path_cells,
is_res_class_iii,
get_pentagons,
get_res0_cells,
cell_to_center_child,
get_icosahedron_faces,
cell_to_local_ij,
local_ij_to_cell,
)
from .edges import (
are_neighbor_cells,
cells_to_directed_edge,
is_valid_directed_edge,
get_directed_edge_origin,
get_directed_edge_destination,
directed_edge_to_cells,
origin_to_directed_edges,
average_hexagon_edge_length,
edge_length,
)
from .latlng import (
latlng_to_cell,
cell_to_latlng,
polygon_to_cells,
polygons_to_cells,
polygon_to_cells_experimental,
polygons_to_cells_experimental,
cell_to_boundary,
directed_edge_to_boundary,
great_circle_distance,
)
from .vertex import (
cell_to_vertex,
cell_to_vertexes,
vertex_to_latlng,
is_valid_vertex,
)
from .to_multipoly import (
cells_to_multi_polygon
)
from .util import (
c_version,
str_to_int,
int_to_str,
)
from .memory import (
iter_to_mv,
)
from .error_system import (
UnknownH3ErrorCode,
H3BaseException,
H3GridNavigationError,
H3MemoryError,
H3ValueError,
H3FailedError,
H3DomainError,
H3LatLngDomainError,
H3ResDomainError,
H3CellInvalidError,
H3DirEdgeInvalidError,
H3UndirEdgeInvalidError,
H3VertexInvalidError,
H3PentagonError,
H3DuplicateInputError,
H3NotNeighborsError,
H3ResMismatchError,
H3MemoryAllocError,
H3MemoryBoundsError,
H3OptionInvalidError,
H3IndexInvalidError,
H3BaseCellDomainError,
H3DigitDomainError,
H3DeletedDigitError,
get_H3_ERROR_END,
error_code_to_exception,
)
@@ -0,0 +1,30 @@
from .h3lib cimport bool, int64_t, H3int
cpdef bool is_valid_index(H3int h)
cpdef bool is_valid_cell(H3int h)
cpdef bool is_pentagon(H3int h)
cpdef int get_base_cell_number(H3int h) except -1
cpdef int get_resolution(H3int h) except -1
cpdef int get_index_digit(H3int h, int res) except -1
cpdef H3int construct_cell(int baseCellNumber, const int[:] digits) except 0
cpdef int grid_distance(H3int h1, H3int h2) except -1
cpdef H3int[:] grid_disk(H3int h, int k)
cpdef H3int[:] grid_ring(H3int h, int k)
cpdef H3int cell_to_parent(H3int h, res=*) except 0
cpdef int64_t cell_to_children_size(H3int h, res=*) except -1
cpdef H3int[:] cell_to_children(H3int h, res=*)
cpdef H3int cell_to_center_child(H3int h, res=*) except 0
cpdef int64_t cell_to_child_pos(H3int child, int parent_res) except -1
cpdef H3int child_pos_to_cell(H3int parent, int child_res, int64_t child_pos) except 0
cpdef H3int[:] compact_cells(const H3int[:] hu)
cpdef H3int[:] uncompact_cells(const H3int[:] hc, int res)
cpdef int64_t get_num_cells(int resolution) except -1
cpdef double average_hexagon_area(int resolution, unit=*) except -1
cpdef double cell_area(H3int h, unit=*) except -1
cpdef H3int[:] grid_path_cells(H3int start, H3int end)
cpdef bool is_res_class_iii(H3int h)
cpdef H3int[:] get_pentagons(int res)
cpdef H3int[:] get_res0_cells()
cpdef get_icosahedron_faces(H3int h)
cpdef (int, int) cell_to_local_ij(H3int origin, H3int h) except *
cpdef H3int local_ij_to_cell(H3int origin, int i, int j) except 0
@@ -0,0 +1,455 @@
cimport h3lib
from .h3lib cimport bool, int64_t, H3int, H3ErrorCodes
from .util cimport (
check_cell,
check_index,
check_distance,
)
from .error_system cimport (
H3Error,
check_for_error,
check_for_error_msg,
)
from .memory cimport (
H3MemoryManager,
int_mv,
)
# todo: add notes about Cython exception handling
cpdef bool is_valid_index(H3int h):
"""Validates an H3 index (cell, vertex, or directed edge).
Returns
-------
boolean
"""
return h3lib.isValidIndex(h) == 1
# bool is a python type, so we don't need the except clause
cpdef bool is_valid_cell(H3int h):
"""Validates an H3 cell (hexagon or pentagon)
Returns
-------
boolean
"""
return h3lib.isValidCell(h) == 1
cpdef bool is_pentagon(H3int h):
return h3lib.isPentagon(h) == 1
cpdef int get_base_cell_number(H3int h) except -1:
check_cell(h)
return h3lib.getBaseCellNumber(h)
cpdef int get_resolution(H3int h) except -1:
"""Returns the resolution of an H3 Index
0--15
"""
check_cell(h)
return h3lib.getResolution(h)
cpdef int get_index_digit(H3int h, int res) except -1:
cdef:
int digit
check_index(h)
check_for_error(
h3lib.getIndexDigit(h, res, &digit)
)
return digit
cpdef H3int construct_cell(int base_cell_number, const int[:] digits) except 0:
cdef:
H3int out
int res = len(digits)
H3Error err
if res > 0:
err = h3lib.constructCell(res, base_cell_number, &digits[0], &out)
else:
err = h3lib.constructCell(res, base_cell_number, NULL, &out)
check_for_error(err)
return out
cpdef int grid_distance(H3int h1, H3int h2) except -1:
""" Compute the grid distance between two cells
"""
cdef:
int64_t distance
check_cell(h1)
check_cell(h2)
check_for_error(
h3lib.gridDistance(h1, h2, &distance)
)
return distance
cpdef H3int[:] grid_disk(H3int h, int k):
""" Return cells at grid distance `<= k` from `h`.
"""
cdef:
int64_t n
check_cell(h)
check_distance(k)
check_for_error(
h3lib.maxGridDiskSize(k, &n)
)
hmm = H3MemoryManager(n)
check_for_error(
h3lib.gridDisk(h, k, hmm.ptr)
)
mv = hmm.to_mv()
return mv
cpdef H3int[:] grid_ring(H3int h, int k):
""" Return cells at grid distance `== k` from `h`.
Collection is "hollow" for k >= 1.
"""
check_cell(h)
check_distance(k)
n = 6*k if k > 0 else 1
hmm = H3MemoryManager(n)
check_for_error(
h3lib.gridRing(h, k, hmm.ptr)
)
mv = hmm.to_mv()
return mv
cpdef H3int cell_to_parent(H3int h, res=None) except 0:
cdef:
H3int parent
check_cell(h)
if res is None:
res = get_resolution(h) - 1
err = h3lib.cellToParent(h, res, &parent)
if err:
msg = 'Invalid parent resolution {} for cell {}.'
msg = msg.format(res, hex(h))
check_for_error_msg(err, msg)
return parent
cpdef int64_t cell_to_children_size(H3int h, res=None) except -1:
cdef:
int64_t n
check_cell(h)
if res is None:
res = get_resolution(h) + 1
err = h3lib.cellToChildrenSize(h, res, &n)
if err:
msg = 'Invalid child resolution {} for cell {}.'
msg = msg.format(res, hex(h))
check_for_error_msg(err, msg)
return n
cpdef H3int[:] cell_to_children(H3int h, res=None):
check_cell(h)
if res is None:
res = get_resolution(h) + 1
n = cell_to_children_size(h, res)
hmm = H3MemoryManager(n)
check_for_error(
h3lib.cellToChildren(h, res, hmm.ptr)
)
mv = hmm.to_mv()
return mv
cpdef H3int cell_to_center_child(H3int h, res=None) except 0:
cdef:
H3int child
check_cell(h)
if res is None:
res = get_resolution(h) + 1
err = h3lib.cellToCenterChild(h, res, &child)
if err:
msg = 'Invalid child resolution {} for cell {}.'
msg = msg.format(res, hex(h))
check_for_error_msg(err, msg)
return child
cpdef int64_t cell_to_child_pos(H3int child, int parent_res) except -1:
cdef:
int64_t child_pos
check_cell(child)
err = h3lib.cellToChildPos(child, parent_res, &child_pos)
if err:
msg = "Couldn't find child pos of cell {} at res {}."
msg = msg.format(hex(child), parent_res)
check_for_error_msg(err, msg)
return child_pos
cpdef H3int child_pos_to_cell(H3int parent, int child_res, int64_t child_pos) except 0:
cdef:
H3int child
check_cell(parent)
err = h3lib.childPosToCell(child_pos, parent, child_res, &child)
if err:
msg = "Couldn't find child with pos {} at res {} from parent {}."
msg = msg.format(child_pos, child_res, hex(parent))
check_for_error_msg(err, msg)
return child
cpdef H3int[:] compact_cells(const H3int[:] hu):
# todo: fix this with my own Cython object "wrapper" class?
# everything has a .ptr interface?
# todo: the Clib can handle 0-len arrays because it **avoids**
# dereferencing the pointer, but Cython's syntax of
# `&hu[0]` **requires** a dereference. For Cython, checking for array
# length of zero and returning early seems like the easiest solution.
# note: open to better ideas!
if len(hu) == 0:
return H3MemoryManager(0).to_mv()
for h in hu: ## todo: should we have an array version? would that be faster?
check_cell(h)
cdef size_t n = len(hu)
hmm = H3MemoryManager(n)
check_for_error(
h3lib.compactCells(&hu[0], hmm.ptr, n)
)
mv = hmm.to_mv()
return mv
# todo: https://stackoverflow.com/questions/50684977/cython-exception-type-for-a-function-returning-a-typed-memoryview
# apparently, memoryviews are python objects, so we don't need to do the except clause
cpdef H3int[:] uncompact_cells(const H3int[:] hc, int res):
# todo: the Clib can handle 0-len arrays because it **avoids**
# dereferencing the pointer, but Cython's syntax of
# `&hc[0]` **requires** a dereference. For Cython, checking for array
# length of zero and returning early seems like the easiest solution.
# note: open to better ideas!
cdef:
int64_t n
if len(hc) == 0:
return H3MemoryManager(0).to_mv()
for h in hc:
check_cell(h)
check_for_error(
h3lib.uncompactCellsSize(&hc[0], len(hc), res, &n)
)
hmm = H3MemoryManager(n)
check_for_error(
h3lib.uncompactCells(
&hc[0], # todo: symmetry here with the wrapper object might be nice. hc.ptr / hc.n
len(hc),
hmm.ptr,
hmm.n,
res
)
)
mv = hmm.to_mv()
return mv
cpdef int64_t get_num_cells(int resolution) except -1:
cdef:
int64_t num_cells
check_for_error(
h3lib.getNumCells(resolution, &num_cells)
)
return num_cells
cpdef double average_hexagon_area(int resolution, unit='km^2') except -1:
cdef:
double area
check_for_error(
h3lib.getHexagonAreaAvgKm2(resolution, &area)
)
# todo: multiple units
convert = {
'km^2': 1.0,
'm^2': 1000*1000.0
}
try:
area *= convert[unit]
except:
raise ValueError('Unknown unit: {}'.format(unit))
return area
cpdef double cell_area(H3int h, unit='km^2') except -1:
cdef:
double area
if unit == 'rads^2':
err = h3lib.cellAreaRads2(h, &area)
elif unit == 'km^2':
err = h3lib.cellAreaKm2(h, &area)
elif unit == 'm^2':
err = h3lib.cellAreaM2(h, &area)
else:
raise ValueError('Unknown unit: {}'.format(unit))
check_for_error(err)
return area
cdef _could_not_find_line(err, start, end):
msg = "Couldn't find line between cells {} and {}"
msg = msg.format(hex(start), hex(end))
check_for_error_msg(err, msg)
cpdef H3int[:] grid_path_cells(H3int start, H3int end):
cdef:
int64_t n
# todo: can we segfault here with invalid inputs?
# Can we trust the c library to validate the start/end cells?
# probably applies to all size/work pairs of functions...
err = h3lib.gridPathCellsSize(start, end, &n)
_could_not_find_line(err, start, end)
hmm = H3MemoryManager(n)
err = h3lib.gridPathCells(start, end, hmm.ptr)
_could_not_find_line(err, start, end)
# todo: probably here too?
mv = hmm.to_mv()
return mv
cpdef bool is_res_class_iii(H3int h):
return h3lib.isResClassIII(h) == 1
cpdef H3int[:] get_pentagons(int res):
n = h3lib.pentagonCount()
hmm = H3MemoryManager(n)
check_for_error(
h3lib.getPentagons(res, hmm.ptr)
)
mv = hmm.to_mv()
return mv
cpdef H3int[:] get_res0_cells():
n = h3lib.res0CellCount()
hmm = H3MemoryManager(n)
check_for_error(
h3lib.getRes0Cells(hmm.ptr)
)
mv = hmm.to_mv()
return mv
# oh, this is returning a set??
# todo: convert to int[:]?
cpdef get_icosahedron_faces(H3int h):
cdef:
int n
int[:] faces ## todo: weird, this needs to be specified to avoid errors. cython bug?
check_for_error(
h3lib.maxFaceCount(h, &n)
)
faces = int_mv(n)
check_for_error(
h3lib.getIcosahedronFaces(h, &faces[0])
)
# todo: wait? do faces start from 0 or 1?
# we could do this check/processing in the int_mv object
out = [f for f in faces if f >= 0]
return out
cpdef (int, int) cell_to_local_ij(H3int origin, H3int h) except *:
cdef:
h3lib.CoordIJ c
err = h3lib.cellToLocalIj(origin, h, 0, &c)
if err:
msg = "Couldn't find local (i,j) between cells {} and {}."
msg = msg.format(hex(origin), hex(h))
check_for_error_msg(err, msg)
return c.i, c.j
cpdef H3int local_ij_to_cell(H3int origin, int i, int j) except 0:
cdef:
h3lib.CoordIJ c
H3int out
c.i, c.j = i, j
err = h3lib.localIjToCell(origin, &c, 0, &out)
if err:
msg = "Couldn't find cell at local ({},{}) from cell {}."
msg = msg.format(i, j, hex(origin))
check_for_error_msg(err, msg)
return out
@@ -0,0 +1,11 @@
from .h3lib cimport bool, H3int
cpdef bool are_neighbor_cells(H3int h1, H3int h2)
cpdef H3int cells_to_directed_edge(H3int origin, H3int destination) except *
cpdef bool is_valid_directed_edge(H3int e)
cpdef H3int get_directed_edge_origin(H3int e) except 1
cpdef H3int get_directed_edge_destination(H3int e) except 1
cpdef (H3int, H3int) directed_edge_to_cells(H3int e) except *
cpdef H3int[:] origin_to_directed_edges(H3int origin)
cpdef double average_hexagon_edge_length(int resolution, unit=*) except -1
cpdef double edge_length(H3int e, unit=*) except -1
@@ -0,0 +1,114 @@
cimport h3lib
from .h3lib cimport bool, H3int
from .error_system cimport check_for_error
from .memory cimport H3MemoryManager
# todo: make bint
cpdef bool are_neighbor_cells(H3int h1, H3int h2):
cdef:
int out
err = h3lib.areNeighborCells(h1, h2, &out)
# note: we are intentionally not raising an error here, and just
# returning false.
# todo: is this choice consistent across the Python and C libs?
if err:
return False
return out == 1
cpdef H3int cells_to_directed_edge(H3int origin, H3int destination) except *:
cdef:
int neighbor_out
H3int out
check_for_error(
h3lib.cellsToDirectedEdge(origin, destination, &out)
)
return out
cpdef bool is_valid_directed_edge(H3int e):
return h3lib.isValidDirectedEdge(e) == 1
cpdef H3int get_directed_edge_origin(H3int e) except 1:
cdef:
H3int out
check_for_error(
h3lib.getDirectedEdgeOrigin(e, &out)
)
return out
cpdef H3int get_directed_edge_destination(H3int e) except 1:
cdef:
H3int out
check_for_error(
h3lib.getDirectedEdgeDestination(e, &out)
)
return out
cpdef (H3int, H3int) directed_edge_to_cells(H3int e) except *:
# todo: use directed_edge_to_cells in h3lib
return get_directed_edge_origin(e), get_directed_edge_destination(e)
cpdef H3int[:] origin_to_directed_edges(H3int origin):
""" Returns the 6 (or 5 for pentagons) directed edges
for the given origin cell
"""
hmm = H3MemoryManager(6)
check_for_error(
h3lib.originToDirectedEdges(origin, hmm.ptr)
)
mv = hmm.to_mv()
return mv
cpdef double average_hexagon_edge_length(int resolution, unit='km') except -1:
cdef:
double length
check_for_error(
h3lib.getHexagonEdgeLengthAvgKm(resolution, &length)
)
# todo: multiple units
convert = {
'km': 1.0,
'm': 1000.0
}
try:
length *= convert[unit]
except:
raise ValueError('Unknown unit: {}'.format(unit))
return length
cpdef double edge_length(H3int e, unit='km') except -1:
cdef:
double length
if unit == 'rads':
err = h3lib.edgeLengthRads(e, &length)
elif unit == 'km':
err = h3lib.edgeLengthKm(e, &length)
elif unit == 'm':
err = h3lib.edgeLengthM(e, &length)
else:
raise ValueError('Unknown unit: {}'.format(unit))
check_for_error(err)
return length
@@ -0,0 +1,6 @@
from .h3lib cimport H3Error
cpdef error_code_to_exception(H3Error err)
cdef check_for_error(H3Error err)
cdef check_for_error_msg(H3Error err, str msg)
cpdef H3Error get_H3_ERROR_END()
@@ -0,0 +1,260 @@
"""
Exceptions from the h3-py library have three possible sources:
- the Python code
- the Cython code
- the underlying H3 C library code
The Python and Cython `h3-py` code will only raise standard Python
built-in exceptions; **no custom** exception classes will be used.
Conversely, many functions in the H3 C library return a `uint32_t`
error code (aliased as type `H3Error`).
When these errors happen (and `h3-py` can't recover from them internally),
they are passed up to the Python/Cython code, where their
`uint32_t` error values are converted to **custom** Python exception types.
These custom exception classes all inherit from `H3BaseException`.
There is a 1-1 correspondence between the concrete subclasses of
`H3BaseException` and the H3 C library `H3ErrorCodes` values.
The correspondence is intentional, so that the user can refer to the
H3 C library documentation on these errors.
The (`uint32_t` <-> Exception) correspondence should be clear from
the names of each error/exception, but the explicit mapping is given by
a dictionary in the code below.
Note that some "abstract" subclasses of `H3BaseException` are also included to
group the exceptions by type. (We say "abstract" because Python has no easy
way to make true abstract exception classes.)
These "abstract" exceptions will never be raised directly by `h3-py`, but they
allow the user to catch general groups of errors.
Note that `h3-py` will only ever directly raise
the "concrete" exception classes.
Summarizing, all exceptions originating from the C library inherit from
`H3BaseException`, which has both "abstract" and "concrete" subclasses.
**Abstract classes**:
- H3BaseException
- H3ValueError
- H3MemoryError
- H3GridNavigationError
**Concrete classes**:
- H3FailedError
- H3DomainError
- H3LatLngDomainError
- H3ResDomainError
- H3CellInvalidError
- H3DirEdgeInvalidError
- H3UndirEdgeInvalidError
- H3VertexInvalidError
- H3PentagonError
- H3DuplicateInputError
- H3NotNeighborsError
- H3ResMismatchError
- H3MemoryAllocError
- H3MemoryBoundsError
- H3OptionInvalidError
- H3IndexInvalidError
- H3BaseCellDomainError
- H3DigitDomainError
- H3DeletedDigitError
# TODO: add tests verifying that concrete exception classes have the right error codes associated with them
"""
from contextlib import contextmanager
from .h3lib cimport (
H3Error,
# H3ErrorCodes enum values
E_SUCCESS,
E_FAILED,
E_DOMAIN,
E_LATLNG_DOMAIN,
E_RES_DOMAIN,
E_CELL_INVALID,
E_DIR_EDGE_INVALID,
E_UNDIR_EDGE_INVALID,
E_VERTEX_INVALID,
E_PENTAGON,
E_DUPLICATE_INPUT,
E_NOT_NEIGHBORS,
E_RES_MISMATCH,
E_MEMORY_ALLOC,
E_MEMORY_BOUNDS,
E_OPTION_INVALID,
E_INDEX_INVALID,
E_BASE_CELL_DOMAIN,
E_DIGIT_DOMAIN,
E_DELETED_DIGIT,
H3_ERROR_END # sentinel value
)
@contextmanager
def _the_error(obj):
"""
Syntactic maple syrup for grouping exception definitions.
The associated `with` statement ends up as a not-half-bad
approximation to a valid sentence fragment.
This provides sort of a "pretend scope", in that it allows for
block indentation which helps to visually indicate the "scope"
of the `... as e` statement. Just note that Python doesn't treat the
`with` block as a "true" separate scope.
Note that this doesn't actually do anything context-manager-y, outside
of the variable assignment and block indentation.
"""
yield obj
#
# Base exception for C library error codes
#
class H3BaseException(Exception):
""" Base H3 exception class.
Concrete subclasses of this class correspond to specific
error codes from the C library.
Base/abstract subclasses will have `h3_error_code = None`, while
concrete subclasses will have `h3_error_code` equal to their associated
C library error code.
"""
h3_error_code = None
#
# A few "abstract" exceptions; organizational.
#
with _the_error(H3BaseException) as e:
class H3ValueError(e, ValueError): ...
class H3MemoryError(e, MemoryError): ...
class H3GridNavigationError(e, RuntimeError): ...
#
# Concrete exceptions
#
class UnknownH3ErrorCode(H3BaseException):
"""
Indicates that the h3-py Python bindings have received an
unrecognized error code from the C library.
This should never happen. Please report if you get this error.
Note that this exception is *outside* of the
H3BaseException class hierarchy.
"""
pass
with _the_error(H3BaseException) as e:
class H3FailedError(e): ...
with _the_error(H3GridNavigationError) as e:
class H3PentagonError(e): ...
with _the_error(H3MemoryError) as e:
class H3MemoryAllocError(e): ...
class H3MemoryBoundsError(e): ...
with _the_error(H3ValueError) as e:
class H3DomainError(e): ...
class H3LatLngDomainError(e): ...
class H3ResDomainError(e): ...
class H3CellInvalidError(e): ...
class H3DirEdgeInvalidError(e): ...
class H3UndirEdgeInvalidError(e): ...
class H3VertexInvalidError(e): ...
class H3DuplicateInputError(e): ...
class H3NotNeighborsError(e): ...
class H3ResMismatchError(e): ...
class H3OptionInvalidError(e): ...
class H3IndexInvalidError(e): ...
class H3BaseCellDomainError(e): ...
class H3DigitDomainError(e): ...
class H3DeletedDigitError(e): ...
"""
This defines a mapping between uint32_t error codes and concrete Python
exception classes.
Note that we intentionally omit E_SUCCESS, as it isn't an actual error.
"""
error_mapping = {
E_FAILED: H3FailedError,
E_DOMAIN: H3DomainError,
E_LATLNG_DOMAIN: H3LatLngDomainError,
E_RES_DOMAIN: H3ResDomainError,
E_CELL_INVALID: H3CellInvalidError,
E_DIR_EDGE_INVALID: H3DirEdgeInvalidError,
E_UNDIR_EDGE_INVALID: H3UndirEdgeInvalidError,
E_VERTEX_INVALID: H3VertexInvalidError,
E_PENTAGON: H3PentagonError,
E_DUPLICATE_INPUT: H3DuplicateInputError,
E_NOT_NEIGHBORS: H3NotNeighborsError,
E_RES_MISMATCH: H3ResMismatchError,
E_MEMORY_ALLOC: H3MemoryAllocError,
E_MEMORY_BOUNDS: H3MemoryBoundsError,
E_OPTION_INVALID: H3OptionInvalidError,
E_INDEX_INVALID: H3IndexInvalidError,
E_BASE_CELL_DOMAIN: H3BaseCellDomainError,
E_DIGIT_DOMAIN: H3DigitDomainError,
E_DELETED_DIGIT: H3DeletedDigitError,
}
# Go back and modify the class definitions so that each concrete exception
# stores its associated error code.
for code, ex in error_mapping.items():
ex.h3_error_code = code
#
# Helper functions
#
# TODO: Move the helpers to util?
# TODO: Unclear how/where to expose these functions. cdef/cpdef?
cpdef error_code_to_exception(H3Error err):
"""
Return Python exception corresponding to integer error code
given via the H3ErrorCodes enum in `h3api.h.in` in the C library.
"""
if err == E_SUCCESS:
return None
elif err in error_mapping:
return error_mapping[err]
else:
return UnknownH3ErrorCode(err)
cdef check_for_error(H3Error err):
ex = error_code_to_exception(err)
if ex:
raise ex
cpdef H3Error get_H3_ERROR_END():
"""
Return integer H3_ERROR_END from the H3ErrorCodes enum
in `h3api.h.in` in the C library, which is one greater than
the last valid error code.
"""
return H3_ERROR_END
# todo: There's no easy way to do `*args` in `cdef` functions, but I'm also
# not sure this even needs to be a Cython `cdef` function at all, or that
# any of the other helper functions need to be in Cython.
# todo: Revisit after we've played with this a bit.
# todo: also: maybe the extra messages aren't that much more helpful...
cdef check_for_error_msg(H3Error err, str msg):
ex = error_code_to_exception(err)
if ex:
raise ex(msg)
@@ -0,0 +1,860 @@
/*
* Copyright 2016-2021 Uber Technologies, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @file h3api.h
* @brief Primary H3 core library entry points.
*
* This file defines the public API of the H3 library. Incompatible changes to
* these functions require the library's major version be increased.
*/
#ifndef H3API_H
#define H3API_H
/*
* Preprocessor code to support renaming (prefixing) the public API.
* All public functions should be wrapped in H3_EXPORT so they can be
* renamed.
*/
#ifdef H3_PREFIX
#define XTJOIN(a, b) a##b
#define TJOIN(a, b) XTJOIN(a, b)
/* export joins the user provided prefix with our exported function name */
#define H3_EXPORT(name) TJOIN(H3_PREFIX, name)
#else
#define H3_EXPORT(name) name
#endif
/* Windows DLL requires attributes indicating what to export */
#if _WIN32 && BUILD_SHARED_LIBS
#if BUILDING_H3
#define DECLSPEC __declspec(dllexport)
#else
#define DECLSPEC __declspec(dllimport)
#endif
#else
#define DECLSPEC
#endif
/* For uint64_t */
#include <stdint.h>
/* For size_t */
#include <stdlib.h>
/*
* H3 is compiled as C, not C++ code. `extern "C"` is needed for C++ code
* to be able to use the library.
*/
#ifdef __cplusplus
extern "C" {
#endif
/** @brief Identifier for an object (cell, edge, etc) in the H3 system.
*
* The H3Index fits within a 64-bit unsigned integer.
*/
typedef uint64_t H3Index;
/**
* Invalid index used to indicate an error from latLngToCell and related
* functions or missing data in arrays of H3 indices. Analogous to NaN in
* floating point.
*/
#define H3_NULL 0
/** @brief Result code (success or specific error) from an H3 operation */
typedef uint32_t H3Error;
typedef enum {
E_SUCCESS = 0, // Success (no error)
E_FAILED = 1, // The operation failed but a more specific error is not
// available
E_DOMAIN = 2, // Argument was outside the acceptable range (when a more
// specific error code is not available)
E_LATLNG_DOMAIN = 3, // Latitude or longitude arguments were outside the
// acceptable range
E_RES_DOMAIN = 4, // Resolution argument was outside the acceptable range
E_CELL_INVALID = 5, // `H3Index` cell argument was not valid
E_DIR_EDGE_INVALID = 6, // `H3Index` directed edge argument was not valid
E_UNDIR_EDGE_INVALID =
7, // `H3Index` undirected edge argument was not valid
E_VERTEX_INVALID = 8, // `H3Index` vertex argument was not valid
E_PENTAGON = 9, // Pentagon distortion was encountered which the algorithm
// could not handle
E_DUPLICATE_INPUT = 10, // Duplicate input was encountered in the arguments
// and the algorithm could not handle it
E_NOT_NEIGHBORS = 11, // `H3Index` cell arguments were not neighbors
E_RES_MISMATCH =
12, // `H3Index` cell arguments had incompatible resolutions
E_MEMORY_ALLOC = 13, // Necessary memory allocation failed
E_MEMORY_BOUNDS = 14, // Bounds of provided memory were not large enough
E_OPTION_INVALID = 15, // Mode or flags argument was not valid
E_INDEX_INVALID = 16, // `H3Index` argument was not valid
E_BASE_CELL_DOMAIN =
17, // Base cell number was outside of acceptable range
E_DIGIT_DOMAIN = 18, // Child digits invalid
E_DELETED_DIGIT = 19, // Deleted subsequence indicates invalid index
// Sentinel value; not a real error. One past the last valid code.
H3_ERROR_END
} H3ErrorCodes;
/** @defgroup describeH3Error describeH3Error
* Functions for describeH3Error
* @{
*/
/** @brief converts the provided H3Error value into a description string */
DECLSPEC const char *H3_EXPORT(describeH3Error)(H3Error err);
/** @} */
/* library version numbers generated from VERSION file */
// clang-format off
#define H3_VERSION_MAJOR 4
#define H3_VERSION_MINOR 5
#define H3_VERSION_PATCH 0
// clang-format on
/** Maximum number of cell boundary vertices; worst case is pentagon:
* 5 original verts + 5 edge crossings
*/
#define MAX_CELL_BNDRY_VERTS 10
/** @struct LatLng
@brief latitude/longitude in radians
*/
typedef struct {
double lat; ///< latitude in radians
double lng; ///< longitude in radians
} LatLng;
/** @struct CellBoundary
@brief cell boundary in latitude/longitude
*/
typedef struct {
int numVerts; ///< number of vertices
LatLng verts[MAX_CELL_BNDRY_VERTS]; ///< vertices in ccw order
} CellBoundary;
/** @struct GeoLoop
* @brief similar to CellBoundary, but requires more alloc work
*/
typedef struct {
int numVerts;
LatLng *verts;
} GeoLoop;
/** @struct GeoPolygon
* @brief Simplified core of GeoJSON Polygon coordinates definition
*/
typedef struct {
GeoLoop geoloop; ///< exterior boundary of the polygon
int numHoles; ///< number of elements in the array pointed to by holes
GeoLoop *holes; ///< interior boundaries (holes) in the polygon
} GeoPolygon;
/** @struct GeoMultiPolygon
* @brief Simplified core of GeoJSON MultiPolygon coordinates definition
*/
typedef struct {
int numPolygons;
GeoPolygon *polygons;
} GeoMultiPolygon;
/**
* Values representing polyfill containment modes, to be used in
* the `flags` bit field for `polygonToCellsExperimental`.
*/
typedef enum {
CONTAINMENT_CENTER = 0, ///< Cell center is contained in the shape
CONTAINMENT_FULL = 1, ///< Cell is fully contained in the shape
CONTAINMENT_OVERLAPPING = 2, ///< Cell overlaps the shape at any point
CONTAINMENT_OVERLAPPING_BBOX = 3, ///< Cell bounding box overlaps shape
CONTAINMENT_INVALID = 4 ///< This mode is invalid and should not be used
} ContainmentMode;
/** @struct LinkedLatLng
* @brief A coordinate node in a linked geo structure, part of a linked list
*/
typedef struct LinkedLatLng LinkedLatLng;
struct LinkedLatLng {
LatLng vertex;
LinkedLatLng *next;
};
/** @struct LinkedGeoLoop
* @brief A loop node in a linked geo structure, part of a linked list
*/
typedef struct LinkedGeoLoop LinkedGeoLoop;
struct LinkedGeoLoop {
LinkedLatLng *first;
LinkedLatLng *last;
LinkedGeoLoop *next;
};
/** @struct LinkedGeoPolygon
* @brief A polygon node in a linked geo structure, part of a linked list.
*/
typedef struct LinkedGeoPolygon LinkedGeoPolygon;
struct LinkedGeoPolygon {
LinkedGeoLoop *first;
LinkedGeoLoop *last;
LinkedGeoPolygon *next;
};
/** @struct CoordIJ
* @brief IJ hexagon coordinates
*
* Each axis is spaced 120 degrees apart.
*/
typedef struct {
int i; ///< i component
int j; ///< j component
} CoordIJ;
/** @defgroup latLngToCell latLngToCell
* Functions for latLngToCell
* @{
*/
/** @brief find the H3 index of the resolution res cell containing the lat/lng
*/
DECLSPEC H3Error H3_EXPORT(latLngToCell)(const LatLng *g, int res,
H3Index *out);
/** @} */
/** @defgroup cellToLatLng cellToLatLng
* Functions for cellToLatLng
* @{
*/
/** @brief find the lat/lng center point g of the cell h3 */
DECLSPEC H3Error H3_EXPORT(cellToLatLng)(H3Index h3, LatLng *g);
/** @} */
/** @defgroup cellToBoundary cellToBoundary
* Functions for cellToBoundary
* @{
*/
/** @brief give the cell boundary in lat/lng coordinates for the cell h3 */
DECLSPEC H3Error H3_EXPORT(cellToBoundary)(H3Index h3, CellBoundary *gp);
/** @} */
/** @defgroup gridDisk gridDisk
* Functions for gridDisk
* @{
*/
/** @brief maximum number of hexagons in k-ring */
DECLSPEC H3Error H3_EXPORT(maxGridDiskSize)(int k, int64_t *out);
/** @brief hexagons neighbors in all directions, assuming no pentagons */
DECLSPEC H3Error H3_EXPORT(gridDiskUnsafe)(H3Index origin, int k, H3Index *out);
/** @} */
/** @brief hexagons neighbors in all directions, assuming no pentagons,
* reporting distance from origin */
DECLSPEC H3Error H3_EXPORT(gridDiskDistancesUnsafe)(H3Index origin, int k,
H3Index *out,
int *distances);
/** @brief hexagons neighbors in all directions reporting distance from origin
*/
DECLSPEC H3Error H3_EXPORT(gridDiskDistancesSafe)(H3Index origin, int k,
H3Index *out, int *distances);
/** @brief collection of hex rings sorted by ring for all given hexagons */
DECLSPEC H3Error H3_EXPORT(gridDisksUnsafe)(H3Index *h3Set, int length, int k,
H3Index *out);
/** @brief hexagon neighbors in all directions */
DECLSPEC H3Error H3_EXPORT(gridDisk)(H3Index origin, int k, H3Index *out);
/** @} */
/** @defgroup gridDiskDistances gridDiskDistances
* Functions for gridDiskDistances
* @{
*/
/** @brief hexagon neighbors in all directions, reporting distance from origin
*/
DECLSPEC H3Error H3_EXPORT(gridDiskDistances)(H3Index origin, int k,
H3Index *out, int *distances);
/** @} */
/** @defgroup gridRing gridRing
* Functions for gridRing
* @{
*/
/** @brief maximum number of hexagons in hollow k-ring */
DECLSPEC H3Error H3_EXPORT(maxGridRingSize)(int k, int64_t *out);
/** @brief hollow hexagon ring k distance from origin */
DECLSPEC H3Error H3_EXPORT(gridRingUnsafe)(H3Index origin, int k, H3Index *out);
/** @brief hollow hexagon ring k distance from origin */
DECLSPEC H3Error H3_EXPORT(gridRing)(H3Index origin, int k, H3Index *out);
/** @} */
/** @defgroup polygonToCells polygonToCells
* Functions for polygonToCells
* @{
*/
/** @brief maximum number of cells that could be in the polygon */
DECLSPEC H3Error H3_EXPORT(maxPolygonToCellsSize)(const GeoPolygon *geoPolygon,
int res, uint32_t flags,
int64_t *out);
/** @brief cells within the given polygon */
DECLSPEC H3Error H3_EXPORT(polygonToCells)(const GeoPolygon *geoPolygon,
int res, uint32_t flags,
H3Index *out);
/** @} */
/** @defgroup polygonToCellsExperimental polygonToCellsExperimental
* Functions for polygonToCellsExperimental.
* This is an experimental-only API and is subject to change in minor versions.
* @{
*/
/** @brief maximum number of cells that could be in the polygon */
DECLSPEC H3Error H3_EXPORT(maxPolygonToCellsSizeExperimental)(
const GeoPolygon *polygon, int res, uint32_t flags, int64_t *out);
/** @brief cells within the given polygon */
DECLSPEC H3Error H3_EXPORT(polygonToCellsExperimental)(
const GeoPolygon *polygon, int res, uint32_t flags, int64_t size,
H3Index *out);
/** @} */
/** @defgroup cellsToMultiPolygon cellsToMultiPolygon
* Functions for cellsToMultiPolygon (currently a binding-only concept)
* @{
*/
/** @brief Create a LinkedGeoPolygon from a set of cells */
DECLSPEC H3Error H3_EXPORT(cellsToLinkedMultiPolygon)(const H3Index *h3Set,
const int numHexes,
LinkedGeoPolygon *out);
/** @brief Free all memory created for a LinkedGeoPolygon */
DECLSPEC void H3_EXPORT(destroyLinkedMultiPolygon)(LinkedGeoPolygon *polygon);
/** @} */
/** @defgroup degsToRads degsToRads
* Functions for degsToRads
* @{
*/
/** @brief converts degrees to radians */
DECLSPEC double H3_EXPORT(degsToRads)(double degrees);
/** @} */
/** @defgroup radsToDegs radsToDegs
* Functions for radsToDegs
* @{
*/
/** @brief converts radians to degrees */
DECLSPEC double H3_EXPORT(radsToDegs)(double radians);
/** @} */
/** @defgroup greatCircleDistance greatCircleDistance
* Functions for distance
* @{
*/
/** @brief "great circle distance" between pairs of LatLng points in radians*/
DECLSPEC double H3_EXPORT(greatCircleDistanceRads)(const LatLng *a,
const LatLng *b);
/** @brief "great circle distance" between pairs of LatLng points in
* kilometers*/
DECLSPEC double H3_EXPORT(greatCircleDistanceKm)(const LatLng *a,
const LatLng *b);
/** @brief "great circle distance" between pairs of LatLng points in meters*/
DECLSPEC double H3_EXPORT(greatCircleDistanceM)(const LatLng *a,
const LatLng *b);
/** @} */
/** @defgroup getHexagonAreaAvg getHexagonAreaAvg
* Functions for getHexagonAreaAvg
* @{
*/
/** @brief average hexagon area in square kilometers (excludes pentagons) */
DECLSPEC H3Error H3_EXPORT(getHexagonAreaAvgKm2)(int res, double *out);
/** @brief average hexagon area in square meters (excludes pentagons) */
DECLSPEC H3Error H3_EXPORT(getHexagonAreaAvgM2)(int res, double *out);
/** @} */
/** @defgroup cellArea cellArea
* Functions for cellArea
* @{
*/
/** @brief exact area for a specific cell (hexagon or pentagon) in radians^2 */
DECLSPEC H3Error H3_EXPORT(cellAreaRads2)(H3Index h, double *out);
/** @brief exact area for a specific cell (hexagon or pentagon) in kilometers^2
*/
DECLSPEC H3Error H3_EXPORT(cellAreaKm2)(H3Index h, double *out);
/** @brief exact area for a specific cell (hexagon or pentagon) in meters^2 */
DECLSPEC H3Error H3_EXPORT(cellAreaM2)(H3Index h, double *out);
/** @} */
/** @defgroup getHexagonEdgeLengthAvg getHexagonEdgeLengthAvg
* Functions for getHexagonEdgeLengthAvg
* @{
*/
/** @brief average hexagon edge length in kilometers (excludes pentagons) */
DECLSPEC H3Error H3_EXPORT(getHexagonEdgeLengthAvgKm)(int res, double *out);
/** @brief average hexagon edge length in meters (excludes pentagons) */
DECLSPEC H3Error H3_EXPORT(getHexagonEdgeLengthAvgM)(int res, double *out);
/** @} */
/** @defgroup edgeLength edgeLength
* Functions for edgeLength
* @{
*/
/** @brief exact length for a specific directed edge in radians*/
DECLSPEC H3Error H3_EXPORT(edgeLengthRads)(H3Index edge, double *length);
/** @brief exact length for a specific directed edge in kilometers*/
DECLSPEC H3Error H3_EXPORT(edgeLengthKm)(H3Index edge, double *length);
/** @brief exact length for a specific directed edge in meters*/
DECLSPEC H3Error H3_EXPORT(edgeLengthM)(H3Index edge, double *length);
/** @} */
/** @defgroup getNumCells getNumCells
* Functions for getNumCells
* @{
*/
/** @brief number of cells (hexagons and pentagons) for a given resolution
*
* It works out to be `2 + 120*7^r` for resolution `r`.
*
* # Mathematical notes
*
* Let h(n) be the number of children n levels below
* a single *hexagon*.
*
* Then h(n) = 7^n.
*
* Let p(n) be the number of children n levels below
* a single *pentagon*.
*
* Then p(0) = 1, and p(1) = 6, since each pentagon
* has 5 hexagonal immediate children and 1 pentagonal
* immediate child.
*
* In general, we have the recurrence relation
*
* p(n) = 5*h(n-1) + p(n-1)
* = 5*7^(n-1) + p(n-1).
*
* Working through the recurrence, we get that
*
* p(n) = 1 + 5*\sum_{k=1}^n 7^{k-1}
* = 1 + 5*(7^n - 1)/6,
*
* using the closed form for a geometric series.
*
* Using the closed forms for h(n) and p(n), we can
* get a closed form for the total number of cells
* at resolution r:
*
* c(r) = 12*p(r) + 110*h(r)
* = 2 + 120*7^r.
*
*
* @param res H3 cell resolution
*
* @return number of cells at resolution `res`
*/
DECLSPEC H3Error H3_EXPORT(getNumCells)(int res, int64_t *out);
/** @} */
/** @defgroup getRes0Cells getRes0Cells
* Functions for getRes0Cells
* @{
*/
/** @brief returns the number of resolution 0 cells (hexagons and pentagons) */
DECLSPEC int H3_EXPORT(res0CellCount)(void);
/** @brief provides all base cells in H3Index format*/
DECLSPEC H3Error H3_EXPORT(getRes0Cells)(H3Index *out);
/** @} */
/** @defgroup getPentagons getPentagons
* Functions for getPentagons
* @{
*/
/** @brief returns the number of pentagons per resolution */
DECLSPEC int H3_EXPORT(pentagonCount)(void);
/** @brief generates all pentagons at the specified resolution */
DECLSPEC H3Error H3_EXPORT(getPentagons)(int res, H3Index *out);
/** @} */
/** @defgroup getResolution getResolution
* Functions for getResolution
* @{
*/
/** @brief returns the resolution of the provided H3 index
* Works on both cells and directed edges. */
DECLSPEC int H3_EXPORT(getResolution)(H3Index h);
/** @} */
/** @defgroup getBaseCellNumber getBaseCellNumber
* Functions for getBaseCellNumber
* @{
*/
/** @brief returns the base cell "number" (0 to 121) of the provided H3 cell
*
* Note: Technically works on H3 edges, but will return base cell of the
* origin cell. */
DECLSPEC int H3_EXPORT(getBaseCellNumber)(H3Index h);
/** @} */
/** @defgroup getIndexDigit getIndexDigit
* Functions for getIndexDigit
* @{
*/
/** @brief returns the indexing digit of the provided H3 cell at a given
* resolution
*
* Indexing digits are 1-indexed beginning with the digit for resolution 1. */
DECLSPEC H3Error H3_EXPORT(getIndexDigit)(H3Index h, int res, int *out);
/** @} */
/** @defgroup constructCell constructCell
* Functions for constructCell
* @{
*/
/** @brief create a cell from its components
* Only allows for constructing valid H3 cells.
**/
DECLSPEC H3Error H3_EXPORT(constructCell)(int res, int baseCellNumber,
const int *digits, H3Index *out);
/** @} */
/** @defgroup stringToH3 stringToH3
* Functions for stringToH3
* @{
*/
/** @brief converts the canonical string format to H3Index format */
DECLSPEC H3Error H3_EXPORT(stringToH3)(const char *str, H3Index *out);
/** @} */
/** @defgroup h3ToString h3ToString
* Functions for h3ToString
* @{
*/
/** @brief converts an H3Index to a canonical string */
DECLSPEC H3Error H3_EXPORT(h3ToString)(H3Index h, char *str, size_t sz);
/** @} */
/** @defgroup isValidCell isValidCell
* Functions for isValidCell
* @{
*/
/** @brief confirms if an H3Index is a valid cell (hexagon or pentagon)
* In particular, returns 0 (False) for H3 directed edges or invalid data
*/
DECLSPEC int H3_EXPORT(isValidCell)(H3Index h);
/** @} */
/** @defgroup isValidIndex isValidIndex
* Functions for isValidIndex
* @{
*/
/** @brief confirms if an H3Index is valid for any mode (cell, directed edge, or
* vertex) Returns 1 if the H3 index is valid for any supported type, 0
* otherwise
*/
DECLSPEC int H3_EXPORT(isValidIndex)(H3Index h);
/** @} */
/** @defgroup cellToParent cellToParent
* Functions for cellToParent
* @{
*/
/** @brief returns the parent (or grandparent, etc) cell of the given cell
*/
DECLSPEC H3Error H3_EXPORT(cellToParent)(H3Index h, int parentRes,
H3Index *parent);
/** @} */
/** @defgroup cellToChildren cellToChildren
* Functions for cellToChildren
* @{
*/
/** @brief determines the exact number of children (or grandchildren, etc)
* that would be returned for the given cell */
DECLSPEC H3Error H3_EXPORT(cellToChildrenSize)(H3Index h, int childRes,
int64_t *out);
/** @brief provides the children (or grandchildren, etc) of the given cell */
DECLSPEC H3Error H3_EXPORT(cellToChildren)(H3Index h, int childRes,
H3Index *children);
/** @} */
/** @defgroup cellToCenterChild cellToCenterChild
* Functions for cellToCenterChild
* @{
*/
/** @brief returns the center child of the given cell at the specified
* resolution */
DECLSPEC H3Error H3_EXPORT(cellToCenterChild)(H3Index h, int childRes,
H3Index *child);
/** @} */
/** @defgroup cellToChildPos cellToChildPos
* Functions for cellToChildPos
* @{
*/
/** @brief Returns the position of the cell within an ordered list of all
* children of the cell's parent at the specified resolution */
DECLSPEC H3Error H3_EXPORT(cellToChildPos)(H3Index child, int parentRes,
int64_t *out);
/** @} */
/** @defgroup childPosToCell childPosToCell
* Functions for childPosToCell
* @{
*/
/** @brief Returns the child cell at a given position within an ordered list of
* all children at the specified resolution */
DECLSPEC H3Error H3_EXPORT(childPosToCell)(int64_t childPos, H3Index parent,
int childRes, H3Index *child);
/** @} */
/** @defgroup compactCells compactCells
* Functions for compactCells
* @{
*/
/** @brief compacts the given set of hexagons as best as possible */
DECLSPEC H3Error H3_EXPORT(compactCells)(const H3Index *h3Set,
H3Index *compactedSet,
const int64_t numHexes);
/** @} */
/** @defgroup uncompactCells uncompactCells
* Functions for uncompactCells
* @{
*/
/** @brief determines the exact number of hexagons that will be uncompacted
* from the compacted set */
DECLSPEC H3Error H3_EXPORT(uncompactCellsSize)(const H3Index *compactedSet,
const int64_t numCompacted,
const int res, int64_t *out);
/** @brief uncompacts the compacted hexagon set */
DECLSPEC H3Error H3_EXPORT(uncompactCells)(const H3Index *compactedSet,
const int64_t numCompacted,
H3Index *outSet,
const int64_t numOut, const int res);
/** @} */
/** @defgroup isResClassIII isResClassIII
* Functions for isResClassIII
* @{
*/
/** @brief determines if a hexagon is Class III (or Class II) */
DECLSPEC int H3_EXPORT(isResClassIII)(H3Index h);
/** @} */
/** @defgroup isPentagon isPentagon
* Functions for isPentagon
* @{
*/
/** @brief determines if an H3 cell is a pentagon */
DECLSPEC int H3_EXPORT(isPentagon)(H3Index h);
/** @} */
/** @defgroup getIcosahedronFaces getIcosahedronFaces
* Functions for getIcosahedronFaces
* @{
*/
/** @brief Max number of icosahedron faces intersected by an index */
DECLSPEC H3Error H3_EXPORT(maxFaceCount)(H3Index h3, int *out);
/** @brief Find all icosahedron faces intersected by a given H3 index */
DECLSPEC H3Error H3_EXPORT(getIcosahedronFaces)(H3Index h3, int *out);
/** @} */
/** @defgroup areNeighborCells areNeighborCells
* Functions for areNeighborCells
* @{
*/
/** @brief returns whether or not the provided hexagons border */
DECLSPEC H3Error H3_EXPORT(areNeighborCells)(H3Index origin,
H3Index destination, int *out);
/** @} */
/** @defgroup cellsToDirectedEdge cellsToDirectedEdge
* Functions for cellsToDirectedEdge
* @{
*/
/** @brief returns the directed edge H3Index for the specified origin and
* destination */
DECLSPEC H3Error H3_EXPORT(cellsToDirectedEdge)(H3Index origin,
H3Index destination,
H3Index *out);
/** @} */
/** @defgroup isValidDirectedEdge isValidDirectedEdge
* Functions for isValidDirectedEdge
* @{
*/
/** @brief returns whether the H3Index is a valid directed edge */
DECLSPEC int H3_EXPORT(isValidDirectedEdge)(H3Index edge);
/** @} */
/** @defgroup getDirectedEdgeOrigin \
* getDirectedEdgeOrigin
* Functions for getDirectedEdgeOrigin
* @{
*/
/** @brief Returns the origin hexagon H3Index from the directed edge
* H3Index */
DECLSPEC H3Error H3_EXPORT(getDirectedEdgeOrigin)(H3Index edge, H3Index *out);
/** @} */
/** @defgroup getDirectedEdgeDestination \
* getDirectedEdgeDestination
* Functions for getDirectedEdgeDestination
* @{
*/
/** @brief Returns the destination hexagon H3Index from the directed edge
* H3Index */
DECLSPEC H3Error H3_EXPORT(getDirectedEdgeDestination)(H3Index edge,
H3Index *out);
/** @} */
/** @defgroup directedEdgeToCells \
* directedEdgeToCells
* Functions for directedEdgeToCells
* @{
*/
/** @brief Returns the origin and destination hexagons from the directed
* edge H3Index */
DECLSPEC H3Error H3_EXPORT(directedEdgeToCells)(H3Index edge,
H3Index *originDestination);
/** @} */
/** @defgroup originToDirectedEdges \
* originToDirectedEdges
* Functions for originToDirectedEdges
* @{
*/
/** @brief Returns the 6 (or 5 for pentagons) edges associated with the H3Index
*/
DECLSPEC H3Error H3_EXPORT(originToDirectedEdges)(H3Index origin,
H3Index *edges);
/** @} */
/** @defgroup directedEdgeToBoundary directedEdgeToBoundary
* Functions for directedEdgeToBoundary
* @{
*/
/** @brief Returns the CellBoundary containing the coordinates of the edge */
DECLSPEC H3Error H3_EXPORT(directedEdgeToBoundary)(H3Index edge,
CellBoundary *gb);
/** @} */
/** @defgroup reverseDirectedEdge reverseDirectedEdge
* Functions for reverseDirectedEdge
* @{
*/
/** @brief Returns the directed edge with origin and destination cells reversed
*/
DECLSPEC H3Error H3_EXPORT(reverseDirectedEdge)(H3Index edge, H3Index *out);
/** @} */
/** @defgroup cellToVertex cellToVertex
* Functions for cellToVertex
* @{
*/
/** @brief Returns a single vertex for a given cell, as an H3 index */
DECLSPEC H3Error H3_EXPORT(cellToVertex)(H3Index origin, int vertexNum,
H3Index *out);
/** @} */
/** @defgroup cellToVertexes cellToVertexes
* Functions for cellToVertexes
* @{
*/
/** @brief Returns all vertexes for a given cell, as H3 indexes */
DECLSPEC H3Error H3_EXPORT(cellToVertexes)(H3Index origin, H3Index *vertexes);
/** @} */
/** @defgroup vertexToLatLng vertexToLatLng
* Functions for vertexToLatLng
* @{
*/
/** @brief Returns a single vertex for a given cell, as an H3 index */
DECLSPEC H3Error H3_EXPORT(vertexToLatLng)(H3Index vertex, LatLng *point);
/** @} */
/** @defgroup isValidVertex isValidVertex
* Functions for isValidVertex
* @{
*/
/** @brief Whether the input is a valid H3 vertex */
DECLSPEC int H3_EXPORT(isValidVertex)(H3Index vertex);
/** @} */
/** @defgroup gridDistance gridDistance
* Functions for gridDistance
* @{
*/
/** @brief Returns grid distance between two indexes */
DECLSPEC H3Error H3_EXPORT(gridDistance)(H3Index origin, H3Index h3,
int64_t *distance);
/** @} */
/** @defgroup gridPathCells gridPathCells
* Functions for gridPathCells
* @{
*/
/** @brief Number of indexes in a line connecting two indexes */
DECLSPEC H3Error H3_EXPORT(gridPathCellsSize)(H3Index start, H3Index end,
int64_t *size);
/** @brief Line of h3 indexes connecting two indexes */
DECLSPEC H3Error H3_EXPORT(gridPathCells)(H3Index start, H3Index end,
H3Index *out);
/** @} */
/** @defgroup cellToLocalIj cellToLocalIj
* Functions for cellToLocalIj
* @{
*/
/** @brief Returns two dimensional coordinates for the given index */
DECLSPEC H3Error H3_EXPORT(cellToLocalIj)(H3Index origin, H3Index h3,
uint32_t mode, CoordIJ *out);
/** @} */
/** @defgroup localIjToCell localIjToCell
* Functions for localIjToCell
* @{
*/
/** @brief Returns index for the given two dimensional coordinates */
DECLSPEC H3Error H3_EXPORT(localIjToCell)(H3Index origin, const CoordIJ *ij,
uint32_t mode, H3Index *out);
/** @} */
#ifdef __cplusplus
} // extern "C"
#endif
#endif
@@ -0,0 +1,191 @@
# cython: c_string_type=unicode, c_string_encoding=utf8
from cpython cimport bool
from libc.stdint cimport uint32_t, uint64_t, int64_t
ctypedef object H3str
cdef extern from 'h3api.h':
cdef int H3_VERSION_MAJOR
cdef int H3_VERSION_MINOR
cdef int H3_VERSION_PATCH
ctypedef uint64_t H3int 'H3Index'
ctypedef uint32_t H3Error
ctypedef enum H3ErrorCodes:
E_SUCCESS = 0
E_FAILED = 1
E_DOMAIN = 2
E_LATLNG_DOMAIN = 3
E_RES_DOMAIN = 4
E_CELL_INVALID = 5
E_DIR_EDGE_INVALID = 6
E_UNDIR_EDGE_INVALID = 7
E_VERTEX_INVALID = 8
E_PENTAGON = 9
E_DUPLICATE_INPUT = 10
E_NOT_NEIGHBORS = 11
E_RES_MISMATCH = 12
E_MEMORY_ALLOC = 13
E_MEMORY_BOUNDS = 14
E_OPTION_INVALID = 15
E_INDEX_INVALID = 16
E_BASE_CELL_DOMAIN = 17
E_DIGIT_DOMAIN = 18
E_DELETED_DIGIT = 19
H3_ERROR_END # sentinel value
ctypedef struct LatLng:
double lat # in radians
double lng # in radians
ctypedef struct CellBoundary:
int num_verts 'numVerts'
LatLng verts[10] # MAX_CELL_BNDRY_VERTS
ctypedef struct CoordIJ:
int i
int j
ctypedef struct GeoLoop:
int numVerts
LatLng *verts
ctypedef struct GeoPolygon:
GeoLoop geoloop
int numHoles
GeoLoop *holes
int isValidCell(H3int h) nogil
int isPentagon(H3int h) nogil
int isResClassIII(H3int h) nogil
int isValidDirectedEdge(H3int edge) nogil
int isValidVertex(H3int v) nogil
int isValidIndex(H3int h) nogil
double degsToRads(double degrees) nogil
double radsToDegs(double radians) nogil
int getResolution(H3int h) nogil
int getBaseCellNumber(H3int h) nogil
H3Error getIndexDigit(H3int h, int res, int *out) nogil
H3Error constructCell(int res, int baseCellNumber, const int *digits, H3int *out) nogil
H3Error latLngToCell(const LatLng *g, int res, H3int *out) nogil
H3Error cellToLatLng(H3int h, LatLng *) nogil
H3Error gridDistance(H3int h1, H3int h2, int64_t *distance) nogil
H3Error cellToVertex(H3int cell, int vertexNum, H3int *out) nogil
H3Error cellToVertexes(H3int cell, H3int *vertexes) nogil
H3Error vertexToLatLng(H3int vertex, LatLng *coord) nogil
H3Error maxGridDiskSize(int k, int64_t *out) nogil # num/out/N?
H3Error gridDisk(H3int h, int k, H3int *out) nogil
H3Error cellToParent( H3int h, int parentRes, H3int *parent) nogil
H3Error cellToCenterChild(H3int h, int childRes, H3int *child) nogil
H3Error cellToChildPos(H3int child, int parentRes, int64_t *out) nogil
H3Error childPosToCell(int64_t childPos, H3int parent, int childRes, H3int *child) nogil
H3Error cellToChildrenSize(H3int h, int childRes, int64_t *num) nogil # num/out/N?
H3Error cellToChildren( H3int h, int childRes, H3int *children) nogil
H3Error compactCells(
const H3int *cells_u,
H3int *cells_c,
const int num_u
) nogil
H3Error uncompactCellsSize(
const H3int *cells_c,
const int64_t num_c,
const int res,
int64_t *num_u
) nogil
H3Error uncompactCells(
const H3int *cells_c,
const int num_c,
H3int *cells_u,
const int num_u,
const int res
) nogil
H3Error getNumCells(int res, int64_t *out) nogil
int pentagonCount() nogil
int res0CellCount() nogil
H3Error getPentagons(int res, H3int *out) nogil
H3Error getRes0Cells(H3int *out) nogil
H3Error gridPathCellsSize(H3int start, H3int end, int64_t *size) nogil
H3Error gridPathCells(H3int start, H3int end, H3int *out) nogil
H3Error getHexagonAreaAvgKm2(int res, double *out) nogil
H3Error getHexagonAreaAvgM2(int res, double *out) nogil
H3Error cellAreaRads2(H3int h, double *out) nogil
H3Error cellAreaKm2(H3int h, double *out) nogil
H3Error cellAreaM2(H3int h, double *out) nogil
H3Error maxFaceCount(H3int h, int *out) nogil
H3Error getIcosahedronFaces(H3int h3, int *out) nogil
H3Error cellToLocalIj(H3int origin, H3int h3, uint32_t mode, CoordIJ *out) nogil
H3Error localIjToCell(H3int origin, const CoordIJ *ij, uint32_t mode, H3int *out) nogil
H3Error gridDiskDistances(H3int origin, int k, H3int *out, int *distances) nogil
H3Error gridRing(H3int origin, int k, H3int *out) nogil
H3Error gridRingUnsafe(H3int origin, int k, H3int *out) nogil
H3Error areNeighborCells(H3int origin, H3int destination, int *out) nogil
H3Error cellsToDirectedEdge(H3int origin, H3int destination, H3int *out) nogil
H3Error getDirectedEdgeOrigin(H3int edge, H3int *out) nogil
H3Error getDirectedEdgeDestination(H3int edge, H3int *out) nogil
H3Error originToDirectedEdges(H3int origin, H3int *edges) nogil
# todo: directedEdgeToCells
H3Error getHexagonEdgeLengthAvgKm(int res, double *out) nogil
H3Error getHexagonEdgeLengthAvgM(int res, double *out) nogil
H3Error edgeLengthRads(H3int edge, double *out) nogil
H3Error edgeLengthKm(H3int edge, double *out) nogil
H3Error edgeLengthM(H3int edge, double *out) nogil
H3Error cellToBoundary(H3int h3, CellBoundary *gp) nogil
H3Error directedEdgeToBoundary(H3int edge, CellBoundary *gb) nogil
double greatCircleDistanceRads(const LatLng *a, const LatLng *b) nogil
double greatCircleDistanceKm(const LatLng *a, const LatLng *b) nogil
double greatCircleDistanceM(const LatLng *a, const LatLng *b) nogil
H3Error maxPolygonToCellsSize(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count)
H3Error polygonToCells(const GeoPolygon *geoPolygon, int res, uint32_t flags, H3int *out)
H3Error maxPolygonToCellsSizeExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t *count)
H3Error polygonToCellsExperimental(const GeoPolygon *geoPolygon, int res, uint32_t flags, uint64_t sz, H3int *out)
ctypedef struct GeoMultiPolygon:
int numPolygons
GeoPolygon *polygons
# int hexRange(H3int origin, int k, H3int *out)
# int hexRangeDistances(H3int origin, int k, H3int *out, int *distances)
# int hexRanges(H3int *h3Set, int length, int k, H3int *out)
# void h3SetToLinkedGeo(const H3int *h3Set, const int numCells, LinkedGeoPolygon *out)
# void destroyLinkedPolygon(LinkedGeoPolygon *polygon)
# H3int stringToH3(const char *str)
# void h3ToString(H3int h, char *str, size_t sz)
# void getH3intesFromUnidirectionalEdge(H3int edge, H3int *originDestination)
# cellsToMultiPolygon and destroyGeoMultiPolygon are temporarily excluded
# from the public API, so we use an internal header until they're moved
# back into h3api.h
cdef extern from 'cellsToMultiPoly.h':
H3Error cellsToMultiPolygon(const H3int *cells, const int64_t numCells, GeoMultiPolygon *out)
void destroyGeoMultiPolygon(GeoMultiPolygon *mpoly)
@@ -0,0 +1,7 @@
from .h3lib cimport H3int
cpdef H3int latlng_to_cell(double lat, double lng, int res) except 1
cpdef (double, double) cell_to_latlng(H3int h) except *
cpdef double great_circle_distance(
double lat1, double lng1,
double lat2, double lng2, unit=*) except -1
@@ -0,0 +1,325 @@
from libc.stdint cimport uint64_t
cimport h3lib
from h3lib cimport bool, H3int
from .util cimport (
check_cell,
check_edge,
check_res,
deg2coord,
coord2deg
)
from .error_system cimport check_for_error
from .memory cimport H3MemoryManager
# TODO: We might be OK with taking the GIL for the functions in this module
from libc.stdlib cimport (
# malloc as h3_malloc, # not used
calloc as h3_calloc,
realloc as h3_realloc,
free as h3_free,
)
cpdef H3int latlng_to_cell(double lat, double lng, int res) except 1:
cdef:
h3lib.LatLng c
H3int out
c = deg2coord(lat, lng)
check_for_error(
h3lib.latLngToCell(&c, res, &out)
)
return out
cpdef (double, double) cell_to_latlng(H3int h) except *:
"""Map an H3 cell into its centroid geo-coordinate (lat/lng)"""
cdef:
h3lib.LatLng c
check_cell(h)
# todo: think about: if you give this an invalid cell, should it still return a lat/lng?
# idea: safe and unsafe APIs?
check_for_error(
h3lib.cellToLatLng(h, &c)
)
return coord2deg(c)
cdef h3lib.GeoLoop make_geoloop(latlngs) except *:
"""
The returned `GeoLoop` must be freed with a call to `free_geoloop`.
Parameters
----------
latlngs : list or tuple
GeoLoop: A sequence of >= 3 (lat, lng) pairs where the last
element may or may not be same as the first (to form a closed loop).
The order of the pairs may be either clockwise or counterclockwise.
"""
cdef:
h3lib.GeoLoop gl
gl.numVerts = len(latlngs)
# todo: need for memory management
# can automatically free?
gl.verts = <h3lib.LatLng*> h3_calloc(gl.numVerts, sizeof(h3lib.LatLng))
for i, (lat, lng) in enumerate(latlngs):
gl.verts[i] = deg2coord(lat, lng)
return gl
cdef free_geoloop(h3lib.GeoLoop* gl):
h3_free(gl.verts)
gl.verts = NULL
cdef class GeoPolygon:
cdef:
h3lib.GeoPolygon gp
def __cinit__(self, outer, holes=None):
"""
Parameters
----------
outer : list or tuple
GeoLoop
A GeoLoop is a sequence of >= 3 (lat, lng) pairs where the last
element may or may not be same as the first (to form a closed loop).
The order of the pairs may be either clockwise or counterclockwise.
holes : list or tuple
A sequence of GeoLoops
"""
if holes is None:
holes = []
self.gp.geoloop = make_geoloop(outer)
self.gp.numHoles = len(holes)
self.gp.holes = NULL
if len(holes) > 0:
self.gp.holes = <h3lib.GeoLoop*> h3_calloc(len(holes), sizeof(h3lib.GeoLoop))
for i, hole in enumerate(holes):
self.gp.holes[i] = make_geoloop(hole)
def __dealloc__(self):
free_geoloop(&self.gp.geoloop)
for i in range(self.gp.numHoles):
free_geoloop(&self.gp.holes[i])
h3_free(self.gp.holes)
def polygon_to_cells(outer, int res, holes=None):
""" Get the set of cells whose center is contained in a polygon.
The polygon is defined similarity to the GeoJson standard, with an exterior
`outer` ring of lat/lng points, and a list of `holes`, each of which are also
rings of lat/lng points.
Each ring may be in clockwise or counter-clockwise order
(right-hand rule or not), and may or may not be a closed loop (where the last
element is equal to the first).
The GeoJSON spec requires the right-hand rule and a closed loop, but
this function relaxes those constraints.
Unlike the GeoJson standard, the elements of the lat/lng pairs of each
ring are in lat/lng order, instead of lng/lat order.
We'll handle translation to different formats in the Python code,
rather than the Cython code.
Parameters
----------
outer : list or tuple
A ring given by a sequence of lat/lng pairs.
res : int
The resolution of the output hexagons
holes : list or tuple
A collection of rings, each given by a sequence of lat/lng pairs.
These describe any the "holes" in the polygon.
"""
cdef:
uint64_t n
check_res(res)
if not outer:
return H3MemoryManager(0).to_mv()
gp = GeoPolygon(outer, holes=holes)
check_for_error(
h3lib.maxPolygonToCellsSize(&gp.gp, res, 0, &n)
)
hmm = H3MemoryManager(n)
check_for_error(
h3lib.polygonToCells(&gp.gp, res, 0, hmm.ptr)
)
mv = hmm.to_mv()
return mv
def polygons_to_cells(polygons, int res):
mvs = [
polygon_to_cells(outer=poly.outer, res=res, holes=poly.holes)
for poly in polygons
]
n = sum(map(len, mvs))
hmm = H3MemoryManager(n)
# probably super inefficient, but it is working!
# tood: move this to C
k = 0
for mv in mvs:
for v in mv:
hmm.ptr[k] = v
k += 1
return hmm.to_mv()
def polygon_to_cells_experimental(outer, int res, int flag, holes=None):
""" Get the set of cells whose center is contained in a polygon.
The polygon is defined similarity to the GeoJson standard, with an exterior
`outer` ring of lat/lng points, and a list of `holes`, each of which are also
rings of lat/lng points.
Each ring may be in clockwise or counter-clockwise order
(right-hand rule or not), and may or may not be a closed loop (where the last
element is equal to the first).
The GeoJSON spec requires the right-hand rule and a closed loop, but
this function relaxes those constraints.
Unlike the GeoJson standard, the elements of the lat/lng pairs of each
ring are in lat/lng order, instead of lng/lat order.
We'll handle translation to different formats in the Python code,
rather than the Cython code.
Parameters
----------
outer : list or tuple
A ring given by a sequence of lat/lng pairs.
res : int
The resolution of the output hexagons
flag : int
Polygon to cells flag, such as containment mode.
holes : list or tuple
A collection of rings, each given by a sequence of lat/lng pairs.
These describe any the "holes" in the polygon.
"""
cdef:
uint64_t n
check_res(res)
if not outer:
return H3MemoryManager(0).to_mv()
gp = GeoPolygon(outer, holes=holes)
check_for_error(
h3lib.maxPolygonToCellsSizeExperimental(&gp.gp, res, flag, &n)
)
hmm = H3MemoryManager(n)
check_for_error(
h3lib.polygonToCellsExperimental(&gp.gp, res, flag, n, hmm.ptr)
)
mv = hmm.to_mv()
return mv
def polygons_to_cells_experimental(polygons, int res, int flag):
mvs = [
polygon_to_cells_experimental(outer=poly.outer, res=res, holes=poly.holes, flag=flag)
for poly in polygons
]
n = sum(map(len, mvs))
hmm = H3MemoryManager(n)
# probably super inefficient, but it is working!
# tood: move this to C
k = 0
for mv in mvs:
for v in mv:
hmm.ptr[k] = v
k += 1
return hmm.to_mv()
def cell_to_boundary(H3int h):
"""Compose an array of geo-coordinates that outlines a hexagonal cell"""
cdef:
h3lib.CellBoundary gb
check_cell(h)
h3lib.cellToBoundary(h, &gb)
verts = tuple(
coord2deg(gb.verts[i])
for i in range(gb.num_verts)
)
return verts
def directed_edge_to_boundary(H3int edge):
""" Returns the CellBoundary containing the coordinates of the edge
"""
cdef:
h3lib.CellBoundary gb
check_edge(edge)
h3lib.directedEdgeToBoundary(edge, &gb)
# todo: move this verts transform into the CellBoundary object
verts = tuple(
coord2deg(gb.verts[i])
for i in range(gb.num_verts)
)
return verts
cpdef double great_circle_distance(
double lat1, double lng1,
double lat2, double lng2, unit='km') except -1:
a = deg2coord(lat1, lng1)
b = deg2coord(lat2, lng2)
if unit == 'rads':
d = h3lib.greatCircleDistanceRads(&a, &b)
elif unit == 'km':
d = h3lib.greatCircleDistanceKm(&a, &b)
elif unit == 'm':
d = h3lib.greatCircleDistanceM(&a, &b)
else:
raise ValueError('Unknown unit: {}'.format(unit))
return d
@@ -0,0 +1,12 @@
from .h3lib cimport H3int
cdef class H3MemoryManager:
cdef:
size_t n
H3int* ptr
cdef H3int[:] to_mv(self)
cdef H3int[:] to_mv_keep_zeros(self)
cdef int[:] int_mv(size_t n)
cpdef H3int[:] iter_to_mv(cells)
@@ -0,0 +1,248 @@
from cython.view cimport array
from .h3lib cimport H3int
"""
### Memory allocation options
We have a few options for the memory allocation functions.
There's a trade-off between using the Python allocators which let Python
track memory usage and offers some optimizations vs the system
allocators, which do not need to acquire the GIL.
"""
"""
System allocation functions. These do not acquire the GIL.
"""
from libc.stdlib cimport (
# malloc as h3_malloc, # not used
calloc as h3_calloc,
realloc as h3_realloc,
free as h3_free,
)
"""
PyMem_Raw* functions should just be wrappers around system allocators
also given in libc.stdlib. These functions do not acquire the GIL.
Note that these do not have a calloc function until py 3.5 and Cython 3.0,
so we would need to zero-out memory manually.
https://python.readthedocs.io/en/stable/c-api/memory.html#raw-memory-interface
"""
# from cpython.mem cimport (
# PyMem_RawMalloc as h3_malloc,
# # PyMem_RawCalloc as h3_calloc, # only in Python >=3.5 (and Cython >=3.0?)
# PyMem_RawRealloc as h3_realloc,
# PyMem_RawFree as h3_free,
# )
"""
These functions use the Python allocator (instead of the system allocator),
which offers some optimizations for Python, and allows Python to track
memory usage. However, these functions must acquire the GIL.
Note that these do not have a calloc function until py 3.5 and Cython 3.0,
so we would need to zero-out memory manually.
https://cython.readthedocs.io/en/stable/src/tutorial/memory_allocation.html
https://python.readthedocs.io/en/stable/c-api/memory.html#memory-interface
"""
# from cpython.mem cimport (
# PyMem_Malloc as h3_malloc,
# # PyMem_Calloc as h3_calloc, # only in Python >=3.5 (and Cython >=3.0?)
# PyMem_Realloc as h3_realloc,
# PyMem_Free as h3_free,
# )
cdef size_t move_nonzeros(H3int* a, size_t n):
""" Move nonzero elements to front of array `a` of length `n`.
Return the number of nonzero elements.
Loop invariant: Everything *before* `i` or *after* `j` is "done".
Move `i` and `j` inwards until they equal, and exit.
You can move `i` forward until there's a zero in front of it.
You can move `j` backward until there's a nonzero to the left of it.
Anything to the right of `j` is "junk" that can be reallocated.
| a | b | 0 | c | d | ... |
^ ^
i j
| a | b | d | c | d | ... |
^ ^
i j
"""
cdef:
size_t i = 0
size_t j = n
while i < j:
if a[j-1] == 0:
j -= 1
continue
if a[i] != 0:
i += 1
continue
# if we're here, we know:
# a[i] == 0
# a[j-1] != 0
# i < j
# so we can swap! (actually, move a[j-1] -> a[i])
a[i] = a[j-1]
j -= 1
return i
cdef H3int[:] empty_memory_view():
# todo: get rid of this?
# there's gotta be a better way to do this...
# create an empty cython.view.array?
cdef:
H3int a[1]
return (<H3int[:]>a)[:0]
cdef _remove_zeros(H3MemoryManager x):
x.n = move_nonzeros(x.ptr, x.n)
if x.n == 0:
h3_free(x.ptr)
x.ptr = NULL
else:
x.ptr = <H3int*> h3_realloc(x.ptr, x.n*sizeof(H3int))
if not x.ptr:
raise MemoryError()
cdef H3int[:] _copy_to_mv(const H3int* ptr, size_t n):
cdef:
array arr
arr = <H3int[:n]> ptr
arr.callback_free_data = h3_free
return arr
cdef H3int[:] _create_mv(H3MemoryManager x):
if x.n == 0:
h3_free(x.ptr)
x.ptr = NULL
mv = empty_memory_view()
else:
mv = _copy_to_mv(x.ptr, x.n)
# responsibility for the memory moves from this object to the array/memoryview
x.ptr = NULL
x.n = 0
return mv
"""
TODO: The not None declaration for the argument automatically rejects None values as input, which would otherwise be allowed. The reason why None is allowed by default is that it is conveniently used for return arguments:
https://cython.readthedocs.io/en/latest/src/userguide/memoryviews.html#syntax
TODO: potential optimization: https://cython.readthedocs.io/en/latest/src/userguide/memoryviews.html#performance-disabling-initialization-checks
## future improvements:
- abolish any appearance of &thing[0]. (i.e., identical interfaces)
- can i make the interface for all these memory views identical?
"""
cdef class H3MemoryManager:
"""
Cython object in charge of allocating and freeing memory for arrays
of H3 indexes.
Initially allocates memory and provides access through `self.ptr` and
`self.n`.
The `to_mv()` function removes responsibility for the allocated memory
from this object to a memory view object. A memory view object automatically
deallocates its memory during garbage collection.
If the H3MemoryManager is garbage collected before running `to_mv()`,
it will deallocate its memory itself.
This pattern is useful for a few reasons:
- provide convenient access to the raw memory pointer and length for passing
to h3lib functions
- remove zeroes from the array output (some h3lib functions may return
results with zeros/H3NULL values)
- cython and python array types have weird interfaces; memoryviews are
much cleaner
If we find a better way to do these then this class may no longer be
necessary.
TODO: consider a context manager pattern
"""
def __cinit__(self, size_t n):
self.n = n
self.ptr = <H3int*> h3_calloc(self.n, sizeof(H3int))
if not self.ptr:
raise MemoryError()
cdef H3int[:] to_mv_keep_zeros(self):
# todo: this could be a private method
return _create_mv(self)
cdef H3int[:] to_mv(self):
_remove_zeros(self)
return _create_mv(self)
def __dealloc__(self):
# If the memory has been handed off to a memoryview, this pointer
# should be NULL, and deallocing on NULL is fine.
# If the pointer is *not* NULL, then this means the MemoryManager
# has is still responsible for the memory (it hasn't given the memory away to another object).
h3_free(self.ptr)
"""
todo: combine with the H3MemoryManager using fused types?
https://cython.readthedocs.io/en/stable/src/userguide/fusedtypes.html
"""
cdef int[:] int_mv(size_t n):
cdef:
array arr
if n == 0:
raise MemoryError()
else:
ptr = <int*> h3_calloc(n, sizeof(int))
if ptr is NULL:
raise MemoryError()
arr = <int[:n]> ptr
arr.callback_free_data = h3_free
return arr
cpdef H3int[:] iter_to_mv(cells):
""" cells needs to be an iterable that knows its size...
or should we have it match the np.fromiter function, which infers if not available?
"""
cdef:
H3int[:] mv
n = len(cells)
mv = H3MemoryManager(n).to_mv_keep_zeros()
for i,h in enumerate(cells):
mv[i] = h
return mv
@@ -0,0 +1,45 @@
cimport h3lib
from h3lib cimport H3int
from .util cimport check_cell, coord2deg
from .error_system cimport check_for_error
cdef _loop_to_list(const h3lib.GeoLoop *loop):
return [coord2deg(loop.verts[v]) for v in range(loop.numVerts)]
cdef _poly_to_lists(const h3lib.GeoPolygon *poly):
return (
[_loop_to_list(&poly.geoloop)]
+ [_loop_to_list(&poly.holes[h]) for h in range(poly.numHoles)]
)
def _to_multi_polygon(const H3int[:] cells):
cdef:
h3lib.GeoMultiPolygon mpoly
H3int cell
for cell in cells:
check_cell(cell)
check_for_error(
h3lib.cellsToMultiPolygon(&cells[0], len(cells), &mpoly)
)
try:
out = [
_poly_to_lists(&mpoly.polygons[p])
for p in range(mpoly.numPolygons)
]
finally:
h3lib.destroyGeoMultiPolygon(&mpoly)
return out
def cells_to_multi_polygon(const H3int[:] cells):
if len(cells) == 0:
return []
return _to_multi_polygon(cells)
@@ -0,0 +1,14 @@
from .h3lib cimport H3int, H3str, LatLng
cdef LatLng deg2coord(double lat, double lng) nogil
cdef (double, double) coord2deg(LatLng c) nogil
cpdef H3int str_to_int(H3str h) except? 0
cpdef H3str int_to_str(H3int x)
cdef check_cell(H3int h)
cdef check_edge(H3int e)
cdef check_vertex(H3int v)
cdef check_index(H3int h)
cdef check_res(int res)
cdef check_distance(int k)
@@ -0,0 +1,101 @@
from .h3lib cimport (
H3int,
H3str,
isValidCell,
isValidDirectedEdge,
isValidVertex,
isValidIndex,
)
cimport h3lib
from .error_system import (
H3ResDomainError,
H3DomainError,
H3DirEdgeInvalidError,
H3CellInvalidError,
H3VertexInvalidError,
H3IndexInvalidError,
)
cdef h3lib.LatLng deg2coord(double lat, double lng) nogil:
cdef:
h3lib.LatLng c
c.lat = h3lib.degsToRads(lat)
c.lng = h3lib.degsToRads(lng)
return c
cdef (double, double) coord2deg(h3lib.LatLng c) nogil:
return (
h3lib.radsToDegs(c.lat),
h3lib.radsToDegs(c.lng)
)
cpdef basestring c_version():
v = (
h3lib.H3_VERSION_MAJOR,
h3lib.H3_VERSION_MINOR,
h3lib.H3_VERSION_PATCH,
)
return '{}.{}.{}'.format(*v)
cpdef H3int str_to_int(H3str h) except? 0:
return int(h, 16)
cpdef H3str int_to_str(H3int x):
""" Convert H3 integer to hex string representation
Need to be careful in Python 2 because `hex(x)` may return a string
with a trailing `L` character (denoting a "large" integer).
The formatting approach below avoids this.
Also need to be careful about unicode/str differences.
"""
return '{:x}'.format(x)
cdef check_cell(H3int h):
""" Check if valid H3 "cell" (hexagon or pentagon).
Does not check if a valid H3 edge, for example.
Since this function is used by multiple interfaces (int or str),
we want the error message to be informative to the user
in either case.
We use the builtin `hex` function instead of `int_to_str` to
prepend `0x` to indicate that this **integer** representation
is incorrect, but in a format that is easily compared to
`str` inputs.
"""
if isValidCell(h) == 0:
raise H3CellInvalidError('Integer is not a valid H3 cell: {}'.format(hex(h)))
cdef check_edge(H3int e):
if isValidDirectedEdge(e) == 0:
raise H3DirEdgeInvalidError('Integer is not a valid H3 edge: {}'.format(hex(e)))
cdef check_vertex(H3int v):
if isValidVertex(v) == 0:
raise H3VertexInvalidError('Integer is not a valid H3 vertex: {}'.format(hex(v)))
cdef check_index(H3int h):
if isValidIndex(h) == 0:
raise H3IndexInvalidError('Integer is not a valid H3 index: {}'.format(hex(h)))
cdef check_res(int res):
if (res < 0) or (res > 15):
raise H3ResDomainError(res)
cdef check_distance(int k):
if k < 0:
raise H3DomainError(
'Grid distances must be nonnegative. Received: {}'.format(k)
)
@@ -0,0 +1,6 @@
from .h3lib cimport bool, H3int
cpdef H3int cell_to_vertex(H3int h, int vertex_num) except 1
cpdef H3int[:] cell_to_vertexes(H3int h)
cpdef (double, double) vertex_to_latlng(H3int v) except *
cpdef bool is_valid_vertex(H3int v)
@@ -0,0 +1,54 @@
cimport h3lib
from h3lib cimport bool, H3int
from .util cimport (
check_cell,
check_vertex,
coord2deg
)
from .error_system cimport check_for_error
from .memory cimport H3MemoryManager
cpdef H3int cell_to_vertex(H3int h, int vertex_num) except 1:
cdef:
H3int out
check_cell(h)
check_for_error(
h3lib.cellToVertex(h, vertex_num, &out)
)
return out
cpdef H3int[:] cell_to_vertexes(H3int h):
cdef:
H3int out
check_cell(h)
hmm = H3MemoryManager(6)
check_for_error(
h3lib.cellToVertexes(h, hmm.ptr)
)
mv = hmm.to_mv()
return mv
cpdef (double, double) vertex_to_latlng(H3int v) except *:
cdef:
h3lib.LatLng c
check_vertex(v)
check_for_error(
h3lib.vertexToLatLng(v, &c)
)
return coord2deg(c)
cpdef bool is_valid_vertex(H3int v):
return h3lib.isValidVertex(v) == 1
@@ -0,0 +1,338 @@
from abc import ABCMeta, abstractmethod
class H3Shape(metaclass=ABCMeta):
"""
Abstract parent class of ``LatLngPoly`` and ``LatLngMultiPoly``.
"""
@property
@abstractmethod
def __geo_interface__(self):
""" https://github.com/pytest-dev/pytest-cov/issues/428 """
class LatLngPoly(H3Shape):
"""
Container for loops of lat/lng points describing a polygon, possibly with holes.
Attributes
----------
outer : list[tuple[float, float]]
List of lat/lng points describing the outer loop of the polygon
holes : list[list[tuple[float, float]]]
List of loops of lat/lng points describing the holes of the polygon
Examples
--------
A polygon with a single outer ring consisting of 4 points, having no holes:
>>> LatLngPoly(
... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)],
... )
<LatLngPoly: [4]>
The same polygon, but with one hole consisting of 3 points:
>>> LatLngPoly(
... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)],
... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)],
... )
<LatLngPoly: [4/(3,)]>
The same as above, but with one additional hole, made up of 5 points:
>>> LatLngPoly(
... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)],
... [(37.76, -122.51), (37.76, -122.44), (37.81, -122.51)],
... [(37.71, -122.43), (37.71, -122.37), (37.73, -122.37), (37.75, -122.41),
... (37.73, -122.43)],
... )
<LatLngPoly: [4/(3, 5)]>
"""
def __init__(self, outer, *holes):
loops = [outer] + list(holes)
for loop in loops:
if len(loop) in (1, 2):
raise ValueError('Non-empty LatLngPoly loops need at least 3 points.')
point_dimensions = set(map(len, loop))
# empty set is possible for empty polygons, so we check if a subset
if not (point_dimensions <= {2}):
raise ValueError('LatLngPoly only accepts 2D points: lat/lng.')
self.outer = tuple(_open_ring(outer))
self.holes = tuple(
_open_ring(hole)
for hole in holes
)
def __repr__(self):
return '<LatLngPoly: {}>'.format(self.loopcode)
def __len__(self):
"""
Should this be the number of points in the outer loop,
the number of holes (or +1 for the outer loop)?
"""
raise NotImplementedError('No clear definition of length for LatLngPoly.')
@property
def loopcode(self):
""" Short code for describing the length of the outer loop and each hole
Example: ``[382/(18, 6, 6)]`` indicates an outer loop of 382 points,
along with 3 holes with 18, 6, and 6 points, respectively.
Example: ``[15]`` indicates an outer loop of 15 points and no holes.
"""
outer = len(self.outer)
holes = tuple(map(len, self.holes))
outer = str(outer)
if holes:
out = outer + '/' + str(holes)
else:
out = outer
return '[' + out + ']'
@property
def __geo_interface__(self):
ll2 = _polygon_to_LL2(self)
gj_dict = _LL2_to_geojson_dict(ll2)
return gj_dict
class LatLngMultiPoly(H3Shape):
"""
Container for multiple ``LatLngPoly`` polygons.
Attributes
----------
polys : list[LatLngPoly]
List of lat/lng points describing the outer loop of the polygon
"""
def __init__(self, *polys):
self.polys = tuple(polys)
for p in self.polys:
if not isinstance(p, LatLngPoly):
raise ValueError('LatLngMultiPoly requires each input to be an LatLngPoly object, instead got: ' + str(p)) # noqa
def __repr__(self):
out = [p.loopcode for p in self.polys]
out = ', '.join(out)
out = '<LatLngMultiPoly: {}>'.format(out)
return out
def __iter__(self):
return iter(self.polys)
def __len__(self):
""" Give the number of polygons in this multi-polygon.
"""
"""
TODO: Pandas series or dataframe representation changes depending
on if __len__ is defined.
I'd prefer the one that states `LatLngMultiPoly`.
It seems like Pandas is assuming an iterable is best-described
by its elements when choosing the representation.
when __len__ *IS NOT* defined:
0 <LatLngMultiPoly: [368], [20], [6]>
1 <LatLngMultiPoly: [632/(6, 6, 6, 6, 6)], [290/(6,)...
2 <LatLngMultiPoly: [490/(6, 6, 10, 10, 14, 10, 6)],...
3 <LatLngMultiPoly: [344/(6,)], [22], [6], [10], [6]...
4 <LatLngMultiPoly: [382/(18, 6, 6)], [32], [6], [18...
when __len__ *IS* defined:
0 (<LatLngPoly: [368]>, <LatLngPoly: [20]>, <LatLngPoly: [6]>)
1 (<LatLngPoly: [632/(6, 6, 6, 6, 6)]>, <LatLngPoly: [29...
2 (<LatLngPoly: [490/(6, 6, 10, 10, 14, 10, 6)]>, <H...
3 (<LatLngPoly: [344/(6,)]>, <LatLngPoly: [22]>, <LatLngPoly...
4 (<LatLngPoly: [382/(18, 6, 6)]>, <LatLngPoly: [32]>, <...
"""
return len(self.polys)
def __getitem__(self, index):
return self.polys[index]
@property
def __geo_interface__(self):
ll3 = _mpoly_to_LL3(self)
gj_dict = _LL3_to_geojson_dict(ll3)
return gj_dict
"""
Helpers for cells_to_geojson and geojson_to_cells.
Dealing with GeoJSON Polygons and MultiPolygons can be confusing because
there are so many nested lists. To help keep track, we use the following
symbols to denote different levels of nesting.
LL0: lat/lng or lng/lat pair
LL1: list of LL0s
LL2: list of LL1s (i.e., a polygon with holes)
LL3: list of LL2s (i.e., several polygons with holes)
## TODO
- Allow user to specify "container" in `cells_to_geojson`.
- That is, they may want a MultiPolygon even if the output fits in a Polygon
- 'auto', Polygon, MultiPolygon, FeatureCollection, GeometryCollection, ...
"""
def _mpoly_to_LL3(mpoly):
ll3 = tuple(
_polygon_to_LL2(poly)
for poly in mpoly
)
return ll3
def _LL3_to_mpoly(ll3):
polys = [
_LL2_to_polygon(ll2)
for ll2 in ll3
]
mpoly = LatLngMultiPoly(*polys)
return mpoly
def _polygon_to_LL2(poly):
ll2 = [poly.outer] + list(poly.holes)
ll2 = tuple(
_close_ring(_swap_latlng(ll1))
for ll1 in ll2
)
return ll2
def _remove_z(ll1):
ll1 = [(a, b) for a, b, *z in ll1]
return ll1
def _LL2_to_polygon(ll2):
ll2 = [
_remove_z(ll1)
for ll1 in ll2
]
ll2 = [
_swap_latlng(ll1)
for ll1 in ll2
]
h3poly = LatLngPoly(*ll2)
return h3poly
def _LL2_to_geojson_dict(ll2):
gj_dict = {
'type': 'Polygon',
'coordinates': ll2,
}
return gj_dict
def _LL3_to_geojson_dict(ll3):
gj_dict = {
'type': 'MultiPolygon',
'coordinates': ll3,
}
return gj_dict
def _swap_latlng(ll1):
ll1 = tuple(
(b, a) for a, b in ll1
)
return ll1
def _close_ring(ll1):
"""
Idempotent
"""
if ll1 and (ll1[0] != ll1[-1]):
ll1 = tuple(ll1) + (ll1[0],)
return ll1
def _open_ring(ll1):
"""
Idempotent
"""
if ll1 and (ll1[0] == ll1[-1]):
ll1 = ll1[:-1]
return ll1
def geo_to_h3shape(geo):
"""
Translate from ``__geo_interface__`` to H3Shape.
``geo`` either implements ``__geo_interface__`` or is a dict matching the format
Returns
-------
H3Shape
"""
# geo can be dict, a __geo_interface__, a string, LatLngPoly or LatLngMultiPoly
if isinstance(geo, H3Shape):
return geo
if hasattr(geo, '__geo_interface__'):
# get dict
geo = geo.__geo_interface__
assert isinstance(geo, dict) # todo: remove
t = geo['type']
coord = geo['coordinates']
if t == 'Polygon':
ll2 = coord
shape = _LL2_to_polygon(ll2)
elif t == 'MultiPolygon':
ll3 = coord
shape = _LL3_to_mpoly(ll3)
else:
raise ValueError('Unrecognized type: ' + str(t))
return shape
def h3shape_to_geo(h3shape):
"""
Translate from an ``H3Shape`` to a ``__geo_interface__`` dict.
``h3shape`` should be either ``LatLngPoly`` or ``LatLngMultiPoly``
Returns
-------
dict
"""
return h3shape.__geo_interface__
@@ -0,0 +1,3 @@
from importlib import metadata
__version__ = metadata.version(__package__ or __name__)
@@ -0,0 +1,6 @@
# flake8: noqa
from . import basic_int
from . import basic_str
from . import memview_int
from . import numpy_int
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,17 @@
from ... import _cy
def _in_scalar(x):
return x
_out_scalar = _in_scalar
def _in_collection(cells):
it = list(cells)
return _cy.iter_to_mv(it)
_out_collection = list
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,14 @@
from ... import _cy
_in_scalar = _cy.str_to_int
_out_scalar = _cy.int_to_str
def _in_collection(cells):
it = [_cy.str_to_int(h) for h in cells]
return _cy.iter_to_mv(it)
def _out_collection(mv):
return list(_cy.int_to_str(h) for h in mv)
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,8 @@
def _id(x):
return x
_in_scalar = _id
_out_scalar = _id
_in_collection = _id
_out_collection = _id
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,15 @@
def _in_scalar(x):
return x
_out_scalar = _in_scalar
def _in_collection(x):
import numpy as np
# array is copied only if dtype does not match
# `list`s should work, but not `set`s of integers
return np.asarray(x, dtype='uint64')
_out_collection = _in_collection
@@ -0,0 +1,860 @@
/*
* Copyright 2016-2021 Uber Technologies, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** @file h3api.h
* @brief Primary H3 core library entry points.
*
* This file defines the public API of the H3 library. Incompatible changes to
* these functions require the library's major version be increased.
*/
#ifndef H3API_H
#define H3API_H
/*
* Preprocessor code to support renaming (prefixing) the public API.
* All public functions should be wrapped in H3_EXPORT so they can be
* renamed.
*/
#ifdef H3_PREFIX
#define XTJOIN(a, b) a##b
#define TJOIN(a, b) XTJOIN(a, b)
/* export joins the user provided prefix with our exported function name */
#define H3_EXPORT(name) TJOIN(H3_PREFIX, name)
#else
#define H3_EXPORT(name) name
#endif
/* Windows DLL requires attributes indicating what to export */
#if _WIN32 && BUILD_SHARED_LIBS
#if BUILDING_H3
#define DECLSPEC __declspec(dllexport)
#else
#define DECLSPEC __declspec(dllimport)
#endif
#else
#define DECLSPEC
#endif
/* For uint64_t */
#include <stdint.h>
/* For size_t */
#include <stdlib.h>
/*
* H3 is compiled as C, not C++ code. `extern "C"` is needed for C++ code
* to be able to use the library.
*/
#ifdef __cplusplus
extern "C" {
#endif
/** @brief Identifier for an object (cell, edge, etc) in the H3 system.
*
* The H3Index fits within a 64-bit unsigned integer.
*/
typedef uint64_t H3Index;
/**
* Invalid index used to indicate an error from latLngToCell and related
* functions or missing data in arrays of H3 indices. Analogous to NaN in
* floating point.
*/
#define H3_NULL 0
/** @brief Result code (success or specific error) from an H3 operation */
typedef uint32_t H3Error;
typedef enum {
E_SUCCESS = 0, // Success (no error)
E_FAILED = 1, // The operation failed but a more specific error is not
// available
E_DOMAIN = 2, // Argument was outside the acceptable range (when a more
// specific error code is not available)
E_LATLNG_DOMAIN = 3, // Latitude or longitude arguments were outside the
// acceptable range
E_RES_DOMAIN = 4, // Resolution argument was outside the acceptable range
E_CELL_INVALID = 5, // `H3Index` cell argument was not valid
E_DIR_EDGE_INVALID = 6, // `H3Index` directed edge argument was not valid
E_UNDIR_EDGE_INVALID =
7, // `H3Index` undirected edge argument was not valid
E_VERTEX_INVALID = 8, // `H3Index` vertex argument was not valid
E_PENTAGON = 9, // Pentagon distortion was encountered which the algorithm
// could not handle
E_DUPLICATE_INPUT = 10, // Duplicate input was encountered in the arguments
// and the algorithm could not handle it
E_NOT_NEIGHBORS = 11, // `H3Index` cell arguments were not neighbors
E_RES_MISMATCH =
12, // `H3Index` cell arguments had incompatible resolutions
E_MEMORY_ALLOC = 13, // Necessary memory allocation failed
E_MEMORY_BOUNDS = 14, // Bounds of provided memory were not large enough
E_OPTION_INVALID = 15, // Mode or flags argument was not valid
E_INDEX_INVALID = 16, // `H3Index` argument was not valid
E_BASE_CELL_DOMAIN =
17, // Base cell number was outside of acceptable range
E_DIGIT_DOMAIN = 18, // Child digits invalid
E_DELETED_DIGIT = 19, // Deleted subsequence indicates invalid index
// Sentinel value; not a real error. One past the last valid code.
H3_ERROR_END
} H3ErrorCodes;
/** @defgroup describeH3Error describeH3Error
* Functions for describeH3Error
* @{
*/
/** @brief converts the provided H3Error value into a description string */
DECLSPEC const char *H3_EXPORT(describeH3Error)(H3Error err);
/** @} */
/* library version numbers generated from VERSION file */
// clang-format off
#define H3_VERSION_MAJOR 4
#define H3_VERSION_MINOR 5
#define H3_VERSION_PATCH 0
// clang-format on
/** Maximum number of cell boundary vertices; worst case is pentagon:
* 5 original verts + 5 edge crossings
*/
#define MAX_CELL_BNDRY_VERTS 10
/** @struct LatLng
@brief latitude/longitude in radians
*/
typedef struct {
double lat; ///< latitude in radians
double lng; ///< longitude in radians
} LatLng;
/** @struct CellBoundary
@brief cell boundary in latitude/longitude
*/
typedef struct {
int numVerts; ///< number of vertices
LatLng verts[MAX_CELL_BNDRY_VERTS]; ///< vertices in ccw order
} CellBoundary;
/** @struct GeoLoop
* @brief similar to CellBoundary, but requires more alloc work
*/
typedef struct {
int numVerts;
LatLng *verts;
} GeoLoop;
/** @struct GeoPolygon
* @brief Simplified core of GeoJSON Polygon coordinates definition
*/
typedef struct {
GeoLoop geoloop; ///< exterior boundary of the polygon
int numHoles; ///< number of elements in the array pointed to by holes
GeoLoop *holes; ///< interior boundaries (holes) in the polygon
} GeoPolygon;
/** @struct GeoMultiPolygon
* @brief Simplified core of GeoJSON MultiPolygon coordinates definition
*/
typedef struct {
int numPolygons;
GeoPolygon *polygons;
} GeoMultiPolygon;
/**
* Values representing polyfill containment modes, to be used in
* the `flags` bit field for `polygonToCellsExperimental`.
*/
typedef enum {
CONTAINMENT_CENTER = 0, ///< Cell center is contained in the shape
CONTAINMENT_FULL = 1, ///< Cell is fully contained in the shape
CONTAINMENT_OVERLAPPING = 2, ///< Cell overlaps the shape at any point
CONTAINMENT_OVERLAPPING_BBOX = 3, ///< Cell bounding box overlaps shape
CONTAINMENT_INVALID = 4 ///< This mode is invalid and should not be used
} ContainmentMode;
/** @struct LinkedLatLng
* @brief A coordinate node in a linked geo structure, part of a linked list
*/
typedef struct LinkedLatLng LinkedLatLng;
struct LinkedLatLng {
LatLng vertex;
LinkedLatLng *next;
};
/** @struct LinkedGeoLoop
* @brief A loop node in a linked geo structure, part of a linked list
*/
typedef struct LinkedGeoLoop LinkedGeoLoop;
struct LinkedGeoLoop {
LinkedLatLng *first;
LinkedLatLng *last;
LinkedGeoLoop *next;
};
/** @struct LinkedGeoPolygon
* @brief A polygon node in a linked geo structure, part of a linked list.
*/
typedef struct LinkedGeoPolygon LinkedGeoPolygon;
struct LinkedGeoPolygon {
LinkedGeoLoop *first;
LinkedGeoLoop *last;
LinkedGeoPolygon *next;
};
/** @struct CoordIJ
* @brief IJ hexagon coordinates
*
* Each axis is spaced 120 degrees apart.
*/
typedef struct {
int i; ///< i component
int j; ///< j component
} CoordIJ;
/** @defgroup latLngToCell latLngToCell
* Functions for latLngToCell
* @{
*/
/** @brief find the H3 index of the resolution res cell containing the lat/lng
*/
DECLSPEC H3Error H3_EXPORT(latLngToCell)(const LatLng *g, int res,
H3Index *out);
/** @} */
/** @defgroup cellToLatLng cellToLatLng
* Functions for cellToLatLng
* @{
*/
/** @brief find the lat/lng center point g of the cell h3 */
DECLSPEC H3Error H3_EXPORT(cellToLatLng)(H3Index h3, LatLng *g);
/** @} */
/** @defgroup cellToBoundary cellToBoundary
* Functions for cellToBoundary
* @{
*/
/** @brief give the cell boundary in lat/lng coordinates for the cell h3 */
DECLSPEC H3Error H3_EXPORT(cellToBoundary)(H3Index h3, CellBoundary *gp);
/** @} */
/** @defgroup gridDisk gridDisk
* Functions for gridDisk
* @{
*/
/** @brief maximum number of hexagons in k-ring */
DECLSPEC H3Error H3_EXPORT(maxGridDiskSize)(int k, int64_t *out);
/** @brief hexagons neighbors in all directions, assuming no pentagons */
DECLSPEC H3Error H3_EXPORT(gridDiskUnsafe)(H3Index origin, int k, H3Index *out);
/** @} */
/** @brief hexagons neighbors in all directions, assuming no pentagons,
* reporting distance from origin */
DECLSPEC H3Error H3_EXPORT(gridDiskDistancesUnsafe)(H3Index origin, int k,
H3Index *out,
int *distances);
/** @brief hexagons neighbors in all directions reporting distance from origin
*/
DECLSPEC H3Error H3_EXPORT(gridDiskDistancesSafe)(H3Index origin, int k,
H3Index *out, int *distances);
/** @brief collection of hex rings sorted by ring for all given hexagons */
DECLSPEC H3Error H3_EXPORT(gridDisksUnsafe)(H3Index *h3Set, int length, int k,
H3Index *out);
/** @brief hexagon neighbors in all directions */
DECLSPEC H3Error H3_EXPORT(gridDisk)(H3Index origin, int k, H3Index *out);
/** @} */
/** @defgroup gridDiskDistances gridDiskDistances
* Functions for gridDiskDistances
* @{
*/
/** @brief hexagon neighbors in all directions, reporting distance from origin
*/
DECLSPEC H3Error H3_EXPORT(gridDiskDistances)(H3Index origin, int k,
H3Index *out, int *distances);
/** @} */
/** @defgroup gridRing gridRing
* Functions for gridRing
* @{
*/
/** @brief maximum number of hexagons in hollow k-ring */
DECLSPEC H3Error H3_EXPORT(maxGridRingSize)(int k, int64_t *out);
/** @brief hollow hexagon ring k distance from origin */
DECLSPEC H3Error H3_EXPORT(gridRingUnsafe)(H3Index origin, int k, H3Index *out);
/** @brief hollow hexagon ring k distance from origin */
DECLSPEC H3Error H3_EXPORT(gridRing)(H3Index origin, int k, H3Index *out);
/** @} */
/** @defgroup polygonToCells polygonToCells
* Functions for polygonToCells
* @{
*/
/** @brief maximum number of cells that could be in the polygon */
DECLSPEC H3Error H3_EXPORT(maxPolygonToCellsSize)(const GeoPolygon *geoPolygon,
int res, uint32_t flags,
int64_t *out);
/** @brief cells within the given polygon */
DECLSPEC H3Error H3_EXPORT(polygonToCells)(const GeoPolygon *geoPolygon,
int res, uint32_t flags,
H3Index *out);
/** @} */
/** @defgroup polygonToCellsExperimental polygonToCellsExperimental
* Functions for polygonToCellsExperimental.
* This is an experimental-only API and is subject to change in minor versions.
* @{
*/
/** @brief maximum number of cells that could be in the polygon */
DECLSPEC H3Error H3_EXPORT(maxPolygonToCellsSizeExperimental)(
const GeoPolygon *polygon, int res, uint32_t flags, int64_t *out);
/** @brief cells within the given polygon */
DECLSPEC H3Error H3_EXPORT(polygonToCellsExperimental)(
const GeoPolygon *polygon, int res, uint32_t flags, int64_t size,
H3Index *out);
/** @} */
/** @defgroup cellsToMultiPolygon cellsToMultiPolygon
* Functions for cellsToMultiPolygon (currently a binding-only concept)
* @{
*/
/** @brief Create a LinkedGeoPolygon from a set of cells */
DECLSPEC H3Error H3_EXPORT(cellsToLinkedMultiPolygon)(const H3Index *h3Set,
const int numHexes,
LinkedGeoPolygon *out);
/** @brief Free all memory created for a LinkedGeoPolygon */
DECLSPEC void H3_EXPORT(destroyLinkedMultiPolygon)(LinkedGeoPolygon *polygon);
/** @} */
/** @defgroup degsToRads degsToRads
* Functions for degsToRads
* @{
*/
/** @brief converts degrees to radians */
DECLSPEC double H3_EXPORT(degsToRads)(double degrees);
/** @} */
/** @defgroup radsToDegs radsToDegs
* Functions for radsToDegs
* @{
*/
/** @brief converts radians to degrees */
DECLSPEC double H3_EXPORT(radsToDegs)(double radians);
/** @} */
/** @defgroup greatCircleDistance greatCircleDistance
* Functions for distance
* @{
*/
/** @brief "great circle distance" between pairs of LatLng points in radians*/
DECLSPEC double H3_EXPORT(greatCircleDistanceRads)(const LatLng *a,
const LatLng *b);
/** @brief "great circle distance" between pairs of LatLng points in
* kilometers*/
DECLSPEC double H3_EXPORT(greatCircleDistanceKm)(const LatLng *a,
const LatLng *b);
/** @brief "great circle distance" between pairs of LatLng points in meters*/
DECLSPEC double H3_EXPORT(greatCircleDistanceM)(const LatLng *a,
const LatLng *b);
/** @} */
/** @defgroup getHexagonAreaAvg getHexagonAreaAvg
* Functions for getHexagonAreaAvg
* @{
*/
/** @brief average hexagon area in square kilometers (excludes pentagons) */
DECLSPEC H3Error H3_EXPORT(getHexagonAreaAvgKm2)(int res, double *out);
/** @brief average hexagon area in square meters (excludes pentagons) */
DECLSPEC H3Error H3_EXPORT(getHexagonAreaAvgM2)(int res, double *out);
/** @} */
/** @defgroup cellArea cellArea
* Functions for cellArea
* @{
*/
/** @brief exact area for a specific cell (hexagon or pentagon) in radians^2 */
DECLSPEC H3Error H3_EXPORT(cellAreaRads2)(H3Index h, double *out);
/** @brief exact area for a specific cell (hexagon or pentagon) in kilometers^2
*/
DECLSPEC H3Error H3_EXPORT(cellAreaKm2)(H3Index h, double *out);
/** @brief exact area for a specific cell (hexagon or pentagon) in meters^2 */
DECLSPEC H3Error H3_EXPORT(cellAreaM2)(H3Index h, double *out);
/** @} */
/** @defgroup getHexagonEdgeLengthAvg getHexagonEdgeLengthAvg
* Functions for getHexagonEdgeLengthAvg
* @{
*/
/** @brief average hexagon edge length in kilometers (excludes pentagons) */
DECLSPEC H3Error H3_EXPORT(getHexagonEdgeLengthAvgKm)(int res, double *out);
/** @brief average hexagon edge length in meters (excludes pentagons) */
DECLSPEC H3Error H3_EXPORT(getHexagonEdgeLengthAvgM)(int res, double *out);
/** @} */
/** @defgroup edgeLength edgeLength
* Functions for edgeLength
* @{
*/
/** @brief exact length for a specific directed edge in radians*/
DECLSPEC H3Error H3_EXPORT(edgeLengthRads)(H3Index edge, double *length);
/** @brief exact length for a specific directed edge in kilometers*/
DECLSPEC H3Error H3_EXPORT(edgeLengthKm)(H3Index edge, double *length);
/** @brief exact length for a specific directed edge in meters*/
DECLSPEC H3Error H3_EXPORT(edgeLengthM)(H3Index edge, double *length);
/** @} */
/** @defgroup getNumCells getNumCells
* Functions for getNumCells
* @{
*/
/** @brief number of cells (hexagons and pentagons) for a given resolution
*
* It works out to be `2 + 120*7^r` for resolution `r`.
*
* # Mathematical notes
*
* Let h(n) be the number of children n levels below
* a single *hexagon*.
*
* Then h(n) = 7^n.
*
* Let p(n) be the number of children n levels below
* a single *pentagon*.
*
* Then p(0) = 1, and p(1) = 6, since each pentagon
* has 5 hexagonal immediate children and 1 pentagonal
* immediate child.
*
* In general, we have the recurrence relation
*
* p(n) = 5*h(n-1) + p(n-1)
* = 5*7^(n-1) + p(n-1).
*
* Working through the recurrence, we get that
*
* p(n) = 1 + 5*\sum_{k=1}^n 7^{k-1}
* = 1 + 5*(7^n - 1)/6,
*
* using the closed form for a geometric series.
*
* Using the closed forms for h(n) and p(n), we can
* get a closed form for the total number of cells
* at resolution r:
*
* c(r) = 12*p(r) + 110*h(r)
* = 2 + 120*7^r.
*
*
* @param res H3 cell resolution
*
* @return number of cells at resolution `res`
*/
DECLSPEC H3Error H3_EXPORT(getNumCells)(int res, int64_t *out);
/** @} */
/** @defgroup getRes0Cells getRes0Cells
* Functions for getRes0Cells
* @{
*/
/** @brief returns the number of resolution 0 cells (hexagons and pentagons) */
DECLSPEC int H3_EXPORT(res0CellCount)(void);
/** @brief provides all base cells in H3Index format*/
DECLSPEC H3Error H3_EXPORT(getRes0Cells)(H3Index *out);
/** @} */
/** @defgroup getPentagons getPentagons
* Functions for getPentagons
* @{
*/
/** @brief returns the number of pentagons per resolution */
DECLSPEC int H3_EXPORT(pentagonCount)(void);
/** @brief generates all pentagons at the specified resolution */
DECLSPEC H3Error H3_EXPORT(getPentagons)(int res, H3Index *out);
/** @} */
/** @defgroup getResolution getResolution
* Functions for getResolution
* @{
*/
/** @brief returns the resolution of the provided H3 index
* Works on both cells and directed edges. */
DECLSPEC int H3_EXPORT(getResolution)(H3Index h);
/** @} */
/** @defgroup getBaseCellNumber getBaseCellNumber
* Functions for getBaseCellNumber
* @{
*/
/** @brief returns the base cell "number" (0 to 121) of the provided H3 cell
*
* Note: Technically works on H3 edges, but will return base cell of the
* origin cell. */
DECLSPEC int H3_EXPORT(getBaseCellNumber)(H3Index h);
/** @} */
/** @defgroup getIndexDigit getIndexDigit
* Functions for getIndexDigit
* @{
*/
/** @brief returns the indexing digit of the provided H3 cell at a given
* resolution
*
* Indexing digits are 1-indexed beginning with the digit for resolution 1. */
DECLSPEC H3Error H3_EXPORT(getIndexDigit)(H3Index h, int res, int *out);
/** @} */
/** @defgroup constructCell constructCell
* Functions for constructCell
* @{
*/
/** @brief create a cell from its components
* Only allows for constructing valid H3 cells.
**/
DECLSPEC H3Error H3_EXPORT(constructCell)(int res, int baseCellNumber,
const int *digits, H3Index *out);
/** @} */
/** @defgroup stringToH3 stringToH3
* Functions for stringToH3
* @{
*/
/** @brief converts the canonical string format to H3Index format */
DECLSPEC H3Error H3_EXPORT(stringToH3)(const char *str, H3Index *out);
/** @} */
/** @defgroup h3ToString h3ToString
* Functions for h3ToString
* @{
*/
/** @brief converts an H3Index to a canonical string */
DECLSPEC H3Error H3_EXPORT(h3ToString)(H3Index h, char *str, size_t sz);
/** @} */
/** @defgroup isValidCell isValidCell
* Functions for isValidCell
* @{
*/
/** @brief confirms if an H3Index is a valid cell (hexagon or pentagon)
* In particular, returns 0 (False) for H3 directed edges or invalid data
*/
DECLSPEC int H3_EXPORT(isValidCell)(H3Index h);
/** @} */
/** @defgroup isValidIndex isValidIndex
* Functions for isValidIndex
* @{
*/
/** @brief confirms if an H3Index is valid for any mode (cell, directed edge, or
* vertex) Returns 1 if the H3 index is valid for any supported type, 0
* otherwise
*/
DECLSPEC int H3_EXPORT(isValidIndex)(H3Index h);
/** @} */
/** @defgroup cellToParent cellToParent
* Functions for cellToParent
* @{
*/
/** @brief returns the parent (or grandparent, etc) cell of the given cell
*/
DECLSPEC H3Error H3_EXPORT(cellToParent)(H3Index h, int parentRes,
H3Index *parent);
/** @} */
/** @defgroup cellToChildren cellToChildren
* Functions for cellToChildren
* @{
*/
/** @brief determines the exact number of children (or grandchildren, etc)
* that would be returned for the given cell */
DECLSPEC H3Error H3_EXPORT(cellToChildrenSize)(H3Index h, int childRes,
int64_t *out);
/** @brief provides the children (or grandchildren, etc) of the given cell */
DECLSPEC H3Error H3_EXPORT(cellToChildren)(H3Index h, int childRes,
H3Index *children);
/** @} */
/** @defgroup cellToCenterChild cellToCenterChild
* Functions for cellToCenterChild
* @{
*/
/** @brief returns the center child of the given cell at the specified
* resolution */
DECLSPEC H3Error H3_EXPORT(cellToCenterChild)(H3Index h, int childRes,
H3Index *child);
/** @} */
/** @defgroup cellToChildPos cellToChildPos
* Functions for cellToChildPos
* @{
*/
/** @brief Returns the position of the cell within an ordered list of all
* children of the cell's parent at the specified resolution */
DECLSPEC H3Error H3_EXPORT(cellToChildPos)(H3Index child, int parentRes,
int64_t *out);
/** @} */
/** @defgroup childPosToCell childPosToCell
* Functions for childPosToCell
* @{
*/
/** @brief Returns the child cell at a given position within an ordered list of
* all children at the specified resolution */
DECLSPEC H3Error H3_EXPORT(childPosToCell)(int64_t childPos, H3Index parent,
int childRes, H3Index *child);
/** @} */
/** @defgroup compactCells compactCells
* Functions for compactCells
* @{
*/
/** @brief compacts the given set of hexagons as best as possible */
DECLSPEC H3Error H3_EXPORT(compactCells)(const H3Index *h3Set,
H3Index *compactedSet,
const int64_t numHexes);
/** @} */
/** @defgroup uncompactCells uncompactCells
* Functions for uncompactCells
* @{
*/
/** @brief determines the exact number of hexagons that will be uncompacted
* from the compacted set */
DECLSPEC H3Error H3_EXPORT(uncompactCellsSize)(const H3Index *compactedSet,
const int64_t numCompacted,
const int res, int64_t *out);
/** @brief uncompacts the compacted hexagon set */
DECLSPEC H3Error H3_EXPORT(uncompactCells)(const H3Index *compactedSet,
const int64_t numCompacted,
H3Index *outSet,
const int64_t numOut, const int res);
/** @} */
/** @defgroup isResClassIII isResClassIII
* Functions for isResClassIII
* @{
*/
/** @brief determines if a hexagon is Class III (or Class II) */
DECLSPEC int H3_EXPORT(isResClassIII)(H3Index h);
/** @} */
/** @defgroup isPentagon isPentagon
* Functions for isPentagon
* @{
*/
/** @brief determines if an H3 cell is a pentagon */
DECLSPEC int H3_EXPORT(isPentagon)(H3Index h);
/** @} */
/** @defgroup getIcosahedronFaces getIcosahedronFaces
* Functions for getIcosahedronFaces
* @{
*/
/** @brief Max number of icosahedron faces intersected by an index */
DECLSPEC H3Error H3_EXPORT(maxFaceCount)(H3Index h3, int *out);
/** @brief Find all icosahedron faces intersected by a given H3 index */
DECLSPEC H3Error H3_EXPORT(getIcosahedronFaces)(H3Index h3, int *out);
/** @} */
/** @defgroup areNeighborCells areNeighborCells
* Functions for areNeighborCells
* @{
*/
/** @brief returns whether or not the provided hexagons border */
DECLSPEC H3Error H3_EXPORT(areNeighborCells)(H3Index origin,
H3Index destination, int *out);
/** @} */
/** @defgroup cellsToDirectedEdge cellsToDirectedEdge
* Functions for cellsToDirectedEdge
* @{
*/
/** @brief returns the directed edge H3Index for the specified origin and
* destination */
DECLSPEC H3Error H3_EXPORT(cellsToDirectedEdge)(H3Index origin,
H3Index destination,
H3Index *out);
/** @} */
/** @defgroup isValidDirectedEdge isValidDirectedEdge
* Functions for isValidDirectedEdge
* @{
*/
/** @brief returns whether the H3Index is a valid directed edge */
DECLSPEC int H3_EXPORT(isValidDirectedEdge)(H3Index edge);
/** @} */
/** @defgroup getDirectedEdgeOrigin \
* getDirectedEdgeOrigin
* Functions for getDirectedEdgeOrigin
* @{
*/
/** @brief Returns the origin hexagon H3Index from the directed edge
* H3Index */
DECLSPEC H3Error H3_EXPORT(getDirectedEdgeOrigin)(H3Index edge, H3Index *out);
/** @} */
/** @defgroup getDirectedEdgeDestination \
* getDirectedEdgeDestination
* Functions for getDirectedEdgeDestination
* @{
*/
/** @brief Returns the destination hexagon H3Index from the directed edge
* H3Index */
DECLSPEC H3Error H3_EXPORT(getDirectedEdgeDestination)(H3Index edge,
H3Index *out);
/** @} */
/** @defgroup directedEdgeToCells \
* directedEdgeToCells
* Functions for directedEdgeToCells
* @{
*/
/** @brief Returns the origin and destination hexagons from the directed
* edge H3Index */
DECLSPEC H3Error H3_EXPORT(directedEdgeToCells)(H3Index edge,
H3Index *originDestination);
/** @} */
/** @defgroup originToDirectedEdges \
* originToDirectedEdges
* Functions for originToDirectedEdges
* @{
*/
/** @brief Returns the 6 (or 5 for pentagons) edges associated with the H3Index
*/
DECLSPEC H3Error H3_EXPORT(originToDirectedEdges)(H3Index origin,
H3Index *edges);
/** @} */
/** @defgroup directedEdgeToBoundary directedEdgeToBoundary
* Functions for directedEdgeToBoundary
* @{
*/
/** @brief Returns the CellBoundary containing the coordinates of the edge */
DECLSPEC H3Error H3_EXPORT(directedEdgeToBoundary)(H3Index edge,
CellBoundary *gb);
/** @} */
/** @defgroup reverseDirectedEdge reverseDirectedEdge
* Functions for reverseDirectedEdge
* @{
*/
/** @brief Returns the directed edge with origin and destination cells reversed
*/
DECLSPEC H3Error H3_EXPORT(reverseDirectedEdge)(H3Index edge, H3Index *out);
/** @} */
/** @defgroup cellToVertex cellToVertex
* Functions for cellToVertex
* @{
*/
/** @brief Returns a single vertex for a given cell, as an H3 index */
DECLSPEC H3Error H3_EXPORT(cellToVertex)(H3Index origin, int vertexNum,
H3Index *out);
/** @} */
/** @defgroup cellToVertexes cellToVertexes
* Functions for cellToVertexes
* @{
*/
/** @brief Returns all vertexes for a given cell, as H3 indexes */
DECLSPEC H3Error H3_EXPORT(cellToVertexes)(H3Index origin, H3Index *vertexes);
/** @} */
/** @defgroup vertexToLatLng vertexToLatLng
* Functions for vertexToLatLng
* @{
*/
/** @brief Returns a single vertex for a given cell, as an H3 index */
DECLSPEC H3Error H3_EXPORT(vertexToLatLng)(H3Index vertex, LatLng *point);
/** @} */
/** @defgroup isValidVertex isValidVertex
* Functions for isValidVertex
* @{
*/
/** @brief Whether the input is a valid H3 vertex */
DECLSPEC int H3_EXPORT(isValidVertex)(H3Index vertex);
/** @} */
/** @defgroup gridDistance gridDistance
* Functions for gridDistance
* @{
*/
/** @brief Returns grid distance between two indexes */
DECLSPEC H3Error H3_EXPORT(gridDistance)(H3Index origin, H3Index h3,
int64_t *distance);
/** @} */
/** @defgroup gridPathCells gridPathCells
* Functions for gridPathCells
* @{
*/
/** @brief Number of indexes in a line connecting two indexes */
DECLSPEC H3Error H3_EXPORT(gridPathCellsSize)(H3Index start, H3Index end,
int64_t *size);
/** @brief Line of h3 indexes connecting two indexes */
DECLSPEC H3Error H3_EXPORT(gridPathCells)(H3Index start, H3Index end,
H3Index *out);
/** @} */
/** @defgroup cellToLocalIj cellToLocalIj
* Functions for cellToLocalIj
* @{
*/
/** @brief Returns two dimensional coordinates for the given index */
DECLSPEC H3Error H3_EXPORT(cellToLocalIj)(H3Index origin, H3Index h3,
uint32_t mode, CoordIJ *out);
/** @} */
/** @defgroup localIjToCell localIjToCell
* Functions for localIjToCell
* @{
*/
/** @brief Returns index for the given two dimensional coordinates */
DECLSPEC H3Error H3_EXPORT(localIjToCell)(H3Index origin, const CoordIJ *ij,
uint32_t mode, H3Index *out);
/** @} */
#ifdef __cplusplus
} // extern "C"
#endif
#endif
@@ -0,0 +1,28 @@
####### Expanded from @PACKAGE_INIT@ by configure_package_config_file() #######
####### Any changes to this file will be overwritten by the next CMake run ####
####### The input file was Config.cmake.in ########
get_filename_component(PACKAGE_PREFIX_DIR "${CMAKE_CURRENT_LIST_DIR}/../../../" ABSOLUTE)
macro(set_and_check _var _file)
set(${_var} "${_file}")
if(NOT EXISTS "${_file}")
message(FATAL_ERROR "File or directory ${_file} referenced by variable ${_var} does not exist !")
endif()
endmacro()
macro(check_required_components _NAME)
foreach(comp ${${_NAME}_FIND_COMPONENTS})
if(NOT ${_NAME}_${comp}_FOUND)
if(${_NAME}_FIND_REQUIRED_${comp})
set(${_NAME}_FOUND FALSE)
endif()
endif()
endforeach()
endmacro()
####################################################################################
include("${CMAKE_CURRENT_LIST_DIR}/h3Targets.cmake")
check_required_components("h3")
@@ -0,0 +1,65 @@
# This is a basic version file for the Config-mode of find_package().
# It is used by write_basic_package_version_file() as input file for configure_file()
# to create a version-file which can be installed along a config.cmake file.
#
# The created file sets PACKAGE_VERSION_EXACT if the current version string and
# the requested version string are exactly the same and it sets
# PACKAGE_VERSION_COMPATIBLE if the current version is >= requested version,
# but only if the requested major version is the same as the current one.
# The variable CVF_VERSION must be set before calling configure_file().
set(PACKAGE_VERSION "4.5.0")
if(PACKAGE_VERSION VERSION_LESS PACKAGE_FIND_VERSION)
set(PACKAGE_VERSION_COMPATIBLE FALSE)
else()
if("4.5.0" MATCHES "^([0-9]+)\\.")
set(CVF_VERSION_MAJOR "${CMAKE_MATCH_1}")
if(NOT CVF_VERSION_MAJOR VERSION_EQUAL 0)
string(REGEX REPLACE "^0+" "" CVF_VERSION_MAJOR "${CVF_VERSION_MAJOR}")
endif()
else()
set(CVF_VERSION_MAJOR "4.5.0")
endif()
if(PACKAGE_FIND_VERSION_RANGE)
# both endpoints of the range must have the expected major version
math (EXPR CVF_VERSION_MAJOR_NEXT "${CVF_VERSION_MAJOR} + 1")
if (NOT PACKAGE_FIND_VERSION_MIN_MAJOR STREQUAL CVF_VERSION_MAJOR
OR ((PACKAGE_FIND_VERSION_RANGE_MAX STREQUAL "INCLUDE" AND NOT PACKAGE_FIND_VERSION_MAX_MAJOR STREQUAL CVF_VERSION_MAJOR)
OR (PACKAGE_FIND_VERSION_RANGE_MAX STREQUAL "EXCLUDE" AND NOT PACKAGE_FIND_VERSION_MAX VERSION_LESS_EQUAL CVF_VERSION_MAJOR_NEXT)))
set(PACKAGE_VERSION_COMPATIBLE FALSE)
elseif(PACKAGE_FIND_VERSION_MIN_MAJOR STREQUAL CVF_VERSION_MAJOR
AND ((PACKAGE_FIND_VERSION_RANGE_MAX STREQUAL "INCLUDE" AND PACKAGE_VERSION VERSION_LESS_EQUAL PACKAGE_FIND_VERSION_MAX)
OR (PACKAGE_FIND_VERSION_RANGE_MAX STREQUAL "EXCLUDE" AND PACKAGE_VERSION VERSION_LESS PACKAGE_FIND_VERSION_MAX)))
set(PACKAGE_VERSION_COMPATIBLE TRUE)
else()
set(PACKAGE_VERSION_COMPATIBLE FALSE)
endif()
else()
if(PACKAGE_FIND_VERSION_MAJOR STREQUAL CVF_VERSION_MAJOR)
set(PACKAGE_VERSION_COMPATIBLE TRUE)
else()
set(PACKAGE_VERSION_COMPATIBLE FALSE)
endif()
if(PACKAGE_FIND_VERSION STREQUAL PACKAGE_VERSION)
set(PACKAGE_VERSION_EXACT TRUE)
endif()
endif()
endif()
# if the installed or the using project don't have CMAKE_SIZEOF_VOID_P set, ignore it:
if("${CMAKE_SIZEOF_VOID_P}" STREQUAL "" OR "8" STREQUAL "")
return()
endif()
# check that the installed version has the same 32/64bit-ness as the one which is currently searching:
if(NOT CMAKE_SIZEOF_VOID_P STREQUAL "8")
math(EXPR installedBits "8 * 8")
set(PACKAGE_VERSION "${PACKAGE_VERSION} (${installedBits}bit)")
set(PACKAGE_VERSION_UNSUITABLE TRUE)
endif()
@@ -0,0 +1,19 @@
#----------------------------------------------------------------
# Generated CMake target import file for configuration "Release".
#----------------------------------------------------------------
# Commands may need to know the format version.
set(CMAKE_IMPORT_FILE_VERSION 1)
# Import target "h3::h3" for configuration "Release"
set_property(TARGET h3::h3 APPEND PROPERTY IMPORTED_CONFIGURATIONS RELEASE)
set_target_properties(h3::h3 PROPERTIES
IMPORTED_LINK_INTERFACE_LANGUAGES_RELEASE "C"
IMPORTED_LOCATION_RELEASE "${_IMPORT_PREFIX}/lib64/libh3.a"
)
list(APPEND _cmake_import_check_targets h3::h3 )
list(APPEND _cmake_import_check_files_for_h3::h3 "${_IMPORT_PREFIX}/lib64/libh3.a" )
# Commands beyond this point should not need to know the version.
set(CMAKE_IMPORT_FILE_VERSION)
@@ -0,0 +1,109 @@
# Generated by CMake
if("${CMAKE_MAJOR_VERSION}.${CMAKE_MINOR_VERSION}" LESS 2.8)
message(FATAL_ERROR "CMake >= 2.8.12 required")
endif()
if(CMAKE_VERSION VERSION_LESS "2.8.12")
message(FATAL_ERROR "CMake >= 2.8.12 required")
endif()
cmake_policy(PUSH)
cmake_policy(VERSION 2.8.12...4.0)
#----------------------------------------------------------------
# Generated CMake target import file.
#----------------------------------------------------------------
# Commands may need to know the format version.
set(CMAKE_IMPORT_FILE_VERSION 1)
# Protect against multiple inclusion, which would fail when already imported targets are added once more.
set(_cmake_targets_defined "")
set(_cmake_targets_not_defined "")
set(_cmake_expected_targets "")
foreach(_cmake_expected_target IN ITEMS h3::h3)
list(APPEND _cmake_expected_targets "${_cmake_expected_target}")
if(TARGET "${_cmake_expected_target}")
list(APPEND _cmake_targets_defined "${_cmake_expected_target}")
else()
list(APPEND _cmake_targets_not_defined "${_cmake_expected_target}")
endif()
endforeach()
unset(_cmake_expected_target)
if(_cmake_targets_defined STREQUAL _cmake_expected_targets)
unset(_cmake_targets_defined)
unset(_cmake_targets_not_defined)
unset(_cmake_expected_targets)
unset(CMAKE_IMPORT_FILE_VERSION)
cmake_policy(POP)
return()
endif()
if(NOT _cmake_targets_defined STREQUAL "")
string(REPLACE ";" ", " _cmake_targets_defined_text "${_cmake_targets_defined}")
string(REPLACE ";" ", " _cmake_targets_not_defined_text "${_cmake_targets_not_defined}")
message(FATAL_ERROR "Some (but not all) targets in this export set were already defined.\nTargets Defined: ${_cmake_targets_defined_text}\nTargets not yet defined: ${_cmake_targets_not_defined_text}\n")
endif()
unset(_cmake_targets_defined)
unset(_cmake_targets_not_defined)
unset(_cmake_expected_targets)
# Compute the installation prefix relative to this file.
get_filename_component(_IMPORT_PREFIX "${CMAKE_CURRENT_LIST_FILE}" PATH)
get_filename_component(_IMPORT_PREFIX "${_IMPORT_PREFIX}" PATH)
get_filename_component(_IMPORT_PREFIX "${_IMPORT_PREFIX}" PATH)
get_filename_component(_IMPORT_PREFIX "${_IMPORT_PREFIX}" PATH)
if(_IMPORT_PREFIX STREQUAL "/")
set(_IMPORT_PREFIX "")
endif()
# Create imported target h3::h3
add_library(h3::h3 STATIC IMPORTED)
set_target_properties(h3::h3 PROPERTIES
INTERFACE_COMPILE_DEFINITIONS "H3_PREFIX="
INTERFACE_COMPILE_FEATURES "c_std_99"
INTERFACE_INCLUDE_DIRECTORIES "${_IMPORT_PREFIX}/include"
INTERFACE_LINK_LIBRARIES "/usr/lib64/libm.so"
)
# Load information for each installed configuration.
file(GLOB _cmake_config_files "${CMAKE_CURRENT_LIST_DIR}/h3Targets-*.cmake")
foreach(_cmake_config_file IN LISTS _cmake_config_files)
include("${_cmake_config_file}")
endforeach()
unset(_cmake_config_file)
unset(_cmake_config_files)
# Cleanup temporary variables.
set(_IMPORT_PREFIX)
# Loop over all imported files and verify that they actually exist
foreach(_cmake_target IN LISTS _cmake_import_check_targets)
if(CMAKE_VERSION VERSION_LESS "3.28"
OR NOT DEFINED _cmake_import_check_xcframework_for_${_cmake_target}
OR NOT IS_DIRECTORY "${_cmake_import_check_xcframework_for_${_cmake_target}}")
foreach(_cmake_file IN LISTS "_cmake_import_check_files_for_${_cmake_target}")
if(NOT EXISTS "${_cmake_file}")
message(FATAL_ERROR "The imported target \"${_cmake_target}\" references the file
\"${_cmake_file}\"
but this file does not exist. Possible reasons include:
* The file was deleted, renamed, or moved to another location.
* An install or uninstall procedure did not complete successfully.
* The installation package was faulty and contained
\"${CMAKE_CURRENT_LIST_FILE}\"
but not all the files it references.
")
endif()
endforeach()
endif()
unset(_cmake_file)
unset("_cmake_import_check_files_for_${_cmake_target}")
endforeach()
unset(_cmake_target)
unset(_cmake_import_check_targets)
# This file does not depend on other imported targets which have
# been exported from the same project but in a separate export set.
# Commands beyond this point should not need to know the version.
set(CMAKE_IMPORT_FILE_VERSION)
cmake_policy(POP)
Binary file not shown.
@@ -0,0 +1,11 @@
prefix=/tmp/tmpaps9sxqn/wheel/platlib
exec_prefix=/tmp/tmpaps9sxqn/wheel/platlib
libdir=/tmp/tmpaps9sxqn/wheel/platlib/lib64
includedir=/tmp/tmpaps9sxqn/wheel/platlib/include
Name: h3
Description: Hexagonal hierarchical geospatial indexing system
Version: 4.5.0
Libs: -L${libdir} -lh3 -lm
Cflags: -I${includedir}