API Documentation

Configuration

`gdal_conf`	Stores GDAL configuration options for the current process.
`geocode_conf`	Returns a dictionary of additional parameters for pyroSAR.snap.util.geocode based on processing configurations provided by the config file.
`get_config`	Returns the content of a config file as a dictionary.

ERS_NRB.config.gdal_conf(config)[source]

Stores GDAL configuration options for the current process.

Parameters: config (dict) – Dictionary of the parsed config parameters for the current process.
Returns: Dictionary containing GDAL configuration options for the current process.
Return type: dict

ERS_NRB.config.geocode_conf(config)[source]

Returns a dictionary of additional parameters for pyroSAR.snap.util.geocode based on processing configurations provided by the config file.

Parameters: config (dict) – Dictionary of the parsed config parameters for the current process.
Returns: Dictionary of parameters that can be passed to pyroSAR.snap.util.geocode
Return type: dict

ERS_NRB.config.get_config(config_file, section_name='GENERAL')[source]

Returns the content of a config file as a dictionary.

Parameters

config_file (str) – Full path to the config file that should be parsed to a dictionary.
section_name (str, optional) – Section name of the config file that parameters should be parsed from. Default is ‘GENERAL’.

Returns

out_dict – Dictionary of the parsed config parameters.

Return type

dict

AOI Generation

no_aoi

param ids: List containing the scenes to process.

ERS_NRB.tile_extraction.description2dict(description)[source]

convert the HTML description field of the MGRS tile KML file to a dictionary.

Parameters: description (str) – the plain text of the Description field
Returns: a dictionary with keys ‘TILE_ID’, ‘EPSG’, ‘MGRS_REF’, ‘UTM_WKT’ and ‘LL_WKT’. The value of field ‘EPSG’ is of type integer, all others are strings.
Return type: dict

ERS_NRB.tile_extraction.extract_tile(kml, tile)[source]

Extract a MGRS tile from the global Sentinel-2 tiling grid and return it as a vector object.

Parameters

kml (str) – Path to the Sentinel-2 tiling grid kml file provided by ESA, which can be retrieved from: https://sentinels.copernicus.eu/web/sentinel/missions/sentinel-2/data-products
tile (str) – The MGRS tile ID that should be extracted and returned as a vector object.

Return type

spatialist.vector.Vector

ERS_NRB.tile_extraction.main(config, spacing)[source]

Parameters

config (dict) – Dictionary of the parsed config parameters for the current process.
spacing (int) – The target pixel spacing in meters, which is passed to pyroSAR.snap.util.geocode.

Returns

geo_dict (dict) – Dictionary containing geospatial information for each unique MGRS tile ID that will be processed.
align_dict (dict) – Dictionary containing ‘xmax’ and ‘ymin’ coordinates to use for the standardGridOriginX and standardGridOriginY parameters of pyroSAR.snap.util.geocode

ERS_NRB.tile_extraction.no_aoi(ids, spacing)[source]

Parameters

ids (list of pyroSAR.drivers.ID) – List containing the scenes to process.
spacing (int) – The target pixel spacing in meters, which is passed to pyroSAR.snap.util.geocode.

Returns

geo_dict (dict) – Dictionary containing geospatial information for each scene that will be processed.
align_dict (dict) – Dictionary containing ‘xmax’ and ‘ymin’ coordinates to use for the standardGridOriginX and standardGridOriginY parameters of pyroSAR.snap.util.geocode

ERS_NRB.tile_extraction.tiles_from_aoi(vectorobject, kml, epsg=None)[source]

Return a list of unique MGRS tile IDs that overlap with an area of interest (AOI) provided as a vector object.

Parameters

vectorobject (spatialist.vector.Vector) – The vector object to read.
kml (str) – Path to the Sentinel-2 tiling grid kml file provided by ESA, which can be retrieved from: https://sentinels.copernicus.eu/web/sentinel/missions/sentinel-2/data-products
epsg (int or list[int]) – define which EPSG code(s) are allowed for the tile selection.

Returns

tiles – A list of unique UTM tile IDs.

Return type

list[str]

Processing

`main`
`prepare_dem`	Downloads and prepares the chosen DEM for the NRB processing workflow.
`nrb_processing`	Finalizes the generation of Sentinel-1 NRB products after the main processing steps via pyroSAR.snap.util.geocode have been executed.

ERS_NRB.processor.main(config_file, section_name)[source]

ERS_NRB.processor.nrb_processing(config, scenes, datadir, outdir, tile, extent, epsg, wbm=None, multithread=True, compress='LERC_ZSTD', overviews=None, recursive=False)[source]

