utils.ctransf package

Submodules

utils.ctransf.class_reducer module

class utils.ctransf.class_reducer.ClassReducer(**kwargs)

Bases: ClassTransformer

Author:: Alberto M. Esmoris Pena

Class to reduce a given set of input classes into another set of output classes such that each class of the output set corresponds at least 1 (but potentially more) classes of the input set.

More formally, this class represents a map from m input classes to n output classes where \(m \geq n\).

See ClassTransformer.

Variables:

output_class_names (list of str) – The list of names for the output (transformed) classes. For example [0] is the name of the first output class, i.e., that represented with index 0.
class_groups (list of list of str) – A list which elements are lists of input class names defining the corresponding output class. For example, [1][4] is the fifth input class corresponding to the second output class.

static extract_ctransf_args(spec)

Extract the arguments to initialize/instantiate a ClassReducer.

Parameters:: spec – The key-word specification containing the arguments.
Returns:: The arguments to initialize/instantiate a ClassReducer

__init__(**kwargs)

Initialize/instantiate a ClassReducer.

Parameters:: kwargs – The attributes for the ClassReducer

transform(y, out_prefix=None)

The fundamental transformation logic defining the class reducer.

See ClassTransformer and class_transformer.ClassTransformer.transform().

utils.ctransf.class_setter module

class utils.ctransf.class_setter.ClassSetter(**kwargs)

Bases: ClassTransformer

Author:: Alberto M. Esmoris Pena

Class to set the classification field of a point cloud from any other field.

See ClassTransformer.

Variables:: fname (str) – The name of the feature whose values must be assigned to the classification field. Note that classes must be represented as integer numbers, i.e., the attribute identified with fname must be convertible to integer without loss of precision.

static extract_ctransf_args(spec)

Extract the arguments to initialize/instantiate a ClassSetter.

Parameters:: spec – The key-word specification containing the arguments.
Returns:: The arguments to initialize/instantiate a ClassSetter.

__init__(**kwargs)

Initialize/instantiate a ClassSetter.

Parameters:: kwargs – The attributes for the ClassSetter.

transform(y, f=None, out_prefix=None)

The fundamental transformation logic defining the class transformer.

Parameters:

y (np.ndarray or None) – The point-wise labels.
f (np.ndarray) – The point-wise feature values that will be converted to an integer type so they can be assigned to the labels.
out_prefix (str or None) – It will not be used for nothing.

Returns:

The transformed input feature ready to be assigned to the classification field of a point cloud.

Return type:

np.ndarray

transform_pcloud(pcloud, out_prefix=None): See ClassTransformer.transform()

utils.ctransf.class_transformer module

exception utils.ctransf.class_transformer.ClassTransformerException(message='')

Bases: VL3DException

Author:: Alberto M. Esmoris Pena

Class for exceptions related to class transformation components. See VL3DException.

__init__(message='')

class utils.ctransf.class_transformer.ClassTransformer(**kwargs)

Bases: object

Author:: Alberto M. Esmoris Pena

Class (code) for class (classification) transformation operations.

Variables:

on_predictions (bool) – Flag controlling whether the transformation must be applied to classification or prediction.
num_classes (int) – The number of input classes
input_class_names (list of str) – The list of names corresponding to input classes. For example [0] is the name of the first class, i.e., that represented with index 0.
report_path (str) – The path to write the report file reporting the consequences of the class transformation.
plot_path (str) – The path to write the plot file reporting the consequences of the class transformation.
cti (dict) – The dictionary mapping the string-like names of the input classes (keys) to their corresponding integer index (values).

static extract_ctransf_args(spec)

Extract the arguments to initialize/instantiate a ClassTransformer from a key-word specification.

Parameters:: spec – The key-word specification containing the arguments.
Returns:: The arguments to initialize/instantiate a ClassTransformer.

__init__(**kwargs)

Initialize/instantiate a ClassTransformer.

Parameters:: kwargs – The attributes for the ClassTransformer.

