Running RRINGG

Overview

The RRINGG program is executed from the command line. It requires input InSAR products (velocity fields or time series) and GNSS data (velocities or displacements), and produces corrected or referenced outputs.

Two main operations are supported:

1. Correction of the InSAR velocity field

2. Referencing of InSAR time series in a global frame

Preprocessing (EPOS TCS only)

Note

Data from EPOS TCS are not directly usable in RRINGG. They must first be converted into an admissible format using the helper script ``csv2raster.py``.

The script takes a CSV file containing InSAR and GNSS parameters (e.g., mean velocity, temporal coherence, topography, LOS vector, and time series) and rasterizes them into a georeferenced grid.

Minimal usage example:

python src/tools/csv2raster.py \
    --time_series_csv_path input_data.csv \
    --output_path ./rasterized_output/

Main arguments of csv2raster.py:

csv2raster Command-Line Parameters

Argument	Description	Choices / Type	Default
-ts, --time_series_csv_path	Path to LOS Displacement Time Series (CSV)	<path>	—
-xr, --x_resolution	Pixel size in X (decimal degree)	<float>	None
-yr, --y_resolution	Pixel size in Y (decimal degree)	<float>	None
-nv, --nodata_value	Value for no-data pixels	<float>	NaN
-op, --output_path	Directory where rasters will be generated	<path>	—

Warning

During the CSV to raster conversion, an auxiliary file RRINGG_[NAME]_COORDINATES.txt is created. This file lists the geographic coordinates of the centers of all generated pixels.

Purpose:

It is intended to verify that the raster resolution has been set correctly.

• If the resolution is correct, each coordinate will correspond to the center of a unique pixel in the raster.

• If the resolution is incorrect, you may observe mismatches: * Too many or too few pixels compared to the CSV input. * Pixel centers not aligned with the expected grid.

Recommended Quality Check: Always load the generated raster together with the RRINGG_[NAME]_COORDINATES.txt file into a GIS software (e.g., QGIS) and perform a visual overlay check. A systematic quality control at this stage is strongly advised before proceeding with correction or referencing steps.

General Command Syntax

The basic syntax is:

python src/rringg.py [options]

Available options control the operation type, input/output files, geometry type, referencing method, and other processing details.

Input Parameters

The table below lists all command-line parameters.

RRINGG Command-Line Parameters

Argument	Description	Choices / Type	Default
-po, --processing_operation	Operation to perform	correction / referencing	correction
-gt, --geometry_type	Input geometry	ground / radar	ground
-vr, --velocity_raster_path	Path to LOS mean velocity raster (GeoTIFF)	<path> (required if correction)	—
-ts, --time_series_raster_path	Path to LOS displacement time series raster (GeoTIFF)	<path> (required if referencing)	—
-lo, --los_vectors	Path to custom LOS vector file (ASCII or GeoTIFF)	<path>	—
-lr, --lut_radar	Radar→ground geometry LUT (GeoTIFF, required if radar)	<path>	None
-lg, --lut_ground	Ground→radar geometry LUT (GeoTIFF, required if radar)	<path>	None
-rd, --reference_date	Reference date (YYYY-MM-DD) matching an acquisition date (only required for mean_velocity referencing)	<string>	None
-rm, --referencing_method	Referencing method	differential / mean_velocity	differential
-wd, --work_directory	Working directory	<path>	From config file
-ou, --output_directory	Output directory	<path>	From config file
-cd, --cache_directory	Cache directory for intermediate files	<path>	From config file
-sc, --scale	Bounding-box scale factor	<float>	Config project
-fi, --fitting	Plane fitting method	ransac / least_squares	From config project
-rs, --remove_stations	GNSS station codes to exclude	<str> (list)	None
-as, --additional_station	Directory containing additional GNSS time series	<path>	None
-vf, --velocity_file	CSV file with station velocity data	<path>	None
-hm, --hull_method	Method to determine convex hull of InSAR coverage	simple / complex	complex
-iv, --inverse_los	Convert LOS vector raster from NEU to ENU	flag	None

Example Workflows

1. Correction of Velocity Field (Ground Geometry)

python src/rringg.py \
  -po correction \
  -gt ground \
  -vr data/velocity.tiff \
  -lo data/los_vectors.tiff \
  -ou results/correction

Explanation: - -po correction → operation is velocity field correction - -gt ground → inputs are in ground geometry - -vr → velocity raster input - -lo → LOS vector file - -ou → directory where corrected raster is saved

Only these arguments are strictly necessary. Others can be specified if custom behavior is desired.

2. Referencing Time Series (Radar Geometry)

python src/rringg.py \
  -po referencing \
  -gt radar \
  -ts data/series.tiff \
  -lo data/los_vectors.tiff \
  -lr data/lut_radar.tiff \
  -lg data/lut_ground.tiff \
  -rd 2021-08-15 \
  -rm differential \
  -ou results/referencing

Explanation: - -po referencing → referencing of time series - -gt radar → input in radar geometry (requires LUT files) - -ts → displacement time series raster - -rd → reference date for mean velocity referencing - -rm differential → use differential referencing method - -ou → results are written to output folder

Notes and Best Practices

• Coordinate systems: Ensure all rasters (velocity, time series, LUTs) are in the same projection (typically geographic WGS84).

• LOS vectors: Must be consistent with InSAR data (satellite orbit, incidence angle).

• GNSS stations: Exclude noisy or discontinuous stations using --remove_stations.

• Referencing method: - mean_velocity → efficient, assumes linear motion. - differential → more accurate in presence of non-linear deformation.

• Performance: Plane fitting can be accelerated using ransac for outlier-robustness.