Scenarios

Orthorectify pairs of Sentinel-1 images on Sentinel-2 grid

In this scenario pairs of Sentinel-1 images are:

  • calibrated according to β0, γ0 or σ0 calibration

  • then orthorectified onto MGRS Sentinel-2 grid,

  • to be finally concatenated.

The unique elements in this scenario are:

All options go in a request configuration file (e.g. MyS1ToS2.cfg in workingdir). Important options will be:

Then running S1Tiling is as simple as:

cd workingdir
S1Processor MyS1ToS2.cfg

Eventually,

  • The S1 products will be downloaded in s1_images.

  • The orthorectified images will be generated in output.

  • Temporary files will be produced in tmp.

Note

S1 Tiling never cleans the tmp directory as its files are cached in between runs. This means you will have to watch this directory and eventually clean it.

Orthorectify pairs of Sentinel-1 images on Sentinel-2 grid with σ0T NORMLIM calibration

This scenario is a variation of the previous one. The difference lies in the calibration applied: it is the \(σ^0_{T}\) NORMLIM calibration described in [Small2011].

In S1Tiling, we have chosen to precompute Local Incidence Angle (LIA) maps on MGRS Sentinel-2 grid. Given a precise orbit file, a relative orbit and a MGRS tile, we directly compute the correction map on the selected Sentinel-2 tile.

That map will then be used for all series of pairs of Sentinel-1 images, of compatible orbit, β° calibrated and projected to the associated S2 tile.

Regarding options, the only difference with previous scenario are:

S1Tiling will then automatically take care of:

  • obtaining the precise orbit files (EOF), if none match the request parameters,

  • producing, or using existing, maps of sin(LIA) for each MGRS Sentinel-2 tiles – given an orbit,

  • producing intermediary products calibrated with β0 LUT.

sine(LIA)

Map of sine(LIA) on 33NWB descending orbit 007

Warning

If you wish to parallelize this scenario and to dedicate a different cluster node to each date – as recommended in “Process huge quantities of data” scenario, you will NEED to produce all the LIA maps beforehand. Otherwise, a same file may be concurrently written to from different nodes, and it will likely end up corrupted.

Note

This scenario requires NORMLIM σ° binaries. At the moment, NORMLIM σ0 binaries need to be compiled manually. Unless you use either S1Tiling docker images, or S1Tiling on CNES TREX cluster.

Note

This scenario requires to configure either cop_dataspace data provider in eodag configuration file, or to enter valid EarthData credentials in your ~/.netrc file (can be overridden with $NETRC).

Pre-produce maps of Local Incidence Angles for σ0T NORMLIM calibration

While S1Processor is able to produce the necessary LIA maps on the fly, it is not able to do so when parallelization is done manually over time ranges – as described in “Process huge quantities of data” scenario.

A dedicated program is provided to compute the LIA maps beforehand: S1LIAMap. It takes the exact same parameter files as S1Processor. A few options will be ignored though: calibration type, masking… But the following (non-obvious) options are mandatory:

cd workingdir
# Yes, the same file works!
S1LIAMap MyS1ToS2.cfg

Note

LIA maps are perfect products to be stored and reused.

Note

This scenario requires NORMLIM σ° binaries. At the moment, NORMLIM σ0 binaries need to be compiled manually. Unless you use either S1Tiling docker images, or S1Tiling on CNES TREX cluster.

Note

To run S1LIAMap from the official S1Tiling docker, use --lia as the first parameter to the docker execution (just before the request configuration file and other S1LIAMap related parameters). See Using S1LIAMap or S1IAMap with a docker.

Produce maps of Ellipsoid Incidence Angles

S1Tiling can produce maps of cosine, sine and/or tangent of the incidence angle over the WGS84 ellipsoid, thanks to S1IAMap program. See Incidence Angle data flow for more detailed information on the internal operation sequencing.

The typical use case is the following:

  1. Sine and cosine maps have been generated (with S1IAMap), and cached, for all MGRS Sentinel-2 tiles of interest.

  2. Series of calibrated and ortho-rectified Sentinel-1 data have been generated for a given calibration (typically σ°), and possibly made available on data providers like CNES’s Geodes.

  3. You can obtain the same product in other calibrations very quickly by applying the corrective sine/cosine map on the Sentinel-2 tiles product.

Relevant parameters (step 1)

It takes a very similar parameter file as S1Processor. Actually the same file can be used: only relevant parameters will be taken in account:

