Ancillary Functions

This module gathers central functions and classes for general pyroSAR applications.

find_datasets

find pyroSAR datasets in a directory based on their metadata

getargs

get the arguments of a function

groupby

group a list of images by a metadata attribute

groupbyTime

function to group images by their acquisition time difference

hasarg

simple check whether a function takes a parameter as input

multilook_factors

compute multi-looking factors to approximate a square pixel with defined target ground range pixel spacing.

parse_datasetname

Parse the name of a pyroSAR processing product and extract its metadata components as dictionary

seconds

function to extract time in seconds from a file name.

pyroSAR.ancillary.find_datasets(directory, recursive=False, **kwargs)[source]

find pyroSAR datasets in a directory based on their metadata

Parameters:
  • directory (str) – the name of the directory to be searched

  • recursive (bool) – search the directory recursively into subdirectories?

  • kwargs – Metadata attributes for filtering the scene list supplied as key=value. e.g. sensor=’S1A’. Multiple allowed options can be provided in tuples, e.g. sensor=(‘S1A’, ‘S1B’). Any types other than tuples require an exact match, e.g. proc_steps=[‘grd’, ‘mli’, ‘geo’, ‘norm’, ‘db’] will be matched only if these processing steps are contained in the product name in this exact order. The special attributes start and stop can be used for time filtering where start<=value<=stop. See function parse_datasetname() for further options.

Returns:

the file names found in the directory and filtered by metadata attributes

Return type:

list of str

Examples

>>> selection = find_datasets('path/to/files', sensor=('S1A', 'S1B'), polarization='VV')
pyroSAR.ancillary.getargs(func)[source]

get the arguments of a function

Parameters:

func (function) – the function to be checked

Returns:

the argument names

Return type:

list or str

pyroSAR.ancillary.groupby(images, attribute)[source]

group a list of images by a metadata attribute

Parameters:
  • images (list[str]) – the names of the images to be sorted

  • attribute (str) – the name of the attribute used for sorting; see parse_datasetname() for options

Returns:

a list of sub-lists containing the grouped images

Return type:

list[list[str]]

pyroSAR.ancillary.groupbyTime(images, function, time)[source]

function to group images by their acquisition time difference

Parameters:
  • images (list[str]) – a list of image names

  • function (function) – a function to derive the time from the image names; see e.g. seconds()

  • time (int or float) – a time difference in seconds by which to group the images

Returns:

a list of sub-lists containing the grouped images

Return type:

list[list[str]]

pyroSAR.ancillary.hasarg(func, arg)[source]

simple check whether a function takes a parameter as input

Parameters:
  • func (function) – the function to be checked

  • arg (str) – the argument name to be found

Returns:

does the function take this as argument?

Return type:

bool

pyroSAR.ancillary.multilook_factors(source_rg, source_az, target, geometry, incidence)[source]

compute multi-looking factors to approximate a square pixel with defined target ground range pixel spacing.

Parameters:
  • source_rg (int or float) – the range pixel spacing

  • source_az (int or float) – the azimuth pixel spacing

  • target (int or float) – the target pixel spacing of an approximately square pixel

  • geometry (str) – the imaging geometry; either ‘SLANT_RANGE’ or ‘GROUND_RANGE’

  • incidence (int or float) – the angle of incidence

Returns:

the multi-looking factors as (range looks, azimuth looks)

Return type:

tuple[int]

Examples

>>> from pyroSAR.ancillary import multilook_factors
>>> rlks, azlks = multilook_factors(source_rg=2, source_az=13, target=10,
>>>                                 geometry='SLANT_RANGE', incidence=39)
>>> print(rlks, azlks)
4 1
pyroSAR.ancillary.parse_datasetname(name, parse_date=False)[source]

Parse the name of a pyroSAR processing product and extract its metadata components as dictionary

Parameters:
  • name (str) – the name of the file to be parsed

  • parse_date (bool) – parse the start date to a datetime object or just return the string?

Returns:

the metadata attributes

Return type:

dict

Examples

>>> meta = parse_datasetname('S1A__IW___A_20150309T173017_VV_grd_mli_geo_norm_db.tif')
>>> print(sorted(meta.keys()))
['acquisition_mode', 'extensions', 'filename', 'orbit',
'outname_base', 'polarization', 'proc_steps', 'sensor', 'start']
pyroSAR.ancillary.seconds(filename)[source]

function to extract time in seconds from a file name. the format must follow a fixed pattern: YYYYmmddTHHMMSS Images processed with pyroSAR functionalities via module snap or gamma will contain this information.

Parameters:

filename (str) – the name of a file from which to extract the time from

Returns:

the difference between the time stamp in filename and Jan 01 1900 in seconds

Return type:

float

pyroSAR.ancillary.windows_fileprefix(func, path, exc_info)[source]

Helper function for shutil.rmtree() to exceed Windows’ file name length limit of 256 characters. See here for details.

Parameters:

Examples

>>> import shutil
>>> from pyroSAR.ancillary import windows_fileprefix
>>> shutil.rmtree('/path', onerror=windows_fileprefix)