API Documentation

Configuration

gdal_conf

Stores GDAL configuration options for the current process.

get_config

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

get_keys

get all allowed configuration keys for a section

read_config_file

Reads a configuration file and returns a ConfigParser object

version_dict

Get the versions of used packages
asard.config.gdal_conf(config)[source]

Stores GDAL configuration options for the current process.

Parameters:

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

Returns:

Dictionary containing GDAL configuration options for the current process.

Return type:

dict

asard.config.get_config(config_file=None, **kwargs)[source]

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

Parameters:

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

  • kwargs (dict[str]) – further keyword arguments overriding configuration found in the config file.

Returns:

Dictionary of the parsed config parameters. The keys correspond to the config sections in lowercase letters.

Return type:

dict

asard.config.get_keys(section)[source]

get all allowed configuration keys for a section

Parameters:

section (str) – the configuration section to get the allowed keys for. Either ‘processing’ or the name of a SAR processor plugin e.g. ‘snap’.

Returns:

a list of keys

Return type:

list[str]

asard.config.read_config_file(config_file=None)[source]

Reads a configuration file and returns a ConfigParser object

Parameters:

config_file (str or None) – the configuration file name. If None, the default configuration file within the package will be used.

Return type:

configparser.ConfigParser

asard.config.version_dict(processor_name: str) → dict[str, str][source]

Get the versions of used packages

Parameters:

processor_name – the name of the used SAR processor (e.g. snap)

Returns:

  • a dictionary containing the versions of relevant python packages and

  • the return of the version_dict function of the used SAR processor.

Processing

asard.processor.main(config_file, **kwargs)[source]

Main processing function.

Parameters:

  • config_file (str or None) – Path to the INI configuration file.

  • kwargs – Additional arguments overriding configuration in config_file.

SAR

asard 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 asard can fully interact with the module.

SNAP

main interface

config_to_string

Convert the values of a configuration dictionary to strings.

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.

processor-specific functions

process

Main function for SAR processing with SNAP.

pre

General SAR preprocessing.
asard.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

asard.snap.get_config_keys()[source]

Get all allowed configuration keys.

Return type:

List[str]

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

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

Parameters:
Return type:

dict

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

Get processing metadata needed for ARD product metadata.

Parameters:

  • scene (pyroSAR.drivers.ID) – the name of the SAR scene

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

Return type:

dict

asard.snap.pre(src, dst, workflow, allow_res_osv=True, output_beta0=True, output_sigma0=True, output_gamma0=False, gpt_args=None)[source]

General SAR preprocessing. The following operators are used (optional steps in brackets): Apply-Orbit-File->Calibration

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.

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

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

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

  • 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 asard import snap
>>> scene = 'ASA_IMP_1PNESA20110820_092721_000000173105_00381_49533_0000.N1'
>>> dem = 'ASA_IMP_1PNESA20110820_092721_000000173105_00381_49533_0000_DEM_GLO30.tif'
>>> outdir = '.'
>>> spacing = 10
>>> export_extra = ['localIncidenceAngle', 'incidenceAngleFromEllipsoid',
>>>                 'scatteringArea', 'layoverShadowMask', 'gammaSigmaRatio']
>>> snap.process(scene=scene, outdir=outdir, spacing=spacing, dem=dem,
>>>              export_extra=export_extra)

ARD

append_metadata

Append metadata files to an ARD product.

get_datasets

Collect processing output for a list of scenes.

format

Create ARD products from the SAR processor output.

product_info

Create ARD product metadata.
asard.ard.append_metadata(config, prod_meta, src_ids, assets, compression)[source]

Append metadata files to an ARD product.

Parameters:

  • config (dict) – the configuration dictionary

  • prod_meta (dict) – the product metadata as returned by product_info()

  • src_ids (List[pyroSAR.drivers.ID]) – the source product objects

  • assets (List[str]) – a list of assets in the ARD product

  • compression (str) – the used compression algorithm

asard.ard.format(config: dict[str, dict[str, int | float | str | list[str]]], prod_meta: dict[str, str | int | datetime], src_ids: list[ID], sar_assets: list[dict[str, str]], tile: str, extent: dict[str, int | float], epsg: int, wbm: str | None = None, dem_type: str | None = None, multithread: bool = True, compress: str | None = None, overviews: list[int] | None = None, annotation: list[str] | None = None) → list[str] | 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 – Dictionary of the parsed config parameters for the current process.

  • prod_meta – Product metadata as returned by product_info().

  • src_ids – 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 – The SAR processing assets as returned by get_datasets().

  • tile – ID of an MGRS tile.

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

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

  • wbm – Path to a water body mask file with the dimensions of an MGRS tile.

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

  • overviews – Internal overview levels to be created for each GeoTIFF file. Defaults to [2, 4, 9, 18, 36]

  • annotation –

    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:

