StaMPS-PyRefactor

Python port and workflow refactor of the StaMPS PS-InSAR chain

GPL-3.0

This project is derived from StaMPS (Stanford Method for Persistent Scatterers) and released under GPL-3.0. Preserve the license and cite appropriate StaMPS publications when using or redistributing. This is not the official StaMPS distribution.

Overview

StaMPS-PyRefactor translates the MATLAB StaMPS processing chain into Python, focused on PS-InSAR and SLC-native Small Baseline workflows from ISCE/ISCE2 stack outputs. Intermediate products use HDF5 with JSON parameter files, snaphu unwrapping, and GeoPackage/Shapefile export. This is an independent refactor — not the official StaMPS distribution.

Features

Direct ISCE2 preprocessing

prep_isce.py reads ISCE2 merged directories without requiring MATLAB parms.mat.

Full Steps 1–8

Initial loading, gamma estimation, PS selection, weeding, phase correction, snaphu unwrapping, and SCLA/SCN filtering.

PS and SB workflows

Supports PS-InSAR and SLC-native Small Baseline flows including define_sb_pairs and build_sb_phase.

HDF5 + JSON parameters

parms.json / localparms.json replace MATLAB .mat with priority localparms > parms > code defaults.

Vector export

export_results.py exports velocity (mm/yr) and displacement time series (mm); GeoPackage by default, Shapefile optional.

Performance tuning

Step 3 gamma re-estimation and Step 4/5 merge paths optimized for large HDF5 I/O.

Architecture

ISCE2 merged

prep_isce.py

stamps_main.py (Steps 1-8)

export_results.py

Typical PS flow: prep_isce prepares patches and candidates → stamps_main runs Steps 1–8 → export_results writes GeoPackage. SB flow additionally uses define_sb_pairs and build_sb_phase.

Workflows

prep_isce.py reads ISCE2 merged stack
stamps_main.py Steps 1–8
export_results.py exports GeoPackage

python stamps_python/prep_isce.py path/to/merged \
  --output runs/prep_ps \
  --reference-date 20200101 \
  --bootstrap-metadata \
  --range-patches 8 --azimuth-patches 2 \
  --write-step1

python stamps_python/stamps_main.py --start 1 --end 8 --config runs/prep_ps

Completed

Direct ISCE2 merged preprocessing with Python metadata bootstrap
StaMPS Steps 1–8 in Python with snaphu integration
Full-chain Step 8 validation on real ISCE2 stacks
PS and SB workflows with GeoPackage export
Step 3/4/5 performance improvements and incidence extraction

Known limitations

SB workflow needs broader cross-dataset validation
MATLAB plotting GUI not ported
TRAIN tropospheric correction not ported end to end
Not yet packaged as an installable Python distribution
Automated test coverage still limited

Requirements

Python 3.10+ (validated on Windows with Python 3.11)
snaphu installed and on PATH (Step 6 unwrapping)
ISCE2 merged stack (SLC/, geom_reference/, baselines/)
pip install -r requirements.txt

Quick start

1. Install dependencies
After cloning, run pip install -r requirements.txt
2. PS preprocessing
python stamps_python/prep_isce.py path/to/merged --output runs/prep --reference-date YYYYMMDD --bootstrap-metadata --write-step1
3. Run Steps 1–8
python stamps_python/stamps_main.py --start 1 --end 8 --config runs/prep
4. Export results
python stamps_python/export_results.py --input-path runs/prep --output-dir runs/prep/export --format gpkg --correction v-dso

Downloads

StaMPS-PyRefactor v0.20

June 26, 2026

Source release

Only source archives are provided. Clone the repo and run pip install -r requirements.txt

ZIP (Source)tar.gz (Source)GitHub

Release notes

StaMPS-PyRefactor v0.20 adds the first validated Small Baseline (SBAS) workflow support on top of the existing PS-InSAR Python refactor.

Highlights

Added SLC-native Small Baseline pair definition with define_sb_pairs.py.
Added split SB preprocessing support in prep_isce.py, including SB candidate preparation without immediate phase extraction.
Added build_sb_phase.py to build wrapped SB phase samples from co-registered ISCE2 SLC pairs and write Python-native Step-1 HDF5 products.
Extended Step 1-8 processing paths for SB projects, including SB-aware merge, unwrapping, SCLA/SCN handling, and export behavior.
Updated GeoPackage/Shapefile export so SB time series can be exported through the Python pipeline.
Expanded README and operation manual with the recommended Small Baseline workflow and command examples.
Added a synthetic regression check for split SB preparation plus SLC-native SB phase building.

Validation

Syntax checks passed for the modified Python modules and new SB scripts.
stamps_python/tests/prep_isce_sb_split_check.py passed on the synthetic ISCE2 SB fixture.
git diff --check passed, with only local LF/CRLF conversion warnings from Git on Windows.

Known limitations

SBAS support is now available, but broader numerical equivalence against every MATLAB StaMPS SB branch still needs more datasets.
TRAIN/tropospheric correction integrations remain outside this release.
The project is still a development refactor, not a packaged Python distribution.

This project is an independent GPL-3.0 refactor and is not the official StaMPS distribution.

StaMPS-PyRefactor v0.10

June 21, 2026

Source release

Only source archives are provided. Clone the repo and run pip install -r requirements.txt

ZIP (Source)tar.gz (Source)GitHub

Release notes

StaMPS-PyRefactor v0.10 is the first public development release of the Python refactor of the StaMPS PS-InSAR workflow.

Highlights

Python implementation of the PS-InSAR processing chain from Step 1 through Step 8.
Direct preprocessing of ISCE2 SLC stack outputs with prep_isce.py.
Python-native HDF5 intermediate products and JSON parameter files.
SNAPHU integration for phase unwrapping.
Improved Step 6 grid construction, Goldstein filtering, look-angle error estimation, and 3D_FULL unwrapping behavior.
Deramped velocity and displacement time-series export.
GeoPackage output by default, with Shapefile output retained as an option.
Windows-focused validation with cross-platform Python code paths.

Validation

The full PS-InSAR chain has been run through Step 8 on real ISCE2 SLC stack data.
ISCE2 metadata bootstrap and candidate preparation have been validated without requiring MATLAB parameter files.
Synthetic regression checks cover small-baseline preparation and core Step 6 grid/unwrapping behavior.

Known limitations

The Small Baseline workflow is not yet fully validated end to end.
TRAIN/tropospheric correction integrations are not ported end to end.
Numerical equivalence with every MATLAB StaMPS branch and optional mode is still being validated.
The project is not yet packaged as an installable Python distribution.

This project is an independent GPL-3.0 refactor and is not the official StaMPS distribution.