rasterio._io module

Rasterio input/output.

class rasterio._io.BufferedDatasetWriterBase

Bases: DatasetWriterBase

stop()

Close the GDAL dataset handle

class rasterio._io.DatasetReaderBase

Bases: DatasetBase

Provides data and metadata reading methods.

dataset_mask(out=None, out_shape=None, window=None, boundless=False, resampling=Resampling.nearest)

Get the dataset’s 2D valid data mask.

Parameters:

  • out (numpy.ndarray, optional) –

    As with Numpy ufuncs, this is an optional reference to an output array with the same dimensions and shape into which data will be placed.

    Note: the method’s return value may be a view on this array. In other words, out is likely to be an incomplete representation of the method’s results.

    Cannot be combined with out_shape.

  • out_shape (tuple, optional) –

    A tuple describing the output array’s shape. Allows for decimated reads without constructing an output Numpy array.

    Cannot be combined with out.

  • window (a pair (tuple) of pairs of ints or Window, optional) – The optional window argument is a 2 item tuple. The first item is a tuple containing the indexes of the rows at which the window starts and stops and the second is a tuple containing the indexes of the columns at which the window starts and stops. For example, ((0, 2), (0, 2)) defines a 2x2 window at the upper left of the raster dataset.

  • boundless (bool, optional (default False)) – If True, windows that extend beyond the dataset’s extent are permitted and partially or completely filled arrays will be returned as appropriate.

  • resampling (Resampling) – By default, pixel values are read raw or interpolated using a nearest neighbor algorithm from the band cache. Other resampling algorithms may be specified. Resampled pixels are not cached.

Returns:

The dtype of this array is uint8. 0 = nodata, 255 = valid data.

Return type:

Numpy ndarray or a view on a Numpy ndarray

Notes

Note: as with Numpy ufuncs, an object is returned even if you use the optional out argument and the return value shall be preferentially used by callers.

The dataset mask is calculated based on the individual band masks according to the following logic, in order of precedence:

  1. If a .msk file, dataset-wide alpha, or internal mask exists it will be used for the dataset mask.

  2. Else if the dataset is a 4-band with a shadow nodata value, band 4 will be used as the dataset mask.

  3. If a nodata value exists, use the binary OR (|) of the band masks 4. If no nodata value exists, return a mask filled with 255.

