Usage

Configuration

Usage of the S1_NRB package relies on a configuration file that needs to be set up by the user. The configuration file follows the INI format, which uses plain text to store properties as key-value pairs. INI files can be created and opened with any text editor. An example config.ini file for the S1_NRB package can be found here:

https://github.com/SAR-ARD/S1_NRB/blob/main/config.ini

The following provides an overview of the parameters the config.ini should contain and anything that should be considered when selecting their values:

  • mode

Options: all | nrb | snap

This parameter determines if the entire processing chain should be executed or only part of it.

  • aoi_tiles & aoi_geometry

The area of interest (AOI) for which S1-NRB products should be created.

aoi_tiles can be used to define the area of interest via MGRS tile IDs, which must be provided comma-separated (e.g., aoi_tiles = 32TNS, 32TMT, 32TMS). aoi_geometry defines the area of interest via a full path to a vector file supported by spatialist.vector.Vector. This option will automatically search for overlapping MGRS tiles and use these for processing. Both parameters are optional and can be set to None or left empty. aoi_tiles overrides aoi_geometry. If neither is defined, all tiles overlapping with the scene search result are processed.

  • mindate & maxdate

The time period to create S1-NRB products for. Allowed date formats are %Y-%m-%d and %Y-%m-%dT%H:%M:%S.

  • acq_mode

Options: IW | EW | SM

The acquisition mode of the source scenes that should be processed.

  • product

Options: GRD | SLC

The product of the source scenes that should be processed.

  • work_dir & scene_dir

Both need to be provided as full paths to existing directories. work_dir is the main directory in which any subdirectories and files are stored that are generated during processing. scene_dir will be searched recursively for any Sentinel-1 scenes using the regex pattern '^S1[AB].*\.zip$'.

  • rtc_dir, tmp_dir, nrb_dir, wbm_dir & log_dir

Processing S1-NRB products creates many intermediate files that are expected to be stored in separate subdirectories. The default values provided in the example configuration file linked above are recommended and will automatically create subdirectories relative to the directory specified with work_dir. E.g., nrb_dir = NRB will create the subdirectory /<work_dir>/NRB. Optionally, full paths to existing directories can be provided for all of these parameters.

  • db_file

Any Sentinel-1 scenes found in scene_dir will be stored in a database file created by pyrosar.drivers.Archive. With db_file either a full path to an existing database can be provided or it will be created in work_dir if only a filename is provided. E.g., db_file = scenes.db will automatically create the database file /<work_dir>/scenes.db.

  • kml_file

The Sentinel-2 Military Grid Reference System (MGRS) tiling system establishes the basis of the processing chain and a local reference file containing the respective tile information for processing S1-NRB products is needed. The official KML file provided by ESA can be retrieved here. With the kml_file parameter either a full path to this reference file can be provided or it is expected to be located in the directory provided with work_dir if only a filename is provided. E.g., the processor expects to find /<work_dir>/s2_grid.kml if kml_file = s2_grid.kml.

  • dem_type

Options: Copernicus 10m EEA DEM | Copernicus 30m Global DEM II | Copernicus 30m Global DEM | GETASSE30

The Digital Elevation Model (DEM) that should be used for processing.

Note that water body masks are not available for “GETASSE30”, and will therefore not be included in the product data mask. “Copernicus 10m EEA DEM” and “Copernicus 30m Global DEM II” (both include water body masks) are retrieved from the Copernicus Space Component Data Access system (CSCDA), which requires registration. The processor reads username and password from the environment variables DEM_USER and DEM_PASS if possible and otherwise interactively asks for authentication if one of these DEM options is selected.

  • gdal_threads

Temporarily changes GDAL_NUM_THREADS during processing. Will be reset after processing has finished.

  • measurement

Options: gamma | sigma

The backscatter measurement convention. Either creates gamma naught RTC (\(\gamma^0_T\)) or ellipsoidal sigma naught (\(\sigma^0_E\)).

  • annotation

A comma-separated list to define the annotation layers to be created. Supported options:

  • dm: data mask (four masks: not layover not shadow, layover, shadow, ocean water)

  • ei: ellipsoidal incident angle (needed for computing geolocation accuracy)

  • em: digital elevation model

  • id: acquisition ID image (source scene ID per pixel)

  • lc: RTC local contributing area

  • li: local incident angle

  • np: noise power (NESZ, per polarization)

  • gs: gamma-sigma ratio: sigma0 RTC / gamma0 RTC (ignored if measurement is not gamma)

  • sg: sigma-gamma ratio: gamma0 RTC / sigma0 ellipsoidal (ignored if measurement is not sigma)

Use one of the following to create no annotation layer:

  • annotation =

  • annotation = None

  • etad & etad_dir

Determines if the Extended Timing Annotation Dataset (ETAD) correction should be performed or not. If etad=True, etad_dir is searched for ETAD products matching the respective input SLC and a new SLC is created in tmp_dir, which is then used for all other processing steps. If etad=False, etad_dir will be ignored.

Sections

Configuration files in INI format can have different sections. Each section begins at a section name and ends at the next section name. The config.ini file used with the S1_NRB package should at least have a dedicated section for processing related parameters. This section is by default named [PROCESSING] (see example config file).

A reserved section [METADATA] may contain user-specific metadata to be written to the product’s metadata files. Currently supported fields:

  • access_url

  • licence

  • doi

  • processing_center

Users might create several processing sections in the same configuration file with parameter values that correspond to different processing scenarios (e.g., for different areas of interest). Note that each section must contain all necessary configuration parameters even if only a few are varied between the sections.

Command Line Interface

Once a configuration file has been created and all of its parameters have been properly defined, it can be used to start the processor using the command line interface (CLI) tool provided with the S1_NRB package.

The following options are currently available:

s1_nrb --help

Print a help message for the CLI tool.

s1_nrb --version

Print the processor version.

s1_nrb -c /path/to/config.ini

Start the processor using parameters defined in the default section of a config.ini file.

s1_nrb -c /path/to/config.ini -s SECTION_NAME

Start the processor using parameters defined in section SECTION_NAME of a config.ini file.