SurfaceMesh: 3D Surface Meshes Based on CGAL

Daniel Wollschläger (wollschlaeger@uni-mainz.de)

Oktober 30, 2026

Introduction

SurfaceMesh is an R package that supports processing of 3D surface meshes using as backend the C++ library for computational geometry CGAL via R package RcppCGAL. Features include:

The package also calculates surface distance and volume-overlap based similarity metrics for a given pair of 3D surface meshes (see dkfz metrics reloaded):

Background

This package includes code adapted from packages Boov, cgalMeshes, and SurfaceReconstruction, developed and copyright by Stéphane Laurent. Currently, only a subset of the functionality of these packages is provided in SurfaceMesh.

A fork / adaptation of packages Boov, cgalMeshes, and SurfaceReconstruction was carried out as upstream changes to CGAL introduced incompatibilities, and the packages were archived from CRAN.

The design was chosen such that mesh data resides in R space. This means that for each mesh operation, data is first transferred to the C++ side (using Rcpp), converted to a CGAL surface mesh, processed with CGAL functions, and then transferred back to R. The package does not maintain a pointer to a C++ data structure to keep the mesh data there - unlike packages such as terra or cgalMeshes. This approach carries a performance penalty, but from an R perspective, it is more straightforward. In particular, there are no serialization issues (saving meshes). Furthermore, memory management is easier.

Create Surface Meshes

See vignette("SurfaceMesh_Examples") for meshes included in this package as examples.

Read Mesh / Polygon Soup Files

f_mesh   <- system.file("extdata", "dataCorner.off", package="SurfaceMesh")
mesh     <- makeMesh(f_mesh, verbose=FALSE)
mesh_rgl <- toRGL(mesh)

view3d(85, -65, zoom=0.8)
shade3d(mesh_rgl, col="wheat2")

Create Surface Mesh Based on mesh3d Object

dataTubularKnot
##  mesh3d object with 3600 vertices, 7200 triangles.
mesh <- makeMesh(dataTubularKnot)
mesh
## CGALmesh with 3600 vertices and 7200 faces.
## The edge lengths vary from 0.06447 to 0.593.
## This mesh is triangle.
## This mesh can be converted to a 'rgl' mesh (see `?toRGL`).
## This mesh does not have vertex normals.

Triangulate

mesh     <- makeMesh(dataSeptuaginta, triangulate=FALSE, verbose=FALSE)
mesh_rgl <- toRGL(mesh)
isTriangle(mesh)
## [1] FALSE
mesh_tri     <- triangulateMesh(mesh)
mesh_tri_rgl <- toRGL(mesh_tri)

mfrow3d(1, 2)
view3d(0, 30, zoom=0.8)
wire3d(mesh_rgl)
next3d()
view3d(0, 30, zoom=0.8)
wire3d(mesh_tri_rgl)

Vertex normals

Calculate vertex normals when creating a mesh.

mesh <- makeMesh(dataToroHelix, normals=TRUE)
mesh
## CGALmesh with 6000 vertices and 12000 faces.
## The edge lengths vary from 0.1463 to 0.7058.
## This mesh is triangle.
## This mesh can be converted to a 'rgl' mesh (see `?toRGL`).
## This mesh has vertex normals.

Calculate vertex normals for existing mesh.

mesh    <- makeMesh(dataToroHelix, normals=FALSE)
mesh_vn <- addVertexNormals(mesh)

mfrow3d(1, 2)
view3d(0, 30, zoom=0.8)
shade3d(toRGL(mesh), col="tomato")
next3d()
view3d(0, 30, zoom=0.8)
shade3d(toRGL(mesh_vn), col="turquoise4")

Extract vertex normals.

mesh <- makeMeshValid(dataSphere, normals=TRUE)
vn   <- getVertexNormals(mesh)
head(vn)
##               [,1]       [,2]          [,3]
## [1,] -1.114637e-16  0.5257311  8.506508e-01
## [2,]  5.573185e-17  0.5257311 -8.506508e-01
## [3,]  3.761900e-16 -0.5257311  8.506508e-01
## [4,] -3.483241e-16 -0.5257311 -8.506508e-01
## [5,]  5.257311e-01  0.8506508 -1.569679e-16
## [6,]  5.257311e-01 -0.8506508  3.622570e-16

