src.utils.ctransf.taut_string_reclassifier

Classes

TautStringReclassifier(**kwargs)

class src.utils.ctransf.taut_string_reclassifier.TautStringReclassifier(**kwargs)
Author:

Alberto M. Esmoris Pena

The TautStringReclassifier class detects local underhangs on semantically segmented 3D point clouds and quantifies the per-point depth via a sliding-window taut-string envelope over vertical slices of each wall cluster. The component supports two operating modes:

– Mode A (ground-based ambiguity breaker): when

ground_classes is given, the algorithm orients the wall plane’s horizontal direction \(\pmb{h}\) outward using a hierarchical sign-disambiguation rule (majority side, then lower-ground-median, then lower-ground-base, then a per-cluster inconclusive fallback). Only the upper convex hull of every slice is used, so only inward concavities (underhangs) are reclassified.

– Mode B (non-ambiguity-resolution): when ground_classes

is absent, the algorithm computes both the upper and lower convex hull of every slice and labels any point whose larger gap to either envelope exceeds the \(D\) depth_threshold as underhang.

The Python class is a thin orchestration layer over the C++ backend exposed as pyvl3dpp.alg_taut_string_reclassify_fs32 (float32) / alg_taut_string_reclassify_ds32 (float64). It handles eager validation, auto-default expansion, class-name resolution, the empty-cloud no-op contract, dispatch of the binding by coordinate dtype, end-of-transform INFO emission, and the per-cluster TautStringReclassificationReport build.

See ClassTransformer.

Variables:

  • output_class_names (list of str) – Names of the output classes.

  • source_classes (list of str) – Names of the input classes considered as wall by the algorithm.

  • underhang_class (str) – The output class name assigned to points that the algorithm labels as underhang.

  • ground_classes (list of str or None) – Names of the ground-class anchors used by the mode-A sign-disambiguation hierarchy. None or empty list activates mode B.

  • ground_classes_idx (np.ndarray of int32) – Integer indices of ground_classes resolved via input_class_names. Empty array in mode B.

  • depth_threshold (float) – Depth \(D > 0\) above which a deviation is considered an underhang.

  • gravity_direction (np.ndarray of float) – Unit-norm vector pointing along the upward vertical axis.

  • bin_size (float) – Vertical-slice bin width \(\Delta > 0\).

  • sliding_window_size (float) – Vertical sliding-window size \(w > 0\).

  • sliding_window_stride (float) – Vertical sliding-window stride \(s\) with \(0 < s \leq w\).

  • plane_fit_trim (bool) – Whether to apply the one-shot trim refit on the cluster’s PCA plane fit.

  • plane_fit_trim_eps (float) – Trim tolerance \(\epsilon \geq 0\). 0 / None resolves to depth_threshold / 2.

  • initial_region_radius (float) – Region-growing seed radius \(r_0 > 0\).

  • region_growing_step (float) – Region-growing step radius \(r_{\Delta} > 0\).

  • region_growing_plane_tolerance (float) – Plane-tolerance gate \(\tau \geq 0\). 0 / None disables the gate.

  • ground_search_radius (float) – Ground-anchor search radius \(R_g \geq 0\). 0 / None resolves to \(3 r_0\).

  • ground_min_count (int) – Minimum ground-anchor count \(N_g^{\min} > 0\).

  • ground_majority_ratio (float) – Majority-side fraction threshold \(\rho_g^{\min} \in (0.5, 1]\).

  • ground_distance_deadband (float) – Signed-distance dead-band \(\delta_g \geq 0\). 0 / None resolves to bin_size.

  • ground_elevation_deadband (float) – Vertical dead-band \(\tau_z \geq 0\). 0 / None resolves to initial_region_radius.

  • include_cluster_eigenmin (bool) – When True, the last-accepted cluster eigenmin is appended to the output cloud.

  • cluster_eigenmin_name (str) – Attribute name for the cluster eigenmin output column.

  • include_wall_clusters (bool) – When True, the per-point cluster index is appended to the output cloud.

  • wall_cluster_name (str) – Attribute name for the cluster-index output column.

  • include_depth_distance (bool) – When True, the per-point depth distance is appended to the output cloud.

  • depth_distance_name (str) – Attribute name for the depth-distance output column.

  • nthreads (int) – Number of OpenMP threads. -1 means all available cores.

  • prediction_type (np.dtype) – Numpy integer dtype configured via VL3DCFG['IO']['PointCloud']['prediction_type'] and used to coerce the prediction vector when on_predictions=True.

static extract_ctransf_args(spec)

Extract the arguments to initialize/instantiate a TautStringReclassifier from a JSON-style key-word specification. Inherits the shared ClassTransformer arguments (on_predictions, input_class_names, num_classes, report_path, plot_path) and adds the algorithm-specific keys documented in the seed.

Parameters:

spec – The key-word specification containing the arguments.

Returns:

The arguments to initialize/instantiate a TautStringReclassifier.

Return type:

dict

__init__(**kwargs)

Initialize/instantiate a TautStringReclassifier. Every hyperparameter is eagerly validated before the C++ backend is loaded so that misconfigured pipelines fail fast.

Parameters:

kwargs – The attributes for the TautStringReclassifier (see class docstring for the full list).

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

The fundamental transformation logic of the TautStringReclassifier. Builds the wall mask from source_classes, dispatches the C++ binding by the coordinate matrix dtype, applies the class rewrite, and builds the per-cluster TautStringReclassificationReport.

Parameters:

  • y (np.ndarray) – The vector of point-wise classes (classifications or predictions; depending on on_predictions). This is the channel the algorithm rewrites and that the caller writes back to the cloud.

  • X (np.ndarray) – The structure space matrix representing the input point cloud whose classes must be transformed.

  • F (np.ndarray) – Optional feature space matrix (kept for the ClassTransformer signature; unused by this transformer).

  • fnames (list of str) – Optional feature names (kept for the ClassTransformer signature; unused by this transformer).

  • out_prefix (str) – See class_transformer.ClassTransformer.transform().

Returns:

The transformed vector of classes.

Return type:

np.ndarray

transform_pcloud(pcloud, out_prefix=None)

Apply transform() to a point cloud and append the optional output columns gated by the include_* flags. Implements the empty-cloud no-op contract (no columns appended when no wall points are present).

Parameters:

  • pcloud (PointCloud) – The point cloud whose classes/predictions must be transformed.

  • out_prefix (str) – Output prefix forwarded to the reports.

Returns:

The point cloud with updated classes/predictions and (when applicable) the optional output columns.

Return type:

PointCloud