ravetools (version 0.3.2)

vcg_fix_defects: Detect and repair defects in a triangular surface mesh

Description

Repairs common defects that prevent a mesh from being a closed, manifold, genus-0 surface - a hard precondition of algorithms such as mris_inflate. Typical sources of such defects are surfaces extracted from volumes via marching-cubes-style algorithms (e.g. vcg_isosurface), which can leave behind small "cracks": isolated boundary-edge loops bounding tiny holes that are not closed by simple vertex-welding.

Usage

vcg_fix_defects(
  mesh,
  merge_tolerance = NA,
  max_hole_size = 100L,
  verbose = FALSE
)

Value

A repaired triangular mesh of class 'mesh3d', with an additional attribute "info", a named list reporting what was found and changed: boundary_edges_before/after, nonmanifold_edges_before/after, vertices_merged, merge_tolerance, holes_filled, is_oriented, is_orientable, normals_flipped_outward, and is_closed_manifold (TRUE when the repaired mesh is closed and manifold, i.e. ready for mris_inflate).

Arguments

mesh

triangular mesh of class 'mesh3d'.

merge_tolerance

distance (in mesh units) below which vertices are welded together; default is NA, in which case the tolerance is derived automatically as 1e-4 times the mesh's average edge length.

max_hole_size

maximum number of boundary edges of a hole that will be triangulated (ear-cutting fill); holes larger than this threshold are left untouched (and will be reported as remaining boundary edges in attr(..., "info")). Default is 100.

verbose

whether to print a short before/after diagnostic report; default is FALSE.

Details

The repair pipeline applies, in order:

1. Remove degenerate and duplicate faces.

2. Weld near-coincident vertices (closes cracks caused by duplicated vertices), using merge_tolerance or, by default, a distance derived from the mesh's average edge length.

3. Triangulate ("ear-cut fill") any remaining small boundary loops -- i.e. isolated edges / genuine small holes that welding alone cannot close, up to max_hole_size edges.

4. Remove unreferenced vertices.

5. Re-orient all faces coherently (consistent winding order), and, if the result is a single watertight component, flip normals to point outward (this last step assumes the geometry is meant to be watertight).

Examples

if (is_not_cran()) {

  mesh <- vcg_isosurface(left_hippocampus_mask)

  repaired <- vcg_fix_defects(mesh, verbose = TRUE)

  attr(repaired, "info")$is_closed_manifold

  # repaired mesh can now be inflated
  inflated <- mris_inflate(repaired, scale_brain = FALSE)

}