PHASE (Persistent scatterer Highly Automated Suite for Environmental monitoring)

PHASE (Persistent scatterer Highly Automated Suite for Environmental monitoring) is a MATLAB-based software suite for automated InSAR Persistent Scatterer Interferometry (PSI) processing and advanced geospatial analysis. Built on the foundation of snap2stamps and StaMPS, PHASE introduces enhanced automation, user-friendly interactive map interfaces, and a powerful geospatial modeling module to interpret and visualize displacement time series, making it ideal for environmental and infrastructure monitoring.

PHASE 6.0: preprocessing, StaMPS and geospatial modelling now run as standalone, editable MATLAB applications with a shared modern interface. The production entry points are PHASE_Preprocessing, PHASE_StaMPS and PHASE_Model; none of them loads an .mlapp at runtime. The former App Designer applications are retained only for provenance in legacy.

SAR Satellites compatibility

• Sentinel-1 (from European Space Agency)
• COSMO-SkyMed (from Agenzia Spaziale Italiana - automatically supports both CSK and CSG generations)

Required software

• SNAP (version 13.x is recommended)
• MATLAB (R2026a is recommended)
• StaMPS
• Python 3.11 or newer with requests, asf_search, shapely, and openpyxl

Required OS

• Linux: supported end-to-end for the complete PSI pipeline.
• Windows: supported end-to-end for the complete PSI pipeline (preprocessing, StaMPS, and geospatial analysis) via the Windows-native StaMPS fork pyccino/StaMPS. PHASE auto-discovers the StaMPS Windows install through StaMPS_CONFIG.ps1 and shares the Python interpreter with StaMPS via %APPDATA%\PHASE\python.txt (thanks to Samuel and Matteo).
• macOS: supports preprocessing and geospatial analysis modules.

Installation and setup

Important

Windows users: use the PHASE installer. Do not clone the repository for a normal installation. Download install-phase.exe from the latest GitHub Release, Release, run it, and launch PHASE from the three shortcuts it creates. The installer supplies and configures the complete Windows runtime, including StaMPS, TRAIN and their native executables; a plain repository clone does not. Clone the repository on Windows only if you intend to develop PHASE itself.

Note

A detailed, step-by-step guide is available in the provided user manual.
Before using PHASE, please carefully read the entire manual!

Windows installation

Download install-phase.exe, run it, and follow the wizard. It configures PHASE, StaMPS, TRAIN, the required Windows binaries and Python, then creates three shortcuts in the selected PHASE folder. The engine directory remains visible and editable. See installer/README.md for build and packaging instructions.

Manual installation (Linux, macOS, and developers only)

1. Install SNAP Software
   Download and install SNAP 13.x from the European Space Agency website.
   
   Verify that the following mandatory SNAP plugin module is installed:

   • Sentinel-1 Toolbox
     (Note: Previous versions required multiple toolboxes like Optical or SMOS, but these are no longer needed).
     

   After installing SNAP, it is highly recommended to optimize your memory settings:

   • Edit $HOME/snap/bin/gpt.vmoptions and modify the -Xmx parameter according to your RAM (e.g., -Xmx12G).
   • Edit $HOME/snap/etc/snap.properties and add/verify:
     • #snap.home=
     • #snap.userdir=
     • snap.jai.tileCacheSize = 1024
     • snap.jai.defaultTileSize = 512

2. Install Required Python Modules:
   Install Python 3.x on your machine. Ensure Python is added to your system's PATH. The PHASE suite utilizes standard built-in Python libraries, so you only need to install the external Excel library. Run the following command in your terminal:

   pip install openpyxl requests asf_search shapely

3. Install xterm (only Linux Users):
   Install xterm by running sudo apt-get install xterm in the terminal.

4. Install StaMPS (only Linux Users):
   Install StaMPS from the official GitHub repository.

   git clone https://github.com/dbekaert/StaMPS.git
   

