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
- width, height
Lengths of the window.
- Type
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
- 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
- height
- intersection(other)
Return the intersection of this window and another
- round_lengths(**kwds)
Return a copy with width and height rounded.
Lengths are rounded to the nearest whole number. The offsets are not changed.
- 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.
- round_shape(**kwds)
- row_off
- 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
- 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_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
- 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.
- rasterio.windows.crop(window, height, width)
Crops a window to given height and width.
- 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
- Returns
A new Window object with absolute index values.
- Return type
- 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
- 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
- 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
- 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
- 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.
- 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
- 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
- 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.