Ancillary Functions

buffer_min_overlap	Buffer a rectangular geometry to a minimum overlap with a second geometry.
buffer_time	Time range buffering
check_scene_consistency	Check the consistency of a scene selection.
check_spacing	Check whether the spacing fits into the MGRS tile boundaries.
combine_polygons	Combine polygon vector objects into one.
compute_hash	Compute the (multi)hash of a file using the specified algorithm.
datamask	Create data masks for a given image file.
date_to_utc	convert a date object to a UTC date string or datetime object.
generate_unique_id	Returns a unique product identifier as a hexadecimal string.
get_kml	Download the Sentinel-2 MGRS grid KML file.
get_max_ext	Gets the maximum extent from a list of geometries.
get_tmp_name	Get the name of a temporary file with defined suffix.
group_by_attr	Group items based on a key function.
group_by_time	Group scenes by their acquisition time difference.
set_logging	Set logging for the current process.
vrt_add_overviews	Add overviews to an existing VRT file.

s1ard.ancillary.buffer_min_overlap(geom1, geom2, percent=1, step=None)

Buffer a rectangular geometry to a minimum overlap with a second geometry. The geometry is iteratively buffered until the minimum overlap is reached. If the overlap of the input geometries is already larger than the defined threshold, a copy of the original geometry is returned.

Parameters:

• geom1 (spatialist.vector.Vector) – the geometry to be buffered

• geom2 (spatialist.vector.Vector) – the reference geometry to intersect with

• percent (int or float) – the minimum overlap in percent of geom1

• step (int or float or None) – the buffering step size. If None, the step size is 0.1 % of the average rectangle corner length.

s1ard.ancillary.buffer_time(start, stop, as_datetime=False, str_format='%Y%m%dT%H%M%S', **kwargs)

Time range buffering

Parameters:

• start (str) – the start time date object to convert; timezone-unaware dates are interpreted as UTC.

• stop (str) – the stop time date object to convert; timezone-unaware dates are interpreted as UTC.

• as_datetime (bool) – return datetime objects instead of strings?

• str_format (str) – the output string format (ignored if as_datetime is True)

• kwargs – time arguments passed to datetime.timedelta()

Returns:

the buffered start and stop time as string or datetime object

Return type:

tuple[str | datetime]

s1ard.ancillary.check_scene_consistency(scenes)

Check the consistency of a scene selection. The following pyroSAR object attributes must be the same:

• sensor

• acquisition_mode

• product

• frameNumber (data take ID)

Parameters:

scenes (list[str or pyroSAR.drivers.ID])

Raises:

RuntimeError –

s1ard.ancillary.check_spacing(spacing)

Check whether the spacing fits into the MGRS tile boundaries.

Parameters:

spacing (int or float) – the target pixel spacing in meters

s1ard.ancillary.combine_polygons(vector, crs=4326, multipolygon=False, layer_name='combined')

Combine polygon vector objects into one. The output is a single vector object with the polygons either stored in separate features or combined into a single multipolygon geometry.

Parameters:

• vector (spatialist.vector.Vector or list[spatialist.vector.Vector]) – the input vector object(s). Providing only one object only makes sense when multipolygon=True.

• crs (int or str) – the target CRS. Default: EPSG:4326

• multipolygon (bool) – combine all polygons into one multipolygon? Default False: write each polygon into a separate feature.

• layer_name (str) – the layer name of the output vector object.

Return type:

spatialist.vector.Vector

s1ard.ancillary.compute_hash(file_path, algorithm='sha256', chunk_size=8192, multihash_encode=True)

Compute the (multi)hash of a file using the specified algorithm.

Parameters:

• file_path (str) – Path to the file.

• algorithm (str) – Hash algorithm to use (default is ‘sha256’).

• chunk_size (int) – Size of chunks to read from the file in bytes (default is 8192).

• multihash_encode (bool) – Encode the hash according to the multihash specification (default is True)? The hash generated by hashlib will be wrapped using multiformats.multihash.wrap().

Returns:

the hexadecimal hash string of the file.

Return type:

str

See also

hashlib, multiformats.multihash

s1ard.ancillary.datamask(measurement, dm_ras, dm_vec)

