Match-reference functionality

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:

Operation	Enforced on `Raster`	Enforced on `Vector`
`reproject()`	`transform` and `crs`	`bounds`¹ and `crs`
`crop()`	`bounds`	`bounds`

¹Because 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`	Behaviour
`rasterize()`	Gridding with `transform` and `crs`
`create_mask()`	Gridding with `transform` and `crs`
`proximity()`	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`	Behaviour
`polygonize()`	Using `.self` (`Raster`) as reference for `transform` and `crs`
`proximity()`	Using `.self` (`Raster`) as reference for `transform` and `crs`