buildtemplate: Build 3D surface template

Description

An interactive function to build template of three-dimensional (3D) surface sliding semilandmarks. Input for the function is either a matrix of vertex coordinates defining a 3D surface object or a mesh3d object as obtained from read.ply.

Usage

buildtemplate(spec, fixed, surface.sliders, ptsize = 1, center = TRUE)

Arguments

spec

Name of surface file, as either an object of class shape3d/mesh3d, or matrix of three-dimensional vertex coordinates.

fixed

numeric Either: a single value designating the number of fixed template landmarks to be selected by digit.fixed, OR a p-x-k matrix of 3D coordinates collected previously

surface.sliders

numeric: The number of template surface sliders desired

ptsize

numeric: Size to plot the mesh points (vertices), e.g. 0.1 for dense meshes, 3 for sparse meshes

center

Logical Whether the object 'spec' should be centered prior to digitizing (default {center=TRUE})

Value

Function writes to the working directory three files: an NTS file with the name of the specimen and .nts suffix containing the landmark coordinates, "template.txt" containing the same coordinates for use with the function digitsurface, and "surfslide.csv", a file containing the address of the landmarks defined as "surface sliders" for use with gpagen. Function also returns to console an n x 3 matrix containing the x,y,z coordinates of the digitized landmarks.

Details

Function constructs a template of fixed landmarks and n "surface sliders", semilandmarks that slide over a surface. The user digitizes the fixed points (see digitizing below), then the function finds n surface semilandmarks following algorithm outlined in Gunz et al. (2005) and Mitteroecker and Gunz (2009). Surface semilandmarks are roughly equidistant set of predetermined number of points, chosen over the mesh automatically using a nearest-neighbor approach. The set of fixed and surface slider landmarks are exported as a "template", which is used to extract a set of similarly numbered landmarks on every specimen using function digitsurface. Some of the "fixed" landmarks can be later designated as "curve sliders" using function define.sliders.3d if required - see details in digit.fixed. Because template matching is based on the correspondence of fixed landmark points in the template and the specimen, a minimum of four fixed landmarks must be used. To ensure a strong match between the scan and the template, it is recommended that a reasonable number of fixed points be used. These fixed points can be designated as "curve sliders" later using function define.sliders.3d, see the function digit.fixed for details. NOTE: Function centers the mesh before digitizing by default (center=TRUE). If one chooses not to center, specimen may be difficult to manipulate in rgl window. Digitizing{ Digitizing using buildtemplate is interactive between landmark selection using a mouse (see below for instructions), and the R console. Once a point is selected, the user is asked if the system should keep or discard the selection #'(y/n). If "y", the user is asked to continue to select the next landmark. If "n" the removes the last chosen landmark, and the user is asked to select it again. This can be repeated until the user is comfortable with the landmark chosen. To digitize with a standard 3-button (PC):

the RIGHT mouse button (primary) to select points to be digitized,
the LEFT mouse button (secondary) is used to rotate mesh,
the mouse SCROLLER (third/middle) is used to zoom in and out.

NOTE: Digitizing functions on MACINTOSH computers using a standard 3-button mice works as specified. Macs using platform specific single button mice, XQuartz must be configured: go to Preferences > Input > tick "Emulate three button mouse":

press button to rotate 3D mesh,
press button while pressing COMMAND key to select vertex to be used as a landmark),
press button while pressing OPTION key to adjust mesh perspective.
the mouse SCROLLER or trackpad two finger scroll is used to zoom in an out.

NOTE: there is no pan (translate) functionality in rgl library for all platforms at this time. The template can be edited using function editTemplate. } AUTO mode{ The function as described above (for interactive mode) calls digit.fixed, prompting the user to select fixed landmarks in the rgl window. However if the user has digitized these fixed landmark elsewhere (e.g., in other software), then the input for parameter 'fixed' can be a p-x-k matrix of 3D coordinates. In this case, the function will automatically use these landmarks to build the template of sliding semilandmarks. }

References

Gunz P, Mitteroecker P, & Bookstein FJ (2005) Semilandmarks in Three Dimensions. Modern Morphometrics in Physical Anthropology, ed Slice DE (Springer-Verlag, New York), pp 73-98. Mitteroecker P & Gunz P (2009) Advances in Geometric Morphometrics. Evolutionary Biology 36(2):235-247.