rasterio.vrt module

rasterio.vrt: a module concerned with GDAL VRTs

class rasterio.vrt.WarpedVRT

Bases: WarpedVRTReaderBase, WindowMethodsMixin, TransformMethodsMixin

A virtual warped dataset.

Abstracts the details of raster warping and allows access to data that is reprojected when read.

This class is backed by an in-memory GDAL VRTWarpedDataset VRT file.

Parameters:

  • src_dataset (dataset object) – The warp source.

  • src_crs (CRS or str, optional) – Overrides the coordinate reference system of src_dataset.

  • src_transform (Affine, optional) – Overrides the transform of src_dataset.

  • src_nodata (float, optional) – Overrides the nodata value of src_dataset, which is the default.

  • crs (CRS or str, optional) – The coordinate reference system at the end of the warp operation. Default: the crs of src_dataset. dst_crs was a deprecated alias for this parameter.

  • transform (Affine, optional) – The transform for the virtual dataset. Default: will be computed from the attributes of src_dataset. dst_transform was a deprecated alias for this parameter.

  • height (int, optional) – The dimensions of the virtual dataset. Defaults: will be computed from the attributes of src_dataset. dst_height and dst_width were deprecated alias for these parameters.

  • width (int, optional) – The dimensions of the virtual dataset. Defaults: will be computed from the attributes of src_dataset. dst_height and dst_width were deprecated alias for these parameters.

  • nodata (float, optional) – Nodata value for the virtual dataset. Default: the nodata value of src_dataset or 0.0. dst_nodata was a deprecated alias for this parameter.

  • resampling (Resampling, optional) – Warp resampling algorithm. Default: Resampling.nearest.

  • tolerance (float, optional) – The maximum error tolerance in input pixels when approximating the warp transformation. Default: 0.125, or one-eigth of a pixel.

  • src_alpha (int, optional) – Index of a source band to use as an alpha band for warping.

  • dst_alpha (int, optional) – Index of a destination band to use as an alpha band for warping.

  • add_alpha (bool, optional) – Whether to add an alpha masking band to the virtual dataset. Default: False. This option will cause deletion of the VRT nodata value.

  • init_dest_nodata (bool, optional) – Whether or not to initialize output to nodata. Default: True.

  • warp_mem_limit (int, optional) – The warp operation’s memory limit in MB. The default (0) means 64 MB with GDAL 2.2.

  • dtype (str, optional) – The working data type for warp operation and output.

  • warp_extras (dict) – GDAL extra warp options. See https://gdal.org/doxygen/structGDALWarpOptions.html.

src_dataset

The dataset object to be virtually warped.

Type:

dataset

resampling

One of the values from rasterio.enums.Resampling. The default is Resampling.nearest.

Type:

int

tolerance

The maximum error tolerance in input pixels when approximating the warp transformation. The default is 0.125.

Type:

float

src_nodata

The source nodata value. Pixels with this value will not be used for interpolation. If not set, it will be default to the nodata value of the source image, if available.

Type:

int or float, optional

dst_nodata

The nodata value used to initialize the destination; it will remain in all areas not covered by the reprojected source. Defaults to the value of src_nodata, or 0 (gdal default).

Type:

int or float, optional

working_dtype

The working data type for warp operation and output.

Type:

str, optional

warp_extras

GDAL extra warp options. See https://gdal.org/doxygen/structGDALWarpOptions.html.

Type:

dict

Examples

>>> with rasterio.open('tests/data/RGB.byte.tif') as src:
...     with WarpedVRT(src, crs='EPSG:3857') as vrt:
...         data = vrt.read()
block_shapes

An ordered list of block shapes for each bands

Shapes are tuples and have the same ordering as the dataset’s shape: (count of image rows, count of image columns).

Return type:

list

block_size(bidx, i, j)

Returns the size in bytes of a particular block

Only useful for TIFF formatted datasets.

Parameters:

  • bidx (int) – Band index, starting with 1.

  • i (int) – Row index of the block, starting with 0.

  • j (int) – Column index of the block, starting with 0.

Return type:

int

block_window(bidx, i, j)

Returns the window for a particular block

Parameters:

  • bidx (int) – Band index, starting with 1.

  • i (int) – Row index of the block, starting with 0.

  • j (int) – Column index of the block, starting with 0.

Return type:

Window

block_windows(bidx=0)

Iterator over a band’s blocks and their windows

The primary use of this method is to obtain windows to pass to read() for highly efficient access to raster block data.

The positional parameter bidx takes the index (starting at 1) of the desired band. This iterator yields blocks “left to right” and “top to bottom” and is similar to Python’s enumerate() in that the first element is the block index and the second is the dataset window.

