Quick Start¶

Overview¶

Three worked examples cover the main usage scenarios of RRINGG in correction mode, each with a different InSAR input format and GNSS data source.

Case	Scenario	InSAR input	GNSS source	Output directory
1	Case 1 — EPOS TCS CSV input, NGL GNSS	EPOS TCS CSV → GeoTIFF	NGL (online)	`data/output/case_INSAR_EPOS_TCSAT_GNSS_NGL`
2	Case 2 — GeoTIFF input, EPOS GNSS	GeoTIFF (ready to use)	EPOS (online)	`data/output/case_INSAR_GeoTIFF_GNSS_EPOS`
3	Case 3 — EPOS TCS CSV input, local GNSS file	EPOS TCS CSV → GeoTIFF	Local velocity file	`data/output/case_INSAR_EPOS_TCSAT_GNSS_Text`

Example Data¶

Download the example dataset:

Example datasets

Extract it at the project root. The expected layout is:

data/
├── input/
│   ├── GNSS_SARDAIGNE.txt                             # User-supplied GNSS velocity file (plain text)
│   ├── INSAR_EPOS_TCSAT_TUSCANY/                      # EPOS TCS InSAR dataset (CSV format)
│   │   └── DTSLOS_CNRIREA_20160714_20231030_ZII6.csv
│   ├── INSAR_GeoTIFF_BALKANS/                         # FLATSIM InSAR dataset (GeoTIFF format)
│   │   ├── CNES_MV-LOS_geo_16rlks.tiff
│   │   └── CNES_CosENU_geo_16rlks.tiff
│   └── INSAR_EPOS_TCSAT_SARDINIA/                     # EPOS TCS InSAR dataset (CSV format)
│       └── DTSLOS_CNRIREA_20160714_20250621_9JMU.csv
└── output/                                            # created automatically on first run

Case 1 — EPOS TCS CSV input, NGL GNSS¶

What this shows: the full workflow starting from an EPOS TCS Satellite CSV product. The first step converts it to GeoTIFF; the second runs the correction using online NGL MIDAS GNSS stations with RANSAC fitting — appropriate here because the Italian network is dense and contains stations of heterogeneous quality.

Note

This case uses the NGL data source. Set GNSSConfig.source = "NGL" in src/config.py before running. An internet connection is required for the initial download (subsequent runs use the local cache).

Step 1 — Convert CSV to GeoTIFF¶

python src/tools/csv2raster.py \
  -ts ./data/input/INSAR_EPOS_TCSAT_TUSCANY/DTSLOS_CNRIREA_20160714_20231030_ZII6.csv \
  -op ./data/input/INSAR_EPOS_TCSAT_TUSCANY/

This produces four GeoTIFFs (and a .meta sidecar for each) in the same directory:

File	Content
`CNRIREA_MV-LOS_geo_5rlks.tiff`	Mean LOS velocity (rad/yr, single band). Used by `rringg -vr`.
`CNRIREA_CosNEU_geo_5rlks.tiff`	LOS unit vectors (3 bands: North, East, Up cosines). Used by `rringg -lo`.
`CNRIREA_TCoh_geo_5rlks.tiff`	Temporal coherence (single band, 0–1).
`CNRIREA_DTs_geo_5rlks.tiff`	Displacement time series (rad, one band per acquisition date).

The pixel size is auto-detected from the point spacing of the CSV. The wavelength is read from the CSV metadata header and used to convert velocities and displacements from cm to radians.

Step 2 — Run correction¶

rringg \
  -po correction \
  -vr ./data/input/INSAR_EPOS_TCSAT_TUSCANY/CNRIREA_MV-LOS_geo_5rlks.tiff \
  -lo ./data/input/INSAR_EPOS_TCSAT_TUSCANY/CNRIREA_CosNEU_geo_5rlks.tiff \
  -lc NEU \
  -fi ransac \
  -ou ./data/output/case_INSAR_EPOS_TCSAT_GNSS_NGL \
  -rs BLGN00ITA COL100ITA AULL00ITA MODE00ITA MOPS00ITA \
      LOD000ITA SGIP00ITA VER200ITA VIRG00ITA PAMA00ITA \
      BRUG00ITA GENV00ITA GENO00ITA GENU00ITA GENA00ITA \
      CHRV00ITA LASP00ITA EMPO00ITA EMNS00ITA FIPR00ITA \
      IGMI00ITA CAL100ITA LEG200ITA GUAS00ITA AQNC00ITA \
      ENZA00ITA VARZ00ITA IGM200ITA CREA00ITA PARM00ITA \
      BOLG00ITA VIC300ITA

