model.deeplearn.dlrun package

Submodules

model.deeplearn.dlrun.furthest_point_subsampling_post_processor module

class model.deeplearn.dlrun.furthest_point_subsampling_post_processor.FurthestPointSubsamplingPostProcessor(fps_preproc, **kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Postprocess an input in the furthest point subsampling space back to the original space before the subsampling.

See FurthestPointSubsamplingPreProcessor.

Variables:

fps_preproc (FurthestPointSubsamplingPreProcessor) – The preprocessor that generated the furthest point subsampling that must be reverted by the post-processor.

__init__(fps_preproc, **kwargs)

Initialization/instantiation of a Furthest Point Subsampling post-processor.

Parameters:

kwargs – The key-word arguments for the FurthestPointSubsamplingPostProcessor.

__call__(inputs, reducer=None)

Executes the post-processing logic.

Parameters:

  • inputs (dict) – A key-word input where the key “X” gives the coordinates of the points in the original point cloud. Also, the key “z” gives the predictions computed on a receptive field of \(R\) points that must be propagated back to the \(m\) points of the original point cloud.

  • reducer (PredictionReducer) – The prediction reducer for the post-processor, if any.

Returns:

The \(m\) point-wise predictions derived from the \(R\) input predictions on the receptive field.

post_process(inputs, reducer)

Assists the FurthestPointSubsamplingPreProcessor.__call__() providing the post-process logic itself.

model.deeplearn.dlrun.furthest_point_subsampling_post_processorpp module

class model.deeplearn.dlrun.furthest_point_subsampling_post_processorpp.FurthestPointSubsamplingPostProcessorPP(fps_preproc, **kwargs)

Bases: FurthestPointSubsamplingPostProcessor

Author:

Alberto M. Esmoris Pena

C++ implementation of the FurthestPointSubsamplingPostProcessor.

__init__(fps_preproc, **kwargs)

C++ version of FurthestPointSubsamplingPostProcessor.__init__().`

post_process(inputs, reducer)

C++ version of FurthestPointSubsamplingPostProcessor.post_process().

static find_cpp_postproc_fun(Mdtype, Idtype, zdtype)

Determine the C++ function that must be used to post-process the output of the neural network back to the original point cloud.

static find_cpp_reduction_type(reducer)

Determine the C++ reduction strategy that must be used to post-process the output of the neural network back to the original point cloud.

static extract_cpp_extra_args(reducer)

Extract the extra arguments to be passed to the cpp function. See FurthestPointSubsamplingPostProcessorPP.find_cpp_postproc_fun() .

Returns:

The extra arguments are returned as a list that always follows the same order so it can be easily understood by the C++ code.

Rtype list:

model.deeplearn.dlrun.furthest_point_subsampling_pre_processor module

class model.deeplearn.dlrun.furthest_point_subsampling_pre_processor.FurthestPointSubsamplingPreProcessor(**kwargs)

Bases: ReceptiveFieldPreProcessor

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 ReceptiveFieldFPS. See ReceptiveFieldPreProcessor.

Variables:

  • num_points (int) – The number of points any point cloud must be reduced to through furthest point subsampling.

  • num_encoding_neighbors (int) – How many neighbors consider to propagate and also to reduce. See ReceptiveFieldFPS for further details.

  • fast (bool) – Flag to control whether to use random methods to speed up the computation of the furthest point subsampling.

__init__(**kwargs)

Initialization/instantiation of a Furthest Point Subsampling pre-processor.

Parameters:

kwargs – The key-word arguments for the FurthestPointSubsamplingPreProcessor.

__call__(inputs)

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

The pre-processing logic is similar to that of grid_subsampling_pre_processor.GridSubsamplingPreProcessor.__call__() but using a ReceptiveFieldFPS instead of ReceptiveFieldGS.

Parameters:

inputs – See grid_subsampling_pre_processor.GridSubsamplingPreProcessor.__call__() .

Returns:

See grid_subsampling_pre_processor.GridSubsamplingPreProcessor.__call__() .

get_num_input_points()

See point_net_pre_processor.PointNetPreProcessor.get_num_input_points() .

static clean_support_neighborhoods(sup_X, I, num_points, oversampling=None)

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 neighborhoods with more than num_points neighbors.

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 support point i in X_sup.

  • num_points – The expected number of points.

  • oversampling – The oversampling specification, if any.

Returns:

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

Return type:

tuple

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.

Return type:

np.ndarray

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 and receptive_field_pre_processor.ReceptiveFieldPreProcessor.overwrite_pretrained_model().

from_temporary_file()

Realize the logic necessary for Architecture.pre_processor_from_temporary_file().

model.deeplearn.dlrun.furthest_point_subsampling_pre_processorpp module

class model.deeplearn.dlrun.furthest_point_subsampling_pre_processorpp.FurthestPointSubsamplingPreProcessorPP(**kwargs)

Bases: FurthestPointSubsamplingPreProcessor

Author:

Alberto M. Esmoris Pena

C++ implementation of the FurthestPointSubsamplingPreProcessor.

__init__(**kwargs)

C++ version of FurthestPointSubsamplingPreProcessor.__init__().

__call__(inputs)

C++ version of FurthestPointSubsamplingPreProcessor.__call__().

reduce_labels(X_rf, y, I=None)

C++ version of FurthestPointSubsamplingPreProcessor.reduce_labels().

reduce_labels_python(X_rf, y, I=None)

Method that mimics a call to FurthestPointSubsamplingPreProcessor.reduce_labels() to provide a Python alternative to label reduction.

NOTE that this method should only be used for testing and debugging purposes.

static find_cpp_reduce_label_function(y, Ii, N)

Determine the C++ function that must be used to reduce the point-wise labels considering the data types of the input.

Parameters:

  • y (np.ndarray) – The input point-wise labels.

  • Ii (np.ndarray) – The indices of the neighbors in the original point cloud for a given i-th receptive field.

  • N (np.ndarray) – The first downsampling neighborhood of a given i-th receptive field.

Returns:

The C++ function for label reduction.

static prepare_training_class_distribution(training_class_distribution)

Prepare the training class distribution to be used for a C++ deep learning pre-processing call.

Parameters:

training_class_distribution – The training class distribution that must be prepared (typically, it comes from self.training_class_distribution)

Returns:

Prepared training classs distribution.

static prepare_radii(neighborhood_spec)

Prepare the radii argument to be used for a C++ deep learning pre-processing call.

Parameters:

neighborhood_spec (dict) – The neighborhood specification that contains the information that is needed to prepare the radii argument.

Returns:

Prepared radii argument.

Return type:

np.ndarray

static prepare_oversampling(oversampling_spec, num_points)

Prepare the oversampling argument to be used for a C++ deep learning pre-processing call.

Parameters:

  • oversampling_spec (dict) – The oversampling specification that contains the data that is needed to prepare the oversampling arguments.

  • num_points (int) – How many points are requested for the FPS subsampling strategy.

Returns:

Prepared oversampling arguments.

Return type:

list

model.deeplearn.dlrun.grid_subsampling_post_processor module

class model.deeplearn.dlrun.grid_subsampling_post_processor.GridSubsamplingPostProcessor(gs_preproc, **kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Postprocess an input in the grid subsampling space back to the original space before the subsampling.

See GridSubsamplingPreProcessor.

Variables:

gs_preproc (GridSubsamplingPreProcessor) – The preprocessor that generated the grid subsampling that must be reverted by the post-processor.

__init__(gs_preproc, **kwargs)

Initialization/instantiation of a Grid Subsampling post-processor.

Parameters:

kwargs – The key-word arguments for the GridSubsamplingPostProcessor.

__call__(inputs, reducer=None)

Executes the post-processing logic.

Parameters:

  • inputs (dict) – A key-word input where the key “X” gives the coordinates of the points in the original point cloud. Also, the key “z” gives the predictions computed on a receptive field of \(R\) points that must be propagated back to the \(m\) points of the original point cloud.

  • reducer (PredictionReducer) – The prediction reducer for the post-processor, if any.

Returns:

The \(m\) point-wise predictions derived from the \(R\) input predictions on the receptive field.

static pwise_reduce(npoints, nvars, I, v_propagated)

Compute a point-wise reduction of propagated values with overlapping. In other words, this method can be used to reduce values computed on overlapping neighborhoods so there is potentially more than one value for the same variable of the same point. The reduction consists of computing the mean value.

Parameters:

  • npoints – The number of points.

  • nvars – The number of considered point-wise variables.

  • I – The list of neighborhoods. I[i] is the list of indices corresponding to the points composing the neighborhood i.

  • v_propagated – The values to be point-wise reduced. They often come from a propagation operation computed on a receptive field, thus the name.

Returns:

The reduced v vector with a single value for the same variable of the same point.

Return type:

np.ndarray

static post_process(inputs, rf, I, nthreads=1, reducer=None)

Computes the post-processing logic. The method is used to aid the grid_subsampling_post_processor.GridSubsamplingPostProcessor.__call__() method.

Parameters:

  • inputs (dict) – A key-word input where the key “X” gives the coordinates of the points in the original point cloud. Also, the key “z” gives the predictions computed on a receptive field of \(R\) points that must be propagated back to the \(m\) points of the original point cloud.

  • rf (list) – The receptive fields to compute the propagations. See ReceptiveField and ReceptiveFieldGS.

  • I (list) – The list of neighborhoods, where each neighborhood is given as a list of indices.

  • nthreads (int) – The number of threads for parallel computing.

  • reducer (PredictionReducer) – The prediction reducer for the post-processor, if any.

Returns:

The \(m\) point-wise predictions derived from the \(R\) input predictions on the receptive field.

model.deeplearn.dlrun.grid_subsampling_pre_processor module

class model.deeplearn.dlrun.grid_subsampling_pre_processor.GridSubsamplingPreProcessor(**kwargs)

Bases: ReceptiveFieldPreProcessor

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().

model.deeplearn.dlrun.hierarchical_fps_post_processor module

class model.deeplearn.dlrun.hierarchical_fps_post_processor.HierarchicalFPSPostProcessor(hfps_preproc, **kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Postprocess the data from the first level of the FPS hierarchy back to the original space.

See HierarchicalFPSPreProcessor and FurthestPointSubsamplingPostProcessor.

Variables:

hfps_preproc (HierarchicalFPSPreProcessor.) – The preprocessor that generated the hierarchical furthest point subsampling that must be reverted by the post-processor.

__init__(hfps_preproc, **kwargs)

Initialization/instantiation of a hierarchical FPS post-processor.

Parameters:

  • hfps_preproc – The corresponding hierarchical FPS pre-processor.

  • kwargs – The key-word arguments for the HierarchicalFPSPostProcessor.

__call__(inputs, reducer=None)

Executes the post-processing logic.

Parameters:

  • inputs (dict) – A key-word input where the key “X” gives the coordinates of the points in the original point cloud. Also, the key “z” gives the predictions computed on a receptive field of \(R_1\) points (i.e., at depth \(d=1\)) that must be propagated back to the \(m\) points of the original point cloud.

  • reducer (PredictionReducer) – The prediction reducer for the post-processor, if any.

Returns:

The \(m\) point-wise predictions derived from the \(R\) input predictions on the receptive field.

Return type:

np.ndarray

post_process(inputs, reducer)

Assists the HierarchicalFPSPostProcessor.__call__() providing the post-process logic itself.

model.deeplearn.dlrun.hierarchical_fps_post_processorpp module

class model.deeplearn.dlrun.hierarchical_fps_post_processorpp.HierarchicalFPSPostProcessorPP(hfps_preproc, **kwargs)

Bases: HierarchicalFPSPostProcessor

Author:

Alberto M. Esmoris Pena

C++ version of HierarchicalFPSPostProcessor.

__init__(hfps_preproc, **kwargs)

C++ version of HierarchicalFPSPostProcessor.__init__().

post_process(inputs, reducer)

C++ version of FurthestPointSubsamplingPostProcessor.post_process().

model.deeplearn.dlrun.hierarchical_fps_pre_processor module

class model.deeplearn.dlrun.hierarchical_fps_pre_processor.HierarchicalFPSPreProcessor(**kwargs)

Bases: ReceptiveFieldPreProcessor

Author:

Alberto M. Esmoris Pena

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

See ReceptiveFieldHierarchicalFPS. See ReceptiveFieldPreProcessor.

Variables:

  • num_downsampling_neighbors (list) – List with the number of neighbors involved in the downsampling at a given depth, i.e., [i] corresponds to depth i.

  • num_pwise_neighbors (list) – List with the number of k nearest neighbors for the point-wise feature extraction at a given depth, i.e., [i] gives the point-wise knn neighborhoods at depth i.

  • num_upsampling_neighbors (list) – List with the number of neighbors involved in the upsampling at a given depth, i.e., [i] corresponds to depth i.

  • num_points_per_depth (list) – List with the number of points per depth level, i.e., the number of points per receptive field.

  • depth (int) – The depth of the hierarchical receptive fields. At building time it is taken as the length of the number of points per depth level.

  • fast_flag_per_depth (list) – List of boolean flags specifying whether the corresponding receptive field must be computed using a stochastic approximation (faster) or the exhaustive furthest point sampling computation (slower).

__init__(**kwargs)

Initialization/instantiation of a Hierarchical Furthest Point Subsampling pre-processor.

Parameters:

kwargs – The key-word arguments for the Hierarchical Furthest Point Subsampling pre-processor.

__call__(inputs)

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

The pre-processing logic transforms the input structure space matrix \(\pmb{X_{\mathrm{IN}}} \in \mathbb{R}^{m_{\mathrm{IN}} \times n_x}\) (typically \(n_x=3\)), the feature space matrix \(\pmb{F_{\mathrm{IN}}} \in \mathbb{R}^{m_{\mathrm{IN}} \times n_f}\), and potentially the reference values \(\pmb{y} \in \mathbb^{R}{m_{\mathrm{IN}}}\) into many receptive fields. Where \(m_{\mathrm{IN}}\) is the number of input points.

Now, a given receptive field can be represented by a structure space matrix \(\pmb{X} \in \mathbb{R}^{m \times n_x}\), a feature space matrix \(\pmb{F} \in \mathbb{R}^{m \times n_f}, the downsampling indexing matrices :math:\)pmb{N}^{D}_{i} in mathbb{Z}^{m_i}`, the neighborhood indexing matrices \(\pmb{N}_{i} \in \mathbb{Z}^{m_i \times R}\), and the upsampling indexing matrices \(\pmb{N}^{U}_{i} \in \mathbb{Z}^{m_i}\), Where \(i = 1, \ldots, \text{max depth}\), \(m\) is the number of points, \(m_i\) is the number of points at depth i, and \(R in \mathbb{Z}_{>0}\) the number of nearest neighbors defining each point-wise neighborhood.

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 hierarchical model. If “X” is a list, then the first element is assumed to be the matrix \(\pmb{X_{\mathrm{IN}}}\) of coordinates and the second the matrix \(\pmb{F_{\mathrm{IN}}}\) of features. If “X” is a matrix (array), then the matrix of features is assumed to be a column vector of ones.

Returns:

Either (X, F, …NDi…, …Ni…, …NUi…, y) or (X, F, …NDi…, …Ni…, …NUi…). Where X are the input points, F are the input features, NDi are point-wise downsamlping neighborhoods at depth i, Ni are the point-wise neighborhoods at depth i, and NUi are the point-wise upsampling neighborhoods at depth i.

static clean_support_neighborhoods(sup_X, I, num_points, oversampling=None)

See FurthestPointSubsamplingPreProcessor and furthest_point_subsampling_pre_processor.FurthestPointSubsamplingPreProcessor.clean_support_neighborhoods().

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)

