insarhub 0.4.0

English | 简体中文

InSARHub is a modular Python framework for automated InSAR and time-series processing.

The primary goal of this package is to provide a streamlined and user-friendly InSAR processing experience across multiple satellite products. InSARHub currently supports:

¹ Mixed — process pipeline that mixed with cloud processing and local processing

Table of Contents

• Web UI
• Installation
• Requirements
• Usage
• CLI
• Documentation

Web UI

InSARHub includes a self-hosted web interface that covers the full InSAR workflow — from scene search and download through interferogram processing to time-series analysis.

insarhub-app

Open http://localhost:8080 to access the UI.

All data stays on your machine — InSARHub runs a local FastAPI server and delivers a modern React frontend directly in your browser.

See the Web UI documentation for a full walkthrough.

Search & Download

Draw an AOI on the interactive map, set a date range and orbit filters, and search ASF for Sentinel-1 SLC stacks. InSARHub groups results by track/frame and downloads scenes and precise orbit files automatically.

Pair Selection & Quality Scoring

Build the interferogram network interactively. Pairs are colored by score so weak connections stand out immediately. Adjust temporal or perpendicular baseline limits and drag nodes/edges to refine the network live.

Processor

Submit the selected pairs to a cloud or local InSAR engine, run them locally or via SLURM (or inside Docker), monitor job status, download results, and retry failed jobs from the same panel.

Analyzer

Run time-series analysis step by step. Edit the network post-ingest, inspect diagnostic overview layers, and export velocity and displacement maps when done. Each analyzer is matched to the processor that generated the interferograms.

Results Viewer

Overlay the LOS velocity map on the basemap and click any pixel to plot its full displacement time series.

Installation

InSARHub can be installed using Conda:

conda install insarhub -c conda-forge

Pip:

conda install gdal -c conda-forge
pip install insarhub

From source:

git clone https://github.com/jldz9/InSARHub.git
cd InSARHub
conda env create -f environment.yml -n insarhub_dev
conda activate insarhub_dev
pip install -e .

The commands above install base InSARHub (HyP3 + MintPy). Local processing with ISCE2, ISCE3 + dolphin, or GMTSAR each needs its own toolchain added to the environment. See the Installation guide for the per-processor install steps.

Run in a container

Skip installing the heavy SAR toolchains locally and run each processor/analyzer inside Docker instead. Install base InSARHub (Conda/pip above), then pass --container to any processor or analyzer command — InSARHub pulls the matching image and runs the step inside it, mounting your workdir automatically:

insarhub processor -N ISCE2_S1 -w /data/p100_f466 --bbox 33.0 38.0 -120.0 -115.0 submit --container

Prebuilt images (ghcr.io/jldz9/insarhub-*:dev):

You can also run entirely inside a container instead of installing anything locally. See the Container Execution guide for details, and the Dockerfiles under docker/ to build your own.

Requirements

• Python >=3.11,<3.13
• numpy <2.0
• proj >=9.4
• gdal >=3.8
• sqlite >=3.44
• mintpy
• asf_search
• colorama
• contextily
• dem_stitcher
• hyp3_sdk
• rasterio >=1.4
• sentineleof
• pyproj
• fastapi
• uvicorn
• python-multipart

Usage

Downloader:

from insarhub import Downloader

• View available downloaders

  Downloader.available()
  

• Create downloader

  dl = Downloader.create('S1_SLC',
                          intersectsWith=[-113.05, 37.74, -112.68, 38.00],
                          start='2020-01-01',
                          end='2020-12-31',
                          relativeOrbit=100,
                          frame=466,
                          workdir='path/to/dir')
  

• Search

  results = dl.search()
  

• Filter

  filter_result = dl.filter(start='2020-02-01')
  

• Select interferogram pairs

  from insarhub.utils import plot_pair_network
  pairs, baselines, scene_bperp = dl.select_pairs(dt_max=96, pb_max=150)
  fig = plot_pair_network(pairs, baselines, scene_bperp)
  fig.show()
  

• Download

  dl.download()
  

Processor:

from insarhub import Processor

• View available processors

  Processor.available()
  

See the Processor table above for the full list. Example workflows for two engines:

HyP3 (cloud)

processor = Processor.create('Hyp3_S1', workdir='/your/work/path', pairs=pairs)
jobs = processor.submit()
jobs = processor.refresh()
processor.download()

ISCE2 (local / HPC)

Requires SLC .SAFE files already downloaded. Runs ISCE2 stackSentinel locally or submits each step to SLURM with hpc_mode=True.

from insarhub.config import ISCE2_S1_Config

cfg = ISCE2_S1_Config(
    workdir='/data/p100_f466',
    bbox=[33.0, 38.0, -120.0, -115.0],   # [S, N, W, E]
)
processor = Processor.create('ISCE2_S1', pairs=pairs, config=cfg)
processor.submit()        # starts background execution
processor.refresh()       # check step status

Analyzer

from insarhub import Analyzer

• View available analyzers

  Analyzer.available()
  

See the Analyzer table above for the full list. Example workflows:

HyP3 outputs

analyzer = Analyzer.create('Hyp3_Mintpy_SBAS', workdir="/your/work/dir")
analyzer.prep_data()   # unzip and clip HyP3 products
analyzer.run()         # full MintPy SBAS pipeline

ISCE2 outputs

analyzer = Analyzer.create('ISCE2_Mintpy_SBAS', workdir="/your/work/dir")
analyzer.prep_data()   # auto-discover ISCE2 interferograms and geometry
analyzer.run()         # full MintPy SBAS pipeline

CLI

InSARHub includes a command-line interface for running the full pipeline without writing Python code, suitable for HPC batch jobs and scripted workflows.

insarhub <command> [options]

End-to-end example — HyP3 (cloud)

# Search scenes and select interferogram pairs
insarhub downloader -N S1_SLC \
    --AOI -113.05 37.74 -112.68 38.00 \
    --start 2020-01-01 --end 2020-12-31 \
    --stacks 100:466 \
    -w /data/bryce \
    --select-pairs

# Submit pairs to HyP3 (auto-reads stack_p*_f*.json from workdir subfolders)
insarhub processor -N Hyp3_S1 -w /data/bryce submit

# Wait for jobs and download results automatically
insarhub processor -w /data/bryce watch

# Run MintPy time-series analysis
insarhub analyzer -N Hyp3_Mintpy_SBAS -w /data/bryce run

End-to-end example — ISCE2 (local / HPC)

# Search and download SLC scenes + orbits
insarhub downloader -N S1_SLC \
    --AOI -113.05 37.74 -112.68 38.00 \
    --start 2020-01-01 --end 2020-12-31 \
    --stacks 100:466 \
    -w /data/p100_f466 \
    --select-pairs --download --orbits

# Dry run to verify ISCE2 config before committing
insarhub processor -N ISCE2_S1 -w /data/p100_f466 \
    --bbox 33.0 38.0 -120.0 -115.0 submit --dry-run

# Run ISCE2 stackSentinel locally (background) or on SLURM (--hpc_mode True)
insarhub processor -N ISCE2_S1 -w /data/p100_f466 \
    --bbox 33.0 38.0 -120.0 -115.0 submit

# Monitor step progress
insarhub processor -N ISCE2_S1 -w /data/p100_f466 refresh

# Run MintPy time-series analysis on ISCE2 outputs
insarhub analyzer -N ISCE2_Mintpy_SBAS -w /data/p100_f466 run

Commands

Use insarhub <command> --help for full option details, or see the CLI Reference.

Documentation

InSARHub documentation