Set vertex normals to given matrix.

## random unit normal vectors
mesh    <- makeMesh(dataPentaPrism, triangulate=TRUE, normals=FALSE)
nVerts  <- nrow(mesh[["vertices"]])
nrmls0  <- matrix(runif(nVerts*3), ncol=3)
lens    <- sqrt(rowSums(nrmls0^2))
nrmls   <- diag(1/lens) %*% nrmls0

## set vertex normals
mesh_vn <- setVertexNormals(mesh, nrmls)
head(mesh_vn[["normals"]])
##           [,1]      [,2]      [,3]
## [1,] 0.3040854 0.9406019 0.1509972
## [2,] 0.6986143 0.6139785 0.3673806
## [3,] 0.4726623 0.7402458 0.4781490
## [4,] 0.6398779 0.7204969 0.2672836
## [5,] 0.8131478 0.5669370 0.1318069
## [6,] 0.0629725 0.9793978 0.1918709
head(nrmls)
##           [,1]      [,2]      [,3]
## [1,] 0.3040854 0.9406019 0.1509972
## [2,] 0.6986143 0.6139785 0.3673806
## [3,] 0.4726623 0.7402458 0.4781490
## [4,] 0.6398779 0.7204969 0.2672836
## [5,] 0.8131478 0.5669370 0.1318069
## [6,] 0.0629725 0.9793978 0.1918709

Mesh Characteristics

Check Mesh Status

mesh <- makeMeshValid(dataTorus)
isValid(mesh)
## [1] TRUE
hasGarbage(mesh)
## [1] FALSE
isTriangle(mesh)
## [1] TRUE
isQuad(mesh)
## [1] FALSE
doesBoundVolume(mesh)
## [1] TRUE
isClosed(mesh)
## [1] TRUE
doesSelfIntersect(mesh)
## [1] FALSE

Check and Change Mesh Orientation

mesh_rgl <- meshIsoCuboid(c(-1, -2, -3), c(1, 2, 3))
mesh     <- makeMeshValid(mesh_rgl)
mesh_rfo <- reverseFaceOrientations(mesh)
isOutwardOriented(mesh)
## [1] TRUE
isOutwardOriented(mesh_rfo)
## [1] FALSE

Two tetraeders, one with positive orientation, one with negative orientation.

vertices <- rbind(
    c(0, 0, 0),
    c(2, 2, 0),
    c(2, 0, 2),
    c(0, 2, 2),
    c(3, 3, 3),
    c(5, 5, 3),
    c(5, 3, 5),
    c(3, 5, 5))

faces <- rbind(
    c(3, 2, 1),
    c(3, 4, 2),
    c(1, 2, 4),
    c(4, 3, 1),
    c(5, 6, 7),
    c(6, 8, 7),
    c(8, 6, 5),
    c(5, 7, 8))

mesh    <- makeMesh(vertices, faces=faces)
mesh_bv <- orientToBoundVolume(mesh)
doesBoundVolume(mesh)
## [1] FALSE
doesBoundVolume(mesh_bv)
## [1] TRUE

Measurements

Centroid (Center of Mass)

mesh <- makeMesh(dataPentaPrism, triangulate=TRUE)
getCentroid(mesh)
## [1] -8.735937e-18 -3.931172e-18 -4.367969e-19

Surface Area

mesh <- makeMesh(dataTruncIcosahedron, triangulate=TRUE)
getArea(mesh)
## [1] 72.60725

Volume

mesh <- makeMesh(dataSeptuaginta, triangulate=TRUE)
getVolume(mesh)
## [1] 3.732051

Average Spacing

mesh <- makeMesh(dataToroHelix, triangulate=TRUE)
getAverageSpacing(mesh[["vertices"]], nNeighbors=12L)
## [1] 0.3432712

Mesh Repair