See FurthestPointSubsamplingPreProcessor and furthest_point_subsampling_pre_processor.FurthestPointSubsamplingPreProcessor.find_neighborhood().

overwrite_pretrained_model(spec)

See hierarchical_pre_processor.HierarchicalPreProcessor.overwrite_pretrained_model() method and receptive_field_pre_processor.ReceptiveFieldPreProcessor.overwrite_pretrained_model().

model.deeplearn.dlrun.hierarchical_fps_pre_processorpp module

class model.deeplearn.dlrun.hierarchical_fps_pre_processorpp.HierarchicalFPSPreProcessorPP(**kwargs)

Bases: HierarchicalFPSPreProcessor

Author:

Alberto M. Esmoris Pena

C++ version of the HierarchicalFPSPreProcessor.

__init__(**kwargs)

C++ version of FurthestPointSubsamplingPreProcessor.__init__().

__call__(inputs)

C++ version of FurthestPointSubsamplingPreProcessor.__call__().

static optimize_indexing_memory(I)

Optimize the encoding of the received array of indices (I) to use as few bytes as possible. This method assists HierarchicalFPSPreProcessorPP.optimize_indices().

Parameters:

I (np.ndarray of int) – The array of integer indices whose memory encoding must be optimized.

static optimize_indices(depth, NDs, NUs, Ns)

