src.utils.ptransf.receptive_field_fps

Classes

ReceptiveFieldFPS(**kwargs)

class src.utils.ptransf.receptive_field_fps.ReceptiveFieldFPS(**kwargs)

Author:: Alberto M. Esmoris Pena

Class representing a receptive field based on furthest point subsampling.

See ReceptiveField, ReceptiveFieldGS, and FurthestPointSubsamplingPreProcessor.

Variables:

num_points (int) – The number of points so each point cloud is subsampled to this number of points through FPS. Typically noted as \(R\).
num_encoding_neighbors (int) – How many neighbors consider when propagating and reducing. Assume the number of encoding neighbors is \(m^* \in \mathbb{Z}_{\geq 0}\). For then, when reducing values from \(\pmb{X} \in \mathbb{R}^{m \times n}\) (input point cloud) to \(\pmb{Y} \in \mathbb{R}^{R \times n}\) (receptive field points), each reduced value in \(\pmb{Y}\) will be obtained by reducing \(m^*\) values in \(\pmb{X}\). Also, when propagating values from \(\pmb{Y} \in \mathbb{R}^{R \times n}\) to \(\pmb{X} \in \mathbb{R}^{m \times n}\), each propagated value in \(\pmb{X}\) will be obtained by reducing \(m^*\) values from \(\pmb{Y}\).
fast (bool) – Flag to control whether to use the fast mode or not. When running the FPS receptive field in fast mode, a random uniform sampling is computed before the furthest poit subsampling. While faster because it reduces the computational burden for the FPS, this approach is also less stable and might produce unexpected results.
N (np.ndarray) – The indexing matrix \(\pmb{N} \in \mathbb{Z}_{\geq 0}^{R \times m^*}\). Each row \(i\) in this matrix represents the indices in \(\pmb{X}\) that are associated to the point represented by the row \(i\) in \(\pmb{Y}\).
M (np.ndarray) – The reverse indexing matrix \(\pmb{M} \in \mathbb{Z}_{\geq 0}^{m \times m^*}. Each row :math:`i\) in this matrix represents the indices in \(\pmb{Y}\) that are associated to the points represented by the row \(i\) in \(\pmb{X}\).
x (npn.ndarray) – The center point of the receptive field. It is assigned when calling receptive_field_fps.ReceptiveFieldFPS.fit().
Y (np.ndarray) – The subsample representing the original input point cloud, i.e., a matrix of coordinates in a \(n\)-dimensional space such that \(\pmb{Y} \in \mathbb{R}^{R \times n}\).

__init__(**kwargs)

Initialize/instantiate a receptive field object.

Parameters:

kwargs – The key-word specification to instantiate the ReceptiveFieldFPS.

Keyword Arguments:

num_points (int) – The number of points \(R\) the input points must be reduced to. In other words, for a given number of input points \(m_1\), the reduced number of points will be \(R\). For another, let us say different (i.e., \(m_1 \neq m_2\)) number of points, the reduced number of points will also be \(R\).
num_encoding_neighbors (int) –
How many neighbors consider when doing propagations and reductions. For instance, for three encoding neighbors propagating a value means three points in the receptive field will be considered to estimate the value in the original domain. Analogously, reducing a value means three points in the original domain will be considered to encode the value in the receptive field.
fast (bool) –
A flag to enable the fast-computation mode. When True, a random uniform subsampling will be computed before the furthest point sampling so the latest is faster because it is not considering the entire input point cloud.

fit(X, x, structure_float_type=<class 'numpy.float64'>, id=None)

Fit the receptive field to represent the given points by taking the subset of the furthest points, i.e., the subset of points that maximize the distances between points. Typically, the next point in a FPS iteration maximizes the distance with respect to the already considered points in a greedy scheme.

Parameters:

X (np.ndarray) – The input matrix of m points in an n-dimensional space.
x (np.ndarray) – The center point used to define the origin of the receptive field.
structure_float_type (np.dtype) – The decimal type for the structure space.
id – See ReceptiveField.fit().

Returns:

The fitted receptive field itself (for fluent programming)

Return type:

ReceptiveFieldFPS

centroids_from_points(X)

The centroids of an FPS receptive field are said to be the subsampled points themselves.

Parameters:: X (np.ndarray or None) – The matrix of input points (can be NONE, in fact, it is not used).
Returns:: A matrix which rows are the points representing the centroids.
Return type:: np.ndarray

propagate_values(v, reduce_strategy='mean', **kwargs)

Propagate \(R\) values associated to \(\pmb{Y} \in \mathbb{R}^{R \times n}\) to \(m\) values associated to \(\pmb{X} \in \mathbb{R}^{m \times n}\) through the indexing matrix \(\pmb{M} \in \mathbb{Z}_{\geq 0}^{m \times m^*}\).

See ReceptiveField.propagate_values().

Parameters:

v (list) – The \(R\) values to be propagated.
reduce_strategy (str) – The reduction strategy, either “mean” or “closest”.

Returns:

The output as a matrix when there are more than two values per point or the output as a vector when there is one value per point.

Return type:

np.ndarray

static do_propagate_values(M, v, reduce_strategy): See ReceptiveFieldFPS.propagate_values().

reduce_values(X, v, reduce_f=<function mean>)

Reduce \(m\) values associated to \(\pmb{X} \in \mathbb{R}^{m \times n} to :math:`R\) values associated to \(\pmb{Y} \in \mathbb{R}^{R \times n}\) through the indexing matrix \(\pmb{N} \in \mathbb{Z}_{\geq 0}^{m \times m^*}\).