See CGAL mesh repair

Fill Boundary Holes

Note: Hole is easier to see in interactive version shown with example(fillBoundaryHoles).

f_mesh <- system.file("extdata", "dataCornerHole.off", package="SurfaceMesh")
mesh   <- makeMesh(f_mesh, triangulate=TRUE, verbose=TRUE)
## Processing mesh...
## Mesh is not closed.
## Mesh is triangle.
## Mesh does not have self-intersections.
## Mesh is valid.
mesh_rgl  <- toRGL(mesh)
mesh_fill <- fillBoundaryHoles(mesh, verbose=TRUE)
## Trying to fill boundary holes.
## Filled 1 boundary hole(s).
## Mesh is closed.
## Mesh is triangle.
## Mesh does not have self-intersections.
## Mesh bounds a volume.
## Mesh is valid.
mesh_fill_rgl <- toRGL(mesh_fill)

mfrow3d(1, 2)
view3d(70, 25, zoom=0.8)
shade3d(mesh_rgl, col="orangered")
next3d()
view3d(70, 25, zoom=0.8)
shade3d(mesh_fill_rgl, col="violetred")

Remove Self-Intersections

TODO: Use a mesh with self-intersections.

mesh     <- makeMesh(dataPentaPrism, triangulate=TRUE)
mesh_nsi <- removeSelfIntersections(mesh)
getVolume(mesh_nsi)
## [1] 0.06205414

Randomly Sample Points on a Mesh

mesh      <- makeMesh(dataPentaPrism, triangulate=TRUE)
ptsOnMesh <- samplePoints(mesh, ptsOnFaces=2L)
head(ptsOnMesh)
##            [,1]      [,2] [,3]
## [1,]  0.5257311  0.000000  0.1
## [2,]  0.1624598  0.500000  0.1
## [3,] -0.4253254  0.309017  0.1
## [4,] -0.4253254 -0.309017  0.1
## [5,]  0.1624598 -0.500000  0.1
## [6,]  0.5257311  0.000000 -0.1

Boolean Mesh Operations on Bounded Volumes

See CGAL Boolean operations

Union

# mesh one: a cube
mesh1_rgl  <- cube3d()   # (from the rgl package)
mesh2_rgl  <- translate3d(cube3d(), 1, 1, 1)
mesh_u     <- boolUnion(list(mesh1_rgl, mesh2_rgl))
mesh_u_rgl <- toRGL(mesh_u)

shade3d(mesh_u_rgl, color="red")

Difference

mesh1_rgl  <- cube3d()   # (from the rgl package)
mesh2_rgl  <- translate3d(cube3d(), 1, 1, 0)
mesh_d     <- boolDifference(mesh1_rgl, mesh2_rgl)
mesh_d_rgl <- toRGL(mesh_d)

shade3d(mesh1_rgl,  color="yellow", alpha=0.2)
shade3d(mesh2_rgl,  color="cyan",   alpha=0.2)
shade3d(mesh_d_rgl, color="red")

Intersection

mesh1      <- makeMesh(dataTruncIcosahedron, triangulate=TRUE)
mesh1_rgl  <- toRGL(mesh1)
mesh2_rgl  <- translate3d(cube3d(), 2, 0, 0)
mesh2      <- makeMesh(mesh2_rgl, triangulate=TRUE)
mesh_i     <- boolIntersection(list(mesh1, mesh2))
mesh_i_rgl <- toRGL(mesh_i)

shade3d(mesh1_rgl,  color="yellow", alpha=0.2)
shade3d(mesh2_rgl,  color="cyan",   alpha=0.2)
shade3d(mesh_i_rgl, color="red")

Remeshing

See CGAL remeshing

Approximated centroidal Voronoi diagram remeshing

mesh       <- makeMeshValid(dataOloid)
mesh_rgl   <- toRGL(mesh)
mesh_d     <- remeshACVD(mesh, method="uniform_iso_qem", nVerts=100L)
mesh_d_rgl <- toRGL(mesh_d)

