Skip to main content

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

whirlwind can be installed from PyPI,

pip install whirlwind-insar

or on Conda Forge:

conda install -c conda-forge whirlwind-insar

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.

CLI

A CLI is provided that mirrors the Python API. Run whirlwind --help for the full list.

 whirlwind --help
InSAR phase unwrapper.
...

CLI installation

There are multiple ways to install whirlwind to use only the CLI:

  1. Prebuilt binary (no Python or toolchain). Download the archive for your platform from the [latest release][releases], unpack it, and run the whirlwind executable. A single self-contained binary - handy for MATLAB users driving it via system('whirlwind ...').
  2. With the Python package. The wheel ships a whirlwind console script which can be run using uvx with with the UV tool system:
uvx --from whirlwind-insar whirlwind --help   # zero-install try-out
pip install whirlwind-insar                   # puts `whirlwind` on PATH
  1. Docker via the Github Container Registry

  2. From source with Cargo using a local Git clone:

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

Running the CLI

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

--phase is the wrapped phase in radians: a float32 TIFF, or a flat binary float32 file (see below). If you start from a complex-valued GeoTIFF, extract GDAL's PHASE derived subdataset first and pass that as --phase; --ifg is for flat complex64 rasters. The phase path reconstructs a unit-magnitude interferogram, so it does not preserve amplitude. --mask is optional; nonzero means valid. When --mask is omitted the CLI uses coherence > 0 (and igram != 0 with --ifg) as the default valid mask, matching the Python API. The CLI writes a SNAPHU-faithful connected-component label map by default next to --out (foo.conncomp.tif for TIFF, foo.unw.conncomp for flat .unw); use --conncomp PATH to choose the path or --no-conncomp to skip it.

Flat-binary formats (snaphu / ROI_PAC / isce2 / GAMMA)

Whirlwind can also accept flat binary rasters:

# snaphu-style: complex64 .int + amp/cor .cc; width ("line length") on the CLI
whirlwind --ifg pair.int --cor pair.cc --cols 1024 --nlooks 10 --out pair.unw

# ROI_PAC / Stanford: geometry read from the <file>.rsc sidecar automatically
whirlwind --ifg 20150902_20150914.int --cor 20150902_20150914.cc \
    --nlooks 10 --out 20150902_20150914.unw

# isce2 stripmapStack / topsStack: the <file>.xml sidecars provide everything
whirlwind --ifg filt_fine.int --cor filt_fine.cor --nlooks 10 \
    --out filt_fine.unw