-lc NEU declares that the LOS bands produced by csv2raster from EPOS CSV files are in North–East–Up order. -rs excludes stations known to be unreliable in this area.

Case 2 — GeoTIFF input, EPOS GNSS¶

What this shows: the simpler workflow when the InSAR product is already a GeoTIFF (no conversion step), combined with online EPOS GNSS stations. Uses the default configuration — no edits to config.py required.

Note

An internet connection is required for the initial GNSS download (subsequent runs use the local cache).

rringg \
  -po correction \
  -vr ./data/input/INSAR_GeoTIFF_BALKANS/CNES_MV-LOS_geo_16rlks.tiff \
  -lo ./data/input/INSAR_GeoTIFF_BALKANS/CNES_CosENU_geo_16rlks.tiff \
  -lc ENU \
  -ou ./data/output/case_INSAR_GeoTIFF_GNSS_EPOS \
  -rs MTHO00GRC KRYO00GRC ANKY00GRC KITH00GRC \
      VASS00GRC KORO00GRC SKYR00GRC PAT000GRC

The CNES LOS raster stores components in East–North–Up order, so -lc ENU is used (no band reordering needed).

Case 3 — EPOS TCS CSV input, local GNSS file¶

What this shows: using a user-supplied GNSS velocity file (-vf) instead of an online source. This case is fully offline — no internet connection needed.

Step 1 — Convert CSV to GeoTIFF¶

python src/tools/csv2raster.py \
  -ts ./data/input/INSAR_EPOS_TCSAT_SARDINIA/DTSLOS_CNRIREA_20160714_20250621_9JMU.csv \
  -op ./data/input/INSAR_EPOS_TCSAT_SARDINIA/

Step 2 — Run correction¶

rringg \
  -po correction \
  -vr ./data/input/INSAR_EPOS_TCSAT_SARDINIA/CNRIREA_MV-LOS_geo_5rlks.tiff \
  -lo ./data/input/INSAR_EPOS_TCSAT_SARDINIA/CNRIREA_CosNEU_geo_5rlks.tiff \
  -vf ./data/input/GNSS_SARDAIGNE.txt \
  -lc NEU \
  -ou ./data/output/case_INSAR_EPOS_TCSAT_GNSS_Text \
  -rs MURA ANT2 CAGL CAGZ ARBU ORIM VISI CAEF UCAG SOLE IGLE

-vf points to a whitespace-delimited velocity file; RRINGG reads stations from it instead of querying an online GNSS service. Station codes in -rs are matched on the first four characters.

The GNSS_SARDAIGNE.txt file follows the standard RRINGG velocity file format (columns: marker centre frame latitude longitude height ve vn vu se sn su start end number).

The exclusion list retains five well-distributed stations (CAG1, LANU, MASI, SANL, VIZU) and drops the rest for the following reasons:

Station(s)	Reason for exclusion
`CAGL`, `CAGZ`	Series end in 2013, before the InSAR acquisition window (2016–2025); velocity estimate covers a completely different epoch.
`ARBU`, `ORIM`, `VISI`	Up-component uncertainty `su > 1 mm/yr`; unreliable LOS projection.
`CAEF`	Co-located with CAG1 (same site, ~0.001° apart) and `su = 1.08 mm/yr`; redundant with poorer quality.
`UCAG`	Same site as CAG1; keeping both would give that location double weight.
`IGLE`	Up velocity `vu = +0.87 mm/yr` (opposite sign to all other stations); series ends 2017.
`SOLE`	Post-correction LOS residual exceeds 1.5 mm/yr, inconsistent with the surrounding field; likely local effect not representative of the ramp.
`MURA`, `ANT2`	Known unreliable stations in this area (original exclusion).

