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

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.6.0-2025-12-26-x86_64-Linux.tar.bz2
./StereoPipeline-3.6.0-2025-12-26-x86_64-Linux/bin/stereo --help

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

To permanently add the ASP executable subdirectory to your PATH, add to your shell configuration (e.g., ~/.bashrc), a line similar to:

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

The latest additions are documented in Section 22.

2.1.2. MacOS

ASP is available for the Mac Intel and Mac Arm architectures. The latter is somewhat experimental but was shown to work well in testing. The Mac Arm package has all ASP logic except the minor libelas stereo algorithm (Section 18.5).

The installation steps are the same as for Linux. It is important to note that:

  • An error may be shown about not being able to verify the developers. That can be overridden in the Privacy & Security settings of the system. Consider using instead the conda-based installation (Section 2.4), which should not have this issue.

  • Running the Intel build the first time will be slow, as Rosetta will translate the instructions to the native architecture. Subsequent runs will be faster.

2.1.3. 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.2. Conda and docker

The latest ASP release (3.6.0) can be installed with conda (Section 2.4).

ASP can be installed with Docker (instructions).

2.3. Post-installation

The next steps depend on whether it is desired to process planetary (non-Earth), Earth, or aerial images.

2.3.1. Planetary images

To process images from NASA’s spacecraft that are exploring other planets, install ISIS and its data. Summary of the steps:

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

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

  3. Add the ISIS executables to your path:

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

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

  4. 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.

  5. Install Stereo Pipeline and set the PATH variable as above.

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

2.3.2. Earth images

Processing Earth images is described in the data processing tutorial in Section 5. See also examples for ASTER (Section 8.19), Pleiades (Section 8.23), SkySat (Section 8.25), and many more in Section 8.

2.3.3. Aerial and historical images

Fetch the software as above. Processing images without accurate camera pose information is described in Section 9.1. See also examples for declassified satellite images in Section 8.26.

2.4. Conda-based installation

The ASP 3.6.0 release (December 26, 2025) can be installed via conda, together with ISIS 9.0.0 (Section 2.3.1) for Linux, Mac Intel, and Mac Arm.

The Mac Arm release is experimental but was tested rather thoroughly. Since USGS did not release an ISIS version for Mac Arm (as of 12/2025), this is shipped with an unofficial ISIS Arm conda package, hosted on the nasa-ames-stereo-pipeline channel. This one lacks the Kakadu JPEG2000 library support. Consider using the Intel release under Rosetta 2 for mission-critical work.

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.

Configure the conda 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

Not having the channels in this order is likely to result in failure to install ASP. Do not use the defaults channel.

Install ASP with the commands:

conda config --set channel_priority flexible
conda create -n asp            \
  -c nasa-ames-stereo-pipeline \
  -c usgs-astrogeology         \
  -c conda-forge               \
  -c defaults                  \
  stereo-pipeline=3.6.0

This will create a new environment named asp and install ASP 3.6.0 together with ISIS 9.0.0 and all other dependencies.

The priority setting is set to flexible, as otherwise conda can get confused if the same package (even with old versions) exists in more than one channel.

Note that the latest build (Section 2.1) may have more features and fixes than this official release.

2.4.1. Post-installation

Run:

conda activate asp

and set:

export ISISROOT=$CONDA_PREFIX

in any new shell. These should put the ASP binaries in the path, and will also initialize various environmental variables, including ISISROOT and PROJ_DATA.

Check if the stereo command is found by running:

which stereo

When working with planetary images with ISIS, the ISISDATA environmental variable also needs to be set (Section 2.3.1). For more information see the ISIS installation instructions.

2.4.2. Alternative approaches

Consider using mamba instead of conda for the installation, as it is much faster. (Note that recent conda distributions default to using the mamba solver.)

2.5. System requirements

To run ASP, a computer cluster sharing storage and connected via ssh is needed (Section 8.18).

As a rule of thumb, for images on the order of 20,000 x 20,000 pixels, a machine with 40 GB of RAM 16 cores could likely produce a terrain model in 4 - 20 hours. There is a lot of uncertainty here, and much depends on the choice of the stereo algorithm (Section 6.1.1), and if mapprojection is employed (Section 6.1.7).

1 TB of storage or more is suggested.

2.6. 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.3.1).

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

/bin/sh: camrange: command not found

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

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