Parameters:

X (np.ndarray or None) – The centroids representing the furthest point subsampling computed by the receptive field. It can be None since it is not used for an FPS receptive field.
v – The vector of values to reduce. The \(m\) input components will be reduced to \(R\) output components.
reduce_f (callable) – The function to reduce many values to a single one. By default, it is mean.

Returns:

The reduced vector.

Return type:

np.ndarray

static do_reduce_values(N, X, v, reduce_f): See ReceptiveFieldFPS.reduce_values().

center_and_scale(X): Like receptive_field_gs.ReceptiveFieldGS.center_and_scale() but without scaling, i.e., only centering.

undo_center_and_scale(X): Like receptive_field_gs.ReceptiveFieldGS.undo_center_and_scale() but without scaling, i.e., only centering.

static compute_fps_on_3D_pcloud(X, num_points=None, fast=False, structure_float_type=<class 'numpy.float64'>, id=None, oversampling=None)

Compute the furthest point sampling (FPS) algorithm on the point cloud represented by the input 3D matrix \(\pmb{X} \in \mathbb{R}^{m \times 3}\). The result is an output matrix \(\pmb{Y} \in \mathbb{R}^{R \times 3}\).

Parameters:

X (np.ndarray) – The input 3D matrix (rows are points, columns dimensions).
num_points (int) – The number of points \(R\) selected through the furthest point sampling method.
fast (bool or int) – Whether to use a fast approximation of FPS (True) or the exact computation (False). The fast approximation is computed through uniform down sample. Alternatively, it can be (2) to use the turbo-fast mode (faster but purely stochastic). Note that turbo-fast can be slower than fast when only a few points (relative to the total) are selected, e.g., when selecting 5,000 or 10,000 points from a point cloud of 80 millions.
structure_float_type (np.dtype) – The decimal type for the structure space.
id – See ReceptiveField.fit().
oversampling (dict or None) – The dictionary governing the oversampling strategy for not populated enough receptive fields (OPTIONAL).

Returns:

The subsampled point cloud.

Return type:

np.ndarray

static oversample(X, target_points, **kwargs)

Oversample the given structure space matrix \(\pmb{X} \in \mathbb{R}^{m \times n_x}\) representing a point cloud with a \(n_x\)-dimensional structure space. For a given target number of points \(m^* \in \mathbb{Z}_{>1}\) The oversampling can be seen as a map \(\operatorname{o} : \mathbb{R}^{m \times n_x} \to \mathbb{R}^{m^* \times n_x}\) .

