Drivers

This is the core module of package pyroSAR. It contains the drivers for the different SAR image formats and offers functionality for retrieving metadata, unpacking images, downloading ancillary files like DEMs and Orbit State Vector files as well as archiving scenes in a database. The ID class and its subclasses allow easy and standardized access to the metadata of images from different SAR sensors.

classes

ID	Abstract class for SAR meta data handlers
BEAM_DIMAP	Handler class for BEAM-DIMAP data
CEOS_PSR	Handler class for ALOS-PALSAR data in CEOS format
CEOS_ERS	Handler class for ERS data in CEOS format
EORC_PSR	Handler class for ALOS-2/PALSAR-2 data in EORC (Earth Observation Research Center) Path format
ESA	Handler class for SAR data in ESA format (Envisat ASAR, ERS-1/2)
SAFE	Handler class for Sentinel-1 data
TSX	Handler class for TerraSAR-X and TanDEM-X data
TDM	Handler class for TerraSAR-X and TanDEM-X experimental data
Archive	Utility for storing SAR image metadata in a database

functions

identify	identify a SAR scene and return the appropriate metadata handler object
identify_many	wrapper function for returning metadata handlers of all valid scenes in a list, similar to function identify().
filter_processed	Filter a list of pyroSAR objects to those that have not yet been processed and stored in the defined directory.
getFileObj	Load a file in a SAR scene archive into a readable file object.
parse_date	this function gathers known time formats provided in the different SAR products and converts them to a common standard of the form YYYYMMDDTHHMMSS
drop_archive	drop (delete) a scene database

class pyroSAR.drivers.Archive(dbfile, custom_fields=None, postgres=False, user='postgres', password='1234', host='localhost', port=5432, cleanup=True, legacy=False)

Bases: object

Utility for storing SAR image metadata in a database

Parameters:

• dbfile (str) – the filename for the SpatiaLite database. This might either point to an existing database or will be created otherwise. If postgres is set to True, this will be the name for the PostgreSQL database.

• custom_fields (dict or None) – a dictionary containing additional non-standard database column names and data types; the names must be attributes of the SAR scenes to be inserted (i.e. id.attr) or keys in their meta attribute (i.e. id.meta[‘attr’])

• postgres (bool) – enable postgres driver for the database. Default: False

• user (str) – required for postgres driver: username to access the database. Default: ‘postgres’

• password (str) – required for postgres driver: password to access the database. Default: ‘1234’

• host (str) – required for postgres driver: host where the database is hosted. Default: ‘localhost’

• port (int) – required for postgres driver: port number to the database. Default: 5432

• cleanup (bool) – check whether all registered scenes exist and remove missing entries?

• legacy (bool) – open an outdated database in legacy mode to import into a new database. Opening an outdated database without legacy mode will throw a RuntimeError.

Examples

Ingest all Sentinel-1 scenes in a directory and its sub-directories into the database:

>>> from pyroSAR import Archive, identify
>>> from spatialist.ancillary import finder
>>> dbfile = '/.../scenelist.db'
>>> archive_s1 = '/.../sentinel1/GRD'
>>> scenes_s1 = finder(archive_s1, [r'^S1[AB].*\.zip'], regex=True, recursive=True)
>>> with Archive(dbfile) as archive:
>>>     archive.insert(scenes_s1)

select all Sentinel-1 A/B scenes stored in the database, which

• overlap with a test site

• were acquired in Ground-Range-Detected (GRD) Interferometric Wide Swath (IW) mode before 2018

• contain a VV polarization image

• have not been processed to directory outdir before

>>> from pyroSAR import Archive
>>> from spatialist import Vector
>>> archive = Archive('/.../scenelist.db')
>>> site = Vector('/path/to/site.shp')
>>> outdir = '/path/to/processed/results'
>>> maxdate = '20171231T235959'
>>> selection_proc = archive.select(vectorobject=site, processdir=outdir,
>>>                                 maxdate=maxdate, sensor=('S1A', 'S1B'),
>>>                                 product='GRD', acquisition_mode='IW', vv=1)
>>> archive.close()

