geovista.search#
Support to find points or cells within a mesh using various techniques.
Notes#
Added in version 0.1.0.
Attributes#
The default kd-tree nearest neighbour epsilon. |
|
The default kd-tree number of nearest neighbours. |
|
The default kd-tree leaf-size. |
|
The default search preference. |
|
Type alias for a tuple of nearest neighbour distances and indices. |
Classes#
Construct a kd-tree for fast nearest neighbour search of a mesh. |
|
Enumeration of mesh geometry search preferences. |
Functions#
|
Find all the cells neighbouring the given cid cell/s of the mesh. |
|
Find the cell in the mesh that is closest to the point-of-interest (POI). |
Module Contents#
- class geovista.search.KDTree(mesh, /, *, leaf_size=None, preference=None)[source]#
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:
- mesh
PolyData The mesh used to construct the kd-tree.
- leaf_size
int, 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.- preference
strorSearchPreference, optional Construct the kd-tree from the mesh points
pointor cell centerscenter. Also seeSearchPreference. Defaults toKDTREE_PREFERENCE.
- mesh
Notes
Added in version 0.3.0.
- __repr__()[source]#
Serialize
KDTreerepresentation.- Returns:
strString representation of the instance.
Notes
Added in version 0.3.0.
- query(lons, lats, /, *, k=None, epsilon=None, distance_upper_bound=None, globe=None, zlevel=None, zscale=None)[source]#
Query the kd-tree for k nearest neighbours per point-of-interest.
- Parameters:
- lons
floatorArrayLikeorpint.Quantity One or more longitude values for the query points-of-interest. A
pintquantity, from any registry, is read in degrees. Give lats as a quantity too.- lats
floatorArrayLikeorpint.Quantity One or more latitude values for the query points-of-interest. A
pintquantity, from any registry, is read in degrees. Give lons as a quantity too.- k
int, 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.
- globe
Globe, optional The globe the points-of-interest lie on, at its render radius. Defaults to the globe of the mesh the kd-tree was built from.
- zlevel
floatorArrayLike, default=0.0 The z-axis level. Used in combination with the zscale to offset the render radius by a proportional amount i.e.,
render_radius * zlevel * zscale. If zlevel is not a scalar, then its shape must match or broadcast with the shape of lons and lats.- zscale
float, optional The proportional multiplier for z-axis zlevel. Defaults to
geovista.common.ZLEVEL_SCALE.
- lons
- Returns:
NearestNeighboursThe Euclidean distance and index of the k nearest neighbours for each query point-of-interest. A point-of-interest whose longitude or latitude is masked or NaN is missing, and has no neighbour: each of its distances is
infand each of its indices isn_points, the answer for a point beyond distance_upper_bound.
- Raises:
ValueErrorIf a longitude or latitude that is not masked is infinite.
Notes
Added in version 0.3.0.
- 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:
intThe 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:
intThe 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.ndarrayThe 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:
SearchPreferenceThe preference of mesh geometry to search.
Notes
Added in version 0.3.0.
- class geovista.search.SearchPreference[source]#
Bases:
geovista.common.StrEnumPlusEnumeration of mesh geometry search preferences.
Notes#
Added in version 0.3.0.
Initialize self. See help(type(self)) for accurate signature.
- CENTER = 'center'#
Preference to search the cell centers.
- POINT = 'point'#
Preference to search the mesh points.
- geovista.search.find_cell_neighbours(mesh, cid)[source]#
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:
- Returns:
Notes
Added in version 0.1.0.
- geovista.search.find_nearest_cell(mesh, /, x, y, z=0, *, single=False)[source]#
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
cellIDof each cell face which shares that vertex is returned.- Parameters:
- mesh
PolyData The mesh defining the points, cells and CRS.
- x
floatorpint.Quantity The POI x-coordinate. Defaults to
longitudeif no mesh CRS is available. Apintquantity, from any registry, carries its own units, and is read in those of the CRS of the mesh. Give y as a quantity too.- y
floatorpint.Quantity The POI y-coordinate. Defaults to
latitudeif no mesh CRS is available. Apintquantity, from any registry, carries its own units, and is read in those of the CRS of the mesh. Give x as a quantity too.- z
float, optional The POI z-coordinate, if applicable. Defaults to zero.
- single
bool, default=False Enforce expectation of only one nearest
cellIDresult. Otherwise, a sorted list ofcellIDsare returned.
- mesh
- Returns:
- Raises:
ValueErrorIf x or y is masked, NaN or infinite, as such a POI has no position.
Notes
Added in version 0.1.0.