Quick Start#

This guide covers the core workflow in five steps: download → build → extract → aggregate → rasterize.

gh3_download NASA DAAC gh3_build H3 Database gh3_extract Filter & Query gh3_aggregate Multi-scale gh3_rasterize GeoTIFF

Tip: Run any tool with --help for the full list of options.

gh3_build --help

Step 1: Download GEDI Data#

gh3_download -r "-51,0,-50,1" -l2a minimal -l4a minimal

Downloads GEDI L2A and L4A granules covering the bounding box (W,S,E,N). Files are saved to ~/gedi_data/soc/ by default.

Use default instead of minimal for a broader variable set, or pass explicit variable names.

Step 2: Build the H3 Database#

gh3_build -r "-51,0,-50,1" -l2a minimal -l4a minimal

Converts downloaded HDF5 files into an H3-indexed Parquet database at ~/gedi_data/h3/. This is a one-time step; the database can be queried and re-used without rebuilding.

Tip

The database is incremental. If you later expand your region, time range, or variable selection, re-run gh3_build with the updated parameters — existing data is preserved and only new data is processed.

The database you build here determines which variables, region, and time period are available to all downstream tools. For a full guide to variable selection, subsetting strategies, source modes, and performance tuning, see Building a Database.

Step 3: Browse Variables#

gh3_read_schema              # list all available variables
gh3_read_schema --grep agbd  # filter with a keyword

Step 4: Extract a Dataset#

gh3_extract -y -l agbd_l4a rh_098_l2a -o extracted/

The -y flag applies pre-configured quality filtering. Output is a set of flat Parquet files in extracted/, readable with pandas, R, QGIS, or DuckDB.

To filter spatially or temporally:

gh3_extract -y -r region.shp -t0 2020-01-01 -t1 2022-12-31 \
            -l agbd_l4a rh_098_l2a -o extracted/

Step 5: Aggregate#

gh3_aggregate -d extracted/ -h3 7 -a mean -o aggregated/

Aggregates GEDI shots to H3 level 7 hexagons (~5 km²). Use gh3_list_resolutions to see all available levels.

Shortcut: All-in-One#

gh3_aggregate can read the H3 database directly (no prior gh3_extract needed) and produce rasters in the same call with -R, collapsing steps 3–5 into one command:

gh3_aggregate -y -l agbd_l4a rh_098_l2a -h3 7 -a mean -R -o output/

This writes GeoTIFFs to output/ in a single pass. Use this when you don’t need to export intermediate datasets.

Note

Aggregating from H3 hexagons to raster files will resample hexagon polygons to pixels using nearest neighbor interpolation. For exact pixel matches consider using the EGI indexing system.

Step 6: Export as GeoTIFF#

gh3_rasterize -d aggregated/ -o rasters/ --compress LZW

Produces one GeoTIFF per variable per partition, tiled for efficient access.

Python Equivalent#

The same workflow without saving intermediate files:

import gedih3.gh3driver as gh3
from gedih3 import raster

# Load from the H3 database
ddf = gh3.gh3_load(
    source='~/gedi_data/h3/',
    columns=['agbd_l4a', 'rh_098_l2a'],
    query='quality_flag_l2a == 1 and agbd_l4a > 0',
)

# Aggregate to H3 level 6
agg = gh3.gh3_aggregate(ddf, target_res=6, agg=['mean', 'std', 'count']).compute()

# Export to GeoTIFF
xras = raster.h3_to_raster(agg)
raster.export_raster(xras, 'agbd_mean.tif', compress='LZW')

For advanced Python API usage (custom aggregation functions, ancillary data integration, and more), see Python API.

Next Steps#