| plyPlaneCut {molaR} | R Documentation |
Cut a PLY Mesh Along a Specified Plane
Description
plyPlaneCut permits several different approaches for specifying a cutting plane
and returns either a portion of the original mesh from one side of the plane, or
both portions from each side of the plane stored as separate list elements.
Usage
plyPlaneCut(
plyFile,
axis = "Z",
vertIndex = NA,
keepBoth = FALSE,
plane = NA,
col = "rainbow",
flipAxis = FALSE,
displayNew = TRUE
)
Arguments
plyFile |
An object of class 'mesh3d'. |
axis |
String indicating the axis plane on which to cut the mesh. May be |
vertIndex |
Numeric index of a mesh vertex to define clipping plane. Ignored
if |
keepBoth |
Logical indicating if both sides of the cut mesh should be returned,
defaults to |
plane |
Requires four numeric values specifying the coordinates of the plane normal
(a, b, c) and the "offset" (d). Overrides input for |
col |
Vector indicating the color for vertex drawing when interactively choosing
cutting plane. Defaults to |
flipAxis |
Logical indicating whether or not to reverse the output about the
normal of the plane, defaults to |
displayNew |
Logical indicating whether or not to display the function results
when a value is supplied to either |
Details
plyPlaneCut draws a cutting plane using the parametrization ax + by + cz + d = 0
(Hesse normal form), wherein <a, b, c> constitute the normal to the plane, and d is the
"offset" value. See planes3d for further information. Users can supply
any parameters for a, b, c, and d in the plane argument to produce an arbitrary
cutting plane (see Examples), however the function is designed to aid users in choosing a
cutting plane without foreknowledge of the desired parameters.
When plane is NA, the function will cut the mesh along a plane orthogonal to one of
the primary axes (X, Y, or Z, as indicated by axis) at the location of a focal vertex.
The focal vertex can be defined by its index value, supplied to vertIndex. If no value
is given for either plane or vertIndex, then an interactive 3D window allows the
user to select the focal vertex. A 3D window will open displaying all mesh vertices,
colored according to col, with a semi-transparent mesh surface. The display can be
rotated with the left mouse button and zoomed with the mouse wheel. The right mouse
button allows the user to define a rectangular region in which to identify the focal
vertex. The focal vertex is the vertex in the user-selected region with the minimum value
in the dimension indicated by the axis argument. A preview of the resulting cutting
will be supplied, and for the function to finish users must supply a "Y" or "y"
confirmation to the Cut mesh?: prompt in the terminal. Any other response will
restart the selection process.
The col argument is only invoked when choosing a focal vertex in an interactive 3D
window (i.e., vertIndex and plane are set to NA). This argument will apply any
acceptable color vector to the displayed vertices. Alternatively, users can specify
a color ramp by supplying a string, including: "rainbow", "heat.colors",
"terrain.colors", "topo.colors", "cm.colors", or "gray.colors"; see
hcl.colors and gray.colors for
further details. Color ramps will plot along the axis specified by axis and reverse
if flipAxis = TRUE.
If users prefer that the function is inverted with respect to mesh geometry (i.e., that it
identifies the focal vertex as the maximum value with respect to axis, or that the
resulting mesh be that along the negative normal to the plane), then they should set
flipAxis = TRUE. If keepBoth is enabled, the function will return a list of two
'mesh3d' objects: meshA, and meshB. Enabling keepBoth but providing a plane
that does not intersect the mesh will result in a list with one of the objects set
to NULL (see Examples).
This function can be used to cut meshes representing tooth surfaces so as to retain
only the area of the tooth crown above the lowest point of the occlusal basin. This
cropping procedure is consistent with the one used to prepare surfaces for
measurement of occlusal relief (OR) by Ungar & M'Kirera (2003) "A solution to the
worn tooth conundrum in primate functional anatomy" PNAS 100(7):3874-3877
Unreferenced vertices can cause errors, so users are encouraged to clean their mesh
with molaR_Clean prior to using this function.
Value
An object of class 'mesh3d' corresponding to the portion of the mesh on one side
of the cutting plane. If keepBoth is enabled, a list of two such objects corresponding
to the portions from both sides of the plane.
Examples
# Result from providing plane parameters and keeping meshes from both sides of plane
cutMesh <- plyPlaneCut(Tooth, plane = c(0.5, 0.5, 0.5, -4), keepBoth = TRUE)
open3d()
shade3d(cutMesh$meshA, col = "gray")
wire3d(cutMesh$meshB)
planes3d(0.5, 0.5, 0.5, -4, col = "red", alpha = 0.66)
# Result from providing parameters for a plane that does not intersect the mesh
cutMesh <- plyPlaneCut(Tooth, plane = c(1, 0.75, 0.5, -11))
identical(Tooth, cutMesh)
cutMesh <- plyPlaneCut(Tooth, plane = c(1, 0.75, 0.5, -11), keepBoth = TRUE)
identical(Tooth, cutMesh)