Auto Structural Mapping

Use Automated Structural Mapping to segment a triangulated mesh (TIN) into coherent planar patches using dip/azimuth orientation and an optional coplanarity metric. The tool writes per‑triangle attributes and can create per‑patch geometry objects for downstream analysis.

Prerequisites

• A selected TriangulatedMesh in the Project Tree.
• Triangle attributes available on the mesh:
  • Dip (degrees) and Azimuth (degrees) for orientation‑based growth.
  • CoPlanarity (scalar) for seeding and optional non‑orientation growth/filtering.

If any of these are missing, compute or import them first. When dip/azimuth are missing, the algorithm falls back to face normals (forced to the +Z hemisphere), but results may be less geologically meaningful.

Launch

• Project Tree: select a triangulated mesh, then run Attributes → Patch Decomposition (opens “Automated Structural Mapping”).
• Buttons: Apply runs without closing; OK runs and closes.

Dialog Fields

Attributes

• Coplanarity: Choose the layer used to order seeds and, optionally, to filter triangles during growth.
• Use Coplanarity Filter: When on, respects the coplanarity mapper’s min/max window. Triangles with any vertex filtered out are excluded; seeds are limited to values within the window.
• Dip: Choose the dip attribute layer for orientation growth.
• Azimuth: Choose the azimuth attribute layer for orientation growth.

Settings

• Minimum Patch Size: Minimum number of triangles required for a patch to be accepted.
• Tolerance Angle: Orientation mode: angular tolerance in degrees for neighbor acceptance. Non‑orientation mode: treated as a scalar tolerance on coplanarity values.
• Relative Variation: Orientation reference. When on, compares each neighbor to the current triangle (“relative”). When off, compares to the seed triangle. See also “Use Mean Reference”.
• Fix Single Holes: After growth, fill single‑triangle holes fully surrounded by the patch to clean up small gaps.
• Create Objects: Create a per‑patch Orientation object named Auto_<ID> (count) with collected patch vertices.
• Dispersion (0..1): Acceptance control for patch coherence when RMin is not used. Patch is accepted if the average axial angle to the patch mean is ≤ Dispersion * Tolerance Angle. Default 0.75.
• Use Mean Reference: Growth reference is a running axial mean of the patch, not the seed/current triangle. More robust on smoothly varying surfaces.
• RMin (0..1): Mean resultant length threshold for acceptance in orientation mode. If > 0, supersedes Dispersion. Typical values: 0.7–0.9 (tight), 0.5–0.7 (looser).

Filter

• Dip: Enable and set [min, max] in degrees. The patch’s axial mean dip must fall within this window to be accepted.
• Azimuth: Enable and set [min, max] in degrees. Wrap‑around is supported: e.g., 350–10 accepts angles ≥ 350 or ≤ 10.
• Get From Selected: Populates Dip/Azimuth windows from selected orientation objects or measurements (Strike/Dip). The +/- margin expands the window on both sides.
• +/-: Margin in degrees used by “Get From Selected”.

What It Writes

• Triangle attributes added:
  • Patches (int): Patch ID (0 = unassigned).
  • Patch Size (int): Number of triangles in the patch.
  • Patch Difference (float):
    • Orientation mode: angular difference to the patch mean in radians (0..π/2, axial).
    • Non‑orientation mode: absolute difference in coplanarity values.
  • Patch Similarity (float): |dot(pole, patch_mean)| in [0..1] (orientation mode only).
  • Patch CoPlanarity (float): coplanarity of the patch as a whole — one plane fitted through every node in the patch, its ln(λ₁/λ₃) written to each of the patch's triangles. Patches of fewer than four distinct nodes are left at 0. On the same scale as the per‑vertex CoPlanarity attribute, so the two can be compared directly.
• Optional objects: A per‑patch Orientation object when Create Objects is enabled.

tip

Prefer Patch CoPlanarity when you want to know how planar a surface is. The per‑vertex attribute measures a sphere of points around each vertex, so near the edge of a face that sphere spills onto the neighbouring facet and coplanarity dips all round the rim of a surface that is genuinely flat. A patch is one surface by construction, so it carries no such rim effect — and because patches partition the triangles, every triangle has exactly one value.

