Processing

SAR

Implementation of full SAR processing is the responsibility of the satellite-specific processor packages like s1ard. cesard however offers some general functions that these processors might make use of. The cesard.snap module offers some functions to interface the SNAP processor with the respective ARD processor and some general processing functions.

SNAP

main interface

find_datasets	Find processed datasets for a SAR scene.
lsm_encoding	Get the encoding of the layover shadow mask.
version_dict	Get processor software version information.

processor functions

geo	Range-Doppler geocoding.
gsr	Gamma-sigma ratio computation for either ellipsoidal or RTC sigma nought.
mli	Multi-looking.
postprocess	Performs edge cleaning and sets the nodata value in the output ENVI HDR files.
rtc	Radiometric Terrain Flattening.
sgr	Sigma-gamma ratio computation.

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

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.

Return type:

dict[str, str] | None

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

cesard.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 (str | 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 | float) – the target pixel spacing in meters

• crs (int | float) – the target coordinate reference system

• geometry (dict[str, int | float] | Vector | str | None) – a vector geometry to limit the target product’s extent

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

• export_extra (list[str] | None) –

  a list of ancillary layers to write. Supported options:

  • DEM

  • incidenceAngleFromEllipsoid

  • layoverShadowMask

  • localIncidenceAngle

  • projectedLocalIncidenceAngle

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

• standard_grid_origin_y (int | 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] | 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'], ...

Return type:

None

See also

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

cesard.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 | None) – the optional file name of a second source product from which to read the sigma band.

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

Return type:

None

cesard.snap.lsm_encoding()

Get the encoding of the layover shadow mask.

Return type:

dict[str, int]

cesard.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 | 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 | None) – the number of range looks.

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

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

Return type:

None

See also

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

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

Return type:

None

cesard.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] | 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

Return type:

None

cesard.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 | None) – the optional file name of a second source product from which to read the gamma band.

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

Return type:

None

cesard.snap.version_dict()

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.

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

cesard.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 products and overlap with the current MGRS tile.

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

cesard.ard.create_data_mask(outname, datasets, extent, epsg, driver, creation_opt, overviews, overview_resampling, dst_nodata, product_type, lsm_encoding, 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[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

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

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

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

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/en/stable/drivers/raster/vrt.html#built-in-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})

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.

cesard.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 | 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 | None) – The password for accessing the DEM tiles. If None: same behavior as for username but with env. variable ‘DEM_PASS’.

Return type:

tuple[str | None, str | None]

Returns:

the username and password

cesard.dem.mosaic(geometry, dem_type, outname, tr=None, username=None, password=None, threads=4)

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

Parameters:

• geometry (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 | tuple[int | float, int | float]) – the target resolution as (xres, yres) in units of the target CRS.

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

Return type:

None

cesard.dem.prepare(scene, dem_type, mode, dir_out, tr=None, username=None, password=None)

Prepare DEM files for SAR processing.

Parameters:

• scene (ID) – the SAR product

• dem_type (str) – the DEM type

• mode (Literal['single-4326', 'multi-UTM']) – the DEM preparation mode (depends on the requirements of the used SAR processor)

• dir_out (str) – the destination directory

• tr (None | tuple[int | float, int | float]) – the target resolution in meters as (x, y).

• username (str | 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 | None) – The password for accessing the DEM tiles. If None: same behavior as for username but with env. variable ‘DEM_PASS’.

Return type:

list[str]

Returns:

the names of the newly created DEM files.

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

Download and retile DEM and WBM tiles to MGRS. Including re-projection and vertical datum conversion.

Parameters:

• 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 | None) – The DEM target directory. DEM preparation can be skipped if set to None.

• wbm_dir (str | 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] | None) – an optional list of MGRS tile names. Default None: process all overalapping tiles.

• threads (int | 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 | 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 | 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?

Return type:

None

Examples

>>> from cesard 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

cesard.tile_extraction.tile_from_aoi

cesard.dem.to_mgrs(tile, dst, 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

• dem_type (str) – The DEM type.

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

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

• format (str) – the output file format

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

• threads (int | 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) – add a progress bar?

Return type:

None