When adding new points, it is possible to have more candidates than needed extra points. In these cases, the tie is break by considering the best conditioned case. For example, when using the nearest strategy, those pairs of neighbors that are closer to each other will be selected first until \(m_* = m^*-m\) points are added.

Parameters:

X (np.ndarray) – The input structure space matrix \(\pmb{X} \in \mathbb{R}^{m \times n_x}\).
target_points (int) – \(m^* \in \mathbb{Z}_{>1}\).
kwargs (dict) –
The key-word specification governing the oversampling. It supports:

– min_points (\(m_*\), default 0)
The minimum acceptable number of points. Input point clouds with \(m < m_*\) points will raise an exception as they are considered unreliable.

– strategy (default “nearest”)
The oversampling strategy. It can be either "nearest" (for each point, the nearest neighbor distinct to itself is considered, a new point in the middle and equidistant to both neighbors is added), "knn" (the mean of the \(k\)-nearest neighbors is added as a new point), "spherical" (the centroid of a spherical neighborhood is added as a new point), "gaussian_knn" (the \(k\)-nearest neighbors are aggregated depending on their distance to the centroid of the neighborhood), and "spherical_radiation" (the points in the spherical neighborhood have a greater weight when computing the centroid depending on their distance to the center of the sphere, i.e., the closest to the center, the greater the contribution).

– k (default 16)
The number of \(k\)-nearest neighbors for the knn and gaussian_knn strategies.

– radius (default 1)
The radius for the spherical and spherical radiation strategies.

– nthreads (default 1)
The number of threads to be used for parallel computations, if any. Default is one because the oversampling is typically computed inside an already parallelized region, think twice before changing this value.

– report_dir (default None)
Path to the directory where the oversampled receptive fields will be exported as point clouds. If not given, not even a single point cloud will be written.

– ìd (default None)
See ReceptiveField.fit().

static nearest_oversample(K, X, nthreads=1)

Let \(\pmb{X} \in \mathbb{R}^{m \times n_x}\) be a structure space matrix. If \(m < m^*\), then \(K = m^*-m\) points must be generated through nearest oversampling. This consists of finding the closest neighbor distinct to itself for each \(\pmb{x}_{i*}\) and considering the mid-range from the \(K\) closer pairs of neighbors.

Parameters:

K (int) – How many points must be sampled, i.e., \(K = m^* - m\).
X (np.ndarray) – The structure space matrix.

static knn_oversample(K, X, k, nthreads=1)

Let \(\pmb{X} \in \mathbb{R}^{m \times n_x}\) be a structure space matrix. If \(m < m^*\), then \(K = m^*-m\) points must be generated through k-nearest neighbors oversampling. This consists of finding the k-closest neighbors for each \(\pmb{x}_{i*}\) and considering their centroid as a new point. In case more new points than needed are generated, those with the smallest distance between \(\pmb{x}_{i*}\) and its furthest nearest neighbor will be prioritized.

Parameters:

K (int) – How many points must be sampled, i.e., \(K = m^* - m\).
X (np.ndarray) – The structure space matrix.
k (int) – The number of nearest neighbors to consider (\(k\))

static spherical_oversample(K, X, r, nthreads=1)

Let \(\pmb{X} \in \mathbb{R}^{m \times n_x}\) be a structure space matrix. If \(m < m^*\), then \(K = m^*-m\) points must be generated through spherical oversampling. This consists of finding the spherical neighborhood centered on \(\pmb{x}_{i*}\), for each i-th point in the input structure space, and generating a new point by computing the centroid of the neighborhood. In case more new points than needed are generated, the furthest point sampling of the new points will be computed to select exactly \(m^*\) points.

Parameters:

K (int) – How many points must be sampled, i.e., \(K = m^* - m\).
X (np.ndarray) – The structure space matrix.
r (float) – The radius for the spherical neighborhood \(r\).

static naive_spherical_oversample(K, X, r, target_points, nthreads=1)

