✨ PySTACAPISearchIterDataPipe to query dynamic STAC Catalogs

[weiji14]

An iterable-style DataPipe to make STAC API queries to dynamic STAC Catalogs! Uses pystac-client to perform the STAC API Item Search on the /search endpoint.

Preview at https://zen3geo--59.org.readthedocs.build/en/59/api.html#zen3geo.datapipes.PySTACAPISearch

Usage (requires planetary-computer>=0.4.7 and pystac-client>=0.5.0):

import planetary_computer
from torchdata.datapipes.iter import IterableWrapper
from zen3geo.datapipes import PySTACAPISearch

# Peform STAC API query using DataPipe
query = dict(
    bbox=[174.5, -41.37, 174.9, -41.19],
    datetime=["2012-02-20T00:00:00Z", "2022-12-22T00:00:00Z"],
    collections=["cop-dem-glo-30"],
)
dp = IterableWrapper(iterable=[query])
dp_pystac_client = dp.search_for_pystac_item(
    catalog_url="https://planetarycomputer.microsoft.com/api/stac/v1",
    modifier=planetary_computer.sign_inplace,
)
# Loop or iterate over the DataPipe stream
it = iter(dp_pystac_client)
stac_item_search = next(it)
stac_items = list(stac_item_search.items())

print(stac_items)
# [<Item id=Copernicus_DSM_COG_10_S42_00_E174_00_DEM>]

print(stac_items[0].properties)
# {'gsd': 30,
#  'datetime': '2021-04-22T00:00:00Z',
#  'platform': 'TanDEM-X',
#  'proj:epsg': 4326,
#  'proj:shape': [3600, 3600],
#  'proj:transform': [0.0002777777777777778,
#   0.0,
#   173.9998611111111,
#   0.0,
#   -0.0002777777777777778,
#   -40.99986111111111]}

TODO:

• Initial implementation with a doctest
• Add unit tests
• Handle other parameters passed to pystac_client.Client.open
• Add unit test to ensure parameters to pystac_client.Client.open works
• Just list pystac-client as a dependency and not both pystac and pystac-client?
• Ensure that STAC_URL environment variable works (actually no, because STAC_URL no longer works, see remove STAC_URL stac-utils/pystac-client#81, patch update at Remove mention of STAC_URL in Client.open docstring stac-utils/pystac-client#317)

Part of #48.

References:

• https://stacindex.org/catalogs?access=public&type=api
• Add STACAPI dataset microsoft/torchgeo#412 (comment)

[weiji14]

Commented out this modifier parameter (see also stac-utils/pystac-client#259) because

1. It's a (cool) new feature done in Add a post-init modifier keyword stac-utils/pystac-client#286, released in pystac-client=0.5.0, but we don't want to pin to a particular pystac-client version.
2. It requires the planetary-computer library to be installed, specifically version 0.4.7+ which includes Feature/sign inplace microsoft/planetary-computer-sdk-for-python#42

So leaving this as an easter egg 🥚 for now, but will include it in the next walkthrough tutorial.