Ivert Documentation#

ICESat-2 Validation of Elevations Reporting Tool

IVERT validates Digital Elevation Models (DEMs) by comparing their elevations against ICESat-2 satellite photon data. It supports topographic, bathymetric, and mixed coastal DEMs, runs fully offline on any machine, and handles vertical datum conversions automatically.

Capabilities#

  • Validate topographic, bathymetric, and mixed coastal DEMs against ICESat-2 photons — a single DEM, or a whole directory/glob of DEMs with combined collection-level summaries.

  • Classifies photons by surface type — ground, canopy, land ice, buildings, seafloor, and water surfaces — by combining multiple ICESat-2 products (ATL03, ATL06, ATL08, ATL12, ATL13, ATL24) with a Bing-derived building-footprint mask to flag built structures.

  • Coastline/water filtering to minimize false-positive “ground” photons appearing offshore over water and unreasonably-shallow “bathy floor” photons with large errors over deep water.

  • Automatic vertical datum conversion (NAVD88, EGM2008, MLLW, ellipsoid, and many more, by EPSG code or short name) — no manual reprojection needed.

  • Configurable photon filtering at both download and validation: signal confidence, bathymetry confidence, photon class selection, and outlier rejection.

  • Statistical outputs: mean bias, RMSE, standard deviation, a full percentile breakdown of per-cell errors, and optional per-cell photon coverage.

  • Automatically-generated validation plots (per-DEM and collection-wide).

  • Export per-cell errors to GeoTIFF, GeoPackage, Shapefile, or XYZ text.

  • Local, spatially-indexed photon database — download once, validate many times — with commands to list, size, rebuild, and delete cached data.

  • Export classified photons from the database to GeoPackage, Shapefile, or XYZ text.

  • Runs fully offline on any machine, with configurable data directories and per-project config profiles.

Installation#

Available on PyPI:

pip install ivert

or on conda-forge:

conda install ivert

For development (editable install from this repo):

git clone https://github.com/continuous-dems/ivert.git
cd ivert
pip install -e .

Three dependencies — fetchez, globato, and transformez — are pulled automatically from the continuous-dems GitHub organization and do not need to be installed separately.

Quick start#

1. Set up IVERT’s data directories and credentials (run once on a new machine):

ivert setup

This creates the local ~/.ivert data directories and checks your ~/.netrc for NASA Earthdata Login credentials, offering to save them if they are not already present. Earthdata credentials are required to download ICESat-2 data (register for a free account).

2. Download ICESat-2 photon data for your area (bounding box in W/E/S/N order):

ivert database download -- -74.0/-73.0/40.5/41.0

3. Validate your DEM:

ivert validate mydem.tif

4. Check the output directory for mydem_results.h5, a validation plot (.png), and error exports (.tif, .gpkg).

Indices and tables#