src.model.deeplearn.dlrun.receptive_field_pre_processor

Classes

ReceptiveFieldPreProcessor(**kwargs)

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

Author:: Alberto M. Esmoris Pena

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

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