GRASS logo

NAME

i.sar.coregistration - Coregisters a Sentinel-1 TOPS SLC image onto a reference SLC image (geometric coregistration and ESD).

KEYWORDS

imagery, SAR, radar, Sentinel-1, SLC, TOPS, coregistration, interferometry, OpenCL

SYNOPSIS

i.sar.coregistration
i.sar.coregistration --help
i.sar.coregistration [-er] reference=basename secondary=basename output=basename [dem=name] [dem_height=string] [interpolation=string] [extra=string[,string,...]] [esd_coherence=float] [device=string] [platform=string] [nprocs=integer] [xcorr_window=range,azimuth[,range,azimuth,...]] [xcorr_threshold=float] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-e
Do not refine the azimuth coregistration by ESD
-r
Refine the range coregistration by cross-correlation
Estimates a constant range shift from the amplitudes of the coregistered bursts (SNAP Spectral Diversity range shift)
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

reference=basename [required]
Basename of the reference image imported by r.in.s1slc
E.g. s1_20230112_iw2_vv for maps s1_20230112_iw2_vv_i/_q, or their burst maps s1_20230112_iw2_vv_bNN_i/_q (-b import)
secondary=basename [required]
Basename of the secondary image imported by r.in.s1slc
output=basename [required]
Basename of the coregistered secondary maps (_i, _q, with the burst tags of the reference)
dem=name
Digital elevation model file (any GDAL raster, any CRS)
Default: heights of the annotation geolocation grid
dem_height=string
Height reference of the DEM
Options: geoid, ellipsoid
Default: geoid
geoid: Heights above the EGM96 geoid (e.g. SRTM, Copernicus DEM), converted to ellipsoidal heights
ellipsoid: Heights above the WGS84 ellipsoid
interpolation=string
Interpolation of the deramped secondary signal
sincN is a Hann-windowed sinc over N samples
Options: bilinear, bicubic, sinc6, sinc8, sinc16
Default: sinc8
extra=string[,string,...]
Additional maps in reference geometry
Options: azimuth_offset, range_offset, elevation
azimuth_offset: Secondary minus reference azimuth position (lines)
range_offset: Secondary minus reference range position (samples)
elevation: Ellipsoidal terrain height used (meters)
esd_coherence=float
Coherence threshold of the pixels used by ESD
Options: 0-1
Default: 0.3
device=string
Processing device
Options: auto, gpu, cpu, host
Default: auto
auto: First OpenCL GPU, else OpenCL CPU, else host
gpu: OpenCL GPU
cpu: OpenCL CPU device
host: C code on the host CPU (OpenMP)
platform=string
OpenCL platform name filter (case-insensitive substring)
nprocs=integer
Number of threads for parallel computing
0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
Default: 0
xcorr_window=range,azimuth[,range,azimuth,...]
Cross-correlation window for the range refinement (samples, lines)
One window at the centre of each burst, clipped to its valid area
Default: 512,512
xcorr_threshold=float
Minimum correlation peak of a burst used by the range refinement
Options: 0-1
Default: 0.1

Table of contents

DESCRIPTION

i.sar.coregistration resamples a secondary Sentinel-1 TOPS (IW, EW) Single Look Complex image onto the geometry of a reference image of the same sub-swath and relative orbit, so that the two can be combined pixel by pixel, e.g. by i.sar.interferometry. Both images are complex maps imported by r.in.s1slc (measure=complex), with their metadata.

The processing follows ESA SNAP (microwave toolbox) Back-Geocoding and Enhanced Spectral Diversity:

Input images

The reference and secondary options are basenames of images imported by r.in.s1slc, i.e. {output}_{swath}_{pol}:

Both images must be of the same kind. The module fails if a basename matches both kinds of maps.

Output

