Processing

main

Main function that initiates and controls the processing workflow.
s1ard.processor.main(config_file=None, debug=False, **kwargs)[source]

Main function that initiates and controls the processing workflow.

Parameters:

  • config_file (str or None) – Full path to a config.ini file or None to use the package’s default file.

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

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

SAR

s1ard offers a mechanism to plug in different SAR processors. The software offers a snap reference implementation module that can be translated to other processors. All “main interface” functions need to be implemented so that s1ard can fully interact with the module.

SNAP

main interface

config_to_string

Convert the values of a configuration dictionary to strings.

find_datasets

Find processed datasets for a SAR scene.

get_config_keys

Get all allowed configuration keys.

get_config_section

Get the`config.ini` SNAP section content as a dictionary.

get_metadata

Get processing metadata needed for ARD product metadata.

lsm_encoding

Get the encoding of the layover shadow mask.

process

Main function for SAR processing with SNAP.

translate_annotation

Translate s1ard annotation keys to SAR processor naming.

version_dict

Get processor software version information.

processor-specific functions

geo

Range-Doppler geocoding.

grd_buffer

GRD extent buffering.

gsr

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

look_direction

Compute the per-pixel range look direction angle.

mli

Multi-looking.

nrt_slice_num

Check whether a product has a non-zero slice number and add it if not.

postprocess

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

pre

General SAR preprocessing.

rtc

Radiometric Terrain Flattening.

sgr

Sigma-gamma ratio computation.
s1ard.snap.config_to_string(config)[source]

Convert the values of a configuration dictionary to strings.

Parameters:

config (dict) – the configuration as returned by get_config_section()

Returns:

the dictionary with the same structure but values converted to strings.

Return type:

dict

s1ard.snap.find_datasets(scene, outdir, epsg)[source]

Find processed datasets for a SAR scene.

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

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

s1ard.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)[source]

Range-Doppler geocoding.

Parameters:

  • src (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

s1ard.snap.get_config_keys()[source]

Get all allowed configuration keys.

Return type:

List[str]

s1ard.snap.get_config_section(parser, **kwargs)[source]

Get the`config.ini` SNAP section content as a dictionary.

Parameters:
Return type:

dict

s1ard.snap.get_metadata(scene, outdir)[source]

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

s1ard.snap.grd_buffer(src, dst, workflow, neighbors, buffer=100, gpt_args=None)[source]

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. The SliceAssembly operator needs info about the slice number (i.e., the ID/position inside the data take). If the value in the metadata is 0 (which can be the case in NRT slicing mode), the slice number is determined using function nrt_slice_num(). If this fails, the function will raise an error.

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

Raises:

RuntimeError – if the slice number of a scene is 0, and it could not be determined from the acquisition time

s1ard.snap.gsr(src, dst, workflow, src_sigma=None, gpt_args=None)[source]

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

s1ard.snap.look_direction(dim)[source]

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)

s1ard.snap.lsm_encoding()[source]

Get the encoding of the layover shadow mask.

Return type:

dict[str, int]

s1ard.snap.mli(src, dst, workflow, spacing=None, rlks=None, azlks=None, gpt_args=None)[source]

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

s1ard.snap.nrt_slice_num(dim)[source]

Check whether a product has a non-zero slice number and add it if not. In NRT Slicing 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

Raises:

RuntimeError – if the slice number is 0, and it cannot be computed because the segment start time cannot be read from the metadata

s1ard.snap.postprocess(src, clean_edges=True, clean_edges_pixels=4)[source]

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.

s1ard.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, add_slice_num=True, gpt_args=None)[source]

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?

  • add_slice_num (bool) – determine a slice number and add it to the product’s metadata? This is only necessary if GRD buffering is intended. See nrt_slice_num().

  • 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

s1ard.snap.process(scene, outdir, measurement, spacing, 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)[source]

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.

  • dem (str) – The DEM filename. Can be created with s1ard.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 s1ard import snap
>>> scene = 'S1A_IW_SLC__1SDV_20200103T170700_20200103T170727_030639_0382D5_6A12.zip'
>>> 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, dem=dem,
>>>              rlks=rlks, azlks=azlks, export_extra=export_extra)
s1ard.snap.rtc(src, dst, workflow, dem, dem_resampling_method='BILINEAR_INTERPOLATION', sigma0=True, scattering_area=True, dem_oversampling_multiple=2, gpt_args=None)[source]

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

