gedih3.egi.raster#

EGI (EASE Grid Index) Raster Module

This module provides rasterization functions for converting EGI-indexed GeoDataFrames to raster (xarray/GeoTIFF) format. The native alignment of EGI with EASE-Grid 2.0 allows for direct rasterization without resampling.

Attributes#

logger

Functions#

`geodf_to_raster`(→ xarray.Dataset)	Convert EGI-indexed GeoDataFrame to raster (xarray Dataset).
`rasterize_partition`(→ pandas.Series)	Rasterize a single EGI partition (for use with Dask map_partitions).
`export_raster`(→ str)	Export xarray Dataset to GeoTIFF file.
`merge_raster_partitions`(→ xarray.Dataset)	Merge multiple raster partitions into a single raster.
`get_raster_profile`(→ dict)	Generate a rasterio profile for EGI raster output.

Module Contents#

gedih3.egi.raster.logger#

gedih3.egi.raster.geodf_to_raster(geodf: geopandas.GeoDataFrame, columns: List[str] | None = None, fill_value: float = np.nan, outer_tile: int | None = None) → xarray.Dataset[source]#

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

This function creates a raster aligned to the EASE-Grid 2.0 projection, with each EGI pixel mapped directly to a corresponding raster cell using direct index assignment (no interpolation or extrapolation).

The raster covers exactly ONE level-12 outer tile. When that tile is given explicitly (outer_tile), stray pixels from any other tile are skipped with a WARNING — their inner indices are positions within their own tile and would land at wrong map coordinates in this tile’s grid (this protects legacy datasets extracted before the to_hash boundary-overflow carry and the egi_load spillover filter, which can still hold cross-tile rows). When no tile is given, the input must resolve to a single tile; a genuine multi-tile input raises GediRasterizationError instead of guessing which tile to keep — split by outer tile first (rasterize_partition) to keep every pixel.

Parameters:

geodfGeoDataFrame: EGI-indexed GeoDataFrame (index must be EGI hash values)
columnslist of str, optional: Columns to rasterize. If None, all numeric columns are used. Internal columns (egi indices, h3 indices) are automatically excluded.
fill_valuefloat: Value for pixels with no data (default: NaN)
outer_tileint, optional: Level-12 EGI hash of the tile to rasterize. Callers that know their tile (partition writers, rasterize_partition) should always pass it. When None, the input must resolve to a single outer tile; a multi-tile input with no outer_tile hint raises GediRasterizationError rather than guessing which tile to keep — split by outer tile first (rasterize_partition) so no pixels are dropped.

Returns:

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

Raises:

GediRasterizationError: If the input spans more than one outer tile and no outer_tile is given (the function rasterizes exactly one tile and will not silently drop the rest).

Notes

This implementation uses direct index-based pixel assignment: 1. Decode each EGI hash to get pixel indices within the outer tile 2. Create a raster array with exact tile dimensions 3. Assign values directly to pixel locations

This guarantees one polygon = one pixel with no extrapolation.

Examples

>>> # Rasterize aggregated GEDI data
>>> raster = geodf_to_raster(agg_gdf, columns=['agbd_mean', 'rh_098_mean'])
>>> raster.rio.to_raster("output.tif")

gedih3.egi.raster.rasterize_partition(gdf: geopandas.GeoDataFrame, columns: List[str] | None = None, include_egi_id: bool = True) → pandas.Series[source]#

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

This function splits the partition by outer tile and rasterizes each tile separately to ensure proper alignment and avoid mixing data from different tiles.

Parameters:

gdfGeoDataFrame: EGI-indexed GeoDataFrame partition
columnslist of str, optional: Columns to rasterize
include_egi_idbool: If True, include outer tile ID in raster attributes

Returns:

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

Examples

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

gedih3.egi.raster.export_raster(xras: xarray.Dataset, output_path: str, compress: str = 'LZW', tiled: bool = True, blocksize: int = 256, bigtiff: bool = True) → str[source]#

Export xarray Dataset to GeoTIFF file.

Parameters:

xrasxr.Dataset: Raster dataset to export
output_pathstr: Output file path
compressstr: Compression method (‘LZW’, ‘ZSTD’, ‘DEFLATE’, None)
tiledbool: Use tiled output format
blocksizeint: Tile block size in pixels
bigtiffbool: Use BigTIFF format for large files

Returns:

str: Output file path

gedih3.egi.raster.merge_raster_partitions(raster_series: pandas.Series, output_path: str | None = None) → xarray.Dataset[source]#

Merge multiple raster partitions into a single raster.

Parameters:

raster_seriespd.Series: Series of xarray Datasets from rasterize_partition
output_pathstr, optional: If provided, save merged raster to this path

Returns:

xr.Dataset: Merged raster dataset

gedih3.egi.raster.get_raster_profile(level: int, bounds: tuple, crs: str = EGI_CRS_STRING) → dict[source]#

Generate a rasterio profile for EGI raster output.

Parameters:

levelint: EGI resolution level
boundstuple: Raster bounds (left, bottom, right, top)
crsstr: Coordinate reference system

Returns:

dict: Rasterio profile dictionary