Match-reference operations

GeoUtils exposes convenient match-reference options across most of its operations.

Its objective is ease-of-use, by avoiding requiring volatile metadata extraction from users, potentially triggering unintended loading.

What is match-reference ?

Match-reference means to match the georeferencing of a dataset to that of another reference dataset.

Important

A match-reference argument can be any object implementing the georeferencing attributes needed by the operation: bbox, crs and/or transform/shape.

Here, reprojection to a raster reference matches its CRS and grid (pixel size, alignment and bounding box). Cropping uses the reference bounding box, preserving the source CRS and pixel size.

Matching with a raster, vector or point cloud

A vector or point cloud reference provides a bounding box and CRS. A raster reference also provides a grid: its pixel size, alignment and shape.

The same reference information serves the same purpose across object types. Reprojection uses the reference CRS, spatial selection uses its bounding box or geometry, and operations creating a raster grid can use its transform and shape. An operation can use several of these together, as raster reprojection does with CRS and grid.

Reference information	Operations using it
CRS	raster.reproject(), vector.reproject(), point_cloud.reproject()
Bounding box and CRS	raster.crop(), vector.crop(), point_cloud.crop(); raster.plot(), vector.plot(), point_cloud.plot()
Geometry or footprint, projected into the source CRS	raster.clip(), vector.clip(), point_cloud.clip()
Raster grid (CRS, transform and shape)	raster.reproject(), raster.krige(); vector.rasterize(), vector.create_mask() with a raster reference, vector.proximity(); point_cloud.grid(), point_cloud.krige()
Point locations (X/Y, projected into the source CRS)	raster.resample_at_points(), raster.interp_at_points(), raster.reduce_at_points(); vector.create_mask() with a point cloud reference

When only a bounding box and CRS are supplied to an operation requiring a grid definition, such as rasterization, gridding or reprojection, then one of resolution res or output shape shape must be defined. Raster reprojection is an exception, as it can estimate resolution from the source instead.

Note that outputs derived from a raster often need no external reference: for example, polygonize() and proximity() inherit georeferencing of the source raster directly.