Supported operations

Supported operations#

GeoUtils supports scalable execution for most of its operations, nearly all for rasters and point clouds, and most for vectors.

Chunked implementations can run through either Dask (via the Xarray and Pandas accessors) or Multiprocessing (via GeoUtils objects).

The two interfaces expose the same operations, and chunked implementations yield identical results as in-memory operations, including with different backends (e.g., SciPy, Numba).

Table summary#

The table below summarizes the scalability support of GeoUtils operations with respect to their input and output behavior.

If you are unfamiliar with chunked and lazy execution or deferred I/O, see Concept definitions.

Legend

Chunked — Processes in chunks, without loading (for input) and/or returning (for output) the full data. This is also lazy (deferred execution) when using Dask.
In-memory — Loads (for input) or returns (for output) full data in-memory.
Deferred I/O — Deferred input/output by updating internal metadata (as Xarray’s isel()).
N/A — Chunking does not apply, as input or output is tiny (mostly metadata).

The ⟶ symbol denotes methods interfacing from one specific object type to another, with point-cloud type shortened to “Point”.

Memory usage estimates the number of chunks in-memory: 1R/1P/1V mean one raster/point/vector chunk respectively, R/P means either raster or point. See bottom notes for special cases.

Method	Input	Output	Memory usage
Raster ⟶ Raster
`reproject()`	Chunked	Chunked	1R + CRS overlap¹
`crop()` / `icrop()`	Deferred I/O	Deferred I/O	0
`clip()`⁵	Chunked	Chunked	1R
`translate()`	Deferred I/O	Deferred I/O	0
`copy()`	Deferred I/O	Deferred I/O	0
`filter()`	Chunked	Chunked	1R + overlap²
`proximity()`	Chunked	Chunked	1R + overlap²
`krige()`	Chunked	Chunked	1R + overlap²
`random_field()`	Chunked	Chunked	1R + model³
`fill_nodata()` / `sieve()`	In-memory	In-memory	—
Raster ⟶ Point
`subsample()`⁵ / `to_pointcloud()`⁵	Chunked	Chunked	1R + 1P
`interp_at_points()`	Chunked	In-memory	1R + 1P + overlap²
`reduce_at_points()`	Chunked	In-memory	1R + 1P + overlap²
`cosample()`⁵	Chunked	Chunked	1–2R/P
Raster ⟶ Vector
`polygonize()`	Chunked	In-memory	1–2R
Raster ⟶ Other
`plot()`	Chunked	N/A	1R
`stats()`	Chunked	N/A	1R
`pairsample()`	Chunked	In-memory	1R + sample⁴
`variogram()`	Chunked	N/A	1R + sample⁴
`estimate_error_structure()`	Chunked	N/A	1R + sample⁴
`stats()` with `fractional=True`	In-memory	N/A	—
Point ⟶ Point
`crop()`⁵	Deferred I/O	Deferred I/O	0
`clip()`⁵	Chunked	Chunked	1P
`reproject()`	Chunked	Chunked	1P
`translate()`	In-memory	In-memory	—
`subsample()`⁵	Chunked	Chunked	1P
`cosample()`⁵	Chunked	Chunked	1–2R/P
`filter()`	Chunked	Chunked	1P + overlap²
`random_field()`⁵	Chunked	Chunked	1P + model³
Point ⟶ Raster
`grid()`⁵	Chunked	Chunked	1P + 1R + overlap²
`krige()`⁵	Chunked	Chunked	1P + 1R + overlap²
`from_pointcloud_regular()`	In-memory	In-memory	—
Vector ⟶ Vector
`crop()`	Deferred I/O	Deferred I/O	0
`clip()`⁵	Chunked	Chunked	1V
`reproject()` / `translate()`	In-memory	In-memory	—
Vector ⟶ Raster
`rasterize()`	In-memory	Chunked	1R
`create_mask()`	In-memory	Chunked	1R
`proximity()`	In-memory	Chunked	1R + overlap²
Vector ⟶ Point
`create_mask()`	In-memory	Chunked	1P
Point ⟶ Other
`stats()`	Chunked	N/A	1P
`pairsample()`	Chunked	In-memory	1P + index⁴
`variogram()`	Chunked	N/A	1P + index⁴
`estimate_error_structure()`	Chunked	N/A	1P + index⁴
`plot()`	Chunked	N/A	1P
Raster / Point ⟶ Uncertainty
`propagate()`	Chunked	Chunked	1R/P + overlap²

Note that nearly all raster inputs/outputs and most point inputs/outputs methods support Chunked, while vector inputs are often In-memory, as usually less limiting.

For more insights into chunked implementation strategies and behaviour expected for each operation, see the Implementation strategies page.

Notes#

For reprojecion, CRS overlap corresponds to the source area needed for each output chunk after reprojection. By default, GeoUtils sets output chunks to a size that follows changes in resolution to avoid loading more than one source chunk + overlap. GCP/RPC models are supported for chunked reprojection, alongside classic affine grids.
The overlap corresponds to neighboring data needed to calculate values near chunk edges, which depends directly on filter window/neighborhood size. Chunked proximity, point filtering, gridding and kriging limit this through a maximum search distance.
The model is typically a small dataframe describing variable errors along predictors, and modelled correlation functions. All chunks use it.
The sample is the returned in-memory sample. The index helps find nearby points and uses more memory for larger point clouds.
Some operations require preliminary reads even though their output stays lazy, see Preliminary reads directly below.

Preliminary reads#

Some operations need to read part of an object to clearly prepare a chunked operation.

This happens when metadata alone is not sufficient to define the operation, for example to estimate valid data counts before subsampling rasters or point clouds, or estimate average height in a chunk before a 3D affine transformation for elevation data.

Although the output computation stays lazy, these reads are performed during the function call, creating some small initial processing time (usually minimal, a fast pass).

The affected operations are listed below:

Operation	Information read during the call
`subsample()`, `cosample()`, `pairsample()`, or using `subsample` on an operation)	Count valid observations and select sample indices
`pc.to_xarray()`	Count rows when partition lengths are unknown
`pc.crop()`, `pc.clip()`	Select point rows to define the output size
`clip(mask=...)`	Read lazy mask geometries
`pc.grid()`, `pc.krige()`, `pc.random_field()`	Determine point extents when needed

Computation breakpoints#

Operations with in-memory outputs force computation during the call, forming a breakpoint in a lazy workflow (though the Dask input stays lazy).

Usually, these operations usually return small outputs (e.g. statistics dictionary, empirical variogram).

Here is the list of operations triggering a breakpoint:

Operation	In-memory result
`rst.polygonize()`	Vector geometries
`stats()`, `variogram()`, `estimate_error_structure()`	Statistics, variograms and error models
`pc.bbox`, `vct.bbox`	Bounding box (when metadata is unavailable)
`raster_equal()`, `pointcloud_equal()`, `vector_equal()`	Comparison results
`to_geoutils()`	GeoUtils objects

Plotting and file writing also naturally trigger computation, though raster writing with compute=False can remain deferred.