2. Installation

Precompiled binaries are available for the stable releases and the current development build. Stereo Pipeline can also be compiled from source, but this is not recommended (Section 24).

2.1. Precompiled binaries

2.1.1. Linux and macOS

ASP builds are produced for Linux and OSX (with the Intel processor). ASP was verified to work on the OSX M1 processor using Rosetta 2. For Windows, see below.

Choose either the latest build (recommended) or a stable release from:

No installation steps or administrative rights are necessary. Extract the archive, and run the executables in the bin subdirectory as:

tar xvf StereoPipeline-3.3.0-2023-08-16-x86_64-Linux.tar.bz2
./StereoPipeline-3.3.0-2023-08-16-x86_64-Linux/bin/stereo --help

The result of the last command should be a help message.

The stable releases are also available via conda (Section 2.3).

ASP can be installed with Docker (instructions).

The latest additions are documented in Section 22.

To permanently add the ASP executable subdirectory to your PATH, add the following line to the shell configuration (e.g., ~/.bashrc), replacing /path/to/StereoPipeline/bin with the location on your filesystem:

export PATH=${PATH}:/path/to/StereoPipeline/bin

2.1.2. Windows

ASP does not offer Windows binaries. However, the Linux build can be run on Windows using the Windows Subsystem for Linux (WSL). Once a recent Linux distribution is installed and verified to work, the installation steps are the same as for Linux.

2.1.3. Planetary images

If you plan to process images from NASA’s spacecraft that are exploring other planets, you will probably need to have ISIS installed. A full ISIS installation is not required for operation of the main Stereo Pipeline programs (only the ISIS data directory is needed), but it is required for certain preprocessing steps before Stereo Pipeline programs are run for planetary data. If you only want to process terrestrial images, skip to Section 5.

To perform pre-processing (radiometric calibration, ephemeris processing, etc.), of non-terrestrial images prior to running Stereo Pipeline, you will need to install ISIS. Just as with our binaries, you can use the ISIS binaries as-is. See the ISIS installation instructions at:

ASP has its own self-contained version of the ISIS libraries, and on occasion it is behind the latest ISIS (see the release notes in Section 22 for the ISIS version ASP has). You should be able to use a newer version of ISIS to prepare the images and cameras and have those work with the version of ISIS shipped with ASP, assuming no major changes have taken place in the data formats or camera models by the ISIS developers. At the very least, you should be able to install the older standalone version of ISIS that ASP uses if a failure is found.

To install a specific version of ISIS, follow the ISIS installation instructions, but create a new conda environment (not the one with your current ISIS), and right before you would run conda install isis, run conda search isis to find all of the versions of ISIS available for installation. For example, if you wanted to install ISIS 8.0.0, run:

conda install -c usgs-astrogeology -c conda-forge isis=8.0.0

and then follow the remainder of the ISIS installation instructions.

In closing, running the Stereo Pipeline executables only requires that you have downloaded the ISIS secondary data and have appropriately set the ISISDATA environment variable. This is normally performed for the user by starting up the conda ISIS environment.

2.1.4. Quick start for ISIS users

2.1.4.1. Using the packaged ASP tarball

  1. Fetch Stereo Pipeline from https://github.com/NeoGeographyToolkit/StereoPipeline/releases

  2. Fetch ISIS binaries and install, following https://github.com/DOI-USGS/ISIS3#installation

  3. Fetch ISIS data, as detailed at https://github.com/DOI-USGS/ISIS3#the-isis-data-area

  4. Add the ISIS executables to your path:

    • bash: export PATH="/path/to/isis/bin:${PATH}"

    • csh: setenv PATH "/path/to/isis/bin:${PATH}"

  5. Set the ISISDATA environmental variable to point to where your ISIS data was downloaded, per the installation link above. For example, in the bash shell, this is done as follows:

    export ISISDATA="/path/to/isisdata"

    Check that you have the directory $ISISDATA/base.

  6. Extract Stereo Pipeline:

    tar xvf StereoPipeline-<VERSION>-<ARCH>-<OS>.tar.bz2

  7. Add Stereo Pipeline to your path:

    • bash: export PATH="/path/to/StereoPipeline/bin:${PATH}"

    • csh: setenv PATH "/path/to/StereoPipeline/bin:${PATH}"

  8. Try it out. See Section 4.1 for a quick Lunar example which does not require installing ISIS or it supporting data as above, and Section 4.2 for an example using Mars images and ISIS data.

