Feature and scalability overview

Feature and scalability overview#

GeoUtils provides a unified API for manipulating raster, vector, and point cloud data, and provides scalable CPU execution for most raster and point cloud operations, as well as some vector operations, through Dask or multiprocessing.

As many of our numerical operations rely on NumPy, SciPy, or Numba, those are planned to be linked to their GPU counterparts (CuPy and Numba CUDA) in the future.

The summary tables directly below list the core features of GeoUtils and their scalability.

Summary#

GeoUtils exposes a consistent API across raster, vector, and point cloud objects wherever possible (similar in spirit to the recent GDAL CLI overhaul). Many operations also support convenient reference matching (e.g., matching a grid for reprojection or rasterization, bounds for cropping, or point coordinates for interpolation). See the Match-reference operations page for details.

At its core, GeoUtils provides two interchangeable ways to work with geospatial data:

Accessors that extend existing Xarray or GeoPandas structures (rst for rasters, pc for point clouds, and vct for vectors),
GeoUtils objects Raster, PointCloud, and Vector.

All raster and point cloud operations support scalable execution using Dask or multiprocessing, allowing large datasets to be processed chunk-by-chunk without loading the full array into memory. Some vector operations also support scalable execution, although memory is often less limiting for vector data.

Additionally, some numerical routines of GeoUtils provide multiple computational backends (e.g., SciPy or Numba implementations).

All methods are tested to ensure they produce identical results whether executed in-memory, chunked, or with different computational backends.

Data operations#

We first describe GeoUtils’ core data operations, which operate on underlying arrays or geometries and can therefore benefit from scalable execution.

Legend

/ denotes methods shared across object types.
⟷ denotes methods interfacing between two object types.

Common API for data operations#
Method	Description	Scalable
Raster / Vector / Point
`plot()`	Display geospatial data.	✅
`reproject()`	Change CRS or raster grid.	✅
`crop()`	Select data within a bounding box.	✅
`clip()`	Mask, select or cut data by geometry.	✅
`translate()`	Shift spatial coordinates.	✅
Raster / Point
`create_mask()`	Create boolean masks from geometries.	✅
`proximity()`	Measure distance to target values.	✅
`filter()`	Filter values over local neighborhoods.	✅
`subsample()`	Randomly select valid cells or points.	✅
`cosample()`	Select common valid locations across datasets.	✅
`pairsample()`	Sample valid pairs across spatial distances.	✅
`stats()`	Estimate global statistics.	✅
`stats()` with `by`	Estimate statistics grouped by bins, categories or zones.	✅
`variogram()`	Estimate and fit spatial semivariance.	✅
`estimate_error_structure()`	Estimate error magnitude and spatial correlation.	✅
`random_field()`	Generate spatially correlated random values.	✅
Raster ⟷ Vector
`rasterize()`	Burn geometries onto a raster grid.	✅
`polygonize()`	Convert raster regions to polygons.	✅
Raster ⟷ Point
`interp_at_points()`	Interpolate raster values at points.	✅
`reduce_at_points()`	Aggregate raster values around points.	✅
`to_pointcloud()`	Convert raster cells to points.	✅
`from_pointcloud_regular()`	Convert regular points to a raster.	❌
`grid()`	Create a raster from irregular points.	✅

Metadata properties and operations#

In addition to data operations, GeoUtils exposes metadata properties and methods consistently across geospatial objects. These rely only on metadata and therefore do not load or modify underlying data arrays.

Common API from metadata operations#
Attribute / Method	Description
Raster / Vector / Point
`crs`	Coordinate reference system (CRS) of object.
`bbox`	Bounding box of object.
`footprint`	Footprint polygon geometry of object.
`is_loaded`	Whether geospatial object is loaded in-memory.
`name`	Filename of object on disk, if it exists.
`get_bbox_projected()`	Bounding box projected in another CRS.
`get_footprint_projected()`	Footprint polygon geometry in other CRS.
`get_metric_crs()`	Get metric CRS suitable for this object.
`info()`	Summary of attributes for geospatial object.
Raster / Point
`data`	Data array (2D or 3D for raster, 1D for point cloud).
`shape`	Shape of data array.
`is_mask`	Whether object is a mask.
Raster
`transform`	Geotransform to map raster cells to spatial coordinates.
`nodata`	Nodata value used to represent missing data on disk.
`area_or_point`	Interpretation of raster cell values, area-average or point-center.
Point
`point_count`	Number of points in the point cloud.