💻 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]...

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 whose combined extent defines the download region. Use –wsen to switch to W/S/E/N order.

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

(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)

export

Export IVERT ICESat-2 photons to GIS vector formats.

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

* nothing — export 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 export

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

* the IVERT database index .nc file, exported as 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 exports every field it holds per granule, and cannot be written as ‘xyz’ since it holds polygons rather than points.

Examples:

ivert database export

ivert database export -of gpkg,shp -o bahamas_photons

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

ivert database export coastline.gpkg -of xyz

ivert database export granules/ATL24_20230101_x-74y40.nc

ivert database export 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]

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”

Usage

ivert validate [OPTIONS] [FILES_OR_DIRECTORY]...

Options

-V, --vdatum <vdatum>

Vertical datum of the input DEM(s). Accepts an EPSG code (‘EPSG:5703’, ‘5703’), a bare integer, or a common short name (‘navd88’, ‘egm2008’, ‘mllw’, …). 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 their EPSG codes, 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. Requires the -mc/–measure-coverage flag.

-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

-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)