gdf.pc.pairsample() or PointCloud.pairsample()

PointCloudBase.pairsample(*, n_pairs=1000000, sampling='loglag', min_distance=None, max_distance=None, random_state=None, mask=None, strategy='nn_logvector', n_bins=24, anchors_per_round=50000, attempts_per_anchor=1, max_rounds=50, cell_size=None, nn_tolerance=0.1, nn_batch_size=250000, nn_oversample=2.0, nn_max_batches=200, index_dtype=<class 'numpy.int32'>, distance_dtype=<class 'numpy.float32'>, mp_config=None)

Sample point pairs in the point cloud.

This function provides different strategies for sampling short and long pairwise distances in large point clouds. It supports chunked Dask and Multiprocessing out-of-memory reads, with explicit pair subsampling to also limit the returned data held in memory.

Sampling methods

With the default sampling="loglag", distance targets are drawn across a logarithmic scale so that short and long distances are both represented. The "kdtree" and "hashgrid" strategies select a distance range, find observed points at those distances from a sampled first point, and choose one as the second point. They use a SciPy spatial tree and a regular spatial index, respectively. The "nn_logvector" strategy instead projects an endpoint at a sampled distance and direction, then accepts the nearest observed point when it lies within the nn_tolerance fraction of that target distance. This is generally faster for large point clouds, but may return fewer pairs when no point is close to a target.

With sampling="random_xy", both endpoints are drawn independently and pairs outside the requested distance range are discarded. Pairs near min_distance or max_distance are usually rare, even though these distance extremes are often important for spatial analysis. Log-lag strategy options do not apply; max_rounds and nn_batch_size control how candidates are collected.

Memory and chunked inputs

n_pairs limits the returned data held in memory. Dask partitions and multiprocessing row partitions are processed separately, and their eligible coordinates, values, and original row indexes are staged in temporary disk-backed arrays. The complete point table is not collected in memory and the PointCloud stays unloaded. Log-lag sampling still builds a KD-tree or hash-grid index whose memory grows with the number of eligible points. Pair selection and the returned Xarray Dataset are eager for both backends.

type n_pairs:

int

param n_pairs:

Requested number of pairs with two finite values; fewer may be returned if sampling stops early.

type sampling:

Literal['loglag', 'random_xy']

param sampling:

"loglag" balances short and long distances on a log scale; "random_xy" draws endpoints uniformly.

type min_distance:

float | None

param min_distance:

Smallest distance in CRS units (e.g. meters). Defaults to half the spacing estimated from the eligible point density.

type max_distance:

float | None

param max_distance:

Largest distance in CRS units. Defaults to the bounding box diagonal of eligible points.

type random_state:

int | Generator | None

param random_state:

Seed for reproducible sampling (e.g. 42).

type mask:

geoutils.raster.base.RasterBase | DataArray | PointCloudBase | GeoDataFrame | geoutils.vector.base.VectorBase | ArrayLike | None

param mask:

Eligible points: True in a boolean array or spatial mask, or inside vector geometries. Arrays must have one entry per point. Point masks must follow the same ordered coordinates; raster masks use nearest interpolation. Point and raster masks must share this point cloud’s CRS. Missing mask entries are excluded.

type strategy:

Literal['kdtree', 'hashgrid', 'nn_logvector']

param strategy:

GeoUtils log-lag strategy: "kdtree" uses SciPy to search distance rings, "hashgrid" searches rings using a spatial grid, and "nn_logvector" uses SciPy to match proposed endpoints to nearby points.

type n_bins:

int

param n_bins:

Log-spaced distance rings used by "kdtree" and "hashgrid" (e.g. 24).

type anchors_per_round:

int

param anchors_per_round:

First endpoints tested per round by "kdtree" and "hashgrid".

type attempts_per_anchor:

int

param attempts_per_anchor:

Distance rings tried per first endpoint by "kdtree" and "hashgrid".

type max_rounds:

int

param max_rounds:

Maximum rounds to fill the sample with "kdtree", "hashgrid", or "random_xy".

type cell_size:

float | None

param cell_size:

Grid cell width in CRS units for "hashgrid". Defaults to one eighth of max_distance.

type nn_tolerance:

float

param nn_tolerance:

Allowed endpoint snap distance for "nn_logvector", as a fraction of the proposed pair distance (e.g. 0.1 allows a 10% offset).

type nn_batch_size:

int

param nn_batch_size:

Maximum candidate pairs per batch with "nn_logvector" or "random_xy"; smaller batches use less temporary memory.

type nn_oversample:

float

param nn_oversample:

Candidate count as a multiple of the remaining pairs with "nn_logvector" (e.g. 2).

type nn_max_batches:

int

param nn_max_batches:

Maximum batches to fill the sample with "nn_logvector".

type index_dtype:

DTypeLike

param index_dtype:

Integer NumPy dtype for returned row indexes (e.g. "int64" for very large point clouds).

type distance_dtype:

DTypeLike

param distance_dtype:

Floating NumPy dtype for returned distances (e.g. "float64" for greater precision).

type mp_config:

MultiprocConfig | None

param mp_config:

Worker and row partition settings for reading an unloaded point cloud into temporary disk-backed arrays. Cannot be combined with Dask inputs. Pair selection and the returned Xarray Dataset are eager.

rtype:

Dataset

returns:

Xarray Dataset with pair and endpoint dimensions, containing original row indexes, values, coordinates, and distances.