src.utils.ptransf.receptive_field_hierarchical_fps

Classes

ReceptiveFieldHierarchicalFPS(**kwargs)

class src.utils.ptransf.receptive_field_hierarchical_fps.ReceptiveFieldHierarchicalFPS(**kwargs)

Author:: Alberto M. Esmoris Pena

Class representing a hierarchical receptive field based on furthest point subsampling.

A hierarchical receptive field is a special type of receptive field because it is composed of many receptive fields organized in a hierarchical manner.

See ReceptiveField, ReceptiveFieldFPS, and HierarchicalFPSPreProcessor.

Variables:

num_points_per_depth (list or tuple or np.ndarray of int) – The number of points \(R_d \in \mathbb{Z}_{\geq 0}\) at depth \(d\). In other words, for a given number of input points \(m\), and a hierarchy of max depth \(d^*\) the reduced number of points will be \(m \geq R_1 \geq \ldots \geq R_{d^*}\). The value of \(R_d\) will be the same, even for different numbers of input points.
fast_flag_per_depth (list or tuple or np.ndarray of bool) – A flag for each depth level 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.
num_downsampling_neighbors (list or tuple or np.ndarray of int) – How many neighbors consider at each depth to compute the subsampling. For each depth, the number specifies how many points from the source space will be involved in the computation of each point in the downsampled space. The neighborhoods are made of the k-nearest neighbors. Note that the first value in this list corresponds to the num_encoding_neighbors attribute of the ReceptiveFieldFPS receptive field.
num_pwise_neighbors (list or tuple or np.ndarray of int) – How many nearest neighbors consider at each depth-level. In other words, for each point in the structure space at any given depth, the number of nearest neighbors in the same structure space that must be considered.
num_upsampling_neighbors (list or tuple or np.ndarray of int) – How many neighbors consider at each depth to compute the upsampling. For each depth, the number specifies how many points from the source space will be involved in the computation of each point in the upsampled space. The neighborhoods are made of the k-nearest neighbors. Note that the first value in this list corresponds to the reverse indexing matrix (M attribute) of the ReceptiveFieldFPS receptive field.
max_depth (int) – The max depth of the hierarchy, i.e., how many receptive fields.
receptive_field_oversampling (dict or None) – The oversampling specification for the receptive fields (OPTIONAL). See ReceptiveFieldFPS.compute_fps_on_3D_pcloud() and ReceptiveFieldFPS.oversample() for further details.
NDs (list of np.ndarray of int) – The \(\pmb{N}^D_d\) matrices of indices for downsampling with depth \(d=1,\ldots,d^*\). More concretely, \(n^D_{dij}\) is the index of the j-th neighbor in the structure space before the downsampling of the i-th point in the downsampled structure space (at depth \(d\)). It can be seen as an indexing tensor whose slices can be seen as indexing matrices.
Ns (list of np.ndarray of int) – The \(\pmb{N}_d\) matrices of indices for neighborhoods with depth \(d=1,\ldots,d^*\). More concretely, \(n_{dij}\) is the index of the j-th neighbor of the i-th point in the structure space at depth \(d\). It can be seen as an indexing tensor whose slices can be seen as indexing matrices.
NUs (list of np.ndarray of int) – The \(\pmb{N}^U_d\) matrices of indices for upsampling with depth \(d=1,\ldots,d^*\). More concretely, \(n^U_{dij}\) is the index of the j-th neighbor in the structure space before the upsampling of the i-th point in the upsampled structure space (at depth \(d\)).
x (np.ndarray) – The center point of the receptive field. It is assigned when calling receptive_field_fps.ReceptiveFieldFPS.fit().
Ys (np.ndarray) – The hierarchical subsamples representing the original input point cloud and, i.e., a matrices of coordinates in a \(n_x\)-dimensional space such that \(\pmb{Y}_d \in \mathbb{R}^{R_d \times n_x}\).

__init__(**kwargs)

Initialize/instantiate a hierarchical FPS receptive field object.

Parameters:

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

Keyword Arguments:

num_points_per_depth (list or tuple or np.ndarray of int) – The number of points \(R_d \in \mathbb{Z}_{\geq 0}\) at depth \(d\). In other words, for a given number of input points \(m\), and a hierarchy of max depth \(d^*\) the reduced number of points will be \(m \geq R_1 \geq \ldots \geq R_{d^*}\). The value of \(R_d\) will be the same, even for different numbers of input points.
fast_flag_per_depth (list or tuple or np.ndarray of bool) – A flag for each depth level 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.
num_downsampling_neighbors (list or tuple or np.ndarray of int) – How many neighbors consider at each depth to compute the subsampling. For each depth, the number specifies how many points from the source space will be involved in the computation of each point in the downsampled space. The neighborhoods are made of the k-nearest neighbors. Note that the first value in this list corresponds to the num_encoding_neighbors attribute of the ReceptiveFieldFPS receptive field.
num_pwise_neighbors (list or tuple or np.ndarray of int) – How many nearest neighbors consider at each depth-level. In other words, for each point in the structure space at any given depth, the number of nearest neighbors in the same structure space that must be considered.
num_upsampling_neighbors (list or tuple or np.ndarray of int) – How many neighbors consider at each depth to compute the upsampling. For each depth, the number specifies how many points from the source space will be involved in the computation of each point in the upsampled space. The neighborhoods are made of the k-nearest neighbors. Note that the first value in this list corresponds to the reverse indexing matrix (M attribute) of the ReceptiveFieldFPS receptive field.

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 in a recursive way leading to a hierarchy of receptive fields.

See ReceptiveFieldFPS and receptive_field_fps.ReceptiveFieldFPS.fit().

Parameters:

X (np.ndarray) – The input matrix of \(m\) points in a \(n_x\)-dimensional space (for now, \(n_x=3\)).
x (np.ndarray) – The center point used to define the origin of the hierarchical 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:

ReceptiveFieldHierarchicalFPS

centroids_from_points(X)

The centroids of a hierarchical FPS receptive field are said to be subsampled points themselves, as for the ReceptiveFieldFPS.

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): See ReceptiveFieldFPS and receptive_field_fps.ReceptiveFieldFPS.propagate_values().

reduce_values(X, v, reduce_f=<function mean>): See ReceptiveFieldFPS and receptive_field_fps.ReceptiveFieldFPS.reduce_values().

get_downsampling_matrices()

Obtain the downsampling matrices \(\pmb{N}^D_1, \ldots, \pmb{N}^D_{d^{*}}\).

Returns:: The downsampling matrices.
Return type:: list of (list or tuple or np.ndarray) of int

get_neighborhood_matrices()

Obtain the point-wise neighborhoods as matrices of indices \(\pmb{N}_1, \ldots, \pmb{N}_{d^{*}}\).

Returns:: The matrix of indices representing the point-wise neighborhoods.
Return type:: list of (list or tuple or np.ndarray) of int

get_upsampling_matrices()

Obtain the upsampling matrices \(\pmb{N}^U_1, \ldots, \pmb{N}^U_{d^{*}}\).

Returns:: The upsampling matrices.
Return type:: list of (list or tuple or np.ndarray) of int

center_and_scale(X): Like receptive_field_fps.ReceptiveFieldFPS.center_and_scale().

undo_center_and_scale(X): Like receptive_field_fps.ReceptiveFieldFPS.undo_center_and_scale().

optimize_indexing_memory()

Consider all the indexed neighborhoods and select the smallest int type in terms of number of bits that is enough to represent all the neighborhoods at a given depth.

Returns:: Nothing at all, but the indexing matrices of the ReceptiveFieldHierarchicalFPS are updated inplace.

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