Blocks are built-in to a dataset and describe how pixels are grouped within each band and provide a mechanism for efficient I/O. A window is a range of pixels within a single band defined by row start, row stop, column start, and column stop. For example, ((0, 2), (0, 2)) defines a 2 x 2 window at the upper left corner of a raster band. Blocks are referenced by an (i, j) tuple where (0, 0) would be a band’s upper left block.

Raster I/O is performed at the block level, so accessing a window spanning multiple rows in a striped raster requires reading each row. Accessing a 2 x 2 window at the center of a 1800 x 3600 image requires reading 2 rows, or 7200 pixels just to get the target 4. The same image with internal 256 x 256 blocks would require reading at least 1 block (if the window entire window falls within a single block) and at most 4 blocks, or at least 512 pixels and at most 2048.

Given an image that is 512 x 512 with blocks that are 256 x 256, its blocks and windows would look like:

Blocks:

        0       256     512
      0 +--------+--------+
        |        |        |
        | (0, 0) | (0, 1) |
        |        |        |
    256 +--------+--------+
        |        |        |
        | (1, 0) | (1, 1) |
        |        |        |
    512 +--------+--------+


Windows:

    UL: ((0, 256), (0, 256))
    UR: ((0, 256), (256, 512))
    LL: ((256, 512), (0, 256))
    LR: ((256, 512), (256, 512))
Parameters:

bidx (int, optional) – The band index (using 1-based indexing) from which to extract windows. A value less than 1 uses the first band if all bands have homogeneous windows and raises an exception otherwise.

Yields:

block, window

bounds

Returns the lower left and upper right bounds of the dataset in the units of its coordinate reference system.

The returned value is a tuple: (lower left x, lower left y, upper right x, upper right y)

checksum(bidx, window=None)

Compute an integer checksum for the stored band

Parameters:

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

  • window (tuple, optional) – A window of the band. Default is the entire extent of the band.

Return type:

An int.

close()

Close the dataset and unwind attached exit stack.

closed

Test if the dataset is closed

Return type:

bool

colorinterp

A sequence of ColorInterp.<enum> in band order.

Return type:

tuple

colormap(bidx)

Returns a dict containing the colormap for a band.

Parameters:

bidx (int) – Index of the band whose colormap will be returned. Band index starts at 1.

Returns:

Mapping of color index value (starting at 0) to RGBA color as a 4-element tuple.

Return type:

dict

Raises:

  • ValueError – If no colormap is found for the specified band (NULL color table).

  • IndexError – If no band exists for the provided index.

compression
count

The number of raster bands in the dataset

Return type:

int

crs

The dataset’s coordinate reference system

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)

descriptions

Descriptions for each dataset band

To set descriptions, one for each band is required.

Return type:

tuple[str | None, …]

driver
dtypes

The data types of each band in index order

Return type:

list of str

files

Returns a sequence of files associated with the dataset.

Return type:

tuple

gcps

ground control points and their coordinate reference system.

This property is a 2-tuple, or pair: (gcps, crs).

gcpslist of GroundControlPoint

Zero or more ground control points.

crs: CRS

The coordinate reference system of the ground control points.

get_gcps()

Get GCPs and their associated CRS.

get_nodatavals()
get_tag_item(ns, dm=None, bidx=0, ovr=None)

Returns tag item value

Parameters:

  • ns (str) – The key for the metadata item to fetch.

  • dm (str) – The domain to fetch for.

  • bidx (int) – Band index, starting with 1.

  • ovr (int) – Overview level

Return type:

str

get_transform()

Returns a GDAL geotransform in its native form.

height
index(x, y, z=None, op=None, precision=None, transform_method=TransformMethod.affine, **rpc_options)

Get the (row, col) index of the pixel containing (x, y).

Parameters:

  • x (float) – x value in coordinate reference system

  • y (float) – y value in coordinate reference system

  • z (float, optional) – Height associated with coordinates. Primarily used for RPC based coordinate transformations. Ignored for affine based transformations. Default: 0.

  • op (function, optional (default: numpy.floor)) – Function to convert fractional pixels to whole numbers (floor, ceiling, round)

  • transform_method (TransformMethod, optional) – The coordinate transformation method. Default: TransformMethod.affine.

  • rpc_options (dict, optional) – Additional arguments passed to GDALCreateRPCTransformer

  • precision (int, optional) – This parameter is unused, deprecated in rasterio 1.3.0, and will be removed in version 2.0.0.

Returns:

tuple – (row index, col index)

Return type:

int, int

indexes

The 1-based indexes of each band in the dataset

For a 3-band dataset, this property will be [1, 2, 3].

Return type:

list of int

interleaving
is_tiled
lnglat() → tuple[float, float]

Geographic coordinates of the dataset’s center.

Return type:

(longitude, latitude) of centroid.

mask_flag_enums

Sets of flags describing the sources of band masks.

