whirlwind-insar 0.1.0

Rust-backed 2D phase unwrapper for InSAR (`import whirlwind`)

whirlwind

Fast Rust-backed 2D InSAR phase unwrapping with Python bindings.

Whirlwind unwraps a complex interferogram and returns both unwrapped phase and connected-component labels. The NISAR comparison shows agreement with production SNAPHU on 2pi ambiguities, with lower runtime in the tested scenes.

The package is whirlwind-insar on PyPI and GitHub; it imports as whirlwind.

Quickstart

git clone https://github.com/scottstanie/whirlwind-insar.git
cd whirlwind-insar
pip install .

Source installs require Python 3.11+ and Rust.

Usage

import whirlwind as ww

unw, conncomp = ww.unwrap(igram, corr, nlooks=10.0, mask=mask)

igram is a complex wrapped interferogram, corr is coherence/correlation in [0, 1], and mask is optional with True for valid pixels.

For noisy scenes, coarsen the solve with downsample (it unwraps a coherently-averaged copy at the given factor to pick each block's 2π cycle, then maps the cycles back onto the full-resolution phase). nlooks stays the effective looks of your input corr — the down-look scaling is handled internally, so you do not raise it yourself:

unw, conncomp = ww.unwrap(igram, corr, nlooks=10.0, mask=mask, downsample=8)

CLI

The whirlwind CLI is at feature parity with the Python unwrap: every knob the Python API exposes (downsample, the bridge post-pass, persistent-scatterer interpolate, Goldstein filtering, and the connected-component cost controls) is available as a flag. Run whirlwind unwrap --help for the full list.

Install

Pick whichever is simplest for you - no Python required for any of these:

1. Prebuilt binary (simplest, no toolchain). Download the archive for your platform from the latest release, unpack it, and run the whirlwind executable. A single self-contained binary - handy for MATLAB users driving it via system('whirlwind unwrap ...').

2. From source with Cargo (needs the Rust toolchain):

   cargo install --path crates/whirlwind-cli --locked
   

3. Docker (see below).

Run

whirlwind unwrap \
    --phase wrapped_phase.tif \
    --cor coherence.tif \
    --mask valid_mask.tif \
    --nlooks 10 \
    --out unwrapped_phase.tif \
    --conncomp conncomp.tif

--phase is a float32 TIFF of wrapped phase in radians. --mask is optional; nonzero means valid. When --mask is omitted the CLI uses coherence > 0 as the default valid mask, matching the Python API.

For noisy scenes, coarsen the solve with --downsample (as in the Python API); the integration-component --no-bridge-able re-leveling pass runs by default:

whirlwind unwrap --phase wrapped_phase.tif --cor coherence.tif \
    --mask valid_mask.tif --nlooks 10 --downsample 8 \
    --out unwrapped_phase.tif

The CLI is pure Rust (no GDAL), so it also runs from a container. Pull the prebuilt image (published to the GitHub Container Registry by CI), or build it locally:

docker pull ghcr.io/scottstanie/whirlwind-insar:main   # prebuilt, or:
docker build -t ghcr.io/scottstanie/whirlwind-insar .  # build locally

docker run --rm -v "$PWD:/data" ghcr.io/scottstanie/whirlwind-insar unwrap \
    --phase /data/wrapped.tif --cor /data/cor.tif --nlooks 10 \
    --out /data/unw.tif --conncomp /data/conncomp.tif

Dolphin

Dolphin can select Whirlwind as an unwrap method:

dolphin unwrap --unwrap-options.unwrap-method whirlwind ...

See the Dolphin docs for the rest of the Dolphin workflow.

Development

uv sync
uv run maturin develop --release
uv run pytest python/tests
cargo test --workspace

More

• NISAR comparison
• Performance notes
• Algorithm notes
• Environment variables

Repository Layout

• python/whirlwind: Python API.
• crates/whirlwind-core: Rust algorithms.
• crates/whirlwind-py: PyO3 bindings.
• crates/whirlwind-cli: CLI binary.
• docs: reference docs.
• scripts: benchmarks and development utilities.

License

Licensed under either the BSD 3-Clause License or the Apache License, Version 2.0, at your option. See LICENSE.