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

Uploaded CPython 3.11+Windows x86-64

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

Uploaded CPython 3.11+musllinux: musl 1.2+ ARM64

whirlwind_insar-0.6.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.8 MB view details)

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

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

Uploaded CPython 3.11+macOS 11.0+ ARM64

whirlwind_insar-0.6.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.6.0.tar.gz.

File metadata

  • Download URL: whirlwind_insar-0.6.0.tar.gz
  • Upload date:
  • Size: 261.5 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.6.0.tar.gz
Algorithm Hash digest
SHA256 934eb0adf7681e50fe51bc30d4c3496d27af8e0a4a92d263857fd5a100c5e3d2
MD5 d0e034d1d060f5dc7f308bae0862aba1
BLAKE2b-256 4877033f10a8a7f015801270c486746083c3f2b5eb2902e54b56cd538b4b6017

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for whirlwind_insar-0.6.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e5f9bc5ed451006c14d47001bac7bc89d8b0b4dbc36c66638e1bef36bbf3b5af
MD5 df23875ae170a1d871dba538245ef2d4
BLAKE2b-256 a2f2d22ef27f32751832bf114832d0be4b7bfd94f64d9867a18a6d8cdf21f5ea

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for whirlwind_insar-0.6.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 04ac1882ae1da23c6b6185c405e115ea211879608c907ccea93752c9183455fe
MD5 111c3ba9202a41677c98242f77cd6a28
BLAKE2b-256 7bd49012371fac994e7b2e099237e98dc15a1b86d552e38e7271f015793bf0bb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for whirlwind_insar-0.6.0-cp311-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 1206a24c6c7681d9e26a09a73d6924d17cd926a5e3867d13dff8e30433e9474c
MD5 356790eaf44deccc2dd14cfdbe453ab2
BLAKE2b-256 6d6dc82683bae9a8a932b1027bb9ae852f505b9fbdab3e4003dd7163b18c6413

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for whirlwind_insar-0.6.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 31c5114601f619e637ed5703b59aba7cb426dbf1447354b1193d71fb3b990b3a
MD5 f308acc2ffec67f5096286d81ecef711
BLAKE2b-256 efa170b2b063ed37217bc2f53f7f3506b8546fdcbacb17108e9537ac71b9284f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for whirlwind_insar-0.6.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 3fb2f5e920218331627105a8c3aeed5ad6791d55b3c199d06710f4468f252f8b
MD5 64a05771cb8f1cc131e7e7897e44bbd1
BLAKE2b-256 799936c077120c104e8d145fbe00d684329b4b41223cb3fc4d500f754ec9fea9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for whirlwind_insar-0.6.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 df83a2f7b4e60577dff290ed04fc86c960b48c30b013531c6559dacc6ce29f37
MD5 17c783236bcf13638d3c4809cc6084e3
BLAKE2b-256 d09c4f869642c91c5e5c5f6e6ad2b095227f76b99c119f28265e05c62f6f6f20

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for whirlwind_insar-0.6.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 75ef8cb23eb422202a1ca2f2e47e141752ceb936ae6e6bc39b209d2303d10b9e
MD5 857c3a8359b82d70e6cf64820de13231
BLAKE2b-256 165dd3ac31b828cacef32243934375261ea07f1b245dbdf522ec5be9b1818f61

See more details on using hashes here.

Provenance

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