autoInSAR: Automated Sentinel-1 InSAR Dual-Mode Processing Pipeline

---

autoInSAR is a fully automated, dual-track InSAR processing pipeline designed for Sentinel-1 data.

It serves as a high-level wrapper around the ISCE2 (InSAR Scientific Computing Environment) software ecosystem, automating the entire lifecycle of interferometry—from data search and download to interferogram generation, baseline network analysis, and result visualization.

1. Dual-Mode Architecture

The pipeline operates in two distinct modes controlled by the --mode argument:

• [Mode A] pair (D-InSAR Mode): Designed for rapid co-seismic or single-pair deformation analysis. Wraps topsApp.py to generate final unwrapped phase, LOS displacement, and 2D publication-ready plots.
• [Mode B] stack (Time-Series Mode): Designed as the official upstream data feeder for the StaMPS-HPC framework. Wraps stackSentinel.py to prepare massive, perfectly coregistered SLC stacks, evaluates the spatiotemporal baseline network, and auto-recommends StaMPS processing parameters.

2. Features

The pipeline automates the following 8 steps dynamically based on the selected mode:

1. Search: Auto-query SLC images from ASF (default) or Copernicus Data Space Ecosystem. Supports event-based search (±12 days), manual pairs, or multi-year time-series stacks, with an independent search buffer controlled by --search_dlonlat.
2. Download: Sequential downloading of SLC data with ZIP integrity verification and auto-resume.
3. Orbit: Auto-fetch Precision (POEORB) or Restituted (RESORB) orbit files with robust time-window matching.
4. DEM: Auto-download and stitch SRTMGL1 DEM tiles covering the region of interest.
5. Config: Auto-generation of ISCE XML configs (tops.xml) OR sequential execution scripts (run_01 to run_13 for stack mode), with an independent processing ROI controlled by --roi_dlonlat.
6. Process: Execution of the standard topsApp.py workflow OR safe, sequential execution of the stack scripts.
7. Post-Processing:
   • (Pair): GDAL extraction, E/N/U decomposition, and Matplotlib 2D visualization.
   • (Stack): Spatiotemporal baseline network plotting and automated PS/SBAS mode recommendation.
8. Cleanup: Intelligent removal of bulky raw data (SLC/DEM/Orbit) and intermediate ISCE products to save massive disk space, retaining only final high-value results.

3. Prerequisites

• ISCE2 (v2.6+): Must be installed and loaded in your system (topsApp.py, stackSentinel.py, and dem.py must be in PATH).
• Linux: Recommended for ISCE2 compatibility.
• wget: Used for robust file downloading.
• Python Dependencies: pip install numpy matplotlib requests gdal
• Data Access Credentials: ASF downloads require NASA Earthdata credentials; Copernicus downloads require Copernicus Data Space Ecosystem (CDSE) credentials. See the credential setup below.

Data Access Credential Setup

autoInSAR supports two SLC data sources:

• ASF (--data_source asf, default): recommended for most standard Sentinel-1 workflows.
• Copernicus Data Space Ecosystem (--data_source copernicus): useful when the newest products, such as recent Sentinel-1D scenes, are available from Copernicus before they appear on ASF.

ASF / NASA Earthdata (~/.netrc)

Create or edit ~/.netrc:

nano ~/.netrc

Add your NASA Earthdata credentials using this format:

machine urs.earthdata.nasa.gov login YOUR_EARTHDATA_USERNAME password YOUR_EARTHDATA_PASSWORD

Then restrict file permissions:

chmod 600 ~/.netrc

Copernicus / CDSE (~/.cdse_credentials)

Create or edit ~/.cdse_credentials:

nano ~/.cdse_credentials

Add your Copernicus Data Space Ecosystem credentials using this format:

username=YOUR_COPERNICUS_USERNAME
password=YOUR_COPERNICUS_PASSWORD

Then restrict file permissions:

chmod 600 ~/.cdse_credentials

Do not commit real usernames or passwords to GitHub. The credential examples above are templates only.

4. Installation & Environment Setup

1. Clone the Repository & Make the Script Executable First, clone the repository to your local machine, and ensure the main script has execution permissions:

git clone https://github.com/limingjia92/autoInSAR.git
cd autoInSAR
chmod 755 autoInSAR.py
 

2. Add to System PATH (Recommended) To run autoInSAR from any working directory (e.g., your project folder), add the installation directory to your ~/.bashrc or ~/.zshrc file:

# Add this to the end of your ~/.bashrc
export PATH="/path/to/autoInSAR:$PATH"

Then, refresh your shell:

source ~/.bashrc

Now you can simply run autoInSAR.py --lon ... from any folder.

5. Usage Examples

The script is run via the command line. You must provide the spatial center (--lon, --lat) and temporal information.

[Mode A] Pair (D-InSAR)

1. Earthquake / Event Mode: Automatically searches for a pair of images ±12 days around a specific event date.

python autoInSAR.py --mode pair --lon 40.7 --lat 13.6 --event_date 20251117 --platform S1A

2. Manual Pair Mode: Manually specify the Reference and Secondary dates.

python autoInSAR.py --mode pair --lon 40.7 --lat 13.6 --reference_date 20251113 --secondary_date 20251125

[Mode B] Stack (Time-Series for StaMPS-HPC)

3. Time-Series Preparation: Prepare a massive stack of coregistered SLCs for StaMPS. Note: Time-series strictly requires processing on a single satellite track, so --rel_orbit is highly recommended/enforced.

