pcxarray.io module

pcxarray.io.load_from_url(url: str, bands: List[int] | None = None, geometry: BaseGeometry | None = None, crs: CRS | str | int = 4326, chunks: Dict[str, int] | None = None, clip_to_geometry: bool = False, all_touched: bool = False, max_retries: int = 5, **rioxarray_kwargs: Dict[str, Any] | None) → DataArray

Load a raster dataset from a URL and return it as an xarray DataArray.

Signs the provided URL using the Planetary Computer, opens the raster using rioxarray, optionally selects bands, and clips to a geometry if provided. The raster is returned in its original CRS, but can be clipped using the provided CRS.

Parameters:

  • url (str) – The URL of the raster dataset to load (will be signed if needed).

  • bands (list of int, optional) – List of band indices to select. If None, all bands are loaded.

  • geometry (shapely.geometry.base.BaseGeometry, optional) – Geometry to clip the raster data to. If provided, the raster is clipped to this geometry.

  • crs (pyproj.CRS, str or int, default=4326) – Coordinate reference system for clipping. Does not reproject the raster.

  • chunks (dict, optional) – Chunking options for dask/xarray.

  • clip_to_geometry (bool, default=False) – If True, apply a mask to the raster using the provided geometry.

  • all_touched (bool, default=False) – Whether to include all pixels touched by the geometry during clipping.

  • max_retries (int, default=5) – Maximum number of attempts to load the raster in case of failure.

  • **rioxarray_kwargs (dict, optional) – Additional keyword arguments passed to rioxarray.open_rasterio.

Returns:

The loaded (and optionally clipped) raster data.

Return type:

xarray.DataArray

Raises:

RuntimeError – If the raster cannot be loaded after the specified number of retries.

pcxarray.io.read_single_item(item_gs: GeoSeries, bands: List[str | int] | None = None, geometry: BaseGeometry | None = None, crs: CRS | str | int = 4326, chunks: Dict[str, int] | None = None, clip_to_geometry: bool = True, all_touched: bool = False, **rioxarray_kwargs: Dict[str, Any] | None) → DataArray

Read a single STAC item into an xarray DataArray, selecting and concatenating bands as needed.

Identifies the appropriate asset URLs from a STAC item (GeoSeries), loads each band as a DataArray, reprojects/resamples as needed, and concatenates them along the ‘band’ dimension. If only one band is selected, returns a single DataArray.

Parameters:

  • item_gs (geopandas.GeoSeries) – A STAC item record with asset hrefs and metadata.

  • bands (list of str or int, optional) – Band names or indices to select. If strings, must match asset keys. If None, all valid bands are loaded.

  • geometry (shapely.geometry.base.BaseGeometry, optional) – Geometry to clip the raster data to. If provided, the raster is clipped to this geometry.

  • crs (pyproj.CRS, str or int, default=4326) – Output coordinate reference system for clipping. Does not reproject the raster.

  • chunks (dict, optional) – Chunking options for dask/xarray.

  • clip_to_geometry (bool, default=True) – If True, apply a mask to the raster using the provided geometry.

  • all_touched (bool, default=False) – Whether to include all pixels touched by the geometry during clipping.

  • **rioxarray_kwargs (dict, optional) – Additional keyword arguments passed to rioxarray.open_rasterio.

Returns:

If only one band is selected, returns a DataArray. If multiple bands, returns a concatenated DataArray along the ‘band’ dimension.

Return type:

xarray.DataArray