API Documentation

Configuration

gdal_conf	Stores GDAL configuration options for the current process.
snap_conf	Returns a dictionary of additional parameters for S1_NRB.snap.process() based on processing configurations provided by the config file.
get_config	Returns the content of a config.ini file as a dictionary.

S1_NRB.config.gdal_conf(config)

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

S1_NRB.config.get_config(config_file, proc_section='PROCESSING', **kwargs)

Returns the content of a config.ini file as a dictionary.

Parameters:

• config_file (str) – Full path to the config file that should be parsed to a dictionary.

• proc_section (str) – Section of the config file that processing parameters should be parsed from. Default is ‘PROCESSING’.

Returns:

out_dict – Dictionary of the parsed config parameters.

Return type:

dict

S1_NRB.config.get_keys(section)

get all allowed configuration keys

Parameters:

section ({'processing', 'metadata'}) – the configuration section to get the allowed keys for.

Returns:

a list of keys

Return type:

list[str]

S1_NRB.config.snap_conf(config)

Returns a dictionary of additional parameters for S1_NRB.snap.process() 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 S1_NRB.snap.process()

Return type:

dict

Processing

main	Main function that initiates and controls the processing workflow.

S1_NRB.processor.main(config_file, section_name='PROCESSING', debug=False, **kwargs)

Main function that initiates and controls the processing workflow.

Parameters:

• config_file (str) – Full path to a config.ini file.

• section_name (str) – Section name of the config.ini file that processing parameters should be parsed from. Default is ‘PROCESSING’.

• debug (bool) – Set pyroSAR logging level to DEBUG? Default is False.

• **kwargs – extra arguments to override parameters in the config file. E.g. acq_mode.

SNAP

core processing

process	Main function for SAR processing with SNAP.
geo	Range-Doppler geocoding.
grd_buffer	GRD extent buffering.
gsr	Gamma-sigma ratio computation for either ellipsoidal or RTC sigma nought.
mli	Multi-looking.
pre	General SAR preprocessing.
rtc	Radiometric Terrain Flattening.
sgr	Sigma-gamma ratio computation.
look_direction	Compute the per-pixel range look direction angle.

ancillary functions

find_datasets	Find processed datasets for a scene in a certain Coordinate Reference System (CRS).
get_metadata	Get processing metadata needed for ARD product metadata.
postprocess	Performs edge cleaning and sets the nodata value in the output ENVI HDR files.
nrt_slice_num	Compute a slice number for a scene acquired NRT Slicing mode.

S1_NRB.snap.find_datasets(scene, outdir, epsg)

Find processed datasets for a scene in a certain Coordinate Reference System (CRS).

Parameters:

• scene (str) – the file name of the SAR scene

• outdir (str) – the output directory in which to search for results

• epsg (int) – the EPSG code defining the output projection of the processed scenes.

Returns:

Either None if no datasets were found or a dictionary with the following keys and values pointing to the file names (polarization-specific keys depending on product availability):

• hh-g-lin: gamma nought RTC backscatter HH polarization

• hv-g-lin: gamma nought RTC backscatter HV polarization

• vh-g-lin: gamma nought RTC backscatter VH polarization

• vv-g-lin: gamma nought RTC backscatter VV polarization

• hh-s-lin: sigma nought ellipsoidal backscatter HH polarization

• hv-s-lin: sigma nought ellipsoidal backscatter HV polarization

• vh-s-lin: sigma nought ellipsoidal backscatter VH polarization

• vv-s-lin: sigma nought ellipsoidal backscatter VV polarization

• dm: layover-shadow data mask

• ei: ellipsoidal incident angle

• gs: gamma-sigma ratio

• lc: local contributing area (aka scattering area)

• ld: range look direction angle

• li: local incident angle

• sg: sigma-gamma ratio

• np-hh: NESZ HH polarization

• np-hv: NESZ HV polarization

• np-vh: NESZ VH polarization

• np-vv: NESZ VV polarization

Return type:

dict or None

S1_NRB.snap.geo(*src, dst, workflow, spacing, crs, geometry=None, buffer=0.01, export_extra=None, standard_grid_origin_x=0, standard_grid_origin_y=0, dem, dem_resampling_method='BILINEAR_INTERPOLATION', img_resampling_method='BILINEAR_INTERPOLATION', gpt_args=None, **bands)

Range-Doppler geocoding.

Parameters:

• src (list[str or None]) – variable number of input scene file names

• dst (str) – the file name of the target scene. Format is BEAM-DIMAP.

• workflow (str) – the target XML workflow file name

• spacing (int or float) – the target pixel spacing in meters

• crs (int or str) – the target coordinate reference system

• geometry (dict or spatialist.vector.Vector or str or None) – a vector geometry to limit the target product’s extent

• buffer (int or float) – an additional buffer in degrees to add around geometry

• export_extra (list[str] or None) –

  a list of ancillary layers to write. Supported options:

  • DEM

  • incidenceAngleFromEllipsoid

  • layoverShadowMask

  • localIncidenceAngle

  • projectedLocalIncidenceAngle

• standard_grid_origin_x (int or float) – the X coordinate for pixel alignment

• standard_grid_origin_y (int or float) – the Y coordinate for pixel alignment

• dem (str) – the DEM file

• dem_resampling_method (str) – the DEM resampling method

• img_resampling_method (str) – the SAR image resampling method

• gpt_args (list[str] or None) –

  a list of additional arguments to be passed to the gpt call

  • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

• bands – band ids for the input scenes in src as lists with keys bands<index>, e.g., bands1=['NESZ_VV'], bands2=['Gamma0_VV'], ...

See also

pyroSAR.snap.auxil.sub_parametrize, pyroSAR.snap.auxil.geo_parametrize

S1_NRB.snap.get_metadata(scene, outdir)

Get processing metadata needed for ARD product metadata.

Parameters:

• scene (str) – the name of the SAR scene

• outdir (str) – the directory to search for processing output

Return type:

dict

S1_NRB.snap.grd_buffer(src, dst, workflow, neighbors, buffer=100, gpt_args=None)

GRD extent buffering. GRDs, unlike SLCs, do not overlap in azimuth. With this function, a GRD can be buffered using the neighboring acquisitions. First, all images are mosaicked using the SliceAssembly operator and then subsetted to the extent of the main scene including a buffer.

Parameters:

• src (str) – the file name of the source scene in BEAM-DIMAP format.

• dst (str) – the file name of the target scene. Format is BEAM-DIMAP.

• workflow (str) – the output SNAP XML workflow filename.

• neighbors (list[str]) – the file names of neighboring scenes

• buffer (int) – the buffer size in meters

• gpt_args (list[str] or None) –

  a list of additional arguments to be passed to the gpt call

  • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

S1_NRB.snap.gsr(src, dst, workflow, src_sigma=None, gpt_args=None)

Gamma-sigma ratio computation for either ellipsoidal or RTC sigma nought.

Parameters:

• src (str) – the file name of the source scene. Both gamma and sigma bands are expected unless src_sigma is defined.

• dst (str) – the file name of the target scene. Format is BEAM-DIMAP.

• workflow (str) – the output SNAP XML workflow filename.

• src_sigma (str or None) – the optional file name of a second source product from which to read the sigma band.

• gpt_args (list[str] or None) –

  a list of additional arguments to be passed to the gpt call

  • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

S1_NRB.snap.look_direction(dim)

Compute the per-pixel range look direction angle. This adds a new layer to an existing BEAM-DIMAP product.

Steps performed:

• read geolocation grid points

• limit grid point list to those relevant to the image

• for each point, compute the range direction angle to the next point in range direction.

• interpolate the grid to the full image dimensions

Notes

• The interpolation depends on the location of the grid points relative to the image. Hence, by subsetting the image by an amount of pixels/lines different to the grid point sampling rate, the first and last points will no longer be in the first and last line respectively.