python autoInSAR.py --mode stack --lon 40.7 --lat 13.6 --start_date 20200101 --end_date 20231231 --rel_orbit 14

4. Copernicus Data Source: Use Copernicus Data Space Ecosystem instead of ASF, which can be useful for newly available products such as recent Sentinel-1D SLCs.

python autoInSAR.py --data_source copernicus --mode stack --lon -67.9 --lat 10.5 --start_date 20260610 --end_date 20260627 --rel_orbit 106 --platform S1D

5. Separate Search Buffer and Processing ROI: Use a larger search buffer to ensure the correct SLCs are found, while keeping the actual ISCE processing region smaller.

python autoInSAR.py --mode pair --lon 40.7 --lat 13.6 --event_date 20251117 --search_dlonlat 0.5 --roi_dlonlat 0.2

6. Full-Extent Processing: Set --roi_dlonlat 0 to disable ROI clipping in ISCE configuration and pair-mode post-processing. This processes the full available overlap of the selected scenes.

python autoInSAR.py --mode pair --lon 40.7 --lat 13.6 --event_date 20251117 --search_dlonlat 0.5 --roi_dlonlat 0

[General] Running Specific Steps

You can run the pipeline step-by-step using the --step argument. Useful for debugging or re-running parts of the workflow.

python autoInSAR.py --mode stack --step clean

Options: search, download, orbit, dem, xml, isce, post, all (default), clean.

6. Arguments

Argument	Type	Required	Description
--mode	String	No	Execution mode: pair or stack. (Default: pair)
--data_source	String	No	SLC data source: asf or copernicus. (Default: asf). Use copernicus for CDSE products, including newly available Sentinel-1D scenes not yet mirrored by ASF.
--lon	Float	Yes	Center Longitude of the area of interest.
--lat	Float	Yes	Center Latitude of the area of interest.
--event_date	String	No*	[Pair Mode] Event date (YYYYMMDD). Auto-selects pair ±12 days.
--reference_date	String	No*	[Pair Mode] Manual Reference date (YYYYMMDD).
--secondary_date	String	No*	[Pair Mode] Manual Secondary date (YYYYMMDD).
--start_date	String	No**	[Stack Mode] Start date for time-series search (YYYYMMDD).
--end_date	String	No**	[Stack Mode] End date for time-series search (YYYYMMDD).
--platform	String	No	Satellite platform (Default: S1).
--rel_orbit	Int	No***	Specific Relative Orbit Number to filter results.
--search_dlonlat	Float	No	Search buffer size in degrees for ASF/Copernicus queries (Default: 0.2). This controls which SLC scenes are searched and listed.
--roi_dlonlat	Float	No	Processing/cropping ROI half-width in degrees. By default it equals --search_dlonlat, preserving the legacy behavior. Set --roi_dlonlat 0 to disable ROI clipping and process the full available scene overlap.
--dlonlat	Float	No	Deprecated compatibility alias for the old single-buffer behavior. Prefer --search_dlonlat and --roi_dlonlat for new runs.
--zip_check_backend	String	No	ZIP validation backend for Step 2: auto, python, or zipinfo (Default: auto). auto uses zipinfo if available, otherwise falls back to Python zipfile; all modes use fast central-directory checks.
--step	String	No	Execution step (Default: all).

* Pair Mode requires either --event_date OR both --reference_date and --secondary_date. ** Stack Mode requires both --start_date and --end_date. *** Time-Series (Stack Mode) MUST be conducted on a SINGLE relative orbit. Specifying --rel_orbit is highly recommended.

Search buffer vs. processing ROI: --search_dlonlat controls the spatial buffer used for SLC search. --roi_dlonlat controls the ISCE processing ROI and pair-mode post-processing crop. If --roi_dlonlat is omitted, it follows --search_dlonlat. If --roi_dlonlat 0 is used, the ROI line is omitted from tops.xml, the -b option is omitted from stackSentinel.py, and pair-mode post-processing keeps the full geocoded extent.

7. Output Structure

After a successful run and cleanup (Step 8), the output directory will be drastically simplified to retain only the most valuable data.

Stack Mode (Time-Series) Outputs:

├── process/
│   ├── run_* # ISCE2 stack generation scripts (01 to 13)
│   └── merged/                 
│       ├── SLC/                # Perfectly coregistered SLC stack (Ready for StaMPS-HPC)
│       ├── baselines/          # Baseline grids
│       └── geom_reference/     # Topographic geometry (lat, lon, hgt, shadow/layover masks)
└── results/
    ├── stack_baselines_PS_*.png    # PS baseline network plot with optimal master highlighted
    ├── stack_baselines_SBAS_*.png  # SBAS baseline network plot based on temporal neighbors
    └── stamps_hpc_commands.txt     # Auto-generated terminal commands for StaMPS-HPC

Pair Mode (D-InSAR) Outputs:

├── process/
│   ├── tops.xml                # ISCE2 configuration file
│   └── merged/                 # Filtered unwrapped phase, coherence, offsets, etc.
└── results/
    ├── los_disp.grd            # Line-of-Sight Displacement (m)
    ├── coherence.grd           # Interferometric Coherence
    ├── vec_E/N/U.grd           # 3D Decomposition vectors (East/North/Vertical)
    ├── offset_range.grd        # Pixel-offset in Range direction (m)
    ├── offset_azimuth.grd      # Pixel-offset in Azimuth direction (m)
    └── plot_asc_XX/            # Publication-ready PNG Visualizations

8. License

This project is licensed under the MIT License - see the source code for details.

Author: Mingjia Li Copyright (c) 2026 Mingjia Li