Skip to content

sentinel_1

Sentinel1Search #

Sentinel1Search(
    collection: PlanetaryComputerS1Collection | str = GRD,
    date_range: DateLike = None,
    bbox: BBoxLike | None = None,
    intersects: IntersectsLike | None = None,
    logger: Logger = LOGGER,
)

Bases: AbstractStacWrapper

Executable wrapper for Sentinel-1 GRD data on Planetary Computer.

Implements a fluent builder pattern to construct STAC queries for SAR data. Execution and result storage are delegated to an underlying StacSearch client via proxy properties.

Initialize Sentinel1Search.

Parameters:

Name Type Description Default
collection PlanetaryComputerS1Collection | str

The Sentinel-1 STAC collection (default: sentinel-1-grd).

 GRD
date_range DateLike

Temporal filter, native pystac DateLike.

 None
bbox BBoxLike | None

Spatial bounding box filter.

 None
intersects IntersectsLike | None

Spatial GeoJSON geometry filter.

 None
logger Logger

Custom logger instance.

 LOGGER
Source code in src/geospatial_tools/stac/planetary_computer/sentinel_1.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def __init__(
    self,
    collection: PlanetaryComputerS1Collection | str = PlanetaryComputerS1Collection.GRD,
    date_range: DateLike = None,
    bbox: BBoxLike | None = None,
    intersects: IntersectsLike | None = None,
    logger: logging.Logger = LOGGER,
) -> None:
    """
    Initialize Sentinel1Search.

    Args:
        collection: The Sentinel-1 STAC collection (default: sentinel-1-grd).
        date_range: Temporal filter, native pystac DateLike.
        bbox: Spatial bounding box filter.
        intersects: Spatial GeoJSON geometry filter.
        logger: Custom logger instance.
    """
    super().__init__(collection=collection, date_range=date_range, bbox=bbox, intersects=intersects, logger=logger)

    self.instrument_modes: list[PlanetaryComputerS1InstrumentMode] | None = None
    self.polarizations: list[PlanetaryComputerS1Polarization] | None = None
    self.orbit_states: list[PlanetaryComputerS1OrbitState] | None = None
    self.custom_query_params: dict[str, Any] = {}

search_results property #

search_results: list[Item] | None

Proxy property for STAC search results from the underlying client.

downloaded_assets property #

downloaded_assets: list[Asset] | None

Proxy property for downloaded assets from the underlying client.

filter_by_instrument_mode #

filter_by_instrument_mode(
    modes: list[PlanetaryComputerS1InstrumentMode] | PlanetaryComputerS1InstrumentMode,
) -> Self

Filter SAR products by instrument mode (e.g., IW, EW).

Invalidates current search results.

Parameters:

Name Type Description Default
modes list[PlanetaryComputerS1InstrumentMode] | PlanetaryComputerS1InstrumentMode

Single mode or list of PlanetaryComputerS1InstrumentMode.

 required

Returns:

Type Description
Self

The instance itself (Self) for fluent chaining.
Source code in src/geospatial_tools/stac/planetary_computer/sentinel_1.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
def filter_by_instrument_mode(
    self, modes: list[PlanetaryComputerS1InstrumentMode] | PlanetaryComputerS1InstrumentMode
) -> Self:
    """
    Filter SAR products by instrument mode (e.g., IW, EW).

    Invalidates current search results.

    Args:
        modes: Single mode or list of `PlanetaryComputerS1InstrumentMode`.

    Returns:
        The instance itself (Self) for fluent chaining.
    """
    self._invalidate_state()
    if isinstance(modes, list):
        self.instrument_modes = modes
    else:
        self.instrument_modes = [modes]
    return self

filter_by_polarization #

filter_by_polarization(
    polarizations: (
        list[PlanetaryComputerS1Polarization] | PlanetaryComputerS1Polarization
    ),
) -> Self

Filter SAR products by polarization (e.g., VV, VH).

Invalidates current search results. Note: PC STAC requires an exact array match for sar:polarizations.

Parameters:

Name Type Description Default
polarizations list[PlanetaryComputerS1Polarization] | PlanetaryComputerS1Polarization

Single polarization or list of PlanetaryComputerS1Polarization.

 required

Returns:

Type Description
Self