Create data masks for a given image file. The created raster data mask does not contain a simple mask of nodata values. Rather, a boundary vector geometry containing all valid pixels is created and then rasterized. This boundary geometry (single polygon) is saved as dm_vec. In this case dm_vec is returned. If the input image only contains nodata values, no raster data mask is created, and an empty dummy vector mask is created. In this case the function will return None.

Parameters:

• measurement (str) – the binary image file

• dm_ras (str) – the name of the raster data mask

• dm_vec (str) – the name of the vector data mask

Returns:

dm_vec if the vector data mask contains a geometry or None otherwise

Return type:

str or None

s1ard.ancillary.date_to_utc(date, as_datetime=False, str_format='%Y%m%dT%H%M%S')

convert a date object to a UTC date string or datetime object.

Parameters:

• date (str or datetime or None) – the date object to convert; timezone-unaware dates are interpreted as UTC.

• as_datetime (bool) – return a datetime object instead of a string?

• str_format (str) – the output string format (ignored if as_datetime is True)

Returns:

the date string or datetime object in UTC time zone

Return type:

str or datetime or None

s1ard.ancillary.generate_unique_id(encoded_str)

Returns a unique product identifier as a hexadecimal string. The CRC-16 algorithm used to compute the unique identifier is CRC-CCITT (0xFFFF).

Parameters:

encoded_str (bytes) – A string that should be used to generate a unique id from. The string needs to be encoded; e.g.: 'abc'.encode()

Returns:

p_id – The unique product identifier.

Return type:

str

s1ard.ancillary.get_kml()

Download the Sentinel-2 MGRS grid KML file. The target folder is ~/s1ard.

Returns:

the path to the KML file

Return type:

str

s1ard.ancillary.get_max_ext(geometries, buffer=None, crs=None)

Gets the maximum extent from a list of geometries.

Parameters:

• geometries (list[spatialist.vector.Vector]) – List of Vector geometries.

• buffer (float or None) – The buffer in units of the geometries’ CRS to add to the extent.

• crs (str or int or None) – The target CRS of the extent. If None (default) the extent is expressed in the CRS of the input geometries.

Returns:

max_ext – The maximum extent of the selected Vector geometries including the chosen buffer.

Return type:

dict

s1ard.ancillary.get_tmp_name(suffix)

Get the name of a temporary file with defined suffix. Files are placed in a subdirectory ‘s1ard’ of the regular temporary directory so the latter is not flooded with too many files in case they are not properly deleted.

Parameters:

suffix (str) – the file suffix/extension, e.g. ‘.tif’

s1ard.ancillary.group_by_attr(items, key_fn)

Group items based on a key function.

Parameters:

• items (List[TypeVar(T)]) – The list of arbitrary items to group.

• key_fn (Callable[[TypeVar(T)], TypeVar(K)]) – A function that extracts a key from each item.

Return type:

List[List[TypeVar(T)]]

Returns:

A list of groups, where each group is a list of items with the same key.

Example

>>> list_in = ['abc', 'axy', 'brt', 'btk']
>>> print(group_by_attr(list_in, lambda x: x[0]))
[['abc', 'axy'], ['brt', 'btk']]

>>> list_in = [{'a': 1}, {'a': 2}, {'a': 1}, {'a': 2}]
>>> print(group_by_attr(list_in, lambda x: x['a']))
[[{'a': 1}, {'a': 1}], [{'a': 2}, {'a': 2}]]

s1ard.ancillary.group_by_time(scenes, time=3)

Group scenes by their acquisition time difference.

Parameters:

• scenes (list[pyroSAR.drivers.ID or str]) – a list of image names

• time (int or float) – a time difference in seconds by which to group the scenes. The default of 3 seconds incorporates the overlap between SLCs.

Returns:

a list of sub-lists containing the file names of the grouped scenes

Return type:

list[list[pyroSAR.drivers.ID]]

s1ard.ancillary.set_logging(config, debug=False)

Set logging for the current process.

Parameters:

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

• debug (bool) – Set logging level to DEBUG?

Returns:

The log handler for the current process.

Return type:

logging.Logger

s1ard.ancillary.vrt_add_overviews(vrt, overviews, resampling='AVERAGE')

Add overviews to an existing VRT file. Existing overviews will be overwritten.

Parameters:

• vrt (str) – the VRT file

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

• resampling (str) – the overview resampling method