RasterWindow and related functions

helpers.RasterWindow is used internally to process large rasters in a moving window. The windows can be generated with helpers.get_windows().

helpers.RasterWindow also works for processing large rasters with helpers.RasterWizard.

RasterWindow

class helpers.RasterWindow(rasterXSize, rasterYSize, xoff, yoff, xsize, ysize, margin=0)

Window for reading/writing a subset of a raster into/from a numpy array.

Helper class for a window (tile) of a large raster to be used for processing in a moving window. The window can have a margin, for algorithms that consider the neighborhood of a pixel as well. For example, a 3x3 kernel needs a margin of 1.

The windows (RasterWindow instances) can be generated with get_windows().

Does not contain any data, only the parameters to read/write a subset of the raster with GDAL and to slice off the margin before writing data to the output dataset.

To read and write the data with GDAL use the gdalin and gdalout properties. Any margin must be removed from the numpy array before writing the data back to the raster, see getslice().

Example:

# Input and output datasets with gdal
ds = gdal.Open("raster.tif") 
driver = gdal.GetDriverByName("GTiff")
dst_ds = driver.CreateCopy(dst_filename, src_ds, strict=0)

# Get windows
windows = get_windows(ds.RasterXSize, ds.RasterYSize, windowsize=windowsize, margin=margin)

# Loop over windows
band = 1
for win in windows:
    a = ds.GetRasterBand(band).ReadAsArray(*win.gdalin) # In this case a is a 2D numpy array
    # Your calculation with numpy array a
    a = a[win.getslice(2)] # Slice off the margin (2D array)
    dst_ds.GetRasterBand(band).WriteArray(filtered, *win.gdalout)

# Close datasets (flushes data to file)
ds = None
dst_ds = None

property gdalin

Parameters for GDAL ReadAsArray() method.

Tuple with x_offset, y_offset, x_size, y_size (including the margins of the window). The tuple can be unpacked with * to be used as parameters with ReadAsArray.

Example:

a = ds.GetRasterBand(band).ReadAsArray(*win.gdalin)

Returns

tuple with x_offset, y_offset, x_size, y_size

property gdalin_no_margin

Parameters for GDAL ReadAsArray() method to read data without margin.

Only for debugging, use gdalin instead.

Returns

tuple with x_offset, y_offset, x_size, y_size including the margins

property gdalout

Parameters for GDAL WriteArray() method.

Tuple with x_offset, y_offset (excluding the margins of the window). The tuple can be unpacked with * to be used as parameters with the GDAL WriteArray() method. Margins must from the numpy array before writing to the output dataset, see get_slice().

Example:

a = a[win.getslice()] # Slice off the margin
dst_ds.WriteArray(a, *win.gdalout)

Returns

tuple with x_offset, y_offset

get_a_off()

Get the x and y offsets with and without margins.

Primarily for debugging.

Returns

tuple with x_offset, y_offset, x_offset_no_margin, y_offset_no_margin

getslice(ndim=3)

Get tuple of slice objects to be used directly with numpy to remove the margin of the window before writing the data into the output dataset.

Example:

a = a[win.getslice()] # Slice off the margin of a 3D numpy array

Parameters

ndim (int, optional) – number of dimensions of the numpy array; either 2 or 3, default is 3

Returns

tuple of slice objects

Related functions

helpers.get_windows(rasterXSize, rasterYSize, windowsize=5000, margin=0)

Generator yielding RasterWindow instances, dividing a large raster into smaller windows (tiles).

The generated window objects do not contain the data, only the pixel indices and sizes that are used internally to read and write the data with GDAL.

Note that numpy, scipy etc. are very performant on large arrays. It is best to use a large windowsize or even the whole raster, as long as enough memory is avaible. The windows can have a margin, for algorthims that consider the neighborhood of a pixel as well. For example, a 3x3 kernel needs a margin of 1.

If you need the number of windows (e.g. for a progress bar), use number_of_windows().

Parameters

• rasterXSize (int) – number of pixels in x direction of the raster

• rasterYSize (int) – int, number of pixels in y direction of the raster

• windowsize (int, optional) – Size of the windows in x and y direction in pixels, default is 5000

• margin (int, optional) – Size of the margin in pixels, default is 0

Returns

RasterWindow instances

helpers.number_of_windows(rasterXSize, rasterYSize, windowsize)

Returns the number of windows that would be created with get_windows().

To be used for progress bar, etc.

Parameters

• rasterXSize (int) – number of pixels in x direction of the raster

• rasterYSize (int) – number of pixels in y direction of the raster

• windowsize (int) – Size of the windows in x and y direction in pixels

Returns

int, number of windows

helpers.wrap_margin(a, dataset, win: helpers.window.RasterWindow, band=None)

Fill margin of numpy array to enable SciPy filters with mode wrap.

Fills the margin of a numpy array that was read from a RasterWindow that is situated on the edge of the original raster with the data of the far side of the raster. This makes mode="wrap", offered by some SciPy filters, possible. The wrapping itself is done by SciPy, this function only fills the data needed for wrapping to work.

Example:

import gdal
from scipy import ndimage
from scipy_filters.helpers.window import get_windows, wrap_margin

ds = gdal.Open("raster.tif") 
driver = gdal.GetDriverByName("GTiff")
dst_ds = driver.CreateCopy(dst_filename, src_ds, strict=0)

windows = get_windows(ds.RasterXSize, ds.RasterYSize, windowsize=2000, margin=2)

for band in range(1, ds.RasterCount + 1):
    for win in windows:
        a = ds.GetRasterBand(band).ReadAsArray(*win.gdalin) 
        wrap_margin(a, ds, win, band=band)
        # Your calculation, for example median filter
        a = ndimage.median_filter(a, size=5, mode="wrap")
        a = a[win.getslice(2)] # Slice off the margin of the 2D array
        dst_ds.GetRasterBand(band).WriteArray(filtered, *win.gdalout)

Parameters

• a – Numpy array with the data of the window

• dataset – gdal dataset of the input raster

• win – RasterWindow

• band – int | None. Number of band (and using a 2D array), None for all bands (3D array if more than 1 band exists).