diff --git a/.github/workflows/lint_and_coverage.yml b/.github/workflows/lint_and_coverage.yml index c0eb154..8ec1ef1 100644 --- a/.github/workflows/lint_and_coverage.yml +++ b/.github/workflows/lint_and_coverage.yml @@ -6,6 +6,9 @@ on: pull_request: branches: ['*'] +permissions: + contents: read + jobs: linting: name: Lint and Coverage diff --git a/CHANGELOG.md b/CHANGELOG.md index b08eb92..0b6ee3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,11 +15,10 @@ avoid adding features or APIs which do not map onto the [H3 core API](https://uber.github.io/h3/#/documentation/api-reference/). ## Unreleased - -## [4.5.1] - 2026-11-13 - - Fix wheels for Python 3.14.6 free-threading - Add Python 3.14t, 3.15 and 3.15t wheels +- Support `unit='rads'` in `average_hexagon_area` and `average_hexagon_edge_length` (#509) +- Add `container` option to `h3shape_to_geo` (#495) - Fix Android cross-compilation with Buildozer (#494) - Raise `ValueError` instead of `assert` in `geo_to_h3shape` (#500, #502) - Fix `LatLngPoly` loop length check for closed rings (#505) diff --git a/pyproject.toml b/pyproject.toml index ca79213..4430799 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = 'scikit_build_core.build' [project] name = 'h3' -version = '4.5.1' +version = '4.5.0' description = "Uber's hierarchical hexagonal geospatial indexing system" readme = 'readme.md' license = {file = 'LICENSE'} diff --git a/src/h3/_cy/cells.pyx b/src/h3/_cy/cells.pyx index 8b84f9d..f0667e5 100644 --- a/src/h3/_cy/cells.pyx +++ b/src/h3/_cy/cells.pyx @@ -8,6 +8,8 @@ from .util cimport ( check_distance, ) +from .util import EARTH_RADIUS_KM + from .error_system cimport ( H3Error, check_for_error, @@ -322,7 +324,8 @@ cpdef double average_hexagon_area(int resolution, unit='km^2') except -1: # todo: multiple units convert = { 'km^2': 1.0, - 'm^2': 1000*1000.0 + 'm^2': 1000*1000.0, + 'rads^2': 1.0/(EARTH_RADIUS_KM*EARTH_RADIUS_KM), } try: diff --git a/src/h3/_cy/edges.pyx b/src/h3/_cy/edges.pyx index 1d2ef74..7364bd5 100644 --- a/src/h3/_cy/edges.pyx +++ b/src/h3/_cy/edges.pyx @@ -4,6 +4,8 @@ from .h3lib cimport bool, H3int from .error_system cimport check_for_error +from .util import EARTH_RADIUS_KM + from .memory cimport H3MemoryManager # todo: make bint @@ -86,7 +88,8 @@ cpdef double average_hexagon_edge_length(int resolution, unit='km') except -1: # todo: multiple units convert = { 'km': 1.0, - 'm': 1000.0 + 'm': 1000.0, + 'rads': 1.0/EARTH_RADIUS_KM, } try: diff --git a/src/h3/_cy/util.pyx b/src/h3/_cy/util.pyx index 06823d0..74e8f80 100644 --- a/src/h3/_cy/util.pyx +++ b/src/h3/_cy/util.pyx @@ -19,6 +19,10 @@ from .error_system import ( H3IndexInvalidError, ) +# Must match EARTH_RADIUS_KM in h3lib's constants.h, which is not part of the +# public h3api.h header. Used to convert km based averages to radians. +EARTH_RADIUS_KM = 6371.007180918475 + cdef h3lib.LatLng deg2coord(double lat, double lng) nogil: cdef: h3lib.LatLng c diff --git a/src/h3/_h3shape.py b/src/h3/_h3shape.py index 8cfecf0..68d18c2 100644 --- a/src/h3/_h3shape.py +++ b/src/h3/_h3shape.py @@ -184,13 +184,6 @@ 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, ... """ @@ -333,14 +326,63 @@ def geo_to_h3shape(geo): return shape -def h3shape_to_geo(h3shape): +def h3shape_to_geo(h3shape, container='auto'): """ Translate from an ``H3Shape`` to a ``__geo_interface__`` dict. ``h3shape`` should be either ``LatLngPoly`` or ``LatLngMultiPoly`` + Parameters + ---------- + container : str, optional + Specify the desired GeoJSON output container. + Options: 'auto', 'Polygon', 'MultiPolygon', 'Feature', + 'FeatureCollection', or 'GeometryCollection'. + Default is 'auto' (returns the simplest valid geometry). + Returns ------- dict """ - return h3shape.__geo_interface__ + base_geo = h3shape.__geo_interface__ + + # Return immediately if no wrapping is needed + if container == 'auto' or container == base_geo['type']: + return base_geo + + # Upgrade a Polygon to a MultiPolygon if explicitly requested + if container == 'MultiPolygon' and base_geo['type'] == 'Polygon': + return { + 'type': 'MultiPolygon', + 'coordinates': (base_geo['coordinates'],) + } + + if container == 'Feature': + return { + 'type': 'Feature', + 'geometry': base_geo, + 'properties': {} + } + + if container == 'FeatureCollection': + return { + 'type': 'FeatureCollection', + 'features': [{ + 'type': 'Feature', + 'geometry': base_geo, + 'properties': {} + }] + } + + if container == 'GeometryCollection': + return { + 'type': 'GeometryCollection', + 'geometries': [base_geo] + } + + # If we reach here, the requested container is either unknown or + # insufficient for the data (e.g., requesting a Polygon for MultiPolygon data). + raise ValueError( + f"Requested container '{container}' is invalid or insufficient " + f"for data of type '{base_geo['type']}'." + ) diff --git a/src/h3/api/basic_int/__init__.py b/src/h3/api/basic_int/__init__.py index 4b070d7..8eac4b1 100644 --- a/src/h3/api/basic_int/__init__.py +++ b/src/h3/api/basic_int/__init__.py @@ -474,8 +474,6 @@ def uncompact_cells(cells, res): ----- 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) @@ -1367,3 +1365,28 @@ def is_valid_vertex(v): return _cy.is_valid_vertex(v) except (ValueError, TypeError, OverflowError): return False + + +if _out_scalar is _in_scalar: # pragma: no cover + # When _out_scalar is identity (basic_int, numpy_int, memview_int), + # bind scalar functions directly to their _cy counterparts to eliminate + # Python call frame and identity wrapper overhead (Issue #501). + # + # Coverage is only measured on the basic_str copy of this file, where + # this branch is never taken; it is exercised by the int API tests. + for _name in ( + 'latlng_to_cell', + 'cell_to_parent', + 'cell_to_center_child', + 'cells_to_directed_edge', + 'get_directed_edge_origin', + 'get_directed_edge_destination', + 'directed_edge_to_cells', + 'local_ij_to_cell', + 'cell_to_vertex', + ): + _fn = globals()[_name] + _cy_fn = getattr(_cy, _name) + _cy_fn.__doc__ = _fn.__doc__ + globals()[_name] = _cy_fn + del _name, _fn, _cy_fn diff --git a/tests/test_lib/test_apis/test_basic_int.py b/tests/test_lib/test_apis/test_basic_int.py index a567b3d..3f3b14c 100644 --- a/tests/test_lib/test_apis/test_basic_int.py +++ b/tests/test_lib/test_apis/test_basic_int.py @@ -32,3 +32,25 @@ def test_compact_cells(): cells = h3.cell_to_children(h) assert h3.compact_cells(cells) == [h] + + +def test_identity_scalar_bindings(): + """ + Ensure scalar functions in int APIs are bound directly to _cy implementations + to eliminate wrapper and identity call overhead (Issue #501). + """ + from h3 import _cy + + assert h3.latlng_to_cell is _cy.latlng_to_cell + assert h3.cell_to_parent is _cy.cell_to_parent + assert h3.cell_to_center_child is _cy.cell_to_center_child + assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge + assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin + assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination + assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells + assert h3.local_ij_to_cell is _cy.local_ij_to_cell + assert h3.cell_to_vertex is _cy.cell_to_vertex + + # Ensure docstrings and signatures are intact + assert h3.latlng_to_cell.__doc__ is not None + assert 'latlng_to_cell' in h3.latlng_to_cell.__name__ diff --git a/tests/test_lib/test_apis/test_memview_int.py b/tests/test_lib/test_apis/test_memview_int.py index 0523794..f608f54 100644 --- a/tests/test_lib/test_apis/test_memview_int.py +++ b/tests/test_lib/test_apis/test_memview_int.py @@ -23,3 +23,17 @@ def test_line(): ] assert list(out) == expected + + +def test_identity_scalar_bindings(): + from h3 import _cy + + assert h3.latlng_to_cell is _cy.latlng_to_cell + assert h3.cell_to_parent is _cy.cell_to_parent + assert h3.cell_to_center_child is _cy.cell_to_center_child + assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge + assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin + assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination + assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells + assert h3.local_ij_to_cell is _cy.local_ij_to_cell + assert h3.cell_to_vertex is _cy.cell_to_vertex diff --git a/tests/test_lib/test_apis/test_numpy_int.py b/tests/test_lib/test_apis/test_numpy_int.py index c341b55..6bcd0b6 100644 --- a/tests/test_lib/test_apis/test_numpy_int.py +++ b/tests/test_lib/test_apis/test_numpy_int.py @@ -50,3 +50,17 @@ def test_numpy_str(): got = [h3.str_to_int(c) for c in cells] assert expected == got + + +def test_identity_scalar_bindings(): + from h3 import _cy + + assert h3.latlng_to_cell is _cy.latlng_to_cell + assert h3.cell_to_parent is _cy.cell_to_parent + assert h3.cell_to_center_child is _cy.cell_to_center_child + assert h3.cells_to_directed_edge is _cy.cells_to_directed_edge + assert h3.get_directed_edge_origin is _cy.get_directed_edge_origin + assert h3.get_directed_edge_destination is _cy.get_directed_edge_destination + assert h3.directed_edge_to_cells is _cy.directed_edge_to_cells + assert h3.local_ij_to_cell is _cy.local_ij_to_cell + assert h3.cell_to_vertex is _cy.cell_to_vertex diff --git a/tests/test_lib/test_cells_and_edges.py b/tests/test_lib/test_cells_and_edges.py index d817180..65d9d13 100644 --- a/tests/test_lib/test_cells_and_edges.py +++ b/tests/test_lib/test_cells_and_edges.py @@ -131,9 +131,7 @@ def test_parent_err(): except Exception as e: msg = str(e) - # todo: revist this weird formatting stuff - expected = 'Invalid parent resolution -1 for cell {}.' - expected = expected.format(hex(h3.str_to_int(h))) + expected = f'Invalid parent resolution -1 for cell 0x{h}.' assert msg == expected @@ -763,3 +761,13 @@ def test_construct_cell_inverses_int_api(): def test_center_child_with_deconstruct(): for h in h3.get_res0_cells(): h3.construct_cell(*h3.deconstruct_cell(h), 0) == h3.cell_to_center_child(h) + + +def test_uncompact_cells_invalid_resolution(): + # Create a valid cell at resolution 5 + h_res5 = h3.latlng_to_cell(0, 0, 5) + + # Attempting to uncompact to a coarser resolution (4) + # should raise an H3ResMismatchError + with pytest.raises(H3ResMismatchError): + h3.uncompact_cells({h_res5}, 4) diff --git a/tests/test_lib/test_geojson_containers.py b/tests/test_lib/test_geojson_containers.py new file mode 100644 index 0000000..a890c27 --- /dev/null +++ b/tests/test_lib/test_geojson_containers.py @@ -0,0 +1,62 @@ +import pytest +from h3._h3shape import LatLngPoly, h3shape_to_geo, LatLngMultiPoly + + +def test_h3shape_to_geo_containers(): + # Create a basic dummy polygon for testing + poly = LatLngPoly( + [(37.68, -122.54), (37.68, -122.34), (37.82, -122.34), (37.82, -122.54)] + ) + + # Test 'auto' (Default behavior should return a Polygon) + auto_geo = h3shape_to_geo(poly, container='auto') + assert auto_geo['type'] == 'Polygon' + + # Test MultiPolygon wrapper + mp_geo = h3shape_to_geo(poly, container='MultiPolygon') + assert mp_geo['type'] == 'MultiPolygon' + assert len(mp_geo['coordinates']) == 1 + + # Test Feature wrapper + feat_geo = h3shape_to_geo(poly, container='Feature') + assert feat_geo['type'] == 'Feature' + assert feat_geo['geometry']['type'] == 'Polygon' + + # Test FeatureCollection wrapper + fc_geo = h3shape_to_geo(poly, container='FeatureCollection') + assert fc_geo['type'] == 'FeatureCollection' + assert len(fc_geo['features']) == 1 + assert fc_geo['features'][0]['type'] == 'Feature' + assert fc_geo['features'][0]['geometry']['type'] == 'Polygon' + + # Test GeometryCollection wrapper + gc_geo = h3shape_to_geo(poly, container='GeometryCollection') + assert gc_geo['type'] == 'GeometryCollection' + assert len(gc_geo['geometries']) == 1 + assert gc_geo['geometries'][0]['type'] == 'Polygon' + + +def test_h3shape_to_geo_invalid_containers(): + # 1. Test an unknown container string + poly = LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) + with pytest.raises(ValueError, match='invalid or insufficient'): + h3shape_to_geo(poly, container='InvalidString') + + # 2. Test an insufficient container (MultiPolygon data into a Polygon container) + mpoly = LatLngMultiPoly( + LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) + ) + with pytest.raises(ValueError, match='invalid or insufficient'): + h3shape_to_geo(mpoly, container='Polygon') + + +def test_h3shape_to_geo_exact_match(): + # Test that requesting a MultiPolygon for MultiPolygon data succeeds + mpoly = LatLngMultiPoly( + LatLngPoly([(37.68, -122.54), (37.68, -122.34), (37.82, -122.34)]) + ) + + mp_geo = h3shape_to_geo(mpoly, container='MultiPolygon') + + assert mp_geo['type'] == 'MultiPolygon' + assert len(mp_geo['coordinates']) == 1 diff --git a/tests/test_lib/test_length_area.py b/tests/test_lib/test_length_area.py index 1003f56..ca38257 100644 --- a/tests/test_lib/test_length_area.py +++ b/tests/test_lib/test_length_area.py @@ -86,6 +86,30 @@ def test_areas_at_00(): assert u.approx2(out, areas_rads2) +def test_average_hexagon_area_rads(): + # the ratio between km^2 and rads^2 should match the one used by cell_area + h = '89754e64993ffff' + ratio = h3.cell_area(h, unit='km^2') / h3.cell_area(h, unit='rads^2') + + for res in range(16): + km2 = h3.average_hexagon_area(res, unit='km^2') + rads2 = h3.average_hexagon_area(res, unit='rads^2') + + assert km2 / rads2 == pytest.approx(ratio) + + +def test_average_hexagon_edge_length_rads(): + # the ratio between km and rads should match the one used by edge_length + e = '139754e64993ffff' + ratio = h3.edge_length(e, unit='km') / h3.edge_length(e, unit='rads') + + for res in range(16): + km = h3.average_hexagon_edge_length(res, unit='km') + rads = h3.average_hexagon_edge_length(res, unit='rads') + + assert km / rads == pytest.approx(ratio) + + def test_bad_units(): h = '89754e64993ffff' e = '139754e64993ffff'