5. Install PHASE suite

   • Download the latest release of the PHASE suite repository.
   • Move or extract the downloaded folder into your desired project directory.
   • Add the repository to the MATLAB path with addpath(genpath(pwd)).
   • Run PHASE_Preprocessing to open Module 1A immediately.
   • Tune the configurable parameters across the available tabs (including the interactive geographic map for AOI selection).
   • At the preprocessing handoff, PHASE opens PHASE_StaMPS for the generated ASC_* or DSC_* dataset. It may also be launched manually with PHASE_StaMPS(datasetFolder).
   • Run PHASE_Model for geospatial analysis of the exported PS displacement time series.

The three launcher files are small production wrappers around the validated editable engines. Internal package names retain the _beta suffix only for backward compatibility with configurations and existing installations.

Processing Steps

Module 1: InSAR PSI Processing

1. Automated SAR Images Download:
   Retrieve Sentinel-1 images via the integrated module through the Alaska SAR Facility APIs (thanks to Magnus and Johny). For COSMO-SkyMed, use the Images tab in the Cosmo-SkyMed panel to import your .h5 files (they are copied into the slaves directory automatically).
2. Interactive AOI & Automated Master Selection:
   Define your Area of Interest (AOI) by drawing a polygon directly on the integrated map or by importing supported geometry. Let PHASE automatically query the Open-Meteo historical weather API to select the optimal, driest master image for your stack.
3. Master & Slave Pre-Processing:
   Automated splitting, precise orbit correction, coregistration, and interferogram formation. For Sentinel-1, optimal swaths and bursts are dynamically calculated from your AOI. Includes StaMPS export, average scene intensity computation, and local incidence angle/coherence calculations.
4. StaMPS Processing:
   Automated data preparation, parameter definition, metadata auto-detection, and StaMPS PS analysis. Includes integration with TRAIN for GACOS tropospheric corrections, exporting displacement time series in Excel format.

Module 2: Geospatial PSI Data Analysis

The geospatial module enhances PHASE by providing advanced interpolation and modeling of PS displacement time series, tailored for Sentinel-1 data but compatible with any SAR data in the same table format. It offers flexible processing options for environmental and infrastructure monitoring, with user-configurable parameters for experts and automated settings for beginners. Key features include:

• Area of Interest (AOI) Definition: Specify the AOI via shapefiles (preferred for arbitrary shapes) or bounding boxes, with automatic detection and transformation of geographic (WGS84) or projected (UTM) coordinates. PS outside the AOI are filtered to focus analysis.
• Geometry Options: Supports 1D modeling for linear features (e.g., roads, railways) using centerline interpolation and 2D modeling for expansive areas (e.g., volcanoes, large infrastructures) using grid-based meshes, with user-defined resolutions.
• Temporal Modeling: Independently interpolates each time series using cubic splines for outlier removal, trend, and periodic component modeling, followed by least-squares collocation for residuals. Optional nearest-neighbor interpolation extends results spatially for visualization.
• Deterministic Spatio-Temporal Modeling: Creates a continuous displacement field using temporal cubic splines for data cleaning and multi-dimensional splines for spatial interpolation, with per-epoch GIF visualizations.
• Stochastic Spatio-Temporal Modeling: Combines deterministic cubic spline-based cleaning with Least Squares Collocation for deformation modeling, incorporating covariance modeling for robust uncertainty estimates.
• Alerts Analysis: Evaluates PS stability via a thresholding procedure based on average velocity and cumulative displacement, assigning alert levels using standardized statistical criteria and exponential/linear alert scaling.

The module generates a comprehensive Excel report across multiple sheets:

• General Sheet: Summarizes project metadata (title, date, location, modeling approach), unwrapping parameters, PS statistics, and visualizations (logo, AOI map, PS plot).
• Raw Displacement Sheet: Presents adjusted raw displacement time series with coordinates and a figure of average scene displacement with velocity annotation.
• Modeled Displacement Sheet: Details modeled displacements with average velocity and a geoscatter plot of velocity across the AOI.
• Uncertainty Sheet: Provides uncertainty estimates with a geoscatter plot of time-averaged uncertainty.
• Alerts Sheet: Reports stability analysis with velocity, cumulative displacement, and global alert percentages.
• Interpolation Sheet (Optional): Includes extrapolated time series at user-specified coordinates with individual displacement plots.