The coregistered secondary maps have the geometry of the reference maps and their names, the reference basename being replaced by output: {output}_i and {output}_q, or {output}_bNN_i and {output}_bNN_q for each reference burst. They are FCELL maps (null where the secondary image has no data) with the units, calibration, semantic label and timestamp of the secondary image.

The extra option adds maps in reference geometry: the azimuth and range offsets (secondary minus reference position, in lines of the secondary burst and in samples) and the ellipsoidal terrain height used (elevation), which i.sar.interferometry uses to remove the topographic phase.

Each output map carries a cell_misc/<map>/description.json file with the secondary product and annotation metadata (orbit, Doppler, bursts), the reference raster geometry and a coregistration section: reference and secondary maps and products, burst pairs, DEM, interpolation, the ESD result (shift, and phase, Doppler separation, weight and shift of each overlap) and the range refinement result (shift, and window, azimuth and range offsets and correlation peak of each burst).

DEM

The dem is any GDAL raster in any CRS covering the scene; it is reprojected to a WGS84 longitude/latitude grid by bilinear interpolation. Heights above the EGM96 geoid (dem_height=geoid, e.g. SRTM, Copernicus DEM) are converted to ellipsoidal heights with the PROJ grid us_nga_egm96_15.tif or egm96_15.gtx, which must be installed (e.g. projsync --file us_nga_egm96_15.tif). Pixels where the DEM has no data are null.

Processing device

The per-pixel work (height solution, deramping, interpolation) runs in the compute library libsarcoreg, on an OpenCL device or on the host CPU with OpenMP (device), the same code being compiled for both. OpenCL devices need double precision (cl_khr_fp64). The default, device=auto, uses OpenCL whenever a device is usable: the OpenCL GPUs first, then the OpenCL CPU devices; only without any, it falls back to the host OpenMP code, with a warning giving the reason. platform restricts OpenCL to the platforms whose name contains the given text. nprocs sets the number of OpenMP threads of the host path.

NOTES

The current project must be unprojected (XY), like the r.in.s1slc maps. The computational region is not used: every map is processed in full.

The range refinement estimates one constant shift for the whole image. It corrects timing errors, not the range offsets of the terrain relief: without a DEM over hilly terrain it only absorbs their mean. Burst IDs of products before IPF 3.4 are absent; pairing is then geometric only.

The module requires NumPy and the GDAL Python bindings, and a C compiler with OpenMP and the OpenCL headers and ICD loader to build libsarcoreg.

EXAMPLES

Import two acquisitions burst by burst and coregister the second one on the first, with the Copernicus DEM:

grass -c XY $HOME/grassdata/s1_sharjah -e
grass $HOME/grassdata/s1_sharjah/PERMANENT --exec bash

r.in.s1slc -b input=S1A_IW_SLC__1SDV_20230112T142507_20230112T142534_046752_059AD8_A55D.zip \
    output=s1_20230112 swath=IW2 polarization=VV bbox=55.35,25.25,55.50,25.40
r.in.s1slc -b input=S1A_IW_SLC__1SDV_20230124T...zip \
    output=s1_20230124 swath=IW2 polarization=VV bbox=55.35,25.25,55.50,25.40

i.sar.coregistration -r reference=s1_20230112_iw2_vv secondary=s1_20230124_iw2_vv \
    output=s1_20230124_co dem=copernicus_dem_30m.tif extra=elevation

The -r flag adds the range refinement by cross-correlation.

The ESD shift and the per-overlap estimates are in the metadata:

python3 -m json.tool $(g.gisenv get=GISDBASE)/$(g.gisenv get=LOCATION_NAME)/PERMANENT/cell_misc/s1_20230124_co_b04_i/description.json | grep -A3 '"esd"'

REFERENCES

SEE ALSO

i.sar.interferometry, r.in.s1slc

AUTHORS

Yann Chemin

SOURCE CODE

Available at: i.sar.coregistration source code (history)

Accessed: Sunday Nov 15 10:57:14 2026


Main index | Imagery index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual