Skip to content

Clustering & Facets

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

Spatial Clustering & Facet Extraction

The Spatial Clustering module in DSEpy partitions the classified point cloud families into individual 3D structural discontinuity planes (facets) [1, 2]. While Stage 2 groups points into orientation families based on normal vector proximity within a maximum angular cone ($\theta_{\text{threshold}}$), Stage 3 performs spatial segmentation to isolate individual physical joint surfaces exposed on the 3D rock mass.

Workflow Note: Once clustering is completed and inspected, you can either return to Stereonet & Poles if the principal pole identification or classification requires refinement, or proceed directly to calculate Normal Set Spacing and/or Discontinuity Persistence.

1. Theoretical Background

1.1 Conceptual Foundations: From Orientations to Quasi-Planar Clusters

Once a point cloud is classified into Discontinuity Sets (DS), all points assigned to a single family share approximately the same spatial orientation (restricted within the angular threshold $\theta_{\text{threshold}}$). When separating a family's points, spatial clustering algorithms search for dense local point groupings.

Because the maximum angular variation is constrained beforehand, any spatial cluster formed by points of the same family naturally constitutes a planar or quasi-planar surface (facet).

During this spatial analysis, two main geometric situations arise:

  1. Small Local Point Groupings: Minor clusters caused by surface roughness, vegetation remnants, or small blast spalls. These must be filtered out using minimum cluster size thresholds.
  2. Spatially Separated Clusters: Distinct clusters that may either represent separate, parallel joint surfaces or fragmented patches belonging to the exact same physical plane (split due to weathering, rock falls, or sensor occlusions). These require coplanarity testing to decide whether they should be merged or treated as distinct discontinuities.

1.2 Density-Based Spatial Clustering (DBSCAN)

To group coplanar points belonging to the same orientation family into distinct physical planes, DSEpy uses DBSCAN (Density-Based Spatial Clustering of Applications with Noise) [1].

DBSCAN is ideal for 3D geostructural analysis because:

  • It does not require pre-specifying the number of clusters.
  • It can discover clusters of arbitrary 3D shape and extent.
  • It effectively identifies and isolates spatial noise points (small non-representative clusters).

1.3 3D Plane Equation Fitting

Once points are grouped into a valid spatial cluster $c$, a 3D plane equation is fitted to represent the discontinuity surface geometry [1]:

$$Ax + By + Cz + D = 0$$

Where:

  • $\mathbf{n} = (A, B, C)$ is the unit normal vector of the fitted plane.
  • $D$ is the signed orthogonal distance from the origin $(0, 0, 0)$ to the plane:

$$D = -(A \cdot x_0 + B \cdot y_0 + C \cdot z_0)$$

Where $(x_0, y_0, z_0)$ is the centroid of the cluster point set.

2. Interactive GUI Workflow in DSEpy

Spatial clustering and plane fitting are executed within the 3. Spatial clustering and plane fitting tab.

DSEpy Stage 3 Interface DSEpy Stage 3 Interface: Spatial clustering parameters (left) and Cluster Planes Summary table (right).

2.1 DBSCAN Clustering Parameters

  • K-th Neighbor ($K$) [Recommended: 4]: Specifies the $k$-nearest neighbor used to construct the distance distribution graph for automated neighborhood scale estimation.
  • Sigma Multiplier ($k_{\text{sigma}}$) [Recommended: 2.0]: Multiplier applied to the standard deviation of local point distances to compute the search radius parameter ($\epsilon$) for DBSCAN. A value of 2.0 covers ~95% of local spatial dispersion.
  • DBSCAN MinPts [Recommended: 4]: Minimum number of neighboring points required within radius $\epsilon$ to form a core dense region.
  • Minimum Cluster Size (ppcluster) [Recommended: 100]: Minimum point threshold required for a cluster to be accepted as a valid structural plane. Small clusters below this threshold are automatically discarded as spatial noise.

2.2 Plane Calculation & Refinement Options

  • Coplanarity Merge ($k_{\text{sigmas}}$) [Recommended: 0.0 initially, then 1.0 – 2.0]:

    • Concept: Evaluates spatially separated clusters within the same family to determine if they lie on the exact same geometric 3D plane. If two adjacent patches share a common spatial plane within a normal tolerance scaled by $k_{\text{sigmas}}$, they are merged into a single continuous joint plane [1, 2].
    • Recommended Interactive Workflow:
      1. Start with $k_{\text{sigmas}} = 0.0$: Disables coplanarity merging to inspect the raw, unmerged spatial clusters first.
      2. Test $k_{\text{sigmas}} = 1.0$ to $2.0$: Incrementally apply merging to join fragmented patches belonging to the same physical joint face.
      3. Visual Inspection: Always inspect the resulting Cluster id scalar field in CloudCompare to verify that distinct parallel joints have not been incorrectly merged.
    • Data Dependencies & Over-Merging Risk:
      • The quality of merging depends on point cloud planarity, surface roughness, and how well the principal pole represents the set's orientations.
      • Warning on High Dispersion ($\sigma$): If a family presents high angular variation / dispersion (large $\sigma$), the physical search distance calculated by $k \cdot \sigma$ becomes wide. In such cases, coplanarity merging can cause over-merging, erroneously joining distinct parallel joint surfaces that are close to each other.
    • Engineering Importance: Coplanarity merging is critical for accurate Set Normal Spacing calculations downstream. Merging fragmented patches avoids artificially underestimating spacing, provided over-merging is carefully prevented through inspection.

  • Fix Orientation (use pole normal):

    • Concept: Forces all fitted cluster planes within Discontinuity Set $J_k$ to adopt the exact unit normal vector $(A, B, C)$ of the family's mean principal pole.
    • Engineering Importance: Fixing the orientation locks the normal direction across all clusters of a family, isolating parameter $D$ as the sole spatial variable representing parallel plane position along the normal axis.

2.3 Cluster Sorting Options

The Sort Clusters by dropdown defines the ordering criterion used to assign integer IDs (1, 2, 3...) to individual clusters within each discontinuity family:

  • Random: Assigns cluster indices arbitrarily (a custom seed can be specified in Random Seed for reproducibility).
  • Size: Sorts clusters by total point count (Cluster 1 = largest surface area/point count).
  • Position ($D$ parameter): Sorts clusters sequentially along the family's normal vector direction based on their orthogonal distance $D$ from the origin.

Validation Tip: Cluster sorting determines the color assignment when viewing the Cluster id scalar field in CloudCompare. Sorting by Position ($D$) creates a smooth, rainbow gradient along the thickness of the rock mass, making it easy to visually verify parallel joint bedding and spacing.

3. 3D Cluster Visualisation in CloudCompare

Upon clicking Classify Point Cloud / Run Spatial Clustering, DSEpy writes a new integer Scalar Field named Cluster id (or cl) directly to the active CloudCompare entity.

3D Point Cloud in CloudCompare color-coded by Cluster id 3D Point Cloud in CloudCompare color-coded by the Cluster id scalar field, displaying individual spatial joint facets.

3.1 Cluster Export Options

To facilitate detailed manual inspection of individual joint planes:

  • Export one patch per DS family with Cluster id active: Exports a unified point cloud for each family with the Cluster id scalar field pre-activated for quick scalar filtering in CloudCompare.
  • Create separate cluster clouds: Generates separate, individual point cloud sub-entities for every detected cluster in the CloudCompare database tree (DBTree), allowing individual facets to be toggled, isolated, or measured independently.

4. Facet Fitting & Geometric Shapes

DSEpy can fit synthetic 3D geometric facet polygons to each isolated spatial cluster [1, 2]. These facets simplify point cloud geometry into clean 3D CAD/GIS surfaces suitable for slope stability modeling, block kinematic analysis, or fracture network generation.

CloudCompare Facet Shapes Overlay 3D Disk facet shapes fitted to individual spatial clusters and exported directly into CloudCompare.

4.1 Supported Facet Shapes

Using the Facet shape dropdown, users can choose from four geometry fitting models:

  1. Convex Hull: Generates a 2D convex polygon bounding the outer perimeter points of the cluster projected onto the fitted plane. Preserves true exposed surface boundaries.
  2. Rectangle: Fits a minimum bounding rectangle aligned with the principal axes of the point cluster.
  3. Disk: Fits a circular 3D disk centered at the cluster centroid with a radius equal to the maximum extent of the point cluster.
  4. Ellipse: Fits an equivalent 3D ellipse reflecting the major and minor axis aspect ratios of the cluster spatial distribution.

When executed, DSEpy automatically organizes the generated facets into structured subfolders grouped by discontinuity family (e.g., DSE_Cluster_facets_disk_123456/J1, /J2, /J3), allowing direct export to 3D CAD formats or civil engineering analysis software.

5. Interface Parameter Reference

Parameter Recommended Value Description
K-th Neighbor ($K$) 4 Neighbor count used to calculate local point distance graphs.
Sigma Multiplier ($k_{\text{sigma}}$) 2.0 Multiplier for determining DBSCAN spatial search radius $\epsilon$.
DBSCAN MinPts 4 Minimum points required to establish a dense cluster core.
Minimum Cluster Size 100 Minimum point threshold for a valid cluster facet. Clusters below are discarded as spatial noise.
Coplanarity Merge 0.0 initially
1.0 – 2.0 (refinement)		 Tolerance multiplier ($k_{\text{sigmas}}$) to merge coplanar patches. Set to 0.0 first for visual inspection; use caution when angular dispersion ($\sigma$) is high to avoid over-merging parallel planes.
Fix Orientation Checked Forces cluster plane normals to equal the principal set pole orientation vector.
Sort Clusters by Position (D) or Size Ordering logic used for assigning Cluster id values and color ramps.
Facet Shape Disk / Convex Geometry type used to reconstruct planar 3D facets for exported joint sets.

🔗 Next Steps

Once spatial clustering is complete, evaluate the visual quality of the isolated facets:

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). Uso de nubes de puntos 3D para identificación y caracterización de familias de discontinuidades planas en afloramientos rocosos y evaluación de la calidad geomecánica (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