• The list might get very large when merging the scene with neighboring acquisitions using SliceAssembly and this longer list significantly changes the interpolation result. The difference in interpolation can be mitigated by reducing the list of points to those inside the image and those just outside of it.

Parameters:

dim (str) – a BEAM-DIMAP metadata file (extension .dim)

S1_NRB.snap.mli(src, dst, workflow, spacing=None, rlks=None, azlks=None, gpt_args=None)

Multi-looking.

Parameters:

• src (str) – the file name of the source scene

• dst (str) – the file name of the target scene. Format is BEAM-DIMAP.

• workflow (str) – the output SNAP XML workflow filename.

• spacing (int or float) – the target pixel spacing for automatic determination of looks using function pyroSAR.ancillary.multilook_factors(). Overridden by arguments rlks and azlks if they are not None.

• rlks (int or None) – the number of range looks.

• azlks (int or None) – the number of azimuth looks.

• gpt_args (list[str] or None) –

  a list of additional arguments to be passed to the gpt call

  • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

See also

pyroSAR.snap.auxil.mli_parametrize, pyroSAR.ancillary.multilook_factors

S1_NRB.snap.nrt_slice_num(dim)

Compute a slice number for a scene acquired NRT Slicing mode. In this mode both sliceNumber and totalSlices are 0 in the manifest.safe file. sliceNumber is however needed in function grd_buffer() for the SNAP operator SliceAssembly. The time from segmentStartTime to last_line_time is divided by the acquisition duration (last_line_time - first_line_time). totalSlices is set to 100, which is expected to exceed the maximum possible value.

Parameters:

dim (str) – the scene in BEAM-DIMAP format

S1_NRB.snap.postprocess(src, clean_edges=True, clean_edges_pixels=4)

Performs edge cleaning and sets the nodata value in the output ENVI HDR files.

Parameters:

• src (str) – the file name of the source scene. Format is BEAM-DIMAP.

• clean_edges (bool) – perform edge cleaning?

• clean_edges_pixels (int) – the number of pixels to erode during edge cleaning.

S1_NRB.snap.pre(src, dst, workflow, allow_res_osv=True, osv_continue_on_fail=False, output_noise=True, output_beta0=True, output_sigma0=True, output_gamma0=False, gpt_args=None)

General SAR preprocessing. The following operators are used (optional steps in brackets): Apply-Orbit-File(->Remove-GRD-Border-Noise)->Calibration->ThermalNoiseRemoval(->TOPSAR-Deburst)

Parameters:

• src (str) – the file name of the source scene

• dst (str) – the file name of the target scene. Format is BEAM-DIMAP.

• workflow (str) – the output SNAP XML workflow filename.

• allow_res_osv (bool) – Also allow the less accurate RES orbit files to be used?

• osv_continue_on_fail (bool) – Continue processing if no OSV file can be downloaded or raise an error?

• output_noise (bool) – output the noise power images?

• output_beta0 (bool) – output beta nought backscatter needed for RTC?

• output_sigma0 (bool) – output sigma nought backscatter needed for NESZ?

• output_gamma0 (bool) – output gamma nought backscatter needed?

• gpt_args (list[str] or None) –

  a list of additional arguments to be passed to the gpt call

  • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

See also

pyroSAR.snap.auxil.orb_parametrize

S1_NRB.snap.process(scene, outdir, measurement, spacing, kml, dem, dem_resampling_method='BILINEAR_INTERPOLATION', img_resampling_method='BILINEAR_INTERPOLATION', rlks=None, azlks=None, tmpdir=None, export_extra=None, allow_res_osv=True, clean_edges=True, clean_edges_pixels=4, neighbors=None, gpt_args=None, cleanup=True)

Main function for SAR processing with SNAP.

Parameters:

• scene (str) – The SAR scene file name.

• outdir (str) – The output directory for storing the final results.

• measurement ({'sigma', 'gamma'}) –

  the backscatter measurement convention:

  • gamma: RTC gamma nought (\(\gamma^0_T\))

  • sigma: RTC sigma nought (\(\sigma^0_T\))

• spacing (int or float) – The output pixel spacing in meters.

• kml (str) – Path to the Sentinel-2 tiling grid KML file.

• dem (str) – The DEM filename. Can be created with S1_NRB.dem.mosaic().

• dem_resampling_method (str) – The DEM resampling method.

• img_resampling_method (str) – The image resampling method.

• rlks (int or None) – The number of range looks.

• azlks (int or None) – The number of azimuth looks.

• tmpdir (str or None) – Path to a temporary directory for intermediate products.

• export_extra (list[str] or None) –

  A list of ancillary layers to create. Default None: do not create any ancillary layers. Options:

  • DEM

  • gammaSigmaRatio: \(\sigma^0_T / \gamma^0_T\)

  • sigmaGammaRatio: \(\gamma^0_T / \sigma^0_T\)

  • incidenceAngleFromEllipsoid

  • layoverShadowMask

  • localIncidenceAngle

  • NESZ: noise equivalent sigma zero

  • projectedLocalIncidenceAngle

  • scatteringArea

  • lookDirection: range look direction angle

• allow_res_osv (bool) – Also allow the less accurate RES orbit files to be used?

• clean_edges (bool) – Erode noisy image edges? See pyroSAR.snap.auxil.erode_edges(). Does not apply to layover-shadow mask.

• clean_edges_pixels (int) – The number of pixels to erode.

• neighbors (list[str] or None) – (only applies to GRD) an optional list of neighboring scenes to add a buffer around the main scene using function grd_buffer(). If GRDs are processed compeletely independently, gaps are introduced due to a missing overlap. If neighbors is None or an empty list, buffering is skipped.

• gpt_args (list[str] or None) –

  a list of additional arguments to be passed to the gpt call

  • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

• cleanup (bool) – Delete intermediate files after successful process termination?

Examples

>>> from S1_NRB import snap
>>> scene = 'S1A_IW_SLC__1SDV_20200103T170700_20200103T170727_030639_0382D5_6A12.zip'
>>> kml = 'S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml'
>>> dem = 'S1A_IW_SLC__1SDV_20200103T170700_20200103T170727_030639_0382D5_6A12_DEM_EEA10.tif'
>>> outdir = '.'
>>> spacing = 10
>>> rlks = 5
>>> azlks = 1
>>> export_extra = ['localIncidenceAngle', 'incidenceAngleFromEllipsoid',
>>>                 'scatteringArea', 'layoverShadowMask', 'gammaSigmaRatio']
>>> snap.process(scene=scene, outdir=outdir, spacing=spacing, kml=kml, dem=dem,
>>>              rlks=rlks, azlks=azlks, export_extra=export_extra)

S1_NRB.snap.rtc(src, dst, workflow, dem, dem_resampling_method='BILINEAR_INTERPOLATION', sigma0=True, scattering_area=True, dem_oversampling_multiple=2, gpt_args=None)

Radiometric Terrain Flattening.

Parameters:

• src (str) – the file name of the source scene

• dst (str) – the file name of the target scene. Format is BEAM-DIMAP.

• workflow (str) – the output SNAP XML workflow filename.

• dem (str) – the input DEM file name.

• dem_resampling_method (str) – the DEM resampling method.

• sigma0 (bool) – output sigma0 RTC backscatter?

• scattering_area (bool) – output scattering area image?

• dem_oversampling_multiple (int) – a factor to multiply the DEM oversampling factor computed by SNAP. The SNAP default of 1 has been found to be insufficient with stripe artifacts remaining in the image.

• gpt_args (list[str] or None) –

  a list of additional arguments to be passed to the gpt call

  • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

S1_NRB.snap.sgr(src, dst, workflow, src_gamma=None, gpt_args=None)

Sigma-gamma ratio computation.

Parameters:

• src (str) – the file name of the source scene. Both sigma and gamma bands are expected unless src_gamma is defined.

• dst (str) – the file name of the target scene. Format is BEAM-DIMAP.

