S1Tiling API

This section is intented for people who want to directly call S1Tiling code from their project instead of using the external programs S1Processor and S1LIAMap.

Entry points

s1_process

s1tiling.libs.api.s1_process(config_opt: str | Configuration, dl_wait: int = 2, dl_timeout: int = 20, searched_items_per_page: int = 20, nb_max_search_retries: int = 5, dryrun: bool = False, debug_otb: bool = False, debug_caches: bool = False, watch_ram: bool = False, debug_tasks: bool = False, cache_before_ortho: bool = False, lia_process=None) → Situation

Entry point to S1Tiling classic scenario and S1Tiling NORMLIM scenario of on demand Ortho-rectification of Sentinel-1 data on Sentinel-2 grid for all calibration kinds.

It performs the following steps:

1. Download S1 images from S1 data provider (through eodag)

   This step may be ignored if config_opt download option is false;

2. Calibrate the S1 images according to the calibration option from config_opt;

3. Orthorectify S1 images and cut their on geometric tiles;

4. Concatenate images from the same orbit on the same tile;

5. Build mask files;

6. Despeckle final images.

Parameters:

• config_opt – Either a request configuration file or a s1tiling.libs.configuration.Configuration instance.

• dl_wait – Permits to override EODAG default wait time in minutes between two download tries.

• dl_timeout – Permits to override EODAG default maximum time in mins before stop retrying to download (default=20)

• searched_items_per_page – Tells how many items are to be returned by EODAG when searching for S1 images.

• dryrun – Used for debugging: external (OTB/GDAL) application aren’t executed.

• debug_otb – Used for debugging: Don’t execute processing tasks in DASK workers but directly in order to be able to analyse OTB/external application through a debugger.

• debug_caches – Used for debugging: Don’t delete the intermediary files but leave them behind.

• watch_ram – Used for debugging: Monitoring Python/Dask RAM consumption.

• debug_tasks – Generate SVG images showing task graphs of the processing flows

• cache_before_ortho – Cutting, calibration and orthorectification are chained in memory unless this option is true. In that case, Cut and calibrated (aka “OrthoReady”) files are stored in %(tmp)/S1/ directory. Do not forget to regularly clean up this space.

Returns:

A nominal exit code depending of whether everything could have been downloaded and produced.

Return type:

s1tiling.libs.exits.Situation

Raises:

Error – A variety of exceptions. See below (follow the link).

s1_process_lia

s1tiling.libs.api.s1_process_lia(config_opt: str | Configuration, dl_wait: int = 2, dl_timeout: int = 20, searched_items_per_page: int = 20, nb_max_search_retries: int = 5, dryrun: bool = False, debug_otb: bool = False, debug_caches: bool = False, watch_ram: bool = False, debug_tasks: bool = False) → Situation

Entry point to LIA Map production scenario that generates Local Incidence Angle Maps on S2 geometry.

It performs the following steps:

1. Determine the S1 products to process

   Given a list of S2 tiles, we first determine the day that’ll the best coverage of each S2 tile in terms of S1 products.

   In case there is no single day that gives the best coverage for all S2 tiles, we try to determine the best solution that minimizes the number of S1 products to download and process.

2. Process these S1 products

Parameters:

• config_opt – Either a request configuration file or a s1tiling.libs.configuration.Configuration instance.

• dl_wait – Permits to override EODAG default wait time in minutes between two download tries.

• dl_timeout – Permits to override EODAG default maximum time in mins before stop retrying to download (default=20)

• searched_items_per_page – Tells how many items are to be returned by EODAG when searching for S1 images.

• dryrun – Used for debugging: external (OTB/GDAL) application aren’t executed.

• debug_otb – Used for debugging: Don’t execute processing tasks in DASK workers but directly in order to be able to analyse OTB/external application through a debugger.

• debug_caches – Used for debugging: Don’t delete the intermediary files but leave them behind.

• watch_ram – Used for debugging: Monitoring Python/Dask RAM consumption.

• debug_tasks – Generate SVG images showing task graphs of the processing flows

Returns:

A nominal exit code depending of whether everything could have been downloaded and produced.

Return type:

s1tiling.libs.exits.Situation

Raises:

Error – A variety of exceptions. See below (follow the link).

Configuration object

class s1tiling.libs.configuration.Configuration(config_file: str | Path, do_show_configuration=True)

This class handles the parameters from the cfg file

property dem_db_filepath: str

Get the DEMShapefile databe filepath

get_dems_covering_s2_tile(tile_name: str) → Dict

Retrieve the DEM associated to the specified S2 tile.

init_logger(config_log_dir: Path, mode=None) → None

Deported logger initialization function for projects that use their own logger, and S1Tiling through its API only.

Parameters:

mode – Option to override logging mode, if not found/expected in the configuration file.

property log_config

Property log

register_dems_related_to_S2_tiles(dems_by_s2_tiles: Dict[str, Dict]) → None

Workaround that helps caching DEM related information for later use.

show_configuration() → None

Displays the configuration

type_image

Type of images handled

Result (Situation) object

class s1tiling.libs.exits.Situation(nb_computation_errors: int, nb_search_failures: int, nb_download_failures: int, nb_download_timeouts: int)

Class to help determine the exit value from processing function.

The computed code to return will be:

• exits.TASK_FAILED if computation errors have been observed;

• exits.DOWNLOAD_ERROR if some input S1 products could not be downloaded;

• exits.OFFLINE_DATA if some input S1 products could not be downloaded in time because they were off-line.

• exits.OK if no issue has been observed

Exceptions

S1Tiling may raise the following exceptions:

class s1tiling.libs.exceptions.Error

Base class for all S1Tiling specific exceptions.

class s1tiling.libs.exceptions.CorruptedDataSAFEError(product: str, details: str | None, *args, **kwargs)

An empty data safe has been found and needs to be removed so it can be fetched again.

class s1tiling.libs.exceptions.DownloadS1FileError(tile_name: str, *args, **kwargs)

Error that signals problems to download images.

class s1tiling.libs.exceptions.NoS2TileError(*args, **kwargs)

Error that signals incorrect Sentinel-2 tile names.

class s1tiling.libs.exceptions.NoS1ImageError(*args, **kwargs)

No Sentinel-1 product has been found that intersects the requested Sentinel-2 tiles within the requested time range

class s1tiling.libs.exceptions.MissingDEMError(*args, **kwargs)

Cannot find all the DEM products that cover the requested Sentinel-2 tiles

class s1tiling.libs.exceptions.MissingGeoidError(geoid_file: str | Path, *args, **kwargs)

The geoid file is missing or the specified path is incorrect.

class s1tiling.libs.exceptions.InvalidOTBVersionError(reason: str, *args, **kwargs)

Error that signals OTB version incompatible with S1Tiling needs.

class s1tiling.libs.exceptions.MissingApplication(missing_apps, contexts: Set[str] | List[str], *args, **kwargs)

Some processing cannot be done because external applications cannot be executed. Likelly OTB and/or NORMLIM related applications aren’t correctly installed.