2.1.4.2. Installing ASP and ISIS in the same conda environment

This is discussed further down.

2.1.5. Quick start for Digital Globe users

  1. Fetch Stereo Pipeline from https://github.com/NeoGeographyToolkit/StereoPipeline/releases

  2. Extract Stereo Pipeline:

    tar xvf StereoPipeline-<VERSION>-<ARCH>-<OS>.tar.bz2

  3. Add StereoPipeline to your path, as above.

  4. Try it out: Processing Earth images is described in the data processing tutorial in Section 5.

2.1.6. Quick start for aerial and historical images

Fetch the software as above. Processing images without accurate camera pose information is described in Section 10.

2.2. Common errors

Here are some errors you might see, and what it could mean. Treat these as templates for problems. In practice, the error messages might be slightly different.

Error: **ERROR** Unable to initialize camera model in Camera Factory.

**PROGRAMMER ERROR** Unable to create a shape model from
  given target and pvl.

**I/O ERROR** Unable to open [$ISISDATA/<Some/Path/Here>].
Stereo step 0: Preprocessing failed

You need to set up your ISIS environment or manually set the correct location for ISISDATA (Section 2.1.4).

bash: stereo: command not found

You need to add the bin directory of your deployed Stereo Pipeline installation to the environmental variable PATH (Section 2.1.4).

/bin/sh: camrange: command not found

You need to to add the bin directory of your ISIS installation to your path (Section 2.1.4).

Cache size (500 MB) is larger than the requested maximum cache size

Consider increasing --cache-size-mb for your program. This also may be a sign of large input TIF images being stored in blocks as tall or as wide as the image. The storage scheme of an image can be examined with the gdalinfo -stats command, and an image can be rewritten with square blocks using the command:

gdal_translate -co compress=lzw -co TILED=yes -co INTERLEAVE=BAND \
  -co BLOCKXSIZE=256 -co BLOCKYSIZE=256 input.tif output.tif

If the new images are used instead, that warning should go away and the processing time should go down. Both gdalinfo and gdal_translate are included with ASP.

2.3. Fetching pre-compiled ASP with conda

ASP’s official releases can be downloaded with conda, for Linux and OSX with the Intel processor.

ASP conda packages do not exist for ARM64 Mac (M1/M2). See Section 2.1 for how other platforms may be handled.

The latest conda release is version 3.3.0, published on August 16, 2023. See Section 22 for what changed since then. The newer functionality is available only with the daily build (Section 2.1).

To install conda, see:

Make the fetched installation file executable and run it, such as:

chmod u+x ./Miniconda3-latest-Linux-x86_64.sh
./Miniconda3-latest-Linux-x86_64.sh

on Linux, and analogously on OSX. Use the suggested:

$HOME/miniconda3

directory for installation.

Create an environment for ASP as:

conda create -n asp
conda activate asp

Add relevant channels:

conda config --env --add channels conda-forge
conda config --env --add channels usgs-astrogeology
conda config --env --add channels nasa-ames-stereo-pipeline

Do not skip doing each of these three, even if you think you already have some of these channels.

Run:

conda config --show channels

to ensure that the order of channels is:

- nasa-ames-stereo-pipeline
- usgs-astrogeology
- conda-forge
- defaults

