Metadata

Extraction

append_wind_norm	Update a metadata dictionary with wind model information
calc_geolocation_accuracy	Calculates the radial root mean square error, which is a target requirement of the CARD4L NRB specification (Item 4.3).
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.
calc_wm_ref_stats	Calculates the mean wind model reference speed and direction for the wind model annotation layer.
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 the results.
get_osv_info	Get information about the used OSV file.
get_prod_meta	Get ARD product metadata.
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.

s1ard.metadata.extract.append_wind_norm(meta, wm_ref_speed, wm_ref_direction)

Update a metadata dictionary with wind model information

Parameters:

• meta (dict) – metadata extracted by meta_dict()

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

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

s1ard.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://s1ard.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

s1ard.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[str, dict[str, ElementTree]]) – A dictionary of Sentinel-1 annotation file XML objects (key annotation of the dictionary returned by get_src_meta()).

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

Return type:

tuple[float | None, float | None]

Returns:

a tuple with the following values. Each can be set to None if not found in the metadata.

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

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

s1ard.metadata.extract.calc_wm_ref_stats(wm_ref_speed, wm_ref_direction, epsg, bounds, resolution=915)

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

Parameters:

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

• wm_ref_speed – List of paths pointing to the wind model reference direction 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]

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

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

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

Parameters:

• annotation_dict (dict[str, dict[str, ElementTree]]) – A dictionary of Sentinel-1 annotation file XML objects (key annotation of the dictionary returned by get_src_meta()).

• 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 dictionary. If the results differ, an error is raised.

• per_pol (bool) – group the results per polarization? In this case, the dictionary becomes nested with the outer dict having the swaths as keys and the inner the polarizations.

• out_type (Literal['int', 'float', 'str']) – Output type to convert the results to.

Return type:

dict[str, dict[str, list[int | float | str] | int | float | str | None]] | list[int | float | str] | int | float | str | None

Returns:

Either a dictionary with results per annotation file (swath, polarization) or a single result, which is identical across annotation files. None is set if the value is not found.

s1ard.metadata.extract.get_osv_info(sid)

Get information about the used OSV file. First, this function attempts to find an auxiliary OSV file matching the scene. If found, its name is returned. If not, it is assumed that it is not yet available and processing was performed using the OSVs found in the source product. In this case, the metadata is searched for the name of an auxiliary OSV file used during L1 generation. If found, its name is returned.

Parameters:

sid (pyroSAR.drivers.ID) – The pyroSAR scene ID object

Returns:

the OSV file’s basename and the OSV type description. None is returned if no OSV file is found.

Return type:

tuple[str or None]

See also

pyroSAR.drivers.SAFE.getOSV

s1ard.metadata.extract.get_prod_meta(tif, src_ids, sar_dir, processor_name)

Get ARD product metadata. Returns a metadata dictionary, which is generated from a measurement GeoTIFF file of the ARD product and function get_metadata of the SAR processor.

Parameters:

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

• src_ids (list[ID]) – List of objects of all source products.

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

• processor_name (str) – The name of the SAR processor. Needed for reading processing metadata, e.g. s1ard.snap.get_metadata().

Return type:

dict[str, Any]

Returns:

A dictionary containing metadata for the product scene.

s1ard.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 (ID) – A pyroSAR ID object generated with e.g. pyroSAR.drivers.identify().

Return type:

dict[Literal['manifest', 'annotation'], Union[ElementTree, dict[str, dict[str, ElementTree]]]]

Returns:

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

s1ard.metadata.extract.meta_dict(config, prod_meta, src_ids, compression)

Creates a dictionary containing metadata for a product scene, as well as its source scenes. The dictionary can then be used 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.

• prod_meta (dict) – a metadata dictionary as returned by s1ard.ard.product_info()

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

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

Returns:

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

Return type:

dict

STAC

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.

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