rasterio.windows module

Window utilities and related functions.

A window is an instance of Window

Window(column_offset, row_offset, width, height)

or a 2D N-D array indexer in the form of a tuple.

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

The latter can be evaluated within the context of a given height and width and a boolean flag specifying whether the evaluation is boundless or not. If boundless=True, negative index values do not mean index from the end of the array dimension as they do in the boundless=False case.

The newer float precision read-write window capabilities of Rasterio require instances of Window to be used.

class rasterio.windows.Window(col_off, row_off, width, height)

Bases: object

Windows are rectangular subsets of rasters.

This class abstracts the 2-tuples mentioned in the module docstring and adds methods and new constructors.

col_off, row_off

The offset for the window.

Type: float

width, height

Lengths of the window.

Type: float

Notes

Previously the lengths were called ‘num_cols’ and ‘num_rows’ but this is a bit confusing in the new float precision world and the attributes have been changed. The originals are deprecated.

col_off

crop(height, width): Return a copy cropped to height and width

flatten()

A flattened form of the window.

Returns: col_off, row_off, width, height – Window offsets and lengths.
Return type: float

classmethod from_slices(rows, cols, height=-1, width=-1, boundless=False)

Construct a Window from row and column slices or tuples / lists of start and stop indexes. Converts the rows and cols to offsets, height, and width.

In general, indexes are defined relative to the upper left corner of the dataset: rows=(0, 10), cols=(0, 4) defines a window that is 4 columns wide and 10 rows high starting from the upper left.

Start indexes may be None and will default to 0. Stop indexes may be None and will default to width or height, which must be provided in this case.

Negative start indexes are evaluated relative to the lower right of the dataset: rows=(-2, None), cols=(-2, None) defines a window that is 2 rows high and 2 columns wide starting from the bottom right.

Parameters

rows (slice, tuple, or list) – Slices or 2 element tuples/lists containing start, stop indexes.
cols (slice, tuple, or list) – Slices or 2 element tuples/lists containing start, stop indexes.
height (float) – A shape to resolve relative values against. Only used when a start or stop index is negative or a stop index is None.
width (float) – A shape to resolve relative values against. Only used when a start or stop index is negative or a stop index is None.
boundless (bool, optional) – Whether the inputs are bounded (default) or not.

Return type

Window

height

intersection(other)

Return the intersection of this window and another

Parameters: other (Window) – Another window
Return type: Window

round_lengths(**kwds)

Return a copy with width and height rounded.

Lengths are rounded to the nearest whole number. The offsets are not changed.

Parameters: kwds (dict) – Collects keyword arguments that are no longer used.
Return type: Window

round_offsets(**kwds)

Return a copy with column and row offsets rounded.

Offsets are rounded to the preceding whole number. The lengths are not changed.

Parameters: kwds (dict) – Collects keyword arguments that are no longer used.
Return type: Window

round_shape(**kwds)

row_off

todict()

A mapping of attribute names and values.

Return type: dict

toranges(): Makes an equivalent pair of range tuples

toslices()

Slice objects for use as an ndarray indexer.

Returns: row_slice, col_slice – A pair of slices in row, column order
Return type: slice

width

class rasterio.windows.WindowMethodsMixin

Bases: object

Mixin providing methods for window-related calculations. These methods are wrappers for the functionality in rasterio.windows module.

A subclass with this mixin MUST provide the following properties: transform, height and 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

rasterio.windows.bounds(window, transform, height=0, width=0)

Get the spatial bounds of a window.

Parameters

window (Window) – The input window.
transform (Affine) – an affine transform matrix.

Returns

left, bottom, right, top – A tuple of spatial coordinate bounding values.

Return type

float

rasterio.windows.crop(window, height, width)

Crops a window to given height and width.

Parameters

window (Window.) – The input window.
height (int) – The number of rows and cols in the cropped window.
width (int) – The number of rows and cols in the cropped window.

Returns

A new Window object.

Return type

Window

rasterio.windows.evaluate(window, height, width, boundless=False)

Evaluates a window tuple that may contain relative index values.

The height and width of the array the window targets is the context for evaluation.

Parameters

window (Window or tuple of (rows, cols).) – The input window.
height (int) – The number of rows or columns in the array that the window targets.
width (int) – The number of rows or columns in the array that the window targets.

Returns

A new Window object with absolute index values.

Return type

Window

rasterio.windows.from_bounds(left, bottom, right, top, transform=None, height=None, width=None, precision=None)

Get the window corresponding to the bounding coordinates.

Parameters

left (float, required) – Left (west) bounding coordinates
bottom (float, required) – Bottom (south) bounding coordinates
right (float, required) – Right (east) bounding coordinates
top (float, required) – Top (north) bounding coordinates
transform (Affine, required) – Affine transform matrix.
precision (int, optional) – These parameters are unused, deprecated in rasterio 1.3.0, and will be removed in version 2.0.0.
height (int, optional) – These parameters are unused, deprecated in rasterio 1.3.0, and will be removed in version 2.0.0.
width (int, optional) – These parameters are unused, deprecated in rasterio 1.3.0, and will be removed in version 2.0.0.

Returns

A new Window.

Return type

Window

Raises

WindowError – If a window can’t be calculated.

rasterio.windows.get_data_window(arr, nodata=None)

Window covering the input array’s valid data pixels.

Parameters

arr (numpy ndarray, <= 3 dimensions) –
nodata (number) – If None, will either return a full window if arr is not a masked array, or will use the mask to determine non-nodata pixels. If provided, it must be a number within the valid range of the dtype of the input array.

Return type

Window

rasterio.windows.intersect(*windows)

Test if all given windows intersect.

Parameters: windows (sequence) – One or more Windows.
Returns: True if all windows intersect.
Return type: bool

rasterio.windows.intersection(*windows)

Innermost extent of window intersections.

Will raise WindowError if windows do not intersect.

Parameters: windows (sequence) – One or more Windows.
Return type: Window

rasterio.windows.iter_args(function): Decorator to allow function to take either *args or a single iterable which gets expanded to *args.

rasterio.windows.round_window_to_full_blocks(window, block_shapes, height=0, width=0)

Round window to include full expanse of intersecting tiles.

Parameters

window (Window) – The input window.
block_shapes (tuple of block shapes) – The input raster’s block shape. All bands must have the same block/stripe structure

Return type

Window

rasterio.windows.shape(window, height=-1, width=-1)

The shape of a window.

height and width arguments are optional if there are no negative values in the window.

Parameters

window (Window) – The input window.
height (int, optional) – The number of rows or columns in the array that the window targets.
width (int, optional) – The number of rows or columns in the array that the window targets.

Returns

The number of rows and columns of the window.

Return type

num_rows, num_cols

rasterio.windows.toranges(window): Normalize Windows to range tuples

rasterio.windows.transform(window, transform)

Construct an affine transform matrix relative to a window.

Parameters

window (Window) – The input window.
transform (Affine) – an affine transform matrix.

Returns

The affine transform matrix for the given window

Return type

Affine

rasterio.windows.union(*windows)

Union windows and return the outermost extent they cover.

Parameters: windows (sequence) – One or more Windows.
Return type: Window

rasterio.windows.validate_length_value(instance, attribute, value)

rasterio.windows.window_index(window, height=0, width=0)

Construct a pair of slice objects for ndarray indexing

Starting indexes are rounded down, Stopping indexes are rounded up.

Parameters: window (Window) – The input window.
Returns: row_slice, col_slice – A pair of slices in row, column order
Return type: slice