Finalizes the generation of Sentinel-1 NRB products after the main processing steps via pyroSAR.snap.util.geocode have been executed. This includes the following: - Converting all GeoTIFF files to Cloud Optimized GeoTIFF (COG) format - Generating annotation datasets in Virtual Raster Tile (VRT) format - Applying the NRB product directory structure & naming convention - Generating metadata in XML and STAC JSON formats

Parameters

config (dict) – Dictionary of the parsed config parameters for the current process.
scenes (list[str]) – List of scenes to process. Either an individual scene or multiple, matching scenes (consecutive acquisitions).
datadir (str) – The directory containing the datasets processed from the source scenes using pyroSAR.
outdir (str) – The directory to write the final files to.
tile (str) – ID of an MGRS tile.
extent (dict) – Spatial extent of the MGRS tile, derived from a spatialist.vector.Vector object.
epsg (int) – The CRS used for the NRB product; provided as an EPSG code.
wbm (str, optional) – Path to a water body mask file with the dimensions of an MGRS tile.
multithread (bool, optional) – Should gdalwarp use multithreading? Default is True. The number of threads used, can be adjusted in the config.ini file with the parameter gdal_threads.
compress (str, optional) – Compression algorithm to use. See https://gdal.org/drivers/raster/gtiff.html#creation-options for options. Defaults to ‘LERC_DEFLATE’.
overviews (list[int], optional) – Internal overview levels to be created for each GeoTIFF file. Defaults to [2, 4, 9, 18, 36]
recursive (bool, optional) – Find datasets recursively in the directory specified with the parameter datadir? Default is False.

Return type

None

ERS_NRB.processor.prepare_dem(id_list, config, threads, epsg, spacing, buffer=None)[source]

Downloads and prepares the chosen DEM for the NRB processing workflow.

Parameters

id_list (list[pyroSAR.drivers.ID]) – A list of pyroSAR metadata handlers for the current selection of scenes.
config (dict) – Dictionary of the parsed config parameters for the current process.
threads (int) – The number of threads to pass to pyroSAR.auxdata.dem_create.
epsg (int) – The CRS used for the NRB product; provided as an EPSG code.
spacing (int) – The target resolution to pass to pyroSAR.auxdata.dem_create.
buffer (float, optional) – A buffer in degrees to pass to pyroSAR.auxdata.dem_autoload.

Returns

dem_names – List of lists containing paths to DEM tiles for each scene to be processed.

Return type

list[list[str]]

Ancillary Functions

generate_unique_id

Returns a unique product identifier as a hexa-decimal string generated from the time of execution in isoformat.

get_max_ext

param boxes: List of vector objects.

set_logging

Set logging for the current process.

ERS_NRB.ancillary.create_acq_id_image(ref_tif, valid_mask_list, src_scenes, extent, epsg, driver, creation_opt, overviews)[source]

Creation of the acquisition ID image described in CARD4L NRB 2.8

Parameters

ref_tif (str) – Full path to a reference GeoTIFF file of the product.
valid_mask_list (list[str]) – A list of paths pointing to the datamask_ras files that intersect with the current MGRS tile.
src_scenes (list[str]) – A list of paths pointing to the source scenes of the product.
extent (dict) – Spatial extent of the MGRS tile, derived from a spatialist.vector.Vector object.
epsg (int) – The CRS used for the NRB product; provided as an EPSG code.
driver (str) – GDAL driver to use for raster file creation.
creation_opt (list[str]) – GDAL creation options to use for raster file creation. Should match specified GDAL driver.
overviews (list[int]) – Internal overview levels to be created for each raster file.

Return type

None

ERS_NRB.ancillary.create_data_mask(outname, valid_mask_list, src_files, extent, epsg, driver, creation_opt, overviews, overview_resampling, out_format=None, wbm=None)[source]

Creates the Data Mask file.

Parameters

outname (str) – Full path to the output data mask file.
valid_mask_list (list[str]) – A list of paths pointing to the datamask_ras files that intersect with the current MGRS tile.
src_files (list[str]) – A list of paths pointing to the SNAP processed datasets of the product.
extent (dict) – Spatial extent of the MGRS tile, derived from a spatialist.vector.Vector object.
epsg (int) – The CRS used for the NRB product; provided as an EPSG code.
driver (str) – GDAL driver to use for raster file creation.
creation_opt (list[str]) – GDAL creation options to use for raster file creation. Should match specified GDAL driver.
overviews (list[int]) – Internal overview levels to be created for each raster file.
overview_resampling (str) – Resampling method for overview levels.
out_format (str) – The desired output format of the data mask. The following options are possible: - ‘single-layer’: Individual masks will be merged into a single-layer raster file, where each mask is encoded as its initial bit-value. - ‘multi-layer’ (Default): Individual masks will be written into seperate bands encoded with 1 where the mask information is True and 0 where it is False, creating a multi-layer raster file.
wbm (str, optional) – Path to a water body mask file with the dimensions of an MGRS tile.

