asp_report#
The main CLI tool generates a comprehensive PDF report of ASP processing results.
What the report contains#
Each report opens with a title page of DEM metadata and a processing-parameters page that reconstructs the ASP commands from the logs, then one figure per page in processing order: input scenes, stereo geometry, match points, bundle adjustment residuals and camera changes (when --bundle-adjust-prefix is given), disparity, DEM results (DEM, triangulation intersection error, difference to the reference DEM), a hillshade with zoomed details, and the altimetry comparison — ICESat-2 on Earth, LOLA on the Moon, MOLA on Mars — before and after the optional pc_align step. Seven complete reports are on the Example Reports page.
The “Detailed Hillshade” page of the WorldView Atlanta multi-view report: the DEM hillshade with three subsets picked automatically from low, medium, and high triangulation-intersection-error areas, so the reader sees the best and worst of the surface without choosing where to look.#
Files needed from ASP processing#
During the stereo or parallel_stereo steps, add this flag to retain the files needed for plotting:
--keep-only '.mask .txt .exr .match -L.tif -L_sub.tif -R_sub.tif -D_sub.tif -D.tif -RD.tif -F.tif -PC.tif'
Basic usage#
At its simplest, run from the ASP processing directory:
asp_report --directory ./ \
--stereo-directory stereo
This requires only the directory where ASP processing was done (--directory) and the subdirectory containing stereo outputs (--stereo-directory). The reference DEM used in processing is automatically searched for in the logs and used for difference maps if found.
With bundle adjustment and reference DEM#
asp_report --directory ./ \
--bundle-adjust-prefix ba \
--stereo-directory stereo \
--reference-dem ref_dem.tif
--bundle-adjust-prefix accepts either the directory containing the bundle adjustment outputs (ba) or the same ASP-style output prefix you passed to stereo/mapproject (ba/run). A prefix narrows the file search to that run’s outputs when several runs share a directory.
Running without internet#
If you don’t have internet access, disable basemap and altimetry fetching:
asp_report --directory ./ \
--stereo-directory stereo \
--no-basemap \
--no-altimetry
Otherwise, basemaps are fetched using contextily and ICESat-2 data (Earth only) is fetched via SlideRule.
Planetary altimetry (Moon/Mars)#
For planetary DEMs, altimetry data must be requested separately using request_planetary_altimetry, then passed via --altimetry-csv:
# Step 1: Request data (one-time)
request_planetary_altimetry --dem stereo/output-DEM.tif --email user@example.com
# Step 2: After downloading and unzipping the result
asp_report --directory ./ \
--stereo-directory stereo \
--altimetry-csv /path/to/MolaPEDR_*_topo_csv.csv \
--no-basemap \
--no-geometry
Altimetry comparisons are on by default (skip with --no-altimetry). If the DEM is non-Earth but no --altimetry-csv is provided, the tool prints instructions and skips altimetry plots.
Automatic pc_align with ICESat-2#
Unless --no-altimetry or --no-pc-align is passed, when the DEM is on Earth the report appends a pc_align-based alignment step after the standard ICESat-2 diagnostics. The aligned DEM is only retained on disk when pc_align reduces the median absolute error (p50) toward 0 by more than 5% and the translation magnitude exceeds the minimum threshold relative to the DEM GSD; otherwise the intermediate DEM file is removed so its presence is a truthy signal that the alignment is worth using.
The report adds:
An alignment report page: the kwargs used for
pc_align, a one-row horizontal stats table (p16/p50/p84before and after,N/E/Dshifts, translation magnitude, all in meters), a description of what each column means, and a status line naming the aligned DEM path or explaining why no DEM was retained.On success, three additional full-page figures against the aligned DEM: a pre/post land-cover histogram (shared bin edges, per-landcover stats in stacked text boxes whose outline colors match the bar colors), the full elevation profile, and the best/worst 1 km agreement segments. Segment selection is held fixed so Med/NMAD are directly comparable to the unaligned variants.
Disable with --no-pc-align. Automatically skipped when --no-altimetry is set.
ICESat-2 time filtering#
The --atl06sr-time-range option controls which ICESat-2 data is requested from the SlideRule API. Requesting fewer granules speeds up processing but may miss useful data.
"all" (default) requests every ICESat-2 pass over the DEM footprint from mission start (2018-10-14) to present. This is recommended for most surfaces, as the full ~7 years of data provides the largest sample for validation.
"auto" activates date-buffered filtering. It attempts to detect the scene acquisition date from the stereopair XML metadata and requests data within ±1 year of that date. If no XML metadata is found, it falls back to requesting all data.
"START,END" (e.g. "2020-01-01,2024-12-31") requests data within an explicit date range.
For areas with known temporal surface change (e.g. ice sheets, glaciers), consider using "auto" or an explicit date range to restrict the ICESat-2 data to a time window that matches the DEM acquisition. Seasonal or multi-temporal filtering is also available via the Python API (predefined_temporal_filter_atl06sr, generic_temporal_filter_atl06sr).
Comparing re-processing runs (--reuse-selections)#
When you re-process the same scene with different ASP parameters, several diagnostic figures normally change what they show between runs: a fresh ICESat-2 request returns a slightly different point set, the “best” profile track flips, the best/worst agreement segments move, and the detailed-hillshade clip boxes are re-selected from the re-processed intersection-error raster. That makes a true before/after comparison impossible.
Every asp_report run now writes a small YAML sidecar next to the report — <report_stem>_figure_selections.yml — recording each of these selections: the ICESat-2 request settings and parquet cache locations, the chosen profile track (rgt/cycle/spot), the best/worst segment extents, and the detailed-hillshade clip boxes (as DEM-CRS bounding boxes).
To make a second run reproduce the first run’s figures exactly, pass that file back in:
# Run A (e.g. mapprojected stereo) — writes report + *_figure_selections.yml
asp_report --directory my_scene/ --stereo-directory stereo_mapproj/ \
--report-filename report_mapproj.pdf
# Run B (e.g. no-mapprojection variant) — reuses A's track, segments, points, and clips
asp_report --directory my_scene/ --stereo-directory stereo_no_mapproj/ \
--reuse-selections my_scene/stereo_mapproj/report_mapproj_figure_selections.yml \
--report-filename report_no_mapproj.pdf
--reuse-selections replays the exact ICESat-2 points (from the prior run’s parquet cache), pins the same profile track and best/worst segments, and clips the same ground areas for the detailed hillshade. Selections that can’t be applied to the new run (e.g. a clip box that falls outside a re-gridded DEM, or a track absent from freshly-loaded points) fall back to automatic selection with a warning rather than failing. The sidecar is human-readable, so you can also hand-edit it to force a particular track or clip.
The sidecar file#
A *_figure_selections.yml looks like this (paths shown as placeholders; clip boxes are in the DEM’s CRS and best/worst segments are pinned by absolute along-track distance start_xatc/end_xatc so they survive a re-gridded DEM and a shifted track start):
schema_version: 1
asp_plot_version: 1.16.0
dem_filename: <stereo_dir>/run-DEM.tif
map_crs: EPSG:32610
detailed_hillshade:
subset_km: 5.0
intersection_error_percentiles: [16, 50, 84]
dem_crs: EPSG:32610
clips:
- label: low # low / medium / high intersection-error uncertainty
bbox: [569428.22, 5210008.87, 574414.69, 5214995.33]
pixel_offset: [1710, 1140]
- label: medium
bbox: [594360.56, 5175103.60, 599347.02, 5180090.07]
pixel_offset: [3705, 2565]
- label: high
bbox: [589374.09, 5205022.40, 594360.56, 5210008.87]
pixel_offset: [1995, 2280]
icesat2: # omitted for planetary (LOLA/MOLA) DEMs
request: {processing_levels: [all], res: 20, len: 40, ats: 20,
time_range: all, t0: '2018-10-14T00:00:00Z', t1: '2024-06-01T00:00:00Z'}
parquet_cache: {all: <run_dir>/atl06sr_all.parquet}
profile_track: {rgt: 829, cycle: 20, spot: 3}
segments:
best: {start_xatc: 5245997.7, end_xatc: 5246997.7, start_km: 47.84, end_km: 48.84}
worst: {start_xatc: 5219817.7, end_xatc: 5220817.7, start_km: 21.66, end_km: 22.66}
Full options#
Usage: asp_report [OPTIONS]
Generate a comprehensive report of ASP processing results.
Creates a series of diagnostic plots for stereo processing, bundle
adjustment, ICESat-2 comparisons, and more. All plots are combined into a
single PDF report with processing parameters and summary information.
Options:
--directory TEXT Required directory of ASP processing with
scenes and sub-directories for stereo and
optionally bundle adjustment. Default: current
directory.
--bundle-adjust-prefix TEXT Optional bundle adjustment output location,
relative to --directory. Accepts either a
directory (e.g. 'ba') or an ASP-style output
prefix as passed to --bundle-adjust-prefix in
stereo/mapproject (e.g. 'ba/run'). If expected
*residuals_pointmap.csv files are not found
there, no bundle adjustment plots will be
generated. Default: None.
--stereo-directory TEXT Required directory of stereo files. Default:
stereo.
--dem-filename TEXT Optional DEM filename in the stereo directory.
Default: None, which will search for the
*-DEM.tif file in the stereo directory. Specify
it as the basename with extension, e.g. my-
custom-dem-name.tif.
--dem-gsd TEXT Optional ground sample distance of the DEM.
Default: None, which will search for the
*-DEM.tif file in the stereo directory. If
there is a GSD in the name of the file, specify
it here as a float or integer, e.g. 1, 1.5,
etc.
--map-crs TEXT Projection for altimetry and bundle adjustment
plots. As EPSG:XXXX. Default: None, which will
use the projection of the ASP DEM, and fall
back on EPSG:4326 if not found.
--reference-dem TEXT Optional reference DEM used in ASP processing.
No default. If not supplied, the logs will be
examined to find it. If not found, no
difference plots will be generated.
--no-basemap Skip the figure basemaps (basemaps are added by
default, which requires an internet
connection).
--no-altimetry Skip the altimetry comparisons (plotted by
default: ICESat-2 for Earth, LOLA for Moon,
MOLA for Mars; planetary DEMs require
--altimetry-csv).
--altimetry-csv PATH Path to a LOLA/MOLA *_topo_csv.csv file from
the ODE GDS API. Required for planetary
altimetry plots. Obtain via:
request_planetary_altimetry --dem <dem> --email
<email>, then download and unzip the result.
--no-pc-align Skip the pc_align step (run by default against
the reference altimetry -- ICESat-2 for Earth,
MOLA for Mars, LOLA for Moon -- appending the
alignment-report pages; skipped automatically
with --no-altimetry).
--no-geometry Skip the stereo geometry plots (plotted by
default).
--subset-km FLOAT Size in km of the subset to plot for the
detailed hillshade. Default: 1 km.
--atl06sr-time-range TEXT Time range for ICESat-2 ATL06-SR data requests.
"all" for all available data (mission start to
present), or "START,END" for a custom range
(e.g. "2020-01-01,2024-12-31"), or "auto" for
scene metadata +/- 1 year. Default: all.
--reuse-selections PATH Path to a *_figure_selections.yml written by a
previous run. When supplied, replays that run's
ICESat-2 points (parquet), profile track,
best/worst segments, and detailed-hillshade
clip boxes so figures are directly comparable
across re-processing runs. Default: None.
--report-filename TEXT PDF report filename or path. A bare filename
(e.g. 'report.pdf') is saved in the stereo
directory. A path (e.g. 'reports/report.pdf' or
'/tmp/report.pdf') is used as-is. Default:
auto-generated from directory name.
--report-title TEXT Title for the report. Default: Directory name
of ASP processing.
--help Show this message and exit.
During the stereo or parallel_stereo steps, add this flag to retain the files needed for plotting:
--keep-only '.mask .txt .exr .match -L.tif -L_sub.tif -R_sub.tif -D_sub.tif -D.tif -RD.tif -F.tif -PC.tif'