s1ard.snap.sgr(src, dst, workflow, src_gamma=None, gpt_args=None)[source]

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

s1ard.snap.translate_annotation(annotation, measurement)[source]

Translate s1ard annotation keys to SAR processor naming.

Parameters:

  • annotation (List[str]) – the s1ard annotation keys (e.g. ei, gs)

  • measurement (str) – the SAR backscatter measurement (gamma|sigma)

Returns:

the annotation layer keys as required by the SAR processor

Return type:

List[str]

s1ard.snap.version_dict()[source]

Get processor software version information.

Return type:

dict[str, str]

Returns:

a dictionary with software components as keys and their versions as values.

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 GDAL VRT file.

create_vrt

Create a GDAL VRT file executing an on-the-fly pixel function.

format

Create ARD products from the SAR processor output.

get_datasets

Collect processing output for a list of scenes.

wind_normalization

Create ORB wind normalization layers.
s1ard.ard.append_metadata(config, prod_meta, src_ids, assets, compression, wm_ref_speed=None, wm_ref_direction=None)[source]

Append metadata files to an ARD product.

Parameters:
Return type:

None

s1ard.ard.calc_product_start_stop(src_ids, extent, epsg)[source]

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 product. These grid points are then used to interpolate the azimuth time for the coordinates of the MGRS tile extent. The lowest and highest interpolated value are returned as product acquisition start and stop times of the ARD product.

Parameters:

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

  • extent (dict[str, int | float]) – Spatial extent of the MGRS tile, derived from a Vector object.

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

Return type:

tuple[datetime, datetime]

Returns:

Start and stop time of the ARD product in UTC.

See also

pyroSAR.drivers.SAFE.geo_grid, scipy.interpolate.RBFInterpolator

s1ard.ard.create_acq_id_image(outname, ref_tif, datasets, src_ids, extent, epsg, driver, creation_opt, overviews, dst_nodata)[source]

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[ID]) – List of ID objects of all source SLC scenes that overlap with the current MGRS tile.

  • extent (dict[str, int | float]) – 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 | str) – Nodata value to write to the output raster.

Return type:

None

s1ard.ard.create_data_mask(outname, datasets, extent, epsg, driver, creation_opt, overviews, overview_resampling, dst_nodata, product_type, lsm_encoding, wbm=None)[source]

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[str, int | float]) – 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 | 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’.

  • lsm_encoding (dict[str, int]) – a dictionary containing the layover shadow mask encoding.

  • wbm (str | 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’.

Return type:

None

s1ard.ard.create_rgb_vrt(outname, infiles, overviews, overview_resampling)[source]

Creation of the color composite GDAL 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.

Return type:

None

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

Create a GDAL VRT file executing an on-the-fly pixel function.

Parameters:

  • src (str | 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 | 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 | 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 | 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[str, int | float | str] | None) – arguments for fun passed as PixelFunctionArguments. Requires GDAL>=3.5 to be read.

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

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

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

Return type:

None

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})
s1ard.ard.format(config, prod_meta, src_ids, sar_assets, tile, extent, epsg, wbm=None, dem_type=None, multithread=True, compress=None, overviews=None, annotation=None)[source]

Create ARD products from the SAR processor output. 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[str, dict[str, int | float | str | list[str]]]) – Dictionary of the parsed config parameters for the current process.

  • prod_meta (dict[str, str | int | datetime]) – Product metadata as returned by product_info().

  • src_ids (list[ID]) – 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.

  • sar_assets (list[dict[str, str]]) – The SAR processing assets as returned by get_datasets().

  • tile (str) – ID of an MGRS tile.

  • extent (dict[str, int | float]) – 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 | None) – Path to a water body mask file with the dimensions of an MGRS tile.

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

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

  • annotation (list[str] | 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

Return type:

list[str] | None

Returns:

the ARD product assets

s1ard.ard.get_datasets(scenes, sar_dir, extent, epsg, processor_name)[source]

Collect processing output for a list of scenes. Reads metadata from all source SLC/GRD scenes, finds matching output files in sar_dir 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).

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

  • extent (dict[str, int | float]) – Spatial extent of the MGRS tile, derived from a Vector object.

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

  • processor_name (str) – The name of the used SAR processor. The function find_datasets of the respective processor module is used.

Return type:

