gedih3.h3utils
==============

.. py:module:: gedih3.h3utils


Functions
---------

.. autoapisummary::

   gedih3.h3utils.get_all_h3_hexagons
   gedih3.h3utils.iter_all_h3_hexagons
   gedih3.h3utils.fix_h3_geometry
   gedih3.h3utils.h3_expand_ring
   gedih3.h3utils.intersect_h3_geometries
   gedih3.h3utils.h3_index_df
   gedih3.h3utils.h3_parts_to_gdf


Module Contents
---------------

.. py:function:: get_all_h3_hexagons(resolution: int)

   
   Get all H3 hexagons at a given resolution level
















   ..
       !! processed by numpydoc !!

.. py:function:: iter_all_h3_hexagons(resolution: int)

   
   Memory-efficient iterator for all H3 hexagons at resolution
















   ..
       !! processed by numpydoc !!

.. py:function:: fix_h3_geometry(hex: str)

   
   Using the antimeridian package for robust handling.
















   ..
       !! processed by numpydoc !!

.. py:function:: 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:

       **cells** : iterable of str
           H3 cell IDs (all at the same resolution).

       **ring** : int, default 1
           ``grid_disk`` radius.

       **valid** : set, 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.











   ..
       !! processed by numpydoc !!

.. py:function:: 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:

       **spatial** : str | 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).

       **res** : int
           H3 resolution of the candidate cells (ignored when ``h3_ids`` given).

       **h3_ids** : list, 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_ring** : int, default 1
           ``grid_disk`` radius for the overhang-safety expansion; 0 disables.














   ..
       !! processed by numpydoc !!

.. py:function:: h3_index_df(df, res=12, part=3, lat_col='lat_lowestmode', lon_col='lon_lowestmode')

.. py:function:: h3_parts_to_gdf(h3_ids, crs=4326)

   
   Convert H3 partition IDs to a GeoDataFrame with polygon geometries.


   :Parameters:

       **h3_ids** : list
           List of H3 cell IDs (strings)

       **crs** : int or str
           Output CRS (default: 4326)



   :Returns:

       GeoDataFrame
           GeoDataFrame indexed by H3 ID with polygon geometries











   ..
       !! processed by numpydoc !!