cd workingdir
# Yes, the same file works!
S1IAMap MyS1ToS2.cfg

Apply IA maps to σ° calibrated S1Tiling products (step 3)

When an input product has been σ° calibrated, products in other calibrations can be generated thanks to apply-calibration-map.sh. This is the recommended approach.

To convert a σ° calibrated product into:

  • a β° calibrated product, the σ° image needs to be divided by the sine map

    # Either by hand, with OTB, which leaves incorrect CALIBRATION metadata
otbcli_BandMath \
    -il  s1a_tile_polar_dir_087_time_sigma.tif sin_IA_s1a_tile_087.tif \
    -exp 'im1b1/im2b1' \
    -out s1a_tile_polar_dir_087_time_beta.tif
# Fix the incorrect metadata
gdal_edit.py -mo CALIBRATION=beta s1a_tile_polar_dir_087_time_beta.tif

# ----------------------------------------------------------------------
# Or, by hand, with gdal, but all metadata will be lost
gdal_calc.py \
    -A    s1a_tile_polar_dir_087_time_sigma.tif \
    -B    sin_IA_s1a_tile_087.tif \
    --calc "A/B"
    --out s1a_tile_polar_dir_087_time_beta.tif

# ----------------------------------------------------------------------
# Or, wrapped for batch application, with OTB, correct metadata
# RECOMMENDED approach
apply-calibration-map.sh -c beta --dirmap path/to_sinIA_files path/to/S1Tiling/products

  • a γ° calibrated product, the σ° image needs to be divided by the cosine map

    # Either by hand, with OTB, which leaves incorrect CALIBRATION metadata
otbcli_BandMath \
    -il  s1a_tile_polar_dir_087_time_sigma.tif cos_IA_s1a_tile_087.tif \
    -exp 'im1b1/im2b1' \
    -out s1a_tile_polar_dir_087_time_gamma.tif
# Fix the incorrect metadata
gdal_edit.py -mo CALIBRATION=gamma s1a_tile_polar_dir_087_time_beta.tif

# ----------------------------------------------------------------------
# Or, by hand, with gdal, but all metadata will be lost
gdal_calc.py \
    -A    s1a_tile_polar_dir_087_time_sigma.tif \
    -B    cos_IA_s1a_tile_087.tif \
    --calc "A/B"
    --out s1a_tile_polar_dir_087_time_gamma.tif

#-------------------- --------------------------------------------------
# Or, wrapped for batch application, with OTB, correct metadata
# RECOMMENDED approach
apply-calibration-map.sh -c gamma --dirmap path/to_cosIA_files path/to/S1Tiling/products

Notes

Note

Given the calibration is applied on the Sentinel-2 tile geometry, and not in the original Sentinel-1 image geometry, small precision differences may be observed between this approach and the one where the desired calibration is applied at the beginning of the processing.

Note

This scenario requires NORMLIM σ° binaries. At the moment, NORMLIM σ0 binaries need to be compiled manually. Unless you use either S1Tiling docker images, or S1Tiling on CNES TREX cluster.

Note

To run S1IAMap from the official S1Tiling docker, use --ia as the first parameter to the docker execution (just before the request configuration file and other S1IAMap related parameters). See Using S1LIAMap or S1IAMap with a docker.

Orthorectify pairs of Sentinel-1 images on Sentinel-2 grid with γ0T calibration

This scenario is a variation of the previous orthorectification scenario. The difference lies in the calibration applied: it is the \(γ^0_{T}\) calibration described in [Small2011].

In S1Tiling, we have chosen to precompute Gamma Area maps on Sentinel-2 grid.

Given a series of Sentinel-1 images to orthorectify on a Sentinel-2 grid, we select a pair of Sentinel-1 images to compute the associated Gamma Area maps in the geometry of these images. The maps are then projected, through orthorectification, on a Sentinel-2 tile, and eventually concatenated.

The resulting map will then be used for all series of orthorectified pairs of Sentinel-1 images that intersect the associated S2 tile, on the same orbit.

S1Tiling will automatically take care of:

  • producing, or using existing, γ area maps for each Sentinel-2 tiles – given an orbit and its direction,

  • producing intermediary products calibrated with σ0 LUT.

Relevant parameters

Regarding options, the only difference with previous scenario are:

Also, these specific options can be overridden:

Notes

Warning

