raster_tools.align#

raster_tools.align(rasters, *, join='inner', dst_grid=None, dst_crs=None, resolution=None, resampling_method='nearest')[source]#

Put rasters on a common grid.

Every output has the same CRS, affine transform, and x/y coordinates, so the outputs can be combined cell by cell. Bands, dtypes, and chunking are left as they are. This is a lazy operation.

Each raster is handled in the cheapest way that puts it on the destination grid:

  • A raster that is already on the destination grid is returned as is, wrapped in a new Raster object.

  • A raster that has the destination grid’s CRS and cell size and is offset from it by a whole number of cells is cut to the destination extent and padded with null cells where it does not cover it. Its values are not resampled.

  • Any other raster is reprojected onto the destination grid using resampling_method.

A raster without a CRS is treated as having the destination CRS, as long as it does not need to be reprojected.

Parameters

  • rasters (list of Raster or str) – The rasters to align. Path strings are opened with raster_tools.get_raster().

  • join (str, optional) –

    How to combine the input grids when building the destination grid. Only consulted when dst_grid is not provided. Valid options are:

    ’inner’

    Use the intersection of the input grid bounds. This is the default. Inputs that do not overlap raise a ValueError.

    ’outer’

    Use the union of the input grid bounds.

  • dst_grid (odc.geo.GeoBox, raster_tools.Raster, str, optional) – The destination grid. This can be a odc.geo.GeoBox, raster_tools.Raster object, or a path str. If the input is a raster object or path, only its grid is used. The output grid is dst_grid in north-up orientation: x increases and y decreases, even if dst_grid is flipped. A rotated or sheared dst_grid raises a ValueError. A dst_grid without a CRS takes the CRS shared by the inputs, and raises a ValueError if the inputs have different CRSs. The default is to build a grid from the inputs according to join. Passing dst_grid together with a dst_crs that differs from its CRS, or together with resolution, is an error.

  • dst_crs (CRS-like, str, int, optional) – The CRS of the destination grid. This can be anything that can be parsed by rasterio.CRS.from_user_input(). Only consulted when dst_grid is not provided. The default is the CRS of the inputs.

  • resolution (scalar, optional) – Cell size of the destination grid, in units of the destination CRS. Only consulted when dst_grid is not provided. The default is the cell size of the inputs.

  • resampling_method (str, optional) – Resampling method used when reprojecting rasters onto the destination grid. The default is 'nearest'. See raster_tools.reproject() for the valid methods.

Returns

The aligned rasters, in input order.

Return type

tuple of Raster

Notes

When dst_grid is not provided and the inputs share a CRS, cell size, and cell lattice (whole-cell offsets), the destination grid lies on that lattice and no input is resampled. Otherwise, the destination CRS and cell size default to those of the first raster in rasters, and reordering the inputs can change the destination grid.

Each raster’s cell size is taken from its grid (Raster.affine). Along an axis where a raster is one cell wide, that is the cell size recorded in its transform, or the cell size of its other axis if the raster was built from coordinates alone.

A raster with no null value that is padded or reprojected is given the default null value for its dtype, so that the new cells can be marked as null. Its existing cells stay valid, even where they hold that value. For a bool raster the default null value is True, so its padded cells hold True but are masked, while its existing True cells stay valid. A 64-bit integer raster is the exception: its existing cells that hold the null value are masked when cut, and when reprojected they are masked or, with newer GDAL, have their value nudged off it.

A raster whose cell size and offset are within 0.001 of a cell of the destination lattice is cut and padded rather than resampled, so sub-pixel noise in its transform is dropped.

Chunking is preserved, except that padding adds chunks at the edges of the grid. Use Raster.chunk() to rechunk the outputs if needed.

Examples

Crop two overlapping tiles to their shared extent, then add them:

>>> a, b = rts.align([tile_a, tile_b])  
>>> total = a + b

Put a raster on the grid of a reference raster:

>>> (aligned,) = rts.align([src], dst_grid=reference)