• workflow (str) – the output SNAP XML workflow filename.

• src_gamma (str or None) – the optional file name of a second source product from which to read the gamma band.

• gpt_args (list[str] or None) –

  a list of additional arguments to be passed to the gpt call

  • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

ARD

calc_product_start_stop	Calculates the start and stop times of the ARD product.
create_acq_id_image	Creation of the Acquisition ID image.
create_data_mask	Creation of the Data Mask image.
create_rgb_vrt	Creation of the color composite VRT file.
create_vrt	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.
format	Finalizes the generation of Sentinel-1 Analysis Ready Data (ARD) products after SAR processing has finished.
get_datasets	Collect processing output for a list of scenes.
wind_normalization	Create wind normalization layers.

S1_NRB.ard.calc_product_start_stop(src_ids, extent, epsg)

Calculates the start and stop times of the ARD product. The geolocation grid points including their azimuth time information are extracted first from the metadata of each source SLC. These grid points are then used to interpolate the azimuth time for the lower right and upper left (ascending) or upper right and lower left (descending) corners of the MGRS tile extent.

Parameters:

• src_ids (list[pyroSAR.drivers.ID]) – List of ID objects of all source SLC scenes that overlap with the current MGRS tile.

• extent (dict) – Spatial extent of the MGRS tile, derived from a Vector object.

• epsg (int) – The coordinate reference system as an EPSG code.

Returns:

Start and stop time of the ARD product formatted as YYYYmmddTHHMMSS in UTC.

Return type:

tuple[str]

S1_NRB.ard.create_acq_id_image(outname, ref_tif, datasets, src_ids, extent, epsg, driver, creation_opt, overviews, dst_nodata)

Creation of the Acquisition ID image.

Parameters:

• outname (str) – Full path to the output data mask file.

• ref_tif (str) – Full path to any GeoTIFF file of the ARD product.

• datasets (list[dict]) – List of processed output files that match the source SLC scenes and overlap with the current MGRS tile.

• src_ids (list[pyroSAR.drivers.ID]) – List of ID objects of all source SLC scenes that overlap with the current MGRS tile.

• extent (dict) – Spatial extent of the MGRS tile, derived from a Vector object.

• epsg (int) – The CRS used for the ARD 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.

• dst_nodata (int or str) – Nodata value to write to the output raster.

S1_NRB.ard.create_data_mask(outname, datasets, extent, epsg, driver, creation_opt, overviews, overview_resampling, dst_nodata, product_type, wbm=None)

Creation of the Data Mask image.

Parameters:

• outname (str) – Full path to the output data mask file.

• datasets (list[dict]) – List of processed output files that match the source scenes and overlap with the current MGRS tile. An error will be thrown if not all datasets contain a key datamask. The function will return without an error if not all datasets contain a key dm.

• extent (dict) – Spatial extent of the MGRS tile, derived from a Vector object.

• epsg (int) – The coordinate reference system 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.

• dst_nodata (int or str) – Nodata value to write to the output raster.

• product_type (str) – The type of ARD product that is being created. Either ‘NRB’ or ‘ORB’.

