From c0eda95f26a5f79c4deb655d48926e52505bdbd6 Mon Sep 17 00:00:00 2001 From: Joren de Graaf Date: Sat, 3 Oct 2026 17:11:31 +0200 Subject: [PATCH] added gitea activity for fun --- .gitignore | 3 +- main/README.md | 56 + .../tasknest-fasting-notifications.service | 9 + .../tasknest-fasting-notifications.timer | 10 + main/frontend/src/main.js | 13 + main/frontend/src/styles/main.scss | 105 +- main/planner/forms.py | 28 + .../commands/notify_fasting_phases.py | 11 + ...gs_daily_water_goal_ml_waterintakeentry.py | 36 + .../migrations/0017_usersettings_ntfy.py | 11 + ...tingsettings_last_phase_notification_at.py | 12 + main/planner/models.py | 18 + main/planner/services/fasting.py | 8 + .../planner/services/fasting_notifications.py | 43 + main/planner/services/gitea_activity.py | 87 ++ main/planner/services/hydration.py | 41 + main/planner/services/notifications.py | 37 + main/planner/templates/planner/health.html | 10 +- .../planner/partials/gitea_activity.html | 23 + .../planner/partials/hydration_bottle.html | 9 + .../planner/partials/hydration_widget.html | 19 + .../planner/partials/ntfy_test_result.html | 1 + main/planner/templates/planner/task_list.html | 6 + .../templates/planner/user_settings.html | 12 + main/planner/test_fasting_notifications.py | 57 + main/planner/test_gitea_activity.py | 60 + main/planner/test_ntfy.py | 49 + main/planner/tests.py | 47 + main/planner/urls.py | 6 +- main/planner/views.py | 89 +- main/requirements.txt | 5 + main/tasksnest/settings.py | 24 + tasksnest/bin/python | 2 +- .../h3-4.5.0.dist-info/INSTALLER | 1 + .../site-packages/h3-4.5.0.dist-info/METADATA | 329 ++++ .../site-packages/h3-4.5.0.dist-info/RECORD | 66 + .../h3-4.5.0.dist-info/REQUESTED | 0 .../site-packages/h3-4.5.0.dist-info/WHEEL | 7 + .../h3-4.5.0.dist-info/licenses/LICENSE | 202 +++ .../site-packages/h3/CMakeLists.txt | 1 + .../python3.13/site-packages/h3/__init__.py | 33 + .../site-packages/h3/_cy/CMakeLists.txt | 53 + .../site-packages/h3/_cy/__init__.py | 122 ++ .../python3.13/site-packages/h3/_cy/cells.pxd | 30 + .../python3.13/site-packages/h3/_cy/cells.pyx | 455 ++++++ .../python3.13/site-packages/h3/_cy/edges.pxd | 11 + .../python3.13/site-packages/h3/_cy/edges.pyx | 114 ++ .../site-packages/h3/_cy/error_system.pxd | 6 + .../site-packages/h3/_cy/error_system.pyx | 260 ++++ .../python3.13/site-packages/h3/_cy/h3api.h | 860 +++++++++++ .../python3.13/site-packages/h3/_cy/h3lib.pxd | 191 +++ .../site-packages/h3/_cy/latlng.pxd | 7 + .../site-packages/h3/_cy/latlng.pyx | 325 ++++ .../site-packages/h3/_cy/memory.pxd | 12 + .../site-packages/h3/_cy/memory.pyx | 248 +++ .../site-packages/h3/_cy/to_multipoly.pyx | 45 + .../python3.13/site-packages/h3/_cy/util.pxd | 14 + .../python3.13/site-packages/h3/_cy/util.pyx | 101 ++ .../site-packages/h3/_cy/vertex.pxd | 6 + .../site-packages/h3/_cy/vertex.pyx | 54 + .../python3.13/site-packages/h3/_h3shape.py | 338 ++++ .../python3.13/site-packages/h3/_version.py | 3 + .../site-packages/h3/api/__init__.py | 6 + .../h3/api/basic_int/__init__.py | 1369 +++++++++++++++++ .../h3/api/basic_int/_convert.py | 17 + .../h3/api/basic_str/__init__.py | 1369 +++++++++++++++++ .../h3/api/basic_str/_convert.py | 14 + .../h3/api/memview_int/__init__.py | 1369 +++++++++++++++++ .../h3/api/memview_int/_convert.py | 8 + .../h3/api/numpy_int/__init__.py | 1369 +++++++++++++++++ .../h3/api/numpy_int/_convert.py | 15 + .../site-packages/include/h3/h3api.h | 860 +++++++++++ .../lib64/cmake/h3/h3Config.cmake | 28 + .../lib64/cmake/h3/h3ConfigVersion.cmake | 65 + .../lib64/cmake/h3/h3Targets-release.cmake | 19 + .../lib64/cmake/h3/h3Targets.cmake | 109 ++ .../python3.13/site-packages/lib64/libh3.a | Bin 0 -> 185890 bytes .../site-packages/lib64/pkgconfig/h3.pc | 11 + 78 files changed, 11461 insertions(+), 8 deletions(-) create mode 100644 main/deploy/systemd/tasknest-fasting-notifications.service create mode 100644 main/deploy/systemd/tasknest-fasting-notifications.timer create mode 100644 main/planner/management/commands/notify_fasting_phases.py create mode 100644 main/planner/migrations/0016_usersettings_daily_water_goal_ml_waterintakeentry.py create mode 100644 main/planner/migrations/0017_usersettings_ntfy.py create mode 100644 main/planner/migrations/0018_fastingsettings_last_phase_notification_at.py create mode 100644 main/planner/services/fasting_notifications.py create mode 100644 main/planner/services/gitea_activity.py create mode 100644 main/planner/services/hydration.py create mode 100644 main/planner/services/notifications.py create mode 100644 main/planner/templates/planner/partials/gitea_activity.html create mode 100644 main/planner/templates/planner/partials/hydration_bottle.html create mode 100644 main/planner/templates/planner/partials/hydration_widget.html create mode 100644 main/planner/templates/planner/partials/ntfy_test_result.html create mode 100644 main/planner/test_fasting_notifications.py create mode 100644 main/planner/test_gitea_activity.py create mode 100644 main/planner/test_ntfy.py create mode 100644 main/requirements.txt create mode 100644 tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/INSTALLER create mode 100644 tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/METADATA create mode 100644 tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/RECORD create mode 100644 tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/REQUESTED create mode 100644 tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/WHEEL create mode 100644 tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/licenses/LICENSE create mode 100644 tasksnest/lib/python3.13/site-packages/h3/CMakeLists.txt create mode 100644 tasksnest/lib/python3.13/site-packages/h3/__init__.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/CMakeLists.txt create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/__init__.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/cells.pxd create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/cells.pyx create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/edges.pxd create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/edges.pyx create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/error_system.pxd create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/error_system.pyx create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/h3api.h create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/h3lib.pxd create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/latlng.pxd create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/latlng.pyx create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/memory.pxd create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/memory.pyx create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/to_multipoly.pyx create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/util.pxd create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/util.pyx create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/vertex.pxd create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_cy/vertex.pyx create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_h3shape.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/_version.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/api/__init__.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/api/basic_int/__init__.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/api/basic_int/_convert.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/api/basic_str/__init__.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/api/basic_str/_convert.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/api/memview_int/__init__.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/api/memview_int/_convert.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/api/numpy_int/__init__.py create mode 100644 tasksnest/lib/python3.13/site-packages/h3/api/numpy_int/_convert.py create mode 100644 tasksnest/lib/python3.13/site-packages/include/h3/h3api.h create mode 100644 tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Config.cmake create mode 100644 tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3ConfigVersion.cmake create mode 100644 tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Targets-release.cmake create mode 100644 tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Targets.cmake create mode 100644 tasksnest/lib/python3.13/site-packages/lib64/libh3.a create mode 100644 tasksnest/lib/python3.13/site-packages/lib64/pkgconfig/h3.pc diff --git a/.gitignore b/.gitignore index a759a1c..824eeb6 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,7 @@ __pycache__/ venv/ env/ ENV/ +tasksnest-host/ # Environment / secrets .env @@ -58,4 +59,4 @@ yarn-error.log* Thumbs.db # Local development -*.sqlite3 \ No newline at end of file +*.sqlite3 diff --git a/main/README.md b/main/README.md index c796de6..fd910da 100644 --- a/main/README.md +++ b/main/README.md @@ -44,3 +44,59 @@ systemctl list-timers tasknest-demo-seed.timer The supplied timer runs daily at 03:15 Europe/Amsterdam and catches up after a missed scheduled run when the host comes back online. + +## Fasting phase notifications + +The `notify_fasting_phases` command checks each active fasting schedule and sends +an ntfy notification when the current phase changes to fasting or eating. It +requires a tested, enabled ntfy topic in Settings. The command records each +phase boundary so repeated runs do not send duplicate notifications. A failed +delivery is retried on the next run. If the host was offline across several +boundaries, only the current phase is announced. + +The host runs Python 3.12 while the development environment uses Python 3.13. +Create a separate host virtualenv so systemd does not follow a symlink to a +Python executable absent from the host: + +```sh +cd /home/jorenmartijn/django +python3 -m venv tasksnest-host +tasksnest-host/bin/python -m pip install -r main/requirements.txt +tasksnest-host/bin/python main/manage.py check +``` + +Install the provided systemd service and timer to run this check every minute: + +```sh +sudo cp main/deploy/systemd/tasknest-fasting-notifications.{service,timer} /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl enable --now tasknest-fasting-notifications.timer +``` + +Run database migrations before enabling the timer. Adjust the service's user +and paths for your deployment. + +## Gitea activity widget + +The main task page shows a contribution grid below Daily Workout when +`GITEA_USERNAME` is set in the Django server process environment. It uses +Gitea's `/api/v1/users/{username}/heatmap` endpoint, refreshes the server-side +cache every 15 minutes, and keeps any token out of browser requests. + +Put these values in `/home/jorenmartijn/django/.env`, then restart the service +that runs Django. Values set directly in the service environment take priority: + +```ini +GITEA_USERNAME=your-gitea-username +GITEA_BASE_URL=https://git.jorendegraaf.eu +# Only if the public heatmap endpoint does not show the activity you want: +GITEA_TOKEN=your-read-only-token +``` + +The base URL already defaults to `https://git.jorendegraaf.eu`. For public +activity, try without a token first. If Gitea requires authentication or you +want activity visible only to your account, create a token in Gitea's **User +Settings → Applications → Generate New Token** with `read:user` permission. +Store it in the Django service environment, never in this repository or in +browser JavaScript. The dashboard shows a short unavailable message if the +endpoint cannot be reached. diff --git a/main/deploy/systemd/tasknest-fasting-notifications.service b/main/deploy/systemd/tasknest-fasting-notifications.service new file mode 100644 index 0000000..c2aac32 --- /dev/null +++ b/main/deploy/systemd/tasknest-fasting-notifications.service @@ -0,0 +1,9 @@ +[Unit] +Description=Send Tasknest fasting phase notifications +After=network.target + +[Service] +Type=oneshot +User=jorenmartijn +WorkingDirectory=/home/jorenmartijn/django/main +ExecStart=/home/jorenmartijn/django/tasksnest-host/bin/python manage.py notify_fasting_phases diff --git a/main/deploy/systemd/tasknest-fasting-notifications.timer b/main/deploy/systemd/tasknest-fasting-notifications.timer new file mode 100644 index 0000000..01ab76a --- /dev/null +++ b/main/deploy/systemd/tasknest-fasting-notifications.timer @@ -0,0 +1,10 @@ +[Unit] +Description=Check Tasknest fasting phase changes every minute + +[Timer] +OnCalendar=*-*-* *:*:00 +Persistent=true +Unit=tasknest-fasting-notifications.service + +[Install] +WantedBy=timers.target diff --git a/main/frontend/src/main.js b/main/frontend/src/main.js index f5473a3..3a43f23 100644 --- a/main/frontend/src/main.js +++ b/main/frontend/src/main.js @@ -151,6 +151,19 @@ function initialiseGeolocation() { document.addEventListener('DOMContentLoaded', initialiseGeolocation); htmx.on('htmx:afterSwap', initialiseGeolocation); +function initialiseNtfyForm() { + document.querySelectorAll('[data-ntfy-form]').forEach((form) => { + if (form.dataset.ready) return; + form.dataset.ready = 'true'; + form.querySelector('[name="ntfy_url"]')?.addEventListener('input', () => { + form.querySelector('#ntfy-test-result')?.replaceChildren(); + }); + }); +} + +document.addEventListener('DOMContentLoaded', initialiseNtfyForm); +htmx.on('htmx:afterSwap', initialiseNtfyForm); + function initialiseCategoryPickers() { document.querySelectorAll("[data-category-picker]").forEach((picker) => { diff --git a/main/frontend/src/styles/main.scss b/main/frontend/src/styles/main.scss index 5571ee5..86c6d64 100644 --- a/main/frontend/src/styles/main.scss +++ b/main/frontend/src/styles/main.scss @@ -385,8 +385,12 @@ body[data-theme="dark"] .brushing-control__mark { color: #9adab0; } body[data-theme="dark"] .checkin-form--bowel .field textarea { border-color: #536159; color: #edf5ef; background: #161d19; } .checkin-calendar__exports { display: flex; flex-wrap: wrap; gap: 8px; margin: 0 0 14px; } .checkin-calendar__exports .button:focus-visible { outline: 2px solid $forest; outline-offset: 2px; } -.health-layout { max-width: 920px; margin: 0 auto; } +.health-layout { display:grid; grid-template-columns:minmax(0,1fr) 285px; gap:24px; max-width:1180px; margin:0 auto; align-items:start; } +.health-layout__main { min-width:0; } +.health-layout__sidebar { position:sticky; top:96px; display:grid; gap:16px; } +.health-layout__sidebar .hydration-widget { margin-bottom:0; } .health-layout .checkin-panel { margin-top: 24px; } +@media (max-width:820px) { .health-layout { grid-template-columns:1fr; }.health-layout__sidebar { position:static; } } .mobile-weather-slot { display: none; } @media (max-width: 820px) { .mobile-weather-slot { display: block; } @@ -420,3 +424,102 @@ body[data-theme="dark"] .checkin-form--bowel .field textarea { border-color: #53 @media (prefers-reduced-motion: reduce) { .js-nav-ready .primary-nav { transition: none; } } + +.hydration-widget { margin-bottom:16px; padding:18px; border:1px solid #557261; border-radius:18px; background:#242d27; color:#edf5ef; box-shadow:0 0 20px rgba(71,119,82,.12); } +.hydration-widget .eyebrow { margin:0; color:#acc5af; } +.hydration-widget h2 { margin:0 0 8px; font-size:1.35rem; color:#f6f4e9; } +.hydration-widget__main { display:flex; align-items:center; justify-content:space-between; gap:8px; min-width:0; } +.hydration-widget__stats { flex:1; min-width:0; } +.hydration-widget__stats p { margin:0 0 8px; font-size:.78rem; color:#b8cbbd; } +.hydration-widget__total { font-size:1.38rem !important; font-weight:700; color:#fff !important; white-space:nowrap; } +.hydration-widget__total span { font-size:.8rem; color:#b8cbbd; } +.hydration-widget__track { height:8px; overflow:hidden; border-radius:10px; background:#45554a; } +.hydration-widget__track span { display:block; height:100%; border-radius:10px; background:#dcae61; transition:width .35s ease; } +.hydration-bottle { flex:none; max-width:42%; --bottle-stroke:#8da99a; --bottle-fill:#dcae61; --bottle-shell:#253c34; --bottle-cap:#597468; } +.hydration-bottle__water { transition:transform .35s ease; } +.hydration-widget__actions { display:flex; align-items:flex-start; flex-wrap:wrap; gap:6px; margin-top:7px; } +.hydration-widget__actions form { display:flex; flex-wrap:wrap; gap:6px; margin:0; } +.hydration-widget__actions button, .hydration-widget__other summary { display:inline-block; padding:7px 9px; border:1px solid #6f795d; border-radius:8px; background:#39463b; color:#f9edce; font-size:.76rem; font-weight:700; cursor:pointer; } +.hydration-widget__other summary { list-style:none; } +.hydration-widget__other summary::-webkit-details-marker { display:none; } +.hydration-widget__other[open] { width:100%; } +.hydration-widget__other form { align-items:center; margin-top:8px; } +.hydration-widget__other label { font-size:.75rem; } +.hydration-widget__other input { width:88px; padding:6px; border:1px solid #738678; border-radius:7px; background:#17231c; color:#fff; } +.hydration-widget__info { display:flex; align-items:center; justify-content:space-between; gap:6px; margin:12px 0; font-size:.73rem; color:#b8cbbd; } +.hydration-widget__info button { padding:0; border:0; background:none; color:#efc27d; text-decoration:underline; font-size:.73rem; } +.hydration-widget__error { color:#ffd1bd; font-size:.78rem; } +.hydration-widget__week { border-top:1px solid #40574a; padding-top:10px; } +.hydration-widget__week p { margin:0 0 7px; color:#b8cbbd; font-size:.72rem; } +.hydration-widget__days { display:grid; grid-template-columns:repeat(7,minmax(0,1fr)); gap:5px; } +.hydration-widget__day { display:grid; place-items:center; min-height:27px; border-radius:6px; font-size:.7rem; font-weight:700; } +.hydration-widget__day--none { color:#ffc7bc; background:#633d3a; } +.hydration-widget__day--partial { color:#fff0cf; background:#805e31; } +.hydration-widget__day--goal { color:#e1ffe6; background:#326c48; } +.hydration-widget__day--today { outline:1px solid #e8d9a7; outline-offset:2px; } +.hydration-widget button:focus-visible, .hydration-widget summary:focus-visible, .hydration-widget input:focus-visible { outline:2px solid #efc27d; outline-offset:2px; } +@media (prefers-reduced-motion:reduce) { .hydration-widget__track span, .hydration-bottle__water { transition:none; } } + +body[data-theme="light"] .hydration-widget { border-color:#cbded0; background:#f7faf5; color:#253a2d; box-shadow:0 12px 30px rgba(36,89,55,.08); } +body[data-theme="light"] .hydration-widget .eyebrow { color:#437053; } +body[data-theme="light"] .hydration-widget h2 { color:#213a2b; } +body[data-theme="light"] .hydration-widget__stats p, body[data-theme="light"] .hydration-widget__total span, body[data-theme="light"] .hydration-widget__info, body[data-theme="light"] .hydration-widget__week p { color:#526758; } +body[data-theme="light"] .hydration-widget__total { color:#213a2b !important; } +body[data-theme="light"] .hydration-widget__track { background:#dce8dc; } +body[data-theme="light"] .hydration-widget__track span { background:#b9802c; } +body[data-theme="light"] .hydration-bottle { --bottle-stroke:#557964; --bottle-fill:#d5a24f; --bottle-shell:#e8f1e9; --bottle-cap:#a7c3ad; } +body[data-theme="light"] .hydration-widget__actions button, body[data-theme="light"] .hydration-widget__other summary { border-color:#abc5af; background:#e3f0e4; color:#24543a; } +body[data-theme="light"] .hydration-widget__other input { border-color:#abc5af; background:#fff; color:#213a2b; } +body[data-theme="light"] .hydration-widget__info button { color:#875819; } +body[data-theme="light"] .hydration-widget__error { color:#a33d2e; } +body[data-theme="light"] .hydration-widget__week { border-color:#d2e2d4; } +body[data-theme="light"] .hydration-widget__day--none { color:#783b34; background:#f2d9d5; } +body[data-theme="light"] .hydration-widget__day--partial { color:#704915; background:#f4e1b9; } +body[data-theme="light"] .hydration-widget__day--goal { color:#245537; background:#d2ead7; } +body[data-theme="light"] .hydration-widget__day--today { outline-color:#537c60; } +body[data-theme="light"] .hydration-widget button:focus-visible, body[data-theme="light"] .hydration-widget summary:focus-visible, body[data-theme="light"] .hydration-widget input:focus-visible { outline-color:#376e49; } +.ntfy-check { display: flex; align-items: center; gap: .6rem; } +.ntfy-check label { margin: 0; } +#ntfy-url { width: 100%; box-sizing: border-box; min-height: 2.8rem; } +.ntfy-result { margin: 0; padding: .75rem; border-radius: .55rem; } +.ntfy-result--success { color: #14532d; background: #d1fae5; } +.ntfy-result--error { color: #7f1d1d; background: #fee2e2; } + +.gitea-activity { + margin-top: 30px; + padding: 25px 29px; + border: 1px solid $line; + border-radius: 20px; + background: $surface; + box-shadow: $shadow; +} +.gitea-activity__header { display: flex; justify-content: space-between; align-items: end; gap: 18px; } +.gitea-activity__header h2 { margin: 0; font-size: 1.7rem; } +.gitea-activity__header .eyebrow { margin-bottom: 4px; } +.gitea-activity__summary, .gitea-activity__message { margin: 8px 0 20px; color: $muted; font-size: .9rem; } +.gitea-activity__summary strong { color: $forest; font-size: 1.1rem; } +.gitea-activity__scroller { max-width: 100%; overflow-x: auto; padding-bottom: 8px; } +.gitea-activity__chart { display: flex; gap: 3px; width: max-content; } +.gitea-activity__week, .gitea-activity__day-labels { display: grid; grid-template-rows: 17px repeat(7, 10px); gap: 3px; } +.gitea-activity__week { width: 10px; } +.gitea-activity__day-labels { width: 27px; margin-right: 2px; color: $muted; font-size: .65rem; line-height: 10px; } +.gitea-activity__month { height: 17px; white-space: nowrap; color: $muted; font-size: .69rem; line-height: 14px; } +.gitea-activity__cell { display: block; width: 10px; height: 10px; border-radius: 2px; background: #e9eee9; } +.gitea-activity__cell--1 { background: #b7dfc2; } +.gitea-activity__cell--2 { background: #77bd8d; } +.gitea-activity__cell--3 { background: #3f9564; } +.gitea-activity__cell--4 { background: #1f6544; } +.gitea-activity__cell--future { background: transparent; } +.gitea-activity__legend { display: flex; align-items: center; justify-content: end; gap: 4px; margin-top: 12px; color: $muted; font-size: .7rem; } +.gitea-activity__legend span:first-child { margin-right: 3px; } +.gitea-activity__legend span:last-child { margin-left: 3px; } +body[data-theme="dark"] .gitea-activity { border-color: #38443d; background: #202923; box-shadow: 0 18px 45px rgba(0, 0, 0, .22); } +body[data-theme="dark"] .gitea-activity__summary, +body[data-theme="dark"] .gitea-activity__message, +body[data-theme="dark"] .gitea-activity__month, +body[data-theme="dark"] .gitea-activity__day-labels, +body[data-theme="dark"] .gitea-activity__legend { color: #b8c3bb; } +body[data-theme="dark"] .gitea-activity__summary strong { color: #9bd5ae; } +body[data-theme="dark"] .gitea-activity__cell--0 { background: #303a33; } +body[data-theme="dark"] .gitea-activity__cell--future { background: transparent; } +@media (max-width: 560px) { .gitea-activity { padding: 22px; }.gitea-activity__header { align-items: start; }.gitea-activity__header h2 { font-size: 1.45rem; } } diff --git a/main/planner/forms.py b/main/planner/forms.py index 6d3edc6..5521d0f 100644 --- a/main/planner/forms.py +++ b/main/planner/forms.py @@ -145,6 +145,34 @@ class UserSettingsForm(forms.ModelForm): } +class NtfySettingsForm(forms.ModelForm): + class Meta: + model = UserSettings + fields = ('ntfy_url', 'ntfy_enabled') + widgets = {'ntfy_url': forms.URLInput(attrs={'id': 'ntfy-url', 'placeholder': 'https://ntfy.example.com/my-topic'})} + + def clean_ntfy_url(self): + return self.cleaned_data['ntfy_url'].strip() + + def clean(self): + data = super().clean() + if data.get('ntfy_enabled') and not data.get('ntfy_url'): + self.add_error('ntfy_url', 'Enter a topic URL before enabling notifications.') + return data + + +class HydrationGoalForm(forms.ModelForm): + class Meta: + model = UserSettings + fields = ('daily_water_goal_ml',) + labels = {'daily_water_goal_ml': 'Daily water goal (ml)'} + widgets = {'daily_water_goal_ml': forms.NumberInput(attrs={'min': 250, 'max': 10000, 'step': 1})} + + +class WaterIntakeForm(forms.Form): + amount_ml = forms.IntegerField(min_value=1, max_value=3000) + + class SickDaySettingsForm(forms.ModelForm): class Meta: model = SickDaySettings diff --git a/main/planner/management/commands/notify_fasting_phases.py b/main/planner/management/commands/notify_fasting_phases.py new file mode 100644 index 0000000..baea59e --- /dev/null +++ b/main/planner/management/commands/notify_fasting_phases.py @@ -0,0 +1,11 @@ +from django.core.management.base import BaseCommand + +from planner.services.fasting_notifications import notify_fasting_phase_changes + + +class Command(BaseCommand): + help = 'Send ntfy notifications for fasting and eating phase changes.' + + def handle(self, *args, **options): + delivered = notify_fasting_phase_changes() + self.stdout.write(f'Delivered {delivered} fasting phase notification(s).') diff --git a/main/planner/migrations/0016_usersettings_daily_water_goal_ml_waterintakeentry.py b/main/planner/migrations/0016_usersettings_daily_water_goal_ml_waterintakeentry.py new file mode 100644 index 0000000..36bf7d7 --- /dev/null +++ b/main/planner/migrations/0016_usersettings_daily_water_goal_ml_waterintakeentry.py @@ -0,0 +1,36 @@ +# Generated by Django 6.1.1 on 2026-10-02 19:50 + +import django.core.validators +import django.db.models.deletion +import django.utils.timezone +from django.conf import settings +from django.db import migrations, models + + +class Migration(migrations.Migration): + + dependencies = [ + ('planner', '0015_bowelhealthcheckin_toothbrushing'), + migrations.swappable_dependency(settings.AUTH_USER_MODEL), + ] + + operations = [ + migrations.AddField( + model_name='usersettings', + name='daily_water_goal_ml', + field=models.PositiveIntegerField(default=2000, validators=[django.core.validators.MinValueValidator(250), django.core.validators.MaxValueValidator(10000)]), + ), + migrations.CreateModel( + name='WaterIntakeEntry', + fields=[ + ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('amount_ml', models.PositiveIntegerField(validators=[django.core.validators.MinValueValidator(1), django.core.validators.MaxValueValidator(3000)])), + ('recorded_at', models.DateTimeField(db_index=True, default=django.utils.timezone.now)), + ('created_at', models.DateTimeField(auto_now_add=True)), + ('user', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='water_entries', to=settings.AUTH_USER_MODEL)), + ], + options={ + 'ordering': ('-recorded_at', '-pk'), + }, + ), + ] diff --git a/main/planner/migrations/0017_usersettings_ntfy.py b/main/planner/migrations/0017_usersettings_ntfy.py new file mode 100644 index 0000000..09af4c0 --- /dev/null +++ b/main/planner/migrations/0017_usersettings_ntfy.py @@ -0,0 +1,11 @@ +from django.db import migrations, models + + +class Migration(migrations.Migration): + dependencies = [('planner', '0016_usersettings_daily_water_goal_ml_waterintakeentry')] + + operations = [ + migrations.AddField(model_name='usersettings', name='ntfy_url', field=models.URLField(blank=True)), + migrations.AddField(model_name='usersettings', name='ntfy_enabled', field=models.BooleanField(default=False)), + migrations.AddField(model_name='usersettings', name='ntfy_last_tested_at', field=models.DateTimeField(blank=True, null=True)), + ] diff --git a/main/planner/migrations/0018_fastingsettings_last_phase_notification_at.py b/main/planner/migrations/0018_fastingsettings_last_phase_notification_at.py new file mode 100644 index 0000000..b7442d2 --- /dev/null +++ b/main/planner/migrations/0018_fastingsettings_last_phase_notification_at.py @@ -0,0 +1,12 @@ +from django.db import migrations, models + + +class Migration(migrations.Migration): + dependencies = [('planner', '0017_usersettings_ntfy')] + + operations = [ + migrations.AddField( + model_name='fastingsettings', name='last_phase_notification_at', + field=models.DateTimeField(blank=True, null=True), + ), + ] diff --git a/main/planner/models.py b/main/planner/models.py index 00584df..3e4b5b2 100644 --- a/main/planner/models.py +++ b/main/planner/models.py @@ -5,6 +5,7 @@ from django.core.exceptions import ValidationError from django.core.validators import MaxValueValidator, MinValueValidator from django.db import models from django.urls import reverse +from django.utils import timezone class Task(models.Model): @@ -116,6 +117,12 @@ class UserSettings(models.Model): ) onboarding_enabled = models.BooleanField(default=True) onboarding_step = models.PositiveSmallIntegerField(default=0) + daily_water_goal_ml = models.PositiveIntegerField( + default=2000, validators=[MinValueValidator(250), MaxValueValidator(10000)], + ) + ntfy_url = models.URLField(blank=True) + ntfy_enabled = models.BooleanField(default=False) + ntfy_last_tested_at = models.DateTimeField(null=True, blank=True) created_at = models.DateTimeField(auto_now_add=True) updated_at = models.DateTimeField(auto_now=True) @@ -341,6 +348,7 @@ class FastingSettings(models.Model): validators=[MinValueValidator(1), MaxValueValidator((24 * 60) - 1)], ) tracking_started_at = models.DateTimeField(blank=True, null=True) + last_phase_notification_at = models.DateTimeField(blank=True, null=True) created_at = models.DateTimeField(auto_now_add=True) updated_at = models.DateTimeField(auto_now=True) @@ -366,6 +374,16 @@ class FastingPause(models.Model): return f'Fasting pause for {self.user} at {self.paused_at}' +class WaterIntakeEntry(models.Model): + user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name='water_entries') + amount_ml = models.PositiveIntegerField(validators=[MinValueValidator(1), MaxValueValidator(3000)]) + recorded_at = models.DateTimeField(default=timezone.now, db_index=True) + created_at = models.DateTimeField(auto_now_add=True) + + class Meta: + ordering = ('-recorded_at', '-pk') + + class FastingPeriod(models.Model): class Status(models.TextChoices): COMPLETED = 'completed', 'Completed' diff --git a/main/planner/services/fasting.py b/main/planner/services/fasting.py index ff54ffe..c53892b 100644 --- a/main/planner/services/fasting.py +++ b/main/planner/services/fasting.py @@ -113,6 +113,7 @@ def configure_fasting( 'fasting_start_time': fasting_start_time, 'fasting_duration_minutes': fasting_duration_minutes, 'tracking_started_at': now if enabled else None, + 'last_phase_notification_at': now, }, ) if created: @@ -121,9 +122,16 @@ def configure_fasting( return settings was_enabled = settings.enabled + schedule_changed = ( + settings.fasting_start_time != fasting_start_time + or settings.fasting_duration_minutes != fasting_duration_minutes + or was_enabled != enabled + ) settings.fasting_start_time = fasting_start_time settings.fasting_duration_minutes = fasting_duration_minutes settings.enabled = enabled + if schedule_changed: + settings.last_phase_notification_at = now if enabled and settings.tracking_started_at is None: settings.tracking_started_at = now settings.save() diff --git a/main/planner/services/fasting_notifications.py b/main/planner/services/fasting_notifications.py new file mode 100644 index 0000000..c15175b --- /dev/null +++ b/main/planner/services/fasting_notifications.py @@ -0,0 +1,43 @@ +"""Deliver the latest fasting phase transition once per tracked schedule.""" + +import logging + +from django.db import transaction +from django.utils import timezone + +from planner.models import FastingSettings +from planner.services.fasting import current_fasting_phase +from planner.services.notifications import NotificationError, send_notification + +logger = logging.getLogger(__name__) + + +def notify_fasting_phase_changes(now=None): + now = now or timezone.now() + delivered = 0 + for settings_id in FastingSettings.objects.filter(enabled=True).values_list('pk', flat=True): + with transaction.atomic(): + settings = FastingSettings.objects.select_for_update().select_related('user').get(pk=settings_id) + if not settings.enabled: + continue + phase = current_fasting_phase(settings, now) + boundary = phase.cycle_start + cursor = settings.last_phase_notification_at + if cursor is None: + # Existing configurations start at the current phase without a catch-up alert. + settings.last_phase_notification_at = now + settings.save(update_fields=['last_phase_notification_at']) + continue + if boundary <= cursor or boundary > now: + continue + title = 'Fasting started' if phase.is_fasting else 'Eating window started' + message = 'Your fasting window has started.' if phase.is_fasting else 'Your eating window is open.' + try: + sent = send_notification(settings.user, title, message) + except NotificationError: + logger.warning('Could not deliver fasting phase notification for user %s.', settings.user_id) + continue + settings.last_phase_notification_at = boundary + settings.save(update_fields=['last_phase_notification_at']) + delivered += int(sent) + return delivered diff --git a/main/planner/services/gitea_activity.py b/main/planner/services/gitea_activity.py new file mode 100644 index 0000000..49c87d4 --- /dev/null +++ b/main/planner/services/gitea_activity.py @@ -0,0 +1,87 @@ +"""Fetch and shape a Gitea user's contribution heatmap for the dashboard.""" + +from datetime import datetime, timedelta, timezone as utc_timezone +import json +from urllib.error import HTTPError, URLError +from urllib.parse import quote +from urllib.request import Request, urlopen + +from django.conf import settings +from django.core.cache import cache +from django.utils import timezone + +HEATMAP_CACHE_SECONDS = 15 * 60 + + +def fetch_heatmap(): + username = settings.GITEA_USERNAME + if not username: + return None + key = f'gitea-heatmap:{settings.GITEA_BASE_URL}:{username}' + cached = cache.get(key) + if cached is not None: + return cached + url = f'{settings.GITEA_BASE_URL}/api/v1/users/{quote(username, safe="")}/heatmap' + headers = {'Accept': 'application/json'} + if settings.GITEA_TOKEN: + headers['Authorization'] = f'token {settings.GITEA_TOKEN}' + try: + with urlopen(Request(url, headers=headers), timeout=4) as response: + data = json.load(response) + except (HTTPError, URLError, TimeoutError, OSError, ValueError): + return None + if not isinstance(data, list): + return None + cache.set(key, data, HEATMAP_CACHE_SECONDS) + return data + + +def activity_level(count): + if count <= 0: + return 0 + if count == 1: + return 1 + if count <= 3: + return 2 + if count <= 6: + return 3 + return 4 + + +def activity_context(today=None): + """Return 53 Sunday-first weeks ending in the current week.""" + today = today or timezone.localdate() + data = fetch_heatmap() + if data is None: + return {'activity_unavailable': True} + counts = {} + for item in data: + try: + day = datetime.fromtimestamp(item['timestamp'], utc_timezone.utc).date() + count = max(0, int(item['contributions'])) + except (KeyError, TypeError, ValueError, OverflowError, OSError): + continue + counts[day] = count + first = today - timedelta(days=364) + first -= timedelta(days=(first.weekday() + 1) % 7) + weeks = [] + total = 0 + for week_number in range(53): + week_start = first + timedelta(days=week_number * 7) + week = [] + for weekday in range(7): + day = week_start + timedelta(days=weekday) + count = counts.get(day, 0) if day <= today else 0 + if day <= today and day >= today - timedelta(days=364): + total += count + week.append({ + 'date': day, 'count': count, 'level': activity_level(count), + 'future': day > today, + }) + month = week_start.strftime('%b') if week_number == 0 or week_start.month != (week_start - timedelta(days=7)).month else '' + weeks.append({'days': week, 'month': month}) + return { + 'activity_weeks': weeks, + 'activity_total': total, 'activity_username': settings.GITEA_USERNAME, + 'activity_profile_url': f'{settings.GITEA_BASE_URL}/{quote(settings.GITEA_USERNAME, safe="")}', + } diff --git a/main/planner/services/hydration.py b/main/planner/services/hydration.py new file mode 100644 index 0000000..2cd22a0 --- /dev/null +++ b/main/planner/services/hydration.py @@ -0,0 +1,41 @@ +from datetime import datetime, time, timedelta + +from django.utils import timezone + +from planner.models import UserSettings, WaterIntakeEntry +from planner.timezones import timezone_for_user + + +def hydration_context(user, now=None): + zone = timezone_for_user(user) + today = timezone.localtime(now or timezone.now(), zone).date() + start = today - timedelta(days=today.weekday()) + week_start = timezone.make_aware(datetime.combine(start, time.min), zone) + week_end = timezone.make_aware(datetime.combine(start + timedelta(days=7), time.min), zone) + goal = UserSettings.objects.get_or_create(user=user)[0].daily_water_goal_ml + entries = WaterIntakeEntry.objects.filter(user=user, recorded_at__gte=week_start, recorded_at__lt=week_end) + totals = {start + timedelta(days=i): 0 for i in range(7)} + for entry in entries: + totals[timezone.localtime(entry.recorded_at, zone).date()] += entry.amount_ml + total = totals[today] + last = entries.filter( + recorded_at__gte=timezone.make_aware(datetime.combine(today, time.min), zone), + recorded_at__lt=timezone.make_aware(datetime.combine(today + timedelta(days=1), time.min), zone), + ).order_by('-recorded_at', '-pk').first() + percent = round(total * 100 / goal) + visual = min(100, percent) + days = [] + for day, amount in totals.items(): + state = 'none' if amount == 0 else ('goal' if amount >= goal else 'partial') + days.append({'date': day, 'label': day.strftime('%a')[0], 'total': amount, + 'state': state, 'state_label': {'none': 'no water logged', 'partial': 'partial goal', 'goal': 'goal met'}[state], + 'today': day == today}) + return {'hydration_total': total, 'hydration_goal': goal, 'hydration_percent': percent, + 'hydration_visual': visual, 'hydration_fill_y': 168 - round(visual * 1.22), + 'hydration_fill_height': round(visual * 1.22), 'hydration_last': last, + 'hydration_last_time': timezone.localtime(last.recorded_at, zone).strftime('%H:%M') if last else None, + 'hydration_zone': zone, 'hydration_days': days, + 'hydration_markers': [ + {'y': 46, 'value': goal}, {'y': 77, 'value': round(goal * .75)}, + {'y': 107, 'value': round(goal * .5)}, {'y': 138, 'value': round(goal * .25)}, + ]} diff --git a/main/planner/services/notifications.py b/main/planner/services/notifications.py new file mode 100644 index 0000000..04bee3d --- /dev/null +++ b/main/planner/services/notifications.py @@ -0,0 +1,37 @@ +import socket +from urllib.error import HTTPError, URLError +from urllib.request import Request, urlopen + +from planner.models import UserSettings + + +class NotificationError(Exception): + """A delivery error safe to display without exposing the topic URL.""" + + +def send_ntfy_notification(url, title, message, timeout=10): + request = Request( + url, + data=message.encode('utf-8'), + headers={'Content-Type': 'text/plain; charset=utf-8', 'Title': title}, + method='POST', + ) + try: + with urlopen(request, timeout=timeout) as response: + status = response.getcode() + except HTTPError as error: + raise NotificationError(f'ntfy server responded with HTTP {error.code}.') from error + except (TimeoutError, socket.timeout): + raise NotificationError('Connection to the ntfy server timed out.') from None + except (URLError, OSError): + raise NotificationError('Could not connect to the ntfy server.') from None + if not 200 <= status < 300: + raise NotificationError(f'ntfy server responded with HTTP {status}.') + + +def send_notification(user, title, message): + preferences = UserSettings.objects.filter(user=user).first() + if not preferences or not preferences.ntfy_enabled or not preferences.ntfy_url: + return False + send_ntfy_notification(preferences.ntfy_url, title, message) + return True diff --git a/main/planner/templates/planner/health.html b/main/planner/templates/planner/health.html index ab115e6..d10a8cc 100644 --- a/main/planner/templates/planner/health.html +++ b/main/planner/templates/planner/health.html @@ -11,7 +11,13 @@
- {% include 'planner/partials/neck_headache_checkin.html' %} - {% include 'planner/partials/bowel_health_checkin.html' %} +
+ {% include 'planner/partials/neck_headache_checkin.html' %} + {% include 'planner/partials/bowel_health_checkin.html' %} +
+
{% endblock %} diff --git a/main/planner/templates/planner/partials/gitea_activity.html b/main/planner/templates/planner/partials/gitea_activity.html new file mode 100644 index 0000000..e6d66ef --- /dev/null +++ b/main/planner/templates/planner/partials/gitea_activity.html @@ -0,0 +1,23 @@ +
+
+

