:py:mod:`geovista.search` ========================= .. py:module:: geovista.search .. autoapi-nested-parse:: Support to find points or cells within a mesh using various techniques. Notes ----- .. versionadded:: 0.1.0 .. !! processed by numpydoc !! Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: geovista.search.KDTree geovista.search.SearchPreference Functions ~~~~~~~~~ .. autoapisummary:: geovista.search.find_cell_neighbours geovista.search.find_nearest_cell Attributes ~~~~~~~~~~ .. autoapisummary:: geovista.search.KDTREE_EPSILON geovista.search.KDTREE_K geovista.search.KDTREE_LEAF_SIZE geovista.search.KDTREE_PREFERENCE geovista.search.NearestNeighbours .. py:class:: KDTree(mesh, leaf_size = None, preference = None) Construct a kd-tree for fast nearest neighbour search of a mesh. For further details, see https://github.com/storpipfugl/pykdtree. Notes ----- .. versionadded:: 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 https://github.com/storpipfugl/pykdtree. :Parameters: **mesh** : :obj:`PolyData ` The mesh used to construct the kd-tree. **leaf_size** : :class:`python: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 :data:`KDTREE_LEAF_SIZE`. **preference** : :class:`python:str` or :obj:`SearchPreference`, optional Construct the kd-tree from the `mesh` points ``point`` or cell centers ``center``. Also see :class:`SearchPreference`. Defaults to :data:`KDTREE_PREFERENCE`. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:method:: 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: **lons** : :class:`python:float` or :obj:`ArrayLike ` One or more longitude values for the query points-of-interest. **lats** : :class:`python:float` or :obj:`ArrayLike ` One or more latitude values for the query points-of-interest. **k** : :class:`python:int`, optional The number of nearest neighbours to find per point-of-interest. Defaults to :data:`KDTREE_K`. **epsilon** : non-negative :class:`python: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 :data:`KDTREE_EPSILON`. **distance_upper_bound** : non-negative :class:`python:float`, optional Return only neighbors within this distance. This is used to prune tree searches. **radius** : :class:`python:float`, optional The radius of the sphere. Defaults to :data:`geovista.common.RADIUS`. **zlevel** : :class:`python:float` or :obj:`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`. **zscale** : :class:`python:float`, optional The proportional multiplier for z-axis `zlevel`. Defaults to :data:`geovista.common.ZLEVEL_SCALE`. :Returns: :obj:`NearestNeighbours` The Euclidean distance and index of the k nearest neighbours for each query point-of-interest. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:attribute:: crs .. py:property:: leaf_size :type: 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: :class:`python:int` The leaf size i.e., the number of data points per leaf, for the tree creation. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:property:: n_points :type: int Number of mesh points registered with the kd-tree. :Returns: :class:`python:int` The number of mesh points in the kd-tree. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:property:: points :type: numpy.ndarray The cartesian data points registered with the kd-tree. :Returns: :obj:`np.ndarray ` The cartesian data points in the kd-tree. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:property:: preference :type: SearchPreference The target mesh geometry to search. Focus either on the mesh points or the mesh cell centers. :Returns: :obj:`SearchPreference` The preference of mesh geometry to search. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:attribute:: xyz .. py:class:: SearchPreference(*args, **kwds) Bases: :py:obj:`geovista.common.MixinStrEnum`, :py:obj:`enum.Enum` Enumeration of mesh geometry search preferences. .. rubric:: Notes .. versionadded:: 0.3.0 .. !! processed by numpydoc !! .. py:attribute:: CENTER :value: 'center' .. py:attribute:: POINT :value: 'point' .. py:function:: 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: **mesh** : :obj:`PolyData ` The mesh defining the points cells. **cid** : :class:`python:int` or :class:`python:list` of :class:`python:int` The offset of the cell/s in the `mesh` that is/are the focus of the neighbourhood. :Returns: :class:`python:list` of :class:`python:int` The sorted list of neighbouring cell-ids. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:function:: 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: **mesh** : :obj:`PolyData ` The mesh defining the points, cells and CRS. **x** : :class:`python:float` The POI x-coordinate. Defaults to ``longitude`` if no `mesh` CRS is available. **y** : :class:`python:float` The POI y-coordinate. Defaults to ``latitude`` if no `mesh` CRS is available. **z** : :class:`python:float`, optional The POI z-coordinate, if applicable. Defaults to zero. **single** : :class:`python:bool`, default=False Enforce expectation of only one nearest ``cellID`` result. Otherwise, a sorted list of ``cellIDs`` are returned. :Returns: :class:`python:int` or :class:`python:list` of :class:`python:int` The cellID of the closest mesh cell, or the cellIDs that share the coincident point-of-interest as a node. .. rubric:: Notes .. versionadded:: 0.1.0 .. !! processed by numpydoc !! .. py:data:: KDTREE_EPSILON :type: float :value: 0.0 The default kd-tree nearest neighbour epsilon. .. !! processed by numpydoc !! .. py:data:: KDTREE_K :type: int :value: 1 The default kd-tree number of nearest neighbours. .. !! processed by numpydoc !! .. py:data:: KDTREE_LEAF_SIZE :type: int :value: 16 The default kd-tree leaf-size. .. !! processed by numpydoc !! .. py:data:: KDTREE_PREFERENCE :type: str :value: 'point' The default search preference. .. !! processed by numpydoc !! .. py:data:: NearestNeighbours Type alias for a tuple of nearest neighbour distances and indices. .. !! processed by numpydoc !!