How It Works (Summary)

Implementation: CAutoStructureMappingDlg drives CTINPatchDecomposer.

1. Attribute setup

• SetAttributes(Dip, Azimuth, CoPlanarity, UseCoplanarityFilter). If Coplanarity is present and filtering is enabled, seed candidates are restricted to the mapper’s range and triangles with filtered vertices are excluded during growth.

2. Seed ordering

• Triangles are ordered by average coplanarity (highest first) when available; otherwise by index. Filtered triangles are skipped when filter is on.

3. Patch growth

• Orientation mode (default): Accepts neighbor triangles whose axial angle to the chosen reference is ≤ Tolerance Angle.
  • Reference can be: current triangle (Relative), seed triangle, or running mean (Use Mean Reference).
• Non‑orientation mode: Uses coplanarity differences instead of angles.

4. Acceptance

• Must meet Minimum Patch Size and Dip/Azimuth filter windows (if enabled).
• Coherence controls (orientation mode):
  • If RMin > 0: compute mean resultant length R = |Σ aligned poles| / N and require R ≥ RMin.
  • Else: require average axial angle to the patch mean ≤ Dispersion * Tolerance Angle.

5. Post‑processing

• Optional single‑triangle hole fill; attribute writing; hide consumed triangles during sweep to avoid reseeding; unhide at end.

Tips For Best Results

• Start conservative: Tolerance Angle 10–20°. If patches are too fragmented, increase gradually or enable Use Mean Reference.
• Use RMin for consistency: Prefer RMin (e.g., 0.8) when you want patches with uniform orientation, independent of the chosen tolerance.
• Target known sets: Enable Dip/Azimuth filters to focus on expected planes (e.g., bedding or dominant fracture sets).
• Wrap‑around azimuth: For ranges that cross 0°, set min > max (e.g., 350–10). The filter treats this as a wrap.
• Smoothly varying surfaces: Enable Use Mean Reference to let the patch “follow” gentle curvature without drifting.
• Clean boundaries: Leave Relative Variation off when boundaries are crisp; turn it on to allow local adaptation, but watch for gradual drift.
• Faster iteration: Try Apply without Create Objects first. Create Objects can be heavier on large meshes.

Troubleshooting

• “Missing Attributes: Need Dip, Azimuth and Coplanarity”: Ensure the mesh has all three attribute layers selected in the dialog. If coplanarity is not used, you still need to choose a layer; you can disable Use Coplanarity Filter if you don’t want it to constrain growth.
• No patches created or far too few:
  • Increase Tolerance Angle, reduce Minimum Patch Size, disable Dip/Azimuth filters, or relax Dispersion/increase RMin.
  • Verify Dip/Azimuth are in degrees and valid per triangle.
• Over‑merged patches (too large/indistinct):
  • Reduce Tolerance Angle, increase RMin, or lower Dispersion.
  • Narrow Dip/Azimuth filter windows to isolate sets.
• Azimuth window behaves oddly: Check wrap‑around. Use ranges like 350–10 for values straddling 0°.
• Attributes look constant or zero:
  • Confirm you selected the intended layers in Attributes. Recompute Dip/Azimuth/Coplanarity if needed.
• Performance concerns:
  • Subsequent Apply runs in the same dialog avoid recomputing connectivity. Close/reopen only when necessary.

Reference: Parameter Mapping

• Minimum Patch Size → MinTriangles
• Tolerance Angle → MaxAng (degrees in orientation mode)
• Relative Variation → IsRelative
• Fix Single Holes → bFixHoles
• Create Objects → bSaveData
• Dip/Azimuth filters → SetDipFilter, SetAzimuthFilter
• Use Coplanarity Filter → passed to SetAttributes(..., UseCoplanarityFilter)
• Dispersion → SetDispersionFraction
• Use Mean Reference → UseMeanReference
• RMin → SetResultantMin

See also: internal notes in VRGS2020/CTINPatchDecomposer.md for lower‑level details of the algorithm and outputs.