MintPy: from interferogram stack to deformation time series

Turning an interferogram stack into a deformation time series

Most InSAR workflows stop at producing individual interferograms, which leaves you with a stack of unwrapped phase files and a decision about what to do with them. MintPy takes that stack as its starting point. It accepts coregistered and unwrapped interferograms produced by ISCE, ARIA, FRInGE, HyP3, GMTSAR, SNAP, GAMMA or ROI_PAC, together with geometry files such as the DEM, the lookup table and incidence angle, and returns three dimensional ground surface displacement in the line-of-sight direction, two dimensions in space and one in time.

That framing decides who the package is for. The audience is deformation, volcano, tectonic and other remote sensing scientists who already have a working SAR processing chain and need a defensible way to invert an interferogram network into a velocity estimate and a displacement history. MintPy does not process raw SAR echoes. It begins downstream of coregistration, so the hard work of forming the interferograms stays outside this package.

What smallbaselineApp.py does between load_data and velocity

A run is defined by the text file smallbaselineApp.cfg rather than by command line flags, and that file lists default values for every step. Reading the pipeline in order shows what actually happens. The unwrapped interferograms are referenced to the same coherent pixel, chosen as the reference point. Phase closure is then calculated and unwrapping errors estimated when the template asks for it. The interferogram network is inverted into a time series, and temporal coherence is computed to evaluate the quality of that inversion. Later steps correct local oscillator drift for Envisat only, correct stratified tropospheric delay using either global atmospheric models or a phase-elevation-ratio approach, remove phase ramps when requested, correct DEM error, and finally estimate velocity.

Two details deserve attention. Tropospheric correction is not one algorithm but two selectable paths, and the choice changes the velocity field you end up with. The Envisat oscillator drift correction is tied to one mission, so a Sentinel-1 workflow never triggers it.

A first run on Fernandina volcano with Sentinel-1 data

Before touching MintPy you need an interferogram stack, which is the part of the pipeline this package does not handle. The fastest way to see the software end to end is the demo dataset from the Fernandina volcano in the Galapagos, built from Sentinel-1 data. The README gives these commands:

wget https://zenodo.org/record/3952953/files/FernandinaSenDT128.tar.xz
tar -xvJf FernandinaSenDT128.tar.xz
cd FernandinaSenDT128/mintpy
smallbaselineApp.py ${MINTPY_HOME}/docs/templates/FernandinaSenDT128.txt

After extraction you move into the mintpy directory inside the archive and point smallbaselineApp.py at the template that ships with the docs. The template tells MintPy where the interferograms, the DEM and the other geometry files live, which is why the demo passes a custom template instead of relying on the default smallbaselineApp.cfg. Results are plotted into the./pic folder of the run directory, so after the run you should find velocity and time series images there.

Inspecting the output with info.py, view.py and tsview.py

Reading results is done with separate scripts rather than more flags. The README lists the ones intended for a first look at the output:

info.py                    # check HDF5 file structure and metadata
view.py                    # 2D map view
tsview.py                  # 1D point time-series (interactive)
plot_coherence_matrix.py   # plot coherence matrix for one pixel (interactive)
plot_network.py            # plot network configuration of the dataset
plot_transection.py        # plot 1D profile along a line of a 2D matrix (interactive)
save_kmz.py                # generate Google Earth KMZ file in points or raster image
save_kmz_timeseries.py     # generate Google Earth KMZ file in points for time-series (interactive)

info.py is the one to run first, because it prints the structure and metadata of the HDF5 files the run produced. The entries marked interactive open a window rather than writing a file, which matters on a headless server where you will need a display or a different front end. save_kmz.py is the practical bridge to Google Earth for reporting.

Custom recipes and the mintpy Python module

Beyond the default template, MintPy works as a toolbox of independent utility scripts, and each one accepts -h or --help. The README points to scripts/compare_velocity_with_diff_tropo.sh as an example of a custom recipe that compares velocities estimated under different tropospheric delay corrections. This is the escape hatch for researchers whose corrections differ from the defaults, and it is the main reason to read smallbaselineApp.cfg in full before a campaign.

The same point applies one level down. The package is modularised into utility classes and functions under mintpy.objects and mintpy.utils, so your own analysis code can consume the outputs directly:

from mintpy.utils import readfile
ts_data, meta = readfile.read('timeseries_ERA5_ramp_demErr.h5')

The file name in that example encodes the processing chain behind it: ERA5 atmospheric correction, ramp removal and DEM error correction. The call returns the three dimensional time series matrix together with its metadata.

A research disclaimer, a beta status and a missing API site

Two limits are stated plainly. The README describes the package as research code provided as is, with no warranties of correctness and at your own risk, and the pyproject.toml classifier lists the development status as Beta. Second, there is no complete API document website, which the README itself flags as something contributors could add. The public surface is therefore whatever the source tree exposes, and it can change between releases without a compatibility promise.

On licensing, the pyproject.toml metadata declares GPL-3.0-or-later and the README badge says GPLv3+, while the repository listing reports the licence as Other because GitHub cannot classify the custom LICENSE file. Read the LICENSE file in the tree before redistributing anything derived from it.

Where MintPy is the wrong tool

There are concrete situations where this package is the wrong choice. If you hold raw Sentinel-1 or other SAR data and no interferogram stack, you need ISCE, ARIA, FRInGE, HyP3, GMTSAR, SNAP, GAMMA or ROI_PAC first, and MintPy does nothing with the raw echoes. If your question needs the perpendicular and vertical components rather than line-of-sight motion, you must combine ascending and descending tracks yourself. If your group wants a stable library API with documentation and a compatibility contract, the beta classification and the missing API site are reasons to budget time for reading source code.

Version naming is a smaller trap. The package was called PySAR before version 1.1.1, and from version 1.1.2 onward the name is MintPy, so older scripts and blog posts that reference PySAR point at an earlier layout.

Editorial conclusion

Adopt MintPy if you already produce unwrapped interferograms and need a time series inversion, a velocity estimate and inspection tools without writing your own network inversion. Do not expect it to replace the SAR processing chain, and do not treat it as a documented library API. Before you commit, check three things: that your stack matches one of the listed input formats, that the DEM and lookup table named in the template point at the right products, and that the LICENSE file in the tree matches the GPL-3.0-or-later identifier in pyproject.toml for your redistribution plans. The project is not archived and its last push was on 2026-10-20, with release v1.6.4 dated 2026-07-25.

Frequently asked questions

Official sources

1. insarlab/MintPy on GitHub
2. Issues
3. Project website
4. README
5. Releases