XarraySource#

class XarraySource[source]#

Bases: RasterSource

A RasterSource for reading an Xarry DataArray.

Warning

XarraySource API is in beta.

Attributes

bbox

Bounding box applied to the source imagery.

crs_transformer

Associated CRSTransformer.

dtype

numpy.dtype of the chips read from this source.

extent

Extent of the RasterSource.

num_channels

Number of channels in the chips read from this source.

shape

Shape of the raster as a (height, width, num_channels) tuple.

__init__(data_array: DataArray, crs_transformer: CRSTransformer, raster_transformers: List[RasterTransformer] = [], channel_order: Optional[Sequence[int]] = None, bbox: Optional[Box] = None, temporal: bool = False)[source]#

Constructor.

Parameters
  • uris (Union[str, List[str]]) – One or more URIs of images. If more than one, the images will be mosaiced together using GDAL.

  • crs_transformer (CRSTransformer) – A CRSTransformer defining the mapping between pixel and map coords.

  • raster_transformers (List['RasterTransformer']) – RasterTransformers to use to transform chips after they are read.

  • channel_order (Optional[Sequence[int]]) – List of indices of channels to extract from raw imagery. Can be a subset of the available channels. If None, all channels available in the image will be read. Defaults to None.

  • bbox (Optional[Box], optional) – User-specified crop of the extent. If None, the full extent available in the source file is used.

  • temporal (bool) – If True, data_array is expected to have a “time” dimension and the chips returned will be of shape (T, H, W, C).

  • data_array (DataArray) –

Methods

__init__(data_array, crs_transformer[, ...])

Constructor.

from_stac(item_or_item_collection[, ...])

Construct an XarraySource from a STAC Item or ItemCollection.

get_chip(window[, bands, time, out_shape])

Read a chip specified by a window from the file.

get_chip_by_map_window(window_map_coords[, ...])

Same as get_chip(), but input is a window in map coords.

get_raw_chip(window[, out_shape])

Return raw chip without applying channel_order or transforms.

resize(chip[, out_shape])

set_bbox(bbox)

Set self.bbox to the given value.

__getitem__(key: Any) ndarray[source]#
Parameters

key (Any) –

Return type

ndarray

__init__(data_array: DataArray, crs_transformer: CRSTransformer, raster_transformers: List[RasterTransformer] = [], channel_order: Optional[Sequence[int]] = None, bbox: Optional[Box] = None, temporal: bool = False)[source]#

Constructor.

Parameters
  • uris (Union[str, List[str]]) – One or more URIs of images. If more than one, the images will be mosaiced together using GDAL.

  • crs_transformer (CRSTransformer) – A CRSTransformer defining the mapping between pixel and map coords.

  • raster_transformers (List['RasterTransformer']) – RasterTransformers to use to transform chips after they are read.

  • channel_order (Optional[Sequence[int]]) – List of indices of channels to extract from raw imagery. Can be a subset of the available channels. If None, all channels available in the image will be read. Defaults to None.

  • bbox (Optional[Box], optional) – User-specified crop of the extent. If None, the full extent available in the source file is used.

  • temporal (bool) – If True, data_array is expected to have a “time” dimension and the chips returned will be of shape (T, H, W, C).

  • data_array (DataArray) –

classmethod from_stac(item_or_item_collection: Union[Item, ItemCollection], raster_transformers: List[RasterTransformer] = [], channel_order: Optional[Sequence[int]] = None, bbox: Optional[Box] = None, bbox_map_coords: Optional[Box] = None, temporal: bool = False, allow_streaming: bool = False, stackstac_args: dict = {'rescale': False}) XarraySource[source]#

Construct an XarraySource from a STAC Item or ItemCollection.

Parameters
  • item_or_item_collection (Union[Item, ItemCollection]) – STAC Item or ItemCollection.

  • raster_transformers (List[RasterTransformer]) – RasterTransformers to use to transform chips after they are read.

  • channel_order (Optional[Sequence[int]]) – List of indices of channels to extract from raw imagery. Can be a subset of the available channels. If None, all channels available in the image will be read. Defaults to None.

  • bbox (Optional[Box]) – User-specified crop of the extent. If None, the full extent available in the source file is used. Mutually exclusive with bbox_map_coords. Defaults to None.

  • bbox_map_coords (Optional[Box]) – User-specified bbox in EPSG:4326 coords of the form (ymin, xmin, ymax, xmax). Useful for cropping the raster source so that only part of the raster is read from. Mutually exclusive with bbox. Defaults to None.

  • temporal (bool) – If True, data_array is expected to have a “time” dimension and the chips returned will be of shape (T, H, W, C).

  • allow_streaming (bool) – If False, load the entire DataArray into memory. Defaults to True.

  • stackstac_args (dict) – Optional arguments to pass to stackstac.stack().

Return type

XarraySource

get_chip(window: Box, bands: Optional[Union[int, Sequence[int], slice]] = None, time: Union[int, Sequence[int], slice] = slice(None, None, None), out_shape: Optional[Tuple[int, ...]] = None) ndarray[source]#

Read a chip specified by a window from the file.

Parameters
  • window (Box) – Bounding box of chip in pixel coordinates.

  • bands (Optional[Union[Sequence[int], slice]], optional) – Subset of bands to read. Note that this will be applied on top of the channel_order (if specified). So if this is an RGB image and channel_order=[2, 1, 0], then using bands=[0] will return the B-channel. Defaults to None.

  • out_shape (Optional[Tuple[int, ...]], optional) – (height, width) of the output chip. If None, no resizing is done. Defaults to None.

  • time (Union[int, Sequence[int], slice]) –

Returns

A chip of shape (height, width, channels).

Return type

np.ndarray

get_chip_by_map_window(window_map_coords: Box, out_shape: Optional[Tuple[int, int]] = None) ndarray#

Same as get_chip(), but input is a window in map coords.

Parameters
Return type

ndarray

get_raw_chip(window: Box, out_shape: Optional[Tuple[int, int]] = None) ndarray#

Return raw chip without applying channel_order or transforms.

Parameters
Returns

Array of shape (…, height, width, channels).

Return type

np.ndarray

resize(chip: ndarray, out_shape: Optional[Tuple[int, int]] = None) ndarray#
Parameters
Return type

ndarray

set_bbox(bbox: Box) None#

Set self.bbox to the given value.

Note

This method is idempotent.

Parameters

bbox (Box) – User-specified bbox in pixel coordinates.

Return type

None

property bbox: Box#

Bounding box applied to the source imagery.

property crs_transformer: RasterioCRSTransformer#

Associated CRSTransformer.

property dtype: dtype#

numpy.dtype of the chips read from this source.

property extent: Box#

Extent of the RasterSource.

property num_channels: int#

Number of channels in the chips read from this source.

Note

Unlike the parent class, XarraySource applies channel_order before raster_transformers. So the number of output channels is not guaranteed to be equal to len(channel_order).

property shape: Tuple[int, int, int]#

Shape of the raster as a (height, width, num_channels) tuple.