read

Contents

read#

read(ds: str | ~cloudpathlib.cloudpath.CloudPath | ~pathlib.Path | tuple[~numpy.ndarray | ~numpy.ma.MaskedArray, dict] | ~xarray.core.dataarray.DataArray | ~xarray.core.dataset.Dataset | ~rasterio.io.DatasetReader | ~rasterio.io.DatasetWriter, resolution: tuple | list | float = None, size: tuple | list = None, window: ~typing.Any = None, resampling: ~rasterio.enums.Resampling = Resampling.nearest, masked: bool = True, **kwargs) -> (<class 'numpy.ma.MaskedArray'>, <class 'dict'>)[source]#

Read a raster dataset from a rasterio.Dataset or 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

Tip: Use index with a list of one element to keep a 3D array

Parameters:

  • ds (AnyRasterType) – Path to the raster, its dataset, its xarray or a tuple containing its array and metadata

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

  • size (Union[tuple, list]) – Size of the array (width, height). Not used if resolution is provided.

  • 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 (nearest by default)

  • masked (bool) – Get a masked array, True by default (whereas it is False by default in rasterio)

  • **kwargs – Other ds.read() arguments such as indexes.

Returns:

Masked array corresponding to the raster data and its metadata

Return type:

np.ma.masked_array, dict

Example

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