It is possible that you may already have some of these channels in a global ~/.condarc file, and you may be tempted to just run the final add channels command. If you aren’t familiar with conda channel management, this may have unintended consequences. Please inspect the order of the output of the --show channels command carefully, if it is not exactly like the above, you can either edit the $CONDA_PREFIX/.condarc file, or delete it completely, and then run each of the three conda config --env -add channels commands exactly as shown.

You can use the --prepend channels argument to conda config but unless you want to add the nasa-ames-stereo-pipeline channel to all of your conda environments (which you probably don’t), please make sure you have activated your asp environment and make sure to use the --env argument to contain the change to the current environment and not all environments.

Install ASP with the command:

conda install                 \
 -c nasa-ames-stereo-pipeline \
 -c usgs-astrogeology         \
 -c conda-forge               \
 stereo-pipeline==3.3.0

This will install ASP 3.3.0 together with ISIS 8.0.0. Note that the latest build (see above) may have more fixes or features than this official release.

Alternatively, consider using mamba instead of conda. It is must faster though it is not always guaranteed to work.

2.3.1. Fixes for potential OSX issues

The ASP 3.3.0 conda package for OSX had a couple of issues with external packages. These were later fixed and the conda packages for this release have been updated. For the record, these issues and workarounds for them are described below, even though they are no longer applicable.

On OSX, if an error about embree not finding tbb is encountered (these are third-party libraries), run:

conda activate asp
conda install -c usgs-astrogeology -c conda-forge \
  embree -y --force-reinstall

If the ipfind (or pc_align with the option --initial-transform-from-hillshading, which uses ipfind) fails, try to run this tool along the lines of:

DYLD_LIBRARY_PATH=$HOME/miniconda3/envs/asp/lib ipfind \
  <other options>

These issues seem to be caused by how conda handles third-party libraries. This is not a problem with the binary release (Section 2.1) or with conda on Linux.

2.3.2. Post-installation

Check that the stereo command can be found as:

which stereo

If using ISIS, the environmental variable ISISROOT should be set to point to this distribution, such as:

export ISISROOT=$HOME/miniconda3/envs/asp

If you are working with planetary data, you need to complete the ISIS installation steps from this new asp conda environment. Your new asp environment already has the base ISIS software installed, but you must run the script which sets the ISIS environment variables, and also install the appropriate ISIS data files (if you also have a separate ISIS conda environment, you can use the set-up script to point the asp conda environment’s ISISDATA environment variable to your existing data area).

For more information see the ISIS installation instructions and Section 2.1.3.

2.3.3. Using a precise list of packages

Some variability may exist in the precise dependencies fetched by conda. For the record, the full environment for this release can be found as a set of .yaml files in the conda subdirectory of the Stereo Pipeline GitHub repository. So, alternatively, the installation can happen as:

conda env create -n asp -f asp_3.3.0_linux_env.yaml

or:

conda env create -n asp -f asp_3.3.0_osx_env.yaml

depending on your platform. Then invoke, as earlier:

conda activate asp

For how to build ASP, without and with conda, see Section 24.1 and Section 24.2.

2.4. Settings optimization

Finally, the last thing to be done for Stereo Pipeline is to setup up Vision Workbench’s render and logging settings. This step is optional, but for best performance some thought should be applied here.

Vision Workbench is a multi-threaded image processing library used by Stereo Pipeline. The settings by which Vision Workbench processes data are configurable by having a .vwrc file hidden in your home directory. Below is an example:

# This is an example VW configuration file. Save this file to
# ~/.vwrc to adjust the VW log settings, even if the program is
#already running.

# General settings
[general]
default_num_threads = 16
write_pool_size = 40
system_cache_size = 1073741824 # ~ 1 GB

# The following integers are associated with the log levels
# throughout the Vision Workbench.  Use these in the log rules
# below.
#
#    ErrorMessage = 0
#    WarningMessage = 10
#    InfoMessage = 20
#    DebugMessage = 30
#    VerboseDebugMessage = 40
#    EveryMessage = 100
#
# You can create a new log file or adjust the settings
# for the console log:
#   logfile <filename>
#       - or -
#   logfile console