# GAMMA: big-endian; width from a .par/.off (or --cols + --big-endian)
whirlwind --ifg pair.diff --ifg-meta pair.off \
    --cor pair.cc --cor-meta pair.off --nlooks 10 --out-format float --out pair.unw
  • --ifg is the raw flat complex64 interferogram (snaphu COMPLEX_DATA, i.e. numpy.tofile() of a complex64 array). --phase accepts float32 wrapped phase as TIFF or flat binary (snaphu FLOAT_DATA) and reconstructs unit-magnitude complex values. Exactly one of the two is given.
  • --cor may be single-band float32 (isce2 .cor, GAMMA .cc) or the two-band line-interleaved amplitude+correlation "rmg" layout (snaphu's default, ROI_PAC .cc): the band count is detected from the file size and the correlation is read from the second channel, exactly as snaphu does. --cor-format alt-sample covers snaphu's sample-interleaved variant.
  • --cols (alias --width) is snaphu's "line length" / ROI_PAC WIDTH; the row count always comes from the file size. A <file>.rsc or <file>.xml next to each input supplies it automatically (and, for isce2, the dtype, band count, scheme, and byte order). Use --ifg-meta, --phase-meta, or --cor-meta when the sidecar is not next to that input.
  • Output is chosen by extension (override with --out-format): .tif → TIFF; .unw → two-band amp+phase rmg (snaphu's default output layout); anything else → flat float32 phase. Conncomp follows the output style by default: u16 TIFF for TIFF outputs, or one-byte-per-pixel flat for flat outputs (the snaphu/isce2 convention). Flat outputs keep the input's byte order.
  • --mask also accepts snaphu-style flat byte masks (nonzero = valid, zero = masked).
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 \
    --phase /data/wrapped.tif --cor /data/cor.tif --nlooks 10 \
    --out /data/unw.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

git clone https://github.com/scottstanie/whirlwind-insar.git
cd whirlwind-insar
pip install .
uv sync
uv run maturin develop --release
uv run pytest python/tests
cargo test --workspace

More

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.

Download files

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

Source Distribution

whirlwind_insar-0.5.0.tar.gz (248.0 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

whirlwind_insar-0.5.0-cp311-abi3-win_amd64.whl (1.6 MB view details)

Uploaded CPython 3.11+Windows x86-64

whirlwind_insar-0.5.0-cp311-abi3-musllinux_1_2_x86_64.whl (2.0 MB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ x86-64

whirlwind_insar-0.5.0-cp311-abi3-musllinux_1_2_aarch64.whl (1.6 MB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

whirlwind_insar-0.5.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.7 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ x86-64

whirlwind_insar-0.5.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.5 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

whirlwind_insar-0.5.0-cp311-abi3-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

whirlwind_insar-0.5.0-cp311-abi3-macosx_10_12_x86_64.whl (1.6 MB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

Details for the file whirlwind_insar-0.5.0.tar.gz.

File metadata

  • Download URL: whirlwind_insar-0.5.0.tar.gz
  • Upload date:
  • Size: 248.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for whirlwind_insar-0.5.0.tar.gz
Algorithm Hash digest
SHA256 d7673008c82ff07d5b2dc41fbb180a72956a6ec287647590c3480de9f82a5c6c
MD5 7ab4475e92451c6f7abdd9f262a59056
BLAKE2b-256 19d556f082150c83a6736f47595c2ea5b5585d7314e52f0daa9d9dbafeb3d211

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.0.tar.gz:

Publisher: release.yml on scottstanie/whirlwind-insar

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

File details

Details for the file whirlwind_insar-0.5.0-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 28a467bf584992ee8e91a39e33c180d6eb4d94a3f9cdf1ae631a1663768c3695
MD5 f907e4630ba3702612fcebd059e8839d
BLAKE2b-256 2db19d525cac061457b007d2da4bbcbc6839f94de9999717ddbc75aebfdc693c

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.0-cp311-abi3-win_amd64.whl:

Publisher: release.yml on scottstanie/whirlwind-insar

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

File details

Details for the file whirlwind_insar-0.5.0-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 fd0d957647d5a20978d25d8dc52935b5cf7c866524fc983ff4280bdb491738f9
MD5 49f8e5cc64206745284f4152be04a891
BLAKE2b-256 e3e6df662d3e7b10850a71bc96cfb3dc8bce304d6cb691d2a754b0db6c193a5f

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.0-cp311-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on scottstanie/whirlwind-insar

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

File details

Details for the file whirlwind_insar-0.5.0-cp311-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.0-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 ca127ef6771ca7d40ad449270eb395199d657ebb268d6ca8b98634adfc3773b1
MD5 29d561397b00565e1ef8cc263335e7da
BLAKE2b-256 5c7d9e8afd51eefbcaa96fcb8bb96465c0329ebad65d7d4cb04d32c43cc291dc

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.0-cp311-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on scottstanie/whirlwind-insar

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

File details

Details for the file whirlwind_insar-0.5.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d493ac29e3858a10daedb6890f4f1e141fe4593feb61e84fa88c0b1174cb3f58
MD5 aff1c8063bc82246bc82e7bf9ba9f714
BLAKE2b-256 9214d80bfd8226a850c723346ab0a83cf7a8c9d201f33166cbd17948ebdcb4bb

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on scottstanie/whirlwind-insar

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

File details

Details for the file whirlwind_insar-0.5.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0e574d03f6829d96bd4cdb20dd5b8909e13588a22e36c3475a612fca1535b458
MD5 2438ce6b71b2522f3977f47739a55467
BLAKE2b-256 816d6ce20bec4ce4b6811d53b58f17e81e2571237fbb275310445b1e6025443f

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on scottstanie/whirlwind-insar

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

File details

Details for the file whirlwind_insar-0.5.0-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b99ada8417e638b3cfe845c343b02829749cd8c111dd4085bd47dc5723c3995a
MD5 bff29328315c030f95b798dac5ee8935
BLAKE2b-256 ac019d66dce95332cecff03495a11257f4ccfbc33edc1ba15c08d841f67b8aad

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.0-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on scottstanie/whirlwind-insar

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

File details

Details for the file whirlwind_insar-0.5.0-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 ad29155a8ee29b777e43153123620a7ea6ce72e52f029ec0de4ddfb3b5284b75
MD5 66e86c976b6a23bb3ad54aac5a1f5398
BLAKE2b-256 3c1249b54a56743a5fe9cdddaf08c8d63d6c67eba612da71e2c1a7ac69773413

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.0-cp311-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on scottstanie/whirlwind-insar

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 Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page