Alternatively, the with statement can be used. In this case to just check whether one particular scene is already registered in the database:

>>> from pyroSAR import identify, Archive
>>> scene = identify('S1A_IW_SLC__1SDV_20150330T170734_20150330T170801_005264_006A6C_DA69.zip')
>>> with Archive('/.../scenelist.db') as archive:
>>>     print(archive.is_registered(scene.scene))

When providing ‘postgres’ as driver, a PostgreSQL database will be created at a given host. Additional arguments are required.

>>> from pyroSAR import Archive, identify
>>> from spatialist.ancillary import finder
>>> dbfile = 'scenelist_db'
>>> archive_s1 = '/.../sentinel1/GRD'
>>> scenes_s1 = finder(archive_s1, [r'^S1[AB].*\.zip'], regex=True, recursive=True)
>>> with Archive(dbfile, driver='postgres', user='user', password='password', host='host', port=5432) as archive:
>>>     archive.insert(scenes_s1)

Importing an old database:

>>> from pyroSAR import Archive
>>> db_new = 'scenes.db'
>>> db_old = 'scenes_old.db'
>>> with Archive(db_new) as db:
>>>     with Archive(db_old, legacy=True) as db_old:
>>>         db.import_outdated(db_old)

add_tables(tables)

Add tables to the database per sqlalchemy.schema.Table Tables provided here will be added to the database.

Note

Columns using Geometry must have setting management=True for SQLite, for example: geometry = Column(Geometry('POLYGON', management=True, srid=4326))

Parameters:

tables (sqlalchemy.schema.Table or list[sqlalchemy.schema.Table]) – The table(s) to be added to the database.

cleanup()

Remove all scenes from the database, which are no longer stored in their registered location

close()

close the database connection

drop_element(scene, with_duplicates=False)

Drop a scene from the data table. If duplicates table contains matching entry, it will be moved to the data table.

Parameters:

• scene (str) – a SAR scene

• with_duplicates (bool) – True: delete matching entry in duplicates table False: move matching entry from duplicates into data table

drop_table(table)

Drop a table from the database.

Parameters:

table (str) – the table name

static encode(string, encoding='utf-8')

export2shp(path, table='data')

export the database to a shapefile

Parameters:

• path (str) – the path of the shapefile to be written. This will overwrite other files with the same name. If a folder is given in path it is created if not existing. If the file extension is missing ‘.shp’ is added.

• table (str) – the table to write to the shapefile; either ‘data’ (default) or ‘duplicates’

filter_scenelist(scenelist)

Filter a list of scenes by file names already registered in the database.

Parameters:

scenelist (list[str or ID]) – the scenes to be filtered

Returns:

the file names of the scenes whose basename is not yet registered in the database

Return type:

list[ID]

get_colnames(table='data')

Return the names of all columns of a table.

Returns:

the column names of the chosen table

Return type:

list[str]

get_tablenames(return_all=False)

Return the names of all tables in the database

Parameters:

return_all (bool) – only gives tables data and duplicates on default. Set to True to get all other tables and views created automatically.

Returns:

the table names

Return type:

list[str]

get_unique_directories()

Get a list of directories containing registered scenes

Returns:

the directory names

Return type:

list[str]

import_outdated(dbfile)

import an older database

Parameters:

dbfile (str or Archive) – the old database. If this is a string, the name of a CSV file is expected.

insert(scene_in, pbar=False, test=False)

Insert one or many scenes into the database

Parameters:

• scene_in (str or ID or list[str or ID]) – a SAR scene or a list of scenes to be inserted

• pbar (bool) – show a progress bar?

• test (bool) – should the insertion only be tested or directly be committed to the database?

is_registered(scene)

Simple check if a scene is already registered in the database.

Parameters:

scene (str or ID) – the SAR scene

Returns:

is the scene already registered?

Return type:

bool

move(scenelist, directory, pbar=False)

Move a list of files while keeping the database entries up to date. If a scene is registered in the database (in either the data or duplicates table), the scene entry is directly changed to the new location.

Parameters:

• scenelist (list[str]) – the file locations

• directory (str) – a folder to which the files are moved

• pbar (bool) – show a progress bar?