The instance itself (Self) for fluent chaining.
Source code in src/geospatial_tools/stac/planetary_computer/sentinel_1.py 
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def filter_by_polarization(
    self, polarizations: list[PlanetaryComputerS1Polarization] | PlanetaryComputerS1Polarization
) -> Self:
    """
    Filter SAR products by polarization (e.g., VV, VH).

    Invalidates current search results. Note: PC STAC requires an exact array match
    for `sar:polarizations`.

    Args:
        polarizations: Single polarization or list of `PlanetaryComputerS1Polarization`.

    Returns:
        The instance itself (Self) for fluent chaining.
    """
    self._invalidate_state()
    if isinstance(polarizations, list):
        self.polarizations = polarizations
    else:
        self.polarizations = [polarizations]
    return self

filter_by_orbit_state #

filter_by_orbit_state(
    states: list[PlanetaryComputerS1OrbitState] | PlanetaryComputerS1OrbitState,
) -> Self

Filter SAR products by orbit state (ascending or descending).

Invalidates current search results.

Parameters:

Name Type Description Default
states list[PlanetaryComputerS1OrbitState] | PlanetaryComputerS1OrbitState

Single state or list of PlanetaryComputerS1OrbitState.

 required

Returns:

Type Description
Self

The instance itself (Self) for fluent chaining.
Source code in src/geospatial_tools/stac/planetary_computer/sentinel_1.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
def filter_by_orbit_state(
    self, states: list[PlanetaryComputerS1OrbitState] | PlanetaryComputerS1OrbitState
) -> Self:
    """
    Filter SAR products by orbit state (ascending or descending).

    Invalidates current search results.

    Args:
        states: Single state or list of `PlanetaryComputerS1OrbitState`.

    Returns:
        The instance itself (Self) for fluent chaining.
    """
    self._invalidate_state()
    if isinstance(states, list):
        self.orbit_states = states
    else:
        self.orbit_states = [states]
    return self

download #

download(
    bands: list[PlanetaryComputerS1Band | str], base_directory: str | Path
) -> list[Asset] | None

Download Sentinel-1 assets with lowercase band key normalization.

Parameters:

Name Type Description Default
bands list[PlanetaryComputerS1Band | str]

List of bands to download.

 required
base_directory str | Path

Local directory where assets will be saved.

 required

Returns:

Type Description
list[Asset] | None

List of downloaded Asset objects.
Source code in src/geospatial_tools/stac/planetary_computer/sentinel_1.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def download(self, bands: list[PlanetaryComputerS1Band | str], base_directory: str | Path) -> list[Asset] | None:
    """
    Download Sentinel-1 assets with lowercase band key normalization.

    Args:
        bands: List of bands to download.
        base_directory: Local directory where assets will be saved.

    Returns:
        List of downloaded Asset objects.
    """
    # Small specialized override for S1 casing requirements
    lower_bands = [str(b).lower() for b in bands]
    return super().download(bands=lower_bands, base_directory=base_directory)

with_custom_query #

with_custom_query(query_params: dict[str, Any]) -> Self

Merge custom STAC query parameters and invalidate current state.

Parameters:

Name Type Description Default
query_params dict[str, Any]

Dictionary of custom STAC query parameters.

 required

Returns:

Type Description
Self

The instance itself (Self) for fluent chaining.
Source code in src/geospatial_tools/stac/core.py 
939
940
941
942
943
944
945
946
947
948
949
950
951
def with_custom_query(self, query_params: dict[str, Any]) -> Self:
    """
    Merge custom STAC query parameters and invalidate current state.

    Args:
        query_params: Dictionary of custom STAC query parameters.

    Returns:
        The instance itself (Self) for fluent chaining.
    """
    self._invalidate_state()
    self.custom_query_params.update(query_params)
    return self

search #

search() -> list[Item] | None

Execute the STAC search using the built query and parameters.

Returns:

Type Description
list[Item] | None

List of matched pystac Items, or None if no results.
Source code in src/geospatial_tools/stac/core.py 
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
def search(self) -> list[pystac.Item] | None:
    """
    Execute the STAC search using the built query and parameters.

    Returns:
        List of matched pystac Items, or None if no results.
    """
    query = self._build_collection_query()
    query.update(self.custom_query_params)

    collections = [self.collection] if self.collection else None

    self.client.search(
        collections=collections,
        bbox=self.bbox,
        intersects=self.intersects,
        date_range=self.date_range,
        query=query if query else None,
    )
    return self.search_results