API Documentation
Configuration
Stores GDAL configuration options for the current process. |
|
Returns a dictionary of additional parameters for pyroSAR.snap.util.geocode based on processing configurations provided by the config file. |
|
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.
- 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.
Tile Extraction
|
|
Return a list of unique MGRS tile IDs that overlap with an area of interest (AOI) provided as a vector object. |
|
convert the HTML description field of the MGRS tile KML file to a dictionary. |
|
Extract a MGRS tile from the global Sentinel-2 tiling grid and return it as a vector object. |
- ERS_NRB.tile_extraction.description2dict(description)[source]
convert the HTML description field of the MGRS tile KML file to a dictionary.
- 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:
- ERS_NRB.tile_extraction.main(config, tr)[source]
- Parameters:
- 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:
Processing
Downloads and prepares the chosen DEM for the NRB processing workflow. |
|
Finalizes the generation of Sentinel-1 NRB products after the main processing steps via pyroSAR.snap.util.geocode have been executed. |
- ERS_NRB.processor.nrb_processing(config, scenes, datadir, outdir, tile, extent, epsg, wbm=None, multithread=True, 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.
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:
Ancillary Functions
Returns a unique product identifier as a hexa-decimal string generated from the time of execution in isoformat. |
|
|
|
Set logging for the current process. |
|
Returns a unique product identifier as a hexa-decimal string generated from the time of execution in isoformat. |
|
Creation of the color composite VRT file. |
|
Converts the paths to annotation datasets in a VRT file to relative paths. |
|
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. :param src: The input dataset(s). :type src: str or list[str] :param dst: The output dataset. :type dst: str :param fun: 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). :type fun: str :param relpaths: Should all SourceFilename XML elements with attribute @relativeToVRT="0" be updated to be paths relative to the output VRT file? Default is False. :type relpaths: bool, optional :param scale: 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'. :type scale: int, optional :param offset: 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'. :type offset: float, optional :param args: arguments for fun passed as PixelFunctionArguments. Requires GDAL>=3.5 to be read. :type args: dict, optional :param options: Additional parameters passed to gdal.BuildVRT. :type options: dict, optional :param overviews: Internal overview levels to be created for each raster file. :type overviews: list[int], optional :param overview_resampling: Resampling method for overview levels. :type overview_resampling: str, optional. |
- ERS_NRB.ancillary.check_scene_consistency(scenes)[source]
Check the consistency of a scene selection. The following pyroSAR object attributes must be the same:
sensor
acquisition_mode
product
frameNumber (data take ID)
- Parameters:
scenes (list[str or pyroSAR.drivers.ID]) –
- Raises:
- 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]
Creation of the color composite VRT file. :param outname: Full path to the output VRT file. :type outname: str :param infiles: A list of paths pointing to the linear scaled measurement backscatter files. :type infiles: list[str] :param overviews: Internal overview levels to be defined for the created VRT file. :type overviews: list[int] :param overview_resampling: Resampling method applied to overview pyramids. :type overview_resampling: str
- 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).
- ERS_NRB.ancillary.group_by_time(scenes, time=3)[source]
Group scenes by their acquisition time difference. :param scenes: a list of image names :type scenes: list[pyroSAR.drivers.ID or str] :param time: a time difference in seconds by which to group the scenes.
The default of 3 seconds incorporates the overlap between SLCs.
- Returns:
a list of sub-lists containing the file names of the grouped scenes
- Return type:
- 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:
- ERS_NRB.ancillary.vrt_pixfun(src, dst, fun, relpaths=None, scale=None, offset=None, args=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. :param src: The input dataset(s). :type src: str or list[str] :param dst: The output dataset. :type dst: str :param fun: 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).
- Parameters:
relpaths (bool, optional) – Should all SourceFilename XML elements with attribute @relativeToVRT=”0” be updated to be paths relative to the output VRT file? Default is False.
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’.
args (dict, optional) – arguments for fun passed as PixelFunctionArguments. Requires GDAL>=3.5 to be read.
options (dict, optional) – Additional parameters passed to gdal.BuildVRT.
overviews (list[int], optional) – Internal overview levels to be created for each raster file.
overview_resampling (str, optional) – Resampling method for overview levels.
Examples
linear backscatter as input: >>> src = ‘s1a-iw-nrb-20220601t052704-043465-0530a1-32tpt-vh-g-lin.tif’ decibel scaling I: use log10 pixel function and additional Scale parameter. Known to display well in QGIS, but Scale is ignored when reading array in Python. >>> dst = src.replace(‘-lin.tif’, ‘-log1.vrt’) >>> create_vrt(src=src, dst=dst, fun=’log10’, scale=10) decibel scaling II: use custom Python pixel function. Requires additional environment variable GDAL_VRT_ENABLE_PYTHON set to YES. >>> dst = src.replace(‘-lin.tif’, ‘-log2.vrt’) >>> create_vrt(src=src, dst=dst, fun=’decibel’) decibel scaling III: use dB pixel function with additional PixelFunctionArguments. Works best but requires GDAL>=3.5. >>> dst = src.replace(‘-lin.tif’, ‘-log3.vrt’) >>> create_vrt(src=src, dst=dst, fun=’dB’, args={‘fact’: 10})
Metadata
Extraction
Calculates the performance estimates specified in CARD4L NRB 1.6.9 for all noise power images for the current MGRS tile. |
|
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. |
|
Creates a dictionary containing metadata for a product scene, as well as its source scenes. |
|
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:
- Returns:
out – Dictionary containing the calculated estimates for each available polarization.
- Return type:
- 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:
- Returns:
A dictionary containing metadata for the product scene.
- Return type:
- 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:
STAC
Function to generate product-level metadata for an NRB target product in STAC compliant JSON format. |
|
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.
- 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.
XML
Function to generate product-level metadata for an NRB target product in OGC 10-157r4 compliant XML format. |
|
Function to generate source-level metadata for an NRB target product in OGC 10-157r4 compliant XML format. |
- ERS_NRB.metadata.xmlparser.main(meta, target, tifs)[source]
Wrapper for source_xml and product_xml.
- ERS_NRB.metadata.xmlparser.product_xml(meta, target, tifs)[source]
Function to generate product-level metadata for an NRB target product in OGC 10-157r4 compliant XML format.