Skip to content

Workflow Overview

Jump to bottom
Adrián José Riquelme Guill edited this page Sep 15, 2026 · 4 revisions

Methodological Workflow Overview

DSEpy provides a complete semi-automatic workflow for rock mass discontinuity analysis on 3D point clouds [1, 2]. Built directly inside CloudCompare (CC), it seamlessly bridges raw point cloud editing and advanced geomechanical characterisation.

💡 Key Advantages of Native CloudCompare Integration

  • Direct Point Cloud Preprocessing: Users can leverage CloudCompare's full suite of editing tools prior to analysis—removing vegetation, cleaning structural noise, or segmenting specific rock faces.
  • Flexible Normal Vector Sources: DSEpy works directly with any pre-existing normal vectors assigned to the point cloud. Normals can be obtained via:
    1. Standard CloudCompare computation (Edit $\rightarrow$ Normals $\rightarrow$ Compute).
    2. The Hough Normals plugin (Plugins $\rightarrow$ Hough Normals).
    3. External software import (e.g., pre-calculated normals saved in .ply, .e57, or .pts files).

🔄 Complete Pipeline Diagram

 ┌────────────────────────────────────────────────────────┐
 │        CloudCompare Preprocessing (Edit/Filter)        │
 │ • Noise/Vegetation removal & spatial segmentation     │
 │ • Compute normals (CC / Hough Normals / Imported)      │
 └───────────────────────────┬────────────────────────────┘
                             │
                             ▼
 ┌────────────────────────────────────────────────────────┐
 │ Stage 1: Colour Optimisation                           │
 │ • Map normals (Nx, Ny, Nz) to 3D color spaces          │
 │ • Visual orientation mapping (HSV, CIELAB, OKLCH...)   │
 └───────────────────────────┬────────────────────────────┘
                             │
                             ▼
 ┌────────────────────────────────────────────────────────┐
 │ Stage 2: Stereonet Analysis & Pole Identification      │
 │ • Spherical kernel density estimation (KDE)            │
 │ • Locate principal discontinuity set (DS) poles        │
 └───────────────────────────┬────────────────────────────┘
                             │
                             ▼
 ┌────────────────────────────────────────────────────────┐
 │ Stage 3: Point Cloud Set Classification                │
 │ • Angular proximity thresholding (theta)               │
 │ • Scalar field assignment per DS in CloudCompare       │
 └───────────────────────────┬────────────────────────────┘
                             │
                             ▼
 ┌────────────────────────────────────────────────────────┐
 │ Stage 4: Spatial Clustering & Geomechanical Metrics    │
 │ • DBSCAN spatial segmentation per family               │
 │ • Planar equation fitting (Fixed / Free orientation)   │
 │ • Spacing, Persistence, and 3D Facet Mesh extraction   │
 └────────────────────────────────────────────────────────┘

🖥️ Interactive GUI Workflow & CloudCompare Integration

1. Point Cloud Connection & Active Entity

  • DBTree Selection: Upon launching DSEpy, the module automatically targets the active point cloud entity selected in CloudCompare's Database Tree (DBTree).
  • Validation & Refresh: If no point cloud is highlighted in CC, DSEpy notifies the user that no active entity is detected. To resolve this:
    1. Clean or segment your point cloud in CC if necessary.
    2. Ensure normal vectors $(N_x, N_y, N_z)$ are present (via CC Edit > Normals, Hough Normals, or file import).
    3. Highlight the target point cloud in CC's DBTree.
    4. Click the Update / Refresh button in DSEpy to establish the connection.

2. Stage 1: Principal Poles Analysis (1. Principal Poles Tab)