Code garden

Gitea activity

+ {% if activity_profile_url %}View profile on Gitea{% endif %} +
+ {% if activity_unavailable %} +

Activity is unavailable right now.

+ {% else %} +

{{ activity_total }} contributions in the last year

+
+ +
+ + {% endif %} +
diff --git a/main/planner/templates/planner/partials/hydration_bottle.html b/main/planner/templates/planner/partials/hydration_bottle.html new file mode 100644 index 0000000..5dc5387 --- /dev/null +++ b/main/planner/templates/planner/partials/hydration_bottle.html @@ -0,0 +1,9 @@ + diff --git a/main/planner/templates/planner/partials/hydration_widget.html b/main/planner/templates/planner/partials/hydration_widget.html new file mode 100644 index 0000000..d4818da --- /dev/null +++ b/main/planner/templates/planner/partials/hydration_widget.html @@ -0,0 +1,19 @@ +
+

Daily hydration

+

Water

+
+
+

{{ hydration_total|floatformat:0 }} / {{ hydration_goal }} ml

+

{{ hydration_percent }}% of daily goal

+
+
+ {% include 'planner/partials/hydration_bottle.html' %} +
+
+
{% csrf_token %}
+
Other
{% csrf_token %}
+
+ {% if hydration_error %}{% endif %} +
{% if hydration_last %}Last: {{ hydration_last.amount_ml }} ml at {{ hydration_last_time }}
{% csrf_token %}
{% else %}No water logged today{% endif %}
+