• wbm (str or None) – Path to a water body mask file with the dimensions of an MGRS tile. Optional if product_type=’NRB’, mandatory if `product_type=’ORB’.

S1_NRB.ard.create_rgb_vrt(outname, infiles, overviews, overview_resampling)

Creation of the color composite VRT file.

Parameters:

• outname (str) – Full path to the output VRT file.

• infiles (list[str]) – A list of paths pointing to the linear scaled measurement backscatter files.

• overviews (list[int]) – Internal overview levels to be defined for the created VRT file.

• overview_resampling (str) – Resampling method applied to overview pyramids.

S1_NRB.ard.create_vrt(src, dst, fun, relpaths=False, scale=None, offset=None, dtype=None, args=None, options=None, overviews=None, overview_resampling=None)

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).

• relpaths (bool) – 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 or None) – 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 or None) – 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’.

• dtype (str or None) – the data type of the written VRT file; default None: same data type as source data. data type notations of GDAL (e.g. Float32) and numpy (e.g. int8) are supported.

• args (dict or None) – arguments for fun passed as PixelFunctionArguments. Requires GDAL>=3.5 to be read.

• options (dict or None) – Additional parameters passed to gdal.BuildVRT.

• overviews (list[int] or None) – Internal overview levels to be created for each raster file.

• overview_resampling (str or None) – Resampling method for overview levels.

Examples

linear gamma0 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})

S1_NRB.ard.format(config, product_type, scenes, datadir, outdir, tile, extent, epsg, wbm=None, dem_type=None, multithread=True, compress=None, overviews=None, kml=None, annotation=None, update=False)

Finalizes the generation of Sentinel-1 Analysis Ready Data (ARD) products after SAR processing has finished. This includes the following:

• Creating all measurement and annotation datasets in Cloud Optimized GeoTIFF (COG) format

• Creating additional annotation datasets in Virtual Raster Tile (VRT) format

• Applying the ARD product directory structure & naming convention

• Generating metadata in XML and JSON formats for the ARD product as well as source SLC datasets

Parameters:

• config (dict) – Dictionary of the parsed config parameters for the current process.

• product_type (str) – The type of ARD product to be generated. Options: ‘NRB’ or ‘ORB’.

• scenes (list[str]) – List of scenes to process. Either a single scene or multiple, matching scenes (consecutive acquisitions). All scenes are expected to overlap with extent and an error will be thrown if the processing output cannot be found for any of the scenes.

• datadir (str) – The directory containing the SAR 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 Vector object.

• epsg (int) – The CRS used for the ARD product; provided as an EPSG code.

• wbm (str or None) – Path to a water body mask file with the dimensions of an MGRS tile.

• dem_type (str or None) – if defined, a DEM layer will be added to the product. The suffix em (elevation model) is used. Default None: do not add a DEM layer.

• multithread (bool) – 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 or None) – Compression algorithm to use. See https://gdal.org/drivers/raster/gtiff.html#creation-options for options. Defaults to ‘LERC_DEFLATE’.

• overviews (list[int] or None) – Internal overview levels to be created for each GeoTIFF file. Defaults to [2, 4, 9, 18, 36]

• kml (str or None) – The KML file containing the MGRS tile geometries. Only needs to be defined if dem_type!=None.

• annotation (list[str] or None) –

  an optional list to select the annotation layers. Default None: create all layers if the source products contain the required input layers. Options:

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

  • ei: ellipsoidal incident angle

  • em: digital elevation model

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

  • lc: RTC local contributing area

  • ld: range look direction angle

  • li: local incident angle

  • np: noise power (NESZ, per polarization)

  • gs: gamma-sigma ratio: sigma0 RTC / gamma0 RTC

  • sg: sigma-gamma ratio: gamma0 RTC / sigma0 ellipsoidal

  • wm: OCN product wind model; requires OCN scenes via argument scenes_ocn

• update (bool) – modify existing products so that only missing files are re-created?

Returns:

Either the time spent executing the function in seconds or ‘Already processed - Skip!’

Return type:

str

S1_NRB.ard.get_datasets(scenes, datadir, extent, epsg)

Collect processing output for a list of scenes. Reads metadata from all source SLC/GRD scenes, finds matching output files in datadir and filters both lists depending on the actual overlap of each SLC/GRD valid data coverage with the current MGRS tile geometry. If no output is found for any scene the function will raise an error. To obtain the extent of valid data coverage, first a binary mask raster file is created with the name datamask.tif, which is stored in the same folder as the processing output as found by find_datasets(). Then, the boundary of this binary mask is computed and stored as datamask.gpkg (see function spatialist.vector.boundary()). If the provided extent does not overlap with this boundary, the output is discarded. This scenario might occur when the scene’s geometry read from its metadata overlaps with the tile but the actual extent of data does not.

Parameters:

• scenes (list[str]) – List of scenes to process. Either an individual scene or multiple, matching scenes (consecutive acquisitions).

• datadir (str) – The directory containing the SAR datasets processed from the source scenes using pyroSAR. The function will raise an error if the processing output cannot be found for all scenes in datadir.

• extent (dict) – Spatial extent of the MGRS tile, derived from a Vector object.

• epsg (int) – The coordinate reference system as an EPSG code.

Returns:

• ids (list[pyroSAR.drivers.ID]) – List of ID objects of all source SLC/GRD scenes that overlap with the current MGRS tile.

• datasets (list[dict]) – List of SAR processing output files that match each ID object of ids. The format is a list of dictionaries per scene with keys as described by e.g. S1_NRB.snap.find_datasets().

See also

S1_NRB.snap.find_datasets()

S1_NRB.ard.wind_normalization(src, dst_wm, dst_wn, measurement, gapfill, bounds, epsg, driver, creation_opt, dst_nodata, multithread, resolution=915)

Create wind normalization layers. A wind model annotation layer is created and optionally a wind normalization VRT.

Parameters:

• src (list[str]) – A list of OCN products as prepared by S1_NRB.ocn.extract()

• dst_wm (str) – The name of the wind model layer in the ARD product

• dst_wn (str or None) – The name of the wind normalization VRT. If None, no VRT will be created. Requires measurement to point to a file.

• measurement (str or None) – The name of the measurement file used for wind normalization in dst_wn. If None, no wind normalization VRT will be created.

• gapfill (bool) – Perform additional gap filling (S1_NRB.ocn.gapfill())? This is recommended if the Level-1 source product of measurement is GRD in which case gaps are introduced between subsequently acquired scenes.

• bounds (list[float]) – the bounds of the MGRS tile

• epsg (int) – The EPSG code of the MGRS tile

• 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.

• dst_nodata (float) – Nodata value to write to the output raster.

• multithread (bool) – Should gdalwarp use multithreading?

• resolution (int, optional) – The target pixel resolution in meters. 915 is chosen as default because it is closest to the OCN product resolution (1000) and still fits into the MGRS bounds (109800 % 915 == 0).

ETAD

process

Apply ETAD correction to a Sentinel-1 SLC product.

S1_NRB.etad.process(scene, etad_dir, out_dir, log)

Apply ETAD correction to a Sentinel-1 SLC product.

Parameters:

• scene (pyroSAR.drivers.ID) – The Sentinel-1 SLC scene.

• etad_dir (str) – The directory containing ETAD products. This will be searched for products matching the defined SLC.

• out_dir (str) – The directory to store results. The ETAD product is unpacked to this directory if necessary. Two new sub-directories SLC_original SLC_ETAD and are created, which contain the original unpacked scene and the corrected one respectively.

• log (logging.Logger) – A logger object to write log info.

Returns:

The corrected scene as a pyroSAR ID object.

Return type:

pyroSAR.drivers.ID

DEM

mosaic	Create a new scene-specific DEM mosaic GeoTIFF file.
prepare	Downloads DEM and WBM tiles and restructures them into the MGRS tiling scheme including re-projection and vertical datum conversion.

S1_NRB.dem.authenticate(dem_type, username=None, password=None)

Query the username and password. If None, environment variables DEM_USER and DEM_PASS are read. If they are also None, the user is queried interactively.

Parameters:

• dem_type (str) – the DEM type. Needed for determining whether authentication is needed.

• username (str or None) – The username for accessing the DEM tiles. If None and authentication is required for the selected DEM type, the environment variable ‘DEM_USER’ is read. If this is not set, the user is prompted interactively to provide credentials.

• password (str or None) – The password for accessing the DEM tiles. If None: same behavior as for username but with env. variable ‘DEM_PASS’.

Returns:

the username and password

Return type:

tuple[str or None]

S1_NRB.dem.mosaic(geometry, dem_type, outname, epsg=None, kml_file=None, dem_dir=None, username=None, password=None, threads=4)

Create a new scene-specific DEM mosaic GeoTIFF file. Can be created from MGRS-tiled DEMs as created by S1_NRB.dem.prepare() or ad hoc using pyroSAR.auxdata.dem_autoload() and pyroSAR.auxdata.dem_create(). In the former case the arguments username, password and threads are ignored and all tiles found in dem_dir are read. In the latter case the arguments epsg, kml_file and dem_dir are ignored and the DEM is only mosaiced and geoid-corrected.

Parameters:

• geometry (spatialist.vector.Vector) – The geometry to be covered by the mosaic.

• dem_type (str) – The DEM type.

• outname (str) – The name of the mosaic.

• epsg (int or None) – The coordinate reference system as an EPSG code.

• kml_file (str or None) – The KML file containing the MGRS tile geometries.

• dem_dir (str or None) – The directory containing the DEM MGRS tiles.

• username (str or None) – The username for accessing the DEM tiles. If None and authentication is required for the selected DEM type, the environment variable ‘DEM_USER’ is read. If this is not set, the user is prompted interactively to provide credentials.

• password (str or None) – The password for accessing the DEM tiles. If None: same behavior as for username but with env. variable ‘DEM_PASS’.

• threads (int) – The number of threads to pass to pyroSAR.auxdata.dem_create().

S1_NRB.dem.prepare(vector, dem_type, dem_dir, wbm_dir, kml_file, dem_strict=True, tilenames=None, threads=None, username=None, password=None)

Downloads DEM and WBM tiles and restructures them into the MGRS tiling scheme including re-projection and vertical datum conversion.

Parameters:

• vector (spatialist.vector.Vector) – The vector object for which to prepare the DEM and WBM tiles. CRS must be EPSG:4236.

• dem_type (str) – The DEM type.

• dem_dir (str or None) – The DEM target directory. DEM preparation can be skipped if set to None.

• wbm_dir (str or None) – The WBM target directory. WBM preparation can be skipped if set to None

• kml_file (str) – The KML file containing the MGRS tile geometries.

• dem_strict (bool) – strictly only create DEM tiles in the native CRS of the MGRS tile or also allow reprojection to ensure full coverage of the vector object in every CRS.

• tilenames (list[str] or None) – an optional list of MGRS tile names. Default None: process all overalapping tiles.

• threads (int or None) – The number of threads to pass to pyroSAR.auxdata.dem_create(). Default None: use the value of GDAL_NUM_THREADS without modification.

• username (str or None) – The username for accessing the DEM tiles. If None and authentication is required for the selected DEM type, the environment variable ‘DEM_USER’ is read. If this is not set, the user is prompted interactively to provide credentials.

• password (str or None) – The password for accessing the DEM tiles. If None: same behavior as for username but with env. variable ‘DEM_PASS’.

Examples

>>> from S1_NRB import dem
>>> from spatialist import bbox
>>> ext = {'xmin': 12, 'xmax': 13, 'ymin': 50, 'ymax': 51}
>>> kml = 'S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml'
# strictly only create overlapping DEM tiles in their native CRS.
# Will create tiles 32UQA, 32UQB, 33UUR and 33UUS.
>>> with bbox(coordinates=ext, crs=4326) as vec:
>>>     dem.prepare(vector=vec, dem_type='Copernicus 30m Global DEM',
>>>                 dem_dir='DEM', wbm_dir=None, dem_strict=True,
>>>                 kml_file=kml, threads=4)
# Process all overlapping DEM tiles to each CRS.
# Will additionally create tiles 32UQA_32633, 32UQB_32633, 33UUR_32632 and 33UUS_32632.
>>> with bbox(coordinates=ext, crs=4326) as vec:
>>>     dem.prepare(vector=vec, dem_type='Copernicus 30m Global DEM',
>>>                 dem_dir='DEM', wbm_dir=None, dem_strict=False,
>>>                 kml_file=kml, threads=4)

See also

S1_NRB.tile_extraction.tile_from_aoi

S1_NRB.dem.to_mgrs(tile, dst, kml, dem_type, overviews, tr, format='COG', create_options=None, threads=None, pbar=False)

Create an MGRS-tiled DEM file.

Parameters:

• tile (str) – the MGRS tile ID

• dst (str) – the destination file name

• kml (str) – The KML file containing the MGRS tile geometries.

• dem_type (str) – The DEM type.

• overviews (list[int]) – The overview levels

• tr (tuple[int or float]) – the target resolution as (x, y)

• format (str) – the output file format

• create_options (list[str] or None) – additional creation options to be passed to spatialist.auxil.gdalwarp().

• threads (int or None) – The number of threads to pass to pyroSAR.auxdata.dem_create(). Default None: use the value of GDAL_NUM_THREADS without modification.

• pbar (bool) –

OCN

extract	Extract an OCN product's image variable and write it to a new GeoTIFF file.
gapfill	Fill gaps of an image file using GDAL.

S1_NRB.ocn.extract(src, dst, variable)

Extract an OCN product’s image variable and write it to a new GeoTIFF file. Coordinates are extracted from the corresponding latitude and longitude image variables and the corner coordinates written as ground control points (GCPs) to the output file.

Parameters:

• src (str) – path to OCN product SAFE folder

• dst (str) – the name of the GeoTIFF file to write

• variable (str) – name of the layer to extract from the OCN product, e.g. owiNrcsCmod

S1_NRB.ocn.gapfill(src, dst, md, si)

Fill gaps of an image file using GDAL.

Parameters:

• src (str) – the source image file

• dst (str) – the destination image file with gaps filled

• md (int) – the interpolation maximum distance

• si (int) – the number of smoothing iterations

See also

osgeo.gdal.FillNodata

Tile Extraction

aoi_from_scene	Get processing AOIs for a SAR scene.
aoi_from_tile	Extract one or multiple MGRS tiles from the global Sentinel-2 tiling grid and return it as a Vector object.
description2dict	Convert the HTML description field of the MGRS tile KML file to a dictionary.
tile_from_aoi	Return a list of MGRS tile IDs or vector objects overlapping one or multiple areas of interest.

S1_NRB.tile_extraction.aoi_from_scene(scene, kml, multi=True, percent=1)

Get processing AOIs for a SAR scene. The MGRS grid requires a SAR scene to be geocoded to multiple UTM zones depending on the overlapping MGRS tiles and their projection. This function returns the following for each UTM zone group:

• the extent in WGS84 coordinates (key extent)

• the EPSG code of the UTM zone (key epsg)

• the Easting coordinate for pixel alignment (key align_x)

• the Northing coordinate for pixel alignment (key align_y)

A minimum overlap of the AOIs with the SAR scene is ensured by buffering the AOIs if necessary. The minimum overlap can be controlled with parameter percent.

Parameters:

• scene (pyroSAR.drivers.ID) – the SAR scene object

• kml (str) – Path to the Sentinel-2 tiling grid KML file.

• multi (bool) – split into multiple AOIs per overlapping UTM zone or just one AOI covering the whole scene. In the latter case the best matching UTM zone is auto-detected (using function spatialist.auxil.utm_autodetect()).

• percent (int or float) – the minimum overlap in percent of each AOI with the SAR scene. See function S1_NRB.ancillary.buffer_min_overlap().

Returns:

a list of dictionaries with keys extent, epsg, align_x, align_y

Return type:

list[dict]

S1_NRB.tile_extraction.aoi_from_tile(kml, tile)

Extract one or multiple MGRS tiles 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.

• tile (str or list[str]) – The MGRS tile ID(s) that should be extracted and returned as a vector object. Can also be expressed as <tile ID>_<EPSG code> (e.g. 33TUN_32632). In this case the geometry of the tile is reprojected to the target EPSG code, its corner coordinates rounded to multiples of 10, and a new Vector object created.

Returns:

either a single object or a list depending on tile

Return type:

spatialist.vector.Vector or list[spatialist.vector.Vector]

Notes

The global Sentinel-2 tiling grid can be retrieved from: https://sentinel.esa.int/documents/247904/1955685/S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml

S1_NRB.tile_extraction.description2dict(description)

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:

attrib – 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

S1_NRB.tile_extraction.tile_from_aoi(vector, kml, epsg=None, strict=True, return_geometries=False, tilenames=None)

Return a list of MGRS tile IDs or vector objects overlapping one or multiple areas of interest.

Parameters:

• vector (spatialist.vector.Vector or list[spatialist.vector.Vector]) – The vector object(s) to read. CRS must be EPSG:4236.

• kml (str) – Path to the Sentinel-2 tiling grid KML file.

• epsg (int or list[int] or None) – Define which EPSG code(s) are allowed for the tile selection. If None, all tile IDs are returned regardless of projection.

• strict (bool) – Strictly only return the names/geometries of the overlapping tiles in the target projection or also allow reprojection of neighbouring tiles? In the latter case a tile name takes the form <tile ID>_<EPSG code>, e.g. 33TUN_32632. Only applies if argument epsg is of type int or a list with one element.

• return_geometries (bool) – return a list of spatialist.vector.Vector geometry objects (or just the tile names)?

• tilenames (list[str] or None) – an optional list of MGRS tile names to limit the selection

Returns:

tiles – A list of unique MGRS tile IDs or spatialist.vector.Vector objects with an attribute mgrs containing the tile ID.

Return type:

list[str or spatialist.vector.Vector]

Notes

The global Sentinel-2 tiling grid can be retrieved from: https://sentinel.esa.int/documents/247904/1955685/S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml

Ancillary Functions

buffer_min_overlap	Buffer a geometry to a minimum overlap with a second geometry.
check_scene_consistency	Check the consistency of a scene selection.
check_spacing	Check whether the spacing fits into the MGRS tile boundaries.
generate_unique_id	Returns a unique product identifier as a hexadecimal string.
get_max_ext	Gets the maximum extent from a list of geometries.
group_by_time	Group scenes by their acquisition time difference.
log	Format and handle log messages during processing.
set_logging	Set logging for the current process.
vrt_add_overviews	Add overviews to an existing VRT file.

S1_NRB.ancillary.buffer_min_overlap(geom1, geom2, percent=1)

Buffer a geometry to a minimum overlap with a second geometry. The geometry is iteratively buffered until the minimum overlap is reached. If the overlap of the input geometries is already larger than the defined threshold, a copy of the original geometry is returned.

Parameters:

• geom1 (spatialist.vector.Vector) – the geometry to be buffered

• geom2 (spatialist.vector.Vector) – the reference geometry to intersect with

• percent (int or float) – the minimum overlap in percent of geom1

S1_NRB.ancillary.buffer_time(start, stop, **kwargs)

Time range buffering

Parameters:

• start (str) – the start time in format ‘%Y%m%dT%H%M%S’

• stop (str) – the stop time in format ‘%Y%m%dT%H%M%S’

• kwargs – time arguments passed to datetime.timedelta()

S1_NRB.ancillary.check_scene_consistency(scenes)

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:

RuntimeError –

S1_NRB.ancillary.check_spacing(spacing)

Check whether the spacing fits into the MGRS tile boundaries.

Parameters:

spacing (int or float) – the target pixel spacing in meters

S1_NRB.ancillary.generate_unique_id(encoded_str)

Returns a unique product identifier as a hexadecimal string. 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

S1_NRB.ancillary.get_max_ext(geometries, buffer=None)

Gets the maximum extent from a list of geometries.

Parameters:

• geometries (list[spatialist.vector.Vector]) – List of Vector geometries.

• buffer (float or None) – The buffer in units of the geometries’ CRS to add to the extent.

Returns:

max_ext – The maximum extent of the selected Vector geometries including the chosen buffer.

Return type:

dict

S1_NRB.ancillary.group_by_time(scenes, time=3)

Group scenes by their acquisition time difference.

Parameters:

• scenes (list[pyroSAR.drivers.ID or str]) – a list of image names

• time (int or float) – 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:

list[list[pyroSAR.drivers.ID]]

S1_NRB.ancillary.log(handler, mode, proc_step, scenes, msg)

Format and handle log messages during processing.

Parameters:

• handler (logging.Logger) – The log handler for the current process.

• mode ({'info', 'warning', 'exception'}) – Calls the respective logging helper function. E.g., handler.info().

• proc_step (str) – The processing step for which the message is logged.

• scenes (str or list[str]) – Scenes that are currently being processed.

• msg (Any) – The message that should be logged.

S1_NRB.ancillary.set_logging(config, debug=False)

Set logging for the current process.

Parameters:

• config (dict) – Dictionary of the parsed config parameters for the current process.

• debug (bool) – Set pyroSAR logging level to DEBUG?

Returns:

log_local – The log handler for the current process.

Return type:

logging.Logger

S1_NRB.ancillary.vrt_add_overviews(vrt, overviews, resampling='AVERAGE')

Add overviews to an existing VRT file. Existing overviews will be overwritten.

Parameters:

• vrt (str) – the VRT file

• overviews (list[int]) – the overview levels

• resampling (str) – the overview resampling method

Scene Search

ASF	Simple SAR metadata handler for scenes in the ASF archive.
ASFArchive	Search for scenes in the Alaska Satellite Facility (ASF) catalog.
STACArchive	Search for scenes in a SpatioTemporal Asset Catalog.
asf_select	Search scenes in the Alaska Satellite Facility (ASF) data catalog.
check_acquisition_completeness	Check presence of neighboring acquisitions.
collect_neighbors	Collect a scene's neighboring acquisitions in a data take
scene_select	Central scene search utility.

class S1_NRB.search.ASF(meta)

Bases: ID

Simple SAR metadata handler for scenes in the ASF archive. The interface is consistent with the driver classes in pyroSAR.drivers but does not implement the full functionality due to limited content of the CMR metadata catalog. Registered attributes:

• acquisition_mode

• coordinates

• frameNumber

• orbit

• orbitNumber_abs

• orbitNumber_rel

• polarizations

• product

• projection

• sensor

• start

• stop

scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

class S1_NRB.search.ASFArchive

Bases: object

Search for scenes in the Alaska Satellite Facility (ASF) catalog.

static select(sensor=None, product=None, acquisition_mode=None, mindate=None, maxdate=None, vectorobject=None, date_strict=True, return_value='url')

Select scenes from the ASF catalog. This is a simple wrapper around the function asf_select() to be consistent with the interfaces of STACArchive() and pyroSAR.drivers.Archive.

Parameters:

• sensor (str or list[str] or None) – S1A or S1B

• product (str or list[str] or None) – GRD or SLC

• acquisition_mode (str or list[str] or None) – IW, EW or SM

• mindate (str or datetime.datetime or None) – the minimum acquisition date

• maxdate (str or datetime.datetime or None) – the maximum acquisition date

• vectorobject (spatialist.vector.Vector or None) – a geometry with which the scenes need to overlap

• date_strict (bool) –

  treat dates as strict limits or also allow flexible limits to incorporate scenes whose acquisition period overlaps with the defined limit?

  • strict: start >= mindate & stop <= maxdate

  • not strict: stop >= mindate & start <= maxdate

• return_value (str or list[str]) – the metadata return value; see asf_select() for details

See also

asf_select

Returns:

the scene metadata attributes as specified with return_value; see asf_select() for details

Return type:

list[str or tuple[str] or ASF]

class S1_NRB.search.STACArchive(url, collections, timeout=60, max_retries=20)

Bases: object

Search for scenes in a SpatioTemporal Asset Catalog. Scenes are expected to be unpacked with a folder suffix .SAFE. The interface is kept consistent with ASFArchive() and pyroSAR.drivers.Archive.

Parameters:

• url (str) – the catalog URL

• collections (str or list[str]) – the catalog collection(s) to be searched

• timeout (int) – the allowed timeout in seconds

• max_retries (int or None) – the number of times to retry requests. Set to None to disable retries.

See also

pystac_client.Client.open, pystac_client.stac_api_io.StacApiIO

close()

select(sensor=None, product=None, acquisition_mode=None, mindate=None, maxdate=None, frameNumber=None, vectorobject=None, date_strict=True, check_exist=True)

Select scenes from the catalog. Used STAC keys:

• platform

• start_datetime

• end_datetime

• sar:instrument_mode

• sar:product_type

• s1:datatake (custom)

Parameters:

• sensor (str or list[str] or None) – S1A or S1B

• product (str or list[str] or None) – GRD or SLC

• acquisition_mode (str or list[str] or None) – IW, EW or SM

• mindate (str or datetime.datetime or None) – the minimum acquisition date

• maxdate (str or datetime.datetime or None) – the maximum acquisition date

• frameNumber (int or list[int] or None) – the data take ID in decimal representation. Requires custom STAC key s1:datatake.

• vectorobject (spatialist.vector.Vector or None) – a geometry with which the scenes need to overlap

• date_strict (bool) –

  treat dates as strict limits or also allow flexible limits to incorporate scenes whose acquisition period overlaps with the defined limit?

  • strict: start >= mindate & stop <= maxdate

  • not strict: stop >= mindate & start <= maxdate

• check_exist (bool) – check whether found files exist locally?

Returns:

the locations of the scene directories with suffix .SAFE

Return type:

list[str]

See also

pystac_client.Client.search

S1_NRB.search.asf_select(sensor, product, acquisition_mode, mindate, maxdate, vectorobject=None, return_value='url', date_strict=True)

Search scenes in the Alaska Satellite Facility (ASF) data catalog. This is a simple interface to the asf_search package.

Parameters:

• sensor (str) – S1A or S1B

• product (str) – GRD or SLC

• acquisition_mode (str) – IW, EW or SM

• mindate (str or datetime.datetime) – the minimum acquisition date

• maxdate (str or datetime.datetime) – the maximum acquisition date

• vectorobject (spatialist.vector.Vector or None) – a geometry with which the scenes need to overlap

• return_value (str or list[str]) – the metadata return value; if ASF, an ASF object is returned; further string options specify certain properties to return: beamModeType, browse, bytes, centerLat, centerLon, faradayRotation, fileID, flightDirection, groupID, granuleType, insarStackId, md5sum, offNadirAngle, orbit, pathNumber, platform, pointingAngle, polarization, processingDate, processingLevel, sceneName, sensor, startTime, stopTime, url, pgeVersion, fileName, frameNumber; all options except ASF can also be combined in a list

• date_strict (bool) –

  treat dates as strict limits or also allow flexible limits to incorporate scenes whose acquisition period overlaps with the defined limit?

  • strict: start >= mindate & stop <= maxdate

  • not strict: stop >= mindate & start <= maxdate

Returns:

the scene metadata attributes as specified with return_value; the return type is a list of strings, tuples or ASF objects depending on whether return_type is of type string, list or ASF.

Return type:

list[str or tuple[str] or ASF]

S1_NRB.search.check_acquisition_completeness(archive, scenes)

Check presence of neighboring acquisitions. Check that for each scene a predecessor and successor can be queried from the database unless the scene is at the start or end of the data take. This ensures that no scene that could be covering an area of interest is missed during processing. In case a scene is suspected to be missing, the Alaska Satellite Facility (ASF) online catalog is cross-checked. An error will only be raised if the locally missing scene is present in the ASF catalog.

Parameters:

• archive (pyroSAR.drivers.Archive or STACArchive) – an open scene archive connection

• scenes (list[pyroSAR.drivers.ID]) – a list of scenes

Raises:

RuntimeError –

See also

S1_NRB.search.asf_select

S1_NRB.search.collect_neighbors(archive, scene)

Collect a scene’s neighboring acquisitions in a data take

Parameters:

• archive (pyroSAR.drivers.Archive or STACArchive or ASFArchive) – an open scene archive connection

• scene (pyroSAR.drivers.ID) – the Sentinel-1 scene to be checked

Returns:

the file names of the neighboring scenes

Return type:

list[str]

S1_NRB.search.scene_select(archive, kml_file, aoi_tiles=None, aoi_geometry=None, **kwargs)

Central scene search utility. Selects scenes from a database and returns their file names together with the MGRS tile names for which to process ARD products. The list of MGRS tile names is either identical to the list provided with aoi_tiles, the list of all tiles overlapping with aoi_geometry or vectorobject (via kwargs), or the list of all tiles overlapping with an initial scene search result if no geometry has been defined via aoi_tiles or aoi_geometry. In the latter (most complex) case, the search procedure is as follows:

• perform a first search matching all other search parameters

• derive all MGRS tile geometries overlapping with the selection

• derive the minimum and maximum acquisition times of the selection as search parameters mindate and maxdate

• extend the mindate and maxdate search parameters by one minute

• perform a second search with the extended acquisition date parameters and the derived MGRS tile geometries

As consequence, if one defines the search parameters to only return one scene, the neighboring acquisitions will also be returned. This is because the scene overlaps with a set of MGRS tiles of which many or all will also overlap with these neighboring acquisitions. To ensure full coverage of all MGRS tiles, the neighbors of the scene in focus have to be processed too.

This function has three ways to define search geometries. In order of priority overriding others: aoi_tiles > aoi_geometry > vectorobject (via kwargs). In the latter two cases, the search geometry is extended to the bounding box of all MGRS tiles overlapping with the initial geometry to ensure full coverage of all tiles.

Parameters:

• archive (pyroSAR.drivers.Archive or STACArchive or ASFArchive) – an open scene archive connection

• kml_file (str) – the KML file containing the MGRS tile geometries.

• aoi_tiles (list[str] or None) – a list of MGRS tile names for spatial search

• aoi_geometry (str or None) – the name of a vector geometry file for spatial search

• kwargs – further search arguments passed to pyroSAR.drivers.Archive.select() or STACArchive.select() or ASFArchive.select()

Returns:

• the list of scenes

• the list of MGRS tiles

Return type:

tuple[list[str], list[str]]

Metadata

Extraction

calc_enl	Calculate the Equivalent Number of Looks (ENL) for a linear-scaled backscatter measurement GeoTIFF file.
calc_geolocation_accuracy	Calculates the radial root mean square error, which is a target requirement of the CARD4L NRB specification (Item 4.3).
calc_performance_estimates	Calculates the performance estimates specified in CARD4L NRB 1.6.9 for all noise power images if available.
calc_pslr_islr	Extracts all values for Peak Side Lobe Ratio (PSLR) and Integrated Side Lobe Ratio (ISLR) from the annotation metadata of a scene and calculates the mean value for all swaths.
copy_src_meta	Copies the original metadata of the source scenes to the ARD product directory.
find_in_annotation	Search for a pattern in all XML annotation files provided and return a dictionary of results.
geometry_from_vec	Get geometry information for usage in STAC and XML metadata from a spatialist.vector.Vector object.
get_header_size	Gets the header size of a GeoTIFF file in bytes.
get_prod_meta	Returns a metadata dictionary, which is generated from the name of a product scene using a regular expression pattern and from a measurement GeoTIFF file of the same product scene using the Raster class.
get_src_meta	Retrieve the manifest and annotation XML data of a scene as a dictionary using an pyroSAR.drivers.ID object.
meta_dict	Creates a dictionary containing metadata for a product scene, as well as its source scenes.

S1_NRB.metadata.extract.calc_enl(tif, block_size=30, return_arr=False, decimals=2)

Calculate the Equivalent Number of Looks (ENL) for a linear-scaled backscatter measurement GeoTIFF file. The calculation is performed block-wise for the entire image and by default the median ENL value is returned.

Parameters:

• tif (str) – The path to a linear-scaled backscatter measurement GeoTIFF file.

• block_size (int, optional) – The block size to use for the calculation. Remainder pixels are discarded, if the array dimensions are not evenly divisible by the block size. Default is 30, which calculates ENL for 30x30 pixel blocks.

• return_arr (bool, optional) – If True, the calculated ENL array is returned. Default is False.

• decimals (int, optional) – Number of decimal places to round the calculated ENL value to. Default is 2.

Returns:

The median ENL value or array of ENL values if return_enl_arr is True.

Return type:

float or numpy.ndarray

References

[2]

S1_NRB.metadata.extract.calc_geolocation_accuracy(swath_identifier, ei_tif, etad, decimals=2)

Calculates the radial root mean square error, which is a target requirement of the CARD4L NRB specification (Item 4.3). For more information see: https://s1-nrb.readthedocs.io/en/latest/general/geoaccuracy.html. Currently only the Copernicus DEM is supported.

Parameters:

• swath_identifier (str) – Swath identifier dependent on acquisition mode.

• ei_tif (str) – Path to the annotation GeoTIFF layer ‘Ellipsoidal Incident Angle’ of the current product.

• etad (bool) – Was the ETAD correction applied?

• decimals (int, optional) – Number of decimal places to round the calculated rRMSE value to. Default is 2.

Returns:

rmse_planar – The calculated rRMSE value rounded to two decimal places or None if a DEM other than Copernicus is used.

Return type:

float or None

S1_NRB.metadata.extract.calc_performance_estimates(files, decimals=2)

Calculates the performance estimates specified in CARD4L NRB 1.6.9 for all noise power images if available.

Parameters:

• files (list[str]) – List of paths pointing to the noise power images the estimates should be calculated for.

• decimals (int, optional) – Number of decimal places to round the calculated values to. Default is 2.

Returns:

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

Return type:

dict

S1_NRB.metadata.extract.calc_pslr_islr(annotation_dict, decimals=2)

Extracts all values for Peak Side Lobe Ratio (PSLR) and Integrated Side Lobe Ratio (ISLR) from the annotation metadata of a scene and calculates the mean value for all swaths.

Parameters:

• annotation_dict (dict) – A dictionary of annotation files in the form: {‘swath ID’:lxml.etree._Element object}

• decimals (int, optional) – Number of decimal places to round the calculated values to. Default is 2.

Returns:

a tuple with the following values:

• pslr: Mean PSLR value for all swaths of the scene.

• islr: Mean ISLR value for all swaths of the scene.

Return type:

tuple[float]

S1_NRB.metadata.extract.calc_wm_ref_stats(wm_ref_files, epsg, bounds, resolution=915)

Calculates the mean wind model reference speed and direction for the wind model annotation layer.

Parameters:

• wm_ref_files (list[str]) – List of paths pointing to the wind model reference files.

• epsg (int) – The EPSG code of the current MGRS tile.

• bounds (list[float]) – The bounds of the current MGRS tile.

• resolution (int, optional) – The resolution of the wind model reference files in meters. Default is 915.

Returns:

a tuple with the following values in the following order:

• Mean wind model reference speed.

• Mean wind model reference direction.

Return type:

tuple[float]

S1_NRB.metadata.extract.copy_src_meta(ard_dir, src_ids)

Copies the original metadata of the source scenes to the ARD product directory.

Parameters:

• ard_dir (str) – A path pointing to the current ARD product directory.

• src_ids (list[pyroSAR.drivers.ID]) – List of ID objects of all source scenes that overlap with the current MGRS tile.

Return type:

None

S1_NRB.metadata.extract.find_in_annotation(annotation_dict, pattern, single=False, out_type='str')

Search for a pattern in all XML annotation files provided and return a dictionary of results.

Parameters:

• annotation_dict (dict) – A dict of annotation files in the form: {‘swath ID’: lxml.etree._Element object}

• pattern (str) – The pattern to search for in each annotation file.

• single (bool) – If True, the results found in each annotation file are expected to be the same and therefore only a single value will be returned instead of a dict. If the results differ, an error is raised. Default is False.

• out_type (str) –

  Output type to convert the results to. Can be one of the following:

  • ’str’ (default)

  • ’float’

  • ’int’

Returns:

out – A dictionary of the results containing a list for each of the annotation files. E.g., {‘swath ID’: list[str or float or int]}

Return type:

dict

S1_NRB.metadata.extract.geometry_from_vec(vectorobject)

Get geometry information for usage in STAC and XML metadata from a spatialist.vector.Vector object.

Parameters:

vectorobject (spatialist.vector.Vector) – The vector object to extract geometry information from.

Returns:

out – A dictionary containing the geometry information extracted from the vector object.

Return type:

dict

S1_NRB.metadata.extract.get_header_size(tif)

Gets the header size of a GeoTIFF file in bytes. The code used in this function and its helper function _get_block_offset were extracted from the following source:

https://github.com/OSGeo/gdal/blob/master/swig/python/gdal-utils/osgeo_utils/samples/validate_cloud_optimized_geotiff.py

Copyright (c) 2017, Even Rouault

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Parameters:

tif (str) – A path to a GeoTIFF file of the currently processed ARD product.

Returns:

header_size – The size of all IFD headers of the GeoTIFF file in bytes.

Return type:

int

S1_NRB.metadata.extract.get_prod_meta(product_id, tif, src_ids, sar_dir)

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

Parameters:

• product_id (str) – The top-level product folder name.

• tif (str) – The path to a measurement GeoTIFF file of the product scene.

• src_ids (list[pyroSAR.drivers.ID]) – List of ID objects of all source SLC scenes that overlap with the current MGRS tile.

• sar_dir (str) – A path pointing to the processed SAR datasets of the product.

Returns:

A dictionary containing metadata for the product scene.

Return type:

dict

S1_NRB.metadata.extract.get_src_meta(sid)

Retrieve the manifest and annotation XML data of a scene as a dictionary using an pyroSAR.drivers.ID object.

Parameters:

sid (pyroSAR.drivers.ID) – A pyroSAR ID object generated with e.g. pyroSAR.drivers.identify().

Returns:

A dictionary containing the parsed etree.ElementTree objects for the manifest and annotation XML files.

Return type:

dict

S1_NRB.metadata.extract.meta_dict(config, target, src_ids, sar_dir, proc_time, start, stop, compression, product_type, wm_ref_files=None)

Creates a dictionary containing metadata for a product scene, as well as its source scenes. The dictionary can then be utilized by parse() and parse() to generate OGC 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 current ARD product directory.

• src_ids (list[pyroSAR.drivers.ID]) – List of ID objects of all source scenes that overlap with the current MGRS tile.

• sar_dir (str) – The SAR processing output directory.

• proc_time (datetime.datetime) – The processing time object used to generate the unique product identifier.

• start (datetime.datetime) – The product start time.

• stop (datetime.datetime) – The product stop time.

• compression (str) – The compression type applied to raster files of the product.

• product_type (str) – The type of ARD product that is being created. Either ‘NRB’ or ‘ORB’.

• wm_ref_files (list[str], optional) – A list of paths pointing to wind model reference files. Default is None.

Returns:

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

Return type:

dict

XML

parse	Wrapper for source_xml() and product_xml().
product_xml	Function to generate product-level metadata for an ARD product in OGC 10-157r4 compliant XML format.
source_xml	Function to generate source-level metadata for an ARD product in OGC 10-157r4 compliant XML format.

S1_NRB.metadata.xml.parse(meta, target, assets, exist_ok=False)

Wrapper for source_xml() and product_xml().

Parameters:

• meta (dict) – Metadata dictionary generated with meta_dict().

• target (str) – A path pointing to the root directory of a product scene.

• assets (list[str]) – List of paths to all GeoTIFF and VRT assets of the currently processed ARD product.

• exist_ok (bool) – Do not create files if they already exist?

S1_NRB.metadata.xml.product_xml(meta, target, assets, nsmap, ard_ns, exist_ok=False)

Function to generate product-level metadata for an ARD product in OGC 10-157r4 compliant XML format.

Parameters:

• meta (dict) – Metadata dictionary generated with meta_dict()

• target (str) – A path pointing to the root directory of a product scene.

• assets (list[str]) – List of paths to all GeoTIFF and VRT assets of the currently processed ARD product.

• nsmap (dict) – Dictionary listing abbreviation (key) and URI (value) of all necessary XML namespaces.

• ard_ns (str) – Abbreviation of the ARD namespace. E.g., s1-nrb for the NRB ARD product.

• exist_ok (bool) – Do not create files if they already exist?

S1_NRB.metadata.xml.source_xml(meta, target, nsmap, ard_ns, exist_ok=False)

Function to generate source-level metadata for an ARD product in OGC 10-157r4 compliant XML format.

Parameters:

• meta (dict) – Metadata dictionary generated with meta_dict()

• target (str) – A path pointing to the root directory of a product scene.

• nsmap (dict) – Dictionary listing abbreviation (key) and URI (value) of all necessary XML namespaces.

• ard_ns (str) – Abbreviation of the ARD namespace. E.g., s1-nrb for the NRB ARD product.

• exist_ok (bool) – Do not create files if they already exist?

STAC

parse	Wrapper for source_json() and product_json().
product_json	Function to generate product-level metadata for an ARD product in STAC compliant JSON format.
source_json	Function to generate source-level metadata for an ARD product in STAC compliant JSON format.
make_catalog	For a given directory of Sentinel-1 ARD products, this function will create a high-level STAC Catalog object serving as the STAC endpoint and lower-level STAC Collection objects for each subdirectory corresponding to a unique MGRS tile ID.

S1_NRB.metadata.stac.make_catalog(directory, product_type, recursive=True, silent=False)

For a given directory of Sentinel-1 ARD products, this function will create a high-level STAC Catalog object serving as the STAC endpoint and lower-level STAC Collection objects for each subdirectory corresponding to a unique MGRS tile ID.

WARNING: The directory content will be reorganized into subdirectories based on the ARD type and unique MGRS tile IDs if this is not yet the case.

Parameters:

• directory (str) – Path to a directory that contains ARD products.

• product_type (str) – Type of ARD products. Options: ‘NRB’ or ‘ORB’.

• recursive (bool, optional) – Search directory recursively? Default is True.

• silent (bool, optional) – Should the output during directory reorganization be suppressed? Default is False.

Returns:

nrb_catalog – STAC Catalog object

Return type:

pystac.catalog.Catalog

Notes

The returned STAC Catalog object contains Item asset hrefs that are absolute, whereas the actual on-disk files contain relative asset hrefs corresponding to the self-contained Catalog-Type. The returned in-memory STAC Catalog object deviates in this regard to ensure compatibility with the stackstac library: https://github.com/gjoseph92/stackstac/issues/20

S1_NRB.metadata.stac.parse(meta, target, assets, exist_ok=False)

Wrapper for source_json() and product_json().

Parameters:

• meta (dict) – Metadata dictionary generated with meta_dict()

• target (str) – A path pointing to the root directory of a product scene.

• assets (list[str]) – List of paths to all GeoTIFF and VRT assets of the currently processed ARD product.

• exist_ok (bool) – Do not create files if they already exist?

S1_NRB.metadata.stac.product_json(meta, target, assets, exist_ok=False)

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

Parameters:

• meta (dict) – Metadata dictionary generated with meta_dict().

• target (str) – A path pointing to the root directory of a product scene.

• assets (list[str]) – List of paths to all GeoTIFF and VRT assets of the currently processed ARD product.

• exist_ok (bool) – Do not create files if they already exist?

S1_NRB.metadata.stac.source_json(meta, target, exist_ok=False)

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

Parameters:

• meta (dict) – Metadata dictionary generated with meta_dict().

• target (str) – A path pointing to the root directory of a product scene.

• exist_ok (bool) – Do not create files if they already exist?