select(vectorobject=None, mindate=None, maxdate=None, date_strict=True, processdir=None, recursive=False, polarizations=None, **args)

select scenes from the database

Parameters:

• vectorobject (Vector or None) – a geometry with which the scenes need to overlap

• mindate (str or datetime.datetime or None) – the minimum acquisition date; strings must be in format YYYYmmddTHHMMSS; default: None

• maxdate (str or datetime.datetime or None) – the maximum acquisition date; strings must be in format YYYYmmddTHHMMSS; default: None

• date_strict (bool) –

  treat dates as strict limits or also allow flexible limits to incorporate scenes whose acquisition period overlaps with the defined limit?

  • strict: start >= mindate & stop <= maxdate

  • not strict: stop >= mindate & start <= maxdate

• processdir (str or None) – A directory to be scanned for already processed scenes; the selected scenes will be filtered to those that have not yet been processed. Default: None

• recursive (bool) – (only if processdir is not None) should also the subdirectories of the processdir be scanned?

• polarizations (list[str] or None) – a list of polarization strings, e.g. [‘HH’, ‘VV’]

• **args – any further arguments (columns), which are registered in the database. See get_colnames()

Returns:

the file names pointing to the selected scenes

Return type:

list[str]

select_duplicates(outname_base=None, scene=None, value='id')

Select scenes from the duplicates table. In case both outname_base and scene are set to None all scenes in the table are returned, otherwise only those that match the attributes outname_base and scene if they are not None.

Parameters:

• outname_base (str) – the basename of the scene

• scene (str) – the scene name

• value (str) – the return value; either ‘id’ or ‘scene’

Returns:

the selected scene(s)

Return type:

list[str]

property size

get the number of scenes registered in the database

Returns:

the number of scenes in (1) the main table and (2) the duplicates table

Return type:

tuple[int]

class pyroSAR.drivers.BEAM_DIMAP(scene)

Bases: ID

Handler class for BEAM-DIMAP data

Sensors:

• SNAP supported sensors

scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

unpack(directory, overwrite=False, exist_ok=False)

Unpack the SAR scene into a defined directory.

Parameters:

• directory (str) – the base directory into which the scene is unpacked

• overwrite (bool) – overwrite an existing unpacked scene?

• exist_ok (bool) – allow existing output files and do not create new ones?

class pyroSAR.drivers.CEOS_ERS(scene)

Bases: ID

Handler class for ERS data in CEOS format

Sensors:

• ERS1

• ERS2

Reference:

ER-IS-EPO-GS-5902-3: Annex C. ERS SAR.SLC/SLC-I. CCT and EXABYTE (ESA 1998)

scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

unpack(directory, overwrite=False, exist_ok=False)

Unpack the SAR scene into a defined directory.

Parameters:

• directory (str) – the base directory into which the scene is unpacked

• overwrite (bool) – overwrite an existing unpacked scene?

• exist_ok (bool) – allow existing output files and do not create new ones?

class pyroSAR.drivers.CEOS_PSR(scene)

Bases: ID

Handler class for ALOS-PALSAR data in CEOS format

Sensors:

• PSR1

• PSR2

PALSAR-1:

References:

• NEB-01006: ALOS/PALSAR Level 1 Product Format Description (JAXA 2006)

• NEB-070062B: ALOS/PALSAR Level 1.1/1.5 Product Format Description (JAXA 2009)

Products / processing levels:

• 1.0

• 1.1

• 1.5

Acquisition modes:

• AB: [SP][HWDPC]

• A: supplemental remarks of the sensor type:

  • S: Wide observation mode

  • P: all other modes

• B: observation mode

  • H: Fine mode

  • W: ScanSAR mode

  • D: Direct downlink mode

  • P: Polarimetry mode

  • C: Calibration mode

PALSAR-2:

Reference:

ALOS-2/PALSAR-2 Level 1.1/1.5/2.1/3.1 CEOS SAR Product Format Description (JAXA 2014).

Products / processing levels:

• 1.0

• 1.1

• 1.5

Acquisition modes:

• SBS: Spotlight mode

