Scene Search

`ASF`	Simple SAR metadata handler for scenes in the ASF archive.
`ASFArchive`	Search for scenes in the Alaska Satellite Facility (ASF) catalog.
`STACArchive`	Search for scenes in a SpatioTemporal Asset Catalog.
`STACParquetArchive`	Search for scenes in STAC geoparquet dump.
`asf_select`	Search scenes in the Alaska Satellite Facility (ASF) data catalog.
`check_acquisition_completeness`	Check presence of neighboring acquisitions.
`collect_neighbors`	Collect a scene's neighboring acquisitions in a data take.
`scene_select`	Central scene search utility.

class s1ard.search.ASF(meta)[source]

Bases: ID

Simple SAR metadata handler for scenes in the ASF archive. The interface is consistent with the driver classes in pyroSAR.drivers but does not implement the full functionality due to limited content of the CMR metadata catalog. Registered attributes:

acquisition_mode
coordinates
frameNumber
orbit
orbitNumber_abs
orbitNumber_rel
polarizations
product
projection
sensor
start
stop

scanMetadata()[source]

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 s1ard.search.ASFArchive[source]

Bases: object

Search for scenes in the Alaska Satellite Facility (ASF) catalog. The interface is kept consistent with STACArchive, STACParquetArchive and pyroSAR.drivers.Archive.

static select(sensor=None, product=None, acquisition_mode=None, mindate=None, maxdate=None, vectorobject=None, date_strict=True, return_value='scene')[source]

Select scenes from the ASF catalog. This is a simple wrapper around the function asf_select() to be consistent with the interfaces of the other search classes.

Parameters:

sensor (str or list[str] or None) – S1A or S1B
product (str or list[str] or None) – GRD or SLC
acquisition_mode (str or list[str] or None) – IW, EW or SM
mindate (str or datetime.datetime or None) – the minimum acquisition date; timezone-unaware dates are interpreted as UTC.
maxdate (str or datetime.datetime or None) – the maximum acquisition date; timezone-unaware dates are interpreted as UTC.
vectorobject (spatialist.vector.Vector or None) – a geometry with which the scenes need to overlap. The object may only contain one feature.
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
return_value (str or list[str]) – the metadata return value; see asf_select() for details

See also

asf_select

Returns:: the scene metadata attributes as specified with return_value; see asf_select() for details
Return type:: list[str or tuple[str] or ASF]

class s1ard.search.STACArchive(url, collections, timeout=60, max_retries=20)[source]

Bases: object

Search for scenes in a SpatioTemporal Asset Catalog. Scenes are expected to be unpacked with a folder suffix .SAFE. The interface is kept consistent with ASFArchive, STACParquetArchive and pyroSAR.drivers.Archive.

Parameters:

url (str) – the catalog URL
collections (str or list[str]) – the catalog collection(s) to be searched
timeout (int) – the allowed timeout in seconds
max_retries (int or None) – the number of times to retry requests. Set to None to disable retries.

close()[source]

select(sensor=None, product=None, acquisition_mode=None, mindate=None, maxdate=None, frameNumber=None, vectorobject=None, date_strict=True, check_exist=True, return_value='scene')[source]

Select scenes from the catalog. Duplicates (same acquisition time) are filtered by returning only the last processed product. Used STAC property keys:

platform
start_datetime
end_datetime
created
sar:instrument_mode
sar:product_type
s1:datatake (custom)

Parameters:

sensor (str or list[str] or None) – S1A or S1B
product (str or list[str] or None) – GRD or SLC
acquisition_mode (str or list[str] or None) – IW, EW or SM
mindate (str or datetime.datetime or None) – the minimum acquisition date; timezone-unaware dates are interpreted as UTC.
maxdate (str or datetime.datetime or None) – the maximum acquisition date; timezone-unaware dates are interpreted as UTC.
frameNumber (int or str or list[int or str] or None) – the data take ID in decimal (int) or hexadecimal (str) representation. Requires custom STAC key s1:datatake.
vectorobject (spatialist.vector.Vector or None) – a geometry with which the scenes need to overlap. The object may only contain one feature.
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
check_exist (bool) – check whether found files exist locally?
return_value (str or List[str]) –
the query return value(s). Options:
- acquisition_mode: the sensor’s acquisition mode, e.g., IW, EW, SM
- frameNumber: the frame or datatake number
- geometry_wkb: the scene’s footprint geometry formatted as WKB
- geometry_wkt: the scene’s footprint geometry formatted as WKT
- mindate: the acquisition start datetime in UTC formatted as YYYYmmddTHHMMSS
- maxdate: the acquisition end datetime in UTC formatted as YYYYmmddTHHMMSS
- product: the product type, e.g., SLC, GRD
- scene: the scene’s storage location path (default)
- sensor: the satellite platform, e.g., S1A or S1B