Note that this differs from read_masks and GDAL RFC15 in that it applies per-dataset, not per-band (see https://trac.osgeo.org/gdal/wiki/rfc15_nodatabitmask)

read(indexes=None, out=None, window=None, masked=False, out_shape=None, boundless=False, resampling=Resampling.nearest, fill_value=None, out_dtype=None)

Read band data and, optionally, mask as an array.

A smaller (or larger) region of the dataset may be specified and it may be resampled and/or converted to a different data type.

Parameters:

  • indexes (int or list, optional) – If indexes is a list, the result is a 3D array, but is a 2D array if it is a band index number.

  • out (numpy.ndarray, optional) –

    As with Numpy ufuncs, this is an optional reference to an output array into which data will be placed. If the height and width of out differ from that of the specified window (see below), the raster image will be decimated or replicated using the specified resampling method (also see below). This parameter cannot be combined with out_shape.

    Note: the method’s return value may be a view on this array. In other words, out is likely to be an incomplete representation of the method’s results.

  • out_dtype (str or numpy.dtype) – The desired output data type. For example: ‘uint8’ or rasterio.uint16.

  • out_shape (tuple, optional) – A tuple describing the shape of a new output array. See out (above) for notes on image decimation and replication. This parameter cannot be combined with out.

  • window (Window, optional) – The region (slice) of the dataset from which data will be read. The default is the entire dataset.

  • masked (bool, optional) – If masked is True the return value will be a masked array. Otherwise (the default) the return value will be a regular array. Masks will be exactly the inverse of the GDAL RFC 15 conforming arrays returned by read_masks().

  • boundless (bool, optional (default False)) – If True, windows that extend beyond the dataset’s extent are permitted and partially or completely filled arrays will be returned as appropriate.

  • resampling (Resampling) – By default, pixel values are read raw or interpolated using a nearest neighbor algorithm from the band cache. Other resampling algorithms may be specified. Resampled pixels are not cached.

  • fill_value (scalar) – Fill value applied in the boundless=True case only. Like the fill_value of numpy.ma.MaskedArray, should be value valid for the dataset’s data type.

Return type:

Numpy ndarray or a view on a Numpy ndarray

Raises:

RasterioIOError – If the write fails.

Notes

This data is read from the dataset’s band cache, which means that repeated reads of the same windows may avoid I/O.

As with Numpy ufuncs, an object is returned even if you use the optional out argument and the return value shall be preferentially used by callers.

read_masks(indexes=None, out=None, out_shape=None, window=None, boundless=False, resampling=Resampling.nearest)

Read band masks as an array.

A smaller (or larger) region of the dataset may be specified and it may be resampled and/or converted to a different data type.

Parameters:

  • indexes (int or list, optional) – If indexes is a list, the result is a 3D array, but is a 2D array if it is a band index number.

  • out (numpy.ndarray, optional) –

    As with Numpy ufuncs, this is an optional reference to an output array into which data will be placed. If the height and width of out differ from that of the specified window (see below), the raster image will be decimated or replicated using the specified resampling method (also see below). This parameter cannot be combined with out_shape.

    Note: the method’s return value may be a view on this array. In other words, out is likely to be an incomplete representation of the method’s results.

  • out_shape (tuple, optional) – A tuple describing the shape of a new output array. See out (above) for notes on image decimation and replication. This parameter cannot be combined with out.

  • window (Window, optional) – The region (slice) of the dataset from which data will be read. The default is the entire dataset.

  • boundless (bool, optional (default False)) – If True, windows that extend beyond the dataset’s extent are permitted and partially or completely filled arrays will be returned as appropriate.

  • resampling (Resampling) – By default, pixel values are read raw or interpolated using a nearest neighbor algorithm from the band cache. Other resampling algorithms may be specified. Resampled pixels are not cached.

Return type:

Numpy ndarray or a view on a Numpy ndarray

Raises:

RasterioIOError – If the write fails.

Notes

This data is read from the dataset’s band cache, which means that repeated reads of the same windows may avoid I/O.

As with Numpy ufuncs, an object is returned even if you use the optional out argument and the return value shall be preferentially used by callers.

sample(xy, indexes=None, masked=False)

Get the values of a dataset at certain positions

Values are from the nearest pixel. They are not interpolated.

Parameters:

  • xy (iterable) – Pairs of x, y coordinates (floats) in the dataset’s reference system.

  • indexes (int or list of int) – Indexes of dataset bands to sample.

  • masked (bool, default: False) – Whether to mask samples that fall outside the extent of the dataset.

Returns:

Arrays of length equal to the number of specified indexes containing the dataset values for the bands corresponding to those indexes.

Return type:

iterable

statistics(bidx, approx=False, clear_cache=False)

Get min, max, mean, and standard deviation of a raster band.

Parameters:

  • bidx (int) – The band’s index (1-indexed).

  • approx (bool, optional) – If True, statistics will be calculated from reduced resolution data.

  • clear_cache (bool, optional) – If True, saved stats will be deleted and statistics will be recomputed. Requires GDAL version >= 3.2.

Return type:

Statistics

Notes

GDAL will preferentially use statistics kept in raster metadata like images tags or an XML sidecar. If that metadata is out of date, the statistics may not correspond to the actual data.

Additionally, GDAL will save statistics to file metadata as a side effect if that metadata does not already exist.

stats(*, indexes=None, approx=False)

Update stored statistics for all dataset bands.

If no stats are provided, statistics will be computed for all bands of the dataset.

Parameters:

  • indexes (sequence of ints, optional) – A sequence of band indexes, 1-indexed. If not provided, defaults to the indexes of all dataset bands.

  • approx (bool, optional. Default: False) – Set to True if approximate, faster computation of statistics based on overviews or a subset of tiles is acceptable.

Return type:

List of Statistics objects.

class rasterio._io.DatasetWriterBase

Bases: DatasetReaderBase

Read-write access to raster data and metadata

build_overviews(factors, resampling=Resampling.nearest)

Build overviews at one or more decimation factors for all bands of the dataset.

clear_stats()

Clear stored statistics for all dataset bands.

Return type:

None

set_band_description(bidx, value)

Sets the description of a dataset band.

Parameters:

  • bidx (int) – Index of the band (starting with 1).

  • value (string) – A description of the band.

Return type:

None

set_band_unit(bidx, value)

Sets the unit of measure of a dataset band.

Parameters:

  • bidx (int) – Index of the band (starting with 1).

  • value (str) – A label for the band’s unit of measure such as ‘meters’ or ‘degC’. See the Pint project for a suggested list of units.

Return type:

None

update_stats(*, stats=None, indexes=None, approx=False)

Update stored statistics for all dataset bands.

If no stats are provided, statistics will be computed for all bands of the dataset.

Parameters:

  • stats (sequence of Statistics, optional) – A sequence of band statistics objects. Will be zipped together with the indexes sequence.

  • indexes (sequence of ints, optional) – A sequence of band indexes, 1-indexed. If not provided, defaults to src.indexes.

  • approx (bool, optional. Default: False) – Set to True if approximate, faster computation of statistics based on overviews or a subset of tiles is acceptable.

Return type:

None

update_tags(bidx=0, ns=None, **kwargs)

Updates the tags of a dataset or one of its bands.

Tags are pairs of key and value strings. Tags belong to namespaces. The standard namespaces are: default (None) and ‘IMAGE_STRUCTURE’. Applications can create their own additional namespaces.

The optional bidx argument can be used to select the dataset band. The optional ns argument can be used to select a namespace other than the default.

write(arr, indexes=None, window=None, masked=False)

Write the arr array into indexed bands of the dataset.

If given a Numpy MaskedArray and masked is True, the input’s data and mask will be written to the dataset’s bands and band mask. If masked is False, no band mask is written. Instead, the input array’s masked values are filled with the dataset’s nodata value (if defined) or the input’s own fill value.

Parameters:

  • arr (array-like) – This may be a numpy.ma.MaskedArray.

  • indexes (int or list, optional) – Which bands of the dataset to write to. The default is all.

  • window (Window, optional) – The region (slice) of the dataset to which arr will be written. The default is the entire dataset.

  • masked (bool, optional) – Whether or not to write to the dataset’s band mask.

Return type:

None

Raises:

RasterioIOError – If the write fails.

write_band(bidx, src, window=None)

Write the src array into the bidx band.

Band indexes begin with 1: read_band(1) returns the first band.

The optional window argument takes a tuple like:

((row_start, row_stop), (col_start, col_stop))

specifying a raster subset to write into.

write_colormap(bidx, colormap)

Write a colormap for a band to the dataset.

A colormap maps pixel values of a single-band dataset to RGB or RGBA colors.

Parameters:

  • bidx (int) – Index of the band (starting with 1).

  • colormap (Mapping) – Keys are integers and values are 3 or 4-tuples of ints.

Return type:

None

write_mask(mask_array, window=None)

Write to the dataset’s band mask.

Values > 0 represent valid data.

Parameters:

  • mask_array (ndarray) – Values of 0 represent invalid or missing data. Values > 0 represent valid data.

  • window (Window, optional) – A subset of the dataset’s band mask.

Return type:

None

Raises:

RasterioIOError – When no mask is written.

write_transform(transform)
class rasterio._io.MemoryDataset

Bases: DatasetWriterBase

class rasterio._io.MemoryFileBase

Bases: object

Base for a BytesIO-like class backed by an in-memory file.

close()
closed

Test if the dataset is closed

Return type:

bool

exists()

Test if the in-memory file exists.

Returns:

True if the in-memory file exists.

Return type:

bool

getbuffer()

Return a view on bytes of the file.

read(size=-1)

Read bytes from MemoryFile.

Parameters:

size (int) – Number of bytes to read. Default is -1 (all bytes).

Returns:

String of bytes read.

Return type:

bytes

seek(offset, whence=0)
tell()
write(data)

Write data bytes to MemoryFile.

Parameters:

data (bytes)

Returns:

Number of bytes written.

Return type:

int

class rasterio._io.Statistics(min, max, mean, std)

Bases: object

Raster band statistics.

min, max, mean, std

Basic stats of a raster band.

Type:

float

max
mean
min
std
rasterio._io.silence_errors()

Intercept GDAL errors

rasterio._io.validate_resampling(resampling)

Validate that the resampling method is compatible of reads/writes.

rasterio._io.virtual_file_to_buffer(filename)

Read content of a virtual file into a Python bytes buffer.