mfrow3d(1, 2)
view3d(0, 30, zoom=0.8)
wire3d(mesh_rgl)
next3d()
view3d(0, 30, zoom=0.8)
wire3d(mesh_d_rgl)

Surface Delaunay

mesh     <- makeMesh(dataPentaPrism, triangulate=TRUE)
mesh_rgl <- toRGL(mesh)
mesh_d   <- remeshDelaunay(mesh,
                           edgeSize=0.2,
                           facetDist=0.2,
                           protectConstraints=TRUE)
mesh_d_rgl <- toRGL(mesh_d)

mfrow3d(1, 2)
view3d(0, 30, zoom=0.8)
wire3d(mesh_rgl)
next3d()
view3d(0, 30, zoom=0.8)
wire3d(mesh_d_rgl)

Isotropic

mesh       <- makeMesh(dataTruncIcosahedron, triangulate=TRUE)
mesh_rgl   <- toRGL(mesh)
mesh_i     <- remeshIsotropic(mesh, targetEdgeLen=0.7)
mesh_i_rgl <- toRGL(mesh_i)

mfrow3d(1, 2)
view3d(0, 0, zoom=0.7)
wire3d(mesh_rgl)
next3d()
view3d(0, 0, zoom=0.7)
wire3d(mesh_i_rgl)

Triangulated Surface Mesh Simplification

mesh       <- makeMesh(dataHopfTorus, triangulate=TRUE)
mesh_rgl   <- toRGL(mesh)
mesh_s     <- remeshSimplify(mesh, method="LT-R", stopUeRatio=0.1)
mesh_s_rgl <- toRGL(mesh_s)

mfrow3d(1, 2)
view3d(0, 0, zoom=0.7)
wire3d(mesh_rgl)
next3d()
view3d(0, 0, zoom=0.7)
wire3d(mesh_s_rgl)

Smoothing

Smooth Shape

mesh       <- dataHeart1
mesh_rgl   <- toRGL(mesh)
mesh_s     <- remeshSmoothShape(mesh, nIter=5L, time=1)
mesh_s_rgl <- toRGL(mesh_s)

mfrow3d(1, 2)
view3d(0, -90, zoom=0.7)
shade3d(mesh_rgl, col="forestgreen")
next3d()
view3d(0, -90, zoom=0.7)
shade3d(mesh_s_rgl, col="darkolivegreen4")

Angle Smoothing

mesh       <- makeMesh(dataSeptuaginta, triangulate=TRUE)
mesh_rgl   <- toRGL(mesh)
mesh_s     <- remeshSmoothAngle(mesh, nIter=5L)
mesh_s_rgl <- toRGL(mesh_s)

mfrow3d(1, 2)
view3d(45, -45, zoom=0.7)
shade3d(mesh_rgl, col="darkviolet")
next3d()
view3d(45, -45, zoom=0.7)
shade3d(mesh_s_rgl, col="gray")

Note that CGAL angle_and_area_smoothing() supports smoothing by area optimization as well. However, this feature requires the external Ceres library and is thus currently not enabled here.

Tangential Relaxation

mesh       <- makeMesh(dataSeptuaginta, triangulate=TRUE)
mesh_rgl   <- toRGL(mesh)
mesh_s     <- remeshSmoothTangentRelax(mesh, nIter=5L)
mesh_s_rgl <- toRGL(mesh_s)

mfrow3d(1, 2)
view3d(45, -45, zoom=0.7)
shade3d(mesh_rgl, col="gray")
next3d()
view3d(45, -45, zoom=0.7)
shade3d(mesh_s_rgl, col="royalblue3")

Subdivision

See CGAL subdivision

Catmull-Clark

mesh        <- makeMesh(dataPentaPrism, triangulate=TRUE)
mesh_rgl    <- toRGL(mesh)
mesh_cc     <- subdivide(mesh, method="CC", nIter=2L)
mesh_cc_rgl <- toRGL(mesh_cc)

mfrow3d(1, 2)
view3d(0, 30, zoom=0.8)
wire3d(mesh_rgl)
next3d()
view3d(0, 30, zoom=0.8)
wire3d(mesh_cc_rgl)

