utils.ptransf package

Submodules

utils.ptransf.data_augmentor module

class utils.ptransf.data_augmentor.DataAugmentor(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Interface representing a data augmentation object. Any class must realize this interface if it aims to provide data augmentation capabilities.

__init__(**kwargs)

abstractmethod augment(X, **kwargs)

Augment the given input data.

Parameters:

• X – The input data.

• kwargs – Key-word arguments for data augmentors that need further input specifications.

Returns:

The augmented input data.

utils.ptransf.fps_decorator_transformer module

class utils.ptransf.fps_decorator_transformer.FPSDecoratorTransformer(**kwargs)

Bases: PointCloudSamplerDecorator

Author:

Alberto M. Esmoris Pena

Class representing an FPS transformer that can be used to decorate different components of the framework.

A point cloud \(\pmb{P} = [\pmb{X} | \pmb{F} | \pmb{y}]\) can be reduced to an FPS representation \(\pmb{P'} = [\pmb{X'} | \pmb{F'} | \pmb{y'}]\). More concretely, an input point cloud with dimensionalities \(\pmb{X} \in \mathbb{R}^{m \times n_x}\), \(\pmb{F} \in \mathbb{R}^{m \times n_f}\), \(\pmb{y} \in \mathbb{Z}^{m}\) will be transformed to a representation with dimensionalities \(\pmb{X'} \in \mathbb{R}^{R \times n_x}\), \(\pmb{F'} \in \mathbb{R}^{R \times n_f}\), \(\pmb{y'} \in \mathbb{Z}^{R}\) where \(R \leq m\).

Variables:

• num_points (int or str) – 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\). Alternatively, it can be given as a string. If so, it is understood as an expression that can be evaluated, where “m” is the number of input points. For instance: “m/2” means the FPS will consider half of the input points.

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

• threads – See PointCloudSamplerDecorator.

• num_encoding_neighbors – See PointCloudSamplerDecorator.

• num_decoding_neighbors – See PointCloudSamplerDecorator.

• release_encoding_neighborhoods – See PointCloudSamplerDecorator.

• representation_report_path – See RepresentationReportPath

__init__(**kwargs)

Initialize/instantiate a furthest point sampling decorator object.

Parameters:

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

Keyword Arguments:

• num_points (int or str) – 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\). Alternatively, it can be given as a string. If so, it is understood as an expression that can be evaluated, where “m” is the number of input points. For instance: “m/2” means the FPS will consider half of the input points.

• num_encoding_neighbors (int) –

  See PointCloudSamplerDecorator.__init__().

• num_decoding_neighbors (int) –

  See PointCloudSamplerDecorator.__init__().

• release_encoding_neighborhoods (bool) –

  See PointCloudSamplerDecorator.__init__().

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

• threads (int) –

  See PointCloudSamplerDecorator.__init__().

• representation_report_path (str) –

  See PointCloudSamplerDecorator.__init__().

transform(X, F=None, y=None, out_prefix=None)

See PointCloudSamplerDecorator.transform().

eval_num_points(X=None, m=None)

Evaluate the number of points if it is a string and return the result, otherwise return the number directly.

Parameters:

• X (np.ndarray or None) – The structure space matrix representing the point cloud (rows are columns),

• m (int or None) – The number of points (when not given, the number of rows in X will be considered to initialize m) in the point cloud.

Returns:

The number of points that must be obtained after applying the transformation.

Return type:

int

utils.ptransf.min_dist_decimator_decorator module

class utils.ptransf.min_dist_decimator_decorator.MinDistDecimatorDecorator(**kwargs)

Bases: PointCloudSamplerDecorator

Author:

Alberto M. Esmoris Pena

Class representing a minimum distance decimator that can be used to decorate different components of the framework.

