gedih3.imgutils#
Raster Image Sampling at GEDI Shot Locations
Sample raster pixel values at true GEDI shot coordinates (Points), with optional moving-window statistics (sum, mean, median, mode).
Supports single raster files, VRT mosaics, and tile directories (auto-mosaicked via VRT). Works with both H3 databases and simplified datasets from gh3_extract.
Attributes#
Functions#
|
Resolve image input to a single raster source. |
|
Read raster metadata (CRS, bounds, resolution, bands, nodata). |
|
Parse legacy 3-digit format for window operations. |
|
Sample raster values at GEDI shot locations within a single partition. |
|
Sample raster values at GEDI shot locations. |
Module Contents#
- gedih3.imgutils.logger#
- gedih3.imgutils.resolve_raster_source(image_path, file_format='tif', odir=None)[source]#
Resolve image input to a single raster source.
Single file (.tif, .vrt, etc.) -> return as-is
Directory of tiles -> build VRT mosaic, return VRT path
- Parameters:
- image_pathstr
Path to raster file, VRT file, or directory of tiles
- file_formatstr
File extension to glob when image_path is a directory
- odirstr, optional
Output directory for saving VRT beside output. If provided, VRT is saved as
{odir}/{tiles_dirname}.vrtinstead of inside the tiles directory.
- Returns:
- tuple
(raster_path, is_temp_vrt, tile_count)
- Raises:
- GediImageSamplingError
If no valid raster found
- gedih3.imgutils.get_raster_info(raster_path)[source]#
Read raster metadata (CRS, bounds, resolution, bands, nodata).
Also computes bounds in WGS84 (EPSG:4326) for spatial filtering of GEDI data.
- Parameters:
- raster_pathstr
Path to raster file or VRT
- Returns:
- dict
- Keys: crs, bounds, bounds_wgs84, resolution, shape, band_count,
band_names, nodata
- gedih3.imgutils.parse_window_specs(specs)[source]#
Parse legacy 3-digit format for window operations.
Format: each spec is a 3-character string ‘BZO’ where: - B = band number (0-indexed) - Z = window size (1-9, must be odd) - O = operation ID (0=sum, 1=mean, 2=median, 3=mode, 4=std, 5=min, 6=max, 7=count, 8=range)
- Parameters:
- specslist of str
Window spec strings, e.g. [‘033’, ‘151’]
- Returns:
- list of dict
Each dict has: band (int), size (int), op (str), name (str)
- Raises:
- GediImageSamplingError
If any spec is invalid
- gedih3.imgutils.sample_raster_at_points(df, raster_path, band_names=None, window_ops=None, fillna=None, dropna=False, geo=False, partition_col=None, band_indices=None, all_band_names=None, pixel_distance=False)[source]#
Sample raster values at GEDI shot locations within a single partition.
Designed to be called via Dask map_partitions. For each partition: 1. Extract true point coordinates from geometry column 2. Compute partition bbox with buffer for window operations 3. Open raster, clip to bbox (reads only relevant VRT tiles) 4. Reproject points to raster CRS if needed 5. Sample nearest pixel for each shot 6. Compute relative_pixel_distance (if pixel_distance=True) 7. Apply window operations if specified
- Parameters:
- dfDataFrame or GeoDataFrame
Input partition with geometry column (Point geometries)
- raster_pathstr
Path to raster file or VRT
- band_nameslist of str, optional
Names for the output band columns. When
band_indicesis provided, should have length == len(band_indices).- window_opslist of dict, optional
Parsed window operation specs from parse_window_specs(). Band indices in window_ops refer to original raster bands (0-indexed).
- fillnafloat, optional
Value to fill raster NaN/NoData before sampling
- dropnabool
Drop rows where all band columns are NaN
- geobool
Include geometry in output
- partition_colstr, optional
Partition column name to preserve in output
- band_indiceslist of int, optional
0-based indices of raster bands to sample. If None, all bands are sampled.
- all_band_nameslist of str, optional
Full list of raster band names (all bands). Used for resolving window operation column names when
band_indicesselects a subset. If None, defaults toband_names.- pixel_distancebool
If True, include
relative_pixel_distancecolumn in output. Defaults to False.
- Returns:
- DataFrame or GeoDataFrame
Sampled data with band columns, optional relative_pixel_distance, and optional window operation columns
- gedih3.imgutils.from_image(image_path, data_source=None, region=None, query=None, band_names=None, band_indices=None, window_ops=None, fillna=None, dropna=False, geo=False, file_format='tif', pixel_distance=False)[source]#
Sample raster values at GEDI shot locations.
Supports two input modes with different ROI logic:
- Mode 1 - H3 database (via data_source pointing to an H3 database):
ROI = image boundaries (intersected with user region if provided). Only H3 partitions overlapping the image are loaded.
- Mode 2 - Simplified dataset (via data_source pointing to a simplified dataset):
ROI = entire dataset (all tiles loaded regardless of image coverage). Shots outside image bounds get NaN values.
In both cases, uses TRUE shot geometry for coordinate extraction.
- Parameters:
- image_pathstr
Path to raster file, VRT, or tile directory
- data_sourcestr, optional
Path to H3 database or simplified dataset directory
- regionGeoDataFrame or bbox, optional
Additional spatial filter
- querystr, optional
Pandas query string for filtering shots
- band_nameslist of str, optional
Custom band names for output columns. When
band_indicesis provided, should have length == len(band_indices).- band_indiceslist of int, optional
0-based indices of raster bands to sample. If None, all bands.
- window_opslist of dict, optional
Parsed window specs from parse_window_specs()
- fillnafloat, optional
Value to fill raster NaN/NoData
- dropnabool
Drop rows where all band columns are NaN
- geobool
Include geometry in output
- file_formatstr
Tile file extension for directory input
- pixel_distancebool
If True, include
relative_pixel_distancecolumn in output. Defaults to False.
- Returns:
- dask.dataframe.DataFrame
Sampled data as Dask DataFrame
- Raises:
- GediImageSamplingError
If inputs are invalid or sampling fails