geovista.search

Support to find points or cells within a mesh using various techniques.

Notes

Added in version 0.1.0.

Module Contents

Classes

KDTree	Construct a kd-tree for fast nearest neighbour search of a mesh.
SearchPreference	Enumeration of mesh geometry search preferences.

Functions

find_cell_neighbours(mesh, cid)	Find all the cells neighbouring the given cid cell/s of the mesh.
find_nearest_cell(mesh, x, y[, z, single])	Find the cell in the mesh that is closest to the point-of-interest (POI).

Attributes

KDTREE_EPSILON	The default kd-tree nearest neighbour epsilon.
KDTREE_K	The default kd-tree number of nearest neighbours.
KDTREE_LEAF_SIZE	The default kd-tree leaf-size.
KDTREE_PREFERENCE	The default search preference.
NearestNeighbours	Type alias for a tuple of nearest neighbour distances and indices.

class geovista.search.KDTree(mesh, leaf_size=None, preference=None)

Construct a kd-tree for fast nearest neighbour search of a mesh.

For further details, see storpipfugl/pykdtree.

Notes

Added in version 0.3.0.

Construct kd-tree for nearest neighbour search of mesh points/cell centers.

Note that, the cell centers will be calculated from the mesh geometry and do not require to be provided.

The geolocated mesh data points are converted to cartesian coordinates on a S2 sphere, as the kd-tree implementation uses Euclidean distance as the metric for nearest neighbours.

Nearest neighbour queries are optionally multi-threaded using OpenMP. For further details see storpipfugl/pykdtree.

Parameters:

meshPolyData

The mesh used to construct the kd-tree.

leaf_sizeint, optional

The number of data points per tree leaf. Used to control the memory overhead of the kd-tree. Increasing the leaf size will reduce the memory overhead and construction time, but increase the query time. Defaults to KDTREE_LEAF_SIZE.

preferencestr or SearchPreference, optional

Construct the kd-tree from the mesh points point or cell centers center. Also see SearchPreference. Defaults to KDTREE_PREFERENCE.

Notes

Added in version 0.3.0.

query(lons, lats, k=None, epsilon=None, distance_upper_bound=None, radius=None, zlevel=None, zscale=None)

Query the kd-tree for k nearest neighbours per point-of-interest.

Parameters:

lonsfloat or ArrayLike

One or more longitude values for the query points-of-interest.

latsfloat or ArrayLike

One or more latitude values for the query points-of-interest.

kint, optional

The number of nearest neighbours to find per point-of-interest. Defaults to KDTREE_K.

epsilonnon-negative float, optional

Return approximate nearest neighbours; the k-th returned value is guaranteed to be no further than (1 + epsilon) times the distance to the real k-th nearest neighbour. Defaults to KDTREE_EPSILON.

distance_upper_boundnon-negative float, optional

Return only neighbors within this distance. This is used to prune tree searches.

radiusfloat, optional

The radius of the sphere. Defaults to geovista.common.RADIUS.

zlevelfloat or ArrayLike, default=0.0

The z-axis level. Used in combination with the zscale to offset the radius by a proportional amount i.e., radius * zlevel * zscale. If zlevel is not a scalar, then its shape must match or broadcast with the shape of lons and lats.

zscalefloat, optional

The proportional multiplier for z-axis zlevel. Defaults to geovista.common.ZLEVEL_SCALE.

Returns:

NearestNeighbours

The Euclidean distance and index of the k nearest neighbours for each query point-of-interest.

Notes

Added in version 0.3.0.

crs

property leaf_size: int

The number of data points per tree leaf.

Used to control the memory overhead of the kd-tree. Increasing the leaf size will reduce the memory overhead and construction time, but increase the query time.

Returns:

int

The leaf size i.e., the number of data points per leaf, for the tree creation.

Notes

Added in version 0.3.0.

property n_points: int

Number of mesh points registered with the kd-tree.

Returns:

int

The number of mesh points in the kd-tree.

Notes

Added in version 0.3.0.

property points: numpy.ndarray

The cartesian data points registered with the kd-tree.

Returns:

np.ndarray

The cartesian data points in the kd-tree.

Notes

Added in version 0.3.0.

property preference: SearchPreference

The target mesh geometry to search.

Focus either on the mesh points or the mesh cell centers.

Returns:

SearchPreference

The preference of mesh geometry to search.

Notes

Added in version 0.3.0.

xyz

class geovista.search.SearchPreference(*args, **kwds)

Bases: geovista.common.MixinStrEnum, enum.Enum

Enumeration of mesh geometry search preferences.

Notes

Added in version 0.3.0.

CENTER = 'center'

POINT = 'point'

geovista.search.find_cell_neighbours(mesh, cid)

Find all the cells neighbouring the given cid cell/s of the mesh.

A cell is deemed to neighbour a cid cell if it shares at least one vertex.

Parameters:

meshPolyData

The mesh defining the points cells.

cidint or list of int

The offset of the cell/s in the mesh that is/are the focus of the neighbourhood.

Returns:

list of int

The sorted list of neighbouring cell-ids.

Notes

Added in version 0.1.0.

geovista.search.find_nearest_cell(mesh, x, y, z=0, single=False)

Find the cell in the mesh that is closest to the point-of-interest (POI).

Assumes that the POI is in the canonical units of the gvCRS associated with the mesh, otherwise assumes geographic longitude and latitude.

If the POI is coincident with a vertex of the mesh, then the cellID of each cell face which shares that vertex is returned.

Parameters:

meshPolyData

The mesh defining the points, cells and CRS.

xfloat

The POI x-coordinate. Defaults to longitude if no mesh CRS is available.

yfloat

The POI y-coordinate. Defaults to latitude if no mesh CRS is available.

zfloat, optional

The POI z-coordinate, if applicable. Defaults to zero.

singlebool, default=False

Enforce expectation of only one nearest cellID result. Otherwise, a sorted list of cellIDs are returned.

Returns:

int or list of int

The cellID of the closest mesh cell, or the cellIDs that share the coincident point-of-interest as a node.

Notes

Added in version 0.1.0.

geovista.search.KDTREE_EPSILON: float = 0.0

The default kd-tree nearest neighbour epsilon.

geovista.search.KDTREE_K: int = 1

The default kd-tree number of nearest neighbours.

geovista.search.KDTREE_LEAF_SIZE: int = 16

The default kd-tree leaf-size.

geovista.search.KDTREE_PREFERENCE: str = 'point'

The default search preference.

geovista.search.NearestNeighbours

Type alias for a tuple of nearest neighbour distances and indices.