A point cloud \(\pmb{P} = [\pmb{X} | \pmb{F} | \pmb{y}]\) can be reduced to a minimum distance decimated representation \(\pmb{P'} = [\pmb{X'} | \pmb{F'} | \pmb{y'}]\). More concretely, an input point cloud with dimensionalities \(\pmb{X} \in \mathbb{R}^{m \times n_x}\), \(\pmb{F} \in \mathbb{R}^{m \times n_f}\), \(\pmb{y} \in \mathbb{Z}^{m}\) will be transformed to a representation with dimensionalities \(\pmb{X'} \in \mathbb{R}^{R \times n_x}\), \(\pmb{F'} \in \mathbb{R}^{R \times n_f}\), \(\pmb{y'} \in \mathbb{Z}^{R}\) where \(R \leq m\).

Variables:

min_distance (float) – The minimum distance such that any pair of points in the decimated representation must be separated by at least this distance.

__init__(**kwargs)

Initialize/instantiate a minimum distance decimator

Parameters:

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

Keyword Arguments:

• min_distance (float) – The minimum distance separating the points in the subsampled representation.

• num_encoding_neighbors (int) –

  See PointCloudSamplerDecorator.__init__().

• num_decoding_neighbors (int) –

  See PointCloudSamplerDecorator.__init__().

• release_encoding_neighborhoods (bool) –

  See PointCloudSamplerDecorator.__init__().

• threads (int) –

  See PointCloudSamplerDecorator.__init__().

• representation_report_path (str) –

  See PointCloudSamplerDecorator.__init__().

transform(X, F=None, y=None, out_prefix=None)

See PointCloudSamplerDecorator.transform().

utils.ptransf.point_cloud_sampler module

class utils.ptransf.point_cloud_sampler.PointCloudSampler(**kwargs)

Bases: PointTransformer

Author:

Alberto M. Esmoris Pena

Class for transforming points following one or many sampling strategies.

Variables:

neighborhood_sampling (dict or None) –

The specification of the neighborhood sampling strategy, if any.

The format for this attribute should be like:

{
    "support_conditions": [
        {
            "value_name": "ClassAmbiguity",
            "condition_type": "greater_than_or_equal_to",
            "value_target": 0.5,
            "action": "preserve"
        }
    ],
    "support_strategy": "fps",
    "support_strategy_num_points": 100000,
    "support_strategy_fast": true,
    "support_chunk_size": 50000,
    "center_on_pcloud": false,
    "neighborhood": {
        "type": "sphere",
        "radius": 2.5,
        "separation_factor": 0
    },
    "neighborhoods_per_iter": 10000,
    "nthreads": -1
}

static extract_ptransf_args(spec)

Extract the arguments to initialize/instantiate a PointCloudSampler.

Parameters:

spec – The key-word specification containing the arguments.

Returns:

The arguments to initialize/instantiate a PointCloudSampler.

Return type:

dict

__init__(**kwargs)

Initialize/instantiate a PointCloudSampler.

Parameters:

kwargs – The attributes for the PointCloudSampler.

transform(X=None, F=None, y=None, yhat=None, out_prefix=None, **kwargs)

The fundamental point transform logic defining the point cloud sampler.

See PointTransformer and PointTransformer.transform().

transform_pcloud(pcloud, out_prefix=None, **kwargs)

Update the input point cloud in place.

See PointCloudSampler.transform() and PointTransformer.transform_pcloud().

apply_neighborhood_sampling(X, F, y, yhat, out_prefix=None, **kwargs)

Compute a neighborhood sampling. This strategy considers each support point (for example, the entire X, or a subset of X that satisfied the given conditions) and computes it neighborhood. The indices of the points in the neighborhoods are then returned.

Parameters:

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

• F (np.ndarray or None) – the feature space matrix representing the point cloud to be sampled.

• y (np.ndarray or None) – The references of the point cloud to be sampled (typically a vector of classes).

• yhat (np.ndarray or None) – The predictions on the point cloud to be sampled ( typically a vector of classes).

• out_prefix – See PointTransformer and PointTransformer.transform().

Returns:

List with the indices of the points to be included in the sampled version of the point cloud.

Return type:

List of int

static update_selected_indices(base_selected_indices, new_selected_indices, X, F, y, yhat)

Merge the current selected indices with the new selected indices. Note that the resulting selected indices are built by selecting those indices at base_selected_indices specified by new_selected_indices.

Returns:

The new list of selected indices.

Return type:

list

filter_support_points(conditions, X, F, y, yhat, min_distance=None, out_prefix=None)

Filter the given point cloud considering the given conditions to obtain the corresponding support points.

Parameters:

• conditions (list of dict) –

  A list with the dictionary-like specifications of each condition that must be applied. Each condition must specify:

  – "value_name"The name of the value involved in the

  condition.

  – "condition_type"The relational governing the condition,

  i.e., "not_equals" (\(\neq\)), "equals" (\(=\)), "less_than" (\(<\)), "less_than_or_equal_to" (\(\leq\)), "greater_than" (\(>\)), "greater_than_or_equal_to" (\(\geq\)), "in" (\(\in\)), or "not_in" (\(\notin\)).

  – "value_target"The value for the rhs of the relational.

  Note that the lhs will be the corresponding value from the point cloud.

  – "action"Whether the conditions define points that must be

  preserved ("preserve") or discarded ("discard").

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

• F (np.ndarray or None) – The feature space matrix representing the point cloud.

• y (np.ndarray or None) – The references of the point cloud.

• yhat (np.ndarray or None) – The predictions of the point cloud.

• min_distance (float or None) – When given, support points that are closer to other support points in less than min_distance will be discarded.

• out_prefix – See PointTransformer and PointTransformer.transform().

Returns:

The structure space matrix representing the support points.

Return type:

np.ndarray

apply_condition(cond, X, F, y, yhat)

Apply the given condition to the given point cloud. See PointCloudSampler.filter_support_points() for further details when using this function to filter the support points.

Returns:

The structure space, feature space, references, and predictions of the filtered point cloud.

Return type:

tuple of np.ndarray

static compute_neighborhoods(X, X_sup, neighborhood_spec, support_chunk_size=0, kdt=None)

Compute the neighborhood of each support point on X.

See SupportNeighborhoods for more details.

Parameters:

• X_sup (np.ndarray) – The support structure space.

• X (np.ndarray) – The structure space where the neighbors must be.

• neighborhood_spec (dict) – The key-word specification of the neighborhood.

• support_chunk_size (int) – See SupportNeighborhoods.

• kdt – See SupportNeighborhoods.compute().

utils.ptransf.point_cloud_sampler_decorator module

class utils.ptransf.point_cloud_sampler_decorator.PointCloudSamplerDecorator(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Class representing an abstract sampler that transforms the number of points in a point cloud and can be used to decorate different components of the framework.

Typically, \(m \in \mathbb{Z}_{>0}\) denotes the number of points in the input point cloud and \(R \in \mathbb{Z}_{>0}\) the number of points in the sampled point cloud.

Variables:

• num_encoding_neighbors (int) – How many closest neighbors consider when doing reductions. For instance, for three encoding neighbors reducing a value means three points in the original domain will be considered to estimate the value in the representation domain. A value of zero means the representation will be generated but no neighborhood information connecting the points from the original domain to the representation domain will be computed.

• num_decoding_neighbors (int) – How many closest neighbors consider when doing propagations. For instance, for three decoding neighbors propagating a value means three points in the representation domain will be considered to estimate the value in the original domain. A value of zero means the representation will be generated but no neighborhood information connecting the points from the representation domain back to the original domain will be computed.

• release_encoding_neighborhoods – A flag to enable releasing the encoding neighborhoods after building the representation. It can be used to save memory when the topological information of the encoding process will not be used after generating the representation.

• representation_report_path (str) – Path where a point cloud with the points in the representation space will be exported.

• threads (int) – The number of threads to be used for parallel computations. A value of -1 means using all available cores.

• N (np.ndarray) – The encoding neighborhoods that define what points in the original space must be considered to obtain each point in the representation space. It is a matrix \(\pmb{N} \in \mathbb{R}^{R \times k_e}\) for \(k_e\) encoding neighbors where each row corresponds to a point in the reduced space and the columns give the indices of their neighbors in the original space.

• M (np.ndarray) – The decoding neighborhoods that define what points in the representation space must be considered to propagate back to the original space. It is a matrix \(\pmb{M} \in \mathbb{R}^{m \times k_d}\) for \(k_d\) decoding neighbors where each row corresponds to a point in the original space and the columns give the indices of their neighbors in the reduced space.

__init__(**kwargs)

Initialize/instantiate a point cloud sampler decorator object.

Parameters:

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

Keyword Arguments:

• num_encoding_neighbors (int) –

  How many closest neighbors consider when doing reductions. For instance, for three encoding neighbors reducing a value means three points in the original domain will be considered to estimate the value in the representation domain. A value of zero means the representation will be generated but no neighborhood information connecting the points from the original domain to the representation domain will be computed.

• num_decoding_neighbors (int) –

  How many closest neighbors consider when doing propagations. For instance, for three decoding neighbors propagating a value means three points in the representation domain will be considered to estimate the value in the original domain. A value of zero means the representation will be generated but no neighborhood information connecting the points from the representation domain back to the original domain will be computed.

• release_encoding_neighborhoods (bool) –

  A flag to enable releasing the encoding neighborhoods after building the representation. It can be used to save memory when the topological information of the encoding process will not be used after generating the representation.

• threads (int) –

  The number of threads to be used for parallel computations. Giving -1 means using all available cores.

• representation_report_path (str) –

  Path where a point cloud with the points in the representation space will be exported.

abstractmethod transform(X, F=None, y=None, out_prefix=None)

Transform the given point cloud to its sampled representation.

Note that any concrete point cloud sampler decorator implementation must provide its own logic for this method.

Parameters:

• X – The structure space matrix (i.e., the matrix of coordinates).

• F – The feature space matrix (i.e., the matrix of features).

• y – The reference classes (i.e., the classification).

• out_prefix – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

The structure space matrix, the feature space matrix, and the classes vector of the sampled representation.

Return type:

tuple (np.ndarray, np.ndarray or None, np.ndarray or None)

transform_pcloud(pcloud, fnames=None, ignore_y=False, out_prefix=None)

Transform the given point cloud to its sampled representation.

Parameters:

• pcloud (PointCloud) – The point cloud to be transformed.

• fnames (None or list of str) – A list with the names of the features to be considered. If an empty list is given, no features will be considered. If None is given, all features will be considered.

• ignore_y (bool) – Whether to ignore the classes (True) or to encode them in the representation (False).

• out_prefix (None or str) – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

A new point cloud that is a sampled representation of the input one.

Return type:

PointCloud

propagate(rep_x)

Propagate a representation on \(R\) back to the original space of \(m\) points.

Parameters:

rep_x (np.ndarray) – The representation to be propagated back to the original space. When given as a matrix, rows must be points and columns must be point-wise values.

Returns:

The propagated representation.

Return type:

np.ndarray

reduce(x)

Reduce the original space of \(m\) points to a representation space of \(R\) points.

Parameters:

x (np.ndarray) – The original values to be reduced to the representation space. When given as a matrix, rows must be points and columns must be point-wise values.

Returns:

The reduced values.

Return type:

np.ndarray

handle_encoding_neighbors(X, rep_X)

Compute the encoding neighbors, if necessary.

Parameters:

• X (np.ndarray) – The input structure space.

• rep_X (np.ndarray) – The sampled representation of the structure space.

Returns:

Nothing at all, but self.N is updated.

handle_decoding_neighbors(X, rep_X)

Compute the decoding neighbors, if necessary.

Parameters:

• X (np.ndarray) – The input structure space.

• rep_X (np.ndarray) – The sampled representation of the structure space.

Returns:

Nothing at all, but self.M is updated.

encode(F, y)

Encode the point-wise features and classes.

Parameters:

• F (np.ndarray) – The input feature space matrix.

• y (np.ndarray) – The input vector of classes.

Returns:

The encoded feature space matrix and point-wise classes vector. If any of them was given as None input, the returned one will also be None.

Return type:

tuple of np.ndarray

handle_encoding_neighborhoods_release()

Release the encoding neighborhoods if requested, i.e., if self.release_encoding_neighborhoods is True.

Returns:

Nothing, but self.N is set to None.

export_representation(rep_X, rep_F, rep_y, out_prefix=None)

Export the sampled representation of the point cloud.

Parameters:

• rep_X (np.ndarray) – The structure space matrix of the sampled representation.

• rep_F (np.ndarray) – The feature space matrix of the sampled representation.

• rep_y (np.ndarray) – The point-wise classes vector of the sampled representation.

• out_prefix (None or str) – The output prefix (OPTIONAL). If given, it will be used to particularize the output path.

Returns:

Nothing, but the sampled point cloud is exported to the representation report path.

encode_decode_release_and_export(X, F, y, rep_X, out_prefix=None)

Handle the encoding, decoding, release, and export stages. These are typical computed as a post-processing step after the computation of the sampled structure space.

Parameters:

• X (np.ndarray) – The input structure space.

• F (np.ndarray or None) – The input feature space.

• y (np.ndarray or None) – The input point-wise classes.

• rep_X (np.ndarray) – The sampled structure space.

• out_prefix (str or None) – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

The feature space matrix and vector of points-wise classes obtained after encoding features and classes from the input point cloud into the sampled point cloud.

Return type:

tuple of np.ndarray

utils.ptransf.point_transformer module

exception utils.ptransf.point_transformer.PointTransformerException(message='')

Bases: VL3DException

Author:

Alberto M. Esmoris Pena

Class for exceptions related to point transformation components. See VL3DException

__init__(message='')

class utils.ptransf.point_transformer.PointTransformer(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Class for point transformation operations.

Variables:

• fnames (None or list of str) – The names of the features involved in the transformation (by default None, which will lead to considering all the features in the point cloud).

• _fnames (np.ndarray of str) – A cache with the names of the features involved in the CURRENT transformation. It can be different to fnames. For example, when fnames is None, _fnames will contain the name for each feature in the point cloud. It must not be used outside the scope of an ongoing transformation (consistency is not guaranteed).

static extract_ptransf_args(spec)

__init__(**kwargs)

Initialize/instantiate a PointTransformer.

Parameters:

kwargs – The attributes for the PointTransformer.

abstractmethod transform(X=None, F=None, y=None, yhat=None, out_prefix=None, **kwargs)

The fundamental transformation logic defining the point transformer.

Parameters:

• X (np.ndarray or None) – The structure space matrix of the point cloud to be transformed.

• F (np.ndarray or None) – The feature space matrix of the point cloud to be transformed.

• y (np.ndarray or None) – The references (if any) of the point cloud to be transformed.

• yhat (np.ndarray or None) – The predictions (if any) on the point cloud to be transformed.

• out_prefix (str or None) – The output prefix (OPTIONAL). It might be used to particularize output paths, if any.

• kwargs (dict) – Further key-word arguments defining the transformation.

transform_pcloud(pcloud, out_prefix=None, **kwargs)

Apply the transform method to a point cloud.

See point_transformer.PointTransformer.transform().

Parameters:

• pcloud (PointCloud) – The point cloud to be transformed.

• out_prefix (str or None) – The output prefix (OPTIONAL). It might be used to particularize output paths, if any.

• kwargs (dict) – Further key-word arguments defining the transformation.

Returns:

Whatever the transform method of the non-abstract derived class returns. Thus, in general, this method will need to be overridden to properly return a point cloud (see PointCloud).

utils.ptransf.receptive_field module

class utils.ptransf.receptive_field.ReceptiveField(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Interface representing a receptive field. Any class must realize this interface if it aims to provide receptive field-like transformations.

__init__(**kwargs)

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

Fit the receptive field to represent the given points.

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 (int or str) – Either an integer or a string identifying the receptive field that is being fit. Alternatively it can be None. Note that this argument is meant to be used only for certain purposes, but it is not fundamental for the receptive field. An example can be identifying the current receptive field to name an output report (see ReceptiveFieldOversamplingReport, ReceptiveFieldFPS.fit(), and ReceptiveFieldFPS.compute_fps_on_3D_pcloud()).

Returns:

The fit receptive field itself (for fluent programming).

Return type:

ReceptiveField

abstractmethod centroids_from_points(X)

Compute the centroids, i.e., the points representing the original point cloud in the receptive field space. The points do not need to be actual centroids. The name comes from typical rectangular-cells which are represented by computing the cell-wise centroid considering all points inside a given cell.

Parameters:

X (np.ndarray) – The matrix of input points

Returns:

A matrix which rows are the points representing the centroids.

Return type:

np.ndarray

abstractmethod propagate_values(v)

Propagate given values, so they are associated to the points in the original space preceding the receptive field. In other words, the values v in the domain of the receptive field are transformed back to the original domain before the receptive field was computed.

Parameters:

v (list) – The values to be propagated from the receptive field back to the original domain.

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

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

Reduce given values so there is one per centroid in the receptive field at most.

Parameters:

• X (np.ndarray) – The matrix of coordinates representing the centroids of the receptive field.

• v (np.ndarray) – The vector of values to be reduced.

• reduce_f (callable) – The function to reduce many values to a single one. By default, it is the mean.

Returns:

The reduced vector.

Return type:

np.ndarray

canibalize(rf)

Take the values from given receptive field.

Parameters:

rf – Receptive field whose attributes will be canibalized.

utils.ptransf.receptive_field_fps module

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

Bases: ReceptiveField

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

utils.ptransf.receptive_field_fpspp module

class utils.ptransf.receptive_field_fpspp.ReceptiveFieldFPSPP(**kwargs)

Bases: ReceptiveFieldFPS

Author:

Alberto M. Esmoris Pena

C++ implementation of the ReceptiveFieldFPS.

__init__(**kwargs)

See ReceptiveFieldFPS and ReceptiveFieldFPS.__init__().

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

C++ version of ReceptiveFieldFPS.fit().

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

C++ version of ReceptiveFieldFPS.propagate_values().

static do_propagate_values(M, v, reduce_strategy)

See ReceptiveFieldFPSPP.propagate_values().

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

C++ version of ReceptiveFieldFPS.reduce_values().

reduce_values_python(X, v, reduce_f=<function mean>)

Method that calls ReceptiveFieldFPS.reduce_values() to provide a Python alternative to reductions.

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

static do_reduce_values(N, X, v, reduce_f)

See ReceptiveFieldFPSPP.reduce_values().

utils.ptransf.receptive_field_gs module

class utils.ptransf.receptive_field_gs.ReceptiveFieldGS(**kwargs)

Bases: ReceptiveField

Author:

Alberto M. Esmoris Pena

Class representing a receptive field based on grid subsampling.

Receptive fields constitute a discrete representation of a point cloud of m points using R points. More formally, the receptive field can be defined as a transformation \(\mathcal{R}(\pmb{X})\) such that:

\[\mathcal{R}: \mathbb{R}^{m \times n} \rightarrow \mathbb{R}^{R \times n}\]

The receptive field transformation is modelled using an indexing matrix \(\pmb{N} \in \mathbb{Z}_{\geq -1}^{R \times R^*}\), where \(R^*\) represents the number of correspondences of the point in \(\mathcal{R}\) that corresponds to the maximum number of points in \(\pmb{X}\). Each row \(\pmb{n}_{i*} \in \mathbb{Z}_{\geq -1}^{R^*}\) contains the indices of the points in \(\pmb{X}\) that are associated to the point \(i\) in \(\mathcal{R}\). Furthermore, the greater-than-or-equal-to-zero integer universe is extended with a \(-1\) symbol that does not represent the minus one number, but instead it is the shadow element of the universe. This shadow index is interpreted in the context of the receptive field as a mask that disables certain computations for some empty cells in the receptive field. It is used to model \(\pmb{N}\) as a matrix, for convenience.

The baseline receptive field is implemented as an n-dimensional grid that supports axis-wise steps for its definition. It can be used to build a representation of a point cloud, do some computation on the representation, and then propagate the values back to the original point cloud. For example, the computation can be a classification computed by a neural network that works on sets of \(R\) points.

See ReceptiveField and GridSubsamplingPreProcessor.

Variables:

• cell_size (np.ndarray) – The cell size with respect to the radius. It is noted as \(\pmb{s} = (s_1, \ldots, s_n)\). Each \(s_i \in [0, 2]\) defines how many times the radius must be considered as the step. A value of 2 means there is only one partition along the axis i, and a value of 1 means there are two partitions because the total considered length is twice the radius per axis. In general, a value of \(0 \leq s_i \leq 2\) leads to \(\left\lceil{\dfrac{2}{s_i}}\right\rceil\) partitions.

• dimensionality (int) – The dimensionality of the space where the points are defined. Typically, it refers to the dimensionality of the structure space, i.e., the points without the features. For example, considering the \((x, y)\) coordinates of the points implies a dimensionality \(n=2\), while considering the \((x, y, z)\) coordinates of the points implies a dimensionality \(n=3\).

• bounding_radii (np.ndarray) –

  The radii vector \(\pmb{r} = (r_1, \ldots, r_n)\) that defines the radius for each axis. The length of the axis \(i\) represented by the receptive field is given by \(2 \times r_i\), i.e., twice the axis radius.

  One simple way to compute the bounding radius for a set of coordinates \(X_i = \{x_{1i}, \ldots, x_{mi}\}\) is:

  \[r_i = \dfrac{\max X_i - \min X_i}{2}\]

• num_cells (int) –

  The number of cells \(R\) composing the receptive field. It is computed as:

  \[R = \Biggl\lfloor\biggl({ \prod_{i=1}^{n}{\dfrac{s_i}{2}} }\biggr)^{-1}\Biggr\rceil\]

  Where \(\lfloor x \rceil\) means rounding to the nearest integer of x with round half toward positive infinity as tie-breaking rule.

• N (np.ndarray) – The indexing matrix \(\pmb{N}_{\geq -1}\) described above. It is computed when calling receptive_field_gs.ReceptiveFieldGS.fit().

• x (np.ndarray) – The center point of the receptive field. It is assigned when calling receptive_field_gs.ReceptiveFieldGS.fit().

• m (int) – The number of points represented in the receptive fields. It is assigned when calling receptive_field_gs.ReceptiveFieldGS.fit().

__init__(**kwargs)

Initialize/instantiate a receptive field object.

Parameters:

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

Keyword Arguments:

• bounding_radii (np.ndarray) – The bounding radius for each axis defining the receptive field. See ReceptiveFieldGS for a more detailed description.

• cell_size (np.ndarray) – The cell size defining the receptive field. By default it is \((0.05, 0.05, 0.05)\). See ReceptiveFieldGS for a more detailed description.

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

Fit the receptive field to represent the given points by building a grid containing them.

The matrix of indices \(\pmb{N} \in \mathbb{Z}_{\geq -1}^{R \times R^*}\) is computed here. See also receptive_field_gs.ReceptiveFieldGS.shadow_indexing_matrix_from_points() .

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.

Returns:

The fit receptive field itself (for fluent programming).

Return type:

ReceptiveFieldGS

centroids_from_points(X, interpolate=False, fill_centroid=False)

Compute the centroids, i.e., for each cell in the receptive field the point that represents the cell assuming the receptive field is applied to the rows of \(\pmb{X} \in \mathbb{R}^{m \times n}\) understood as points.

Let \(\pmb{Y} \in \mathbb{R}^{R \times n}\) be the matrix whose rows represent the centroids. Besides, consider the set of neighbors for a given point \(i\) as \(\mathcal{N}_i = \lvert\left\{n_{ij} \geq 0 : 1 \leq j \leq R^* \rvert\right\}\) , where \(n_{ij}\) is the element at row \(i\) column \(j\) in the matrix \(\pmb{N}\) (see ReceptiveFieldGS). For then, each centroid can be computed such that:

\[\pmb{y}_{i*} = \lvert\mathcal{N}_{i}\rvert^{-1} \sum_{j \in \mathcal{N}_{i}}{\pmb{x}_{j*}}\]

Regarding the interpolation, any missing centroid is defined considering the midrange point of the cell (i.e., the geometric center) and its \(3^{n}-1\) closest neighbors. The coordinate-wise mean of these points yields the interpolated value. The reason why \(3^{n}-1\) is selected as the number of neighbors for the interpolation is based on the idea that for 2D and 3D neighborhoods considering a cell in a grid and all its neighbor cells yields \(3^{n}\) neighbors. One is discarded because it corresponds to the cell itself being interpolated. Consequently, \(3^{n}-1\) is expected to be a reasonable compromise to avoid considering too much points so the interpolated point represents the entire receptive field instead of the local region where it belongs to. At the same time, the number of neighbors also scales with the dimensionality to provide an acceptable sample for a reliable interpolation.

Parameters:

• X (np.ndarray) – The matrix of input points

• interpolate (bool) – True to interpolate missing centroids from non-missing centroids, False otherwise.

• fill_centroid (bool) – When interpolate is False and fill_centroid is True, all missing points will be fill as the centroid of the input point cloud.

Returns:

A matrix which rows are the points representing the centroids.

Return type:

np.ndarray

propagate_values(v, safe=True, **kwargs)

Propagate given values, so they are associated to the points in \(\pmb{X}\).

Propagating can be seen as a pseudo-injective map. Clearly, when \(R<m\), there is no injective map between \(\mathcal{R}\) and \(\pmb{X}\) because a single point in \(\mathcal{R}\) can correspond to more than one point in \(\pmb{X}\). However, when propagating, each point in \(\mathcal{R}\) can be associated to each corresponding point in \(\pmb{X}\) thanks to the \(\pmb{N}\) matrix.

More concretely, propagating values can be seen as a map that transforms the given sequence of values \(v_1, \ldots, v_{R_p}\), where \(R_p \leq R\) is the number of non-empty rows in \(\pmb{N}\). Note a row i is said to be empty when \(n_{ij} = -1, \forall 1 \leq j \leq R^*\). The output of the transformation is the sequence of values \(y_1, \ldots, y_m\) such that \(y_i = v_j\), satisfying the point i in \(\pmb{X}\) corresponds to the non-empty cell j in \(\mathcal{R}\).

Parameters:

• v (list) – The values to be propagated. There must be one value per non-empty cell in the receptive field. The values must preserve the order of the non-empty cells. In other words, \(v_j\) must either belong to the cell \(j\) or the cell \(j+k\) where k is the number of empty cells with index \(<j\).

• safe (bool) – True to compute the propagation in safe mode, i.e., raising an exception when there are NaN in the propagation. False otherwise.

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

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

Let \(\pmb{X} \in \mathbb{R}^{R \times n}\) be the matrix of row-wise points such that the row i is the centroid that represents the cell i in the receptive field. Let \(\pmb{v} \in \mathbb{K}^{m}\) be a vector that must be reduced to the receptive field to produce \(\pmb{y} \in \mathbb{K}^{R}\).

For a given reduce function \(f\) that maps an arbitrary number of input values to a single value, let \(u\) represent its input. Note that \(u\) represents any vector whose components are a subset of the set of components defining the vector \(v\). For then, the reduce_values() procedure can be expressed as \(y_{i} = f(u_i)\).

It might happen that some cells are empty and thus, no value is assigned to them during reduction. In those cases, it is possible to apply a filling rule that consists of assuming each empty cell has a value equal to that of its closest neighbor.

Parameters:

• X (np.ndarray) – The centroid representing each cell in matrix form. Each row i of X represents the centroid of a cell i from the 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.

• fill_nan (bool) – True to fill NaN values with the value of the closest non-empty cell in the receptive field.

Returns:

The reduced vector.

Return type:

np.ndarray

shadow_indexing_matrix_from_points(X)

Compute the indexing matrix (supporting shadow indices) \(\pmb{N} \in \mathbb{Z}_{\geq -1}^{R \times R^*}\) from the given points \(\pmb{X} \in \mathbb{R}^{m \times n}\).

In this function, the points in \(\pmb{X}\) are assumed to be expressed in the internal reference system of the receptive field. In other words, the points must have been translated to the origin and scaled so the considered interval for each axis is \([-1, 1]\) instead of the defined by the original units of the boundary radii.

First, the dimensional factors \(f_1, \ldots, f_n\) are computed such that \(f_1 = 1\) and \(f_{i>1} = f_{i-1} \left\lceil\dfrac{2}{s_{i-1}}\right\rceil\).

Then, the point-wise indices \(i_1, \ldots, i_m\) can be computed such that:

\[i_j = \sum_{k=1}^{n}{\min \biggl\{{ f_k \biggl( \biggl\lfloor{\dfrac{2}{s_k}}\biggr\rfloor - 1 \biggr), f_k \biggl\lfloor{{ \dfrac{x_{jk}+1}{s_k} }\biggr\rfloor} }\biggr\}}\]

The previous computation guarantees that extreme points, as the maximum vertex of the axis aligned bounding box containing the point cloud, are assigned to a proper cell. In other words, they are associated to an index inside the boundaries of the indexing space, i.e., no greater than the greatest supported index.

Now, since the \(i_1, \ldots, i_m\) indices are computed, it is known that the point \(j\) must be represented in the \(i_j\) row of matrix \(\pmb{N}\). Consequently, there must be one component of row \(\pmb{n}_{i_j}\), namely \(\pmb{n}_{i_jk}\), such that \(\pmb{n}_{i_jk} = j\). And thus, the matrix \(\pmb{N} \in \mathbb{Z}_{\geq -1}^{R \times R^*}\) is built.

Parameters:

X – The matrix representing the m input points to build the indexing matrix. The points must have been centered and scaled, so they are expressed in the internal reference system of the receptive field. See receptive_field_gs.ReceptiveFieldGS.center_and_scale() for more information.

Returns:

The built indexing matrix.

Return type:

np.ndarray

center_and_scale(X)

Let \(\pmb{o}\) be the origin of the receptive field (also referred to as center point), and \(\pmb{r}\) be the bounding radii vector.

Any row in \(\pmb{X}\) is assumed to represent a point in the canonical reference system. Thus, it is possible to obtain a matrix \(\pmb{Y}\) which rows are the points in \(\pmb{X}\) transformed to the internal reference system of the receptive field. Each point in this matrix can be computed as:

\[\pmb{y}_{i*} = \left[\begin{array}{ccc} \dfrac{x_{i1} - o_1}{r_1} & \cdots & \dfrac{x_{in} - o_n}{r_n} \end{array}\right]\]

Parameters:

X (np.ndarray) – The matrix of points to be transformed.

Returns:

The matrix of transformed points.

Return type:

np.ndarray

undo_center_and_scale(X)

The inverse transform of the receptive_field_gs.ReceptiveFieldGS.center_and_scale() method.

\[\pmb{x}_{i*} = \left[\begin{array}{ccc} r_1 x_{i1} + o_1 & \cdots & r_n x_{in} + o_n \end{array}\right]\]

Parameters:

X (np.ndarray) – The matrix of transformed points to be transformed back to their original representations.

Returns:

The matrix of points after reversing the transformation.

Return type:

np.ndarray

get_center_of_empty_cells(missing_indices=None)

Obtain the center point (computed as the midrange) for each empty cell.

Parameters:

missing_indices – The indices of empty cells. It can be None, in that case it will be computed internally.

Returns:

Matrix of geometric centers, one row per empty cell.

Return type:

np.ndarray

static num_cells_from_cell_size(cell_size)

Compute the number of cells for a receptive field defined by the given cell size.

Parameters:

cell_size – The cell size for which the number of cells must be computed. See ReceptiveFieldGS for further details.

Returns:

The number of cells composing the receptive field.

Return type:

int

canibalize(rf)

See ReceptiveField.canibalize().

utils.ptransf.receptive_field_hierarchical_fps module

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

Bases: ReceptiveField

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

utils.ptransf.receptive_field_hierarchical_fpspp module

class utils.ptransf.receptive_field_hierarchical_fpspp.ReceptiveFieldHierarchicalFPSPP(**kwargs)

Bases: ReceptiveFieldHierarchicalFPS

Author:

Alberto M. Esmoris Pena

C++ implementation of the ReceptiveFieldHierarchicalFPS.

__init__(**kwargs)

See ReceptiveFieldHierarchicalFPS and ReceptiveFieldHierarchicalFPS.__init__().

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

C++ version of ReceptiveFieldHierarchicalFPS.fit().

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

See ReceptiveFieldHierarchicalFPS and ReceptiveFieldHierarchicalFPS.propagate_values().

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

C++ version of ReceptiveFieldHierarchicalFPS.reduce_values().

reduce_values_python(X, v, reduce_f=<function mean>)

Method that calls ReceptiveFieldFPS.reduce_values() to provide a Python alternative to reductions.

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

utils.ptransf.receptive_field_hierarchical_sg module

class utils.ptransf.receptive_field_hierarchical_sg.ReceptiveFieldHierarchicalSG(**kwargs)

Bases: ReceptiveField

Author:

Alberto M. Esmoris Pena

Class representing a hierarchical receptive field based on sparse grids.

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 and HierarchicalSGPreProcessorPP.

Variables:

• size (float) – The size of the cell. Note that 3D cells are voxels with the same length for each edge.

• w (np.ndarray of int) – The size of the submanifold convolutional window. It is given as a half size in terms of number of cells. For example, \(w_t\) means that the submanifold convolutional window at depth \(t\) will consider the active cell in the center, \(w_t\) cells backward, and \(w_t\) cells forward. If the dimensionality of the space is \(n_x\), the number of cells in a submanifold convolutional window will be given by \((2w_t + 1)^{n_x}\). Note that any submanifold convolution has a stride or step size of one.

• wD (np.ndarray of int) – The size of the downsampling convolutional window. It is given as a size in terms of number of cells. For example, \(w^D_t\) means that the downsampling convolutional window at depth \(t\) will consist of \((w^D_t)^{n_x}\) cells for a \(n_x\)-dimensional space.

• sD (np.ndarray of int) – The step size or stride for the downsampling convolutional window. The downsampling window will move \(s^D_t\) cells along the \(t\) sparse grid to generate the cells of the \(t+1\)-th sparse grid in the hierarchy.

• wU (np.ndarray of int) – The size of the upsampling convolutional window. It is given as a size in terms of number of cells. For example, math:w^U_t means that the upsampling convolutional window at depth \(t\) will consist of \((w^U_t)^{n_x}\) for a \(n_x\)-dimensional space.

• sU (np.ndarray of int) – The step size or stride for the upsampling convolutional window. The upsampling window will move \(s^U_t\) cells along the \(t+1\) sparse grid to generate the cells of the \(t\)-th sparse grid in the hierarchy.

• h (list of tuple of np.ndarray) – A list of 2-tuples, each tuple represents the \(h_t\) map at depth \(t\) by storing the vector of keys (first element of the tuple) and the vector of values (second element of the tuple). The \(h_t(i)\) value can be understood as the sequential index representing the active cell that corresponds to the cell index \(i\) in the sparse grid at depth \(t\).

• hD ((list or np.ndarray) of int) – The downsampling indexing. The \(h^D_{ti}\) value can be understood as the index of the min vertex (e.g., the lower-left-backward for a 3D grid) for the convolutional window in the sparse grid at depth \(t\) that generates the value for the \(i\)-th active cell in the sparse grid at depth \(t+1\).

• hU ((list or np.ndarray) of int) – The upsampling indexing. The \(h^U_{ti}\) value can be understood as the index of the min vertex (e.g., the lower-left-backward for a 3D grid) for the convolutional window in the sparse grid at depth \(t+1\) that generates the value for the \(i\)-th active cell in the sparse grid at depth \(t\).

• n (np.ndarray of int) – The axis-wise number of partitions for each sparse grid of the hierarchy.

• A (np.ndarray) – The min point of the sparse grid at the first level of the hierarchy.

__init__(**kwargs)

Initialize/instantiate a hierarchical SG receptive field object.

Parameters:

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

Keyword Arguments:

• size (float) – The size of the cell (note that 3D cells are voxels with the same length for each edge.)

• w (list of int) – The size of the submanifold convolutional window. Note that this size is interpreted differently from the others. It applies twice, one for each direction along each axis.

• wD (list of int) – The size of the downsampling convolutional window.

• sD (list of int) – The step size or stride for the downsampling convolutions.

• wU (list of int) – The size of the upsampling convolutional window.

• sU (list of int) – The step size or stride for the upsampling convolutions.

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

Fit the receptive field to represent the given points by constructing a hierarchy of sparse grids such that the first one has as active cells those in which there is at least one point from the input structure space.

Parameters:

• X – The input structure space matrix of \(m\) points in a \(n_x\)-dimensional space (for now, typically \(n_x=3\)).

• x – The center point used to define the origin of the receptive field. Note that this parameter is ignored by the hierarchical sparse grid because it does not explicitly generate structure spaces nor centers the sparse grids in the hierarchy.

• x – Not used by

• structure_float_type – The decimal type for the structure space. Note that this parameter is ignored by the hierarchical sparse grid because it does not explicitly generate structure spaces.

• id – See ReceptiveField.fit().

Returns:

The fitted receptive field itself (for fluent programming).

Return type:

ReceptiveFieldHierarchicalSG

get_submanifold_maps()

Obtain the submanifold maps from the cell index (key, domain) to its corresponding sequential active cell index (value, codomain).

Returns:

The submanifold maps.

Return type:

list of tf.lookup.StaticHashTable

get_downsampling_vectors()

Obtain the downsampling vector for each depth connecting the min vertex of the convolutional window with its corresponding cell in the downsampled sparse grid.

Returns:

The downsampling vectors.

Return type:

list of np.ndarray of int

get_upsampling_vectors()

Obtain the upsampling vector for each depth connecting the min vertex of the convolutional window with its corresponding cell in the upsampled sparse grid.

Returns:

The upsampling vectors.

Return type:

list of np.ndarray of int

get_num_partitions()

Obtain the number of axis-wise partitions for each sparse grid in the hierarchy.

Returns:

The number of axis-wise partitions for each sparse grid in the hierarchy.

Return type:

np.ndarray of int

get_min_point()

Obtain the min point/vertex of the first sparse grid in the hierarchy.

Returns:

The min vertex of the first sparse grid.

Return type:

np.ndarray

get_max_depth()

Obtain the max depth of the hierarchy.

Returns:

The max depth of the hierarchy.

Return type:

int

get_submanifold_windows()

Obtain the submanifold convolutional window.

Returns:

The submanifold convolutional window.

Return type:

int

get_downsampling_windows()

Obtain the downsampling convolutional window.

Returns:

The downsampling convolutional window.

Return type:

int

get_upsampling_windows()

Obtain the upsampling convolutional window.

Returns:

The upsampling convolutional window.

Return type:

int

compute_active_centroids(t)

Compute the centroid for each active cell of the sparse grid at depth \(t \in \mathbb{Z}_{\geq 0}\) the hierarchy.

This method assumes a 3D structure space so each centroid can be computed from the index of the active cell \(k\) such that:

\[\begin{split}\left\{\begin{array}{ll} x(k) =& \left[(k \mod n_z) + \dfrac{1}{2}\right] s + A_x \\ y(k) =& \left[ \left(\left\lfloor\dfrac{k}{n_z}\right\rfloor \mod n_y\right) + \dfrac{1}{2} \right] s + A_y \\ z(k) =& \left[ \left\lfloor\dfrac{k}{n_y n_z}\right\rfloor + \dfrac{1}{2} \right] s + A_z \end{array}\right.\end{split}\]

Where \(n_x, n_y, n_z\) represent the number of partitions along the \(x, y, z\) axis for the sparse grid at depth \(t\) and \(A = (A_x, A_y, A_z)\) represent the min vertex of the first sparse grid in the hierarchy.

NOTE that the centroids of sparse grids after the first depth will not respect the original scale.

Returns:

Each cell represented as a centroid.

Return type:

np.ndarray

get_submanifold_map_as_dict(t, without_ground=False)

Obtain the submanifold map \(h_t\) at depth \(t\) as a python dictionary.

Parameters:

• t (int) – The depth of the submanifold map that must be obtained.

• without_ground (bool) – Whether the values (sequential indices of active cells) must be corrected to avoid accounting for the ground value (True) or not (False). The ground value is a convenience so the HSG receptive field can be used inside a neural network. It assumes the feature space matrix is expanded with a new row at the beginning that contains the ground value (0). However, the original submanifold map is not aware of this. If without_ground is True then this method will revert the returned submanifold map (as dictionary) so it does not consider the ground value.

Returns:

The submanifold map at depth \(t\) as a dictionary.

Return type:

dict

utils.ptransf.sampling_decorator_utils module

class utils.ptransf.sampling_decorator_utils.SamplingDecoratorUtils

Bases: object

Author:

Alberto M. Esmoris Pena

Class with util static method to work with point sampling decorators.

static validate_decorator_spec(obj, decorated_spec, decorator_spec)

Validate the given decorator specification (including its associated decorated object specification) is correct for the general case.

Parameters:

• obj – The decorator object.

• decorated_spec – The specification governing the decorated object.

• decorator_spec – The decorator’s specification.

Returns:

Nothing, but a VL3DException will be raised if something not valid is found.

static warn_if_problematic_encoding(obj, decorator_spec)

Log a warning if a not recommended encoding configuration is found.

Parameters:

• obj – The decorator object.

• decorator_spec – The decorator’s specification.

Returns:

Nothing, but a warning will be emitted through the logging system if something problematic is detected.

utils.ptransf.simple_data_augmentor module

class utils.ptransf.simple_data_augmentor.SimpleDataAugmentor(**kwargs)

Bases: DataAugmentor

Author:

Alberto M. Esmoris Pena

Class representing a simple data augmentation object. It supports random rotations, scaling, and jitter. Each data augmentation transformation can be defined with a random distribution that can be either normal or uniform.

Variables:

transformations (list of dict) – List of transformations to be applied to augment the input data.

__init__(**kwargs)

Initialize the simple data augmentor.

Parameters:

kwargs – The key-word specification for the initialization of the simple data augmentor.

augment(X, **kwargs)

See DataAugmentor and DataAugmentor.augment().

Parameters:

X (list or np.ndarray) – It can be a single batch, e.g., a tensor \(K x m x n\) that represents \(K\) point clouds of \(m\) points in a \(n\)-dimensional space. Alternatively, it can be a list of batch elements, such that all the elements in the list must be consistently augmented. For example, assume [X1, X2, X3] is given where \(\mathcal{X}_i \in \mathbb{R}^{K_i \times m_i \times n}\) for \(i=1,\ldots,3\). Then the matrices \(\pmb{X}_{1j}\), \(\pmb{X}_{2j}\), and \(\pmb{X}_{3j}\) must be augmented in the same way, i.e., using the same samples from random distributions, for rotations and scaling. However, jitter will be applied independently to any element.

static apply_transformation(transformation, X)

Apply the given transformation to the structure space matrices.

NOTE that the transformation is applied in place, despite the transformed space is also returned.

Parameters:

• transformation (dict) – The specification of the transformation to be applied.

• X (list or np.ndarray) – The structure spaces to be transformed.

Returns:

The transformed structure spaces.

Return type:

list or np.ndarray

static apply_rotation(transformation, X)

Apply a rotation transformation.

Parameters:

• transformation (dict) – The rotation specification.

• X (list or np.ndarray) – The structure spaces to be transformed.

Returns:

The rotated structure spaces.

Return type:

list or np.ndarray

static apply_scale(transformation, X)

Apply a scaling transformation.

Parameters:

• transformation – The scaling specification.

• X (list or np.ndarray) – The structure spaces to be transformed.

Returns:

The scaled structure spaces.

Return type:

list or np.ndarray

static apply_jitter(transformation, X)

Apply a jitter transformation.

Parameters:

• transformation – The jitter specification.

• X (list or np.ndarray) – The structure spaces to be transformed.

Returns:

The structure spaces with jitter.

Return type:

list or np.ndarray

static compute_distribution(distribution, dim=1)

Compute the distribution corresponding to the given specification.

Parameters:

• distribution (dict) – The specification of the distribution to be computed.

• dim – The sampling dimensionality, i.e., how many samples will be taken from the distribution.

Returns:

A tensor of samples representing the computed distribution.

Return type:

np.ndarray

static set_rotation_matrix(R, axis, angle)

Update the rotation matrix in place, so it represents a rotation

around the given axis with the given angle.

Parameters:

• R (np.ndarray) – The rotation matrix to be updated.

• axis (list or tuple or np.ndarray) – The rotation axis.

• angle – The angle of the rotation.

Typa angle:

float

Returns:

The updated rotation matrix (it is also updated in place).

Return type:

np.ndarray

utils.ptransf.simple_smoother_decorator_transformer module

class utils.ptransf.simple_smoother_decorator_transformer.SimpleSmootherDecoratorTransformer(**kwargs)

Bases: object

Author:

Alberto M. Esmoris Pena

Class representing a simple structure smoother transformer that can be used to decorate different components of the framework.

A simple smooth representation of a point cloud \(\pmb{P} = [\pmb{X} | \pmb{F}] \in \mathbb{R}^{m \times (n_x+n_f)}\) is another point cloud \(\pmb{\tilde{P}} = [\pmb{\tilde{X}} | \pmb{F}] \in \mathbb{R}^{m \times (n_x+n_f)}\). The smooth representation has the same number of points but the structure space \(\pmb{X}\) is transformed considering the neighborhood of each point to update its position. The transformation is the same that can be computed with SimpleStructureSmootherPP but the results on the decorated point cloud (e.g., mined features) are then assigned to the original point cloud, i.e., the point cloud is not updated, the smooth representation is only used during a certain computation.

Variables:

• smoother – The SimpleStructureSmootherPP object used to .

• representation_report_path (str) – Path where a point cloud with the smoothed representation will be exported.

__init__(**kwargs)

Initialize/instantiate a simple smoother decorator transformer object.

Parameters:

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

Keyword Arguments:

• neighborhood (dict) – See SimpleStructureSmootherPP.__init__().

• representation_report_path (str) –

  Path where a point cloud with the points in the smoothed representation will be exported.

transform(X, F=None, y=None, fnames=None, header=None, out_prefix=None)

Transform the given point cloud to its smoothed representation.

Parameters:

• X – The original structure space matrix (i.e., the matrix of point-wise coordinates).

• F – The feature space matrix (i.e., the matrix of features).

• y – The reference classes (i.e., the classification).

• fnames – The names of the features in F, it allows to have named features in the point cloud written to the representation report path.

• header – The header of the LAS/LAZ file representing the point cloud (OPTIONAL).

• out_prefix – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

The smoothed structure space matrix.

Return type:

np.ndarray

transform_pcloud(pcloud, fnames=None, ignore_y=False, out_prefix=None)

Transform the given point cloud to its smoothed representation.

Parameters:

• pcloud (PointCloud) – The point cloud to be transformed.

• fnames (None or list of str) – A list with the names of the features to be considered. If an empty list is given, no features will be considered. If None is given, all features will be considered.

• ignore_y (bool) – Whether to ignore the classes (True) or to include them in the representation (False).

• out_prefix (None or str) – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

A new point cloud that is an FPS representation of the input one.

Return type:

PointCloud

utils.ptransf.simple_structure_smootherpp module

class utils.ptransf.simple_structure_smootherpp.SimpleStructureSmootherPP(**kwargs)

Bases: PointTransformer

Author:

Alberto M. Esmoris Pena

Class for smoothing the structure space of a point cloud. The smoothing consists in replacing each point \(\pmb{x}_{i*} \in \mathbb{R}^{3}\) in the point cloud by a smoothed version considering its neighborhood \(\mathcal{N}(\pmb{x}_{i*}) \subset \mathbb{R}^{3}\). Supported neighborhood definitions are 2D and 3D k-nearest neighbors, spheres, and unbounded cylinders of a given radius. The smoothed version of the point is:

– Mean strategy

\[\pmb{x}^{'}_{i*} = \lvert\mathcal{N}(\pmb{x}_{i*})\rvert^{-1} \sum_{\pmb{x}_{j*} \in \mathcal{N}(\pmb{x}_{i*})}{\pmb{x}_{j*}}\]

– Inverse Distance Weighting (IDW) strategy

\[\pmb{x}^{'}_{i*} = \left[ \sum_{\pmb{x}_{j* \in \mathcal{N}(\pmb{x}_{i*})}}{ \left(\max\left\{ \epsilon, \lVert\pmb{x}_{j*} - \pmb{x}_{i*}\rVert \right\}\right)^{-p} } \right]^{-1} \left[ \sum_{\pmb{x}_{j* \in \mathcal{N}(\pmb{x}_{i*})}}{ \left(\max\left\{ \epsilon, \lVert\pmb{x}_{j*} - \pmb{x}_{i*}\rVert \right\}\right)^{-p} \pmb{x}_{j*} } \right]\]

– Radial Basis Function (RBF) strategy (with Gaussian Kernel)

\[\pmb{x}^{'}_{i*} = \left( \sum_{\pmb{x}_{j*} \in \mathcal{N}(\pmb{x}_{i*})}{ \exp\left(-\dfrac{ \lVert\pmb{x}_{j*}-\pmb{x}_{i*}\rVert^{2} }{ p^2 }\right) } \right)^{-1} \left( \sum_{\pmb{x}_{j*} \in \mathcal{N}(\pmb{x}_{i*})}{ \exp\left(-\dfrac{ \lVert\pmb{x}_{j*}-\pmb{x}_{i*}\rVert^{2} }{ p^2 }\right) \pmb{x}_{j*} } \right)\]

Variables:

• neighborhood (dict) – A dictionary specifying the neighborhood definition for the smoothing algorithm. See SimpleStructureSmootherPP.__init__() for specification details.

• strategy (dict) – A dictionary specifying the smoothing strategy. See SimpleStructureSmootherPP.__init__() for specification details.

• nthreads (int) – The number of threads to be used for parallel computations. Note that -1 means using as many threads as available cores.

static extract_ptransf_args(spec)

Extract the arguments to initialize/instantiate a SimpleStructureSmootherPP.

Parameters:

spec – The key-word specification containing the arguments.

Returns:

The arguments to initialize/instantiate a SimpleStructureSmootherPP.

Return type:

dict

__init__(**kwargs)

Initialize/instantiate a simple structure smoother++ object.

Parameters:

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

Keyword Arguments:

• neighborhood (dict) – Dictionary with the neighborhood specification.

  – type

  The type of neighborhood. Either "knn", "knn2d", "sphere", or "cylinder".

  – radius

  The radius for the "sphere" and "cylinder" neighborhoods.

  – k

  The number of neighbors in k-nearest neighbors neighborhoods.

• strategy (dict) – Dictionary with the smoothing strategy specification.

  – type

  The strategy for the smoothing. Either "mean", "idw", or "rbf".

  – parameter

  The power parameter \(p \in \mathbb{Z}_{\geq 1}\) for the "idw" strategy or the bandwith parameter \(p \in \mathbb{R}\) for the "rbf" strategy.

  – min_distance

  The min allowed distance \(\epsilon \in \mathbb{R}_{>0}\) to avoid division by zero when using the "idw" strategy.

• correction (dict) – Dictionary with the Fibonacci orthodromic correction specification. See the C++ documentation for further details about the maths.

  – K

  How many points consider for the Fibonacci support.

  – sigma

  The hard cut threshold for the weighting function:

  \[\omega(\pmb{x}_{j*}, \pmb{q}_{k*}) = \max \;\left\{ 0, \sigma - \arccos\left(\dfrac{ \langle\pmb{x}_{j*}, \pmb{q}_{k*}\rangle }{ \lVert\pmb{x}_{j*}\rVert } \right) \right\}\]

• nthreads (int) –

  The number of threads to be used in parallel computations. Note that -1 means as many threads as available cores.

transform(X=None, F=None, y=None, yhat=None, out_prefix=None, **kwargs)

The fundamental point transform logic defining the simple structure smoother++.

See PointTransformer and PointTransformer.transform().

transform_pcloud(pcloud, out_prefix=None, **kwargs)

Update the input point cloud in place.

See SimpleStructureSmootherPP.transform() and PointTransformer.transform_pcloud().

Module contents

author:

Alberto M. Esmoris Pena

The point transformation package contains the logic for advanced point transformation operations. They are not simply feature transformation. For example, a grid-based receptive field where the cells of the grid represent the discrete units of receptive field that can be used to reduce the point cloud to a representation but also to propagate values from the representation to the point cloud is an example of a point transformation model.