PyGMTSAR Documentation

PyGMTSAR (Python InSAR) is a high-performance library for Sentinel-1 satellite interferometry. It is designed for both occasional users and experts, supporting workflows such as:

• SBAS (Small Baseline Subset)
• PSI (Persistent Scatterer Interferometry)
• PSI-SBAS

It automates the retrieval of Sentinel-1 SLC scenes, bursts, DEMs, and orbits, and provides tools for time-series analysis and 3D visualization. It is capable of handling both single interferograms and large-scale multi-year analyses involving thousands of datasets on standard commodity hardware.

InSAR.dev is the successor to PyGMTSAR. While PyGMTSAR processes single-polarization scenes and bursts along one orbital path, InSAR.dev is a pure Python NISAR/Sentinel-1 framework designed for massive scaling.

InSAR.dev separates the workflow into two distinct phases:

1. Data Preparation: Preparing SLC data (including geocoding, flat-earth, and topographic correction) and packaging it into cloud-ready bursts using the Zarr version 3 data storage format.
2. Interferometric Analysis: Performing core analysis on the prepared datasets.

This architecture allows InSAR.dev to scale to thousands of bursts across multiple polarizations and orbital paths.

If you are running PyGMTSAR inside a Docker container, you can upgrade the Python library using sudo (password-less).

To upgrade from within a Jupyter notebook cell, use:

import sys
!sudo {sys.executable} -m pip install -U pygmtsar

To build and push multi-architecture images (supporting both linux/amd64 and linux/arm64) to DockerHub, use the following buildx workflow. This process uses the pygmtsar.Dockerfile and tags the images with both the current date and the latest tag.

docker buildx create --name pygmtsar
docker buildx use pygmtsar
docker buildx inspect --bootstrap
docker buildx build . -f pygmtsar.Dockerfile \
    --platform linux/amd64,linux/arm64 \
    --tag pechnikov/pygmtsar:$(date "+%Y-%m-%d") \
    --tag pechnikov/pygmtsar:latest \
    --pull --push --no-cache
docker buildx rm pygmtsar

To verify the mathematical correctness of the calc_drho logic against the original GMTSAR C implementation, you can compile and run a standalone C test. This is useful for ensuring that the Python replacement maintains high precision.

1. Create a file named test_calc_drho.c containing the C implementation of calc_drho and a main function with test data.
2. Compile the test using gcc with the math library linked (-lm).
3. Run the resulting executable to compare output values.

# Compile the test
gcc test_calc_drho.c -o test_calc_drho -lm

# Run the test
./test_calc_drho

For a containerized environment that works on macOS, Linux, or Windows, you can use the official PyGMTSAR Docker images available on DockerHub.

docker pull pechnikov/pygmtsar

To compile C tests that utilize the GMTSAR FFT functions, you must link against both the gmt library and the fftw3f library. You also need to provide the include and library paths for your specific GMT and FFTW installations.

Example compilation command for Direct Transform:

gcc test_gmt_fft_2d.c -o test_gmt_fft_2d -I/opt/homebrew/Cellar/gmt/6.4.0_5/include/gmt/ -L/opt/homebrew/Cellar/gmt/6.4.0_5/lib -lgmt -L/opt/homebrew/Cellar/fftw/3.3.10_1/lib -lfftw3f

Example compilation command for Inverse Transform:

gcc test_gmt_ifft_2d.c -o test_gmt_ifft_2d -I/opt/homebrew/Cellar/gmt/6.4.0_5/include/gmt/ -L/opt/homebrew/Cellar/gmt/6.4.0_5/lib -lgmt -L/opt/homebrew/Cellar/fftw/3.3.10_1/lib -lfftw3f

To verify the C implementation of the apply_pspec (Goldstein filter) function, you can use the following steps to compile and run a test program. This test uses a 4x4 complex array and an alpha value of 0.8.

# Compile the test
gcc phasefilt_Goldstein.c -o test_phasefilt_Goldstein -lm

# Run the test
./test_phasefilt_Goldstein

You can build the Docker image locally using the provided pygmtsar.Dockerfile located in the repository.

Local Build Command: Use this command to build a local image tagged as pygmtsar:latest without using the cache.

docker build . -f pygmtsar.Dockerfile -t pygmtsar:latest --no-cache

To test the GMTSAR spline functions locally, follow these steps:

1. Obtain spline.c from the GMTSAR repository.
2. Create a test file (e.g., test_spline.c) containing the C code using spline_ and evals_.
3. Compile using gcc, linking your test file with spline.c.
4. Run the resulting executable.

# Compile
gcc -o test_spline test_spline.c spline.c

# Run
./test_spline

To upgrade the library using the terminal inside a running Docker container, execute:

sudo --preserve-env=PATH sh -c "pip3 install -U pygmtsar"

The phasediff utility logic can be implemented in Python using cmath or numpy to handle complex number operations. The core logic involves calculating a complex exponential (pshif), computing a complex conjugate (iptr2), and performing complex multiplication (intfp).

import cmath
import numpy as np

# Using cmath for scalar complex numbers
pshif = cmath.exp(pha)
# Using numpy for arrays of complex numbers
pshif = np.exp(pha)

# Conjugation
iptr2_conj = iptr2.conjugate() # if iptr2 is a numpy array
iptr2_conj = np.conj(iptr2)    # if iptr2 is a numpy array

# Complex multiplication
intfp_new = intfp * pshif