rasterio._io module

Rasterio input/output.

class rasterio._io.BufferedDatasetWriterBase

Bases: rasterio._io.DatasetWriterBase

stop()

Ends the dataset’s life cycle

class rasterio._io.DatasetReaderBase

Bases: rasterio._base.DatasetBase

dataset_mask()

Calculate the dataset’s 2D mask. Derived from the individual band masks provided by read_masks().

Parameters

out_shape, window, boundless and resampling are passed directly to read_masks() (out,) –

Returns

  • ndarray, shape=(self.height, self.width), dtype=’uint8’

  • 0 = nodata, 255 = valid data

  • The dataset mask is calculate 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 as the dataset mask.

  • 2. If an 4-band RGBA 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()

Read a dataset’s raw pixels as an N-d array

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

Parameters
  • indexes (list of ints or a single int, 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).

    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.

    This parameter cannot be combined with out_shape.

  • 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.

    Cannot 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.

  • 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.

Returns

  • Numpy ndarray or a view on a Numpy ndarray

  • 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.

read_masks()

Read raster band masks as a multidimensional array

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

Parameters
  • indexes (list of ints or a single int, 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 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 combine 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 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

  • Numpy ndarray or a view on a Numpy ndarray

  • 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.

sample()

Get the values of a dataset at certain positions

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

Parameters
  • xy (iterable, pairs of floats) – A sequence or generator of (x, y) pairs.

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

Returns

  • Iterable, yielding dataset values for the specified indexes

  • as an ndarray.

class rasterio._io.DatasetWriterBase

Bases: rasterio._io.DatasetReaderBase

Read-write access to raster data and metadata

build_overviews()

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

set_band_description()

Sets the description of a dataset band.

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

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

Returns

Return type

None

set_band_unit()

Sets the unit of measure of a dataset band.

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

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

Returns

Return type

None

start()
stop()

Ends the dataset’s life cycle

update_tags()

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()

Write the src array into indexed bands of the dataset.

If indexes is a list, the src must be a 3D array of matching shape. If an int, the src must be a 2D array.

See read() for usage of the optional window argument.

write_band()

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()

Write a colormap for a band to the dataset.

write_mask()

Write the valid data mask src array into the dataset’s band mask.

The optional window argument takes a tuple like:

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

specifying a raster subset to write into.

write_transform()
class rasterio._io.InMemoryRaster

Bases: object

Class that manages a single-band in memory GDAL raster dataset. Data type is determined from the data type of the input numpy 2D array (image), and must be one of the data types supported by GDAL (see rasterio.dtypes.dtype_rev). Data are populated at create time from the 2D array passed in.

Use the ‘with’ pattern to instantiate this class for automatic closing of the memory dataset.

This class includes attributes that are intended to be passed into GDAL functions: self.dataset self.band self.band_ids (single element array with band ID of this dataset’s band) self.transform (GDAL compatible transform array)

This class is only intended for internal use within rasterio to support IO with GDAL. Other memory based operations should use numpy arrays.

close()
read()
write()
class rasterio._io.MemoryFileBase

Bases: object

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

close()

Close MemoryFile and release allocated memory.

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()

Read size bytes from MemoryFile.

seek()

Seek to position in MemoryFile.

tell()

Tell current position in MemoryFile.

write()

Write data bytes to MemoryFile

rasterio._io.silence_errors()

Intercept GDAL errors

rasterio._io.virtual_file_to_buffer()

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