# Once you have created a logfile (or selected the console), you
# can add log rules using the following syntax. (Note that you
# can use wildcard characters '*' to catch all log_levels for a
# given log_namespace, or vice versa.)

# <log_level> <log_namespace>

# Below are examples of using the log settings.

# Turn on various logging levels for several subsystems, with
# the output going to the console (standard output).
[logfile console]
# Turn on error and warning messages for the thread subsystem.
10 = thread
# Turn on error, warning, and info messages for the
# asp subsystem.
20 = asp
# Turn on error, warning, info, and debug messages for the
# stereo subsystem.
30 = stereo
# Turn on every single message for the cache subsystem (this will
# be extremely verbose and is not recommended).
# 100 = cache
# Turn off all progress bars to the console (not recommended).
# 0 = *.progress

# Turn on logging of error and warning messages to a file for the
# stereo subsystem. Warning: This file will be always appended
# to, so it should be deleted periodically.
# [logfile /tmp/vw_log.txt]
# 10 = stereo

There are a lot of possible options that can be implemented in the above example. Let’s cover the most important options and the concerns the user should have when selecting a value.

2.4.1. Performance settings

default_num_threads (default=2)

This sets the maximum number of threads that can be used for rendering. When stereo’s subpixel_rfne is running you’ll probably notice 10 threads are running when you have default_num_threads set to 8. This is not an error, you are seeing 8 threads being used for rendering, 1 thread for holding main()’s execution, and finally 1 optional thread acting as the interface to the file driver.

It is usually best to set this parameter equal to the number of processors on your system. Be sure to include the number of logical processors in your arithmetic if your system supports hyper-threading. Adding more threads for rasterization increases the memory demands of Stereo Pipeline. If your system is memory limited, it might be best to lower the default_num_threads option.

write_pool_size (default=21)

The write_pool_size option represents the max waiting pool size of tiles waiting to be written to disk. Most file formats do not allow tiles to be written arbitrarily out of order. Most however will let rows of tiles to be written out of order, while tiles inside a row must be written in order. Because of the previous constraint, after a tile is rasterized it might spend some time waiting in the write pool before it can be written to disk. If the write pool fills up, only the next tile in order can be rasterized. That makes Stereo Pipeline perform like it is only using a single processor.

Increasing the write_pool_size makes Stereo Pipeline more able to use all processing cores in the system. Having this value too large can mean excessive use of memory as it must keep more portions of the image around in memory while they wait to be written. This number should be larger than the number of threads, perhaps by about 20.

system_cache_size (default=1073741824)

Accessing a file from the hard drive can be very slow. It is especially bad if an application needs to make multiple passes over an input file. To increase performance, Vision Workbench will usually leave an input file stored in memory for quick access. This file storage is known as the ‘system cache’ and its max size is dictated by system_cache_size. The default value is 1 GB.

Setting this value too high can cause your application to crash. It is usually recommend to keep this value around 1/4 of the maximum available memory on the system. The units of this property is in bytes.

All tools shipped with ASP have the option --cache-size-mb to override the value of system_cache_size. Its default value is 1024 MB (1 GB).

The recommendations for these values are based on use of the block matching algorithm in ASP. When using memory intensive algorithms such as SGM you may wish to lower some of these values (such as the cache size) to leave more memory available for the algorithm to use.

2.4.2. Logging settings

The messages displayed in the console by Stereo Pipeline are grouped into several namespaces, and by level of verbosity. An example of customizing Stereo Pipeline’s output is given in the .vwrc file shown above.

Several of the tools in Stereo Pipeline, including parallel_stereo, automatically append the information displayed in the console to a log file in the current output directory. These logs contain in addition some data about your system and settings, which may be helpful in resolving problems with the tools (Section 19).

It is also possible to specify a global log file to which all tools will append to, as illustrated in .vwrc.