Returns:

If a single return_value is specified: list of values If multiple return_values are specified: list of tuples containing the requested values

Return type:

list or list[tuple]

See also

pystac_client.Client.search

class s1ard.search.STACParquetArchive(files)[source]

Bases: object

Search for scenes in STAC geoparquet dump. Scenes are expected to be unpacked with a folder suffix .SAFE. The interface is kept consistent with ASFArchive, STACArchive and pyroSAR.drivers.Archive.

Parameters:: files (str) – the file search pattern, e.g. /path/to/*parquet

close()[source]

select(sensor=None, product=None, acquisition_mode=None, mindate=None, maxdate=None, frameNumber=None, vectorobject=None, date_strict=True, return_value='scene')[source]

Select scenes from a STAC catalog’s geoparquet dump. Used STAC property keys:

platform
start_datetime
end_datetime
sar:instrument_mode
sar:product_type
s1:datatake (custom)

Parameters:

sensor (str or list[str] or None) – S1A or S1B
product (str or list[str] or None) – GRD or SLC
acquisition_mode (str or list[str] or None) – IW, EW or SM
mindate (str or datetime.datetime or None) – the minimum acquisition date; timezone-unaware dates are interpreted as UTC.
maxdate (str or datetime.datetime or None) – the maximum acquisition date; timezone-unaware dates are interpreted as UTC.
frameNumber (int or str or list[int or str] or None) – the data take ID in decimal (int) or hexadecimal (str) representation. Requires custom STAC key s1:datatake.
vectorobject (spatialist.vector.Vector or None) – a geometry with which the scenes need to overlap
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
return_value (str or List[str]) –
the query return value(s). Options:
- acquisition_mode: the sensor’s acquisition mode, e.g., IW, EW, SM
- frameNumber: the frame or datatake number
- geometry_wkb: the scene’s footprint geometry formatted as WKB
- geometry_wkt: the scene’s footprint geometry formatted as WKT
- mindate: the acquisition start datetime in UTC formatted as YYYYmmddTHHMMSS
- maxdate: the acquisition end datetime in UTC formatted as YYYYmmddTHHMMSS
- product: the product type, e.g., SLC, GRD
- scene: the scene’s storage location path (default)
- sensor: the satellite platform, e.g., S1A or S1B

Returns:

the selected return value(s). Depending on whether a single or multiple values have been defined for return_value, the returned list will contain strings or tuples.

Return type:

List[str] or List[tuple[str]]

See also

stac_geoparquet.arrow.to_parquet, duckdb.query

s1ard.search.asf_select(sensor=None, product=None, acquisition_mode=None, mindate=None, maxdate=None, vectorobject=None, date_strict=True, return_value='scene')[source]

Search scenes in the Alaska Satellite Facility (ASF) data catalog. This is a simple interface to the asf_search package.

Parameters:

sensor (str or None) – S1A|S1B|S1C|S1D
product (str or None) – GRD|SLC
acquisition_mode (str or None) – IW|EW|SM
mindate (str or datetime.datetime or None) – the minimum acquisition date; timezone-unaware dates are interpreted as UTC.
maxdate (str or datetime.datetime or None) – the maximum acquisition date; timezone-unaware dates are interpreted as UTC.
vectorobject (spatialist.vector.Vector or None) – a geometry with which the scenes need to overlap. The object may only contain one feature.
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
return_value (str or List[str]) –
the query return value(s). Options:
- acquisition_mode: the sensor’s acquisition mode, e.g., IW, EW, SM
- frameNumber: the frame or datatake number
- geometry_wkb: the scene’s footprint geometry formatted as WKB
- geometry_wkt: the scene’s footprint geometry formatted as WKT
- mindate: the acquisition start datetime in UTC formatted as YYYYmmddTHHMMSS
- maxdate: the acquisition end datetime in UTC formatted as YYYYmmddTHHMMSS
- product: the product type, e.g., SLC, GRD
- scene: the scene’s storage location path (default)
- sensor: the satellite platform, e.g., S1A or S1B

Returns:

the scene metadata attributes as specified with return_value; the return type is a list of strings, tuples, or ASF objects depending on whether return_type is of type string, list or ASF.

Return type:

list[str or tuple[str] or ASF]

s1ard.search.check_acquisition_completeness(archive, scenes)[source]

Check presence of neighboring acquisitions. Check that for each scene a predecessor and successor can be queried from the database unless the scene is at the start or end of the data take. This ensures that no scene that could be covering an area of interest is missed during processing. In case a scene is suspected to be missing, the Alaska Satellite Facility (ASF) online catalog is cross-checked. An error will only be raised if the locally missing scene is present in the ASF catalog. It may happen that a neighbor is missing and this error is not raised if the scene is also missing on ASF.

Parameters:

archive (pyroSAR.drivers.Archive or STACArchive) – an open scene archive connection
scenes (list[pyroSAR.drivers.ID]) – a list of scenes

Raises:

RuntimeError –

See also

s1ard.search.asf_select

s1ard.search.collect_neighbors(archive, scene, stac_check_exist=True)[source]

Collect a scene’s neighboring acquisitions in a data take.

Parameters:

archive (pyroSAR.drivers.Archive or STACArchive or STACParquetArchive or ASFArchive) – an open scene archive connection
scene (pyroSAR.drivers.ID) – the Sentinel-1 scene to be checked
stac_check_exist (bool) – if archive is of type STACArchive, check the local existence of the scenes?

Returns:

the filenames/URLs of the neighboring scenes

Return type:

list[str]

s1ard.search.scene_select(archive, aoi_tiles=None, aoi_geometry=None, return_value='scene', **kwargs)[source]

Central scene search utility. Selects scenes from a database and returns their file names together with the MGRS tile names for which to process ARD products. The list of MGRS tile names is either identical to the list provided with aoi_tiles, the list of all tiles overlapping with aoi_geometry or vectorobject (via kwargs), or the list of all tiles overlapping with an initial scene search result if no geometry has been defined via aoi_tiles or aoi_geometry. In the latter (most complex) case, the search procedure is as follows:

perform a first search matching all other search parameters

derive all MGRS tile geometries overlapping with the selection

derive the minimum and maximum acquisition times of the selection as search parameters mindate and maxdate

extend the mindate and maxdate search parameters by one minute

perform a second search with the extended time range and the derived MGRS tile geometries

filter the search result to scenes overlapping with the initial time range (if defined via mindate or maxdate)

As consequence, if one defines the search parameters to only return one scene, the neighboring acquisitions will also be returned. This is because the scene overlaps with a set of MGRS tiles of which many or all will also overlap with these neighboring acquisitions. To ensure full coverage of all MGRS tiles, the neighbors of the scene in focus have to be processed too.

This function has three ways to define search geometries. In order of priority overriding others: aoi_tiles > aoi_geometry > vectorobject (via kwargs). In the latter two cases, the search geometry is extended to the common footprint of all MGRS tiles overlapping with the initial geometry to ensure full coverage of all tiles.

Parameters:

archive (pyroSAR.drivers.Archive or STACArchive or STACParquetArchive or ASFArchive) – an open scene archive connection
aoi_tiles (list[str] or None) – a list of MGRS tile names for spatial search
aoi_geometry (str or None) – the name of a vector geometry file for spatial search
return_value (str or List[str]) – the query return value(s). Default ‘scene’: return the scene’s storage location path. See the documentation of archive.select for options.
kwargs – further search arguments passed to the select method of archive. The date_strict argument has no effect. Whether an ARD product is strictly in the defined time range cannot be determined by this function, and it thus has to add a time buffer. When date_strict=True, more scenes will be filtered out in the last step described above.

Returns:

the list of return values; single value:string, multiple values: tuple
the list of MGRS tiles

Return type:

tuple[list[str or tuple[str]], list[str]]