odc-stac

The odc.stac module provides the primary interface for loading SpatioTemporal Asset Catalog (STAC) items into Open Data Cube (ODC) compatible Xarray DataArrays. Key functions include:

• load: The main entry point for loading STAC items.
• parse_item / parse_items: Functions to parse individual or multiple STAC items into internal representations.
• configure_rio / configure_s3_access: Utilities for configuring Rasterio and S3 access settings for cloud-native data.
• extract_collection_metadata: Retrieves metadata for a collection.
• output_geobox: Generates a geobox output.

The odc.stac.bench module provides utilities for benchmarking data loading. It can be used as a Python library in notebooks or as a command-line application.

CLI Usage:

python -m odc.stac.bench [OPTIONS] COMMAND [ARGS]...

Available Commands:

• dask: Launch a local Dask Cluster.
• prepare: Prepare a benchmarking dataset (creates a GeoJSON file).
• report: Collate results from multiple benchmark experiments into a report.
• run: Run a data load benchmark using Dask.

Because odc-stac bridges two different data models, it is important to understand how STAC terminology maps to Open Datacube (ODC) terminology. While they represent similar concepts, the hierarchy and naming differ:

While geo-referencing metadata is typically stored within the data files, it can also be recorded within the STAC Item or ODC Dataset documents to allow for efficient spatial querying without accessing the source files.

There is a key difference in how projections are handled:

• STAC: Using the Projection Extension, each individual band can have its own unique projection.
• ODC: Projection is a Dataset level property. This means all Measurements within a single Dataset must share the same projection. While individual bands (measurements) can have different resolutions or footprints (provided they overlap significantly), they cannot have different projections.

When using odc.stac, be aware of the following assumptions made by the library regarding your STAC data:

1. Collection Consistency: Items within the same collection are assumed to have the same number of bands, the same band names, and the same data_type across the entire collection.
2. Asset Projection: It is assumed that all Assets within a single STAC Item share a common native projection.

The odc.stac.ParsedItem class and its associated types represent the parsed state of a STAC item, making it ready for loading into Xarray.

Key attributes and methods of ParsedItem include:

• assets: Access to the assets within the item.
• crs: The Coordinate Reference System.
• geoboxes: Spatial extents.
• image_geometry: Geometric information about the image.
• resolve_bands: Resolves band information.
• safe_geometry: Returns a safe version of the geometry.
• solar_date_at: Returns the solar date at a specific location.
• strip: Strips metadata or specific components.

Related data structures include RasterBandMetadata, RasterCollectionMetadata, RasterLoadParams, and RasterSource.

ODC enforces stricter consistency than STAC:

• STAC Collection: A loose term that can theoretically contain highly heterogeneous Items.
• ODC Product: A strict container that defines an expected set of Measurements per Dataset. It also assumes that certain metadata, specifically the pixel data type, remains constant across all Datasets for a given Measurement within that Product.

The STAC equivalent to the ODC Product's strictness is the combination of the Item Assets extension and the Raster Extension, which describes the expected structure of Items at the Collection level.

Both STAC and ODC support multiple bands within a single file, but they model the hierarchy differently:

• STAC: Uses an additional level of hierarchy below an Asset via the bands attribute of the EO extension. An Asset points to a resource that may contain multiple bands, with the Asset containing descriptions for each.
• ODC: Does not model Asset explicitly. Instead, the resource path and the specific location within that resource are properties of a Measurement object.

Note: In scenarios where there is a one-to-one mapping between a band and an asset, an ODC Measurement and a STAC Asset are functionally equivalent.

The project uses jupytext to manage notebooks in version control using the py:percent format. Instead of committing .ipynb files, you should commit .py files.

To work with these files in JupyterLab:

1. Install jupytext into your JupyterLab environment.
2. To view a .py file as a notebook, use the "Open With -> Notebook" command.
3. To create a new notebook from a .py file, use the "Pair Notebook with percent Script" command (accessible via Ctrl-Shift-C and searching for "percent").

# Install jupytext in your environment
pip install jupytext

Before running benchmarks, you must define a test site. A site configuration is a JSON file describing a STAC API query and metadata. You can use pre-configured examples like s2-ms-mosaic to generate a GeoJSON file containing the STAC items for the site.

To prepare the dataset using a sample site:

python -m odc.stac.bench prepare --sample-site s2-ms-mosaic

This command writes a GeoJSON file (e.g., s2-ms-mosaic_2020-06-06--P1D.geojson) to your current directory, which is then used as the input for the run command.

To install the latest unreleased code, use a Conda environment file to manage dependencies and install the package directly from the GitHub repository using pip.

Example environment.yml:

channels:
  - conda-forge
dependencies:
  - odc-geo >=0.1.3
  - xarray >=0.20.1
  - numpy
  - dask
  - pandas
  - affine
  - rasterio
  - boto3
  - toolz
  - pystac
  - pystac-client
  - pip =20
  - pip:
    - git+https://github.com/opendatacube/odc-stac/

The primary purpose of odc-stac is to load pystac.Item objects into an xarray.Dataset. This allows you to perform multidimensional analysis on STAC-compliant data using standard xarray workflows.

To use it, perform a search using a pystac_client.Client, then pass the resulting items to odc.stac.load specifying the desired bands and resolution.

import odc.stac
import pystac_client

# 1. Open a STAC catalog
catalog = pystac_client.Client.open(...)

# 2. Search for items
query = catalog.search(...)

# 3. Load items into an xarray.Dataset
xx = odc.stac.load(
    query.items(),
    bands=["red", "green", "blue"],
    resolution=100,
)

# 4. Use xarray methods to visualize
xx.red.plot.imshow(col="time")