This week

{% for day in hydration_days %}{{ day.label }}{% endfor %}
+
diff --git a/main/planner/templates/planner/partials/ntfy_test_result.html b/main/planner/templates/planner/partials/ntfy_test_result.html new file mode 100644 index 0000000..e3aa15d --- /dev/null +++ b/main/planner/templates/planner/partials/ntfy_test_result.html @@ -0,0 +1 @@ +{% if success %}

Test notification sent successfully.

{% else %}

Could not send the test notification: {{ error }}

{% endif %} diff --git a/main/planner/templates/planner/task_list.html b/main/planner/templates/planner/task_list.html index 1202ed1..0ad485a 100644 --- a/main/planner/templates/planner/task_list.html +++ b/main/planner/templates/planner/task_list.html @@ -41,11 +41,17 @@ {% include 'planner/partials/workout_section.html' %} + {% if gitea_activity_enabled %} +
+

Loading Gitea activity…

+
+ {% endif %} {% if user.is_authenticated %} {% endif %} diff --git a/main/planner/templates/planner/user_settings.html b/main/planner/templates/planner/user_settings.html index bdf78b1..c61840d 100644 --- a/main/planner/templates/planner/user_settings.html +++ b/main/planner/templates/planner/user_settings.html @@ -7,6 +7,18 @@

First-run help

{% if onboarding_enabled %}The guided tour is ready to continue on your dashboard.{% else %}Help is off. You can run the tour again whenever you want.{% endif %}

{% csrf_token %}

Location & weather

Location is optional and private. It is used only to retrieve your forecast.

{% csrf_token %}{% for field in profile_form %}
{{ field.label_tag }}{{ field }}{% if field.help_text %}{{ field.help_text }}{% endif %}{{ field.errors }}
{% endfor %}

Sick Day Mode

Temporarily defer routine work while you recover.

{% csrf_token %}{% for field in sick_form %}
{{ field.label_tag }}{{ field }}{% if field.help_text %}{{ field.help_text }}{% endif %}{{ field.errors }}
{% endfor %}
+

Hydration

Set your daily water goal.

{% csrf_token %}{% for field in hydration_goal_form %}
{{ field.label_tag }}{{ field }}{{ field.errors }}
{% endfor %}
+
+

Notifications / ntfy

+

Enter your private topic URL, test it, then enable notifications.

+
{% csrf_token %} +
{{ ntfy_form.ntfy_url.label_tag }}{{ ntfy_form.ntfy_url }}{{ ntfy_form.ntfy_url.errors }}
+
{{ ntfy_form.ntfy_enabled }}
+ +
+ +
+

Fasting

