gedih3.raster.h3_raster#

H3 Hexagon Rasterization Module

This module provides functions for converting H3-indexed GeoDataFrames to raster format. Unlike EGI (which has native square pixels), H3 hexagons require interpolation/resampling for raster output.

The workflow: 1. Determine appropriate resolution from H3 level 2. Find optimal UTM zone for the data extent 3. Rasterize using geocube with bilinear interpolation 4. Reproject to target CRS (default: EPSG:4326)

Functions#

`get_h3_resolution_meters`(→ float)	Get the approximate pixel resolution in meters for an H3 level.
`get_optimal_utm`(→ int)	Find the optimal UTM zone EPSG code for a GeoDataFrame's extent.
`h3_to_raster`(→ xarray.Dataset)	Convert H3-indexed GeoDataFrame to raster (xarray Dataset).
`rasterize_h3_partition`(→ pandas.Series)	Rasterize a single H3 partition (for use with Dask map_partitions).
`compute_raster_mosaic`(→ xarray.Dataset)	Merge multiple raster partitions into a single mosaic.
`get_h3_raster_resolution`(→ Tuple[float, float])	Determine the appropriate raster resolution for H3 data.

Module Contents#

gedih3.raster.h3_raster.get_h3_resolution_meters(h3_level: int) → float[source]#

Get the approximate pixel resolution in meters for an H3 level.

Uses the average hexagon edge length * 2 (diameter) as the pixel size.

Parameters:

h3_levelint: H3 resolution level (0-15)

Returns:

float: Approximate pixel size in meters

gedih3.raster.h3_raster.get_optimal_utm(gdf: geopandas.GeoDataFrame) → int[source]#

Find the optimal UTM zone EPSG code for a GeoDataFrame’s extent.

Parameters:

gdfGeoDataFrame: Input GeoDataFrame (any CRS)

Returns:

int: EPSG code for the optimal UTM zone

gedih3.raster.h3_raster.h3_to_raster(gdf: geopandas.GeoDataFrame, resolution: Tuple[float, float] | None = None, columns: List[str] | None = None, fill_value: float = np.nan, output_crs: str = H3_RASTER_CRS, partition_level: int | None = None) → xarray.Dataset[source]#

Convert H3-indexed GeoDataFrame to raster (xarray Dataset).

This function rasterizes H3 hexagon data using geocube, with automatic resolution determination based on the H3 level. The data is first reprojected to UTM for accurate rasterization, then to the output CRS.

Parameters:

gdfGeoDataFrame: H3-indexed GeoDataFrame with polygon geometries
resolutiontuple of float, optional: Output resolution as (y_res, x_res) in target CRS units. If None, automatically determined from H3 level.
columnslist of str, optional: Columns to rasterize. If None, all numeric columns are used. Internal columns (h3 indices, egi indices) are automatically excluded.
fill_valuefloat: Value for pixels with no data (default: NaN)
output_crsstr: Output coordinate reference system (default: EPSG:4326)
partition_levelint, optional: H3 partition level for metadata. If None, auto-detected from data.

Returns:

xr.Dataset: Raster dataset with one data variable per column

Examples

>>> # Rasterize H3 aggregated data
>>> raster = h3_to_raster(h3_gdf, columns=['agbd_mean'])
>>> raster.rio.to_raster("output.tif")

gedih3.raster.h3_raster.rasterize_h3_partition(gdf: geopandas.GeoDataFrame, columns: List[str] | None = None, output_crs: str = H3_RASTER_CRS, include_partition_id: bool = True, partition_level: int | None = None) → pandas.Series[source]#

Rasterize a single H3 partition (for use with Dask map_partitions).

Splits data by a coarser H3 parent level to create separate raster tiles, each named by the parent cell ID. This ensures manageable tile sizes and proper file naming for tiled output.

Parameters:

gdfGeoDataFrame: H3-indexed GeoDataFrame partition
columnslist of str, optional: Columns to rasterize
output_crsstr: Output coordinate reference system
include_partition_idbool: If True, include H3 partition ID in raster attributes
partition_levelint, optional: H3 partition level for grouping tiles. If None, auto-detected from data columns or computed as 3 levels coarser than data level.

Returns:

pd.Series: Series containing xarray Dataset(s), one per spatial tile

Examples

>>> # With Dask
>>> rasters = ddf.map_partitions(rasterize_h3_partition, meta=pd.Series(dtype=object))

gedih3.raster.h3_raster.compute_raster_mosaic(raster_series: pandas.Series, show_progress: bool = False) → xarray.Dataset[source]#

Merge multiple raster partitions into a single mosaic.

Parameters:

raster_seriespd.Series: Series of xarray Datasets from rasterize_h3_partition
show_progressbool: If True, show progress during computation

Returns:

xr.Dataset: Merged raster mosaic

gedih3.raster.h3_raster.get_h3_raster_resolution(gdf: geopandas.GeoDataFrame, npartitions: int = 1) → Tuple[float, float][source]#

Determine the appropriate raster resolution for H3 data.

Parameters:

gdfGeoDataFrame or dask GeoDataFrame: H3-indexed data
npartitionsint: Number of partitions to sample (for dask)

Returns:

tuple: (y_resolution, x_resolution) in degrees (EPSG:4326)