Turn billions of NASA GEDI footprints into analysis-ready datasets.#
NASA’s GEDI has measured forest height, biomass, and canopy structure across the planet — billions of individual laser measurements spanning every continent except Antarctica. But the raw data is stored in thousands of complex files organized by orbit, not by location. Getting from “I want a biomass map of my study area” to actually having one requires navigating deeply nested file formats, applying multi-criteria quality filters, and processing terabytes of data.
gedih3 handles all of that. It transforms raw GEDI data into a spatial database you can query by region, filter for quality with a single flag, aggregate to any scale, and export to GeoTIFF, GeoParquet, or any format your tools can read — from the command line or Python.
Install from PyPI or conda-forge:
pip install gedih3 # pip
uv pip install gedih3 # uv
conda install -c conda-forge gedih3 # conda / mamba (recommended for HPC)
See the installation guide for platform coverage, uv projects, and installing from source.
GEDI canopy height data aggregated to H3 hexagons at multiple scales, built and exported entirely with gedih3.
Working with GEDI data is harder than it should be#
GEDI is one of the most important datasets for understanding forests at a global scale — but working with it requires solving several hard engineering problems before you can do any science. These problems affect everyone from PhD students writing their first analysis to national forest inventory programs.
GEDI files are organized by time, not geography. Querying a study area means scanning thousands of orbits — most containing no relevant data.
Each product has hundreds of variables across 8 laser beams in nested HDF5 files. Knowing which ones matter requires domain expertise most users don’t have.
Each product ships with different quality flags. Skipping or misapplying them produces plausible but silently biased results.
The full archive is terabytes across thousands of files. Without spatial indexing and distributed processing, simple analyses take hours or fail entirely.
What gedih3 does about it#
gedih3 is a Python library and CLI toolchain that handles the entire pipeline from raw NASA data to analysis-ready output.
H3-indexed, region-partitioned database built from raw GEDI files. Queries touch only relevant tiles. Builds incrementally; interrupted builds resume automatically.
Use minimal or default presets designed by remote sensing scientists. Output is flat GeoParquet — readable by pandas, R, QGIS, DuckDB, or any modern tool.
A single --quality flag enforces all product-specific flags at once. Add custom pandas filters for beams, sensitivity thresholds, or time ranges with --query.
CLI shorthands (mean, p95) or any Python callable per hexagon. Partition-local grouping avoids data shuffling — scales linearly with data size.
Built on Dask. Streams HDF5 beam-by-beam within constrained RAM on a laptop; connects to an existing Dask scheduler on HPC with no code changes.
Download, build, extract, aggregate, fuse with external data, and export to GeoTIFF or GeoParquet — all from the CLI or Python API. All GEDI products (L1B–L4C).
Get started in 5 minutes#
Three commands — no configuration, no decisions. This downloads GEDI data for a 1-by-1 degree area in the Amazon, builds a spatial database, applies quality filtering, aggregates to ~5 km hexagons, and exports a GeoTIFF.
# 1. Install
git clone https://github.com/tiagodc/GEDI-H3.git && cd GEDI-H3
conda env create -f environment.yml && conda activate gedih3
# 2. Build a sample database (downloads data automatically)
gh3_build -r "-51,0,-50,1" -l2a minimal -l4a minimal -dl
# 3. Get a biomass map
gh3_aggregate -y -l agbd_l4a -h3 7 -a mean -R -o my_first_map/
Open my_first_map/*.tif in QGIS, R, or Python. Done.
Note
You need a free NASA Earthdata account. On first run, earthaccess will prompt you to log in. See Installation for details.
The pipeline has 5 discrete steps. Each can be configured independently — choose your region, products, variable sets, time range, aggregation level, and output format.
# Choose your region, products, variable sets, and time range
gh3_download -r study_area.shp -l2a default -l4a default -l2b minimal -t0 2020-01-01 -t1 2023-12-31
gh3_build -r study_area.shp -l2a default -l4a default -l2b minimal
gh3_extract -y -l agbd_l4a rh_098_l2a cover_l2b -r study_area.shp -o extracted/
gh3_aggregate -d extracted/ -h3 6 -a mean std count -o aggregated/
gh3_rasterize -d aggregated/ -o rasters/ --compress ZSTD
Or in Python, without saving intermediate files:
import gedih3.gh3driver as gh3
from gedih3 import raster
ddf = gh3.gh3_load(source='~/gedi_data/h3/', columns=['agbd_l4a', 'rh_098_l2a'])
agg = gh3.gh3_aggregate(ddf, target_res=6, agg=['mean', 'std', 'count']).compute()
raster.export_raster(raster.h3_to_raster(agg), 'agbd_mean.tif', compress='LZW')
Tip
gh3_aggregate can read the H3 database directly and rasterize in one pass with -R, collapsing extract + aggregate + rasterize into a single command:
gh3_aggregate -y -l agbd_l4a rh_098_l2a -h3 6 -a mean -R -o output/
See the Quick Start guide for a step-by-step walkthrough, or Building a Database for the full configuration reference.
Choosing the right tool#
gedih3 is not the only way to access GEDI data. Here is an honest look at when it is the best choice — and when another tool might serve you better.
gedih3 vs. Google Earth Engine#
Google Earth Engine hosts GEDI L2A, L2B, and L4A as pre-loaded datasets. It is the most widely used platform for GEDI analysis and an excellent choice for many workflows. Here is where the two tools diverge:
Fast spatial aggregation — index-based grouping, not geometry operations. Any Python callable; GEE is limited to fixed reducers.
Full variable access — 300+ variables per product vs. ~100 in GEE. Includes per-algorithm RH metrics and waveform parameters.
All GEDI products — L1B, L2A, L2B, L4A, and L4C. GEE lacks L1B waveforms and L4C (WSCI).
Your data, your hardware — offline, no compute quotas, reproducible. Scales from laptop to HPC.
SQL compatible — query with DuckDB, join with any dataset, larger-than-memory queries.
Incremental and resumable — add orbits, time periods, or variables without rebuilding. Interrupted builds resume automatically.
Storage efficient — S3 streaming transfers only selected variables. A fraction of the full archive footprint.
Zero setup — GEDI data pre-loaded. No download, no build, no local storage.
Quick exploration — faster to a first result for common variables.
Massive ecosystem — thousands of existing scripts and community examples.
No local infrastructure — runs in the cloud; no disk space or conda environments.
In short: if you need quick access to basic height and biomass variables for exploratory analysis, GEE is hard to beat. If you need the full variable set, fast index-based spatial aggregation with custom functions, L4C data, beam-level control, or reproducible offline pipelines — gedih3 is the right tool.
Other GEDI tools and how they compare
Capability |
gedih3 |
rGEDI |
gediDB |
SlideRule |
|---|---|---|---|---|
Incremental database |
Yes |
– |
Yes |
– |
On-the-fly variable subsetting |
Yes |
– |
Yes |
Yes |
Spatial indexing |
Yes |
– |
– |
– |
Spatial aggregation functions |
Yes |
– |
– |
– |
CLI pipeline |
Yes |
– |
– |
– |
GeoTIFF rasterization |
Yes |
– |
– |
– |
Offline / reproducible |
Yes |
Yes |
Yes |
– |
All GEDI products (L1B–L4C) |
Yes |
Partial |
Partial |
Partial |
rGEDI (R) — Supports L1B, L2A, L2B with waveform visualization and waveform simulation capability. Best for: R users doing waveform-level analysis on small areas.
gediDB (Python) — Uses TileDB as the storage backend instead of H3-partitioned Parquet. Supports L2A-B and L4A-C. Best for: users who prefer the TileDB ecosystem with strong Python programming skills.
SlideRule Earth (cloud service) — On-demand, cloud-based processing of GEDI and ICESat-2 data. Returns subsets with quality filtering but no spatial aggregation or rasterization. Best for: quick, on-demand subsets without local infrastructure.
Manual workflow (earthaccess + h5py + geopandas) — Always an option, but spatial aggregation alone typically requires writing point-in-polygon joins or manual grid binning. gedih3 automates the ~500 lines of boilerplate this requires and replaces geometry operations with instant index-based grouping.
Explore the documentation#
Install gedih3, set up NASA credentials, and run your first pipeline.
Best for: new users
Learn about GEDI data, H3 hexagonal indexing, EGI square-pixel indexing, and variable presets.
Best for: users who want to understand what happens under the hood
Complete guide to building databases, CLI reference, Python API, and data format specifications.
Best for: users ready to run their own analyses
Auto-generated documentation from source code: every function, class, and parameter.
Best for: developers and advanced Python users