Outputs¶

Each run produces 10 files in the output directory: one corrected raster, one metadata JSON, and eight diagnostic figures.

File	Description
`RRINGG_<velocity_raster_name>.tiff`	Corrected mean LOS velocity (same unit as the input raster).
`RRINGG_<meta_name>.json`	Full run metadata: software version, GNSS stations, fit parameters, and the exact command used (for reproducibility).
`RRINGG_{SRC}_SCATTER_BEFORE.png`	GNSS vs InSAR scatter plot before correction.
`RRINGG_{SRC}_SCATTER_AFTER.png`	GNSS vs corrected InSAR scatter plot.
`RRINGG_{SRC}_STATIONS_MAP_BEFORE.png`	Map of stations used, before fitting.
`RRINGG_{SRC}_STATIONS_MAP_AFTER.png`	Map of stations with residuals, after correction.
`RRINGG_{SRC}_RESIDUALS.png`	Per-station residual bar chart.
`RRINGG_{SRC}_RESIDUAL_HISTOGRAM.png`	Residual distribution before and after correction.
`RRINGG_{SRC}_FITTED_PLANE.png`	Fitted bias plane map.
`RRINGG_{SRC}_METRICS_SUMMARY.png`	Fitting quality metrics summary.

{SRC} is NGL for Case 1, EPOS for Cases 2 and 3.

Comparing with Reference Outputs¶

The example dataset includes pre-computed reference outputs in data/reference/. To check that your results match:

# Case 1
gdal_calc \
  -A ./data/output/case_INSAR_EPOS_TCSAT_GNSS_NGL/RRINGG_CNRIREA_MV-LOS_geo_5rlks.tiff \
  -B ./data/reference/case_INSAR_EPOS_TCSAT_GNSS_NGL/RRINGG_CNRIREA_MV-LOS_geo_5rlks.tiff \
  --outfile=diff_case1.tiff --calc="A-B"
gdalinfo -stats diff_case1.tiff

# Case 2
gdal_calc \
  -A ./data/output/case_INSAR_GeoTIFF_GNSS_EPOS/RRINGG_CNES_MV-LOS_geo_16rlks.tiff \
  -B ./data/reference/case_INSAR_GeoTIFF_GNSS_EPOS/RRINGG_CNES_MV-LOS_geo_16rlks.tiff \
  --outfile=diff_case2.tiff --calc="A-B"
gdalinfo -stats diff_case2.tiff

# Case 3
gdal_calc \
  -A ./data/output/case_INSAR_EPOS_TCSAT_GNSS_Text/RRINGG_CNRIREA_MV-LOS_geo_5rlks.tiff \
  -B ./data/reference/case_INSAR_EPOS_TCSAT_GNSS_Text/RRINGG_CNRIREA_MV-LOS_geo_5rlks.tiff \
  --outfile=diff_case3.tiff --calc="A-B"
gdalinfo -stats diff_case3.tiff

Use gdal_calc.py instead of gdal_calc if your GDAL version is older than 3.3. The mean of the difference raster should be close to zero and the standard deviation small relative to the signal range.

Minor numerical differences are expected for two reasons:

Online GNSS catalogues (Cases 1 and 2) are updated regularly; station velocities may shift slightly between runs.
RANSAC (Case 1) is stochastic: the random sampling may select a different inlier set, leading to small run-to-run variation in the fitted plane. The corrected raster should nonetheless be statistically indistinguishable from the reference.

Quick Start¶

Overview¶

Example Data¶

Case 1 — EPOS TCS CSV input, NGL GNSS¶

Step 1 — Convert CSV to GeoTIFF¶

Step 2 — Run correction¶

Case 2 — GeoTIFF input, EPOS GNSS¶

Case 3 — EPOS TCS CSV input, local GNSS file¶

Step 1 — Convert CSV to GeoTIFF¶

Step 2 — Run correction¶

Outputs¶

Comparing with Reference Outputs¶

rringg

Navigation

Related Topics