Scene Search

STACArchive	Search for scenes in a SpatioTemporal Asset Catalog.
STACParquetArchive	Search for scenes in STAC geoparquet dump.
check_acquisition_completeness	Check presence of neighboring acquisitions.
collect_neighbors	Collect a scene's neighboring acquisitions in a data take.

class s1ard.search.STACArchive(url, collections, timeout=60, max_retries=20)

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.

See also

pystac_client.Client.open, pystac_client.stac_api_io.StacApiIO

close()

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')

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 | S1B | S1C | S1D

• product (str or list[str] or None) – GRD | SLC

• acquisition_mode (str or list[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.

• 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)

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()

select(sensor=None, product=None, acquisition_mode=None, mindate=None, maxdate=None, frameNumber=None, vectorobject=None, date_strict=True, return_value='scene', filter_antimeridian=True, filter_duplicates=True)

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)

• s1:slice_number (custom)

• s1:total_slices (custom)

• s1:processing_date (custom)

Parameters:

• sensor (str or list[str] or None) – S1A | S1B | S1C | S1D

• product (str or list[str] or None) – GRD | SLC

• acquisition_mode (str or list[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.

• 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

  • slice_number: the slice number (position) in the datatake

  • total_slices: the number of slices (products) in the datatake

  • processing_date: the processing datetime in UTC formatted as YYYYmmddTHHMMSS

• filter_antimeridian (bool) – remove scenes crossing the antimeridian

• filter_duplicates (bool) – Sentinel-1 scenes are often reprocessed. With this, duplicates can be filtered out.

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.check_acquisition_completeness(archive, scenes)

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)

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]