A shapefile and .mat file are generated in WGS84 (EPSG:4326) coordinates, including PS data, velocities, uncertainties, and risks for GIS compatibility.

Possible Errors and Solutions

The procedure has been tested on SNAP 9.x and 13.x, Python 3.11, Python 3.13, Ubuntu 20.04, Windows 10, macOS Sequoia (15.1), and MATLAB 2025a/2026a.

Tip

Refer to the manual for solutions to common errors encountered during the StaMPS processing.

SNAP version selection (Sentinel-1A/1B/1C/1D)

PHASE preprocessing supports both SNAP 9.x (legacy) and SNAP 13.x (recommended). Choose based on which Sentinel-1 satellites your dataset includes:

• SNAP 9.x: supports Sentinel-1A and Sentinel-1B only. Sentinel-1C (launched Dec 2024) and Sentinel-1D are not supported by the SNAP 9 product readers.
• SNAP 13.x: supports the full Sentinel-1A/1B/1C/1D constellation natively. Required for any dataset containing S1C or S1D acquisitions.

Point GPTBIN_PATH in your project.conf to the SNAP version you want PHASE to use:

GPTBIN_PATH = C:/Program Files/snap13/bin/gpt.exe   # SNAP 13 (S1A/B/C/D)
# GPTBIN_PATH = C:/Program Files/snap/bin/gpt.exe   # SNAP 9  (S1A/B only)

Important: do not mix SNAP-9 and SNAP-13 .dim products

SNAP 13's StampsExport operator raises NullPointerException on tie-point grids written by SNAP 9 (the BEAM-DIMAP TPG format changed between majors). The error is silent — StaMPS later hangs mid-PSI without a clear diagnostic.

PHASE's SEN_stamps_export.py automatically detects this mismatch and prints an actionable warning before launching gpt. The fix is to re-run the full preprocessing pipeline (split + coregistration + interferogram) from the original .SAFE.zip files using the same SNAP version that will run StampsExport.

SRTM 3Sec auto-cache

StampsExport has SRTM 3Sec hardcoded for the lat/lon geocoding output, regardless of the DEM chosen for coregistration. When the auto-download fails (offline, mirror down, or — on SNAP 13 — silently for some inputs), the geo files are partially corrupted and StaMPS hangs mid-PSI. PHASE pre-caches the required SRTM tiles into %USERPROFILE%/.snap/auxdata/dem/SRTM 3Sec/ automatically before each StampsExport run, eliminating that failure mode.

This requires the project AOI to be present in project.conf as LATMIN, LATMAX, LONMIN, LONMAX. If the keys are absent the pre-cache is skipped (with a warning) and StampsExport falls back to the standard SNAP auto-download path.

Verifying TRAIN on Windows

After the TRAIN Windows port, verify your install with these three checks.

1. Degradation path (TRAIN missing)

1. Open MATLAB. Run which('aps_linear'). Expected: empty string.
2. Launch PHASE_StaMPS. Tick "TRAIN atmospheric correction". Press Save, then Start.
3. Expected:
   • Warning id StaMPS:phase:trainNotAvailable in diary / smoketest.log.
   • The TRAIN checkbox STAYS TICKED (intentional — preserves intent for re-run).
   • Processing continues through STEP 1 → STEP 2 → export.
   • Output contains no Atmosphere_* columns.
   • Exit code 0.

2. Linear correction (a_linear)

1. Install TRAIN (Windows-patched fork): git clone https://github.com/pyccino/TRAIN.git C:/TRAIN.
2. In MATLAB: addpath(genpath('C:/TRAIN/matlab')); savepath.
3. Verify: which('aps_linear') returns C:\TRAIN\matlab\aps_linear.m.
4. Launch PHASE_StaMPS. Tick TRAIN. Set tropo_method='a_linear'. Save, Start.
5. Expected:
   • No degradation warning.
   • aps_linear runs (console output contains "loading the data").
   • Output contains Atmosphere_a_linear_AOI_PS.mat and Atmosphere_a_linear_*.csv.
   • Velocity values differ from a run with TRAIN unchecked.