Optimize the memory required to encode the given hierarchical neighborhoods. This method is assisted by HierarchicalFPSPreProcessorPP.optimize_indexing_memory().

Parameters:

  • depth (int) – The depth of the hierarchy.

  • NDs (list) – List whose elements are the downsampling neighborhoods at each depth, i.e. NDs[d] gives the downsampling neighborhoods at depth d.

  • NUs (list) – List whose elements are the upsampling neighborhoods at each depth, i.e. NUs[d] gives the upsampling neighborhoods at depth d.

  • Ns (list) – List whose elements are the neighborhoods at a given depth, i.e. Ns[d] gives the upsampling neighborhoods at depth d.

Returns:

Nothing, but the hierarchical neighborhods (NDs, NUs, Ns) are updated in place.

reduce_labels(X_rf, y, I=None)

C++ version of FurthestPointSubsamplingPreProcessor.reduce_labels().

reduce_labels_python(X_rf, y, I=None)

Method that mimics a call to HierarchicalFPSPreProcessor.reduce_labels() to provide a Python alternative to label reduction.

NOTE that this method should only be used for testing and debugging purposes.

model.deeplearn.dlrun.hierarchical_post_processor module

class model.deeplearn.dlrun.hierarchical_post_processor.HierarchicalPostProcessor(hierarchical_preproc, **kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Postprocess the output of a hierarchical neural network (e.g., hierarchical autoencoders) to transform it to the expected output format.

Variables:

hierarchical_preproc (HierarchicalPreProcessor) – The preprocessor that generated the input for the model which output must be handled by the post-processor.

__init__(hierarchical_preproc, **kwargs)

Initialization/instantiation of a hierarchical post-processor.

Parameters:

  • hierarchical_preproc (HierarchicalPostProcessor) – The pre-processor associated to the model which output must be handled by the post-processor.

  • kwargs – The key-word arguments for the HierarchicalPostProcessor.

__call__(inputs, reducer=None)

Executes the post-processing logic.

Parameters:

  • inputs (dict) – A key-word input where the key “X” give the coordinates of the points in the original point cloud. Also, the key “z” gives the predictions computed on a receptive field of \(R_1\) points that must be propagated back to the \(m\) points of the original point cloud.

  • reducer (PredictionReducer) – The prediction reducer for the post-processor, if any.

Returns:

The \(m\) point-wise predictions.

model.deeplearn.dlrun.hierarchical_pre_processor module

class model.deeplearn.dlrun.hierarchical_pre_processor.HierarchicalPreProcessor(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Preprocess the input dictionary of X (coordinates), F (features), and y (expected values) so it can be feed into a hierarchical neural network (e.g., hierarchical autoencoder).

Variables:

  • pre_processor_type (str) – String representing the type of pre-processor to generate the Input for the hierarchical neural network.

  • pre_processor (HierarchicalFPSPreProcessor.) – The pre-processor itself (instantiated).

__init__(**kwargs)

Initialization/instantiation of a hierarchical pre-processor.

Parameters:

kwargs – The key-word arguments for the HierarchicalPreProcessor.

__call__(inputs)

Executes the pre-processing logic.

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 hierarchical model.

Returns:

Either (X, F, …NDi…, …Ni…, …NUi… yout) or (X, F, …NDi…, …Ni…, …NUi…). Where X are the input points, F are the input features, NDi are point-wise downsamlping neighborhoods at depth i, Ni are the point-wise neighborhoods at depth i, and NUi are the point-wise upsampling neighborhoods at depth i.

overwrite_pretrained_model(spec)

Assist the model.Model.overwrite_pretrained_model() method through assisting the architecture.Architecture.overwrite_pretrained_model() method.

Parameters:

spec (dict) – The key-word specification containing the model’s arguments.

to_temporary_file()

Redirect call to underlying ReceptiveFieldPreProcessor.to_temporary_file() (self.pre_processor).

from_temporary_file()

Redirect call to underlying ReceptiveFieldPreProcessor.from_temporary_file() (self.pre_processor).

model.deeplearn.dlrun.hierarchical_sg_post_processorpp module

class model.deeplearn.dlrun.hierarchical_sg_post_processorpp.HierarchicalSGPostProcessorPP(hsg_preproc, **kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Postprocess the data from the first level of the SG hierarchy back to the original space.

See HierarchicalSGPreProcessor.

Variables:

hsg_preproc – The preprocessor that generated the hierarchical sparse grid that must be reverted by the post-processor.

__init__(hsg_preproc, **kwargs)

Initialization/instantiation of a hierarchical SG post-processor.

Parameters:

  • hsg_preproc – The corresponding hierarchical SG pre-processor.

  • kwargs – The key-word arguments for the HierarchicalSGPostProcessor.

__call__(inputs, reducer=None)

Executes the post-processing logic.

Parameters:

  • inputs (dict) – A key-word input where the key “X” gives the coordinates of the points in the original point cloud. Also, the key “z” gives a list where each element contains the predictions computed on a sparse grid receptive field.

  • reducer (PredictionReducer) – The prediction reducer for the post-processor, if any.

Returns:

The \(m\) point-wise predictions derived from the \(R\) input predictions on the receptive field.

Return type:

np.ndarray

post_process(inputs, reducer)

Assists the HierarchicalSGPostProcessor.__call__() providing the post-process logic itself.

static find_cpp_postproc_fun(Xtype, ztype)

Determine the C++ function that must be used to post-process the output of the neural network back to the original point cloud.

model.deeplearn.dlrun.hierarchical_sg_pre_processorpp module

class model.deeplearn.dlrun.hierarchical_sg_pre_processorpp.HierarchicalSGPreProcessorPP(**kwargs)

Bases: ReceptiveFieldPreProcessor

Author:

Alberto M. Esmoris Pena

Preprocess the input dictionary of X (coordinates), F (features), and y (expected values) so it can be feed to a hierarchical sparse neural network such as sparse convolutional neural network.

See ReceptiveFieldPreProcessor. See ReceptiveFieldHierarchicalSG.

Variables:
__init__(**kwargs)

Initialization/instantiation of a Hierarchical Sparse Grid pre-processor.

Parameters:

kwargs – The key-word arguments for the Hierarchical Sparse Grid pre-processor.

__call__(inputs)

Executes the pre-processing logic.

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 sparse hierarchical model.

Returns:

(F, …ht…, …hDt…, …hUt…, …nt…). Where F are the input features for the first grid in the hierarchy, ht is the map whose keys (domain) are the index of active cells at depth t and whose values (co-domain) represent the sequential indexing of the active cells (e.g., to know what row from F corresponds with a given active cell at the first depth), hDt is the indexing vector that gives the index of the min vertex of the convolutional window at depth t that generates the corresponding active cell at depth t+1, hUt is the indexing vector that gives the index of the min vertex of the convolutional window at depth t+1 that generates the corresponding active cell at depth t, and nt is the number of axis-wise partitions along each axis at depth t.

reduce_labels(X, y, I=None)

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

Parameters:

  • X (np.ndarray) – The matrix representing the structure space of the original input point cloud (i.e., NOT a particular receptive field).

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

  • I (None) – Not used by hierarchical sparse grids.

Returns:

The reduced labels for each receptive field.

Return type:

list

static find_cpp_reduce_label_function(X, y)

Determine the C++ function that must be used to reduce the point-wise labels considering the data types of the input.

Parameters:

  • X (np.ndarray) – The matrix representing the structure space of the original input point cloud (i.e., NOT a particular receptive field).

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

Returns:

The C++ function for label reduction.

overwrite_pretrained_model(spec)

Assist the model.Model.overwrite_pretrained_model() method through assisting the architecture.Architecture.overwrite_pretrained_model() method.

Parameters:

spec (dict) – The key-word specification containing the model’s arguments.

model.deeplearn.dlrun.point_net_post_processor module

class model.deeplearn.dlrun.point_net_post_processor.PointNetPostProcessor(pnet_preproc, **kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Postprocess the output of a PointNet neural network to transform it to the expected output format.

Variables:

pnet_preproc (PointNetPreProcessor) – The preprocessor that generated the input for the model which output must be handled by the post-processor.

__init__(pnet_preproc, **kwargs)

Initialization/instantiation of a PointNet post-processor.

Parameters:

  • pnet_preproc (PointNetPreProcessor) – The pre-processor associated to the model which output must be handled by the post-processor.

  • kwargs – The key-word arguments for the PointNetPostProcessor.

__call__(inputs, reducer=None)

Executes the post-processing logic.

Parameters:

  • inputs (dict) – A key-word input where the key “X” gives the coordinates of the points in the original point cloud. Also, the key “z” gives the predictions computed on a receptive field of \(R\) points that must be propagated back to the \(m\) points of the original point cloud.

  • reducer (PredictionReducer) – The prediction reducer for the post-processor, if any.

Returns:

The \(m\) point-wise predictions.

model.deeplearn.dlrun.point_net_pre_processor module

class model.deeplearn.dlrun.point_net_pre_processor.PointNetPreProcessor(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Preprocess the input dictionary of X (coordinates), F (features), and y (expected values) so it can be feed into the PointNet neural network.

Variables:
__init__(**kwargs)

Initialization/instantiation of a PointNet pre-processor.

Parameters:

kwargs – The key-word arguments for the PointNetPreProcessor.

__call__(inputs)

Executes the pre-processing logic.

See GridSubsamplingPreProcessor and FurthestPointSubsamplingPreProcessor.

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 PointNet model.

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()

PointNet pre-processors must provide the expected number of input points to batch the many input neighborhoods.

Returns:

Number of input points per neighborhood.

Return type:

int

overwrite_pretrained_model(spec)

Assist the model.Model.overwrite_pretrained_model() method through assisting the architecture.Architecture.overwrite_pretrained_model() method.

Parameters:

spec (dict) – The key-word specification containing the model’s arguments.

model.deeplearn.dlrun.receptive_field_pre_processor module

class model.deeplearn.dlrun.receptive_field_pre_processor.ReceptiveFieldPreProcessor(**kwargs)

Bases: object

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.

More concretely, this abstract class implements only the common logic for any pre-processor based on receptive fields. For example, grid subsampling pre-processor, or furthest point subsampling pre-processor.

See ReceptiveField. See GridSubsamplingPreProcessor See FurthestPointSubsamplingPreProcessor

Variables:

  • 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_chunk_size (int) – The number of supports 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.

  • to_unit_sphere (bool) – Whether to map the structure space of the receptive fields to the unit sphere (True) or not (False).

  • 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.

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

  • 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.

  • neighborhood_spec (dict) –

    The neighborhood specification. See the example below.

    {
    "type": "sphere",
    "radius": 5.0,
    "separation_factor": 1.0
}

  • num_classes (int) – The number of different classes that the pre-processor is expected to support when dealing with point-wise labels representing classes.

  • receptive_fields_dir (str or None) – Directory where the point clouds representing the many receptive fields will be exported (OPTIONAL).

  • receptive_fields_distribution_report_path (str or None) – Path where the text-like report on the class distribution of the receptive fields will be exported (OPTIONAL).

  • receptive_fields_distribution_plot_path (str or None) – Path where the plot representing the class distribution of the receptive fields will be exported (OPTIONAL).

  • training_receptive_fields_dir – Like receptive_fields_dir but for the receptive fields at training.

  • training_receptive_fields_distribution_report_path – Like receptive_fields_distribution_report_path but for the receptive fields at training.

  • training_receptive_fields_distribution_plot_path – Like receptive_fields_distribution_plot_path but for the receptive fields at training.

  • last_call_receptive_fields (list) – List of the receptive fields used the last time that the pre-processing logic was executed.

  • last_call_neighborhoods (list) – List of neighborhoods (represented by indices) used the last time that the pre-processing logic was executed.

__init__(**kwargs)

Initialization/instantiation of a Receptive Field pre-processor.

Parameters:

kwargs – The key-word arguments for the ReceptiveFieldPreProcessor.

abstractmethod __call__(inputs)

Any receptive field pre-processor must override this abstract method to implement the pre-processing logic.

export_support_points(inputs, sup_X)

Handle the logic to export the support points.

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 the 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.

  • sup_X (np.ndarray) – The structure space matrix representing the support points.

Returns:

Nothing at all, but output files might be written.

overwrite_pretrained_model(spec)

See point_net_pre_processor.PointNetPreProcessor.overwrite_pretrained_model() method.

update_paths(preproc)

Consider the given specification of pre-processing arguments to update the paths.

static transform_to_unit_sphere(X)

Map the points in \(\pmb{X} \in \mathbb{R}^{m \times n_x}\) to the unit sphere (typically \(n_x = 3\), i.e., 3D).

Let \(r = \max_{1 \leq i \leq m} \; \rVert{\pmb{x}_{i*}}\rVert^2\) where \(\pmb{x}_{i*}\) represents the i-th row (i.e., point) in the matrix \(\pmb{X}\). For then, the structure space transformed to the unit sphere can be represented as follows:

\[\pmb{X'} = \pmb{X}/r\]
Parameters:

X (np.ndarray) – The matrix representing a structure space such that rows are points and columns are coordinates.

Returns:

The structure space matrix transformed to the unit sphere.

Return type:

np.ndarray

handle_unit_sphere_transform(I, **kwargs)

Handle the transformation to the unit sphere of the point-wise coordinates for each input structure space, if requested.

Note that this method might be overriden or ignored by pre-processors providing an alternative strategy to handle the transform of the coordinates to the unit sphere.

Parameters:

  • I (list of list) – The list of neighborhoods such that I[i] is the i-th neighborhood, represented by the indices of the points that belong to that neighborhood. Typically, neighborhoods are centered on the support points.

  • kwargs (dict) – Any extra argument given as a key-value pair.

Returns:

The structure space matrices ready to be fed into the neural network.

Return type:

np.ndarray

fit_receptive_fields(X, sup_X, I)

Update the self.last_call_receptive_fields attribute by calling the fit method of each receptive field. The fitted receptive fields replace the previously available receptive fields.

Parameters:

  • X (np.ndarray) – The structure space matrix representing the point cloud.

  • sup_X (np.ndarray) – The structure space matrix representing the support points defining the receptive fields (typically the centers).

  • I (list of list) – The list of neighborhoods such that I[i] is the i-th neighborhood, represented by the indices of the points that belong to that neighborhood. Typically, neighborhoods are centered on the support points.

Returns:

The self.fit_receptive_fields attribute after the update.

Return type:

list

handle_features_reduction(F, I, rv, Xout=None)

Handle the features reduction operation when the receptive field is called. In doing so, a reduce value function (rv) from the corresponding type of receptive field is often used.

See ReceptiveField and receptive_field.ReceptiveField.reduce_values().

Parameters:

  • F – The matrix of features.

  • 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.

  • rv (Callable) – The reduce value function that receives three arguments as input. The i-th receptive field (rf_i), the structure space matrix for the i-th receptive field (Xout_i), and the matrix of features (F).

  • Xout (list of np.ndarray or np.ndarray as a tensor whose slices represent receptive fields.) – The structure space matrix for each receptive field. It can be None (default). In this case, it will be considered that each receptive field has a None structure space matrix and that it will be handled by the logic of the receptive field.

Returns:

The reduced matrix of features for each receptive field.

Return type:

np.ndarray as a tensor whose slices represent receptive fields.

static num_classes_from_pwise_labels(preproc, y)
purge_receptive_fields()

Function to clean all the receptive fields stored in the pre-processor.

to_temporary_file()

Realize the logic necessary for Architecture.pre_processor_to_temporary_file().

from_temporary_file()

Realize the logic necessary for Architecture.pre_processor_from_temporary_file().

Module contents

author:

Alberto M. Esmoris Pena

The deep learning runnable package contains the logic to handle runnable (also callable or functors) components governing the dataflow of deep learning architectures.