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.1.tar.gz (253.2 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.1-cp311-abi3-win_amd64.whl (1.6 MB view details)

Uploaded CPython 3.11+Windows x86-64

whirlwind_insar-0.5.1-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.1-cp311-abi3-musllinux_1_2_aarch64.whl (1.7 MB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

whirlwind_insar-0.5.1-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.1-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.1-cp311-abi3-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

whirlwind_insar-0.5.1-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.1.tar.gz.

File metadata

  • Download URL: whirlwind_insar-0.5.1.tar.gz
  • Upload date:
  • Size: 253.2 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.1.tar.gz
Algorithm Hash digest
SHA256 186f584c8705b9d90ab610f9117714492e8c05edfd79d246c8ade24403a67dc9
MD5 0f522445f5166223d068e70d4e05ca86
BLAKE2b-256 fd42e4644396fdc50127c5d95245431d3ee601a40c3f71983a271a99ccfe0c8f

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.1.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.1-cp311-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.1-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 dff266fc97978934a541345ae309b45ed00194d71fc37d761e575386db7c28cb
MD5 eb536c44606d6f529b43e1932c0b3f6e
BLAKE2b-256 f2341a84d957dbdc8b2b367ea278a8a95b87c6c6b70bbc96f47d671a47ebe49d

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.1-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.1-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.1-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 b1f4ccbf8610fa48880e0098f221ee78df615c7cb6ed4964d7df437acd5c9222
MD5 43ab49a0561777659b4aab7330d2ecaf
BLAKE2b-256 11103400e5a4365f2d3615c0486f36be0ea15c5da53ec9f958cd128669c506ad

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.1-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.1-cp311-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.1-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 eb55849cb57dbf859a125ef6a87d0130e9a9d8413b1f2e446056f6df41c8a060
MD5 5de8a4ab5e9cc47d82e4d55ea3ba59b4
BLAKE2b-256 524ad2b4bac78c042a418c48a5ec96fb568dd842888f5cbfcf6629ec3b6a34ef

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.1-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.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 813a96adfb891291282302946eddf8a7c5764ed299396b7f6619b03494c5953f
MD5 4b78ea1c260d2d7eb0a14d745dda81fb
BLAKE2b-256 1707704fa35af5e43fd569e6179f98f8cab0415e2efccf7f3bdacfa26808a9cb

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.1-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.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 2afbbef973012e4609c16014cc2f14cfee4ec89a44c61a728818955ba6d86000
MD5 c90f3994bd653fc0e58e195938ce2bc4
BLAKE2b-256 4735075980e603d73a32e0f688c7430e9edf56d73f4c5ce90842d5324a4f4905

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.1-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.1-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.1-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9d8e98ce83400f71e4c6a240856d01dfa24874cdc22421686a18a76c393ecd8c
MD5 c333e4fe00a0c6f3d6e775131e2e0f01
BLAKE2b-256 a0490d91a58751c494fefe3cee91bc6a323b520de3210a81a42f20c12f9aa932

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.1-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.1-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for whirlwind_insar-0.5.1-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 2b6bd4b8ca8c15da25f1b81edeeec8a51aa92c9f3c7945f838de1a619b159008
MD5 b0a33a14e73ff42d6fb37e37e0410da6
BLAKE2b-256 6e8fa9462d51fee30a8f5d9d66917417959adf467d2436c52f46dc3c0ae6f117

See more details on using hashes here.

Provenance

The following attestation bundles were made for whirlwind_insar-0.5.1-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