utils.neighborhood package

Submodules

utils.neighborhood.support_neighborhoods module

class utils.neighborhood.support_neighborhoods.SupportNeighborhoods(neighborhood_spec, **kwargs)

Bases: object

Author:: Alberto M. Esmoris Pena

Class providing the methods to generate support neighborhoods, i.e., neighborhoods centered on support points (not necessarily one per point in the point cloud). An instance of SupportNeighborhoods must have a neighborhood definition and might potentially redefine some default parameters to provide alternative behaviors (e.g., the number of desired support points, or the number of threads to use for parallel computations).

Variables:

neighborhood_spec (dict) –
The neighborhood specification governing the behavior of the support neighborhoods object. See the JSON below for an example:
```
{
    "type": "sphere",
    "radius": 5.0,
    "separation_factor": 1.0
}
```
support_strategy (str) – The strategy to be used to compute the support points when no training class distribution has been given. It can be “grid” (default) to get support points through grid sampling, or “fps” to use furthest point sampling.
support_strategy_num_points (int) – The number of points to consider when using a furthest point sampling strategy to compute the support points.
support_strategy_fast (bool) – True to use a fast approximation based on random sampling to compute the furthest point sampling (it works well provided that the number of points is big enough, e.g., > 10^3).
support_chunk_size (int) – The number of support points per chunk \(n\). If zero, all support points are considered at once. If greater than zero, the support points will be considered in chunks of \(n\) points.
training_class_distribution (list or tuple or np.ndarray) – The target class distribution to consider when building the support points. The element i of this vector (or list) specifies how many neighborhoods centered on a point of class i must be considered. If None, then the point-wise classes will not be considered when building the neighborhoods.
center_on_pcloud (bool) – When True, the support points defining the receptive field will be transformed to be a point from the input point cloud. Consequently, the generated neighborhoods are centered on points that belong to the point cloud instead of arbitrary support points. When False, support points do not necessarily match points from the point cloud.
nthreads (int) – The number of threads to consider for the parallel computation of the support neighborhoods.

__init__(neighborhood_spec, **kwargs)

Initialization/instantiation of a SupportNeighborhoods object.

See FurthestPointSubsamplingPreProcessor, furthest_point_subsampling_pre_processor.FurthestPointSubsamplingPreProcessor.find_neighborhood(), HierarchicalFPSPreProcessor, and hierarchical_fps_pre_processor.HierarchicalFpsPreProcessor.find_neighborhoood().

Parameters:

neighborhood_spec (dict) – The neighborhood specification governing the behavior of the support neighborhoods object.
kwargs (dict) – The key-word arguments defining the support neighborhoods object.

compute(X, y=None, kdt=None)

Compute/find the requested neighborhoods in the given input point cloud represented by the matrix of coordinates \(\pmb{X}\).

Parameters:

X (np.ndarray) – The matrix of coordinates.
y (np.ndarray) – The vector of expected values (generally, class labels). It is an OPTIONAL argument that is only necessary when the neighborhoods must be found following a given class distribution.
kdt – The precomputed KDTree for the structure space X, if any.

Returns:

A tuple which first element are the support points representing the centers of the neighborhoods and which second element is a list of neighborhoods, where each neighborhood is represented by a list of indices corresponding to the rows (points) in \(\pmb{X}\) that compose the neighborhood.

Return type:

tuple

static compute_cylindrical_neighborhoods(X, sup_X, neighborhood_spec, kdt=None)

Assists the SupportNeighborhood.compute() method computing cylindrical neighborhoods for each of the support points in the given point cloud.

Parameters:

X (np.ndarray) – The structure space of the point cloud.
sup_X (np.ndarray) – The support structure space, i.e., the coordinates of the center points for each neighborhood.
neighborhood_spec (dict) – The neighborhood specification.
kdt – The KDTree representing the structure space of the point cloud (not the support). If given, it will be used. If not given, it will be built inside the function’s scope.

static compute_spherical_neighborhoods(X, sup_X, neighborhood_spec, kdt=None)

Assists the SupportNeighborhoods.compute() method computing a spherical neighborhoods for each of the support points in the given point cloud.

See SupportNeighborhoods.compute_cylindrical_neighborhoods() for a description of the function’s arguments.

static compute_rectangular2D_neighborhoods(X, sup_X, neighborhood_spec, radius=None, kdt=None)

Assists the SupportNeighborhoods.compute() method computing a rectangular 2D neighborhoods for each of the support points in the given point cloud.

See SupportNeighborhoods.compute_cylindrical_neighborhoods() for a description of the function’s arguments.

static compute_rectangular3D_neighborhoods(X, sup_X, neighborhood_spec, radius=None, support_chunk_size=0, kdt=None)

Assists the SupportNeighborhoods.compute() method computing a rectangular 3D neighborhoods for each of the support points in the given point cloud.

See SupportNeighborhoods.compute_cylindrical_neighborhoods() for a description of the function’s arguments.

utils.neighborhood.support_neighborhoodspp module

class utils.neighborhood.support_neighborhoodspp.SupportNeighborhoodsPP(neighborhood_spec, **kwargs)

Bases: SupportNeighborhoods

Author:: Alberto M. Esmoris Pena

C++ version of SupportNeighborhoods.

It supports more types of neighborhoods like bounded cylindrical, 2D-KNN, 3D-KNN, bounded 2D-KNN, and bounded 3D-KNN neighborhoods.

__init__(neighborhood_spec, **kwargs)

Initialization/instantiation of a SupportNeighborhoods object.

See FurthestPointSubsamplingPreProcessor, furthest_point_subsampling_pre_processor.FurthestPointSubsamplingPreProcessor.find_neighborhood(), HierarchicalFPSPreProcessor, and hierarchical_fps_pre_processor.HierarchicalFpsPreProcessor.find_neighborhoood().

Parameters:

neighborhood_spec (dict) – The neighborhood specification governing the behavior of the support neighborhoods object.
kwargs (dict) – The key-word arguments defining the support neighborhoods object.

compute(X, y=None, kdt=None): C++ version of SupportNeighborhoods.compute().

Module contents

author:: Alberto M. Esmoris Pena

The neighborhood package contains the logic to handle neighborhoods, generally in the point clouds (but not only).