✨ PySTACItemReaderIterDataPipe for reading STAC Items

[weiji14]

An iterable-style DataPipe for STAC items! Uses pystac for reading the files or URLs.

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

Usage

from torchdata.datapipes.iter import IterableWrapper
from zen3geo.datapipes import PySTACItemReader

# Read in STAC Item using DataPipe
item_url: str = "https://planetarycomputer.microsoft.com/api/stac/v1/collections/sentinel-2-l2a/items/S2A_MSIL2A_20220115T032101_R118_T48NUG_20220115T170435"
dp = IterableWrapper(iterable=[item_url])
dp_pystac = dp.read_to_pystac_item()

# Loop or iterate over the DataPipe stream
it = iter(dp_pystac)
stac_item = next(it)

print(stac_item.bbox)
# [103.20205689, 0.81602476, 104.18934086, 1.8096362]

print(stac_item.properties)
# {'datetime': '2022-01-15T03:21:01.024000Z',
#  'platform': 'Sentinel-2A',
#  'proj:epsg': 32648,
#  'instruments': ['msi'],
#  's2:mgrs_tile': '48NUG',
#  'constellation': 'Sentinel 2',
#  's2:granule_id': 'S2A_OPER_MSI_L2A_TL_ESRI_20220115T170436_A034292_T48NUG_N03.00',
#  'eo:cloud_cover': 17.352597,
#  's2:datatake_id': 'GS2A_20220115T032101_034292_N03.00',
#  's2:product_uri': 'S2A_MSIL2A_20220115T032101_N0300_R118_T48NUG_20220115T170435.SAFE',
#  's2:datastrip_id': 'S2A_OPER_MSI_L2A_DS_ESRI_20220115T170436_S20220115T033502_N03.00',
#  's2:product_type': 'S2MSI2A',
#  'sat:orbit_state': 'descending',
#  ...

This dp_pystac DataPipe could then be chained to RioxarrayReader to load the data into an xarray.DataArray, see walkthrough at https://zen3geo.readthedocs.io/en/v0.3.0/walkthrough.html#find-cloud-optimized-geotiffs.

TODO:

• Initial implementation with a doctest that checks the metadata within the pystac.item.Item object.
• Add unit tests
• etc

Part of #48.

References:

• Add STACAPI dataset microsoft/torchgeo#412

[weiji14]

Maybe read_to_pystac_item instead, since we're reading URLs/files to a pystac.Item? See also https://pytorch.org/data/0.4/tutorial.html#naming

Suggested change

	@functional_datapipe("read_from_pystac_item")
	class PySTACItemReaderIterDataPipe(IterDataPipe):
	"""
	Takes files from local disk or URLs (as long as they can be read by pystac)
	and yields :py:class:`pystac.item.Item` objects (functional name:
	``read_from_pystac_item``).
	@functional_datapipe("read_to_pystac_item")
	class PySTACItemReaderIterDataPipe(IterDataPipe):
	"""
	Takes files from local disk or URLs (as long as they can be read by pystac)
	and yields :py:class:`pystac.item.Item` objects (functional name:
	``read_to_pystac_item``).

[weiji14]

Done in d66f1f3