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 operations through Dask and 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 lists the core features of GeoUtils, their scalability and available backends.

Summary#

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

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

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

Nearly all raster 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 and point-cloud accessor operations are also lazy with Dask-GeoPandas, with support still partial and ongoing.

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	Notes	Scalable	Backend
Raster / Vector / Point
`reproject()`	Reproject to other CRS. Also resamples to new grid for rasters, with default parameters ensuring chunk-invariance.	✅	Rasterio / PyProj
`crop()`	Crop to bounds, either intersecting (untouched) allowing efficient I/O, or clipped (data modified).	✅	Rasterio / GeoPandas
`translate()`	Apply a grid shift to object.	✅	NumPy / GeoPandas
`plot()`	Visualization helper.	❌	Matplotlib
Raster / Point
`create_mask()`	Create boolean mask of a vector geometries over raster or point.	✅	Rasterio / GeoPandas
`stats()`	Compute statistics of valid values over a valid mask.	❌	NumPy / SciPy
`subsample()`	Randomly sample valid values. Chunk-invariant seed ensures reproducibility.	✅	NumPy
`filter()`	Filter over window. Fast vectorized logic with NaN support.	✅	SciPy
`proximity()`	Estimate proximity distance to target values.	❌	SciPy
Raster ⟷ Vector
`polygonize()`	Convert raster regions to vector polygons. Multiple chunked strategies for performance.	✅	Rasterio / GeoPandas
`rasterize()`	Burn vector geometries onto a raster grid.	✅	Rasterio
Raster ⟷ Point
`interp_points()`	Interpolate raster at point locations. Fast regular-grid logic with added NaN propagation.	✅	SciPy
`reduce_points()`	Aggregate raster values around points.	❌	NumPy
`grid()`	Grid irregular points onto a raster grid. Multiple approaches with added NaN propagation.	❌	SciPy
`from_pointcloud_regular()`	Direct conversion when points lie on a regular grid.	❌	NumPy
`to_pointcloud()`	Conversion to point cloud.	❌	NumPy

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.
`bounds`	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_bounds_projected()`	Bounds projected in other 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. Clarifies ambiguity of raster/point file types often not supporting boolean types.
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, either an area-average or point-center.
Point
`point_count`	Number of points in the point cloud.