geometry (version 0.5.0)

convhulln: Compute smallest convex hull that encloses a set of points

Description

Returns information about the smallest convex complex of a set of input points in \(N\)-dimensional space (the convex hull of the points). By default, indices to points forming the facets of the hull are returned; optionally normals to the facets and the generalised surface area and volume can be returned. This function interfaces the Qhull library.

Usage

convhulln(
  p,
  options = "Tv",
  output.options = NULL,
  return.non.triangulated.facets = FALSE
)

Value

By default (return.non.triangulated.facets is

FALSE), return an \(M\)-by-\(N\) matrix in which each row contains the indices of the points in p forming an

\(N-1\)-dimensional facet. e.g In 3 dimensions, there are 3 indices in each row describing the vertices of 2-dimensional triangles.

If return.non.triangulated.facets is TRUE then the number of columns equals the maximum number of vertices in a facet, and each row defines a polygon corresponding to a facet of the convex hull with its vertices followed by NAs until the end of the row.

If the output.options or options argument contains

FA or n, return a list with class convhulln

comprising the named elements:

p

The points passed to convnhulln

hull

The convex hull, represented as a matrix indexing p, as described above

area

If FA is specified, the generalised area of the hull. This is the surface area of a 3D hull or the length of the perimeter of a 2D hull. See ../doc/qhull/html/qh-optf.html#FA.

vol

If FA is specified, the generalised volume of the hull. This is volume of a 3D hull or the area of a 2D hull. See ../doc/qhull/html/qh-optf.html#FA.

normals

If n is specified, this is a matrix hyperplane normals with offsets. See ../doc/qhull/html/qh-opto.html#n.

Arguments

p

An \(M\)-by-\(N\) matrix. The rows of p represent \(M\) points in \(N\)-dimensional space.

options

String containing extra options for the underlying Qhull command; see details below and Qhull documentation at ../doc/qhull/html/qconvex.html#synopsis.

output.options

String containing Qhull options to generate extra output. Currently n (normals) and FA (generalised areas and volumes) are supported; see ‘Value’ for details. If output.options is TRUE, select all supported options.

return.non.triangulated.facets

logical defining whether the output facets should be triangulated; FALSE by default.

Author

Raoul Grasman, Robert B. Gramacy, Pavlo Mozharovskyi and David Sterratt

References

Barber, C.B., Dobkin, D.P., and Huhdanpaa, H.T., “The Quickhull algorithm for convex hulls,” ACM Trans. on Mathematical Software, Dec 1996.

http://www.qhull.org

See Also

intersectn, delaunayn, surf.tri, convex.hull

Examples

## Points in a sphere
ps <- matrix(rnorm(3000), ncol=3)
ps <- sqrt(3)*ps/drop(sqrt((ps^2) %*% rep(1, 3)))
ts.surf <- t(convhulln(ps))  # see the qhull documentations for the options
if (FALSE) {
rgl::triangles3d(ps[ts.surf,1],ps[ts.surf,2],ps[ts.surf,3],col="blue",alpha=.2)
for(i in 1:(8*360)) rgl::view3d(i/8)
}

## Square
pq <- rbox(0, C=0.5, D=2)
# Return indices only
convhulln(pq)
# Return convhulln object with normals, generalised area and volume
ch <- convhulln(pq, output.options=TRUE)
plot(ch)

## Cube
pc <- rbox(0, C=0.5, D=3)
# Return indices of triangles on surface
convhulln(pc)
# Return indices of squares on surface
convhulln(pc, return.non.triangulated.facets=TRUE)