Let \(\pmb{X} \in \mathbb{R}^{m \times n_x}\) be a structure space matrix. If \(m < m^*\), then \(K = m^*-m\) points must be generated through spherical oversampling. This consists of finding the spherical neighborhood centered on \(\pmb{x}_{i*}\), for each i-th point in the input structure space, and generating a new point by computing the centroid of the neighborhood. In case more new points than needed are generated, the first \(m^*\) are selected in whatever order they are. Moreover, no uniqueness is forced on the centroids. That is why this method can be considered as the naive version of ReceptiveFieldFPS.spherical_oversample().

Parameters:

K (int) – How many points must be sampled, i.e., \(K = m^* - m\).
X (np.ndarray) – The structure space matrix.
r (float) – The radius for the spherical neighborhood \(r\).
target_points (int) – The target number of points.

static gaussian_knn_oversample(K, X, k, nthreads=1)

Let \(\pmb{X} \in \mathbb{R}^{m \times n_x}\) be a structure space matrix. If \(m < m^*\), then \(K = m^*-m\) points must be generated through Gaussian k-nearest neighbors oversampling. This consists of finding the k-closest neighbors for each \(\pmb{x}_{i*}\) and aggregating them using a Gaussian RBF to generate a new point.

In case more new points than needed are generated, those with the smallest distance between \(\pmb{x}_{i*}\) and its furthest nearest neighbor will be prioritized.

The Gaussian RBF is calculated for each \(i\)-th point as follows:

\[\pmb{y}_{i*} = \dfrac{ \sum_{\pmb{x}_{j*} \in \mathcal{N}_i} w_{ij} \pmb{x}_{j*} }{ \sum_{\pmb{x}_{j*} \in \mathcal{N}_i} w_{ij} }\]

Where \(\pmb{x}_{j*}\) is the \(j\)-th closest neighbor of \(\pmb{x}_{i*}\), \(\mathcal{N}_{i}\) is the set of the k-nearest neighbors of \(\pmb{x}_{i*}\), and \(w_{ij}\) is a Gaussian weight such that:

\[w_{ij} = \exp\left[-\dfrac{ \lVert{\pmb{x}_{j*} - \pmb{\mu}_{i*}}\rVert^{2} }{ (d_i^*)^2 }\right]\]

With

\[\pmb{\mu}_{i*} = k^{-1} \sum_{\pmb{x}_{j*} \in \mathcal{N}_i}{ \pmb{x}_{j*} }\]

and

\[\left(d_i^*\right)^2 = \max \left\{{ \lVert{\pmb{x}_{j*} - \pmb{\mu}_{i*}}\rVert^2 : 1 \leq j \leq k }\right\}\]

Parameters:

K (int) – How many points must be sampled, i.e., \(K = m^* - m\).
X (np.ndarray) – The structure space matrix.
k (int) – The number of nearest neighbors to consider (\(k\))

spherical_radiation_oversample(X, r, nthreads=1)

Let \(\pmb{X} \in \mathbb{R}^{m \times n_x}\) be a structure space matrix. If \(m < m^*\), then \(K = m^* - m\) points must be generated through spherical radiation oversampling. This consists of finding the spherical neighborhood centered on \(\pmb{x}_{i*}\), for each i-th point in the input structure space, and generating a new point by computing the Gaussian centroid of the neighborhood (see ReceptiveFieldFPS.gaussian_knn_oversample() for a detailed description on what Gaussian centroid means). The only difference for the Gaussian centroid with spherical radiation oversampling is that the radius of the sphere is used instead of the maximum squared distance such that:

\[w_{ij} = \exp\left[-\dfrac{ \lVert{\pmb{x}_{j*} - \pmb{\mu}_{i*}}\rVert^{2} }{ r^2 }\right]\]

In case more new points than needed are generated, the furthest point sampling of the new points will be computed to select exactly \(m^*\) points.

Parameters:

K (int) – How many points must be sampled, i.e., \(K = m^* - m\).
X (np.ndarray) – The structure space matrix.
r (float) – The radius for the spherical neighborhood \(r\).

static naive_spherical_radiation_oversample(K, X, r, target_points, nthreads=1): Naive version of ReceptiveField.spherical_radiation_oversample(). See also ReceptiveField.naive_spherical_oversample() to understand the difference between naive and naive spherical approaches.

canibalize(rf): See ReceptiveField.canibalize().