Return type

None

ERS_NRB.ancillary.create_rgb_vrt(outname, infiles, overviews, overview_resampling)[source]

Creates the RGB VRT file.

Parameters

outname (str) – Full path to the output RGB VRT file.
infiles (list[str]) – A list of paths.
overviews (list[int]) – Internal overview levels to be defined for the created VRT file.
overview_resampling (str) – Resampling method for overview levels.

Return type

None

ERS_NRB.ancillary.generate_unique_id(encoded_str)[source]

Returns a unique product identifier as a hexa-decimal string generated from the time of execution in isoformat. The CRC-16 algorithm used to compute the unique identifier is CRC-CCITT (0xFFFF).

Parameters: encoded_str (bytes) – A string that should be used to generate a unique id from. The string needs to be encoded; e.g.: ‘abc’.encode()
Returns: p_id – The unique product identifier.
Return type: str

ERS_NRB.ancillary.get_max_ext(boxes, buffer=None)[source]

Parameters

boxes (list[spatialist.vector.Vector objects]) – List of vector objects.
buffer (float, optional) – The buffer to apply to the extent.

Returns

max_ext – The maximum extent of the selected vector objects including buffer.

Return type

dict

ERS_NRB.ancillary.set_logging(config)[source]

Set logging for the current process.

Parameters: config (dict) – Dictionary of the parsed config parameters for the current process.
Returns: log_local – The log handler for the current process.
Return type: logging.Logger

ERS_NRB.ancillary.vrt_pixfun(src, dst, fun, scale=None, offset=None, options=None, overviews=None, overview_resampling=None)[source]

Creates a VRT file for the specified source dataset(s) and adds a pixel function that should be applied on the fly when opening the VRT file.

Parameters

src (str or list[str]) – The input dataset(s).
dst (str) – The output dataset.
fun (str) – A PixelFunctionType that should be applied on the fly when opening the VRT file. The function is applied to a band that derives its pixel information from the source bands. A list of possible options can be found here: https://gdal.org/drivers/raster/vrt.html#default-pixel-functions Furthermore, the option ‘decibel’ can be specified, which will implement a custom pixel function that uses Python code for decibel conversion (10*log10).
scale (int, optional) – The scale that should be applied when computing “real” pixel values from scaled pixel values on a raster band. Will be ignored if fun=’decibel’.
offset (float, optional) – The offset that should be applied when computing “real” pixel values from scaled pixel values on a raster band. Will be ignored if fun=’decibel’.
options (dict, optional) – Additional parameters passed to gdal.BuildVRT. For possible options see: https://gdal.org/python/osgeo.gdal-module.html#BuildVRTOptions
overviews (list[int], optional) – Internal overview levels to be created for each raster file.
overview_resampling (str, optional) – Resampling method for overview levels.

Return type

None

ERS_NRB.ancillary.vrt_relpath(vrt)[source]

Converts the paths to annotation datasets in a VRT file to relative paths.

Parameters: vrt (str) – Path to the VRT file that should be updated.
Return type: None

Metadata

Extraction

`calc_performance_estimates`	Calculates the performance estimates specified in CARD4L NRB 1.6.9 for all noise power images for the current MGRS tile.
`get_prod_meta`	Returns a metadata dictionary, which is generated from the ID of a product scene using a regular expression pattern and from a measurement GeoTIFF file of the same product scene using spatialist's Raster class.
`meta_dict`	Creates a dictionary containing metadata for a product scene, as well as its source scenes.
`vec_from_srccoords`	Creates a single spatialist.vector.Vector object from a list of footprint coordinates of source scenes.

ERS_NRB.metadata.extract.calc_performance_estimates(files, ref_tif)[source]

Calculates the performance estimates specified in CARD4L NRB 1.6.9 for all noise power images for the current MGRS tile.

Parameters

files (list[str]) – List of paths pointing to the noise power images the estimates should be calculated for.
ref_tif (str) – A path pointing to a product GeoTIFF file, which is used to get spatial information about the current MGRS tile.

Returns

out – Dictionary containing the calculated estimates for each available polarization.

Return type

dict

ERS_NRB.metadata.extract.convert_id_coordinates(coords, stac=False)[source]

Converts a list of coordinate pairs as retrieved by pyroSAR’s identify function to either envelop and center for usage in the XML metadata files or bbox and geometry for usage in STAC metadata files. The latter is returned if the optional parameter ‘stac’ is set to True, else the former is returned.

Parameters

coords (list[tuple(float, float)]) – List of coordinate pairs as retrieved by pyroSAR.drivers.identify from source scenes
stac (bool, optional) – If set to True, bbox and geometry are returned for usage in STAC Items. If set to False (default) envelop and center are returned for usage in XML metadata files.

Returns