Note on the Windows fork. pyccino/TRAIN (default branch main) is forked from dbekaert/TRAIN at the audited commit 6c93feb plus the following Windows-specific additions:

• get_gmt_version.m: actionable error on Windows when GMT is not on PATH (the upstream loop manipulates Linux-only library env vars).
• aps_gacos_files.m: replaces Unix & background launch with synchronous system() call on Windows (cmd.exe parses & differently).
• gacosDownloadDialog.m: helper that shows the GACOS request parameters in a copy-paste dialog (called from PHASE StaMPS).

Unix/Mac behavior is unchanged. Use upstream dbekaert/TRAIN directly on Linux/macOS if preferred.

3. GACOS correction (a_gacos) — optional, requires gacos.net data request

1. Same TRAIN install as above. Additionally install GMT for Windows and ensure C:\Program Files\GMT\bin (or your install dir) is on PATH; verify with gmt --version in a fresh terminal.
2. Launch PHASE_StaMPS. Tick TRAIN. Set tropo_method='a_gacos'. Save, Start.
3. Expected:
   • A "Download GACOS maps" window opens (the gacos.net site and the GACOS/ folder open automatically). It shows the request parameters (UTC, bounding box, dates) ready to copy into the form at gacos.net — select Binary grid as the file type.
   • Download the .tar.gz files from gacos.net, place them in GACOS/ (do not extract), then press Continue in the window.
   • MATLAB extracts/distributes .ztd files.
   • Output contains Atmosphere_a_gacos_AOI_PS.mat and Atmosphere_a_gacos_*.csv.

Updates

• August 2026 — PHASE 6.0: Promoted the standalone editable applications for preprocessing, StaMPS and geospatial modelling to production. Added the unified modern interface, integrated satellite maps and AOI drawing/import, in-app download and run monitoring, configurable processing controls, robust Windows runtime discovery, and the new installer layout. Archived the former .mlapp applications under legacy. Windows users should install from the release executable rather than cloning the repository.
• June 2026: Added the integrated download module for Sentinel-1. Completed the StaMPS porting to Windows; improved the StaMPS data export; created an installer for PHASE on Windows. Introduced the possibility to update the stack with newly available products abd update the pre-processing without re-starting from zero.
• April 2026: Added interactive geographic map GUI for automatic AOI sub-setting. Introduced meteorologically-aware master image selection using Open-Meteo API. Automated parameter metadata detection for StaMPS. Dropped legacy Python 2.7 support.
• March 2026: Introduced Module 2 for geospatial PSI data analysis with deterministic and stochastic modeling.
• September 2024: Added macOS compatibility to the preprocessing application and improved master error handling.

Planned updates

• Improve border constraints based on user selection.
• Introduce the handling of jumps in the displacement models.
• Add support for additional constellations.

Acknowledgments

Special thanks to Jose Manuel Delgado Blasco and Dr. Michael Foumelis for the snap2stamps¹ tool, and Prof. Andy Hooper for the StaMPS² development.

When using this software, please refer to:
Monti, R., & Rossi, L. (2025). PHASE: a Matlab-based software for the DInSAR PS processing. Geodesy and Cartography, 51(2), 88–99. https://doi.org/10.3846/gac.2025.21995

Footnotes

1. Foumelis, M., Delgado Blasco, J. M., Desnos, Y. L., Engdahl, M., Fernández, D., Veci, L. Lu, J. and Wong, C. “SNAP - StaMPS Integrated processing for Sentinel-1 Persistent Scatterer Interferometry”. In Geoscience and Remote Sensing Symposium (IGARSS), 2018 IEEE International, IEEE.
   ↩

2. Hooper, A., A multi-temporal InSAR method incorporating both persistent scatterer and small baseline approaches, Geophys. Res. Lett., 35, L16,302, doi:10.1029/2008GL03465, 2008. ↩