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_osv_info`	Get information about the used OSV file.
`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.

s1ard.metadata.extract.append_wind_norm(meta, wm_ref_speed, wm_ref_direction)[source]

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_enl(tif, block_size=30, return_arr=False, decimals=2)[source]

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.

Raises:

RuntimeError – if the input array contains only NaN values

Returns:

If return_enl_arr=True, an array of ENL values is returned. Otherwise, the median ENL value is returned. If the ENL array contains only NaN and return_enl_arr=False, the return value is None.

Return type:

float or None or numpy.ndarray

References

[2]

s1ard.metadata.extract.calc_geolocation_accuracy(swath_identifier, ei_tif, etad, decimals=2)[source]

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_performance_estimates(files, decimals=2)[source]

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

s1ard.metadata.extract.calc_pslr_islr(annotation_dict, decimals=2)[source]

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]

s1ard.metadata.extract.calc_wm_ref_stats(wm_ref_speed, wm_ref_direction, epsg, bounds, resolution=915)[source]

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

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, out_type='str')[source]

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

s1ard.metadata.extract.geometry_from_vec(vectorobject)[source]

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

s1ard.metadata.extract.get_header_size(tif)[source]

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

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

s1ard.metadata.extract.get_osv_info(sid)[source]

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]

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.

s1ard.metadata.xml.parse(meta, target, assets, exist_ok=False)[source]

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?

s1ard.metadata.xml.product_xml(meta, target, assets, nsmap, ard_ns, exist_ok=False)[source]

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?

s1ard.metadata.xml.source_xml(meta, target, nsmap, ard_ns, exist_ok=False)[source]

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.

s1ard.metadata.stac.make_catalog(directory, product_type, recursive=True, silent=False)[source]

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

s1ard.metadata.stac.parse(meta, target, assets, exist_ok=False)[source]

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?

s1ard.metadata.stac.product_json(meta, target, assets, exist_ok=False)[source]

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?

s1ard.metadata.stac.source_json(meta, target, exist_ok=False)[source]

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?