abstractmethod transform(y, out_prefix=None)

The fundamental transformation logic defining the class transformer.

Parameters:

y (np.ndarray) – The vector of classes.
out_prefix (str) – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

The transformed vector of classes.

Return type:

np.ndarray

transform_pcloud(pcloud, out_prefix=None)

Apply the transform method to a point cloud.

See class_transformer.ClassTransformer.transform()

Parameters:

pcloud (PointCloud) – The point cloud to be transformed.
out_prefix (str) – The output prefix (OPTIONAL). It might be used by a report to particularize the output path.

Returns:

A new point cloud that is the transformed version of the input point cloud.

Return type:

PointCloud

report(report, out_prefix=None)

Handle the way a report is reported. First, it will be reported using the logging system. Then, it will be written to a file if the transformer has a not None report_path.

Parameters:

report – The report to be reported.
out_prefix – The output prefix in case the output path must be expanded.

Returns:

Nothing.

build_new_las_header(pcloud)

Build the LAS header for the output point cloud.

See PointCloud and class_transformer.ClassTransformer.transform_pcloud().

Parameters:: pcloud (PointCloud) – The input point cloud as reference to build the header for the new point cloud.
Returns:: The LAS header for the output point cloud.

utils.ctransf.distance_reclassifier module

class utils.ctransf.distance_reclassifier.DistanceReclassifier(**kwargs)

Bases: ClassTransformer

Author:: Alberto M. Esmoris Pena

Class to transform the classifications (or predictions) into another set of classes depending on distance and conditional filters.

See ClassTransformer.

Variables:

reclassifications (list of dict) –
List with the specifications of the many reclassification operations given in the order that they must be applied. Each reclassification is a dict with the following format:

– source_classes
List with the names of the input classes. There must be as many strings in the list as classes. The \(i\)-th string corresponds with the \(i\)-th input class.

– target_class
List with the names of the output classes. It consists of an arbitrary number of output classes such that the \(i\)-th string corresponds to the \(i\)-th output class.

– conditions
A list of dictionaries such that each dictionary defines a conditional filtering. It can be null (None).

– value_name
The name of the feature involved in the relational condition.

– condition_type
The relational governing the condition it can be either "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 RHS of the relational, with the LHS being the value from the point cloud.

– action
Whether to "preserve" or "discard" the points that satisfy the condition.

– distance_filters
A list of dictionaries such that each dictionary defines a distance-based filter. It can be null (None).

– metric
Either the "euclidean" \(\lVert\pmb{x}_{k*}-\pmb{x}_{i*}\rVert\) or the "manhattan" \(\sum_{j=1}^{n_x}{\lvert x_{kj} - x_{ij}\rvert}\) distance.

– components
A list with the components involved in the distance metric. For example, ["x", "y", "z"] will lead to 3D distances while ["z"] would lead to distances considering the \(z\) coordinate only.

– knn
The dictionary specifying how to compute the k-nearest neighbors neighborhood. For \(k=1\) the distance will be computed with respect to the closest neighbor. For \(k>1\) the distance will be computed with respect to the centroid of the neighborhood.

– coordinates
The coordinates to consider to compute the distance between neighbors. Most typical cases are ["x", "y", "z"] for 3D knn and ["x", "y"] for 2D knn.

– max_distance
The max supported distance. If given (i.e., not null/None) those neighbors further that this value will be excluded from the requested \(k\)-nearest neighbors neighborhood.

– k
The number of neighbors in the neighborhood.

– source_classes
The classes (in the input system of classes) of the points that must be considered in the neighborhood. If not given, then all points will be considered in the neighborhood for distance computations.

– filter_type
The relational governing the distance filter it can be either "not_equals" (\(\neq\)), "equals" (\(=\)), "less_than" (\(<\)), "less_than_or_equal_to" (\(\leq\)), "greater_than" (\(>\)), "greater_than_or_equal_to" (\(\geq\)), "in" (\(\in\)), "not_in" (\(\notin\)), or "inside" (\(x \in [a, b] \subset \mathbb{R}\)). Note that the "inside" type is a special type that implies 1) \(x \geq a\) and 2) \(x \leq b\).