Parameters:

  • all_valid (There are no invalid pixels, all mask values will be) –

    1. When used this will normally be the only flag set.

  • per_dataset (The mask band is shared between all bands on the) – dataset.

  • alpha (The mask band is actually an alpha band and may have) – values other than 0 and 255.

  • nodata (Indicates the mask is actually being generated from) – nodata values (mutually exclusive of “alpha”).

Returns:

One list of rasterio.enums.MaskFlags members per band.

Return type:

list [, list*]

Examples

For a 3 band dataset that has masks derived from nodata values:

>>> dataset.mask_flag_enums
([<MaskFlags.nodata: 8>], [<MaskFlags.nodata: 8>], [<MaskFlags.nodata: 8>])
>>> band1_flags = dataset.mask_flag_enums[0]
>>> rasterio.enums.MaskFlags.nodata in band1_flags
True
>>> rasterio.enums.MaskFlags.alpha in band1_flags
False
meta

The basic metadata of this dataset.

mode
name
nodata

The dataset’s single nodata value

Notes

May be set.

Return type:

float

nodatavals

Nodata values for each band

Notes

This may not be set.

Return type:

list of float

offsets

Raster offset for each dataset band

To set offsets, one for each band is required.

Return type:

list of float

options
overviews(bidx)
photometric
profile

Basic metadata and creation options of this dataset.

May be passed as keyword arguments to rasterio.open() to create a clone of this dataset.

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

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

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

  • kwargs (dict) – This is only for backwards compatibility. No keyword arguments are supported other than the ones named above.

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

Return the GDAL dataset’s stored CRS

read_masks(indexes=None, out=None, out_shape=None, window=None, resampling=Resampling.nearest, **kwargs)

Read raster band masks as a multidimensional array

read_transform()

Return the stored GDAL GeoTransform

res

Returns the (width, height) of pixels in the units of its coordinate reference system.

rpcs

Rational polynomial coefficients mapping between pixel and geodetic coordinates.

This property is a dict-like object.

rpcs : RPC instance containing coefficients. Empty if dataset does not have any metadata in the “RPC” domain.

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

scales

Raster scale for each dataset band

To set scales, one for each band is required.

Return type:

list of float

shape
start()

Start the dataset’s life cycle

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.

stop()

Close the GDAL dataset handle

subdatasets

Sequence of subdatasets

tag_namespaces(bidx=0)

Get a list of the dataset’s metadata domains.

Returned items may be passed as ns to the tags method.

Parameters:

  • int (bidx) – Can be used to select a specific band, otherwise the dataset’s general metadata domains are returned.

  • optional – Can be used to select a specific band, otherwise the dataset’s general metadata domains are returned.

Return type:

list of str

tags(bidx=0, ns=None)

Returns a dict containing copies of the dataset or band’s tags.

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 tags of a specific band. The optional ns argument can be used to select a namespace other than the default.

transform

The dataset’s georeferencing transformation matrix

This transform maps pixel row/column coordinates to coordinates in the dataset’s coordinate reference system.

Return type:

Affine

units

one units string for each dataset band

Possible values include ‘meters’ or ‘degC’. See the Pint project for a suggested list of units.

To set units, one for each band is required.

Return type:

list of str

Type:

A list of str

width
window(left, bottom, right, top, precision=None)

Get the window corresponding to the bounding coordinates.

The resulting window is not cropped to the row and column limits of the dataset.

Parameters:

  • left (float) – Left (west) bounding coordinate

  • bottom (float) – Bottom (south) bounding coordinate

  • right (float) – Right (east) bounding coordinate

  • top (float) – Top (north) bounding coordinate

  • precision (int, optional) – This parameter is unused, deprecated in rasterio 1.3.0, and will be removed in version 2.0.0.

Returns:

window

Return type:

Window

window_bounds(window)

Get the bounds of a window

Parameters:

window (rasterio.windows.Window) – Dataset window

Returns:

bounds – x_min, y_min, x_max, y_max for the given window

Return type:

tuple

window_transform(window)

Get the affine transform for a dataset window.

Parameters:

window (rasterio.windows.Window) – Dataset window

Returns:

transform – The affine transform matrix for the given window

Return type:

Affine

write_transform(value)
xy(row, col, z=None, offset='center', transform_method=TransformMethod.affine, **rpc_options)

Get the coordinates x, y of a pixel at row, col.

The pixel’s center is returned by default, but a corner can be returned by setting offset to one of ul, ur, ll, lr.

Parameters:

  • row (int) – Pixel row.

  • col (int) – Pixel column.

  • z (float, optional) – Height associated with coordinates. Primarily used for RPC based coordinate transformations. Ignored for affine based transformations. Default: 0.

  • offset (str, optional) – Determines if the returned coordinates are for the center of the pixel or for a corner.

  • transform_method (TransformMethod, optional) – The coordinate transformation method. Default: TransformMethod.affine.

  • rpc_options (dict, optional) – Additional arguments passed to GDALCreateRPCTransformer

Returns:

x, y

Return type:

tuple