⚠️ Our 0.1 release refactored several early-development functions for long-term stability, to update your code see here. ⚠️
Future changes will come with deprecation warnings! 🙂

Match-reference functionality#

Match-reference functionalities lie at the core of GeoUtils’ focus to provide accessible and intuitive tools for end-user geospatial analysis.

What is match-reference ?#

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

Why the need for match-reference?#

End-users of geospatial tools largely focus on analyzing their data. To this end, they first need to reconcile data sources, often provided in different projections, resolutions, and bounds. This is generally performed by matching all dataset to a certain reference.

Such functionalities are not always available from lower-level packages, in order to keep geoinformatics flexible for more diverse uses. This breaks the principle of least knowledge, however, for which a user should not need to understand more information than just what is required to run an operation.

GeoUtils allows for match-reference for nearly all geospatial handling operations, with consistent behaviour across functionalities for intuitive use.

Matching with a Raster or a Vector reference#

The rules of using match-reference with Rasters or Vectors are always the same:

  • If the reference passed is a Vector, it can enforce a matching of its bounds and/or of its crs (its only two georeferencing attributes),

  • If the reference is a Raster, it can also enforce a matching of any aspect of its transform (i.e, its res, bounds or shape) and/or of its crs.

Which of these attributes are eventually used to enforce the matching depends entirely on the nature of the operation, which are listed below.

Geospatial handling rules for match-reference#

Geospatial handling methods all support match-reference, and always enforce the same georeferencing attributes for either Raster or Vector:


Enforced on Raster

Enforced on Vector


transform and crs

bounds1 and crs




1Because a Vector only possesses the bounds attribute of a Raster’s transform.

Other operations supporting match-reference#

There are other geospatial operation that also support match-reference arguments. Unlike the geospatial handling methods described above, these do not aim at modifying the georeferencing of Rasters or Vectors. Instead, they simply require the georeferencing metadata.

From vector to raster#

The rasterize() operation to convert from Vector to Raster accepts a Raster to define the grid and georeferencing. The behaviour is similar for create_mask(), that directly relies on rasterize() to rasterize directly into a boolean Mask.

In addition, the proximity() operation to compute proximity distances from the vector also relies on a rasterize(), and therefore also accepts a Raster as reference.

Therefore, the behaviour is consistent for all Vector methods that can be passed a Raster:

Operation on Vector



Gridding with transform and crs


Gridding with transform and crs


Gridding with transform and crs

And inversely#

However, in the case of Raster methods that yield a Vector or Raster, a reference is rarely needed. This is because this reference is derived directly from the input Raster itself, harnessing the object-based structure of GeoUtils.

The user can always crop() or reproject() the output afterwards, if desired.

Operation on Raster



Using .self (Raster) as reference for transform and crs


Using .self (Raster) as reference for transform and crs