{% csrf_token %}{% for field in fasting_form %}
{{ field.label_tag }}{{ field }}{% if field.help_text %}{{ field.help_text }}{% endif %}{{ field.errors }}
{% endfor %}
{% endblock %} diff --git a/main/planner/test_fasting_notifications.py b/main/planner/test_fasting_notifications.py new file mode 100644 index 0000000..ebc9744 --- /dev/null +++ b/main/planner/test_fasting_notifications.py @@ -0,0 +1,57 @@ +from datetime import datetime, time +from unittest.mock import patch +from zoneinfo import ZoneInfo + +from django.contrib.auth import get_user_model +from django.test import TestCase + +from .models import FastingSettings +from .services.fasting import configure_fasting +from .services.fasting_notifications import notify_fasting_phase_changes +from .services.notifications import NotificationError + + +class FastingNotificationTests(TestCase): + def setUp(self): + self.user = get_user_model().objects.create_user(username='phase-user') + self.at = lambda hour, minute=0: datetime(2026, 10, 3, hour, minute, tzinfo=ZoneInfo('Europe/Amsterdam')) + configure_fasting( + self.user, enabled=True, fasting_start_time=time(20), + fasting_duration_minutes=16 * 60, now=self.at(13), + ) + + @patch('planner.services.fasting_notifications.send_notification', return_value=True) + def test_each_phase_is_sent_once(self, sender): + self.assertEqual(notify_fasting_phase_changes(self.at(19, 59)), 0) + self.assertEqual(notify_fasting_phase_changes(self.at(20)), 1) + self.assertEqual(notify_fasting_phase_changes(self.at(20, 1)), 0) + self.assertEqual(notify_fasting_phase_changes(datetime(2026, 10, 4, 12, tzinfo=ZoneInfo('Europe/Amsterdam'))), 1) + self.assertEqual(sender.call_count, 2) + self.assertEqual(sender.call_args.args[1], 'Eating window started') + + @patch('planner.services.fasting_notifications.send_notification', side_effect=[NotificationError('failed'), True]) + def test_delivery_failure_is_retried(self, sender): + self.assertEqual(notify_fasting_phase_changes(self.at(20)), 0) + self.assertEqual(notify_fasting_phase_changes(self.at(20, 1)), 1) + self.assertEqual(sender.call_count, 2) + + @patch('planner.services.fasting_notifications.send_notification', return_value=True) + def test_paused_tracking_and_schedule_changes_do_not_send_old_transition(self, sender): + configure_fasting( + self.user, enabled=False, fasting_start_time=time(20), + fasting_duration_minutes=16 * 60, now=self.at(19), + ) + self.assertEqual(notify_fasting_phase_changes(self.at(20)), 0) + configure_fasting( + self.user, enabled=True, fasting_start_time=time(20), + fasting_duration_minutes=16 * 60, now=self.at(21), + ) + self.assertEqual(notify_fasting_phase_changes(self.at(21, 1)), 0) + sender.assert_not_called() + + @patch('planner.services.fasting_notifications.send_notification', return_value=False) + def test_disabled_ntfy_does_not_queue_old_phase_for_later(self, sender): + self.assertEqual(notify_fasting_phase_changes(self.at(20)), 0) + self.assertEqual(notify_fasting_phase_changes(self.at(20, 1)), 0) + self.assertEqual(sender.call_count, 1) + self.assertEqual(FastingSettings.objects.get(user=self.user).last_phase_notification_at, self.at(20)) diff --git a/main/planner/test_gitea_activity.py b/main/planner/test_gitea_activity.py new file mode 100644 index 0000000..ede3749 --- /dev/null +++ b/main/planner/test_gitea_activity.py @@ -0,0 +1,60 @@ +from datetime import date, datetime, timezone +from io import BytesIO +import json +from unittest.mock import patch + +from django.contrib.auth import get_user_model +from django.core.cache import cache +from django.test import TestCase, override_settings +from django.urls import reverse + +from .services.gitea_activity import activity_context, fetch_heatmap + + +@override_settings(GITEA_BASE_URL='https://git.example.com', GITEA_USERNAME='coder', GITEA_TOKEN='private-token') +class GiteaActivityTests(TestCase): + def setUp(self): + cache.clear() + + @patch('planner.services.gitea_activity.urlopen') + def test_fetch_uses_server_side_token_and_cache(self, open_url): + timestamp = int(datetime(2026, 10, 3, tzinfo=timezone.utc).timestamp()) + open_url.return_value.__enter__.return_value = BytesIO(json.dumps([ + {'timestamp': timestamp, 'contributions': 7}, + ]).encode()) + context = activity_context(date(2026, 10, 3)) + self.assertEqual(context['activity_total'], 7) + self.assertEqual(context['activity_weeks'][-1]['days'][-1]['level'], 4) + request = open_url.call_args.args[0] + self.assertEqual(request.get_header('Authorization'), 'token private-token') + self.assertEqual(request.full_url, 'https://git.example.com/api/v1/users/coder/heatmap') + fetch_heatmap() + self.assertEqual(open_url.call_count, 1) + + @patch('planner.services.gitea_activity.urlopen', side_effect=OSError('offline')) + def test_api_failure_is_a_widget_message(self, open_url): + self.assertTrue(activity_context(date(2026, 10, 3))['activity_unavailable']) + + @patch('planner.services.gitea_activity.urlopen') + def test_widget_renders_contribution_cells(self, open_url): + timestamp = int(datetime(2026, 10, 3, tzinfo=timezone.utc).timestamp()) + open_url.return_value.__enter__.return_value = BytesIO(json.dumps([ + {'timestamp': timestamp, 'contributions': 7}, + ]).encode()) + user = get_user_model().objects.create_user(username='chart-user') + self.client.force_login(user) + response = self.client.get(reverse('planner:gitea-activity')) + self.assertContains(response, '7 contributions') + self.assertContains(response, '2026-10-03') + self.assertContains(response, 'gitea-activity__cell--4') + + @patch('planner.views.activity_context', return_value={'activity_unavailable': True}) + def test_widget_requires_login_and_is_below_workout(self, context): + url = reverse('planner:gitea-activity') + self.assertEqual(self.client.get(url).status_code, 302) + user = get_user_model().objects.create_user(username='dashboard-user') + self.client.force_login(user) + response = self.client.get(reverse('planner:task-list')) + html = response.content.decode() + self.assertLess(html.index('id="workout-section"'), html.index('id="gitea-activity"')) + self.assertContains(self.client.get(url), 'Activity is unavailable right now.') diff --git a/main/planner/test_ntfy.py b/main/planner/test_ntfy.py new file mode 100644 index 0000000..c426cf0 --- /dev/null +++ b/main/planner/test_ntfy.py @@ -0,0 +1,49 @@ +from unittest.mock import Mock, patch + +from django.contrib.auth import get_user_model +from django.test import TestCase +from django.urls import reverse + +from .models import UserSettings +from .services.notifications import NotificationError, send_notification + + +class NtfySettingsTests(TestCase): + def setUp(self): + self.user = get_user_model().objects.create_user(username='ntfy-user', password='test-password') + self.client.force_login(self.user) + self.settings_url = reverse('planner:user-settings') + self.test_url = reverse('planner:ntfy-test') + self.topic = 'https://ntfy.example.com/private-topic' + + def save(self, url=None, enabled=True): + return self.client.post(self.settings_url, { + 'section': 'ntfy', 'ntfy_url': self.topic if url is None else url, + 'ntfy_enabled': 'on' if enabled else '', + }) + + def test_enable_requires_successful_test(self): + response = self.save() + self.assertContains(response, 'Test this URL successfully') + self.assertFalse(UserSettings.objects.get(user=self.user).ntfy_enabled) + + @patch('planner.views.send_ntfy_notification') + def test_successful_test_allows_enable_and_changed_url_requires_retest(self, sender): + self.assertEqual(self.client.post(self.test_url, {'ntfy_url': 'invalid'}).status_code, 400) + self.assertEqual(self.client.post(self.test_url, {'ntfy_url': self.topic}).status_code, 200) + sender.assert_called_once() + self.assertEqual(self.save().status_code, 302) + preferences = UserSettings.objects.get(user=self.user) + self.assertTrue(preferences.ntfy_enabled) + self.assertIsNotNone(preferences.ntfy_last_tested_at) + self.assertContains(self.save(url='https://ntfy.example.com/other'), 'Test this URL successfully') + + @patch('planner.views.send_ntfy_notification', side_effect=NotificationError('Could not connect.')) + def test_failed_test_does_not_allow_enable(self, sender): + self.assertEqual(self.client.post(self.test_url, {'ntfy_url': self.topic}).status_code, 502) + self.assertContains(self.save(), 'Test this URL successfully') + + @patch('planner.services.notifications.send_ntfy_notification') + def test_disabled_preference_suppresses_delivery(self, sender): + self.assertFalse(send_notification(self.user, 'Title', 'Message')) + sender.assert_not_called() diff --git a/main/planner/tests.py b/main/planner/tests.py index 9b5f939..73fad91 100644 --- a/main/planner/tests.py +++ b/main/planner/tests.py @@ -9,6 +9,8 @@ from django.utils import timezone from django.urls import reverse from .models import FastingPause, FastingPeriod, FastingSettings, SickDaySettings, Task +from .models import UserSettings, WaterIntakeEntry +from .services.hydration import hydration_context from .forms import DAILY_FASTING_DURATION_CHOICES, FastingSettingsForm from .services.deferrals import ( apply_missed_task_deferrals, @@ -1511,3 +1513,48 @@ class TaskCompletionViewTests(TestCase): self.client.post(reverse('planner:task-toggle-completed', args=[foreign.pk])).status_code, 404, ) + +class HydrationWidgetTests(TestCase): + def setUp(self): + self.user = get_user_model().objects.create_user(username='hydration-user', password='test-password') + self.client.force_login(self.user) + UserSettings.objects.update_or_create(user=self.user, defaults={'daily_water_goal_ml': 500}) + + def test_entries_total_and_over_goal_visual_cap(self): + self.client.post(reverse('planner:hydration-add'), {'amount_ml': 250}) + self.client.post(reverse('planner:hydration-add'), {'amount_ml': 500}) + self.assertEqual(WaterIntakeEntry.objects.filter(user=self.user).count(), 2) + context = hydration_context(self.user) + self.assertEqual(context['hydration_total'], 750) + self.assertEqual(context['hydration_percent'], 150) + self.assertEqual(context['hydration_visual'], 100) + self.assertEqual(next(day for day in context['hydration_days'] if day['today'])['state'], 'goal') + + def test_health_page_reuses_widgets_and_live_hydration(self): + response = self.client.get(reverse('planner:health')) + self.assertContains(response, 'Health routines') + self.assertContains(response, 'id="fasting-widget"') + self.assertContains(response, 'id="hydration-widget"') + self.client.post(reverse('planner:hydration-add'), {'amount_ml': 250}) + self.assertContains(self.client.get(reverse('planner:health')), '250 / 500 ml', html=True) + + def test_undo_only_current_user_current_day(self): + other = get_user_model().objects.create_user(username='other-hydration-user') + WaterIntakeEntry.objects.create(user=other, amount_ml=500) + yesterday = timezone.now() - timedelta(days=1) + WaterIntakeEntry.objects.create(user=self.user, amount_ml=250, recorded_at=yesterday) + self.client.post(reverse('planner:hydration-add'), {'amount_ml': 500}) + self.client.post(reverse('planner:hydration-undo')) + self.assertEqual(hydration_context(self.user)['hydration_total'], 0) + self.assertEqual(WaterIntakeEntry.objects.filter(user=self.user).count(), 1) + self.assertEqual(WaterIntakeEntry.objects.filter(user=other).count(), 1) + + def test_week_rolls_forward_and_invalid_amount_is_rejected(self): + monday = timezone.now().astimezone(ZoneInfo('Europe/Amsterdam')) + monday = monday - timedelta(days=monday.weekday()) + prior_week = monday - timedelta(days=7) + WaterIntakeEntry.objects.create(user=self.user, amount_ml=500, recorded_at=prior_week) + self.assertTrue(all(day['state'] == 'none' for day in hydration_context(self.user)['hydration_days'])) + response = self.client.post(reverse('planner:hydration-add'), {'amount_ml': 3001}) + self.assertContains(response, 'Enter a whole amount') + self.assertEqual(WaterIntakeEntry.objects.filter(user=self.user).count(), 1) diff --git a/main/planner/urls.py b/main/planner/urls.py index 753fdd5..1bac465 100644 --- a/main/planner/urls.py +++ b/main/planner/urls.py @@ -8,7 +8,7 @@ from .views import ( TaskUpdateView, WorkoutCreateView, WorkoutUpdateView, delete_workout, fasting_configure, neck_headache_checkin_panel, fasting_toggle_tracking, fasting_widget, logout_view, register, toggle_task_active, toggle_task_completed, save_neck_headache_checkin, save_sleep_checkin, advance_onboarding, toggle_workout_completed, user_settings, workout_today, - bowel_health_panel, save_bowel_health_checkin, toggle_tooth_brushing, + bowel_health_panel, save_bowel_health_checkin, toggle_tooth_brushing, hydration_add, hydration_undo, test_ntfy, gitea_activity, ) app_name = 'planner' @@ -20,6 +20,8 @@ urlpatterns = [ path('register/', register, name='register'), path('logout/', logout_view, name='logout'), path('settings/', user_settings, name='user-settings'), + path('settings/notifications/ntfy/test/', test_ntfy, name='ntfy-test'), + path('gitea/activity/', gitea_activity, name='gitea-activity'), path('onboarding/advance/', advance_onboarding, name='onboarding-advance'), path('daily/', DailyPlannerView.as_view(), name='daily-planner'), path('fasting/widget/', fasting_widget, name='fasting-widget'), @@ -29,6 +31,8 @@ urlpatterns = [ path('check-ins/save/', save_neck_headache_checkin, name='neck-headache-checkin-save'), path('sleep-check-ins/save/', save_sleep_checkin, name='sleep-checkin-save'), path('teeth/toggle/', toggle_tooth_brushing, name='tooth-brushing-toggle'), + path('hydration/add/', hydration_add, name='hydration-add'), + path('hydration/undo/', hydration_undo, name='hydration-undo'), path('bowel-health/panel/', bowel_health_panel, name='bowel-health-panel'), path('bowel-health/save/', save_bowel_health_checkin, name='bowel-health-save'), path('check-ins/export//', export_pain_csv, name='pain-export'), diff --git a/main/planner/views.py b/main/planner/views.py index c4514ca..0609566 100644 --- a/main/planner/views.py +++ b/main/planner/views.py @@ -1,9 +1,13 @@ import calendar +from hashlib import sha256 from datetime import timedelta +from django.conf import settings from django.contrib import messages from django.contrib.auth import login, logout from django.contrib.auth.decorators import login_required +from django.core.exceptions import ValidationError +from django.core.validators import URLValidator from django.http import Http404, HttpResponse, JsonResponse from django.shortcuts import get_object_or_404, redirect, render from django.urls import reverse, reverse_lazy @@ -16,9 +20,12 @@ from django.views.generic import CreateView, DeleteView, DetailView, ListView, T from .forms import ( DailyPlannerForm, FastingSettingsForm, RegistrationForm, SickDaySettingsForm, SleepCheckInForm, TimeZoneSettingsForm, - BowelHealthCheckInForm, NeckHeadacheCheckInForm, TaskForm, UserSettingsForm, WorkoutForm, + BowelHealthCheckInForm, NeckHeadacheCheckInForm, TaskForm, UserSettingsForm, WorkoutForm, HydrationGoalForm, WaterIntakeForm, NtfySettingsForm, ) -from .models import BowelHealthCheckIn, FastingPeriod, FastingSettings, NeckHeadacheCheckIn, SickDaySettings, SleepCheckIn, Task, ToothBrushing, UserSettings, Workout +from .models import BowelHealthCheckIn, FastingPeriod, FastingSettings, NeckHeadacheCheckIn, SickDaySettings, SleepCheckIn, Task, ToothBrushing, UserSettings, Workout, WaterIntakeEntry +from .services.hydration import hydration_context +from .services.gitea_activity import activity_context +from .services.notifications import NotificationError, send_ntfy_notification from .services.checkins import ( ANNUAL_PHYSIOTHERAPY_SESSION_ALLOWANCE, LOW_PAIN_STREAK_THRESHOLD, calculate_check_in_streaks, ) @@ -513,11 +520,19 @@ class TaskListView(LoginRequiredMixin, ListView): context.update(dashboard_weather_context(self.request.user)) context.update(workout_context(self.request.user)) context.update(brushing_context(self.request.user)) + context.update(hydration_context(self.request.user)) + context['gitea_activity_enabled'] = bool(settings.GITEA_USERNAME) profile, _ = UserSettings.objects.get_or_create(user=self.request.user) context['onboarding_tour'] = onboarding_context(profile) return context +@login_required +@require_http_methods(['GET']) +def gitea_activity(request): + return render(request, 'planner/partials/gitea_activity.html', activity_context()) + + class HealthView(LoginRequiredMixin, TemplateView): template_name = 'planner/health.html' @@ -530,6 +545,8 @@ class HealthView(LoginRequiredMixin, TemplateView): context.update(bowel_context( self.request.user, selected_check_in_date(self.request.GET.get('bowel_date'), self.request.user), )) + context.update(fasting_widget_context(self.request.user)) + context.update(hydration_context(self.request.user)) return context @@ -735,9 +752,11 @@ def user_settings(request): sick_day, _ = SickDaySettings.objects.get_or_create(user=request.user) fasting = FastingSettings.objects.filter(user=request.user).first() profile_form = UserSettingsForm(instance=profile) + hydration_goal_form = HydrationGoalForm(instance=profile) sick_form = SickDaySettingsForm(instance=sick_day) fasting_form = FastingSettingsForm(instance=fasting) time_zone_form = TimeZoneSettingsForm(instance=profile) + ntfy_form = NtfySettingsForm(instance=profile) if request.method == 'POST': section = request.POST.get('section') @@ -747,6 +766,34 @@ def user_settings(request): profile_form.save() messages.success(request, 'Your weather location was saved.') return redirect('planner:user-settings') + elif section == 'hydration': + hydration_goal_form = HydrationGoalForm(request.POST, instance=profile) + if hydration_goal_form.is_valid(): + hydration_goal_form.save() + messages.success(request, 'Your daily water goal was saved.') + return redirect('planner:user-settings') + elif section == 'ntfy': + old_url = profile.ntfy_url + ntfy_form = NtfySettingsForm(request.POST, instance=profile) + if ntfy_form.is_valid(): + url = ntfy_form.cleaned_data['ntfy_url'] + tested = bool(url) and request.session.get(f'ntfy_tested:{request.user.pk}') == sha256(url.encode()).hexdigest() + previously_tested = url == old_url and profile.ntfy_last_tested_at is not None + if ntfy_form.cleaned_data['ntfy_enabled'] and not (tested or previously_tested): + ntfy_form.add_error('ntfy_url', 'Test this URL successfully before enabling notifications.') + else: + profile = ntfy_form.save(commit=False) + if not url: + profile.ntfy_enabled = False + profile.ntfy_last_tested_at = None + elif tested: + profile.ntfy_last_tested_at = timezone.now() + elif url != old_url: + profile.ntfy_last_tested_at = None + profile.save() + request.session.pop(f'ntfy_tested:{request.user.pk}', None) + messages.success(request, 'Notification settings were saved.') + return redirect('planner:user-settings') elif section == 'sick-day': sick_form = SickDaySettingsForm(request.POST, instance=sick_day) if sick_form.is_valid(): @@ -794,13 +841,51 @@ def user_settings(request): return render(request, 'planner/user_settings.html', { 'profile_form': profile_form, + 'hydration_goal_form': hydration_goal_form, 'sick_form': sick_form, 'fasting_form': fasting_form, 'time_zone_form': time_zone_form, + 'ntfy_form': ntfy_form, 'onboarding_enabled': profile.onboarding_enabled, }) +@login_required +@require_POST +def test_ntfy(request): + url = request.POST.get('ntfy_url', '').strip() + try: + URLValidator(schemes=['http', 'https'])(url) + except ValidationError: + return render(request, 'planner/partials/ntfy_test_result.html', {'error': 'Enter a valid HTTP or HTTPS topic URL.'}, status=400) + try: + send_ntfy_notification(url, 'Tasknest', 'Test notification sent successfully.') + except NotificationError as error: + return render(request, 'planner/partials/ntfy_test_result.html', {'error': str(error)}, status=502) + request.session[f'ntfy_tested:{request.user.pk}'] = sha256(url.encode()).hexdigest() + return render(request, 'planner/partials/ntfy_test_result.html', {'success': True}) + + +@login_required +@require_POST +def hydration_add(request): + form = WaterIntakeForm(request.POST) + if form.is_valid(): + WaterIntakeEntry.objects.create(user=request.user, amount_ml=form.cleaned_data['amount_ml']) + context = hydration_context(request.user) + context['hydration_error'] = form.errors.get('amount_ml') if not form.is_valid() else None + return render(request, 'planner/partials/hydration_widget.html', context) + + +@login_required +@require_POST +def hydration_undo(request): + context = hydration_context(request.user) + if context['hydration_last']: + context['hydration_last'].delete() + return render(request, 'planner/partials/hydration_widget.html', hydration_context(request.user)) + + @require_http_methods(['GET', 'POST']) def register(request): if request.user.is_authenticated: diff --git a/main/requirements.txt b/main/requirements.txt new file mode 100644 index 0000000..23d6153 --- /dev/null +++ b/main/requirements.txt @@ -0,0 +1,5 @@ +asarPy==1.0.1 +asgiref==3.12.1 +Django==6.1.1 +h3==4.5.0 +sqlparse==0.6.0 diff --git a/main/tasksnest/settings.py b/main/tasksnest/settings.py index 2ff809b..4327140 100644 --- a/main/tasksnest/settings.py +++ b/main/tasksnest/settings.py @@ -129,6 +129,30 @@ VITE_DEV_SERVER = os.environ.get('VITE_DEV_SERVER', 'http://localhost:5173') VITE_USE_DEV_SERVER = os.environ.get('VITE_USE_DEV_SERVER', str(DEBUG)).lower() in {'1', 'true', 'yes'} VITE_MANIFEST_PATH = BASE_DIR / 'planner' / 'static' / 'planner' / 'dist' / '.vite' / 'manifest.json' +# Optional Gitea contribution grid on the task dashboard. Read only these +# values from the repository's ignored .env file; the process environment wins. +def _gitea_env(name, default=''): + if name in os.environ: + return os.environ[name] + env_file = BASE_DIR.parent / '.env' + try: + lines = env_file.read_text(encoding='utf-8').splitlines() + except FileNotFoundError: + return default + for line in lines: + key, separator, value = line.strip().partition('=') + if separator and key.strip() == name: + value = value.strip() + if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}: + value = value[1:-1] + return value + return default + + +GITEA_BASE_URL = _gitea_env('GITEA_BASE_URL', 'https://git.jorendegraaf.eu').rstrip('/') +GITEA_USERNAME = _gitea_env('GITEA_USERNAME').strip() +GITEA_TOKEN = _gitea_env('GITEA_TOKEN').strip() + LOGIN_URL = 'planner:login' LOGIN_REDIRECT_URL = 'planner:task-list' LOGOUT_REDIRECT_URL = 'planner:login' diff --git a/tasksnest/bin/python b/tasksnest/bin/python index acd4152..d0391df 120000 --- a/tasksnest/bin/python +++ b/tasksnest/bin/python @@ -1 +1 @@ -/usr/bin/python \ No newline at end of file +/usr/bin/python3.13 \ No newline at end of file diff --git a/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/INSTALLER b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/INSTALLER new file mode 100644 index 0000000..a1b589e --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/INSTALLER @@ -0,0 +1 @@ +pip diff --git a/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/METADATA b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/METADATA new file mode 100644 index 0000000..0c53851 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/METADATA @@ -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 +Maintainer-Email: AJ Friend +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 + +H3 Logo + +# **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) + + +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 + + + +`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'} +``` diff --git a/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/RECORD b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/RECORD new file mode 100644 index 0000000..26b63ee --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/RECORD @@ -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 diff --git a/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/REQUESTED b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/REQUESTED new file mode 100644 index 0000000..e69de29 diff --git a/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/WHEEL b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/WHEEL new file mode 100644 index 0000000..8144362 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/WHEEL @@ -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 + diff --git a/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/licenses/LICENSE b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/licenses/LICENSE new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3-4.5.0.dist-info/licenses/LICENSE @@ -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. diff --git a/tasksnest/lib/python3.13/site-packages/h3/CMakeLists.txt b/tasksnest/lib/python3.13/site-packages/h3/CMakeLists.txt new file mode 100644 index 0000000..9d48e66 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/CMakeLists.txt @@ -0,0 +1 @@ +add_subdirectory(_cy) diff --git a/tasksnest/lib/python3.13/site-packages/h3/__init__.py b/tasksnest/lib/python3.13/site-packages/h3/__init__.py new file mode 100644 index 0000000..1e4f4b8 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/__init__.py @@ -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, +) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/CMakeLists.txt b/tasksnest/lib/python3.13/site-packages/h3/_cy/CMakeLists.txt new file mode 100644 index 0000000..2cb2b6f --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/CMakeLists.txt @@ -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 +) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/__init__.py b/tasksnest/lib/python3.13/site-packages/h3/_cy/__init__.py new file mode 100644 index 0000000..70fa087 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/__init__.py @@ -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, +) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/cells.pxd b/tasksnest/lib/python3.13/site-packages/h3/_cy/cells.pxd new file mode 100644 index 0000000..1bc31b8 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/cells.pxd @@ -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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/cells.pyx b/tasksnest/lib/python3.13/site-packages/h3/_cy/cells.pyx new file mode 100644 index 0000000..78d2561 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/cells.pyx @@ -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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/edges.pxd b/tasksnest/lib/python3.13/site-packages/h3/_cy/edges.pxd new file mode 100644 index 0000000..b7fcf84 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/edges.pxd @@ -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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/edges.pyx b/tasksnest/lib/python3.13/site-packages/h3/_cy/edges.pyx new file mode 100644 index 0000000..bd0aa7c --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/edges.pyx @@ -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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/error_system.pxd b/tasksnest/lib/python3.13/site-packages/h3/_cy/error_system.pxd new file mode 100644 index 0000000..4a1e3b4 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/error_system.pxd @@ -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() diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/error_system.pyx b/tasksnest/lib/python3.13/site-packages/h3/_cy/error_system.pyx new file mode 100644 index 0000000..fc18f46 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/error_system.pyx @@ -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) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/h3api.h b/tasksnest/lib/python3.13/site-packages/h3/_cy/h3api.h new file mode 100644 index 0000000..e882106 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/h3api.h @@ -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 +/* For size_t */ +#include + +/* + * 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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/h3lib.pxd b/tasksnest/lib/python3.13/site-packages/h3/_cy/h3lib.pxd new file mode 100644 index 0000000..6ee3b41 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/h3lib.pxd @@ -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) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/latlng.pxd b/tasksnest/lib/python3.13/site-packages/h3/_cy/latlng.pxd new file mode 100644 index 0000000..40dfc34 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/latlng.pxd @@ -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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/latlng.pyx b/tasksnest/lib/python3.13/site-packages/h3/_cy/latlng.pyx new file mode 100644 index 0000000..d83a9d3 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/latlng.pyx @@ -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 = 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 = 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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/memory.pxd b/tasksnest/lib/python3.13/site-packages/h3/_cy/memory.pxd new file mode 100644 index 0000000..5e259e2 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/memory.pxd @@ -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) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/memory.pyx b/tasksnest/lib/python3.13/site-packages/h3/_cy/memory.pyx new file mode 100644 index 0000000..0852105 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/memory.pyx @@ -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 (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 = 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 = 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 = 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 = h3_calloc(n, sizeof(int)) + if ptr is NULL: + raise MemoryError() + + arr = 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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/to_multipoly.pyx b/tasksnest/lib/python3.13/site-packages/h3/_cy/to_multipoly.pyx new file mode 100644 index 0000000..ed3e763 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/to_multipoly.pyx @@ -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) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/util.pxd b/tasksnest/lib/python3.13/site-packages/h3/_cy/util.pxd new file mode 100644 index 0000000..b584d3a --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/util.pxd @@ -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) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/util.pyx b/tasksnest/lib/python3.13/site-packages/h3/_cy/util.pyx new file mode 100644 index 0000000..9b070f9 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/util.pyx @@ -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) + ) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/vertex.pxd b/tasksnest/lib/python3.13/site-packages/h3/_cy/vertex.pxd new file mode 100644 index 0000000..98d890c --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/vertex.pxd @@ -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) diff --git a/tasksnest/lib/python3.13/site-packages/h3/_cy/vertex.pyx b/tasksnest/lib/python3.13/site-packages/h3/_cy/vertex.pyx new file mode 100644 index 0000000..26a674a --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_cy/vertex.pyx @@ -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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/_h3shape.py b/tasksnest/lib/python3.13/site-packages/h3/_h3shape.py new file mode 100644 index 0000000..5c36295 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_h3shape.py @@ -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)], + ... ) + + + 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)], + ... ) + + + 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)], + ... ) + + """ + 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 ''.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 = ''.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 + 1 , , ) + 1 (, , , , , , <... + """ + 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__ diff --git a/tasksnest/lib/python3.13/site-packages/h3/_version.py b/tasksnest/lib/python3.13/site-packages/h3/_version.py new file mode 100644 index 0000000..712565a --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/_version.py @@ -0,0 +1,3 @@ +from importlib import metadata + +__version__ = metadata.version(__package__ or __name__) diff --git a/tasksnest/lib/python3.13/site-packages/h3/api/__init__.py b/tasksnest/lib/python3.13/site-packages/h3/api/__init__.py new file mode 100644 index 0000000..435b13a --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/api/__init__.py @@ -0,0 +1,6 @@ +# flake8: noqa + +from . import basic_int +from . import basic_str +from . import memview_int +from . import numpy_int diff --git a/tasksnest/lib/python3.13/site-packages/h3/api/basic_int/__init__.py b/tasksnest/lib/python3.13/site-packages/h3/api/basic_int/__init__.py new file mode 100644 index 0000000..1086a63 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/api/basic_int/__init__.py @@ -0,0 +1,1369 @@ +# This file is **symlinked** across the APIs to ensure they are exactly the same. +from typing import Literal +from array import array + +from ... import _cy +from ..._h3shape import ( + H3Shape, + LatLngPoly, + LatLngMultiPoly, + geo_to_h3shape, + h3shape_to_geo, +) + +from ._convert import ( + _in_scalar, + _out_scalar, + _in_collection, + _out_collection, +) + + +def versions(): + """ + Version numbers for the Python (wrapper) and C (wrapped) libraries. + + Versions are output as strings of the form ``'X.Y.Z'``. + C and Python should match on ``X`` (major) and ``Y`` (minor), + but may differ on ``Z`` (patch). + + Returns + ------- + dict like ``{'c': 'X.Y.Z', 'python': 'A.B.C'}`` + """ + from ..._version import __version__ + + v = { + 'c': _cy.c_version(), + 'python': __version__, + } + + return v + + +def str_to_int(h): + """ + Converts a hexadecimal string to an H3 64-bit integer index. + + Parameters + ---------- + h : str + Hexadecimal string like ``'89754e64993ffff'`` + + Returns + ------- + int + Unsigned 64-bit integer + """ + return _cy.str_to_int(h) + + +def int_to_str(x): + """ + Converts an H3 64-bit integer index to a hexadecimal string. + + Parameters + ---------- + x : int + Unsigned 64-bit integer + + Returns + ------- + str + Hexadecimal string like ``'89754e64993ffff'`` + """ + return _cy.int_to_str(x) + + +def get_num_cells(res): + """ + Return the total number of *cells* (hexagons and pentagons) + for the given resolution. + + Returns + ------- + int + """ + return _cy.get_num_cells(res) + + +def average_hexagon_area(res, unit='km^2'): + """ + Return the average area of an H3 *hexagon* + for the given resolution. + + This average *excludes* pentagons. + + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) + + Returns + ------- + float + """ + return _cy.average_hexagon_area(res, unit) + + +def average_hexagon_edge_length(res, unit='km'): + """ + Return the average *hexagon* edge length + for the given resolution. + + This average *excludes* pentagons. + + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) + + Returns + ------- + float + """ + return _cy.average_hexagon_edge_length(res, unit) + + +def is_valid_index(h): + """Validates *any* H3 index (cell, vertex, or directed edge). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_index(h) + except (ValueError, TypeError): + return False + + +def is_valid_cell(h): + """ + Validates an H3 cell (hexagon or pentagon). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_cell(h) + except (ValueError, TypeError): + return False + + +def is_valid_directed_edge(edge): + """ + Validates an H3 directed edge. + + Returns + ------- + bool + """ + try: + e = _in_scalar(edge) + return _cy.is_valid_directed_edge(e) + except (ValueError, TypeError): + return False + + +def latlng_to_cell(lat, lng, res): + """ + Return the cell containing the (lat, lng) point + for a given resolution. + + Returns + ------- + H3Cell + + """ + return _out_scalar(_cy.latlng_to_cell(lat, lng, res)) + + +def cell_to_latlng(h): + """ + Return the center point of an H3 cell as a lat/lng pair. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + h = _in_scalar(h) + return _cy.cell_to_latlng(h) + + +def get_resolution(h): + """ + Return the resolution of an H3 cell. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + """ + # todo: could also work for edges + h = _in_scalar(h) + return _cy.get_resolution(h) + + +def cell_to_parent(h, res=None): + """ + Get the parent of a cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the parent + If ``None``, then ``res = resolution(h) - 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_parent(h, res) + p = _out_scalar(p) + + return p + + +def grid_distance(h1, h2): + """ + Compute the grid distance between two cells. + + The grid distance is defined as the length of the shortest + path between the cells in the graph formed by connecting + adjacent cells. + + This function will raise an exception if the + cells are too far apart to compute the distance. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + int + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + d = _cy.grid_distance(h1, h2) + + return d + + +def cell_to_boundary(h): + """ + Return tuple of lat/lng pairs describing the cell boundary. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + tuple of (lat, lng) tuples + """ + h = _in_scalar(h) + return _cy.cell_to_boundary(h) + + +def grid_disk(h, k=1): + """ + Return unordered collection of cells with grid distance ``<= k`` from ``h``. + That is, the "filled-in" disk. + + Parameters + ---------- + h : H3Cell + k : int + Size of disk. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.grid_disk(h, k) + + return _out_collection(mv) + + +def grid_ring(h, k=1): + """ + Return unordered collection of cells with grid distance ``== k`` from ``h``. + That is, the "hollow" ring. + + Parameters + ---------- + h : H3Cell + k : int + Size of ring. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.grid_ring(h, k) + + return _out_collection(mv) + + +def cell_to_children_size(h, res=None): + """ + Number of children at resolution ``res`` of given cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + int + Count of children + """ + h = _in_scalar(h) + return _cy.cell_to_children_size(h, res) + + +def cell_to_children(h, res=None): + """ + Children of a cell as an unordered collection. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.cell_to_children(h, res) + + return _out_collection(mv) + + +def cell_to_child_pos(child, res_parent): + """ + Child position index of given cell, with respect to its parent at ``res_parent``. + + The reverse operation can be done with ``child_pos_to_cell``. + + Parameters + ---------- + child : H3Cell + res_parent : int + + Returns + ------- + int + Integer index of the child with respect to parent cell. + """ + child = _in_scalar(child) + return _cy.cell_to_child_pos(child, res_parent) + + +def child_pos_to_cell(parent, res_child, child_pos): + """ + Get child H3 cell from a parent cell, child resolution, and child position index. + + The reverse operation can be done with ``cell_to_child_pos``. + + Parameters + ---------- + parent : H3Cell + res_child : int + Child cell resolution + child_pos : int + Integer position of child cell, releative to parent. + + + Returns + ------- + H3Cell + """ + parent = _in_scalar(parent) + child = _cy.child_pos_to_cell(parent, res_child, child_pos) + child = _out_scalar(child) + + return child + + +# todo: nogil for expensive C operation? +def compact_cells(cells): + """ + Compact a collection of H3 cells by combining + smaller cells into larger cells, if all child cells + are present. Input cells must all share the same resolution. + + Parameters + ---------- + cells : iterable of H3 Cells + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + hu = _in_collection(cells) + hc = _cy.compact_cells(hu) + + return _out_collection(hc) + + +def uncompact_cells(cells, res): + """ + Reverse the ``compact_cells`` operation. + + Return a collection of H3 cells, all of resolution ``res``. + + Parameters + ---------- + cells : iterable of H3Cell + res : int + Resolution of desired output cells. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + # TODO: add test to make sure an error is returned when input contains cell + # smaller than output res. + + hc = _in_collection(cells) + hu = _cy.uncompact_cells(hc, res) + + return _out_collection(hu) + + +def polygon_to_cells(h3shape, res): + """ + Alias for ``h3shape_to_cells``. + """ + return h3shape_to_cells(h3shape, res) + + +def h3shape_to_cells(h3shape, res): + """ + Return the collection of H3 cells at a given resolution whose center points + are contained within an ``LatLngPoly`` or ``LatLngMultiPoly``. + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells(poly, 6) + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells(poly.outer, res=res, holes=poly.holes) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells(mpoly.polys, res=res) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) + + +def polygon_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): + """ + Alias for ``h3shape_to_cells_experimental``. + """ + return h3shape_to_cells_experimental(h3shape, res, contain) + + +def h3shape_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): + """ + Experimental function similar to ``h3shape_to_cells``, but with support for + multiple cell containment modes. + + Using ``contain='center'`` should give identical behavior as + ``h3shape_to_cells``. + + Note that this function is **experimental** and has no API stability gaurantees + across versions, so it may change in the future. + + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + contain : {'center', 'full', 'overlap', 'bbox_overlap'}, optional + Specifies the containment condition. + - 'center': Cell center is contained in shape + - 'full': Cell is fully contained in shape + - 'overlap': Cell is partially contained in shape + - 'bbox_overlap': Cell bounding box is partially contained in shape + + Default is 'center'. + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells_experimental(poly, 6, 'center') + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + contain_modes = { + 'center': 0, + 'full': 1, + 'overlap': 2, + 'bbox_overlap': 3, + } + + flag = contain_modes[contain] + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells_experimental( + poly.outer, + res = res, + holes = poly.holes, + flag = flag, + ) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flag=flag) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) + + +def cells_to_h3shape(cells, *, tight=True): + """ + Return an ``H3Shape`` describing the area covered by a collection of H3 cells. + Will return ``LatLngPoly`` or ``LatLngMultiPoly``. + + Parameters + ---------- + cells : iterable of H3 cells + tight : bool + If True, return ``LatLngPoly`` if possible. + If False, always return ``LatLngMultiPoly``. + + Returns + ------- + LatLngPoly | LatLngMultiPoly + + Examples + -------- + + >>> cells = ['8428309ffffffff', '842830dffffffff'] + >>> h3.cells_to_h3shape(cells, tight=True) + + >>> h3.cells_to_h3shape(cells, tight=False) + + """ + cells = _in_collection(cells) + mpoly = _cy.cells_to_multi_polygon(cells) + + polys = [LatLngPoly(*poly) for poly in mpoly] + out = LatLngMultiPoly(*polys) + + if tight and len(out) == 1: + out = out[0] + + return out + + +def geo_to_cells(geo, res): + """Convert from ``__geo_interface__`` to cells. + + Parameters + ---------- + geo : an object implementing ``__geo_interface__`` or a dictionary in that format. + Both ``LatLngPoly`` and ``LatLngMultiPoly`` implement the interface. + res : int + Resolution of desired output cells. + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h3shape = geo_to_h3shape(geo) + return h3shape_to_cells(h3shape, res) + + +def cells_to_geo(cells, tight=True): + """ + Convert from cells to a ``__geo_interface__`` dict. + + Parameters + ---------- + cells : iterable of H3 Cells + tight : bool + When ``True``, returns an ``LatLngPoly`` when possible. + When ``False``, always returns an ``LatLngMultiPoly``. + + Returns + ------- + dict + in `__geo_interface__` format + """ + h3shape = cells_to_h3shape(cells, tight=tight) + return h3shape_to_geo(h3shape) + + +def is_pentagon(h): + """ + Identify if an H3 cell is a pentagon. + + Parameters + ---------- + h : H3Index + + Returns + ------- + bool + ``True`` if input is a valid H3 cell which is a pentagon. + + Notes + ----- + A pentagon should *also* pass ``is_valid_cell()``. + Will return ``False`` for valid H3Edge. + """ + return _cy.is_pentagon(_in_scalar(h)) + + +def get_base_cell_number(h): + """ + Return the base cell *number* (``0`` to ``121``) of the given cell. + + The base cell *number* and the H3Index are two different representations + of the same cell: the parent cell of resolution ``0``. + + The base cell *number* is encoded within the corresponding + H3Index. + + todo: could work with edges + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + + Examples + -------- + >>> h = construct_cell(57, 2, 1, 4) + >>> h + '83728cfffffffff' + >> get_base_cell_number(h) + 57 + """ + return _cy.get_base_cell_number(_in_scalar(h)) + + +def get_index_digit(h, res): + """ + Get the index digit of a cell at the given resolution. + + Parameters + ---------- + h : H3Cell + Cell whose index digit will be returned. + res : int + Resolution (``>= 1``) at which to read the digit. + + Returns + ------- + int + The index digit at the requested resolution. + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) + >>> h + '830e8cfffffffff' + >>> get_index_digit(h, 1) + 2 + >>> get_index_digit(h, 2) + 1 + >>> get_index_digit(h, 3) + 4 + """ + return _cy.get_index_digit(_in_scalar(h), res) + + +def construct_cell(base_cell_number, *digits, res=None): + """ + Construct cell from base cell and digits. + + Parameters + ---------- + base_cell_number : int + Base cell *number* (``0`` to ``121``). + *digits : int + Sequence of index digits (``0`` to ``6``). + Length of digits will be the resulting resolution of the output cell. + res : int, optional + Resolution of the constructed cell. If provided, it must equal + ``len(digits)``; otherwise it is inferred from the number of digits. + + Returns + ------- + H3Cell + The constructed cell. + + Examples + -------- + >>> construct_cell(7, 2, 1, 4) # resolution 3 cell + '830e8cfffffffff' + + >>> construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + '841e057ffffffff' + + >>> construct_cell(15, 0, 0, 5, 3, res=4) + '841e057ffffffff' + """ + if (res is not None) and (len(digits) != res): + raise ValueError('Resolution must match number of digits.') + + digits = array('i', digits) + o = _cy.construct_cell(base_cell_number, digits) + return _out_scalar(o) + + +def deconstruct_cell(h): + """ + Deconstruct cell into base cell and digits. + + Parameters + ---------- + h : H3Cell + Cell to deconstruct. + + Returns + ------- + list of int + [base_cell_number, digit1, digit2, ..., digitN] + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) # resolution 3 cell + >>> h + '830e8cfffffffff' + >>> deconstruct_cell(h) + (7, 2, 1, 4) + + >>> h = construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + >>> h + '841e057ffffffff' + >>> deconstruct_cell(h) + (15, 0, 0, 5, 3) + >>> construct_cell(*deconstruct_cell(h), 0) == cell_to_center_child(h) + """ + res = get_resolution(h) + bc = get_base_cell_number(h) + digits = [get_index_digit(h, r + 1) for r in range(res)] + + return [bc, *digits] + + +def are_neighbor_cells(h1, h2): + """ + Returns ``True`` if ``h1`` and ``h2`` are neighboring cells. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + bool + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + return _cy.are_neighbor_cells(h1, h2) + + +def cells_to_directed_edge(origin, destination): + """ + Create an H3 Index denoting a unidirectional edge. + + The edge is constructed from neighboring cells ``origin`` and + ``destination``. + + Parameters + ---------- + origin : H3Cell + destination : H3Cell + + Raises + ------ + ValueError + When cells are not adjacent. + + Returns + ------- + H3Edge + """ + o = _in_scalar(origin) + d = _in_scalar(destination) + e = _cy.cells_to_directed_edge(o, d) + e = _out_scalar(e) + + return e + + +def get_directed_edge_origin(e): + """ + Origin cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + o = _cy.get_directed_edge_origin(e) + o = _out_scalar(o) + + return o + + +def get_directed_edge_destination(e): + """ + Destination cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + d = _cy.get_directed_edge_destination(e) + d = _out_scalar(d) + + return d + + +def directed_edge_to_cells(e): + """ + Return (origin, destination) tuple from H3 directed edge + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + Origin cell of edge + H3Cell + Destination cell of edge + """ + e = _in_scalar(e) + o, d = _cy.directed_edge_to_cells(e) + o, d = _out_scalar(o), _out_scalar(d) + + return o, d + + +def origin_to_directed_edges(origin): + """ + Return all directed edges starting from ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + + Returns + ------- + unordered collection of H3Edge + """ + mv = _cy.origin_to_directed_edges(_in_scalar(origin)) + + return _out_collection(mv) + + +def directed_edge_to_boundary(edge): + """ + Returns points representing the edge (line of points + describing the boundary between two cells). + + Parameters + ---------- + edge : H3Edge + + Returns + ------- + tuple of (lat, lng) tuples + """ + return _cy.directed_edge_to_boundary(_in_scalar(edge)) + + +def grid_path_cells(start, end): + """ + Returns the ordered collection of cells denoting a + minimum-length non-unique path between cells. + + Parameters + ---------- + start : H3Cell + end : H3Cell + + Returns + ------- + ordered collection of H3Cell + Starting with ``start``, and ending with ``end``. + """ + mv = _cy.grid_path_cells(_in_scalar(start), _in_scalar(end)) + + return _out_collection(mv) + + +def is_res_class_III(h): + """ + Determine if cell has orientation "Class II" or "Class III". + + The orientation of pentagons/hexagons on the icosahedron can be one + of two types: "Class II" or "Class III". + + All cells within a resolution have the same type, and the type + alternates between resolutions. + + "Class II" cells have resolutions: 0,2,4,6,8,10,12,14 + "Class III" cells have resolutions: 1,3,5,7,9,11,13,15 + + Parameters + ---------- + h : H3Cell + + Returns + ------- + bool + ``True`` if ``h`` is "Class III". + ``False`` if ``h`` is "Class II". + + References + ---------- + 1. https://uber.github.io/h3/#/documentation/core-library/coordinate-systems + """ + return _cy.is_res_class_iii(_in_scalar(h)) + + +def get_pentagons(res): + """ + Return all pentagons at a given resolution. + + Parameters + ---------- + res : int + Resolution of the pentagons + + Returns + ------- + unordered collection of H3Cell + """ + mv = _cy.get_pentagons(res) + + return _out_collection(mv) + + +def get_res0_cells(): + """ + Return all cells at resolution 0. + + Parameters + ---------- + None + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + mv = _cy.get_res0_cells() + + return _out_collection(mv) + + +def cell_to_center_child(h, res=None): + """ + Get the center child of a cell at some finer resolution. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the child cell + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_center_child(h, res) + p = _out_scalar(p) + + return p + + +def get_icosahedron_faces(h): + """ + Return icosahedron faces intersecting a given H3 cell. + + There are twenty possible faces, ranging from 0--19. + + Note: Every interface returns a Python ``set`` of ``int``. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + Python ``set`` of ``int`` + """ + h = _in_scalar(h) + faces = _cy.get_icosahedron_faces(h) + + return faces + + +def cell_to_local_ij(origin, h): + """ + Return local (i,j) coordinates of cell ``h`` in relation to ``origin`` cell + + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + h: H3Cell + Destination cell whose i,j coordinates we'd like, based off + of the origin cell. + + + Returns + ------- + Tuple (i, j) of integer local coordinates of cell ``h`` + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of `origin`. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + h = _in_scalar(h) + + i, j = _cy.cell_to_local_ij(origin, h) + + return i, j + + +def local_ij_to_cell(origin, i, j): + """ + Return cell at local (i,j) position relative to the ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + i, j: int + Integer coordinates with respect to ``origin`` cell. + + + Returns + ------- + H3Cell at local (i,j) position relative to the ``origin`` cell + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of ``origin``. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + + h = _cy.local_ij_to_cell(origin, i, j) + h = _out_scalar(h) + + return h + + +def cell_area(h, unit='km^2'): + """ + Compute the spherical surface area of a specific H3 cell. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) + + + Returns + ------- + The area of the H3 cell in the given units + + + Notes + ----- + This function breaks the cell into spherical triangles, and computes + their spherical area. + The function uses the spherical distance calculation given by + ``great_circle_distance()``. + """ + h = _in_scalar(h) + + return _cy.cell_area(h, unit=unit) + + +def edge_length(e, unit='km'): + """ + Compute the spherical length of a specific H3 edge. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) + + + Returns + ------- + The length of the edge in the given units + + + Notes + ----- + This function uses the spherical distance calculation given by + ``great_circle_distance()``. + """ + e = _in_scalar(e) + + return _cy.edge_length(e, unit=unit) + + +def great_circle_distance(latlng1, latlng2, unit='km'): + """ + Compute the spherical distance between two (lat, lng) points. + AKA: great circle distance or "haversine" distance. + + todo: overload to allow two cell inputs? + + Parameters + ---------- + latlng1 : tuple + (lat, lng) tuple in degrees + latlng2 : tuple + (lat, lng) tuple in degrees + unit: str + Unit for distance result (``'km'``, ``'m'``, or ``'rads'``) + + Returns + ------- + The spherical distance between the points in the given units + """ + lat1, lng1 = latlng1 + lat2, lng2 = latlng2 + return _cy.great_circle_distance( + lat1, lng1, + lat2, lng2, + unit = unit + ) + + +def cell_to_vertex(h, vertex_num): + """ + Return a (specified) vertex of an H3 cell. + + Parameters + ---------- + h : H3Cell + vertex_num : int + Vertex number (0-5) + + Returns + ------- + The vertex + """ + h = _in_scalar(h) + h = _cy.cell_to_vertex(h, vertex_num) + return _out_scalar(h) + + +def cell_to_vertexes(h): + """ + Return a list of vertexes of an H3 cell. + The list will be of length 5 for pentagons and 6 for hexagons. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + A list of vertexes + """ + h = _in_scalar(h) + mv = _cy.cell_to_vertexes(h) + return _out_collection(mv) + + +def vertex_to_latlng(v): + """ + Return latitude and longitude of a vertex. + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + v = _in_scalar(v) + return _cy.vertex_to_latlng(v) + + +def is_valid_vertex(v): + """ + Validates an H3 vertex. + + Returns + ------- + bool + """ + try: + v = _in_scalar(v) + return _cy.is_valid_vertex(v) + except (ValueError, TypeError): + return False diff --git a/tasksnest/lib/python3.13/site-packages/h3/api/basic_int/_convert.py b/tasksnest/lib/python3.13/site-packages/h3/api/basic_int/_convert.py new file mode 100644 index 0000000..51f4728 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/api/basic_int/_convert.py @@ -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 diff --git a/tasksnest/lib/python3.13/site-packages/h3/api/basic_str/__init__.py b/tasksnest/lib/python3.13/site-packages/h3/api/basic_str/__init__.py new file mode 100644 index 0000000..1086a63 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/api/basic_str/__init__.py @@ -0,0 +1,1369 @@ +# This file is **symlinked** across the APIs to ensure they are exactly the same. +from typing import Literal +from array import array + +from ... import _cy +from ..._h3shape import ( + H3Shape, + LatLngPoly, + LatLngMultiPoly, + geo_to_h3shape, + h3shape_to_geo, +) + +from ._convert import ( + _in_scalar, + _out_scalar, + _in_collection, + _out_collection, +) + + +def versions(): + """ + Version numbers for the Python (wrapper) and C (wrapped) libraries. + + Versions are output as strings of the form ``'X.Y.Z'``. + C and Python should match on ``X`` (major) and ``Y`` (minor), + but may differ on ``Z`` (patch). + + Returns + ------- + dict like ``{'c': 'X.Y.Z', 'python': 'A.B.C'}`` + """ + from ..._version import __version__ + + v = { + 'c': _cy.c_version(), + 'python': __version__, + } + + return v + + +def str_to_int(h): + """ + Converts a hexadecimal string to an H3 64-bit integer index. + + Parameters + ---------- + h : str + Hexadecimal string like ``'89754e64993ffff'`` + + Returns + ------- + int + Unsigned 64-bit integer + """ + return _cy.str_to_int(h) + + +def int_to_str(x): + """ + Converts an H3 64-bit integer index to a hexadecimal string. + + Parameters + ---------- + x : int + Unsigned 64-bit integer + + Returns + ------- + str + Hexadecimal string like ``'89754e64993ffff'`` + """ + return _cy.int_to_str(x) + + +def get_num_cells(res): + """ + Return the total number of *cells* (hexagons and pentagons) + for the given resolution. + + Returns + ------- + int + """ + return _cy.get_num_cells(res) + + +def average_hexagon_area(res, unit='km^2'): + """ + Return the average area of an H3 *hexagon* + for the given resolution. + + This average *excludes* pentagons. + + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) + + Returns + ------- + float + """ + return _cy.average_hexagon_area(res, unit) + + +def average_hexagon_edge_length(res, unit='km'): + """ + Return the average *hexagon* edge length + for the given resolution. + + This average *excludes* pentagons. + + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) + + Returns + ------- + float + """ + return _cy.average_hexagon_edge_length(res, unit) + + +def is_valid_index(h): + """Validates *any* H3 index (cell, vertex, or directed edge). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_index(h) + except (ValueError, TypeError): + return False + + +def is_valid_cell(h): + """ + Validates an H3 cell (hexagon or pentagon). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_cell(h) + except (ValueError, TypeError): + return False + + +def is_valid_directed_edge(edge): + """ + Validates an H3 directed edge. + + Returns + ------- + bool + """ + try: + e = _in_scalar(edge) + return _cy.is_valid_directed_edge(e) + except (ValueError, TypeError): + return False + + +def latlng_to_cell(lat, lng, res): + """ + Return the cell containing the (lat, lng) point + for a given resolution. + + Returns + ------- + H3Cell + + """ + return _out_scalar(_cy.latlng_to_cell(lat, lng, res)) + + +def cell_to_latlng(h): + """ + Return the center point of an H3 cell as a lat/lng pair. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + h = _in_scalar(h) + return _cy.cell_to_latlng(h) + + +def get_resolution(h): + """ + Return the resolution of an H3 cell. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + """ + # todo: could also work for edges + h = _in_scalar(h) + return _cy.get_resolution(h) + + +def cell_to_parent(h, res=None): + """ + Get the parent of a cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the parent + If ``None``, then ``res = resolution(h) - 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_parent(h, res) + p = _out_scalar(p) + + return p + + +def grid_distance(h1, h2): + """ + Compute the grid distance between two cells. + + The grid distance is defined as the length of the shortest + path between the cells in the graph formed by connecting + adjacent cells. + + This function will raise an exception if the + cells are too far apart to compute the distance. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + int + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + d = _cy.grid_distance(h1, h2) + + return d + + +def cell_to_boundary(h): + """ + Return tuple of lat/lng pairs describing the cell boundary. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + tuple of (lat, lng) tuples + """ + h = _in_scalar(h) + return _cy.cell_to_boundary(h) + + +def grid_disk(h, k=1): + """ + Return unordered collection of cells with grid distance ``<= k`` from ``h``. + That is, the "filled-in" disk. + + Parameters + ---------- + h : H3Cell + k : int + Size of disk. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.grid_disk(h, k) + + return _out_collection(mv) + + +def grid_ring(h, k=1): + """ + Return unordered collection of cells with grid distance ``== k`` from ``h``. + That is, the "hollow" ring. + + Parameters + ---------- + h : H3Cell + k : int + Size of ring. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.grid_ring(h, k) + + return _out_collection(mv) + + +def cell_to_children_size(h, res=None): + """ + Number of children at resolution ``res`` of given cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + int + Count of children + """ + h = _in_scalar(h) + return _cy.cell_to_children_size(h, res) + + +def cell_to_children(h, res=None): + """ + Children of a cell as an unordered collection. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.cell_to_children(h, res) + + return _out_collection(mv) + + +def cell_to_child_pos(child, res_parent): + """ + Child position index of given cell, with respect to its parent at ``res_parent``. + + The reverse operation can be done with ``child_pos_to_cell``. + + Parameters + ---------- + child : H3Cell + res_parent : int + + Returns + ------- + int + Integer index of the child with respect to parent cell. + """ + child = _in_scalar(child) + return _cy.cell_to_child_pos(child, res_parent) + + +def child_pos_to_cell(parent, res_child, child_pos): + """ + Get child H3 cell from a parent cell, child resolution, and child position index. + + The reverse operation can be done with ``cell_to_child_pos``. + + Parameters + ---------- + parent : H3Cell + res_child : int + Child cell resolution + child_pos : int + Integer position of child cell, releative to parent. + + + Returns + ------- + H3Cell + """ + parent = _in_scalar(parent) + child = _cy.child_pos_to_cell(parent, res_child, child_pos) + child = _out_scalar(child) + + return child + + +# todo: nogil for expensive C operation? +def compact_cells(cells): + """ + Compact a collection of H3 cells by combining + smaller cells into larger cells, if all child cells + are present. Input cells must all share the same resolution. + + Parameters + ---------- + cells : iterable of H3 Cells + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + hu = _in_collection(cells) + hc = _cy.compact_cells(hu) + + return _out_collection(hc) + + +def uncompact_cells(cells, res): + """ + Reverse the ``compact_cells`` operation. + + Return a collection of H3 cells, all of resolution ``res``. + + Parameters + ---------- + cells : iterable of H3Cell + res : int + Resolution of desired output cells. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + # TODO: add test to make sure an error is returned when input contains cell + # smaller than output res. + + hc = _in_collection(cells) + hu = _cy.uncompact_cells(hc, res) + + return _out_collection(hu) + + +def polygon_to_cells(h3shape, res): + """ + Alias for ``h3shape_to_cells``. + """ + return h3shape_to_cells(h3shape, res) + + +def h3shape_to_cells(h3shape, res): + """ + Return the collection of H3 cells at a given resolution whose center points + are contained within an ``LatLngPoly`` or ``LatLngMultiPoly``. + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells(poly, 6) + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells(poly.outer, res=res, holes=poly.holes) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells(mpoly.polys, res=res) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) + + +def polygon_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): + """ + Alias for ``h3shape_to_cells_experimental``. + """ + return h3shape_to_cells_experimental(h3shape, res, contain) + + +def h3shape_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): + """ + Experimental function similar to ``h3shape_to_cells``, but with support for + multiple cell containment modes. + + Using ``contain='center'`` should give identical behavior as + ``h3shape_to_cells``. + + Note that this function is **experimental** and has no API stability gaurantees + across versions, so it may change in the future. + + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + contain : {'center', 'full', 'overlap', 'bbox_overlap'}, optional + Specifies the containment condition. + - 'center': Cell center is contained in shape + - 'full': Cell is fully contained in shape + - 'overlap': Cell is partially contained in shape + - 'bbox_overlap': Cell bounding box is partially contained in shape + + Default is 'center'. + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells_experimental(poly, 6, 'center') + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + contain_modes = { + 'center': 0, + 'full': 1, + 'overlap': 2, + 'bbox_overlap': 3, + } + + flag = contain_modes[contain] + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells_experimental( + poly.outer, + res = res, + holes = poly.holes, + flag = flag, + ) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flag=flag) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) + + +def cells_to_h3shape(cells, *, tight=True): + """ + Return an ``H3Shape`` describing the area covered by a collection of H3 cells. + Will return ``LatLngPoly`` or ``LatLngMultiPoly``. + + Parameters + ---------- + cells : iterable of H3 cells + tight : bool + If True, return ``LatLngPoly`` if possible. + If False, always return ``LatLngMultiPoly``. + + Returns + ------- + LatLngPoly | LatLngMultiPoly + + Examples + -------- + + >>> cells = ['8428309ffffffff', '842830dffffffff'] + >>> h3.cells_to_h3shape(cells, tight=True) + + >>> h3.cells_to_h3shape(cells, tight=False) + + """ + cells = _in_collection(cells) + mpoly = _cy.cells_to_multi_polygon(cells) + + polys = [LatLngPoly(*poly) for poly in mpoly] + out = LatLngMultiPoly(*polys) + + if tight and len(out) == 1: + out = out[0] + + return out + + +def geo_to_cells(geo, res): + """Convert from ``__geo_interface__`` to cells. + + Parameters + ---------- + geo : an object implementing ``__geo_interface__`` or a dictionary in that format. + Both ``LatLngPoly`` and ``LatLngMultiPoly`` implement the interface. + res : int + Resolution of desired output cells. + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h3shape = geo_to_h3shape(geo) + return h3shape_to_cells(h3shape, res) + + +def cells_to_geo(cells, tight=True): + """ + Convert from cells to a ``__geo_interface__`` dict. + + Parameters + ---------- + cells : iterable of H3 Cells + tight : bool + When ``True``, returns an ``LatLngPoly`` when possible. + When ``False``, always returns an ``LatLngMultiPoly``. + + Returns + ------- + dict + in `__geo_interface__` format + """ + h3shape = cells_to_h3shape(cells, tight=tight) + return h3shape_to_geo(h3shape) + + +def is_pentagon(h): + """ + Identify if an H3 cell is a pentagon. + + Parameters + ---------- + h : H3Index + + Returns + ------- + bool + ``True`` if input is a valid H3 cell which is a pentagon. + + Notes + ----- + A pentagon should *also* pass ``is_valid_cell()``. + Will return ``False`` for valid H3Edge. + """ + return _cy.is_pentagon(_in_scalar(h)) + + +def get_base_cell_number(h): + """ + Return the base cell *number* (``0`` to ``121``) of the given cell. + + The base cell *number* and the H3Index are two different representations + of the same cell: the parent cell of resolution ``0``. + + The base cell *number* is encoded within the corresponding + H3Index. + + todo: could work with edges + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + + Examples + -------- + >>> h = construct_cell(57, 2, 1, 4) + >>> h + '83728cfffffffff' + >> get_base_cell_number(h) + 57 + """ + return _cy.get_base_cell_number(_in_scalar(h)) + + +def get_index_digit(h, res): + """ + Get the index digit of a cell at the given resolution. + + Parameters + ---------- + h : H3Cell + Cell whose index digit will be returned. + res : int + Resolution (``>= 1``) at which to read the digit. + + Returns + ------- + int + The index digit at the requested resolution. + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) + >>> h + '830e8cfffffffff' + >>> get_index_digit(h, 1) + 2 + >>> get_index_digit(h, 2) + 1 + >>> get_index_digit(h, 3) + 4 + """ + return _cy.get_index_digit(_in_scalar(h), res) + + +def construct_cell(base_cell_number, *digits, res=None): + """ + Construct cell from base cell and digits. + + Parameters + ---------- + base_cell_number : int + Base cell *number* (``0`` to ``121``). + *digits : int + Sequence of index digits (``0`` to ``6``). + Length of digits will be the resulting resolution of the output cell. + res : int, optional + Resolution of the constructed cell. If provided, it must equal + ``len(digits)``; otherwise it is inferred from the number of digits. + + Returns + ------- + H3Cell + The constructed cell. + + Examples + -------- + >>> construct_cell(7, 2, 1, 4) # resolution 3 cell + '830e8cfffffffff' + + >>> construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + '841e057ffffffff' + + >>> construct_cell(15, 0, 0, 5, 3, res=4) + '841e057ffffffff' + """ + if (res is not None) and (len(digits) != res): + raise ValueError('Resolution must match number of digits.') + + digits = array('i', digits) + o = _cy.construct_cell(base_cell_number, digits) + return _out_scalar(o) + + +def deconstruct_cell(h): + """ + Deconstruct cell into base cell and digits. + + Parameters + ---------- + h : H3Cell + Cell to deconstruct. + + Returns + ------- + list of int + [base_cell_number, digit1, digit2, ..., digitN] + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) # resolution 3 cell + >>> h + '830e8cfffffffff' + >>> deconstruct_cell(h) + (7, 2, 1, 4) + + >>> h = construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + >>> h + '841e057ffffffff' + >>> deconstruct_cell(h) + (15, 0, 0, 5, 3) + >>> construct_cell(*deconstruct_cell(h), 0) == cell_to_center_child(h) + """ + res = get_resolution(h) + bc = get_base_cell_number(h) + digits = [get_index_digit(h, r + 1) for r in range(res)] + + return [bc, *digits] + + +def are_neighbor_cells(h1, h2): + """ + Returns ``True`` if ``h1`` and ``h2`` are neighboring cells. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + bool + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + return _cy.are_neighbor_cells(h1, h2) + + +def cells_to_directed_edge(origin, destination): + """ + Create an H3 Index denoting a unidirectional edge. + + The edge is constructed from neighboring cells ``origin`` and + ``destination``. + + Parameters + ---------- + origin : H3Cell + destination : H3Cell + + Raises + ------ + ValueError + When cells are not adjacent. + + Returns + ------- + H3Edge + """ + o = _in_scalar(origin) + d = _in_scalar(destination) + e = _cy.cells_to_directed_edge(o, d) + e = _out_scalar(e) + + return e + + +def get_directed_edge_origin(e): + """ + Origin cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + o = _cy.get_directed_edge_origin(e) + o = _out_scalar(o) + + return o + + +def get_directed_edge_destination(e): + """ + Destination cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + d = _cy.get_directed_edge_destination(e) + d = _out_scalar(d) + + return d + + +def directed_edge_to_cells(e): + """ + Return (origin, destination) tuple from H3 directed edge + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + Origin cell of edge + H3Cell + Destination cell of edge + """ + e = _in_scalar(e) + o, d = _cy.directed_edge_to_cells(e) + o, d = _out_scalar(o), _out_scalar(d) + + return o, d + + +def origin_to_directed_edges(origin): + """ + Return all directed edges starting from ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + + Returns + ------- + unordered collection of H3Edge + """ + mv = _cy.origin_to_directed_edges(_in_scalar(origin)) + + return _out_collection(mv) + + +def directed_edge_to_boundary(edge): + """ + Returns points representing the edge (line of points + describing the boundary between two cells). + + Parameters + ---------- + edge : H3Edge + + Returns + ------- + tuple of (lat, lng) tuples + """ + return _cy.directed_edge_to_boundary(_in_scalar(edge)) + + +def grid_path_cells(start, end): + """ + Returns the ordered collection of cells denoting a + minimum-length non-unique path between cells. + + Parameters + ---------- + start : H3Cell + end : H3Cell + + Returns + ------- + ordered collection of H3Cell + Starting with ``start``, and ending with ``end``. + """ + mv = _cy.grid_path_cells(_in_scalar(start), _in_scalar(end)) + + return _out_collection(mv) + + +def is_res_class_III(h): + """ + Determine if cell has orientation "Class II" or "Class III". + + The orientation of pentagons/hexagons on the icosahedron can be one + of two types: "Class II" or "Class III". + + All cells within a resolution have the same type, and the type + alternates between resolutions. + + "Class II" cells have resolutions: 0,2,4,6,8,10,12,14 + "Class III" cells have resolutions: 1,3,5,7,9,11,13,15 + + Parameters + ---------- + h : H3Cell + + Returns + ------- + bool + ``True`` if ``h`` is "Class III". + ``False`` if ``h`` is "Class II". + + References + ---------- + 1. https://uber.github.io/h3/#/documentation/core-library/coordinate-systems + """ + return _cy.is_res_class_iii(_in_scalar(h)) + + +def get_pentagons(res): + """ + Return all pentagons at a given resolution. + + Parameters + ---------- + res : int + Resolution of the pentagons + + Returns + ------- + unordered collection of H3Cell + """ + mv = _cy.get_pentagons(res) + + return _out_collection(mv) + + +def get_res0_cells(): + """ + Return all cells at resolution 0. + + Parameters + ---------- + None + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + mv = _cy.get_res0_cells() + + return _out_collection(mv) + + +def cell_to_center_child(h, res=None): + """ + Get the center child of a cell at some finer resolution. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the child cell + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_center_child(h, res) + p = _out_scalar(p) + + return p + + +def get_icosahedron_faces(h): + """ + Return icosahedron faces intersecting a given H3 cell. + + There are twenty possible faces, ranging from 0--19. + + Note: Every interface returns a Python ``set`` of ``int``. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + Python ``set`` of ``int`` + """ + h = _in_scalar(h) + faces = _cy.get_icosahedron_faces(h) + + return faces + + +def cell_to_local_ij(origin, h): + """ + Return local (i,j) coordinates of cell ``h`` in relation to ``origin`` cell + + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + h: H3Cell + Destination cell whose i,j coordinates we'd like, based off + of the origin cell. + + + Returns + ------- + Tuple (i, j) of integer local coordinates of cell ``h`` + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of `origin`. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + h = _in_scalar(h) + + i, j = _cy.cell_to_local_ij(origin, h) + + return i, j + + +def local_ij_to_cell(origin, i, j): + """ + Return cell at local (i,j) position relative to the ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + i, j: int + Integer coordinates with respect to ``origin`` cell. + + + Returns + ------- + H3Cell at local (i,j) position relative to the ``origin`` cell + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of ``origin``. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + + h = _cy.local_ij_to_cell(origin, i, j) + h = _out_scalar(h) + + return h + + +def cell_area(h, unit='km^2'): + """ + Compute the spherical surface area of a specific H3 cell. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) + + + Returns + ------- + The area of the H3 cell in the given units + + + Notes + ----- + This function breaks the cell into spherical triangles, and computes + their spherical area. + The function uses the spherical distance calculation given by + ``great_circle_distance()``. + """ + h = _in_scalar(h) + + return _cy.cell_area(h, unit=unit) + + +def edge_length(e, unit='km'): + """ + Compute the spherical length of a specific H3 edge. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) + + + Returns + ------- + The length of the edge in the given units + + + Notes + ----- + This function uses the spherical distance calculation given by + ``great_circle_distance()``. + """ + e = _in_scalar(e) + + return _cy.edge_length(e, unit=unit) + + +def great_circle_distance(latlng1, latlng2, unit='km'): + """ + Compute the spherical distance between two (lat, lng) points. + AKA: great circle distance or "haversine" distance. + + todo: overload to allow two cell inputs? + + Parameters + ---------- + latlng1 : tuple + (lat, lng) tuple in degrees + latlng2 : tuple + (lat, lng) tuple in degrees + unit: str + Unit for distance result (``'km'``, ``'m'``, or ``'rads'``) + + Returns + ------- + The spherical distance between the points in the given units + """ + lat1, lng1 = latlng1 + lat2, lng2 = latlng2 + return _cy.great_circle_distance( + lat1, lng1, + lat2, lng2, + unit = unit + ) + + +def cell_to_vertex(h, vertex_num): + """ + Return a (specified) vertex of an H3 cell. + + Parameters + ---------- + h : H3Cell + vertex_num : int + Vertex number (0-5) + + Returns + ------- + The vertex + """ + h = _in_scalar(h) + h = _cy.cell_to_vertex(h, vertex_num) + return _out_scalar(h) + + +def cell_to_vertexes(h): + """ + Return a list of vertexes of an H3 cell. + The list will be of length 5 for pentagons and 6 for hexagons. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + A list of vertexes + """ + h = _in_scalar(h) + mv = _cy.cell_to_vertexes(h) + return _out_collection(mv) + + +def vertex_to_latlng(v): + """ + Return latitude and longitude of a vertex. + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + v = _in_scalar(v) + return _cy.vertex_to_latlng(v) + + +def is_valid_vertex(v): + """ + Validates an H3 vertex. + + Returns + ------- + bool + """ + try: + v = _in_scalar(v) + return _cy.is_valid_vertex(v) + except (ValueError, TypeError): + return False diff --git a/tasksnest/lib/python3.13/site-packages/h3/api/basic_str/_convert.py b/tasksnest/lib/python3.13/site-packages/h3/api/basic_str/_convert.py new file mode 100644 index 0000000..a6c0ba0 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/api/basic_str/_convert.py @@ -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) diff --git a/tasksnest/lib/python3.13/site-packages/h3/api/memview_int/__init__.py b/tasksnest/lib/python3.13/site-packages/h3/api/memview_int/__init__.py new file mode 100644 index 0000000..1086a63 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/api/memview_int/__init__.py @@ -0,0 +1,1369 @@ +# This file is **symlinked** across the APIs to ensure they are exactly the same. +from typing import Literal +from array import array + +from ... import _cy +from ..._h3shape import ( + H3Shape, + LatLngPoly, + LatLngMultiPoly, + geo_to_h3shape, + h3shape_to_geo, +) + +from ._convert import ( + _in_scalar, + _out_scalar, + _in_collection, + _out_collection, +) + + +def versions(): + """ + Version numbers for the Python (wrapper) and C (wrapped) libraries. + + Versions are output as strings of the form ``'X.Y.Z'``. + C and Python should match on ``X`` (major) and ``Y`` (minor), + but may differ on ``Z`` (patch). + + Returns + ------- + dict like ``{'c': 'X.Y.Z', 'python': 'A.B.C'}`` + """ + from ..._version import __version__ + + v = { + 'c': _cy.c_version(), + 'python': __version__, + } + + return v + + +def str_to_int(h): + """ + Converts a hexadecimal string to an H3 64-bit integer index. + + Parameters + ---------- + h : str + Hexadecimal string like ``'89754e64993ffff'`` + + Returns + ------- + int + Unsigned 64-bit integer + """ + return _cy.str_to_int(h) + + +def int_to_str(x): + """ + Converts an H3 64-bit integer index to a hexadecimal string. + + Parameters + ---------- + x : int + Unsigned 64-bit integer + + Returns + ------- + str + Hexadecimal string like ``'89754e64993ffff'`` + """ + return _cy.int_to_str(x) + + +def get_num_cells(res): + """ + Return the total number of *cells* (hexagons and pentagons) + for the given resolution. + + Returns + ------- + int + """ + return _cy.get_num_cells(res) + + +def average_hexagon_area(res, unit='km^2'): + """ + Return the average area of an H3 *hexagon* + for the given resolution. + + This average *excludes* pentagons. + + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) + + Returns + ------- + float + """ + return _cy.average_hexagon_area(res, unit) + + +def average_hexagon_edge_length(res, unit='km'): + """ + Return the average *hexagon* edge length + for the given resolution. + + This average *excludes* pentagons. + + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) + + Returns + ------- + float + """ + return _cy.average_hexagon_edge_length(res, unit) + + +def is_valid_index(h): + """Validates *any* H3 index (cell, vertex, or directed edge). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_index(h) + except (ValueError, TypeError): + return False + + +def is_valid_cell(h): + """ + Validates an H3 cell (hexagon or pentagon). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_cell(h) + except (ValueError, TypeError): + return False + + +def is_valid_directed_edge(edge): + """ + Validates an H3 directed edge. + + Returns + ------- + bool + """ + try: + e = _in_scalar(edge) + return _cy.is_valid_directed_edge(e) + except (ValueError, TypeError): + return False + + +def latlng_to_cell(lat, lng, res): + """ + Return the cell containing the (lat, lng) point + for a given resolution. + + Returns + ------- + H3Cell + + """ + return _out_scalar(_cy.latlng_to_cell(lat, lng, res)) + + +def cell_to_latlng(h): + """ + Return the center point of an H3 cell as a lat/lng pair. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + h = _in_scalar(h) + return _cy.cell_to_latlng(h) + + +def get_resolution(h): + """ + Return the resolution of an H3 cell. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + """ + # todo: could also work for edges + h = _in_scalar(h) + return _cy.get_resolution(h) + + +def cell_to_parent(h, res=None): + """ + Get the parent of a cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the parent + If ``None``, then ``res = resolution(h) - 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_parent(h, res) + p = _out_scalar(p) + + return p + + +def grid_distance(h1, h2): + """ + Compute the grid distance between two cells. + + The grid distance is defined as the length of the shortest + path between the cells in the graph formed by connecting + adjacent cells. + + This function will raise an exception if the + cells are too far apart to compute the distance. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + int + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + d = _cy.grid_distance(h1, h2) + + return d + + +def cell_to_boundary(h): + """ + Return tuple of lat/lng pairs describing the cell boundary. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + tuple of (lat, lng) tuples + """ + h = _in_scalar(h) + return _cy.cell_to_boundary(h) + + +def grid_disk(h, k=1): + """ + Return unordered collection of cells with grid distance ``<= k`` from ``h``. + That is, the "filled-in" disk. + + Parameters + ---------- + h : H3Cell + k : int + Size of disk. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.grid_disk(h, k) + + return _out_collection(mv) + + +def grid_ring(h, k=1): + """ + Return unordered collection of cells with grid distance ``== k`` from ``h``. + That is, the "hollow" ring. + + Parameters + ---------- + h : H3Cell + k : int + Size of ring. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.grid_ring(h, k) + + return _out_collection(mv) + + +def cell_to_children_size(h, res=None): + """ + Number of children at resolution ``res`` of given cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + int + Count of children + """ + h = _in_scalar(h) + return _cy.cell_to_children_size(h, res) + + +def cell_to_children(h, res=None): + """ + Children of a cell as an unordered collection. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.cell_to_children(h, res) + + return _out_collection(mv) + + +def cell_to_child_pos(child, res_parent): + """ + Child position index of given cell, with respect to its parent at ``res_parent``. + + The reverse operation can be done with ``child_pos_to_cell``. + + Parameters + ---------- + child : H3Cell + res_parent : int + + Returns + ------- + int + Integer index of the child with respect to parent cell. + """ + child = _in_scalar(child) + return _cy.cell_to_child_pos(child, res_parent) + + +def child_pos_to_cell(parent, res_child, child_pos): + """ + Get child H3 cell from a parent cell, child resolution, and child position index. + + The reverse operation can be done with ``cell_to_child_pos``. + + Parameters + ---------- + parent : H3Cell + res_child : int + Child cell resolution + child_pos : int + Integer position of child cell, releative to parent. + + + Returns + ------- + H3Cell + """ + parent = _in_scalar(parent) + child = _cy.child_pos_to_cell(parent, res_child, child_pos) + child = _out_scalar(child) + + return child + + +# todo: nogil for expensive C operation? +def compact_cells(cells): + """ + Compact a collection of H3 cells by combining + smaller cells into larger cells, if all child cells + are present. Input cells must all share the same resolution. + + Parameters + ---------- + cells : iterable of H3 Cells + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + hu = _in_collection(cells) + hc = _cy.compact_cells(hu) + + return _out_collection(hc) + + +def uncompact_cells(cells, res): + """ + Reverse the ``compact_cells`` operation. + + Return a collection of H3 cells, all of resolution ``res``. + + Parameters + ---------- + cells : iterable of H3Cell + res : int + Resolution of desired output cells. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + # TODO: add test to make sure an error is returned when input contains cell + # smaller than output res. + + hc = _in_collection(cells) + hu = _cy.uncompact_cells(hc, res) + + return _out_collection(hu) + + +def polygon_to_cells(h3shape, res): + """ + Alias for ``h3shape_to_cells``. + """ + return h3shape_to_cells(h3shape, res) + + +def h3shape_to_cells(h3shape, res): + """ + Return the collection of H3 cells at a given resolution whose center points + are contained within an ``LatLngPoly`` or ``LatLngMultiPoly``. + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells(poly, 6) + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells(poly.outer, res=res, holes=poly.holes) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells(mpoly.polys, res=res) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) + + +def polygon_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): + """ + Alias for ``h3shape_to_cells_experimental``. + """ + return h3shape_to_cells_experimental(h3shape, res, contain) + + +def h3shape_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): + """ + Experimental function similar to ``h3shape_to_cells``, but with support for + multiple cell containment modes. + + Using ``contain='center'`` should give identical behavior as + ``h3shape_to_cells``. + + Note that this function is **experimental** and has no API stability gaurantees + across versions, so it may change in the future. + + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + contain : {'center', 'full', 'overlap', 'bbox_overlap'}, optional + Specifies the containment condition. + - 'center': Cell center is contained in shape + - 'full': Cell is fully contained in shape + - 'overlap': Cell is partially contained in shape + - 'bbox_overlap': Cell bounding box is partially contained in shape + + Default is 'center'. + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells_experimental(poly, 6, 'center') + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + contain_modes = { + 'center': 0, + 'full': 1, + 'overlap': 2, + 'bbox_overlap': 3, + } + + flag = contain_modes[contain] + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells_experimental( + poly.outer, + res = res, + holes = poly.holes, + flag = flag, + ) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flag=flag) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) + + +def cells_to_h3shape(cells, *, tight=True): + """ + Return an ``H3Shape`` describing the area covered by a collection of H3 cells. + Will return ``LatLngPoly`` or ``LatLngMultiPoly``. + + Parameters + ---------- + cells : iterable of H3 cells + tight : bool + If True, return ``LatLngPoly`` if possible. + If False, always return ``LatLngMultiPoly``. + + Returns + ------- + LatLngPoly | LatLngMultiPoly + + Examples + -------- + + >>> cells = ['8428309ffffffff', '842830dffffffff'] + >>> h3.cells_to_h3shape(cells, tight=True) + + >>> h3.cells_to_h3shape(cells, tight=False) + + """ + cells = _in_collection(cells) + mpoly = _cy.cells_to_multi_polygon(cells) + + polys = [LatLngPoly(*poly) for poly in mpoly] + out = LatLngMultiPoly(*polys) + + if tight and len(out) == 1: + out = out[0] + + return out + + +def geo_to_cells(geo, res): + """Convert from ``__geo_interface__`` to cells. + + Parameters + ---------- + geo : an object implementing ``__geo_interface__`` or a dictionary in that format. + Both ``LatLngPoly`` and ``LatLngMultiPoly`` implement the interface. + res : int + Resolution of desired output cells. + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h3shape = geo_to_h3shape(geo) + return h3shape_to_cells(h3shape, res) + + +def cells_to_geo(cells, tight=True): + """ + Convert from cells to a ``__geo_interface__`` dict. + + Parameters + ---------- + cells : iterable of H3 Cells + tight : bool + When ``True``, returns an ``LatLngPoly`` when possible. + When ``False``, always returns an ``LatLngMultiPoly``. + + Returns + ------- + dict + in `__geo_interface__` format + """ + h3shape = cells_to_h3shape(cells, tight=tight) + return h3shape_to_geo(h3shape) + + +def is_pentagon(h): + """ + Identify if an H3 cell is a pentagon. + + Parameters + ---------- + h : H3Index + + Returns + ------- + bool + ``True`` if input is a valid H3 cell which is a pentagon. + + Notes + ----- + A pentagon should *also* pass ``is_valid_cell()``. + Will return ``False`` for valid H3Edge. + """ + return _cy.is_pentagon(_in_scalar(h)) + + +def get_base_cell_number(h): + """ + Return the base cell *number* (``0`` to ``121``) of the given cell. + + The base cell *number* and the H3Index are two different representations + of the same cell: the parent cell of resolution ``0``. + + The base cell *number* is encoded within the corresponding + H3Index. + + todo: could work with edges + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + + Examples + -------- + >>> h = construct_cell(57, 2, 1, 4) + >>> h + '83728cfffffffff' + >> get_base_cell_number(h) + 57 + """ + return _cy.get_base_cell_number(_in_scalar(h)) + + +def get_index_digit(h, res): + """ + Get the index digit of a cell at the given resolution. + + Parameters + ---------- + h : H3Cell + Cell whose index digit will be returned. + res : int + Resolution (``>= 1``) at which to read the digit. + + Returns + ------- + int + The index digit at the requested resolution. + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) + >>> h + '830e8cfffffffff' + >>> get_index_digit(h, 1) + 2 + >>> get_index_digit(h, 2) + 1 + >>> get_index_digit(h, 3) + 4 + """ + return _cy.get_index_digit(_in_scalar(h), res) + + +def construct_cell(base_cell_number, *digits, res=None): + """ + Construct cell from base cell and digits. + + Parameters + ---------- + base_cell_number : int + Base cell *number* (``0`` to ``121``). + *digits : int + Sequence of index digits (``0`` to ``6``). + Length of digits will be the resulting resolution of the output cell. + res : int, optional + Resolution of the constructed cell. If provided, it must equal + ``len(digits)``; otherwise it is inferred from the number of digits. + + Returns + ------- + H3Cell + The constructed cell. + + Examples + -------- + >>> construct_cell(7, 2, 1, 4) # resolution 3 cell + '830e8cfffffffff' + + >>> construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + '841e057ffffffff' + + >>> construct_cell(15, 0, 0, 5, 3, res=4) + '841e057ffffffff' + """ + if (res is not None) and (len(digits) != res): + raise ValueError('Resolution must match number of digits.') + + digits = array('i', digits) + o = _cy.construct_cell(base_cell_number, digits) + return _out_scalar(o) + + +def deconstruct_cell(h): + """ + Deconstruct cell into base cell and digits. + + Parameters + ---------- + h : H3Cell + Cell to deconstruct. + + Returns + ------- + list of int + [base_cell_number, digit1, digit2, ..., digitN] + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) # resolution 3 cell + >>> h + '830e8cfffffffff' + >>> deconstruct_cell(h) + (7, 2, 1, 4) + + >>> h = construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + >>> h + '841e057ffffffff' + >>> deconstruct_cell(h) + (15, 0, 0, 5, 3) + >>> construct_cell(*deconstruct_cell(h), 0) == cell_to_center_child(h) + """ + res = get_resolution(h) + bc = get_base_cell_number(h) + digits = [get_index_digit(h, r + 1) for r in range(res)] + + return [bc, *digits] + + +def are_neighbor_cells(h1, h2): + """ + Returns ``True`` if ``h1`` and ``h2`` are neighboring cells. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + bool + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + return _cy.are_neighbor_cells(h1, h2) + + +def cells_to_directed_edge(origin, destination): + """ + Create an H3 Index denoting a unidirectional edge. + + The edge is constructed from neighboring cells ``origin`` and + ``destination``. + + Parameters + ---------- + origin : H3Cell + destination : H3Cell + + Raises + ------ + ValueError + When cells are not adjacent. + + Returns + ------- + H3Edge + """ + o = _in_scalar(origin) + d = _in_scalar(destination) + e = _cy.cells_to_directed_edge(o, d) + e = _out_scalar(e) + + return e + + +def get_directed_edge_origin(e): + """ + Origin cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + o = _cy.get_directed_edge_origin(e) + o = _out_scalar(o) + + return o + + +def get_directed_edge_destination(e): + """ + Destination cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + d = _cy.get_directed_edge_destination(e) + d = _out_scalar(d) + + return d + + +def directed_edge_to_cells(e): + """ + Return (origin, destination) tuple from H3 directed edge + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + Origin cell of edge + H3Cell + Destination cell of edge + """ + e = _in_scalar(e) + o, d = _cy.directed_edge_to_cells(e) + o, d = _out_scalar(o), _out_scalar(d) + + return o, d + + +def origin_to_directed_edges(origin): + """ + Return all directed edges starting from ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + + Returns + ------- + unordered collection of H3Edge + """ + mv = _cy.origin_to_directed_edges(_in_scalar(origin)) + + return _out_collection(mv) + + +def directed_edge_to_boundary(edge): + """ + Returns points representing the edge (line of points + describing the boundary between two cells). + + Parameters + ---------- + edge : H3Edge + + Returns + ------- + tuple of (lat, lng) tuples + """ + return _cy.directed_edge_to_boundary(_in_scalar(edge)) + + +def grid_path_cells(start, end): + """ + Returns the ordered collection of cells denoting a + minimum-length non-unique path between cells. + + Parameters + ---------- + start : H3Cell + end : H3Cell + + Returns + ------- + ordered collection of H3Cell + Starting with ``start``, and ending with ``end``. + """ + mv = _cy.grid_path_cells(_in_scalar(start), _in_scalar(end)) + + return _out_collection(mv) + + +def is_res_class_III(h): + """ + Determine if cell has orientation "Class II" or "Class III". + + The orientation of pentagons/hexagons on the icosahedron can be one + of two types: "Class II" or "Class III". + + All cells within a resolution have the same type, and the type + alternates between resolutions. + + "Class II" cells have resolutions: 0,2,4,6,8,10,12,14 + "Class III" cells have resolutions: 1,3,5,7,9,11,13,15 + + Parameters + ---------- + h : H3Cell + + Returns + ------- + bool + ``True`` if ``h`` is "Class III". + ``False`` if ``h`` is "Class II". + + References + ---------- + 1. https://uber.github.io/h3/#/documentation/core-library/coordinate-systems + """ + return _cy.is_res_class_iii(_in_scalar(h)) + + +def get_pentagons(res): + """ + Return all pentagons at a given resolution. + + Parameters + ---------- + res : int + Resolution of the pentagons + + Returns + ------- + unordered collection of H3Cell + """ + mv = _cy.get_pentagons(res) + + return _out_collection(mv) + + +def get_res0_cells(): + """ + Return all cells at resolution 0. + + Parameters + ---------- + None + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + mv = _cy.get_res0_cells() + + return _out_collection(mv) + + +def cell_to_center_child(h, res=None): + """ + Get the center child of a cell at some finer resolution. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the child cell + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_center_child(h, res) + p = _out_scalar(p) + + return p + + +def get_icosahedron_faces(h): + """ + Return icosahedron faces intersecting a given H3 cell. + + There are twenty possible faces, ranging from 0--19. + + Note: Every interface returns a Python ``set`` of ``int``. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + Python ``set`` of ``int`` + """ + h = _in_scalar(h) + faces = _cy.get_icosahedron_faces(h) + + return faces + + +def cell_to_local_ij(origin, h): + """ + Return local (i,j) coordinates of cell ``h`` in relation to ``origin`` cell + + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + h: H3Cell + Destination cell whose i,j coordinates we'd like, based off + of the origin cell. + + + Returns + ------- + Tuple (i, j) of integer local coordinates of cell ``h`` + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of `origin`. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + h = _in_scalar(h) + + i, j = _cy.cell_to_local_ij(origin, h) + + return i, j + + +def local_ij_to_cell(origin, i, j): + """ + Return cell at local (i,j) position relative to the ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + i, j: int + Integer coordinates with respect to ``origin`` cell. + + + Returns + ------- + H3Cell at local (i,j) position relative to the ``origin`` cell + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of ``origin``. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + + h = _cy.local_ij_to_cell(origin, i, j) + h = _out_scalar(h) + + return h + + +def cell_area(h, unit='km^2'): + """ + Compute the spherical surface area of a specific H3 cell. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) + + + Returns + ------- + The area of the H3 cell in the given units + + + Notes + ----- + This function breaks the cell into spherical triangles, and computes + their spherical area. + The function uses the spherical distance calculation given by + ``great_circle_distance()``. + """ + h = _in_scalar(h) + + return _cy.cell_area(h, unit=unit) + + +def edge_length(e, unit='km'): + """ + Compute the spherical length of a specific H3 edge. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) + + + Returns + ------- + The length of the edge in the given units + + + Notes + ----- + This function uses the spherical distance calculation given by + ``great_circle_distance()``. + """ + e = _in_scalar(e) + + return _cy.edge_length(e, unit=unit) + + +def great_circle_distance(latlng1, latlng2, unit='km'): + """ + Compute the spherical distance between two (lat, lng) points. + AKA: great circle distance or "haversine" distance. + + todo: overload to allow two cell inputs? + + Parameters + ---------- + latlng1 : tuple + (lat, lng) tuple in degrees + latlng2 : tuple + (lat, lng) tuple in degrees + unit: str + Unit for distance result (``'km'``, ``'m'``, or ``'rads'``) + + Returns + ------- + The spherical distance between the points in the given units + """ + lat1, lng1 = latlng1 + lat2, lng2 = latlng2 + return _cy.great_circle_distance( + lat1, lng1, + lat2, lng2, + unit = unit + ) + + +def cell_to_vertex(h, vertex_num): + """ + Return a (specified) vertex of an H3 cell. + + Parameters + ---------- + h : H3Cell + vertex_num : int + Vertex number (0-5) + + Returns + ------- + The vertex + """ + h = _in_scalar(h) + h = _cy.cell_to_vertex(h, vertex_num) + return _out_scalar(h) + + +def cell_to_vertexes(h): + """ + Return a list of vertexes of an H3 cell. + The list will be of length 5 for pentagons and 6 for hexagons. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + A list of vertexes + """ + h = _in_scalar(h) + mv = _cy.cell_to_vertexes(h) + return _out_collection(mv) + + +def vertex_to_latlng(v): + """ + Return latitude and longitude of a vertex. + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + v = _in_scalar(v) + return _cy.vertex_to_latlng(v) + + +def is_valid_vertex(v): + """ + Validates an H3 vertex. + + Returns + ------- + bool + """ + try: + v = _in_scalar(v) + return _cy.is_valid_vertex(v) + except (ValueError, TypeError): + return False diff --git a/tasksnest/lib/python3.13/site-packages/h3/api/memview_int/_convert.py b/tasksnest/lib/python3.13/site-packages/h3/api/memview_int/_convert.py new file mode 100644 index 0000000..2f054fd --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/api/memview_int/_convert.py @@ -0,0 +1,8 @@ +def _id(x): + return x + + +_in_scalar = _id +_out_scalar = _id +_in_collection = _id +_out_collection = _id diff --git a/tasksnest/lib/python3.13/site-packages/h3/api/numpy_int/__init__.py b/tasksnest/lib/python3.13/site-packages/h3/api/numpy_int/__init__.py new file mode 100644 index 0000000..1086a63 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/api/numpy_int/__init__.py @@ -0,0 +1,1369 @@ +# This file is **symlinked** across the APIs to ensure they are exactly the same. +from typing import Literal +from array import array + +from ... import _cy +from ..._h3shape import ( + H3Shape, + LatLngPoly, + LatLngMultiPoly, + geo_to_h3shape, + h3shape_to_geo, +) + +from ._convert import ( + _in_scalar, + _out_scalar, + _in_collection, + _out_collection, +) + + +def versions(): + """ + Version numbers for the Python (wrapper) and C (wrapped) libraries. + + Versions are output as strings of the form ``'X.Y.Z'``. + C and Python should match on ``X`` (major) and ``Y`` (minor), + but may differ on ``Z`` (patch). + + Returns + ------- + dict like ``{'c': 'X.Y.Z', 'python': 'A.B.C'}`` + """ + from ..._version import __version__ + + v = { + 'c': _cy.c_version(), + 'python': __version__, + } + + return v + + +def str_to_int(h): + """ + Converts a hexadecimal string to an H3 64-bit integer index. + + Parameters + ---------- + h : str + Hexadecimal string like ``'89754e64993ffff'`` + + Returns + ------- + int + Unsigned 64-bit integer + """ + return _cy.str_to_int(h) + + +def int_to_str(x): + """ + Converts an H3 64-bit integer index to a hexadecimal string. + + Parameters + ---------- + x : int + Unsigned 64-bit integer + + Returns + ------- + str + Hexadecimal string like ``'89754e64993ffff'`` + """ + return _cy.int_to_str(x) + + +def get_num_cells(res): + """ + Return the total number of *cells* (hexagons and pentagons) + for the given resolution. + + Returns + ------- + int + """ + return _cy.get_num_cells(res) + + +def average_hexagon_area(res, unit='km^2'): + """ + Return the average area of an H3 *hexagon* + for the given resolution. + + This average *excludes* pentagons. + + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) + + Returns + ------- + float + """ + return _cy.average_hexagon_area(res, unit) + + +def average_hexagon_edge_length(res, unit='km'): + """ + Return the average *hexagon* edge length + for the given resolution. + + This average *excludes* pentagons. + + Parameters + ---------- + res : int + H3 resolution + unit: str + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) + + Returns + ------- + float + """ + return _cy.average_hexagon_edge_length(res, unit) + + +def is_valid_index(h): + """Validates *any* H3 index (cell, vertex, or directed edge). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_index(h) + except (ValueError, TypeError): + return False + + +def is_valid_cell(h): + """ + Validates an H3 cell (hexagon or pentagon). + + Returns + ------- + bool + """ + try: + h = _in_scalar(h) + return _cy.is_valid_cell(h) + except (ValueError, TypeError): + return False + + +def is_valid_directed_edge(edge): + """ + Validates an H3 directed edge. + + Returns + ------- + bool + """ + try: + e = _in_scalar(edge) + return _cy.is_valid_directed_edge(e) + except (ValueError, TypeError): + return False + + +def latlng_to_cell(lat, lng, res): + """ + Return the cell containing the (lat, lng) point + for a given resolution. + + Returns + ------- + H3Cell + + """ + return _out_scalar(_cy.latlng_to_cell(lat, lng, res)) + + +def cell_to_latlng(h): + """ + Return the center point of an H3 cell as a lat/lng pair. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + h = _in_scalar(h) + return _cy.cell_to_latlng(h) + + +def get_resolution(h): + """ + Return the resolution of an H3 cell. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + """ + # todo: could also work for edges + h = _in_scalar(h) + return _cy.get_resolution(h) + + +def cell_to_parent(h, res=None): + """ + Get the parent of a cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the parent + If ``None``, then ``res = resolution(h) - 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_parent(h, res) + p = _out_scalar(p) + + return p + + +def grid_distance(h1, h2): + """ + Compute the grid distance between two cells. + + The grid distance is defined as the length of the shortest + path between the cells in the graph formed by connecting + adjacent cells. + + This function will raise an exception if the + cells are too far apart to compute the distance. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + int + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + d = _cy.grid_distance(h1, h2) + + return d + + +def cell_to_boundary(h): + """ + Return tuple of lat/lng pairs describing the cell boundary. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + tuple of (lat, lng) tuples + """ + h = _in_scalar(h) + return _cy.cell_to_boundary(h) + + +def grid_disk(h, k=1): + """ + Return unordered collection of cells with grid distance ``<= k`` from ``h``. + That is, the "filled-in" disk. + + Parameters + ---------- + h : H3Cell + k : int + Size of disk. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.grid_disk(h, k) + + return _out_collection(mv) + + +def grid_ring(h, k=1): + """ + Return unordered collection of cells with grid distance ``== k`` from ``h``. + That is, the "hollow" ring. + + Parameters + ---------- + h : H3Cell + k : int + Size of ring. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.grid_ring(h, k) + + return _out_collection(mv) + + +def cell_to_children_size(h, res=None): + """ + Number of children at resolution ``res`` of given cell. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + int + Count of children + """ + h = _in_scalar(h) + return _cy.cell_to_children_size(h, res) + + +def cell_to_children(h, res=None): + """ + Children of a cell as an unordered collection. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the children. + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h = _in_scalar(h) + mv = _cy.cell_to_children(h, res) + + return _out_collection(mv) + + +def cell_to_child_pos(child, res_parent): + """ + Child position index of given cell, with respect to its parent at ``res_parent``. + + The reverse operation can be done with ``child_pos_to_cell``. + + Parameters + ---------- + child : H3Cell + res_parent : int + + Returns + ------- + int + Integer index of the child with respect to parent cell. + """ + child = _in_scalar(child) + return _cy.cell_to_child_pos(child, res_parent) + + +def child_pos_to_cell(parent, res_child, child_pos): + """ + Get child H3 cell from a parent cell, child resolution, and child position index. + + The reverse operation can be done with ``cell_to_child_pos``. + + Parameters + ---------- + parent : H3Cell + res_child : int + Child cell resolution + child_pos : int + Integer position of child cell, releative to parent. + + + Returns + ------- + H3Cell + """ + parent = _in_scalar(parent) + child = _cy.child_pos_to_cell(parent, res_child, child_pos) + child = _out_scalar(child) + + return child + + +# todo: nogil for expensive C operation? +def compact_cells(cells): + """ + Compact a collection of H3 cells by combining + smaller cells into larger cells, if all child cells + are present. Input cells must all share the same resolution. + + Parameters + ---------- + cells : iterable of H3 Cells + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + hu = _in_collection(cells) + hc = _cy.compact_cells(hu) + + return _out_collection(hc) + + +def uncompact_cells(cells, res): + """ + Reverse the ``compact_cells`` operation. + + Return a collection of H3 cells, all of resolution ``res``. + + Parameters + ---------- + cells : iterable of H3Cell + res : int + Resolution of desired output cells. + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + # TODO: add test to make sure an error is returned when input contains cell + # smaller than output res. + + hc = _in_collection(cells) + hu = _cy.uncompact_cells(hc, res) + + return _out_collection(hu) + + +def polygon_to_cells(h3shape, res): + """ + Alias for ``h3shape_to_cells``. + """ + return h3shape_to_cells(h3shape, res) + + +def h3shape_to_cells(h3shape, res): + """ + Return the collection of H3 cells at a given resolution whose center points + are contained within an ``LatLngPoly`` or ``LatLngMultiPoly``. + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells(poly, 6) + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells(poly.outer, res=res, holes=poly.holes) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells(mpoly.polys, res=res) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) + + +def polygon_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): + """ + Alias for ``h3shape_to_cells_experimental``. + """ + return h3shape_to_cells_experimental(h3shape, res, contain) + + +def h3shape_to_cells_experimental( + h3shape: H3Shape, + res: int, + contain: Literal['center', 'full', 'overlap', 'bbox_overlap'] = 'center', +): + """ + Experimental function similar to ``h3shape_to_cells``, but with support for + multiple cell containment modes. + + Using ``contain='center'`` should give identical behavior as + ``h3shape_to_cells``. + + Note that this function is **experimental** and has no API stability gaurantees + across versions, so it may change in the future. + + + Parameters + ---------- + h3shape : ``H3Shape`` + res : int + Resolution of the output cells + contain : {'center', 'full', 'overlap', 'bbox_overlap'}, optional + Specifies the containment condition. + - 'center': Cell center is contained in shape + - 'full': Cell is fully contained in shape + - 'overlap': Cell is partially contained in shape + - 'bbox_overlap': Cell bounding box is partially contained in shape + + Default is 'center'. + + Returns + ------- + list of H3Cell + + Examples + -------- + + >>> poly = LatLngPoly( + ... [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), + ... (37.82, -122.54)], + ... ) + >>> h3.h3shape_to_cells_experimental(poly, 6, 'center') + ['862830807ffffff', + '862830827ffffff', + '86283082fffffff', + '862830877ffffff', + '862830947ffffff', + '862830957ffffff', + '86283095fffffff'] + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + + contain_modes = { + 'center': 0, + 'full': 1, + 'overlap': 2, + 'bbox_overlap': 3, + } + + flag = contain_modes[contain] + + # todo: not sure if i want this dispatch logic here. maybe in the objects? + if isinstance(h3shape, LatLngPoly): + poly = h3shape + mv = _cy.polygon_to_cells_experimental( + poly.outer, + res = res, + holes = poly.holes, + flag = flag, + ) + elif isinstance(h3shape, LatLngMultiPoly): + mpoly = h3shape + mv = _cy.polygons_to_cells_experimental(mpoly.polys, res=res, flag=flag) + elif isinstance(h3shape, H3Shape): + raise ValueError('Unrecognized H3Shape: ' + str(h3shape)) + else: + raise ValueError('Unrecognized type: ' + str(type(h3shape))) + + return _out_collection(mv) + + +def cells_to_h3shape(cells, *, tight=True): + """ + Return an ``H3Shape`` describing the area covered by a collection of H3 cells. + Will return ``LatLngPoly`` or ``LatLngMultiPoly``. + + Parameters + ---------- + cells : iterable of H3 cells + tight : bool + If True, return ``LatLngPoly`` if possible. + If False, always return ``LatLngMultiPoly``. + + Returns + ------- + LatLngPoly | LatLngMultiPoly + + Examples + -------- + + >>> cells = ['8428309ffffffff', '842830dffffffff'] + >>> h3.cells_to_h3shape(cells, tight=True) + + >>> h3.cells_to_h3shape(cells, tight=False) + + """ + cells = _in_collection(cells) + mpoly = _cy.cells_to_multi_polygon(cells) + + polys = [LatLngPoly(*poly) for poly in mpoly] + out = LatLngMultiPoly(*polys) + + if tight and len(out) == 1: + out = out[0] + + return out + + +def geo_to_cells(geo, res): + """Convert from ``__geo_interface__`` to cells. + + Parameters + ---------- + geo : an object implementing ``__geo_interface__`` or a dictionary in that format. + Both ``LatLngPoly`` and ``LatLngMultiPoly`` implement the interface. + res : int + Resolution of desired output cells. + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + h3shape = geo_to_h3shape(geo) + return h3shape_to_cells(h3shape, res) + + +def cells_to_geo(cells, tight=True): + """ + Convert from cells to a ``__geo_interface__`` dict. + + Parameters + ---------- + cells : iterable of H3 Cells + tight : bool + When ``True``, returns an ``LatLngPoly`` when possible. + When ``False``, always returns an ``LatLngMultiPoly``. + + Returns + ------- + dict + in `__geo_interface__` format + """ + h3shape = cells_to_h3shape(cells, tight=tight) + return h3shape_to_geo(h3shape) + + +def is_pentagon(h): + """ + Identify if an H3 cell is a pentagon. + + Parameters + ---------- + h : H3Index + + Returns + ------- + bool + ``True`` if input is a valid H3 cell which is a pentagon. + + Notes + ----- + A pentagon should *also* pass ``is_valid_cell()``. + Will return ``False`` for valid H3Edge. + """ + return _cy.is_pentagon(_in_scalar(h)) + + +def get_base_cell_number(h): + """ + Return the base cell *number* (``0`` to ``121``) of the given cell. + + The base cell *number* and the H3Index are two different representations + of the same cell: the parent cell of resolution ``0``. + + The base cell *number* is encoded within the corresponding + H3Index. + + todo: could work with edges + + Parameters + ---------- + h : H3Cell + + Returns + ------- + int + + Examples + -------- + >>> h = construct_cell(57, 2, 1, 4) + >>> h + '83728cfffffffff' + >> get_base_cell_number(h) + 57 + """ + return _cy.get_base_cell_number(_in_scalar(h)) + + +def get_index_digit(h, res): + """ + Get the index digit of a cell at the given resolution. + + Parameters + ---------- + h : H3Cell + Cell whose index digit will be returned. + res : int + Resolution (``>= 1``) at which to read the digit. + + Returns + ------- + int + The index digit at the requested resolution. + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) + >>> h + '830e8cfffffffff' + >>> get_index_digit(h, 1) + 2 + >>> get_index_digit(h, 2) + 1 + >>> get_index_digit(h, 3) + 4 + """ + return _cy.get_index_digit(_in_scalar(h), res) + + +def construct_cell(base_cell_number, *digits, res=None): + """ + Construct cell from base cell and digits. + + Parameters + ---------- + base_cell_number : int + Base cell *number* (``0`` to ``121``). + *digits : int + Sequence of index digits (``0`` to ``6``). + Length of digits will be the resulting resolution of the output cell. + res : int, optional + Resolution of the constructed cell. If provided, it must equal + ``len(digits)``; otherwise it is inferred from the number of digits. + + Returns + ------- + H3Cell + The constructed cell. + + Examples + -------- + >>> construct_cell(7, 2, 1, 4) # resolution 3 cell + '830e8cfffffffff' + + >>> construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + '841e057ffffffff' + + >>> construct_cell(15, 0, 0, 5, 3, res=4) + '841e057ffffffff' + """ + if (res is not None) and (len(digits) != res): + raise ValueError('Resolution must match number of digits.') + + digits = array('i', digits) + o = _cy.construct_cell(base_cell_number, digits) + return _out_scalar(o) + + +def deconstruct_cell(h): + """ + Deconstruct cell into base cell and digits. + + Parameters + ---------- + h : H3Cell + Cell to deconstruct. + + Returns + ------- + list of int + [base_cell_number, digit1, digit2, ..., digitN] + + Examples + -------- + >>> h = construct_cell(7, 2, 1, 4) # resolution 3 cell + >>> h + '830e8cfffffffff' + >>> deconstruct_cell(h) + (7, 2, 1, 4) + + >>> h = construct_cell(15, 0, 0, 5, 3) # resolution 4 cell + >>> h + '841e057ffffffff' + >>> deconstruct_cell(h) + (15, 0, 0, 5, 3) + >>> construct_cell(*deconstruct_cell(h), 0) == cell_to_center_child(h) + """ + res = get_resolution(h) + bc = get_base_cell_number(h) + digits = [get_index_digit(h, r + 1) for r in range(res)] + + return [bc, *digits] + + +def are_neighbor_cells(h1, h2): + """ + Returns ``True`` if ``h1`` and ``h2`` are neighboring cells. + + Parameters + ---------- + h1 : H3Cell + h2 : H3Cell + + Returns + ------- + bool + """ + h1 = _in_scalar(h1) + h2 = _in_scalar(h2) + + return _cy.are_neighbor_cells(h1, h2) + + +def cells_to_directed_edge(origin, destination): + """ + Create an H3 Index denoting a unidirectional edge. + + The edge is constructed from neighboring cells ``origin`` and + ``destination``. + + Parameters + ---------- + origin : H3Cell + destination : H3Cell + + Raises + ------ + ValueError + When cells are not adjacent. + + Returns + ------- + H3Edge + """ + o = _in_scalar(origin) + d = _in_scalar(destination) + e = _cy.cells_to_directed_edge(o, d) + e = _out_scalar(e) + + return e + + +def get_directed_edge_origin(e): + """ + Origin cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + o = _cy.get_directed_edge_origin(e) + o = _out_scalar(o) + + return o + + +def get_directed_edge_destination(e): + """ + Destination cell from an H3 directed edge. + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + """ + e = _in_scalar(e) + d = _cy.get_directed_edge_destination(e) + d = _out_scalar(d) + + return d + + +def directed_edge_to_cells(e): + """ + Return (origin, destination) tuple from H3 directed edge + + Parameters + ---------- + e : H3Edge + + Returns + ------- + H3Cell + Origin cell of edge + H3Cell + Destination cell of edge + """ + e = _in_scalar(e) + o, d = _cy.directed_edge_to_cells(e) + o, d = _out_scalar(o), _out_scalar(d) + + return o, d + + +def origin_to_directed_edges(origin): + """ + Return all directed edges starting from ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + + Returns + ------- + unordered collection of H3Edge + """ + mv = _cy.origin_to_directed_edges(_in_scalar(origin)) + + return _out_collection(mv) + + +def directed_edge_to_boundary(edge): + """ + Returns points representing the edge (line of points + describing the boundary between two cells). + + Parameters + ---------- + edge : H3Edge + + Returns + ------- + tuple of (lat, lng) tuples + """ + return _cy.directed_edge_to_boundary(_in_scalar(edge)) + + +def grid_path_cells(start, end): + """ + Returns the ordered collection of cells denoting a + minimum-length non-unique path between cells. + + Parameters + ---------- + start : H3Cell + end : H3Cell + + Returns + ------- + ordered collection of H3Cell + Starting with ``start``, and ending with ``end``. + """ + mv = _cy.grid_path_cells(_in_scalar(start), _in_scalar(end)) + + return _out_collection(mv) + + +def is_res_class_III(h): + """ + Determine if cell has orientation "Class II" or "Class III". + + The orientation of pentagons/hexagons on the icosahedron can be one + of two types: "Class II" or "Class III". + + All cells within a resolution have the same type, and the type + alternates between resolutions. + + "Class II" cells have resolutions: 0,2,4,6,8,10,12,14 + "Class III" cells have resolutions: 1,3,5,7,9,11,13,15 + + Parameters + ---------- + h : H3Cell + + Returns + ------- + bool + ``True`` if ``h`` is "Class III". + ``False`` if ``h`` is "Class II". + + References + ---------- + 1. https://uber.github.io/h3/#/documentation/core-library/coordinate-systems + """ + return _cy.is_res_class_iii(_in_scalar(h)) + + +def get_pentagons(res): + """ + Return all pentagons at a given resolution. + + Parameters + ---------- + res : int + Resolution of the pentagons + + Returns + ------- + unordered collection of H3Cell + """ + mv = _cy.get_pentagons(res) + + return _out_collection(mv) + + +def get_res0_cells(): + """ + Return all cells at resolution 0. + + Parameters + ---------- + None + + Returns + ------- + unordered collection of H3Cell + + Notes + ----- + There is currently no guaranteed order of the output cells. + """ + mv = _cy.get_res0_cells() + + return _out_collection(mv) + + +def cell_to_center_child(h, res=None): + """ + Get the center child of a cell at some finer resolution. + + Parameters + ---------- + h : H3Cell + res : int or None, optional + The resolution for the child cell + If ``None``, then ``res = resolution(h) + 1`` + + Returns + ------- + H3Cell + """ + h = _in_scalar(h) + p = _cy.cell_to_center_child(h, res) + p = _out_scalar(p) + + return p + + +def get_icosahedron_faces(h): + """ + Return icosahedron faces intersecting a given H3 cell. + + There are twenty possible faces, ranging from 0--19. + + Note: Every interface returns a Python ``set`` of ``int``. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + Python ``set`` of ``int`` + """ + h = _in_scalar(h) + faces = _cy.get_icosahedron_faces(h) + + return faces + + +def cell_to_local_ij(origin, h): + """ + Return local (i,j) coordinates of cell ``h`` in relation to ``origin`` cell + + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + h: H3Cell + Destination cell whose i,j coordinates we'd like, based off + of the origin cell. + + + Returns + ------- + Tuple (i, j) of integer local coordinates of cell ``h`` + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of `origin`. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + h = _in_scalar(h) + + i, j = _cy.cell_to_local_ij(origin, h) + + return i, j + + +def local_ij_to_cell(origin, i, j): + """ + Return cell at local (i,j) position relative to the ``origin`` cell. + + Parameters + ---------- + origin : H3Cell + Origin/central cell for defining i,j coordinates. + i, j: int + Integer coordinates with respect to ``origin`` cell. + + + Returns + ------- + H3Cell at local (i,j) position relative to the ``origin`` cell + + + Notes + ----- + + The ``origin`` cell does not define (0, 0) for the IJ coordinate space. + (0, 0) refers to the center of the base cell containing origin at the + resolution of ``origin``. + Subtracting the IJ coordinates of ``origin`` from every cell would get + you the property of (0, 0) being the ``origin``. + + This is done so we don't need to keep recomputing the coordinates of + ``origin`` if not needed. + """ + origin = _in_scalar(origin) + + h = _cy.local_ij_to_cell(origin, i, j) + h = _out_scalar(h) + + return h + + +def cell_area(h, unit='km^2'): + """ + Compute the spherical surface area of a specific H3 cell. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for area result (``'km^2'``, ``'m^2'``, or ``'rads^2'``) + + + Returns + ------- + The area of the H3 cell in the given units + + + Notes + ----- + This function breaks the cell into spherical triangles, and computes + their spherical area. + The function uses the spherical distance calculation given by + ``great_circle_distance()``. + """ + h = _in_scalar(h) + + return _cy.cell_area(h, unit=unit) + + +def edge_length(e, unit='km'): + """ + Compute the spherical length of a specific H3 edge. + + Parameters + ---------- + h : H3Cell + unit: str + Unit for length result (``'km'``, ``'m'``, or ``'rads'``) + + + Returns + ------- + The length of the edge in the given units + + + Notes + ----- + This function uses the spherical distance calculation given by + ``great_circle_distance()``. + """ + e = _in_scalar(e) + + return _cy.edge_length(e, unit=unit) + + +def great_circle_distance(latlng1, latlng2, unit='km'): + """ + Compute the spherical distance between two (lat, lng) points. + AKA: great circle distance or "haversine" distance. + + todo: overload to allow two cell inputs? + + Parameters + ---------- + latlng1 : tuple + (lat, lng) tuple in degrees + latlng2 : tuple + (lat, lng) tuple in degrees + unit: str + Unit for distance result (``'km'``, ``'m'``, or ``'rads'``) + + Returns + ------- + The spherical distance between the points in the given units + """ + lat1, lng1 = latlng1 + lat2, lng2 = latlng2 + return _cy.great_circle_distance( + lat1, lng1, + lat2, lng2, + unit = unit + ) + + +def cell_to_vertex(h, vertex_num): + """ + Return a (specified) vertex of an H3 cell. + + Parameters + ---------- + h : H3Cell + vertex_num : int + Vertex number (0-5) + + Returns + ------- + The vertex + """ + h = _in_scalar(h) + h = _cy.cell_to_vertex(h, vertex_num) + return _out_scalar(h) + + +def cell_to_vertexes(h): + """ + Return a list of vertexes of an H3 cell. + The list will be of length 5 for pentagons and 6 for hexagons. + + Parameters + ---------- + h : H3Cell + + Returns + ------- + A list of vertexes + """ + h = _in_scalar(h) + mv = _cy.cell_to_vertexes(h) + return _out_collection(mv) + + +def vertex_to_latlng(v): + """ + Return latitude and longitude of a vertex. + + Returns + ------- + lat : float + Latitude + lng : float + Longitude + """ + v = _in_scalar(v) + return _cy.vertex_to_latlng(v) + + +def is_valid_vertex(v): + """ + Validates an H3 vertex. + + Returns + ------- + bool + """ + try: + v = _in_scalar(v) + return _cy.is_valid_vertex(v) + except (ValueError, TypeError): + return False diff --git a/tasksnest/lib/python3.13/site-packages/h3/api/numpy_int/_convert.py b/tasksnest/lib/python3.13/site-packages/h3/api/numpy_int/_convert.py new file mode 100644 index 0000000..6b293cc --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/h3/api/numpy_int/_convert.py @@ -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 diff --git a/tasksnest/lib/python3.13/site-packages/include/h3/h3api.h b/tasksnest/lib/python3.13/site-packages/include/h3/h3api.h new file mode 100644 index 0000000..e882106 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/include/h3/h3api.h @@ -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 +/* For size_t */ +#include + +/* + * 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 diff --git a/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Config.cmake b/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Config.cmake new file mode 100644 index 0000000..0aed3d6 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Config.cmake @@ -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") diff --git a/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3ConfigVersion.cmake b/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3ConfigVersion.cmake new file mode 100644 index 0000000..5b22fd1 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3ConfigVersion.cmake @@ -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() diff --git a/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Targets-release.cmake b/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Targets-release.cmake new file mode 100644 index 0000000..f7e32e3 --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Targets-release.cmake @@ -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) diff --git a/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Targets.cmake b/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Targets.cmake new file mode 100644 index 0000000..e145c9e --- /dev/null +++ b/tasksnest/lib/python3.13/site-packages/lib64/cmake/h3/h3Targets.cmake @@ -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) diff --git a/tasksnest/lib/python3.13/site-packages/lib64/libh3.a b/tasksnest/lib/python3.13/site-packages/lib64/libh3.a new file mode 100644 index 0000000000000000000000000000000000000000..559662e494e1ae44696eb8719a96fb8a79cf7b71 GIT binary patch literal 185890 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