gedih3.vecutils#

Vector Polygon Spatial Join at GEDI Shot Locations

Spatially join polygon attributes (e.g., ecoregion names, administrative boundaries) to GEDI shot locations based on spatial containment.

Supports shapefiles, GeoPackages, GeoJSON, and GeoParquet. Works with both H3 databases and simplified datasets from gh3_extract.

Attributes#

logger

Functions#

`resolve_vector_source`(vector_path[, file_format])	Resolve vector input to a single file path.
`get_vector_info`(vector_path)	Read vector file metadata without loading all features.
`load_vector`(vector_path[, columns, to_crs])	Load polygon GeoDataFrame, filter columns, reproject to WGS84.
`join_polygons_to_points`(df, vector_path[, ...])	Spatially join polygon attributes to GEDI shot locations within a partition.

Module Contents#

gedih3.vecutils.logger#

gedih3.vecutils.resolve_vector_source(vector_path, file_format='*')[source]#

Resolve vector input to a single file path.

Single file -> return as-is
Directory -> glob for vector files

Parameters:

vector_pathstr: Path to vector file or directory of vector files
file_formatstr: File extension to glob when vector_path is a directory. Use ‘*’ to search all supported formats.

Returns:

tuple: (file_path, file_count)

Raises:

GediSpatialJoinError: If no valid vector file found

gedih3.vecutils.get_vector_info(vector_path)[source]#

Read vector file metadata without loading all features.

Parameters:

vector_pathstr: Path to vector file

Returns:

dict: Keys: crs, bounds_wgs84, columns, feature_count, geometry_type

gedih3.vecutils.load_vector(vector_path, columns=None, to_crs=4326)[source]#

Load polygon GeoDataFrame, filter columns, reproject to WGS84.

Parameters:

vector_pathstr: Path to vector file
columnslist of str, optional: Polygon attribute columns to include. If None, all columns.
to_crsint or str: Target CRS (default: EPSG:4326 for WGS84)

Returns:

GeoDataFrame: Polygon geometries in target CRS with spatial index

Raises:

GediSpatialJoinError: If file contains non-polygon geometries

gedih3.vecutils.join_polygons_to_points(df, vector_path, join_columns=None, predicate='within', how='left', prefix=None, partition_col=None, geo=False)[source]#

Spatially join polygon attributes to GEDI shot locations within a partition.

Designed to be called via Dask map_partitions. For each partition: 1. Load polygons via worker-level cache 2. Build GeoDataFrame from partition points 3. Perform spatial join (gpd.sjoin) 4. Cleanup: drop index_right, apply column prefix, handle conflicts

Parameters:

dfDataFrame or GeoDataFrame: Input partition with geometry column (Point geometries)
vector_pathstr: Path to polygon vector file
join_columnslist of str, optional: Polygon attribute columns to include. If None, all polygon columns.
predicatestr: Spatial join predicate: ‘within’ or ‘intersects’
howstr: Join type: ‘left’ (keep all shots) or ‘inner’ (matched only)
prefixstr, optional: Prefix to add to polygon column names (avoids conflicts)
partition_colstr, optional: Partition column name to preserve in output
geobool: Include geometry in output

Returns:

DataFrame or GeoDataFrame: Joined data with polygon attribute columns