If you wish to parallelize this scenario and dedicate a different cluster node to each date – as recommended in “Process huge quantities of data” scenario, you will NEED to produce all the γ areas maps beforehand. Otherwise, a same file may be concurrently written to from different nodes, and it will likely end up corrupted.

Note

This scenario requires GammaNaughtRTC binaries. At the moment, γ0T binaries need to be compiled manually. Unless you use either S1Tiling docker images, or S1Tiling on CNES TREX cluster.

Pre-produce Gamma Area maps for γ0T calibration

While S1Processor is able to produce the necessary γ area maps on the fly, it is not able to do so when parallelization is done manually over time ranges – as described in “Process huge quantities of data” scenario.

A different program is provided to compute the Gamma Area maps beforehand: S1GammaAreaMap. It takes the exact same parameter files as S1Processor. A few options will be ignored though: calibration type, masking… But the following (non-obvious) options are mandatory:

cd workingdir
# Yes, the same file works!
S1GammaAreaMap MyS1ToS2.cfg

Note

Gamma Area maps are perfect products to be stored and reused.

Note

This scenario requires GammaNaughtRTC binaries. At the moment, γ0T binaries need to be compiled manually. Unless you use either S1Tiling docker images, or S1Tiling on CNES TREX cluster.

Note

To run S1GammaAreaMap from the official S1Tiling docker, use --gamma_area as the first parameter to the docker execution (just before the request configuration file and other S1GammaAreaMap related parameters). See Using S1GammaAreaMap with a docker.

Warning

SARGammaAreaImageEstimation application is really RAM greedy. In order to work on ground coordinates, with a precision under 1 meter, we need to project Cartesian coordinates from S1 image onto DEM geometry in float64 precision. These files weight around 60 Giga Bytes, in memory, when DEM are 2x,2x resampled. The precision can be tuned with [Processing].creation_options.s1_on_dem option. This option will also permit to reduce the file footprint through compression.

Finally, to guarantee no artefact happens between streaming tiles, SARGammaAreaImageEstimation needs to load the entirety of these files; in order words, streaming would need to be disabled.

[Processing]
ram_per_process              = 70000
disable_streaming.gamma_area = True
creation_options.s1_on_dem   = float64 COMPRESS=DEFLATE, BIGTIFF=YES, PREDICTOR=3, TILED=YES, BLOCKXSIZE=1024, BLOCKYSIZE=1024

Generate masks on final products

Pixel masks of valid data can be produced in all S1Processor scenarios when the option generate_border_mask is True.

Process huge quantities of data

This use case concerns people that:

  • have a lot of images to process over many tiles and over a consequent time-range,

  • and have access to computing resources like HPC clusters

In that case, S1Tiling will be much more efficient if the parallelization is done time-wise. We recommend cutting the full time range in smaller subranges, and to distribute each subrange (with all S2 tiles) to a different node – with jobarrays for instances.

Warning

This scenario is not compatible with normlim and gamma_naught_rtc calibrations where the LIA or γ Area maps would be computed on-the-fly. For these calibrations, it’s imperative to precompute (and store the correction maps) before going massively parallel.

Use any other set of DEM inputs

By default, S1Tiling comes with a GPKG database that associates SRTM30 geometries to the SRTM tile filename.

In order to use other DEM inputs, we need:

  1. DEM files stored in [PATHS].dem_dir directory.
    The format of these DEM files needs to be supported by OTB/GDAL.

  2. A DEM (GPKG) database that holds a key (or set of keys) that enable(s) to locate/name DEM files associated to a DEM geometry.
    Set the [PATHS].dem_database key accordingly.
    For instance, eotile provides a couple of DEM databases for various types of DEM files.

  3. A naming scheme that will associate an identifier key from the DEM database to a DEM filename (located in [PATHS].dem_dir directory).
    Set the [PATHS].dem_format key accordingly.
    The default {id}.hgt associates the id key to STRM 30m DEM files.
    Using eotile DEM_Union.gpkg as DEM database, we could instead use:

    • {Product10}.tif for Copernicus 30 m DEM files, using Product10 key from the GPKG file.

    • {Product30}.tif for Copernicus 90 m DEM files, using Product30 key from the GPKG file.

  4. Make sure to use a Geoid file compatible with the chosen DEM. For instance S1Tiling is shipped with EGM96 Geoid with is compatible with SRTM. On the other hand, Copernicus DEM is related to EGM2008 (a.k.a. EGM08)