src.model.deeplearn.dlrun.grid_subsampling_pre_processor

Classes

GridSubsamplingPreProcessor(**kwargs)

class src.model.deeplearn.dlrun.grid_subsampling_pre_processor.GridSubsamplingPreProcessor(**kwargs)
Author:

Alberto M. Esmoris Pena

Preprocess the input dictionary of X (coordinates), F (features), and y (expected values) so it can be feed to some neural networks such as PointNet.

See ReceptiveFieldGS. See ReceptiveFieldPreProcessor.

Variables:

  • sphere_radius (float) –

    The radius of the sphere that bounds a neighborhood. For an arbitrary set of 3D points it can be found as follows:

    \[r = \dfrac{1}{2} \, \max \; \biggl\{ x_{\mathrm{max}}-x_{\mathrm{min}}, y_{\mathrm{max}}-y_{\mathrm{min}}, z_{\mathrm{max}}-z_{\mathrm{min}} \biggr\}\]

  • separation_factor (float) –

    How many times the sphere radius separates the support points to find the input neighborhoods that will be used to generate the receptive fields for the neural network.

    For a given separation factor \(k\), the following condition should be satisfied to prevent missing any region of the input point cloud on a \(n\)-dimensional space:

    \[k \leq \dfrac{2}{\sqrt{n}}\]

  • cell_size (np.ndarray) – The cell size defining the receptive field. See ReceptiveFieldGS.

  • interpolate (bool) – Flag to control whether to interpolate the missing centroids of the receptive fields (True) or not (False). When interpolating, centroids will be computed from missing centroids. Otherwise, all missing centroids will be replaced by the point obtained as the coordinate-wise mean.

__init__(**kwargs)

Initialization/instantiation of a Grid Subsampling pre-processor.

Parameters:

kwargs – The key-word arguments for the GridSubSamplingPreProcessor.

__call__(inputs)

Executes the pre-processing logic. It also updates the cache-like variables of the preprocessor.

The pre-processing logic consists of steps:

1) Generate support points.

Support points are generated as a set of points separated in \(kr\) units between them and covering the entire point cloud. Watch out, generating support points with \(k > 2/\sqrt{n}\) in a \(n\)-dimensional space leads to gaps between the bounding spheres centered on the support points.

2) Find neighborhoods centered on support points. For each support point, a neighborhood (by default a spherical neighborhood but the neighborhood definition can be arbitrarily changed) centered on it is found.

3) Filter empty neighborhoods. Any support point that leads to an empty neighborhood when considering as neighbors points from the input point cloud is filtered out.

4) Transform non-empty neighborhoods to receptive fields. Each non-empty neighborhood is transformed to a receptive field. See ReceptiveFieldGS for further details.

Parameters:

inputs (dict) – A key-word input where the key “X” gives the input dataset and the “y” (OPTIONALLY) gives the reference values that can be used to fit/train a DL model. If “X” is a list, then the first element is assumed to be the matrix X of coordinates and the second the matrix F of features.

Returns:

Either (Xout, yout) or Xout. Where Xout are the points representing the receptive field and yout (only given when “y” was given in the inputs dictionary) the corresponding reference values for those points.

get_num_input_points()

See point_net_pre_processor.PointNetPreProcessor.get_num_input_points() .

static build_support_points(X, separation_factor, sphere_radius, y=None, class_distr=None, class_distr_shuffle=True, center_on_X=False, support_strategy='grid', support_strategy_num_points=1000, support_strategy_fast=False, nthreads=1)

Compute the support points separated \(k\) times the radius \(r\) distributed along the bounding box defining the boundaries of \(\pmb{X}\).

Alternatively, if the labels pmb{y} are passed and a given class distribution is requested, the support points are selected to match this distribution.

Parameters:

  • X – pmb{X}, i.e., the matrix of coordinates representing the input points.

  • separation_factor – \(k\)

  • sphere_radius – \(r\)

  • y – The vector of point-wise labels (OPTIONAL).

  • class_distr – The vector of class-wise distribution (OPTIONAL).

  • class_distr_shuffle (bool) – Whether to shuffle the point-wise class distribution (default and RECOMMENDED to avoid biases) or not.

  • center_on_X – When True, the support points will be points taken from X (as the nearest neighbors of the initial support points). Otherwise, they will be automatically computed such that they do not necessarily correspond to points in X.

  • support_strategy – By default, “grid”, which means the support points will be taken by grid sampling. It can be “fps” to apply furthest point sampling. The support strategy will be ignored if class_distr is given.

  • support_strategy_num_points – The number of points to be considered when using a furthest point sampling support strategy.

  • support_strategy_fast – Whether to use a random sampling strategy to approximate the FPS (True), or not (False). The approximation strategy is significantly faster than the exhaustive FPS computation, but it only converges for sets with enough points (at least thousands of points).

  • nthreads – How many threads use for parallel computations, if any.

Returns:

The support points as a matrix where rows are support points and columns are coordinates.

Return type:

np.ndarray

static clean_support_neighborhoods(sup_X, I)

Compute the clean version of the given support neighborhoods, i.e., support points in sup_X and their neighborhoods as defined in I but considering only non-empty neighborhoods.

Parameters:

  • sup_X – The matrix of coordinates representing the support points.

  • I – The indices (in the original point domain) corresponding to each support point. In other words, I[i] gives the indices in X of the support point i in X_sup.

Returns:

The clean matrix of coordinates representing the support points and their neighborhoods.

Return type:

tuple

static support_points_to_file(sup_X, path)

Export the given support points to a LAS/LAZ point cloud at the given path.

Parameters:

  • sup_X – The support points to be exported.

  • path – The path where the LAS/LAZ file must be written.

Returns:

Nothing at all, but an output file is generated.

reduce_labels(X_rf, y, I=None)

Reduce the given labels \(\pmb{y} \in \mathbb{Z}_{\geq 0}^{m}\) to the receptive field labels \(\pmb{y}_{\mathrm{rf}} \in \mathbb{Z}_{\geq 0}^{R}\).

Parameters:

  • X_rf (np.ndarray) – The matrices of coordinates representing the receptive fields.

  • y (np.ndarray) – The labels of the original point cloud that must be reduced to the receptive fields.

  • I (list) – The list of neighborhoods. Each element of I is itself a list of indices that represents the neighborhood in the point cloud that corresponds to the point in the receptive field.

Returns:

The reduced labels for each receptive field.

find_neighborhood(X, y=None)

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.

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

overwrite_pretrained_model(spec)

See point_net_pre_processor.PointNetPreProcessor.overwrite_pretrained_model() method.

handle_unit_sphere_transform(I, **kwargs)

Override the handle_unit_sphere_transform() method to make it adequate for the logic of the GridSubsamplingPreProcessor.

See ReceptiveFieldPreProcessor and receptive_field_pre_processor.ReceptiveFieldPreProcessor.handle_unit_sphere_transform().