• UBS: Ultra-fine mode Single polarization

• UBD: Ultra-fine mode Dual polarization

• HBS: High-sensitive mode Single polarization

• HBD: High-sensitive mode Dual polarization

• HBQ: High-sensitive mode Full (Quad.) polarimetry

• FBS: Fine mode Single polarization

• FBD: Fine mode Dual polarization

• FBQ: Fine mode Full (Quad.) polarimetry

• WBS: Scan SAR nominal [14MHz] mode Single polarization

• WBD: Scan SAR nominal [14MHz] mode Dual polarization

• WWS: Scan SAR nominal [28MHz] mode Single polarization

• WWD: Scan SAR nominal [28MHz] mode Dual polarization

• VBS: Scan SAR wide mode Single polarization

• VBD: Scan SAR wide mode Dual polarization

property led_filename

scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

unpack(directory, overwrite=False, exist_ok=False)

Unpack the SAR scene into a defined directory.

Parameters:

• directory (str) – the base directory into which the scene is unpacked

• overwrite (bool) – overwrite an existing unpacked scene?

• exist_ok (bool) – allow existing output files and do not create new ones?

class pyroSAR.drivers.EORC_PSR(scene)

Bases: ID

Handler class for ALOS-2/PALSAR-2 data in EORC (Earth Observation Research Center) Path format

Sensors:

• PALSAR-2

PALSAR-2:

Reference:

NDX-150019: ALOS-2/PALSAR-2 EORC Path Product Format Description (JAXA 2016)

Products / processing levels:

• 1.5

Acquisition modes:

• FBD: Fine mode Dual polarization

• WBD: Scan SAR nominal [14MHz] mode Dual polarization

property header_filename

scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

unpack(directory, overwrite=False, exist_ok=False)

Unpack the SAR scene into a defined directory.

Parameters:

• directory (str) – the base directory into which the scene is unpacked

• overwrite (bool) – overwrite an existing unpacked scene?

• exist_ok (bool) – allow existing output files and do not create new ones?

class pyroSAR.drivers.ESA(scene)

Bases: ID

Handler class for SAR data in ESA format (Envisat ASAR, ERS-1/2)

Sensors:

• ASAR

• ERS1

• ERS2

scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

unpack(directory, overwrite=False, exist_ok=False)

Unpack the SAR scene into a defined directory.

Parameters:

• directory (str) – the base directory into which the scene is unpacked

• overwrite (bool) – overwrite an existing unpacked scene?

• exist_ok (bool) – allow existing output files and do not create new ones?

class pyroSAR.drivers.ID(metadict)

Bases: object

Abstract class for SAR meta data handlers

bbox(outname=None, driver=None, overwrite=True)

get the bounding box of a scene either as a vector object or written to a file

Parameters:

• outname (str) – the name of the vector file to be written

• driver (str) – the output file format; needs to be defined if the format cannot be auto-detected from the filename extension

• overwrite (bool) – overwrite an existing vector file?

Returns:

the vector object if outname is None and None otherwise

Return type:

Vector or None

See also

spatialist.vector.Vector.bbox

property compression

check whether a scene is compressed into an tarfile or zipfile or not at all

Returns:

either ‘zip’, ‘tar’ or None

Return type:

str or None

examine(include_folders=False)

check whether any items in the SAR scene structure (i.e. files/folders) match the regular expression pattern defined by the class. On success the item is registered in the object as attribute file.

Parameters:

include_folders (bool) – also match folder (or just files)?

Raises:

RuntimeError –

export2dict()

Return the uuid and the metadata that is defined in self.locals as a dictionary

export2sqlite(dbfile)

Export relevant metadata to an SQLite database

Parameters:

dbfile (str) – the database file

findfiles(pattern, include_folders=False)

find files in the scene archive, which match a pattern.

Parameters:

• pattern (str) – the regular expression to match

• include_folders (bool) – also match folders (or just files)?

Returns:

the matched file names

Return type:

list[str]

See also

spatialist.ancillary.finder()

gdalinfo()

read metadata directly from the GDAL SAR image drivers

Returns:

the metadata attributes

Return type:

dict