the ARD product assets

asard.ard.get_datasets(scenes: list[str | ID], sar_dir: str, extent: dict[str, int | float], epsg: int, processor_name: str) → tuple[list[ID], list[dict[str, str]]][source]

Collect processing output for a list of scenes. Reads metadata from all source products, finds matching output files in sar_dir and filters both lists depending on the actual overlap of each product’s 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 of scenes to process. Either an individual scene or multiple, matching scenes (consecutive acquisitions).

  • sar_dir – 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 – Spatial extent of the MGRS tile, derived from a Vector object.

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

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

Returns:

  • List of ID objects of all source products

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

See also

cesard.snap.find_datasets()

asard.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 ({NRB, ORB}) – the ARD product type

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

  • tile_id (str) – the MGRS tile ID

  • extent (dict) – the extent of the MGRS tile

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

Returns:

ARD product metadata

Return type:

dict

OSV file handling

download_asar

Download DORIS OSV files from ftps://envorb-ftp-ds.eo.esa.int.

download_ers

Download ERS-1/2 OSV files.

get

Get the matching OSV file for a satellite product.
asard.osv.download_asar(username: str, password: str, target: str | None = None, start: datetime | None = None, stop: datetime | None = None) → None[source]

Download DORIS OSV files from ftps://envorb-ftp-ds.eo.esa.int.

Parameters:

  • username – the FTP access username

  • password – the FTP access password

  • target – the download location. Default None: Store data in a subdirectory of the configured SNAP auxiliary data path (See pyroSAR.examine.ExamineSnap.auxdatapath()).

  • start – the acquisition start. Default None: no acquisition start limit

  • stop – the acquisition stop. Default None: no acquisition stop limit

asard.osv.download_ers(type: Literal['DELFT', 'REAPER'], username: str | None = None, password: str | None = None, satellite: Literal['ERS1', 'ERS2'] | None = None, target: str | None = None, start: datetime | None = None, stop: datetime | None = None) → None[source]

Download ERS-1/2 OSV files.

Parameters:

  • username – the FTP access username. Only needed for REAPER products.

  • password – the FTP access password. Only needed for REAPER products.

  • type –

    the OSV type to download; supported options:

  • satellite – Either ERS1, ERS2 or None (both satellites).

  • target – the download location. Default None: Store data in a subdirectory of the configured SNAP auxiliary data path (See pyroSAR.examine.ExamineSnap.auxdatapath()).

  • start – the acquisition start. Default None: no limit

  • stop – the acquisition stop. Default None: no limit

asard.osv.get(scene: ID, type: Literal['DELFT', 'DORIS', 'REAPER'], offline: bool = False, username: str | None = None, password: str | None = None, target: str | None = None) → str | None[source]

Get the matching OSV file for a satellite product.

Parameters:

  • scene – the satellite product object

  • type –

    the OSV type to download; supported options:

    • ASAR: DORIS

    • ERS: DELFT, REAPER

  • offline – only search offline?

  • username – the FTP access username

  • password – the FTP access password

  • target – the download location. Default None: Store data in a subdirectory of the configured SNAP auxiliary data path (See pyroSAR.examine.ExamineSnap.auxdatapath()).

Return type:

either the name of an existing file or None if no file was found

Ancillary Functions

set_logging

Set logging for the current process.
asard.ancillary.set_logging(config: dict[str, Any], debug: bool = False) → Logger[source]

Set logging for the current process.

Parameters:

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

  • debug – Set logging level to DEBUG?

Return type:

The log handler for the current process.

Metadata

Extraction

get_prod_meta

Collect ARD product metadata.

meta_dict

Creates a dictionary containing metadata for an ARD product as well as its source products.
asard.metadata.extract.get_prod_meta(tif, src_ids, sar_dir)[source]

Collect ARD product metadata. Items are obtained from parsing the name of the ARD product and from reading a measurement GeoTIFF file of this product.

Parameters:

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

  • src_ids (list[pyroSAR.drivers.ID]) – The source product object(s).

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

Returns:

A dictionary containing metadata for the product scene.

Return type:

dict

asard.metadata.extract.meta_dict(config, prod_meta, src_ids, compression)[source]

Creates a dictionary containing metadata for an ARD product as well as its source products. The dictionary can then be used to parse XML and STAC JSON metadata files, respectively.

Parameters:

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

  • prod_meta (dict) – general product metadata as extracted by asard.ard.product_info()

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

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

Returns:

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

Return type:

dict