Doo-Sabin

mesh        <- makeMesh(dataSeptuaginta, triangulate=TRUE)
mesh_rgl    <- toRGL(mesh)
mesh_ds     <- subdivide(mesh, method="DS", nIter=1L)
mesh_ds_rgl <- toRGL(mesh_ds)

mfrow3d(1, 2)
view3d(0, 30, zoom=0.8)
wire3d(mesh_rgl)
next3d()
view3d(0, 30, zoom=0.8)
wire3d(mesh_ds_rgl)

Loop

mesh       <- makeMesh(dataSeptuaginta, triangulate=TRUE)
mesh_rgl   <- toRGL(mesh)
mesh_l     <- subdivide(mesh, method="Loop", nIter=1L)
mesh_l_rgl <- toRGL(mesh_l)

mfrow3d(1, 2)
view3d(0, 30, zoom=0.8)
wire3d(mesh_rgl)
next3d()
view3d(0, 30, zoom=0.8)
wire3d(mesh_l_rgl)

Sqrt3

mesh        <- makeMesh(dataPentaPrism, triangulate=TRUE)
mesh_rgl    <- toRGL(mesh)
mesh_s3     <- subdivide(mesh, method="Sqrt3", nIter=2L)
mesh_s3_rgl <- toRGL(mesh_s3)

mfrow3d(1, 2)
view3d(0, 30, zoom=0.8)
wire3d(mesh_rgl)
next3d()
view3d(0, 30, zoom=0.8)
wire3d(mesh_s3_rgl)

Surface Reconstruction

Removing outliers from point cloud

ptsBefore <- matrix(rnorm(120L, mean=0, sd=1), ncol=3L)
getAverageSpacing(ptsBefore, nNeighbors=6L)
## [1] 0.8674813
## contaminate
idx              <- sample(seq_len(nrow(ptsBefore)), 4L, replace=FALSE)
ptsBefore[idx, ] <- matrix(rnorm(12L, mean=10, sd=1), ncol=3L)
ptsAfter         <- removeOutliers(ptsBefore, nNeighbors=6L)
dim(ptsBefore)
## [1] 40  3
dim(ptsAfter)
## [1] 36  3

AFS

See CGAL AFS

mesh         <- dataHeart1
mesh_rgl     <- toRGL(mesh)
mesh_afs     <- reconstructAFS(mesh[["vertices"]], nNeighbors=30)
mesh_afs_rgl <- toRGL(mesh_afs)

mfrow3d(1, 2)
view3d(0, -90, zoom=0.7)
shade3d(mesh_rgl, col="mediumorchid4")
next3d()
view3d(0, -90, zoom=0.7)
shade3d(mesh_afs_rgl, col="maroon2")

SSS

See CGAL SSS

mesh     <- dataHeart1
mesh_rgl <- toRGL(mesh)
mesh_sss <- reconstructSSS(mesh[["vertices"]],
                           nScaleIter   =2L,
                           forceManifold=TRUE,
                           nNeighbors   =12L)
mesh_sss_rgl <- toRGL(mesh_sss)

mfrow3d(1, 2)
view3d(0, -90, zoom=0.7)
shade3d(mesh_rgl, col="yellowgreen")
next3d()
view3d(0, -90, zoom=0.7)
shade3d(mesh_sss_rgl, col="rosybrown4")

Poisson

See CGAL SSS

mesh     <- makeMesh(dataSeptuaginta)
mesh_rgl <- toRGL(mesh)
mesh_psr <- reconstructPoisson(mesh[["vertices"]],
                               normalsFun=getNormalsFun(6L),
                               smAngle=20,
                               smRadius=1,
                               smDistance=20)
mesh_psr_rgl <- toRGL(mesh_psr)

mfrow3d(1, 2)
shade3d(mesh_rgl, col="gray")
next3d()
shade3d(mesh_psr_rgl, col="gray")

Alpha Wrapping

See CGAL Alpha Wrapping