tuple[list[ID], list[dict[str, str]]]

Returns:

List of ID objects of all source SLC/GRD scenes that overlap with the current MGRS tile and a list of SAR processing output files that match each ID object of ids. The format of the latter is a list of dictionaries per scene with keys as described by e.g. s1ard.snap.find_datasets().

See also

s1ard.snap.find_datasets()

s1ard.ard.product_info(product_type, src_ids, tile_id, extent, epsg, dir_out, update=False, product_id=None)[source]

Create ARD product metadata.

Parameters:

  • product_type (str) – the ARD product type; options: NRB, ORB

  • src_ids (list[ID]) – the source product objects

  • tile_id (str) – the MGRS tile ID

  • extent (dict[str, int | float]) – the extent of the MGRS tile

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

  • dir_out (str) – the output directory of the product

  • update (bool) – update an existing product (or create a new one)

  • product_id (str | None) – an existing product ID. Default None: create a new one using function generate_unique_id().

Return type:

dict[str, str | int | datetime]

Returns:

ARD product metadata

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

Create ORB 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 s1ard.ocn.extract()

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

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

  • measurement (str | 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 (s1ard.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) – 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).

Return type:

None

ETAD

process

Apply ETAD correction to a Sentinel-1 SLC product.
s1ard.etad.process(scene, etad_dir, out_dir)[source]

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.

Returns:

The corrected scene as a pyroSAR ID object.

Return type:

pyroSAR.drivers.ID

DEM

authenticate

Query the username and password.

mosaic

Create a new scene-specific DEM mosaic GeoTIFF file.

prepare

Prepare DEM files for SAR processing.

retile

Download and retile DEM and WBM tiles to MGRS.

to_mgrs

Create an MGRS-tiled DEM file.
s1ard.dem.authenticate(dem_type, username=None, password=None)[source]

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]

s1ard.dem.mosaic(geometry, dem_type, outname, tr=None, username=None, password=None, threads=4)[source]

Create a new scene-specific DEM mosaic GeoTIFF file. Makes use of pyroSAR.auxdata.dem_autoload() and pyroSAR.auxdata.dem_create().

Parameters:

  • geometry (spatialist.vector.Vector) – The geometry to be covered by the mosaic. The geometry’s CRS is used as target CRS.

  • dem_type (str) – The DEM type.

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

  • tr (None or tuple[int or float]) – the target resolution as (xres, yres) in units of the target CRS.

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

s1ard.dem.prepare(scene, dem_type, mode, dir_out, tr=None, username=None, password=None)[source]

Prepare DEM files for SAR processing.

Parameters:

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

  • dem_type (str) – the DEM type

  • mode ({single-4326, multi-UTM}) – the DEM preparation mode (depends on the requirements of the used SAR processor)

  • dir_out (str) – the destination directory

  • tr (tuple(int or float) or None) – the target resolution in meters as (x, y). Only applies to mode multi-UTM.

  • 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 names of the newly created DEM files.

Return type:

List[str]

s1ard.dem.retile(vector, dem_type, dem_dir, wbm_dir, dem_strict=True, tilenames=None, threads=None, username=None, password=None, lock_timeout=1200)[source]

Download and retile DEM and WBM tiles to MGRS. 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

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

  • lock_timeout (int) – how long to wait to acquire a lock on created files?

Examples

>>> from s1ard import dem
>>> from spatialist import bbox
>>> ext = {'xmin': 12, 'xmax': 13, 'ymin': 50, 'ymax': 51}
# 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.retile(vector=vec, dem_type='Copernicus 30m Global DEM',
>>>                dem_dir='DEM', wbm_dir=None, dem_strict=True,
>>>                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.retile(vector=vec, dem_type='Copernicus 30m Global DEM',
>>>                dem_dir='DEM', wbm_dir=None, dem_strict=False,
>>>                threads=4)

See also

s1ard.tile_extraction.tile_from_aoi

s1ard.dem.to_mgrs(tile, dst, dem_type, overviews, tr, format='COG', create_options=None, threads=None, pbar=False)[source]

Create an MGRS-tiled DEM file.

Parameters:

  • tile (str) – the MGRS tile ID

  • dst (str) – the destination file name

  • 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.
s1ard.ocn.extract(src, dst, variable)[source]

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

s1ard.ocn.gapfill(src, dst, md, si)[source]

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