– filter_target
The RHS of the distance relational, with the LHS being the computed distance.

– action
Whether to "preserve" or "discard" the points that satisfy the distance condition.
nthreads (int) – The number of threads to be used for parallel computations. Note that -1 means as many threads as available cores.

static extract_ctransf_args(spec)

Extract the arguments to initialize/instantiate a DistanceReclassifier.

Parameters:: spec – The key-word specification containing the arguments.
Returns:: The arguments to initialize/instantiate a DistanceReclassifier.

__init__(**kwargs)

Initialize/instantiate a DistanceReclassifier.

Parameters:: kwargs – The attributes for the DistanceReclassifier

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

The fundamental transformation logic defining the distance reclassifier.

Parameters:

y (np.ndarray) – The vector of classes (either reference classifications or predictions).
X (np.ndarray) – The structure space matrix representing the input point cloud whose classes must be transformed.
F (np.ndarray) – The feature space matrix representing the input point cloud whose classes must be transformed.
fnames (list of str) – The list with the name for each considered feature.
out_prefix – See class_transformer.ClassTransformer.transform()

Returns:

The transformed vector of classes.

Return type:

np.ndarray

transform_pcloud(pcloud, out_prefix=None): See class_transformer.ClassTransformer.transform()

apply_conditions(reclassification, mask, X, F, flut=None, yinlut=None, youtlut=None)

Update the point-wise mask of selected points applying the conditional filters in the reclassification specification.

Parameters:

reclassification (dict) – The reclassification specification.
mask (np.ndarray of bool) – The point-wise mask of selected points (True if selected, False otherwise).
X (np.ndarray) – The structure space matrix.
F (np.ndarray) – The feature space matrix.
flut (dict) – The feature look-up table. Keys are feature names, values are corresponding integer row-indices in F.
yinlut (dict) – The source (input) classes look-up table. Keys are class names, values are the corresponding indices.
youtlut (dict) – The target (output) classes look-up table. Keys are class names, values are the corresponding indices.

Returns:

The point-wise boolean mask (also updated in place).

Return type:

np.ndarray of bool

apply_distance_filters(reclassification, mask, X, F, y, flut=None, yinlut=None, youtlut=None)

Update the point-wise maks of selected points applying the distance-based filters in the reclassification specification.

The DistanceReclassifier.compute_centroids() assists this method with the parallel computation of the centroids.

Parameters:

reclassification (dict) – The reclassification specification.
mask (np.ndarray of bool) – The point-wise mask of selected points (True if selected, False otherwise).
X (np.ndarray) – The structure space matrix.
F (np.ndarray) – The feature space matrix.
y (np.ndarray) – The vector of point-wise source classes.
flut (dict) – The feature look-up table. Keys are feature names, values are corresponding integer row-indices in F.
yinlut (dict) – The source (input) classes look-up table. Keys are class names, values are the corresponding indices.
youtlut (dict) – The target (output) classes look-up table. Keys are class names, values are the corresponding indices.

Returns:

The point-wise boolean mask (also updated in place).

Return type:

np.ndarray of bool

static compute_centroids(knnX_chunk)

Method with the logic for the parallel computation of centroids during the application of distance filters.

See DistanceReclassifier.apply_distance_filters().

Parameters:: knnX_chunk – The chunk of neighborhoods (i.e., the structure space matrix for each neighborhood) whose centroid must be computed.
Returns:: The centroids for the neighborhoods in the given chunk.
Return type:: np.ndarray

determine_fnames()

Determine the names of the features involved in the distance reclassification.

Returns:: The names of the features necessary for the distance reclassification.
Return type:: list of str

Module contents

author:: Alberto M. Esmoris Pena

The class transformation package contains the logic to transform classes (in the context of classifications, not code).