geoutils.open_raster

Contents

geoutils.open_raster#

geoutils.open_raster(filename, is_mask=False, downsample=1, *, as_object_type='dataarray', data_name=None, parse_sensor_metadata=False, **kwargs)[source]#

Open a raster as a Xarray DataArray or Dataset.

This function relies directly on rioxarray.open_rasterio(), to which keyword arguments are passed.

The raster array is always masked (i.e. forced to floating with NaNs) and squeezed (single-band dimension removed).

Use downsample to open a smaller raster by sampling rows and columns at regular intervals. For example, downsample=2 keeps one row and one column out of every two, returning about one quarter of the source pixels.

To open an overview (reduced copy) already stored in the file, pass overview_level through kwargs passed to Rioxarray. Level 0 selects the first stored overview, level 1 the second, and so on. The returned array uses that overview’s shape and resolution. See Rioxarray’s Cloud Optimized GeoTIFF example.

Overviews are also used automatically with downsample: GeoUtils reads the closest suitable overview and resamples it to the requested factor, or reads the original raster if no suitable overview exists. downsample and overview_level cannot be combined because one selects an overview automatically and the other explicitly. See Rasterio’s overview documentation for how reduced reads use stored overviews.

Parameters:

  • filename (str) – Path to the raster file to open.

  • is_mask (bool) – Whether to return the raster values as booleans.

  • downsample (int | float | integer[Any] | floating[Any]) – Downsampling factor (e.g., 2 selects one out of two pixels for every row/column). Rows or columns that do not fill a complete interval are omitted. Default 1 keeps the native resolution.

  • as_object_type (Literal['dataarray', 'dataset']) – Returned representation: dataarray (the default) or dataset. A Dataset contains one raster variable, with multiple bands on its band dimension.

  • data_name (str | None) – Name of the DataArray or Dataset variable. Defaults to the source array name, or raster for an unnamed array returned as a Dataset.

  • parse_sensor_metadata (bool) – Parse sensor metadata from the filename and add it to the raster attributes.

  • kwargs (Any) – Keyword arguments passed to rioxarray.open_rasterio().

Return type:

DataArray | Dataset

Returns:

The opened raster as a DataArray or Dataset with Rioxarray georeferencing.

Contents