envelop (str) – Acquisition footprint coordinates for the XML field ‘multiExtentOf’ in ‘eop:Footprint’
center (str) – Acquisition center coordinates for the XML field ‘centerOf’ in ‘eop:Footprint’

Notes

If stac=True the following parameters are returned instead of envelop and center:

bbox: list[float]: Acquisition bounding box for usage in STAC Items. Formatted in accordance with RFC 7946, section 5: https://datatracker.ietf.org/doc/html/rfc7946#section-5
geometry: GeoJSON Geometry Object: Acquisition footprint geometry for usage in STAC Items. Formatted in accordance with RFC 7946, section 3.1.: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1

ERS_NRB.metadata.extract.convert_spatialist_extent(extent)[source]

Converts the extent of a spatialist vector object to bbox and geometry as required for the usage in STAC Items: https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#item-fields

Parameters

extent (dict) – The extent of a vector object as returned by spatialist.vector.Vector.extent

Returns

bbox (list[float]) – Formatted in accordance with RFC 7946, section 5: https://datatracker.ietf.org/doc/html/rfc7946#section-5
geometry (GeoJSON Geometry Object) – Formatted in accordance with RFC 7946, section 3.1.: https://datatracker.ietf.org/doc/html/rfc7946#section-3.1

ERS_NRB.metadata.extract.get_prod_meta(product_id, tif, src_scenes)[source]

Returns a metadata dictionary, which is generated from the ID of a product scene using a regular expression pattern and from a measurement GeoTIFF file of the same product scene using spatialist’s Raster class.

Parameters

product_id (str) – The product ID (filename) of the product scene.
tif (str) – The paths to a measurement GeoTIFF file of the product scene.
src_scenes (list[str]) – A list of paths pointing to the source scenes of the product.

Returns

A dictionary containing metadata for the product scene.

Return type

dict

ERS_NRB.metadata.extract.get_uid_sid(filepath)[source]

Returns the unique identifier of a Sentinel-1 scene and a pyroSAR metadata handler generated using pyroSAR.drivers.identify

Parameters

filepath (str) – Filepath pointing to a Sentinel-1 scene.

Returns

uid (str) – The last four characters of a Sentinel-1 filename, which is the unique identifier of the scene.
sid (pyroSAR.drivers.ID subclass object) – A pyroSAR metadata handler for the scene generated with pyroSAR.drivers.identify.

ERS_NRB.metadata.extract.meta_dict(config, target, src_scenes, src_files, proc_time)[source]

Creates a dictionary containing metadata for a product scene, as well as its source scenes. The dictionary can then be utilized by metadata.xmlparser and metadata.stacparser to generate XML and STAC JSON metadata files, respectively.

Parameters

config (dict) – Dictionary of the parsed config parameters for the current process.
target (str) – A path pointing to the root directory of a product scene.
src_scenes (list[str]) – A list of paths pointing to the source scenes of the product.
src_files (list[str]) – A list of paths pointing to the SNAP processed datasets of the product.
proc_time (datetime.datetime) – The datetime object used to generate the unique product identifier from.

Returns

meta – A dictionary containing an extensive collection of metadata for product as well as source scenes.

Return type

dict

ERS_NRB.metadata.extract.vec_from_srccoords(coord_list)[source]

Creates a single spatialist.vector.Vector object from a list of footprint coordinates of source scenes.

Parameters: coord_list (list[list[tuple(float, float)]]) – List containing (for n source scenes) a list of coordinate pairs as retrieved by pyroSAR.drivers.identify
Return type: spatialist.vector.Vector object

STAC

`product_json`	Function to generate product-level metadata for an NRB target product in STAC compliant JSON format.
`source_json`	Function to generate source-level metadata for an NRB target product in STAC compliant JSON format.

ERS_NRB.metadata.stacparser.main(meta, target, tifs)[source]

Wrapper for source_json and product_json.

Parameters

meta (dict) – Metadata dictionary generated with metadata.extract.meta_dict
target (str) – A path pointing to the root directory of a product scene.
tifs (list[str]) – List of paths to all GeoTIFF files of the currently processed NRB product.

Return type

None

ERS_NRB.metadata.stacparser.product_json(meta, target, tifs)[source]

Function to generate product-level metadata for an NRB target product in STAC compliant JSON format.

Parameters

meta (dict) – Metadata dictionary generated with metadata.extract.meta_dict
target (str) – A path pointing to the root directory of a product scene.
tifs (list[str]) – List of paths to all GeoTIFF files of the currently processed NRB product.

Return type

None

ERS_NRB.metadata.stacparser.source_json(meta, target)[source]

Function to generate source-level metadata for an NRB target product in STAC compliant JSON format.

Parameters

meta (dict) – Metadata dictionary generated with metadata.extract.meta_dict
target (str) – A path pointing to the root directory of a product scene.

Return type

None