PyGMTSAR: automating Sentinel-1 interferometry in Python notebooks

The download step PyGMTSAR takes away from you

Interferometry projects usually stall before any science happens, on the boring part: pulling Sentinel-1 SLC scenes and bursts, orbit files, SRTM DEM data and land mask data, then converting heights to ellipsoidal heights via EGM96. PyGMTSAR automates that retrieval. The README states that the library automatically retrieves Sentinel-1 SLC scenes and bursts, DEMs and orbits, and that it computes interferograms and correlations, performs time series analysis, and provides 3D visualization.

That single sentence is the entire pitch, and it matters because the alternative is not really optional. A SAR workflow has dependencies that are painful to install and easy to get subtly wrong, and the library treats them as its problem rather than the user's. The result is described as a fully integrated InSAR project with minimal hassle, whether the target is a single interferogram or a multi-year analysis involving thousands of datasets.

SBAS, PSI and PSI-SBAS in a single library

The feature set named in the README covers SBAS, PSI, PSI-SBAS and more, so the choice of technique is a parameter of the analysis rather than a change of tool. The worked cases in the README show the range: a single interferogram comparison for the 2014 Fogo volcano eruption against a published geodetic modelling study, a La Cumbre eruption in Ecuador compared with an Instituto Geofisico report where the InSAR software used is left unspecified, and a 2017 earthquake case whose results are compared with outputs from GMTSAR, SNAP and GAMMA.

Two of those examples are about detecting change rather than measuring deformation velocity. The Kalkarindji flooding case in northern Australia uses correlation loss to identify flooded areas, and the Lake Sarez landslides case in Tajikistan is reproduced from a published finding. That breadth is the argument for the library: the same download and preprocessing machinery serves flood mapping, landslide detection, subsidence monitoring and earthquake deformation.

The Colab notebooks as the practical first run

The README does not give an installation command line, so the entry point it points to is Google Colab. The notebooks run on a Colab host with Ubuntu 22 and Python 3.10, install the library and its dependencies on that host, then fetch SLCs, orbit files, SRTM DEM data converted to ellipsoidal heights via EGM96, and land mask data, before running complete interferometry with final mapping and an interactive 3D map. The package is also published on PyPI and there is a Docker image, so a local or server install is possible for those who want it.

The notebooks are meant to be edited, not just run. The README notes you can modify the scene or burst names to analyse your own area of interest, and the Colab badges point at each notebook directly. One case, the Central Turkiye earthquakes of 2023, covers two consecutive Sentinel-1 scenes, or 56 bursts in total, which sets a realistic expectation for how long a run takes on a hosted notebook.

The successor project and the NetCDF problem

The most important paragraph in the README is the announcement at the top. InSAR.dev is described as the successor to PyGMTSAR, a pure Python NISAR and Sentinel-1 framework that uses the modern Zarr version 3 data storage format, avoiding the NetCDF related issues affecting PyGMTSAR.

That is a fairly blunt assessment of the project you are considering installing. It also explains the structural difference between the two: PyGMTSAR processes single polarization scenes and bursts along one orbital path, while InSAR.dev splits the workflow into two phases, preparing SLC data with geocoding, flat earth and topographic correction and packaging into cloud ready bursts, and then running the core interferometric analysis on those datasets. That two phase split is what scales to thousands of bursts across multiple polarizations and orbital paths. In other words, the successor exists because of a format problem and a scaling limit, and it addresses both.

What the repository layout reveals about scope

The tree tells you the project is broader than a single library. At the top level sit the package directory pygmtsar/, a notebooks/ directory, a docker/ directory, a ui/ directory, a book/ directory, pubs/, tests/, todo/ and an assets folder, plus a CITATION.cff file for citation metadata and a CNAME file, which indicates the documentation site is served from this repository.

The ui/ directory is worth a second look, because the README points to Imperial_Valley_2015.html as a self-contained web page holding the resulting InSAR velocity map for the Imperial Valley subsidence case. A self contained HTML map means results can be shared as a single file rather than a running service. The tests/ and todo/ directories are a plain signal of project hygiene, and the presence of a todo/ folder is a reminder that scope is still moving, which fits a project that has handed over its long term direction to a successor.

Where PyGMTSAR does not fit

The boundary is stated plainly in the README, and it is a hard one. PyGMTSAR handles single polarization scenes and bursts along one orbital path. Any study that needs several polarizations compared against each other, or that spans many orbital paths, is outside what this library is built for, and the README points to the successor design for that case rather than pretending the limitation is minor.

There is a second constraint that is about your workflow rather than the data. The examples are hosted notebooks, which is convenient for trying the library and awkward for a pipeline that must run unattended over a catalogue of scenes. Local, cloud server and Colab execution are all described as supported, but the README documents only the Colab path step by step, so moving a production job off a notebook means reading the developer guide in the project documentation and the Docker setup yourself.

How PyGMTSAR compares with GMTSAR, SNAP and GAMMA

The README names three established tools, so it is worth being precise about the difference. The Iran and Iraq earthquake example compares PyGMTSAR results with outputs from GMTSAR, SNAP and GAMMA, so those tools are the reference implementations against which the library is checked. The Imperial Valley example is different in kind: it is drawn from the GMTSAR project itself, taken from the GMTSAR download archive as the file S1A_Stack_CPGF_T173.tar.gz, titled Sentinel-1 TOPS Time Series.

The practical difference is one of delivery. GMTSAR, SNAP and GAMMA are established external programmes with their own install, their own conventions and their own desktop workflows; the examples here compare results, not packages. PyGMTSAR arrives as a Python library with automatic data retrieval and notebook examples, so the first result arrives in a browser session rather than in a workstation queue. For an expert who already runs one of the external tools well, that convenience may be redundant. For a student or an application developer who needs an interferogram rather than a software stack, it is the whole reason to use it.

Editorial conclusion

PyGMTSAR is a good fit for researchers and students who want reproducible Sentinel-1 interferograms, including SBAS and PSI time series, without installing and stitching together desktop SAR software. It is the wrong choice if you need multiple polarizations across orbital paths, and it is a project in transition, so read the announcement about InSAR.dev before committing. Verify first which version the Colab notebooks pin and whether the Docker image matches your own hardware and data volume.

Frequently asked questions

Official sources

1. AlexeyPechnikov/pygmtsar on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases