Skip to main content

Workflows for generating surface displacement maps using InSAR

Project description

dolphin

Pytest and build docker image pre-commit.ci status Documentation Status Conda-Forge PyPI platforms GitHub Discussion DOI

High resolution wrapped phase estimation for Interferometric Synthetic Aperture Radar (InSAR) using combined persistent scatterer (PS) and distributed scatterer (DS) processing.

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)

The full set of options is written to the configuration file; you can edit this file, or you can see which commonly tuned options by are changeable running dolphin config --help.

Building and running via Docker

dolphin can also be run using Docker. You can use the one built on Github, or build it locally using the script

./docker/build-docker-image.sh

Citation

If you use dolphin in your research, please cite:

Staniewicz et al., (2024). Dolphin: A Python package for large-scale InSAR PS/DS processing. Journal of Open Source Software, 9(103), 6997, https://doi.org/10.21105/joss.06997

Contributing

We welcome many forms of contributing, including testing, bug reports, and documentation fixes. If you think you've found a problem, please let us know! You can raise an issue on the repository, where there are templates for Bug Reports and Feature Requests. If you have a general question of idea, feel free to raise it in the Discussions page.

For more detailed guidance on setting up a development environment, including how make and test changes to the code, see Contributing to Dolphin.

For more general Q&A, please use the Discussions page.

License

This software is licensed under your choice of BSD-3-Clause or Apache-2.0 licenses. See the accompanying LICENSE file for further details.

SPDX-License-Identifier: BSD-3-Clause OR Apache-2.0

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dolphin-0.40.0.tar.gz (10.0 MB view details)

Uploaded Source

Built Distribution

dolphin-0.40.0-py3-none-any.whl (213.5 kB view details)

Uploaded Python 3

File details

Details for the file dolphin-0.40.0.tar.gz.

File metadata

  • Download URL: dolphin-0.40.0.tar.gz
  • Upload date:
  • Size: 10.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for dolphin-0.40.0.tar.gz
Algorithm Hash digest
SHA256 8182f1fe9ce98ce4e2c7f1e41b579ee3b475751b0b2f0ee26cca5b971f1d1853
MD5 da3d1f064091eeadab006ae721f3e8e4
BLAKE2b-256 89139f13e82fee35461bdfc67bfd117c96706eab2b523f7c3f80dd6b4193dd66

See more details on using hashes here.

Provenance

The following attestation bundles were made for dolphin-0.40.0.tar.gz:

Publisher: cd.yml on isce-framework/dolphin

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file dolphin-0.40.0-py3-none-any.whl.

File metadata

  • Download URL: dolphin-0.40.0-py3-none-any.whl
  • Upload date:
  • Size: 213.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for dolphin-0.40.0-py3-none-any.whl
Algorithm Hash digest
SHA256 9f0c4c90c548ae6a9166d1278af62201e833983e9259d187d6385dbc3ed64c23
MD5 872188aa3d1164d74b1691dac6463f5c
BLAKE2b-256 e417dd487334f642859a007d8b3013b7b43ee1fbf826c2c9412f0d0d94eabcb8

See more details on using hashes here.

Provenance

The following attestation bundles were made for dolphin-0.40.0-py3-none-any.whl:

Publisher: cd.yml on isce-framework/dolphin

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page