Skip to content

Getting started

Install

dolphin may be installed via conda-forge:

# if mamba is not already installed, see here: https://mamba.readthedocs.io/en/latest/
mamba install -c conda-forge dolphin

It is also available via PyPI and may be pip-installed on some platforms, such as Google's Colab. However, certain dependencies (e.g. GDAL) are more easily set up through conda.

dolphin has the ability to unwrap interferograms using several options, which can be toggled using the unwrap_method configuration option:

  1. snaphu-py, a lightweight Python bindings to SNAPHU. Available on both pip and conda.
  2. isce3's python bindings to SNAPHU, PHASS, or ICU
  3. spurt, a 3D unwrapper, implementing the Extended Minimum Cost Flow (ECMF) algorithm
  4. tophu, a multi-scale unwrapper designed to unwrap large interferograms in parallel tiles at multiple resolution.

These may be installed via conda or (in the case of snaphu-py) pip.

To install locally:

  1. Download source code:
git clone https://github.com/isce-framework/dolphin.git && cd dolphin
  1. Install dependencies:
mamba env create --file conda-env.yml

or if you have an existing environment:

mamba env update --name my-existing-env --file conda-env.yml
  1. Install dolphin via pip:
conda activate dolphin-env
python -m pip install .

Dolphin can also take advantage of CUDA-compatible GPUs for faster processing. See the docs for installation instructions and configuration.

Usage

The main entry point for configuring and running workflows the dolphin command line tool:

  1. dolphin config: create a workflow configuration file.
  2. dolphin run : run the workflow using this file.

Example usage:

dolphin config --slc-files /path/to/slcs/*tif
# OR: to make a coarser output 4x as quickly:
# dolphin config --slc-files /path/to/slcs/*tif --strides 2 2
dolphin run dolphin_config.yaml

The config command creates a YAML file (by default dolphin_config.yaml in the current directory). If you'd like to see an empty YAML with all defaults filled in, you can run dolphin config --print-empty, which creates a sample file like the one here

The only required inputs for the workflow are the paths to the coregistered SLC files (in either geographic or radar coordinates). If the SLC files are spread over multiple files, you can either

  1. use the --slc-files option with a bash glob pattern, (e.g. dolphin config --slc-files merged/SLC/*/*.slc would match the ISCE2 stack processor output )

  2. Store all input SLC files in a text file delimited by newlines (e.g. my_slc_list.txt), and give the name of this text file prefixed by the @ character (e.g. dolphin config --slc-files @my_slc_list.txt)

For a more complete tutorial, see our notebooks

For help with installing locally and contributing, see the full developer setup instructions.