asap-stereo 0.3.1

Docs

Documentation is available at https://asap-stereo.readthedocs.io

Goals

The aim of ASAP-Stereo is to enable reproducible workflows for ASP. Through rich logging and the jupyter notebook based workflows, users can distribute the complete log of the steps they ran to produce a digital elevation model, and from that other users can run the same steps to duplicate results. ASAP-Stereo, like the asp_scripts project, provides high level functions to execute many individual steps of the pipeline to reduce the complexity of producing a CTX or DEM to two steps.

In addition, workflows are broken down to dozens of granular steps that users can re-run with different parameters to fix issues as they arise.

High Level Workflow

ASAP-Stereo provides both a command line interface and jupyter notebook based workflows that are also executable using the command line interface, accessible using the asap command. Generally, users should first make the CTX DEM for a location they are interested in and verify it is correctly registered to MOLA topography. Then users can proceed to produce a HiRISE DEM, and aligning it to the CTX DEM in the 2nd step for good co-registration of the HiRISE DEM.

The advantage of the CLI interface is that there are many individual steps in the workflow that sometimes need to be re-run with different parameters when things don’t go well. However, often this is only one or two steps in the workflow, such as stereo correlation or point cloud alignment that can be run in relative isolation of the other steps in the pipeline. Different steps require varying degrees of granularity as some steps are much faster than others.

The advantage of the Jupyter Notebook workflows are that the configuration parameters and preview images are richly displayed along side logs of the commands that were run so that workflows are both reproducible and easy to interact with. Should things go wrong for a processing step, the Jupyter Notebooks are easy to modify so steps can be re-run easily. The Jupyter Notebook workflow uses the same CLI interface for ASAP-Stereo so the notebooks are the preferred way to interact with ASAP-Stereo.

Differences from asp_scripts

There are a few minor to major differences between the workflow in ASAP-Stereo and the asp_scripts default workflow that are partially listed here.

1. Bundle Adjustment was added to the HiRISE workflow, possibly of marginal benefit.

2. PEDR data, and pedr2tab is optional as the ODE Rest API is used to get relevant data.

3. Image resolutions are encoded in file names in meters with an underscore for decimals (ie 0_25.tif would be 25 cm per pixel).

4. Hillshade alignment of the HiRISE dem to the target DEM is used to improve/speed up alignment of HiRISE to CTX.

Installation

ASAP can be installed using pip in a conda environment hosting ASP and ISIS. See the documentation for more details.

Clone the repository, cd into the project and run: python setup.py install (or develop).

You must also have all of the other dependencies for ASP and the asp_scripts installed and available in the path to run. You will also need GDAL command line tools,and ISIS3 installed. It is recommended to use anaconda to isolate the ASAP-Stereo environment.

New CTX-HiRISE Workflow (with notebooks)

nohup is recommended for each of the following steps for long running processes.

Pick two CTX and/or HiRISE images as stereo pairs and note their product ids, which can be partial.

You can either start with CTX or HiRISE, but note that the third HiRISE step requires a reference DEM like the once produced from CTX.

Detailed help for each command can be viewed by running: asap PREFIX COMMAND – –help, for example asap ctx notebook_pipeline_make_dem – –help.

Estimating Max-Disparity (–maxdisp)

note: As of 0.2.0 disparity is estimated for the user by ASAP, this note retained for cases when overrides needed.

The maximum disparity parameter used in both workflows above can be estimated by loading the reference and target DEM products into a GIS environment (like QGIS) to determine the distance in the x, y, and z axes between the two products. It is good practice to add a hundred meter margin to this estimate. For CTX use the PEDR CSV file to estimate it from MOLA, for HiRISE use the final DEM.tif (non-geoid corrected) for the corresponding CTX pair.