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.