rasterio.io module¶
Classes capable of reading and writing datasets
Instances of these classes are called dataset objects.
-
class
rasterio.io.
BufferedDatasetWriter
¶ Bases:
rasterio._io.BufferedDatasetWriterBase
,rasterio.windows.WindowMethodsMixin
,rasterio.transform.TransformMethodsMixin
Maintains data and metadata in a buffer, writing to disk or network only when close() is called.
This allows incremental updates to datasets using formats that don’t otherwise support updates, such as JPEG.
-
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).
- Returns
- Return type
list
-
block_size
()¶ 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.
- Returns
- Return type
int
-
block_window
()¶ 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.
- Returns
- Return type
-
block_windows
()¶ 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 a2 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 a1800 x 3600
image requires reading 2 rows, or 7200 pixels just to get the target 4. The same image with internal256 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 are256 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)
-
build_overviews
()¶ Build overviews at one or more decimation factors for all bands of the dataset.
-
checksum
()¶ 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.
- Returns
- Return type
An int.
-
close
()¶ Close the dataset
-
closed
¶ Test if the dataset is closed
- Returns
- Return type
bool
-
colorinterp
¶ Returns a sequence of
ColorInterp.<enum>
representing color interpretation in band order.To set color interpretation, provide a sequence of
ColorInterp.<enum>
:import rasterio from rasterio.enums import ColorInterp
- with rasterio.open(‘rgba.tif’, ‘r+’) as src:
- src.colorinterp = (
ColorInterp.red, ColorInterp.green, ColorInterp.blue, ColorInterp.alpha)
- Returns
- Return type
tuple
-
colormap
()¶ Returns a dict containing the colormap for a band or None.
-
compression
¶
-
count
¶ The number of raster bands in the dataset
- Returns
- Return type
int
-
crs
¶ The dataset’s coordinate reference system
In setting this property, the value may be a CRS object or an EPSG:nnnn or WKT string.
- Returns
- Return type
-
dataset_mask
()¶ 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:
If a .msk file, dataset-wide alpha, or internal mask exists it will be used for the dataset mask.
Else if the dataset is a 4-band with a shadow nodata value, band 4 will be used as the dataset mask.
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.
- Returns
- Return type
list of str
-
driver
¶
-
dtypes
¶ The data types of each band in index order
- Returns
- Return type
list of str
-
files
¶ Returns a sequence of files associated with the dataset.
- Returns
- 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
()¶ 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
- Returns
- Return type
str
-
get_transform
()¶ Returns a GDAL geotransform in its native form.
-
height
¶
-
index
(x, y, op=<built-in function floor>, precision=None)¶ Returns the (row, col) index of the pixel containing (x, y) given a coordinate reference system.
Use an epsilon, magnitude determined by the precision parameter and sign determined by the op function:
positive for floor, negative for ceil.
- Parameters
x (float) – x value in coordinate reference system
y (float) – y value in coordinate reference system
op (function, optional (default: math.floor)) – Function to convert fractional pixels to whole numbers (floor, ceiling, round)
precision (int, optional (default: None)) – Decimal places of precision in indexing, as in round().
- Returns
(row index, col index)
- Return type
tuple
-
indexes
¶ The 1-based indexes of each band in the dataset
For a 3-band dataset, this property will be
[1, 2, 3]
.- Returns
- Return type
list of int
-
interleaving
¶
-
is_tiled
¶
-
lnglat
()¶
-
mask_flag_enums
¶ Sets of flags describing the sources of band masks.
- all_valid: There are no invalid pixels, all mask values will be
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.
- Returns
- Return type
float
-
nodatavals
¶ Nodata values for each band
Notes
This may not be set.
- Returns
- Return type
list of float
-
offsets
¶ Raster offset for each dataset band
To set offsets, one for each band is required.
- Returns
- Return type
list of float
-
options
¶
-
overviews
()¶
-
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
()¶ 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. Like the fill_value of numpy.ma.MaskedArray, should be value valid for the dataset’s data type.
- 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
()¶ 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.
-
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
()¶ 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.
- Returns
- Return type
list of float
-
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
-
shape
¶
-
start
()¶ Start the dataset’s life cycle
-
stop
()¶ Close the GDAL dataset handle
-
subdatasets
¶ Sequence of subdatasets
-
tag_namespaces
()¶ 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.
- Returns
- Return type
list of str
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.
- Returns
- 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.
- Returns
- Return type
list of str
- Type
A list of str
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.
-
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) – Number of decimal points of precision when computing inverse transform.
- Returns
window
- Return type
-
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
()¶ 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
()¶
-
xy
(row, col, offset='center')¶ Returns the coordinates
(x, y)
of a pixel at row and 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.
offset (str, optional) – Determines if the returned coordinates are for the center of the pixel or for a corner.
- Returns
(x, y)
- Return type
tuple
-
-
class
rasterio.io.
DatasetReader
¶ Bases:
rasterio._io.DatasetReaderBase
,rasterio.windows.WindowMethodsMixin
,rasterio.transform.TransformMethodsMixin
An unbuffered data and metadata reader
-
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).
- Returns
- Return type
list
-
block_size
()¶ 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.
- Returns
- Return type
int
-
block_window
()¶ 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.
- Returns
- Return type
-
block_windows
()¶ 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 a2 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 a1800 x 3600
image requires reading 2 rows, or 7200 pixels just to get the target 4. The same image with internal256 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 are256 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
()¶ 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.
- Returns
- Return type
An int.
-
close
()¶ Close the dataset
-
closed
¶ Test if the dataset is closed
- Returns
- Return type
bool
-
colorinterp
¶ Returns a sequence of
ColorInterp.<enum>
representing color interpretation in band order.To set color interpretation, provide a sequence of
ColorInterp.<enum>
:import rasterio from rasterio.enums import ColorInterp
- with rasterio.open(‘rgba.tif’, ‘r+’) as src:
- src.colorinterp = (
ColorInterp.red, ColorInterp.green, ColorInterp.blue, ColorInterp.alpha)
- Returns
- Return type
tuple
-
colormap
()¶ Returns a dict containing the colormap for a band or None.
-
compression
¶
-
count
¶ The number of raster bands in the dataset
- Returns
- Return type
int
-
crs
¶ The dataset’s coordinate reference system
In setting this property, the value may be a CRS object or an EPSG:nnnn or WKT string.
- Returns
- Return type
-
dataset_mask
()¶ 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:
If a .msk file, dataset-wide alpha, or internal mask exists it will be used for the dataset mask.
Else if the dataset is a 4-band with a shadow nodata value, band 4 will be used as the dataset mask.
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.
- Returns
- Return type
list of str
-
driver
¶
-
dtypes
¶ The data types of each band in index order
- Returns
- Return type
list of str
-
files
¶ Returns a sequence of files associated with the dataset.
- Returns
- 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
()¶ 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
- Returns
- Return type
str
-
get_transform
()¶ Returns a GDAL geotransform in its native form.
-
height
¶
-
index
(x, y, op=<built-in function floor>, precision=None)¶ Returns the (row, col) index of the pixel containing (x, y) given a coordinate reference system.
Use an epsilon, magnitude determined by the precision parameter and sign determined by the op function:
positive for floor, negative for ceil.
- Parameters
x (float) – x value in coordinate reference system
y (float) – y value in coordinate reference system
op (function, optional (default: math.floor)) – Function to convert fractional pixels to whole numbers (floor, ceiling, round)
precision (int, optional (default: None)) – Decimal places of precision in indexing, as in round().
- Returns
(row index, col index)
- Return type
tuple
-
indexes
¶ The 1-based indexes of each band in the dataset
For a 3-band dataset, this property will be
[1, 2, 3]
.- Returns
- Return type
list of int
-
interleaving
¶
-
is_tiled
¶
-
lnglat
()¶
-
mask_flag_enums
¶ Sets of flags describing the sources of band masks.
- all_valid: There are no invalid pixels, all mask values will be
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.
- Returns
- Return type
float
-
nodatavals
¶ Nodata values for each band
Notes
This may not be set.
- Returns
- Return type
list of float
-
offsets
¶ Raster offset for each dataset band
To set offsets, one for each band is required.
- Returns
- Return type
list of float
-
options
¶
-
overviews
()¶
-
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
()¶ 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. Like the fill_value of numpy.ma.MaskedArray, should be value valid for the dataset’s data type.
- 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
()¶ 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.
-
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
()¶ 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.
- Returns
- Return type
list of float
-
shape
¶
-
start
()¶ Start the dataset’s life cycle
-
stop
()¶ Close the GDAL dataset handle
-
subdatasets
¶ Sequence of subdatasets
-
tag_namespaces
()¶ 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.
- Returns
- Return type
list of str
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.
- Returns
- 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.
- Returns
- 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) – Number of decimal points of precision when computing inverse transform.
- Returns
window
- Return type
-
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
()¶
-
xy
(row, col, offset='center')¶ Returns the coordinates
(x, y)
of a pixel at row and 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.
offset (str, optional) – Determines if the returned coordinates are for the center of the pixel or for a corner.
- Returns
(x, y)
- Return type
tuple
-
-
class
rasterio.io.
DatasetWriter
¶ Bases:
rasterio._io.DatasetWriterBase
,rasterio.windows.WindowMethodsMixin
,rasterio.transform.TransformMethodsMixin
An unbuffered data and metadata writer. Its methods write data directly to disk.
-
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).
- Returns
- Return type
list
-
block_size
()¶ 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.
- Returns
- Return type
int
-
block_window
()¶ 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.
- Returns
- Return type
-
block_windows
()¶ 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 a2 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 a1800 x 3600
image requires reading 2 rows, or 7200 pixels just to get the target 4. The same image with internal256 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 are256 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)
-
build_overviews
()¶ Build overviews at one or more decimation factors for all bands of the dataset.
-
checksum
()¶ 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.
- Returns
- Return type
An int.
-
close
()¶ Close the dataset
-
closed
¶ Test if the dataset is closed
- Returns
- Return type
bool
-
colorinterp
¶ Returns a sequence of
ColorInterp.<enum>
representing color interpretation in band order.To set color interpretation, provide a sequence of
ColorInterp.<enum>
:import rasterio from rasterio.enums import ColorInterp
- with rasterio.open(‘rgba.tif’, ‘r+’) as src:
- src.colorinterp = (
ColorInterp.red, ColorInterp.green, ColorInterp.blue, ColorInterp.alpha)
- Returns
- Return type
tuple
-
colormap
()¶ Returns a dict containing the colormap for a band or None.
-
compression
¶
-
count
¶ The number of raster bands in the dataset
- Returns
- Return type
int
-
crs
¶ The dataset’s coordinate reference system
In setting this property, the value may be a CRS object or an EPSG:nnnn or WKT string.
- Returns
- Return type
-
dataset_mask
()¶ 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:
If a .msk file, dataset-wide alpha, or internal mask exists it will be used for the dataset mask.
Else if the dataset is a 4-band with a shadow nodata value, band 4 will be used as the dataset mask.
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.
- Returns
- Return type
list of str
-
driver
¶
-
dtypes
¶ The data types of each band in index order
- Returns
- Return type
list of str
-
files
¶ Returns a sequence of files associated with the dataset.
- Returns
- 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
()¶ 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
- Returns
- Return type
str
-
get_transform
()¶ Returns a GDAL geotransform in its native form.
-
height
¶
-
index
(x, y, op=<built-in function floor>, precision=None)¶ Returns the (row, col) index of the pixel containing (x, y) given a coordinate reference system.
Use an epsilon, magnitude determined by the precision parameter and sign determined by the op function:
positive for floor, negative for ceil.
- Parameters
x (float) – x value in coordinate reference system
y (float) – y value in coordinate reference system
op (function, optional (default: math.floor)) – Function to convert fractional pixels to whole numbers (floor, ceiling, round)
precision (int, optional (default: None)) – Decimal places of precision in indexing, as in round().
- Returns
(row index, col index)
- Return type
tuple
-
indexes
¶ The 1-based indexes of each band in the dataset
For a 3-band dataset, this property will be
[1, 2, 3]
.- Returns
- Return type
list of int
-
interleaving
¶
-
is_tiled
¶
-
lnglat
()¶
-
mask_flag_enums
¶ Sets of flags describing the sources of band masks.
- all_valid: There are no invalid pixels, all mask values will be
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.
- Returns
- Return type
float
-
nodatavals
¶ Nodata values for each band
Notes
This may not be set.
- Returns
- Return type
list of float
-
offsets
¶ Raster offset for each dataset band
To set offsets, one for each band is required.
- Returns
- Return type
list of float
-
options
¶
-
overviews
()¶
-
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
()¶ 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. Like the fill_value of numpy.ma.MaskedArray, should be value valid for the dataset’s data type.
- 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
()¶ 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.
-
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
()¶ 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.
- Returns
- Return type
list of float
-
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
-
shape
¶
-
start
()¶ Start the dataset’s life cycle
-
stop
()¶ Close the GDAL dataset handle
-
subdatasets
¶ Sequence of subdatasets
-
tag_namespaces
()¶ 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.
- Returns
- Return type
list of str
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.
- Returns
- 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.
- Returns
- Return type
list of str
- Type
A list of str
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.
-
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) – Number of decimal points of precision when computing inverse transform.
- Returns
window
- Return type
-
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
()¶ 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
()¶
-
xy
(row, col, offset='center')¶ Returns the coordinates
(x, y)
of a pixel at row and 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.
offset (str, optional) – Determines if the returned coordinates are for the center of the pixel or for a corner.
- Returns
(x, y)
- Return type
tuple
-
-
class
rasterio.io.
MemoryFile
(file_or_bytes=None, dirname=None, filename=None, ext='.tif')¶ Bases:
rasterio._io.MemoryFileBase
A BytesIO-like object, backed by an in-memory file.
This allows formatted files to be read and written without I/O.
A MemoryFile created with initial bytes becomes immutable. A MemoryFile created without initial bytes may be written to using either file-like or dataset interfaces.
Examples
A GeoTIFF can be loaded in memory and accessed using the GeoTIFF format driver
>>> with open('tests/data/RGB.byte.tif', 'rb') as f, MemoryFile(f) as memfile: ... with memfile.open() as src: ... pprint.pprint(src.profile) ... {'count': 3, 'crs': CRS({'init': 'epsg:32618'}), 'driver': 'GTiff', 'dtype': 'uint8', 'height': 718, 'interleave': 'pixel', 'nodata': 0.0, 'tiled': False, 'transform': Affine(300.0379266750948, 0.0, 101985.0, 0.0, -300.041782729805, 2826915.0), 'width': 791}
-
close
()¶
-
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.
-
open
(driver=None, width=None, height=None, count=None, crs=None, transform=None, dtype=None, nodata=None, sharing=False, **kwargs)¶ Open the file and return a Rasterio dataset object.
If data has already been written, the file is opened in ‘r’ mode. Otherwise, the file is opened in ‘w’ mode.
- Parameters
well that there is no path parameter (Note) –
a single dataset and there is no need to specify a (contains) –
path. –
parameters are optional and have the same semantics as the (Other) –
of rasterio.open() (parameters) –
-
read
()¶ Read size bytes from MemoryFile.
-
seek
()¶
-
tell
()¶
-
write
()¶ Write data bytes to MemoryFile
-
-
class
rasterio.io.
ZipMemoryFile
(file_or_bytes=None)¶ Bases:
rasterio.io.MemoryFile
A read-only BytesIO-like object backed by an in-memory zip file.
This allows a zip file containing formatted files to be read without I/O.
-
close
()¶
-
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.
-
open
(path, driver=None, sharing=False, **kwargs)¶ Open a dataset within the zipped stream.
- Parameters
path (str) – Path to a dataset in the zip file, relative to the root of the archive.
parameters are optional and have the same semantics as the (Other) –
of rasterio.open() (parameters) –
- Returns
- Return type
A Rasterio dataset object
-
read
()¶ Read size bytes from MemoryFile.
-
seek
()¶
-
tell
()¶
-
write
()¶ Write data bytes to MemoryFile
-
-
rasterio.io.
get_writer_for_driver
(driver)¶ Return the writer class appropriate for the specified driver.
-
rasterio.io.
get_writer_for_path
(path, driver=None)¶ Return the writer class appropriate for the existing dataset.