h3v 0.1.0__py3-none-any.whl

_h3v_core.py

@@ -0,0 +1,197 @@
+"""Shared H3V format constants, validation, and exact radial arithmetic.
+
+Internal support only: this module imports no API category or facade.
+"""
+
+from numbers import Rational
+import math
+
+from h3.api import basic_int as h3
+
+
+
+
+_AUTHALIC_EARTH_RADIUS_KM = 6371.007180918475
+RADIAL_BASE_STEP = _AUTHALIC_EARTH_RADIUS_KM
+MAX_RADIAL_RESOLUTION = 10
+_RADIAL_BASE_CELLS = 256
+
+MAX_ALTITUDE = (_RADIAL_BASE_CELLS - 1) * _AUTHALIC_EARTH_RADIUS_KM
+
+_EARTH_RADIUS_NUMERATOR, _EARTH_RADIUS_DENOMINATOR = (
+    _AUTHALIC_EARTH_RADIUS_KM.as_integer_ratio()
+)
+_MAX_SURFACE_RESOLUTION = 15
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+_HALF_BITS = 64
+_PACKED_BITS = 2 * _HALF_BITS
+_BITS_PER_DIGIT = 4
+_DIGIT_MASK = 0xF
+_RADIAL_DIGIT_SLOTS = 10
+_BASE_SHIFT = _BITS_PER_DIGIT * _RADIAL_DIGIT_SLOTS
+_BASE_MASK = 0xFF
+_RESOLUTION_SHIFT = _BASE_SHIFT + 8
+_FORMAT_SHIFT = 60
+_FORMAT_VERSION = 4
+_HEADER = _FORMAT_VERSION << _FORMAT_SHIFT
+_UNUSED_DIGITS = (1 << _BASE_SHIFT) - 1
+_MASK64 = (1 << _HALF_BITS) - 1
+_RADIAL_DIRECTION_SHIFT = _RESOLUTION_SHIFT + _BITS_PER_DIGIT
+_RADIAL_DIRECTION_MASK = 3 << _RADIAL_DIRECTION_SHIFT
+_RADIAL_RESERVED_SHIFT = _RADIAL_DIRECTION_SHIFT + 2
+_RADIAL_RESERVED_MASK = ((1 << (_FORMAT_SHIFT - _RADIAL_RESERVED_SHIFT)) - 1) << _RADIAL_RESERVED_SHIFT
+
+
+_RADIAL_METADATA_MASK = (
+    (0xF << _FORMAT_SHIFT) | _RADIAL_RESERVED_MASK | _RADIAL_DIRECTION_MASK
+)
+
+
+def _resolution(value, maximum, name):
+    """Require an ordinary integer level; reject booleans as well as floats."""
+    if type(value) is not int or not 0 <= value <= maximum:
+        raise ValueError(f"{name} must be an integer from 0 to {maximum}")
+    return value
+
+
+def _number_ratio(value, name):
+    """Return a supported finite number as two exact integers, without rational objects.
+
+    Rational accepts Python integer/rational inputs without importing fractions.
+    Normalize components to Python int before arithmetic to avoid fixed-width overflow.
+    Floats supply their own exact as_integer_ratio() conversion.
+    """
+    if isinstance(value, bool) or not isinstance(value, (Rational, float)):
+        raise ValueError(f"{name} must be a finite number")
+    if isinstance(value, Rational):
+        return int(value.numerator), int(value.denominator)
+    try:
+        return value.as_integer_ratio()
+    except (ValueError, OverflowError) as exc:
+        raise ValueError(f"{name} must be finite") from exc
+
+
+def _ratio(numerator, denominator):
+    """Reduce an exact ratio; all internal denominators are positive."""
+    divisor = math.gcd(numerator, denominator)
+    return numerator // divisor, denominator // divisor
+
+
+def _sum_ratios(left, right):
+    """Add integer ratios using a common denominator without unnecessary growth."""
+    left_numerator, left_denominator = left
+    right_numerator, right_denominator = right
+    divisor = math.gcd(left_denominator, right_denominator)
+    return _ratio(
+        left_numerator * (right_denominator // divisor)
+        + right_numerator * (left_denominator // divisor),
+        left_denominator * (right_denominator // divisor),
+    )
+
+
+def _pack_radial(bin_number, resolution):
+    """Pack a radius-based logical bin coordinate, increasing with physical radius."""
+    _resolution(resolution, MAX_RADIAL_RESOLUTION, "radial resolution")
+    base_bin, refinement = divmod(bin_number, 7**resolution)
+    if not 0 <= base_bin < _RADIAL_BASE_CELLS:
+        raise ValueError("unsupported radial base number")
+
+    digit_bits = _UNUSED_DIGITS
+
+
+    for level in range(resolution - 1, -1, -1):
+        refinement, position = divmod(refinement, 7)
+        shift = _BITS_PER_DIGIT * (_RADIAL_DIGIT_SLOTS - 1 - level)
+        digit_bits = (digit_bits & ~(_DIGIT_MASK << shift)) | (position << shift)
+    return (
+        _HEADER
+        | (resolution << _RESOLUTION_SHIFT)
+        | (base_bin << _BASE_SHIFT)
+        | digit_bits
+    )
+
+
+def _read_radial(radial_index):
+    """Validate and return (resolution, radius-based logical bin coordinate)."""
+    if type(radial_index) is not int or not 0 <= radial_index < 1 << _HALF_BITS:
+        raise ValueError("radial index must be an unsigned 64-bit integer")
+    if radial_index & _RADIAL_METADATA_MASK != _HEADER:
+        raise ValueError("radial format version must be 4; direction and reserved bits must be zero")
+    resolution = _resolution(
+        (radial_index >> _RESOLUTION_SHIFT) & _DIGIT_MASK,
+        MAX_RADIAL_RESOLUTION,
+        "radial resolution",
+    )
+    bin_number = (radial_index >> _BASE_SHIFT) & _BASE_MASK
+    for level in range(_RADIAL_DIGIT_SLOTS):
+        shift = _BITS_PER_DIGIT * (_RADIAL_DIGIT_SLOTS - 1 - level)
+        digit = (radial_index >> shift) & _DIGIT_MASK
+        if level < resolution:
+            if not 0 <= digit <= 6:
+                raise ValueError("active radial digits must be 0..6")
+            bin_number = bin_number * 7 + digit
+        elif digit != _DIGIT_MASK:
+            raise ValueError("unused radial digits must be f")
+    return resolution, bin_number
+
+
+def _read_index(index):
+    """Validate and return surface, radial, radial level, and radius-based logical bin."""
+    if type(index) is not int or not 0 <= index < 1 << _PACKED_BITS:
+        raise ValueError("packed index must be an unsigned 128-bit integer")
+    surface = index & _MASK64
+    radial = index >> _HALF_BITS
+    if not h3.is_valid_cell(surface):
+        raise ValueError("surface index must be a valid unsigned 64-bit H3 cell")
+    resolution, bin_number = _read_radial(radial)
+    return surface, radial, resolution, bin_number
+
+
+def _read_directed_edge(index):
+    """Validate an edge and return its (origin voxel, destination voxel)."""
+    if type(index) is not int or not 0 <= index < 1 << _PACKED_BITS:
+        raise ValueError("packed edge must be an unsigned 128-bit integer")
+    surface = index & _MASK64
+    marked_radial = index >> _HALF_BITS
+    direction = (marked_radial & _RADIAL_DIRECTION_MASK) >> _RADIAL_DIRECTION_SHIFT
+    radial = marked_radial & ~_RADIAL_DIRECTION_MASK
+    resolution, bin_number = _read_radial(radial)
+    if direction == 0:
+        if not h3.is_valid_directed_edge(surface):
+            raise ValueError("lateral edge requires a valid H3 directed edge")
+        origin, destination = h3.directed_edge_to_cells(surface)
+        return (radial << _HALF_BITS) | origin, (radial << _HALF_BITS) | destination
+    if direction == 3 or not h3.is_valid_cell(surface):
+        raise ValueError("radial edge requires one radial direction and an H3 cell")
+    destination_bin = bin_number + (-1 if direction == 1 else 1)
+    if not 0 <= destination_bin < _RADIAL_BASE_CELLS * 7**resolution:
+        raise ValueError("radial edge destination is outside the domain")
+    destination_radial = _pack_radial(destination_bin, resolution)
+    return (radial << _HALF_BITS) | surface, (destination_radial << _HALF_BITS) | surface
+
+
+def _validate_object(index):
+    """Validate a voxel or directed edge without relaxing voxel validation."""
+    if type(index) is not int or not 0 <= index < 1 << _PACKED_BITS:
+        raise ValueError("packed index must be an unsigned 128-bit integer")
+    if (index >> _HALF_BITS) & _RADIAL_DIRECTION_MASK or not h3.is_valid_cell(index & _MASK64):
+        _read_directed_edge(index)
+    else:
+        _read_index(index)
+
+
+__all__ = []

h3v-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: h3v
+Version: 0.1.0
+Summary: Packed 128-bit H3 volume indices with independent surface and radial resolutions
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/piglabsai/h3v
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: h3==4.5.0
+Provides-Extra: docs
+Requires-Dist: sphinx<9,>=7.4; extra == "docs"
+Requires-Dist: myst-parser<5,>=3; extra == "docs"
+Requires-Dist: sphinx-book-theme<2,>=1.1; extra == "docs"
+Dynamic: license-file
+
+# H3V: H3 cells with altitude
+
+**Experimental preview 0.1.0.** Public API and serialized-index compatibility
+are not yet guaranteed. Record the H3V package version alongside persisted
+voxel IDs. The encoded format version is currently 4.
+
+**A voxel is H3V's equivalent of an H3 cell: a region with an ID.**
+An H3 cell covers an area on Earth's surface. An H3V voxel combines that
+cell with an altitude interval, giving it a vertical extent as well.
+
+The starting operation is **latitude + longitude + altitude -> voxel ID**, using
+`latlngalt_to_voxel()`. It works like H3's `latlng_to_cell()`, with altitude
+and a separate radial resolution (altitude detail) added.
+
+Use H3V to group positions by voxel, change grid detail, get boundaries for
+drawing, calculate volumes, or measure straight lines between voxel centers.
+Convert Earth-centered, Earth-fixed (ECEF) coordinates in kilometres using
+`ecef_to_voxel()` and `voxel_to_ecef()`. ECEF indexing defaults to surface
+resolution 15 and radial resolution 10; decoding returns the voxel center.
+
+## Install
+
+From a checkout of this repository, with Python 3.10 or later:
+
+```console
+python -m pip install .
+```
+
+The H3 dependency is installed automatically.
+
+## First example
+
+Find the voxel containing a point at latitude 52 degrees, longitude 13 degrees,
+and altitude 1 km:
+
+```python
+import h3v
+
+voxel = h3v.latlngalt_to_voxel(
+    52, 13, 1, surface_resolution=9, radial_resolution=7
+)
+print(h3v.get_resolution(voxel))  # (9, 7)
+
+latitude, longitude, altitude_km = h3v.voxel_to_latlngalt(voxel)
+print(round(altitude_km, 4))  # 1.0018
+```
+
+The integer `voxel` identifies a region, not the original point. Decoding
+returns the voxel center, so its altitude can differ from the input.
+
+`surface_resolution` controls horizontal detail. `radial_resolution` controls
+altitude thickness; level 7 is about 7.74 m thick. The two choices are independent.
+
+## What to know
+
+- Latitude and longitude use degrees; altitude uses kilometres.
+- Altitudes refer to a spherical Earth surface with an Earth radius of about
+  6,371 km, not terrain or an ellipsoid.
+- Every voxel ID represents a positive-volume voxel, including at altitude zero.
+  Both resolutions are required; bare H3 cells and old-format IDs are invalid.
+  Format v4 uses unsigned radial bases 0..255 and child digits 0..6 with `f` padding.
+  Base 0 covers Earth's interior; the exact altitude domain is `-R < h < 255*R`,
+  where `R` is the exact ratio represented by `authalic_earth_radius()`.
+- Higher radial resolution divides thickness by seven, up to level 10
+  (about 0.0226 m). Surface resolution follows standard H3 levels 0 through 15.
+- H3 footprint extraction uses H3's integer API. Voxel IDs are Python integers;
+  use `int_to_str()` and `str_to_int()` to exchange them as strings.
+
+H3V is a project-specific extension, not an official H3 format.
+
+## Documentation
+
+- [Understand the grid](docs/concepts.md): voxels, altitude, and resolution.
+- [Usage guide](docs/usage.md): common tasks with runnable examples.
+- [API quick reference](docs/api_quick.md): find a function by task.
+- [API reference](docs/api_reference.md): parameters, units, and return values.
+- [Format specification](docs/format.md): exact interval rules and encoding.
+- [Contributing](docs/contributing.md): tests, documentation builds, and local preview.
+
+Build the documentation locally with Python 3.12 or later:
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -e ".[docs]"
+.\.venv\Scripts\python.exe -m sphinx -b html -n -W --keep-going docs docs/_build/html
+```
+
+Open `docs/_build/html/index.html`, or follow the contributor guide to serve it
+on localhost. Documentation sources are tracked by Git; the generated HTML is
+not. The current workflow checks documentation without publishing it.
+
+The repository is <https://github.com/piglabsai/h3v>.
+Licensed under the [Apache License 2.0](LICENSE).

h3v-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+_h3v_core.py,sha256=vN_bE6LHQdRDptkmfeL6iUj963vFO1C7gXsjp6zwd4k,7475
+h3v.py,sha256=eToC__3rlHSq_LNFrJvFNlQTfswRrPu8AcN75uUpJP0,2284
+h3v_directed_edges.py,sha256=zFx3serFnCGYT6NR5r_LvPpeou2qbqbQl0uO93USus0,5954
+h3v_geometry.py,sha256=vzwu4xO_djzZ3gaahWsgL2xXol3BeWvX5ISYrtybzyw,20450
+h3v_hierarchy.py,sha256=WCxyWzCrhdWlkUjIa25QDADk9BdOR0T2EQzolY-iuzM,4934
+h3v_indexing.py,sha256=zYKux-zT7OyGLYdGOtQD1kp0LQupUPZ1peuD4pN3XAg,16229
+h3v_inspection.py,sha256=RIuqzHgYKu-xC0lnxLPEUXNn421Z8aHSWJCLH0GKxpw,4731
+h3v_miscellaneous.py,sha256=FhcxpQ-Xs-W7GrB1AS0GU87i2zX-VnRHoULsbfZ5XA0,1358
+h3v_regions.py,sha256=Qnwq6A3_bqIOoIvtZrvrQg2-dN8s7SMCYX0UFFGApK0,88
+h3v_traversal.py,sha256=nrFaD64WFaEsVzvg9p9Cke82LD0Cohy9soLMxy3WCr0,4979
+h3v_vertexes.py,sha256=PQ8zyhxa-3ehV3R4z4gjmdxtDijuYDOd2758Oo3Rfx0,89
+h3v-0.1.0.dist-info/licenses/LICENSE,sha256=x9ojFkiG3QSO2INDLO4tyhtQqkqf8LLicIaFT_aKylQ,11540
+h3v-0.1.0.dist-info/licenses/NOTICE,sha256=-meAH9kkLlS6-r3J3ZlD9U53FWixWyGrAThWriLRofM,410
+h3v-0.1.0.dist-info/METADATA,sha256=_rvXvy7PT08qHChkYRDaypx6JXc9lqF6ixZcIJ1UbCQ,4607
+h3v-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+h3v-0.1.0.dist-info/top_level.txt,sha256=fjdkWvhgcv2LuHFd7PckEVONOXrAXTObnDGulLUz8gs,145
+h3v-0.1.0.dist-info/RECORD,,

h3v-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

h3v-0.1.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 2026 Piglabs
+
+   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.

h3v-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,10 @@
+H3V
+Copyright 2026 H3V contributors
+
+Licensed under the Apache License, Version 2.0. See LICENSE.
+
+H3V is an independent extension and is not an official H3 format.
+H3V depends on H3 through h3-py, projects maintained by Uber Technologies
+and their contributors and distributed separately under Apache License 2.0.
+The authalic Earth radius follows H3's EARTH_RADIUS_KM constant:
+6371.007180918475 kilometres.

h3v-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,11 @@
+_h3v_core
+h3v
+h3v_directed_edges
+h3v_geometry
+h3v_hierarchy
+h3v_indexing
+h3v_inspection
+h3v_miscellaneous
+h3v_regions
+h3v_traversal
+h3v_vertexes

h3v.py

@@ -0,0 +1,66 @@
+"""H3V: a 3D grid whose voxels are the equivalent of H3 surface cells.
+
+A voxel combines an H3 cell with an altitude interval.
+Find a voxel from latitude, longitude, and altitude. Read its center, change
+its resolutions, get outlines for drawing, or measure volumes and straight
+lines between voxel centers. A voxel ID is an ordinary Python integer.
+Convert spherical Earth-centered, Earth-fixed (ECEF) coordinates to voxels,
+or return a voxel center as Cartesian coordinates in kilometres.
+
+Latitude and longitude are degrees; altitude is kilometres above the spherical
+reference Earth surface. Earth radius is about 6,371 km, matching H3.
+Surface resolution controls horizontal detail. Altitude resolution (the API's
+radial_resolution) controls vertical thickness, dividing it by seven per level.
+
+Every voxel has positive radial thickness and volume, including at altitude zero.
+The Earth center is excluded. Public functions raise ValueError for invalid
+arguments; validation predicates return False instead. See the usage guide and
+format specification for examples and the exact geometry contract.
+"""
+
+from h3v_indexing import *
+from h3v_inspection import *
+from h3v_traversal import *
+from h3v_hierarchy import *
+from h3v_regions import *
+from h3v_directed_edges import *
+from h3v_vertexes import *
+from h3v_geometry import *
+from h3v_miscellaneous import *
+
+
+__all__ = [
+    'latlngalt_to_voxel',
+    'voxel_to_latlngalt',
+    'ecef_to_voxel',
+    'voxel_to_ecef',
+    'voxel_to_altitude_bounds',
+    'voxel_to_boundary',
+    'get_resolution',
+    'is_valid_voxel',
+    'voxel_to_cell',
+    'int_to_str',
+    'str_to_int',
+    'grid_distance',
+    'grid_ring',
+    'grid_disk',
+    'voxel_to_parent',
+    'voxel_to_children',
+    'are_neighbor_voxels',
+    'voxels_to_directed_edge',
+    'is_valid_directed_edge',
+    'get_directed_edge_origin',
+    'get_directed_edge_destination',
+    'directed_edge_to_voxels',
+    'origin_to_directed_edges',
+    'reverse_directed_edge',
+    'voxel_volume',
+    'voxels_to_line',
+    'voxels_to_vector_ecef',
+    'voxels_to_great_circle',
+    'visibility_cap_radius',
+    'authalic_earth_radius',
+    'RADIAL_BASE_STEP',
+    'MAX_RADIAL_RESOLUTION',
+    'MAX_ALTITUDE',
+]