geometry(outname=None, driver=None, overwrite=True)

get the footprint geometry of a scene either as a vector object or written to a file

Parameters:

• outname (str) – the name of the vector file to be written

• driver (str) – the output file format; needs to be defined if the format cannot be auto-detected from the filename extension

• overwrite (bool) – overwrite an existing vector file?

Returns:

the vector object if outname is None, None otherwise

Return type:

Vector or None

See also

spatialist.vector.Vector.write

getCorners()

Get the bounding box corner coordinates

Returns:

the corner coordinates as a dictionary with keys xmin, ymin, xmax, ymax

Return type:

dict

getFileObj(filename)

Load a file into a readable file object.

Parameters:

filename (str) – the name of a file in the scene archive, easiest to get with method findfiles()

Returns:

a file pointer object

Return type:

io.BytesIO

getGammaImages(directory=None)

list all files processed by GAMMA

Parameters:

directory (str or None) – the directory to be scanned; if left empty the object attribute gammadir is scanned

Returns:

the file names of the images processed by GAMMA

Return type:

list[str]

Raises:

RuntimeError –

getHGT()

get the names of all SRTM HGT tiles overlapping with the SAR scene

Returns:

names of the SRTM HGT tiles

Return type:

list[str]

is_processed(outdir, recursive=False)

check whether a scene has already been processed and stored in the defined output directory (and subdirectories if scanned recursively)

Parameters:

outdir (str) – the directory to be checked

Returns:

does an image matching the scene pattern exist?

Return type:

bool

outname_base(extensions=None)

parse a string containing basic information about the scene in standardized format. Currently, this id contains the sensor (4 digits), acquisition mode (4 digits), orbit (1 digit) and acquisition start time (15 digits)., e.g. S1A__IW___A_20150523T122350.

Parameters:

extensions (list[str]) – the names of additional parameters to append to the basename, e.g. ['orbitNumber_rel']

Returns:

a standardized name unique to the scene

Return type:

str

static parse_date(x)

this function gathers known time formats provided in the different SAR products and converts them to a common standard of the form YYYYMMDDTHHMMSS.

Parameters:

x (str) – the time stamp

Returns:

the converted time stamp in format YYYYmmddTHHMMSS

Return type:

str

abstract quicklook(outname, format='kmz')

export a quick look image of the scene

Parameters:

• outname (str) – the name of the output file

• format (str) – the format of the file to write; currently only kmz is supported

Examples

>>> from pyroSAR import identify
>>> scene = identify('S1A_IW_GRDH_1SDV_20180101T170648_20180101T170713_019964_021FFD_DA78.zip')
>>> scene.quicklook('S1A__IW___A_20180101T170648.kmz')

abstract scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

summary()

print the set of standardized scene metadata attributes

abstract unpack(directory, overwrite=False, exist_ok=False)

Unpack the SAR scene into a defined directory.

Parameters:

• directory (str) – the base directory into which the scene is unpacked

• overwrite (bool) – overwrite an existing unpacked scene?

• exist_ok (bool) – allow existing output files and do not create new ones?

class pyroSAR.drivers.SAFE(scene)

Bases: ID

Handler class for Sentinel-1 data

Sensors:

• S1A

• S1B

References:

• S1-RS-MDA-52-7443 Sentinel-1 IPF Auxiliary Product Specification

• MPC-0243 Masking “No-value” Pixels on GRD Products generated by the Sentinel-1 ESA IPF

getOSV(osvdir=None, osvType='POE', returnMatch=False, useLocal=True, timeout=300, url_option=1)

download Orbit State Vector files for the scene

Parameters:

• osvdir (str) – the directory of OSV files; subdirectories POEORB and RESORB are created automatically; if no directory is defined, the standard SNAP auxdata location is used

• osvType (str or list[str]) – the type of orbit file either ‘POE’, ‘RES’ or a list of both; if both are selected, the best matching file will be retrieved. I.e., POE if available and RES otherwise

• returnMatch (bool) – return the best matching orbit file?

• useLocal (bool) – use locally existing files and do not search for files online if the right file has been found?

