Fufiters

A combined InSAR, pixel-offsets workflow for measuring elevation change in Nepal using Sentinel-1 Synthethic Aperture Radar bursts

An application of v1.0 of this software is detailed in the following publication. Please consider reading it to understand the motivation behind this project as well as lengthy discussion of the methodology and products generated by the workflow. If you use or have benefitted from this software, please cite this:

Brencher, G., Henderson, S. T., and Shean, D. E.: Quantifying degradation of the Imja Lake moraine dam with fused InSAR and SAR feature tracking time series, The Cryosphere, 20, 67–86, https://doi.org/10.5194/tc-20-67-2026, 2026.

Design

Note: since this workflow was developed, ASF has continued to update hyp3-isce2 workflows, please consider if those meet your needs before using this repository!

Run a modified fork of hyp3-isce2 (https://github.com/relativeorbit/hyp3-isce2) to generate an inventory of inteferograms and pixel offset maps for a given Sentinel-1 burst. Workflows are written using Python scripts and GitHub Actions for concurrent batch processing on Microsoft Azure.

Resuable Workflows are composed to run processing of a single image pair, to processing all pairs over all available years in parallel (Sentinel-1 acquisitions start in October 2014).

At a minimum you need to select a Sentinel-1 Burst. You can search for Burst IDs using NASA Earthdata Search

Instructions

Setup

Install the GitHub actions CLI in order to easily run workflows from the command line. Alternatively you can manually run workflows from the 'Actions' repository tab.

Note: you must be a member of this GitHub organization to run these workflows, or you can fork this repository and add your own secrets (see below).

First for convience specify the repo where the workflows live for the gh commands:

export GH_REPO=relativeorbit/fufiters

Generate a single burst interferogram:

Use the full SLC names and specify the full burstId from those SLCs ([Track]_[Burst]_[Subswath]) that you want to process:

gh workflow run insar_pair.yml \
  -f reference=S1A_IW_SLC__1SDV_20190101T121401_20190101T121429_025284_02CBEB_65D7 \
  -f secondary=S1A_IW_SLC__1SDV_20190113T121401_20190113T121429_025459_02D234_3311 \
  -f burstId=012_023790_IW1 \
  -f environment=testing

Note: to select SLC names you can use https://search.asf.alaska.edu or use ASF's Python Client https://github.com/asfadmin/Discovery-asf_search

Optional inputs for all workflows:

nlooks=5x1 [20x4, 10x2]
polarization=VV [HH]
environment=production [testing]

Note: the "environment" input specifies GitHub Environments to direct outputs to different persistent storage locations such as per-project S3 Buckets.

Note: gh>=2.87 returns the run ID, so it can be convenient to "watch" progress. Just pipe the ID with | grep -oE '[0-9]+$' | xargs gh run watch

Run workflow locally (only works on Linux/MacOS Intel due to ISCE2 dependency)

You must first install a specific branch of hyp3-isce2, we recommend using pixi to setup a reproducible (locked) environment:

git clone https://github.com/relativeorbit/hyp3-isce2.git
pixi shell --frozen

cd /tmp
python -m hyp3_isce2 ++process insar_tops_fufiters \
  S1A_IW_SLC__1SDV_20190101T121401_20190101T121429_025284_02CBEB_65D7 \
  S1A_IW_SLC__1SDV_20190113T121401_20190113T121429_025459_02D234_3311 \
  --burstId 012_023790_IW1 \
  --looks 20x4 \
  --apply-water-mask False

Note: Unfortunately ISCE2 doesn't run on ARM-based Macs, but you can use the insar_pair.yml workflow to run on GitHub Actions and download the resulting interferogram artifacts to your local machine.

Generate a set of interferograms for a specific year

This workflow will do the search automatically and create 3 pairs for every acquisition date in a year (n+1, n+2, n+3 pairs).

gh workflow run insar_timeseries.yml \
  -f year=2023 \
  -f burstId=012_023790_IW1

Note: We created a convenience script to quickly search for burstIDs that contain a lon,lat point:

pixi run find-bursts -73.604 -49.669 --show-plot

Similarly, if you know a burstID and want a list of all SLCs, you can use:

pixi run find-slcs 135_289664_IW1

Generate a set of interferograms for all years

This workflow will do the search automatically and create 3 pairs for every date (n+1, n+2, n+3 pairs). It uses a 'matrix job' such that processing sets of interferograms for each year runs in parallel.

gh workflow run insar_pipeline.yml \
  -f burstId=012_023790_IW1

Generate a set of pixel offsets for all years

gh workflow run offsets_pipeline.yml \
  -f burstId=012_023790_IW1

Download artifacts

Note this particular workflow was run twice

gh run list -w insar_pipeline.yml

STATUS  TITLE                     WORKFLOW        BRANCH  EVENT              ID          ELAPSED   AGE
✓       121_258662_IW2 VV 5x1 3   InSAR_Pipeline  main    workflow_dispatch  8072975855  23m26s    about 15 hours ago
✓       121_258661_IW2 VV 5x1 2   InSAR_Pipeline  main    workflow_dispatch  8055416864  1h29m41s  about 1 day ago

gh run view 8072975855

# Download interferograms for a specific date
gh run download 8072975855 --dir /tmp/121_258662_IW2 --pattern "*20190813*"

# Specific artifact
gh run download 8072975855 --dir /tmp/121_258662_IW2 --name "20190720_20190813"

# All artifacts (may take a while!)
gh run download 8072975855 --dir /tmp/121_258662_IW2

Configuration

• The workflow requires the following Actions secrets:

  • AWS_ACCESS_KEY_ID & AWS_SECRET_ACCESS_KEY (for an IAM user that only has access to and S3 bucket)
  • EARTHDATA_USERNAME & EARTHDATA_PASSWORD (to download S1 Bursts from ASF DAAC https://urs.earthdata.nasa.gov)
  • ESA_USERNAME & ESA_PASSWORD (to download Sentinel-1 precise orbits from https://dataspace.copernicus.eu)

• Persistant COG outputs are stored in an AWS S3 Bucket (configured here https://github.com/relativeorbit/pulumi-fufiters).

Acknowledgments

University of Washington eScience Winter Incubator 2024