open_stac#

geowombat.core.stac.open_stac(stac_catalog='microsoft_v1', collection=None, bounds=None, proj_bounds=None, start_date=None, end_date=None, cloud_cover_perc=None, bands=None, chunksize=256, mask_items=None, bounds_query=None, mask_data=False, epsg=None, resolution=None, resampling=Resampling.nearest, nodata_fill=None, view_asset_keys=False, extra_assets=None, out_path='.', max_items=100, max_extra_workers=1)[source]#

Opens a collection from a spatio-temporal asset catalog (STAC).

Parameters:

  • stac_catalog (str) – Choices are [‘element84_v0’, ‘element84_v1, ‘google’, ‘microsoft_v1’].

  • collection (str) –

    The STAC collection to open. Catalog options:

    element84_v0:

    sentinel_s2_l2a_cogs

    element84_v1:

    cop_dem_glo_30 landsat_c2_l2 sentinel_s2_l2a sentinel_s2_l1c sentinel_s1_l1c

    microsoft_v1:

    cop_dem_glo_30 landsat_c2_l1 landsat_c2_l2 landsat_l8_c2_l2 sentinel_s2_l2a sentinel_s1_l1c sentinel_3_lst io_lulc usda_cdl

  • bounds (sequence | str | Path | GeoDataFrame) – The search bounding box. This can also be given with the configuration manager (e.g., gw.config.update(ref_bounds=bounds)). The bounds CRS must be given in WGS/84 lat/lon (i.e., EPSG=4326).

  • proj_bounds (sequence) – The projected bounds to return data. If None (default), the returned bounds are the union of all collection scenes. See bounds in gjoseph92/stackstac for details.

  • start_date (str) – The start search date (yyyy-mm-dd).

  • end_date (str) – The end search date (yyyy-mm-dd).

  • cloud_cover_perc (float | int) – The maximum percentage cloud cover.

  • bands (sequence) – The bands to open.

  • chunksize (int) – The dask chunk size.

  • mask_items (sequence) – The items to mask.

  • bounds_query (Optional[str]) – A query to select bounds from the geopandas.GeoDataFrame.

  • mask_data (Optional[bool]) – Whether to mask the data. Only relevant if mask_items=True.

  • epsg (Optional[int]) – An EPSG code to warp to.

  • resolution (Optional[float | int]) – The cell resolution to resample to.

  • resampling (Optional[rasterio.enumsResampling enum]) – The resampling method.

  • nodata_fill (Optional[float | int]) – A fill value to replace ‘no data’ NaNs.

  • view_asset_keys (Optional[bool]) – Whether to view asset ids.

  • extra_assets (Optional[list]) – Extra assets (non-image assets) to download.

  • out_path (Optional[str | Path]) – The output path to save files to.

  • max_items (Optional[int]) – The maximum number of items to return from the search, even if there are more matching results, passed to pystac_client.ItemSearch. See https://pystac-client.readthedocs.io/en/latest/api.html#pystac_client.ItemSearch for details.

  • max_extra_workers (Optional[int]) – The maximum number of extra assets to download concurrently.

Return type:

DataArray

Returns:

xarray.DataArray

Examples

>>> from geowombat.core.stac import open_stac, merge_stac
>>>
>>> data_l, df_l = open_stac(
>>>     stac_catalog='microsoft_v1',
>>>     collection='landsat_c2_l2',
>>>     start_date='2020-01-01',
>>>     end_date='2021-01-01',
>>>     bounds='map.geojson',
>>>     bands=['red', 'green', 'blue', 'qa_pixel'],
>>>     mask_data=True,
>>>     extra_assets=['ang', 'mtl.txt', 'mtl.xml']
>>> )
>>>
>>> from rasterio.enums import Resampling
>>>
>>> data_s2, df_s2 = open_stac(
>>>     stac_catalog='element84_v1',
>>>     collection='sentinel_s2_l2a',
>>>     start_date='2020-01-01',
>>>     end_date='2021-01-01',
>>>     bounds='map.geojson',
>>>     bands=['blue', 'green', 'red'],
>>>     resampling=Resampling.cubic,
>>>     epsg=int(data_l.epsg.values),
>>>     extra_assets=['granule_metadata']
>>> )
>>>
>>> # Merge two temporal stacks
>>> stack = (
>>>     merge_stac(data_l, data_s2)
>>>     .sel(band='red')
>>>     .mean(dim='time')
>>> )