• timeout (int or tuple or None) – the timeout in seconds for downloading OSV files as provided to requests.get()

• url_option (int) – the OSV download URL option; see pyroSAR.S1.OSV.catch() for options

Returns:

the best matching OSV file if returnMatch is True or None otherwise

Return type:

str or None

See also

pyroSAR.S1.OSV

quicklook(outname, format='kmz', na_transparent=True)

Write a quicklook file for the scene.

Parameters:

• outname (str) – the file to write

• format (str) –

  the quicklook format. Currently supported options:

  • kmz

• na_transparent (bool) – make NA values transparent?

removeGRDBorderNoise(method='pyroSAR')

mask out Sentinel-1 image border noise.

Parameters:

method (str) –

the border noise removal method to be applied; one of the following:

• ’ESA’: the pure implementation as described by ESA

• ’pyroSAR’: the ESA method plus the custom pyroSAR refinement

See also

removeGRDBorderNoise()

resolution()

Compute the mid-swath resolution of the Sentinel-1 product. For GRD products the resolution is expressed in ground range and in slant range otherwise.

References:

• https://sentinel.esa.int/web/sentinel/user-guides/sentinel-1-sar/resolutions/level-1-single-look-complex

• https://sentinel.esa.int/web/sentinel/user-guides/sentinel-1-sar/resolutions/level-1-ground-range-detected

• https://sentinel.esa.int/web/sentinel/user-guides/sentinel-1-sar/document-library/-/asset_publisher/1dO7RF5fJMbd/content/sentinel-1-product-definition

Returns:

the resolution as (range, azimuth)

Return type:

tuple[float]

scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

unpack(directory, overwrite=False, exist_ok=False)

Unpack the SAR scene into a defined directory.

Parameters:

• directory (str) – the base directory into which the scene is unpacked

• overwrite (bool) – overwrite an existing unpacked scene?

• exist_ok (bool) – allow existing output files and do not create new ones?

class pyroSAR.drivers.TDM(scene)

Bases: TSX

Handler class for TerraSAR-X and TanDEM-X experimental data

Sensors:

• TDM1

References:

• TD-GS-PS-3028 TanDEM-X Experimental Product Description

Acquisition modes:

• HS: High Resolution SpotLight

• SL: SpotLight

• SM: StripMap

Polarisation modes:

• Single (S): all acquisition modes

• Dual (D): High Resolution SpotLight (HS), SpotLight (SL) and StripMap (SM)

• Twin (T): StripMap (SM) (experimental)

• Quad (Q): StripMap (SM) (experimental)

Products:

• CoSSCs: (bi-static) SAR co-registered single look slant range complex products (CoSSCs)

Examples

Ingest all Tandem-X Bistatic scenes in a directory and its sub-directories into the database:

>>> from pyroSAR import Archive, identify
>>> from spatialist.ancillary import finder
>>> dbfile = '/.../scenelist.db'
>>> archive_tdm = '/.../TDM/'
>>> scenes_tdm = finder(archive_tdm, [r'^TDM1.*'], foldermode=2, regex=True, recursive=True)
>>> with Archive(dbfile) as archive:
>>>     archive.insert(scenes_tdm)

scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

class pyroSAR.drivers.TSX(scene)

Bases: ID

Handler class for TerraSAR-X and TanDEM-X data

Sensors:

• TSX1

• TDX1

References:

• TX-GS-DD-3302 TerraSAR-X Basic Product Specification Document

• TX-GS-DD-3303 TerraSAR-X Experimental Product Description

• TD-GS-PS-3028 TanDEM-X Experimental Product Description

• TerraSAR-X Image Product Guide (Airbus Defence and Space)

Acquisition modes:

• ST: Staring Spotlight

• HS: High Resolution SpotLight

• HS300: High Resolution SpotLight 300 MHz

• SL: SpotLight

• SM: StripMap

• SC: ScanSAR

• WS: Wide ScanSAR

Polarisation modes:

• Single (S): all acquisition modes

• Dual (D): High Resolution SpotLight (HS), SpotLight (SL) and StripMap (SM)

• Twin (T): StripMap (SM) (experimental)

