rasterio._base module

Numpy-free base classes.

class rasterio._base.DatasetBase

Bases: object

Dataset base class

block_shapes

bounds

closed

colorinterp

count

crs

descriptions

files

gcps

rpcs

indexes

mask_flag_enums

meta

nodata

nodatavals

profile

res

subdatasets

transform

units

compression

Compression algorithm’s short name

Type:: str

driver

Format driver used to open the dataset

Type:: str

interleaving

‘pixel’ or ‘band’

Type:: str

kwds

Stored creation option tags

Type:: dict

mode

Access mode

Type:: str

name

Remote or local dataset name

Type:: str

options

Copy of opening options

Type:: dict

photometric

Photometric interpretation’s short name

Type:: str

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

In setting this property, the value may be a CRS object or an EPSG:nnnn or WKT string.

Return type:: CRS

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

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_crs(): Return the GDAL dataset’s stored CRS

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.

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

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

write_transform(value)

rasterio._base.driver_can_create(drivername): Return True if the driver has CREATE capability

rasterio._base.driver_can_create_copy(drivername): Return True if the driver has CREATE_COPY capability

rasterio._base.driver_supports_mode(drivername, creation_mode): Return True if the driver supports the mode

rasterio._base.get_dataset_driver(path)

Get the name of the driver that opens a dataset.

Parameters:: path (rasterio.path.Path or str) – A remote or local dataset path.
Return type:: str