mesh        <- dataHeart1
mesh_rgl    <- toRGL(mesh)
mesh_aw     <- alphaWrap(mesh,
                         alphaRel =10,
                         offsetRel=300)
mesh_aw_rgl <- toRGL(mesh_aw)

mfrow3d(1, 2)
view3d(0, -90, zoom=0.7)
shade3d(mesh_rgl, col="olivedrab3")
next3d()
view3d(0, -90, zoom=0.7)
shade3d(mesh_aw_rgl, col="mediumseagreen")

Bounding Shapes

Axis-parallel Bounding Box

mesh1     <- makeMesh(dataTubularKnot)
mesh1_rgl <- toRGL(mesh1)
bb1       <- getBoundingBox(mesh1[["vertices"]])
bb1_rgl   <- toRGL(bb1)

view3d(10, 25, zoom=0.9)
shade3d(mesh1_rgl, color="mediumaquamarine")
wire3d(bb1_rgl)

Optimal (Oriented) Bounding Box

Based on matrix of points

mesh2     <- dataHeart1
mesh2_rgl <- toRGL(mesh2)
bb2       <- getBoundingBox(mesh2[["vertices"]], oriented=TRUE)
bb2_rgl   <- toRGL(bb2)
shade3d(mesh2_rgl, color="peachpuff")
wire3d(bb2_rgl)

Bounding Sphere

Based on mesh3d object

bs_rgl <- getBoundingSphere(dataToroHelix, out="rgl")
shade3d(dataToroHelix, color="plum2")
wire3d(bs_rgl)

Bounding Ellipse

mesh     <- dataHeart1
mesh_rgl <- toRGL(mesh)
bell_rgl <- getBoundingEll(mesh, out="rgl", eps=0.01)
shade3d(mesh_rgl, color="lightgreen")
wire3d(bell_rgl)

Convex Hull

mesh     <- makeMesh(dataToroHelix)
mesh_rgl <- toRGL(mesh)
hull     <- getConvexHull(mesh[["vertices"]])
hull_rgl <- toRGL(hull)

mfrow3d(1, 2)
view3d(15, 45, zoom=0.8)
wire3d(mesh_rgl)
next3d()
view3d(15, 45, zoom=0.8)
wire3d(hull_rgl)

Distace and Agreement Measures

Euclidean Distance from Points to a Mesh

mesh   <- makeMesh(dataPentaPrism, triangulate=TRUE)
points <- matrix(2*runif(3*4), ncol=3)
getDistance(mesh, points)
## [1] 1.961426 1.748435 1.702709 1.320738

Distance Between the Two Respective Centers of Mass (DCOM)

getDCOM(dataHeart1, dataHeart2)
## [1] 2.784605

Surface Distance Between two Meshes

Hausdorff Distance

See CGAL Hausdorff distance, dkfz metrics reloaded: HD

Approximate

getHausdorff(dataHeart1, dataHeart2, symmetric=TRUE)
## [1] 13.90838

Bounded error

getHausdorff(dataHeart1, dataHeart2, symmetric=TRUE, errBound=0.01)
## [1] 13.90838

Quantile (e.g., ‘HD95’), see dkfz metrics reloaded: xHD

getHausdorff(dataHeart1, dataHeart2, symmetric=TRUE, p=0.95)
## [1] 7.967251

Average symmetric surface distance (ASSD) and Root Mean Squared Error (RMSE)

See dkfz metrics reloaded: ASSD

sd_heart <- getSurfaceDist(dataHeart1, dataHeart2, p=0.95, ptsOnFaces=100L)
sd_heart[["ASSD"]]
## [1] 2.037871
sd_heart[["RMSE"]]
## [1] 3.105619

Volume-Overlap Based Similarity Measures

mesh1_rgl <- cube3d()      # (from the rgl package)
mesh2_rgl <- translate3d(cube3d(), 1, 1, 1)
jsc_dsc   <- getJSCDSC(mesh1_rgl, mesh2_rgl)
jsc_dsc[["JSC"]]
## [1] 0.06666667
jsc_dsc[["DSC"]]
## [1] 0.125