• Quad (Q): StripMap (SM) (experimental)

Products:

• SSC: Single Look Slant Range Complex

• MGD: Multi Look Ground Range Detected

• GEC: Geocoded Ellipsoid Corrected

• EEC: Enhanced Ellipsoid Corrected

scanMetadata()

scan SAR scenes for metadata attributes. The returned dictionary is registered as attribute meta by the class upon object initialization. This dictionary furthermore needs to return a set of standardized attribute keys, which are directly registered as object attributes.

Returns:

the derived attributes

Return type:

dict

unpack(directory, overwrite=False, exist_ok=False)

Unpack the SAR scene into a defined directory.

Parameters:

• directory (str) – the base directory into which the scene is unpacked

• overwrite (bool) – overwrite an existing unpacked scene?

• exist_ok (bool) – allow existing output files and do not create new ones?

pyroSAR.drivers.drop_archive(archive)

drop (delete) a scene database

Parameters:

archive (pyroSAR.drivers.Archive) – the database to be deleted

See also

sqlalchemy_utils.functions.drop_database()

Examples

>>> pguser = os.environ.get('PGUSER')
>>> pgpassword = os.environ.get('PGPASSWORD')

>>> db = Archive('test', postgres=True, port=5432, user=pguser, password=pgpassword)
>>> drop_archive(db)

pyroSAR.drivers.filter_processed(scenelist, outdir, recursive=False)

Filter a list of pyroSAR objects to those that have not yet been processed and stored in the defined directory. The search for processed scenes is either done in the directory only or recursively into subdirectories. The scenes must have been processed with pyroSAR in order to follow the right naming scheme.

Parameters:

• scenelist (list[ID]) – a list of pyroSAR objects

• outdir (str) – the processing directory

• recursive (bool) – scan outdir recursively into subdirectories?

Returns:

a list of those scenes, which have not been processed yet

Return type:

list[ID]

pyroSAR.drivers.getFileObj(scene, filename)

Load a file in a SAR scene archive into a readable file object.

Parameters:

• scene (str) – the scene archive. Can be either a directory or a compressed archive of type zip or tar.gz.

• filename (str) – the name of a file in the scene archive, easiest to get with method findfiles()

Returns:

a file object

Return type:

BytesIO

pyroSAR.drivers.identify(scene)

identify a SAR scene and return the appropriate metadata handler object

Parameters:

scene (str) – a file or directory name

Returns:

a pyroSAR metadata handler

Return type:

pyroSAR.drivers.ID

Examples

>>> from pyroSAR import identify
>>> filename = 'S1A_IW_GRDH_1SDV_20180829T170656_20180829T170721_023464_028DE0_F7BD.zip'
>>> scene = identify(filename)
>>> print(scene)
pyroSAR ID object of type SAFE
acquisition_mode: IW
cycleNumber: 148
frameNumber: 167392
lines: 16703
orbit: A
orbitNumber_abs: 23464
orbitNumber_rel: 117
polarizations: ['VV', 'VH']
product: GRD
projection: +proj=longlat +datum=WGS84 +no_defs
samples: 26056
sensor: S1A
spacing: (10.0, 10.0)
start: 20180829T170656
stop: 20180829T170721

pyroSAR.drivers.identify_many(scenes, pbar=False, sortkey=None)

wrapper function for returning metadata handlers of all valid scenes in a list, similar to function identify().

Parameters:

• scenes (list[str or ID]) – the file names of the scenes to be identified

• pbar (bool) – adds a progressbar if True

• sortkey (str or None) – sort the handler object list by an attribute

Returns:

a list of pyroSAR metadata handlers

Return type:

list[ID]

Examples

>>> from pyroSAR import identify_many
>>> files = finder('/path', ['S1*.zip'])
>>> ids = identify_many(files, pbar=False, sortkey='start')

pyroSAR.drivers.parse_date(x)

this function gathers known time formats provided in the different SAR products and converts them to a common standard of the form YYYYMMDDTHHMMSS

Parameters:

x (str or datetime) – the time stamp to be converted

Returns:

the converted time stamp in format YYYYmmddTHHMMSS

Return type:

str