💻 Command Line Interface

The ivert command line tool allows you to build an icesat2 database and validate DEms.

ivert

IVERT: ICESat-2 Validation of Elevations Reporting Tool.

Run ‘ivert <command> –help’ for detailed help on any command.

Usage

ivert [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

--config <PATH>

Path to a user config file, overriding the default (~/.ivert/user_config.ini) and the IVERT_USER_CONFIG environment variable.

-v, --verbosity <LEVEL>

Logging verbosity: debug, info, warning, or error (case-insensitive). Overrides the ‘verbosity’ setting in ivert_defaults.ini for this run. Change the persistent default with ‘ivert options verbosity=<level>’.

cache

Manage the IVERT local file cache.

Run ‘ivert cache <subcommand> –help’ for details.

Usage

ivert cache [OPTIONS] [COMMAND] [ARGS]...

delete

Delete all files in the IVERT cache directory.

Usage

ivert cache delete [OPTIONS]

Options

-f, --force

Skip the confirmation prompt.

list

Show the number of files and total size of the cache.

Usage

ivert cache list [OPTIONS]

classes

List the ICESat-2 photon classification codes and their meanings.

These are the class codes assigned to ICESat-2 photons during classification and used when filtering photons for validation (e.g. the --classes option of ivert database download and ivert validate). Definitions come from the globato ICESat-2 reader so they always match the classifier.

Usage

ivert classes [OPTIONS]

database

Manage the local IVERT ICESat-2 photon database.

Subcommands handle downloading new data, updating existing records, and editing or inspecting the database.

Run ‘ivert database <subcommand> –help’ for details.

Usage

ivert database [OPTIONS] [COMMAND] [ARGS]...

convert

Convert IVERT ICESat-2 photons to GIS vector formats.

BBOX_OR_FILE (optional) says what to convert. It is one of:

* nothing — convert every photon in the database

* a 4-value bounding box in W/E/S/N order (slash-separated,

e.g. -74/-73/40.5/41)

* a georeferenced raster file, whose extent defines the region

* a polygon-vector file, whose polygon(s) define the area(s) to convert

* a single IVERT .nc photon granule, converted in its entirety

* the IVERT database index .nc file, converted to a polygon layer of

granule footprints (one rectangle per granule, from its data_bbox)

The last two are auto-detected from the contents of the .nc file.

Photon outputs carry the same per-photon fields as ‘ivert database’ stores (x, y, z, class_code, class_name, confidence, delta_time, granule_id, and bathy_confidence where present). The database index converts every field it holds per granule, and cannot be written as ‘xyz’ since it holds polygons rather than points.

Examples:

ivert database convert

ivert database convert -of gpkg,shp -o bahamas_photons

ivert database convert – -74/-73/40.5/41 -c 40/41 -ds 2023.01.01 -de 2024.01.01

ivert database convert coastline.gpkg -of xyz

ivert database convert granules/ATL24_20230101_x-74y40.nc

ivert database convert granules/_ivert_database_index.nc -of gpkg,shp

(Note: Use the ‘–’ delimiter to end command-line options if coordinates begin with a negative ‘-‘)

Usage

ivert database convert [OPTIONS] [BBOX_OR_FILE]...

Options

-of, --output-format <FORMATS>

Vector format(s) to export, drawn from ‘gpkg’, ‘shp’, ‘xyz’. Pass a single format or a comma-separated combination (e.g. ‘gpkg,shp’).

Default:

'gpkg'

-o, --output <PATH>

Output file path. The correct extension is added per format, so multiple formats share this base name. Default: ‘ivert_photons’ in the current directory, or the input file’s name when exporting a single .nc file.

-c, --classes <CLASSES>

Slash-separated photon class codes to include (e.g. ‘1/40/41’). Default: all classes. Run ‘ivert classes’ for the full list of codes.

-ds, --start-date, --start_date <DATE>

Only export photons on or after this date. Accepts any format supported by Python’s dateparser library (e.g. ‘2023.01.01’, ‘1 year ago’). Default: no lower date bound.

-de, --end-date, --end_date <DATE>

Only export photons before this date. Accepts any format supported by Python’s dateparser library. Default: no upper date bound.

-p, --projection <projection>

Horizontal projection (EPSG code) that the bounding-box coordinates are in.

Default:

'EPSG:4326'

--wsen

Treat the bounding box as W/S/E/N order (lower-left, upper-right). Default order is W/E/S/N (Xmin/Xmax/Ymin/Ymax).

-ow, --overwrite

Overwrite existing output files. Default: skip formats whose file already exists.

-f, --force

Skip the confirmation prompt when the export is estimated to be large.

Arguments

BBOX_OR_FILE

Optional argument(s)

delete

Delete the NetCDF database index file.

The downloaded .nc granule files are kept unless –all is specified.

Usage

ivert database delete [OPTIONS]

Options

-a, --all

Also delete all .nc granule data files from the granules directory.

-y, --yes

Skip confirmation prompt and delete immediately.

download

Download ICESat-2 photon data for a region of interest.

BBOX_OR_FILES: A 4-value bounding box in W/E/S/N order (slash-separated, e.g., -74.0/-73.0/40.5/41.0), or one or more DEM files and/or polygon vector files (.gpkg, .shp, .geojson, .kml, …) whose combined area defines the download region. Use –wsen to switch to W/S/E/N order.

All of the files’ footprints are dissolved into one area, which is then covered with as few rectangular requests as possible (2-degree squares over its bounding box, minus the squares the area does not reach, merged back together), so a vector file of many adjacent or scattered tiles is fetched in one pass without a request per tile and without covering the gaps between them. Vector files are read in their own coordinate system; -p only applies to a numeric bounding box.

Examples:

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

ivert database download -ds 2023.01.01 -de 2024.01.01 ../dems/oregon_coast_v1.tif

ivert database download -ds “two years ago” -de “one year ago” ../dems/*.tif

ivert database download survey_tiles.gpkg

(Note: Use the ‘–’ delimiter to explicitly end your command-line options if coordinates begin with a negative ‘-‘)

Usage

ivert database download [OPTIONS] BBOX_OR_FILES...

Options

-ds, --date-start <date_start>

Start date for the ICESat-2 data search. Accepts any format supported by Python’s dateparser library (e.g., ‘2023.01.01’, ‘1 year ago’).

Default:

'one year and one week ago'

-de, --date-end <date_end>

End date for the ICESat-2 data search. Must be after –date-start. The default one-week buffer accounts for processing delays in ICESat-2 derived products (ATL08, ATL24, etc.).

Default:

'one week ago'

-p, --projection <projection>

Horizontal projection (EPSG code) that the bounding box coordinates are in.

Default:

'EPSG:4326'

--wsen

Treat BBOX as W/S/E/N order (lower-left, upper-right). Default order is W/E/S/N (Xmin/Xmax/Ymin/Ymax).

-r, --replace

Replace any previously downloaded data that overlaps the requested region in space and time. Default: keep existing data and only fill gaps.

-c, --classes <classes>

ICESat-2 photon classes to download, slash-separated. Run ‘ivert classes’ for the full list of codes and their meanings.

Default:

'1/6/7/40/41/42/44'

-cl, --confidence-level <confidence_level>

Minimum ATL03 signal confidence level to save (1-4). Photons below this level are discarded before writing to the database. 1=low (keep all), 2=medium, 3=high, 4=very-high.

Default:

1

-bc, --bathy-confidence <bathy_confidence>

Minimum ATL24 bathymetry confidence to save (0.0-1.0). Bathy-floor photons (class 40) below this confidence are discarded before writing to the database.

Default:

0.01

-f, --force

Skip the interactive prompt when the requested date range extends beyond the ATL24 data cutoff date. A warning is still printed.

Arguments

BBOX_OR_FILES

Required argument(s)

dump

Pack the IVERT database, or part of it, into a zip archive.

The archive holds the database’s ICESat-2 photon granule files and its landmasks, as they are, with a summary of what is inside. Restore it on this or another machine with ‘ivert database restore’.

BBOX_OR_FILE (optional) limits the dump to a region. It is one of:

* nothing — dump the whole database

* a 4-value bounding box in W/E/S/N order (slash-separated,

e.g. -74/-73/40.5/41)

* a georeferenced raster file, whose extent defines the region

* a polygon-vector file, whose polygons are covered with rectangles

that define the region

Granule files and landmasks reaching outside the region (or the dates given with -ds/-de) are cut to it.

Examples:

ivert database dump -o my_database.zip

ivert database dump -o monterey.zip – -122.5/-121.5/36/37.2

ivert database dump study_area.gpkg -ds 2022.01.01 -de 2023.01.01

(Note: Use the ‘–’ delimiter to end command-line options if coordinates begin with a negative ‘-‘)

Usage

ivert database dump [OPTIONS] [BBOX_OR_FILE]...

Options

-o, --output <PATH>

The archive to write (‘.zip’ is added if missing), or an existing directory to write ‘ivert_database_<YYYYMMDD>.zip’ into. Default: that name in the current directory.

-ds, --start-date <DATE>

Only dump photons on or after this date. Accepts any format supported by Python’s dateparser library (e.g. ‘2023.01.01’, ‘1 year ago’).

-de, --end-date <DATE>

Only dump photons before this date.

-p, --projection <projection>

Horizontal projection (EPSG code) that the bounding-box coordinates are in.

Default:

'EPSG:4326'

--wsen

Treat the bounding box as W/S/E/N order (lower-left, upper-right). Default order is W/E/S/N (Xmin/Xmax/Ymin/Ymax).

-ow, --overwrite

Overwrite the archive if it already exists.

-f, --force

Skip the confirmation prompt when the dump is estimated to be large.

Arguments

BBOX_OR_FILE

Optional argument(s)

export

Deprecated alias for ‘ivert database convert’, to be removed in a later IVERT release.

Convert IVERT ICESat-2 photons to GIS vector formats.

BBOX_OR_FILE (optional) says what to convert. It is one of:

* nothing — convert every photon in the database

* a 4-value bounding box in W/E/S/N order (slash-separated,

e.g. -74/-73/40.5/41)

* a georeferenced raster file, whose extent defines the region

* a polygon-vector file, whose polygon(s) define the area(s) to convert

* a single IVERT .nc photon granule, converted in its entirety

* the IVERT database index .nc file, converted to a polygon layer of

granule footprints (one rectangle per granule, from its data_bbox)

The last two are auto-detected from the contents of the .nc file.

Photon outputs carry the same per-photon fields as ‘ivert database’ stores (x, y, z, class_code, class_name, confidence, delta_time, granule_id, and bathy_confidence where present). The database index converts every field it holds per granule, and cannot be written as ‘xyz’ since it holds polygons rather than points.

Examples:

ivert database convert

ivert database convert -of gpkg,shp -o bahamas_photons

ivert database convert – -74/-73/40.5/41 -c 40/41 -ds 2023.01.01 -de 2024.01.01

ivert database convert coastline.gpkg -of xyz

ivert database convert granules/ATL24_20230101_x-74y40.nc

ivert database convert granules/_ivert_database_index.nc -of gpkg,shp

(Note: Use the ‘–’ delimiter to end command-line options if coordinates begin with a negative ‘-‘)

Usage

ivert database export [OPTIONS] [BBOX_OR_FILE]...

Options

-of, --output-format <FORMATS>

Vector format(s) to export, drawn from ‘gpkg’, ‘shp’, ‘xyz’. Pass a single format or a comma-separated combination (e.g. ‘gpkg,shp’).

Default:

'gpkg'

-o, --output <PATH>

Output file path. The correct extension is added per format, so multiple formats share this base name. Default: ‘ivert_photons’ in the current directory, or the input file’s name when exporting a single .nc file.

-c, --classes <CLASSES>

Slash-separated photon class codes to include (e.g. ‘1/40/41’). Default: all classes. Run ‘ivert classes’ for the full list of codes.

-ds, --start-date, --start_date <DATE>

Only export photons on or after this date. Accepts any format supported by Python’s dateparser library (e.g. ‘2023.01.01’, ‘1 year ago’). Default: no lower date bound.

-de, --end-date, --end_date <DATE>

Only export photons before this date. Accepts any format supported by Python’s dateparser library. Default: no upper date bound.

-p, --projection <projection>

Horizontal projection (EPSG code) that the bounding-box coordinates are in.

Default:

'EPSG:4326'

--wsen

Treat the bounding box as W/S/E/N order (lower-left, upper-right). Default order is W/E/S/N (Xmin/Xmax/Ymin/Ymax).

-ow, --overwrite

Overwrite existing output files. Default: skip formats whose file already exists.

-f, --force

Skip the confirmation prompt when the export is estimated to be large.

Arguments

BBOX_OR_FILE

Optional argument(s)

list

List granules currently in the IVERT ICESat-2 database.

Usage

ivert database list [OPTIONS]

Options

-a, --all

Show all fields for each granule instead of the default summary columns.

-bo, --boxes

Print the unique query bounding boxes used to build the database. Overrides –all.

rebuild

Rebuild the database index from existing .nc granule files on disk.

Usage

ivert database rebuild [OPTIONS]

restore

Unpack an ‘ivert database dump’ archive into the IVERT database.

ARCHIVE is a zip written by ‘ivert database dump’. Its photon granule files and landmasks are added to the local database, and the database index is rebuilt.

If the archive covers places and dates the database already holds, IVERT lists the overlap and asks what to do, unless -oo/–on-overlap says. The archive must use the same vertical datum as the database.

Usage

ivert database restore [OPTIONS] ARCHIVE

Options

-oo, --on-overlap <on_overlap>

What to do where the archive overlaps data already in the database, instead of asking: ‘all’ imports everything (possibly duplicating photons), ‘keep’ keeps the existing data and imports only what lies outside it, ‘replace’ imports everything and removes the existing data it overlaps, ‘cancel’ imports nothing.

Options:

all | keep | replace | cancel

--dry-run

Show what the archive holds and where it overlaps the database; change nothing.

Arguments

ARCHIVE

Required argument

size

Report the number of files and disk size for each part of the database.

Usage

ivert database size [OPTIONS]

options

Configure IVERT settings and local data directories.

Typically, run once before using IVERT on a new machine, or when changing data directory paths or credentials.

Usage

ivert options [OPTIONS] [COMMAND] [ARGS]...

Options

-y, --yes

Skip the confirmation prompt and also update any settings that are defined in terms of the ones being changed.

info

Show a description of a single setting, its current value, and default.

Usage

ivert options info [OPTIONS] OPTION_NAME

Arguments

OPTION_NAME

Required argument

list

List all configurable settings and their current values.

Usage

ivert options list [OPTIONS]

Options

-d, --details

Show a description of what each setting means.

reset

Reset all settings to IVERT defaults by deleting the user config file.

Usage

ivert options reset [OPTIONS]

Options

-y, --yes

Skip confirmation prompt.

setup

Create IVERT’s local data directories and check NASA Earthdata credentials.

Run once on a new machine. Creates the ~/.ivert data directories and verifies that NASA Earthdata Login credentials are stored in your ~/.netrc file, offering to save them if they are not.

Usage

ivert setup [OPTIONS]

validate

Validate one or more DEMs against ICESat-2 photon data.

FILES_OR_DIRECTORY can be one or more GeoTIFF paths, a directory (all *.tif files are used), or a glob pattern (e.g., data/ncei*.tif).

Example: ivert validate mydem.tif -V navd88 -n “Oregon Coast”

Each run that validates anything writes a manifest of its settings into the output directory; pass it back with -m/–manifest to repeat them.

Usage

ivert validate [OPTIONS] [FILES_OR_DIRECTORY]...

Options

-m, --manifest <FILE>

Run with the settings recorded in an IVERT manifest, the ‘ivert_manifest.ini’ (or ‘<dem>_ivert_manifest.ini’) file that every validation writes into its output directory. Options given on the command line override the manifest’s values. The manifest’s input files and output directory are not used: name the DEMs (and -o) as usual.

-V, --vdatum <vdatum>

Vertical datum of the input DEM(s). Accepts an EPSG code (‘EPSG:5703’, ‘5703’), a common short name (‘navd88’, ‘egm2008’, ‘mllw’, …), or a transformez reference ID (‘vdatum:mllw’). Tidal names are passed to transformez as its own IDs. If omitted, IVERT reads the datum from the DEM metadata header. Use –list-vdatums to see all recognised names.

--list-vdatums

Print all recognised vertical datum names and what they resolve to, then exit.

-n, --name, --region-name <region_name>

Name of the region being validated. For a single DEM, appears on its plot (defaults to the DEM filename). For a collection, appears only on the collection-level summary plot; individual DEM plots always use their filenames.

-ph, --include-photons

Return a point database of individual ICESat-2 photons used to validate each DEM, in addition to the normal .h5 and .tif results outputs.

-mc, --measure-coverage

Measure relative photon coverage per grid cell (fraction of 15x15 sub-regions containing photons). Useful for post-processing coarse-resolution DEMs where sampling bias may matter.

-mcp, --minimum-coverage-pct <minimum_coverage_pct>

Only validate grid cells whose measured coverage is at or above this percentage (0-100); lower-coverage cells are dropped from the results, statistics, and plots. Applies to every cell unless -mcpl or -mcpb sets a threshold for that type of cell. Turns on -mc/–measure-coverage.

-mcpl, --minimum-coverage-pct-land <minimum_coverage_pct_land>

Like -mcp, but only for land cells (cells with no bathymetry photons), overriding -mcp for them. Turns on -mc/–measure-coverage.

-mcpb, --minimum-coverage-pct-bathy <minimum_coverage_pct_bathy>

Like -mcp, but only for bathymetry cells (cells with any bathymetry photons), overriding -mcp for them. Bathymetry cells are usually far sparser than land cells, so they often need a lower threshold. Turns on -mc/–measure-coverage.

-bn, --band-num <band_num>

Raster band to validate in each DEM (1-indexed). Other bands are ignored.

Default:

1

-sd, --outlier-sd <outlier_sd_threshold>

Standard-deviation threshold for outlier filtering. Errors more than this many SDs from the mean are treated as noise and removed. Use -1 to disable outlier filtering.

Default:

2.5

-c, --classes <CLASSES>

ICESat-2 photon classes to validate against, slash-separated (e.g. ‘1/40’). Photons in any other class are excluded before the elevation statistics are computed. Run ‘ivert classes’ for the full list of codes.

Default:

'1/6/40'

-mp, --min-photons <min_photons>

Minimum number of photons a grid cell must contain to be validated. Cells with fewer photons are omitted from the results entirely. Cells with 5 or more photons have their outliers trimmed to the interdecile range; cells below that use every photon they contain.

Default:

3

-b, --buildings

Include building-class photons (class 7) in validation, on top of -c/–classes.

-cl, --confidence-level <confidence_level>

Minimum ATL03 signal confidence level to use (1-4). Photons below this level are excluded from validation. 1=low (keep all), 2=medium, 3=high, 4=very-high.

Default:

4

-bc, --bathy-confidence <bathy_confidence>

Minimum ATL24 bathymetry confidence to use (0.0-1.0). Bathy-floor photons (class 40) below this confidence are excluded from validation.

Default:

0.9

-bf, --bathy-filters <RULES>

Comma-separated filters that remove misclassified bathy-floor (class 40) photons: ‘deep’ (reference bathymetry too deep for ICESat-2), ‘offshore’ (near-surface returns far from the coast), ‘reference’ (much shallower than the reference bathymetry), ‘land’ (below sea level on land). ‘none’ turns them off. Overrides the ‘bathy_filters’ setting (default: all four).

--bathy-max-depth <M>

‘deep’ filter: depth past which ICESat-2 cannot see the seafloor. Overrides ‘bathy_max_depth_m’.

--bathy-ref-window <M>

‘deep’ filter: radius searched for the shallowest reference cell. Overrides ‘bathy_ref_window_m’.

--bathy-near-surface <M>

‘offshore’ filter: photons less than this far below sea level (the EGM2008 geoid, which ignores the tide) are near-surface. Raise in macrotidal areas. Overrides ‘bathy_near_surface_m’.

--bathy-min-coast-dist <M>

‘offshore’ filter: only photons farther than this from the coastline. Overrides ‘bathy_min_coast_dist_m’.

--bathy-ref-tolerance <M>

‘reference’ filter: how much shallower than the reference a photon may be. Overrides ‘bathy_ref_tolerance_m’.

--bathy-land-max-below-sl <M>

‘land’ filter: how far below sea level a photon on land may be. Overrides ‘bathy_land_max_below_sl_m’.

--bathy-offshore-min-ref-depth <M>

‘offshore’ filter: apply only where the reference is also deeper than this, to protect shallow banks. ‘none’ turns it off. Overrides ‘bathy_offshore_min_ref_depth_m’ (default: off).

--bathy-ref-raster <FILE>

Reference bathymetry raster for the filters, in metres relative to EGM2008, instead of ETOPO 2022. ‘none’ uses ETOPO. Overrides ‘bathy_ref_raster’.

-o, --outdir <DIR>

Output directory for validation results. Relative paths are resolved relative to the input DEM’s directory. Defaults to the ‘ivert_results_subdir’ setting (run ‘ivert options list’ to view).

--ndv <VALUE>

No-data value to exclude from DEM pixels before validation. Accepts a number (e.g. -9999) or ‘nan’ for IEEE floating-point NaN. Overrides any no-data value in the DEM file header. If not set, the file header value is used, falling back to the config default (dem_default_ndv).

-ef, --export-formats <FORMATS>

Comma-separated GIS formats to export the per-cell errors into, drawn from ‘tif’, ‘gpkg’, ‘shp’, ‘xyz’. Overrides the ‘export_error_formats’ setting for this run only. Pass ‘none’ (or an empty string) to skip error exports.

-ow, --overwrite

Redo the validation and overwrite existing output files, even if the validation has already completed (or partially completed) for this DEM. Default: reuse existing interim/output files and skip work that’s already done.

-ex, --exclude <BBOX_OR_FILE>

Exclude ICESat-2 photons falling within a zone before validation. Repeatable (use multiple times to combine zones). Each use takes either a 4-value slash-separated bounding box in the DEM’s own projection (W/E/S/N order, minx/maxx/miny/maxy; use –wsen for W/S/E/N order), or a path to a vector file (.shp, .geojson, .gpkg) containing exclusion polygon(s).

--wsen

Treat -ex/–exclude bounding boxes as W/S/E/N order (minx/miny/maxx/maxy). Default order is W/E/S/N (minx/maxx/miny/maxy).

Arguments

FILES_OR_DIRECTORY

Optional argument(s)