read

Contents

read#

read(ds: str | CloudPath | Path | tuple[ndarray | MaskedArray, dict] | DataArray | Dataset | DatasetReader | DatasetWriter, resolution: tuple | list | float = None, size: tuple | list = None, window: Any = None, resampling: Resampling = Resampling.nearest, masked: bool = True, indexes: int | list = None, as_type: Any = None, **kwargs) → DataArray | Dataset[source]#

Read a raster dataset from a :

  • xarray (compatibility issues)

  • rasterio.Dataset

  • rasterio opened data (array, metadata)

  • a path.

The resolution can be provided (in dataset unit) as:

  • a tuple or a list of (X, Y) resolutions

  • a float, in which case X resolution = Y resolution

  • None, in which case the dataset resolution will be used

Uses rioxarray.open_rasterio.

Warning

With dask usage, this function is not lazy (yet) when downsampling! (becaise of a odc.geo issue: opendatacube/odc-geo#236)

Parameters:

  • ds (AnyRasterType) – Path to the raster or a rasterio dataset or a xarray

  • resolution (tuple | list | float) – Resolution of the wanted band, in dataset resolution unit (X, Y)

  • size (tuple | list) – Size of the array (width, height). Overrides resolution.

  • window (Any) – Anything that can be returned as a window (i.e. path, gpd.GeoPandas, Iterable, rasterio.Window…). In case of an iterable, assumption is made it corresponds to geographic bounds. For pixel, please provide a rasterio.Window directly.

  • resampling (Resampling) – Resampling method

  • masked (bool) – Get a masked array

  • indexes (int | list) – Indexes of the band to load. Load the whole array if None. Starts at 1 like GDAL.

  • as_type (Any) – Type in which to load the array

  • **kwargs – Optional keyword arguments to pass into rioxarray.open_rasterio().

Returns:

Masked xarray corresponding to the raster data and its metadata

Return type:

AnyXrDataStructure

Example

>>> raster_path = "path/to/raster.tif"
>>> xds1 = read(raster_path)
>>>
>>> # or
>>> with rasterio.open(raster_path) as ds:
>>>    xds2 = read(ds)
>>>
>>> # Assert those two approaches give the same result
>>> xds1 == xds2
True
Contents