Once connected, switch to the 1. Principal poles tab to begin processing:

  • Cylindrical Colour Map Visualisation: Inspect structural orientation domains directly on the 3D model. If an optimized rotation matrix was previously calculated (via Tools $\rightarrow$ Normal Colour Optimisation), select it from the rotation dropdown menu; otherwise, DSEpy operates in the original geographic coordinate space.
  • Stereonet Projection & Density Estimation:
    • Project normal vectors onto a lower-hemisphere stereonet using Equal-angle (Wulff) or Equal-area (Schmidt) projections.
    • Compute spherical Kernel Density Estimation (KDE) to generate density contours for poles and principal pole peaks [1].
  • Principal Poles Summary & Manual Editing:
    • Clicking the Automatic calculation button extracts density peaks and populates the Principal Poles Summary panel on the right [1, 2].
    • Geologists can manually edit, reorder, add, or delete principal poles to reflect field observations.
  • Pairwise Angles: The Pairwise Angles table displays inter-set angular distances (in degrees) between all identified principal poles.
  • Progressive Interface Unlocking: Downstream workflow tabs (Clustering, Geomechanical metrics) remain disabled until point cloud classification and set assignments are computed.

3. Stage 2: Point Classification & Scalar Field Assignment

Assigning principal poles to individual points classifies the point cloud into Discontinuity Sets (DS) based on angular proximity ($\theta_{\text{threshold}}$) [1]:

  • Scalar Field Generation: DSEpy generates a new Scalar Field (SF) on the active point cloud in CloudCompare containing the set index for each point.
  • Unclassified Points (Value 0): Points exceeding the maximum angular threshold are designated as unclassified noise and assigned a scalar value of 0.
  • Filtering Unclassified Points in CloudCompare: To isolate classified families, use CC's Filter by Value tool (Edit $\rightarrow$ Scalar Fields $\rightarrow$ Filter by Value):
    • Minimum: Set to 1 (excludes unassigned 0 points).
    • Maximum: Keep at the maximum family index.
  • Iterative Classification Validation: Inspect the provisional classification in CC's 3D window. If the set boundary assignments require refinement, return to DSEpy, adjust the principal pole orientations or thresholds, and re-run the point assignment. DSEpy will automatically overwrite the existing scalar field in CC.

4. Stage 3: Spatial Cluster Analysis & Plane Extraction

Once the provisional classification is accepted, DSEpy unlocks the Cluster Analysis tab:

  • DBSCAN Clustering: Point cloud sets are spatially segmented into individual joint faces using density-based spatial clustering (DBSCAN) [1, 2].
  • Plane Fitting Options: For each detected cluster, 3D plane equations are calculated under two modal conditions:
    • Fixed Orientation: Constrains individual plane normals to the mean set pole direction.
    • Free Orientation: Performs an unconstrained local planar fit per cluster.
  • Sensitivity Warning: Cluster extraction depends heavily on DBSCAN parameters—specifically the search radius ($\epsilon$) and minimum points ($N_{\text{min}}$). Ensure parameters match the spatial resolution and point density of your dataset.

📊 Input Data Requirements

Parameter Requirement / Value Notes
Entity Format CloudCompare Point Cloud (ccPointCloud) Standard point cloud object selected in DBTree
Normal Vectors $N_x, N_y, N_z$ present Generated via CC (Edit > Normals), Hough Normals, or imported externally
Coordinate System Metric scale (meters recommended) Essential for correct spacing and area values
Point Density Uniform density preferred Pre-filter vegetation and outliers in CloudCompare

🔗 Next Steps

References

  1. Riquelme, A. J., Abellán, A., Tomás, R., & Jaboyedoff, M. (2014). A new approach for semi-automatic rock mass joints recognition from 3D point clouds. Computers & Geosciences, 68, 38–52. https://doi.org/10.1016/j.cageo.2014.03.014
  2. Riquelme, A. (2015). Desarrollo de métodos para la caracterización del macizo rocoso mediante nubes de puntos 3D (Doctoral dissertation, Universidad de Alicante). RUA Repository: https://rua.ua.es/entities/publication/78d254b9-1a7b-49b1-a35a-c0edbdeeb225

🚀 Getting Started

📖 User Manual

🔗 Links

Clone this wiki locally