gedih3.h3utils

Functions

get_all_h3_hexagons(resolution)	Get all H3 hexagons at a given resolution level
iter_all_h3_hexagons(resolution)	Memory-efficient iterator for all H3 hexagons at resolution
fix_h3_geometry(hex)	Using the antimeridian package for robust handling.
h3_expand_ring(cells[, ring, valid])	Expand a set of H3 cells by their grid_disk neighbors.
intersect_h3_geometries(spatial[, res, h3_ids, ...])	Return H3 cells whose data footprint may intersect spatial.
h3_index_df(df[, res, part, lat_col, lon_col])
h3_parts_to_gdf(h3_ids[, crs])	Convert H3 partition IDs to a GeoDataFrame with polygon geometries.

Module Contents

gedih3.h3utils.get_all_h3_hexagons(resolution: int)

Get all H3 hexagons at a given resolution level

gedih3.h3utils.iter_all_h3_hexagons(resolution: int)

Memory-efficient iterator for all H3 hexagons at resolution

gedih3.h3utils.fix_h3_geometry(hex: str)

Using the antimeridian package for robust handling.

gedih3.h3utils.h3_expand_ring(cells, ring=1, valid=None)

Expand a set of H3 cells by their grid_disk neighbors.

The shared overhang-safety primitive: shots are stored under their hierarchy partition, which can overhang the partition’s polygon by ~0.18 x edge length (see _H3_OVERHANG_FRACTION in utils.py) — far less than one cell width, so any cell set selected by exact polygon intersection only needs its ring-1 neighbors to cover all storage partitions. Used by intersect_h3_geometries, egi_h3_intersection and geoseries_to_filter.

Parameters:

cellsiterable of str

H3 cell IDs (all at the same resolution).

ringint, default 1

grid_disk radius.

validset, optional

When given, only neighbors in this set are added (e.g. the partitions that actually exist in a database).

Returns:

list[str]

Sorted union of cells and their (filtered) neighbors.

gedih3.h3utils.intersect_h3_geometries(spatial, res=3, h3_ids=None, expand_ring=1)

Return H3 cells whose data footprint may intersect spatial.

H3 children are not geometrically contained in their parents: a shot stored under partition cell_to_parent(latlng_to_cell(lon, lat, index_res), part_res) can sit up to ~0.14-0.16 x the parent’s edge length outside the parent’s own polygon (~8-10 km at partition level 3; see _H3_OVERHANG_FRACTION in utils.py). A ROI touching that overhang band intersects the polygon the shots physically fall in, not the partition they are stored in — so an exact polygon intersection silently misses boundary shots (observed in production on the EGI path: ~5% of one L3 partition’s shots; see egi_h3_intersection).

expand_ring=1 (default) closes this by adding the grid_disk ring-1 neighbors of every polygon-intersecting cell, restricted to the candidate set (h3_ids when given). This is guaranteed sufficient: the overhang (~0.18 x edge) is far smaller than one cell width, so the true storage partition of any shot inside a polygon is always that polygon’s cell or an immediate neighbor. Callers that need the exact polygon intersection can pass expand_ring=0.

Parameters:

spatialstr | list | GeoSeries | GeoDataFrame | shapely geometry

ROI as a vector-file path / “W,S,E,N” string, [W,S,E,N] bbox list, geopandas object, or shapely geometry (EPSG:4326).

resint

H3 resolution of the candidate cells (ignored when h3_ids given).

h3_idslist, optional

Candidate cell set (e.g. a database’s partition ids). When given, both the intersection and the ring expansion are restricted to it.

expand_ringint, default 1

grid_disk radius for the overhang-safety expansion; 0 disables.

gedih3.h3utils.h3_index_df(df, res=12, part=3, lat_col='lat_lowestmode', lon_col='lon_lowestmode')

gedih3.h3utils.h3_parts_to_gdf(h3_ids, crs=4326)

Convert H3 partition IDs to a GeoDataFrame with polygon geometries.

Parameters:

h3_idslist

List of H3 cell IDs (strings)

crsint or str

Output CRS (default: 4326)

Returns:

GeoDataFrame

GeoDataFrame indexed by H3 ID with polygon geometries