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