| buildtemplate {geomorph} | R Documentation |
Build 3D surface template
Description
An interactive function to build a template for the digitization across
specimens 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, center = TRUE, surface.sliders, ptsize = 1)
Arguments
spec |
An object of class shape3d/mesh3d, or matrix of 3D vertex coordinates |
fixed |
Either a numeric value designating the number of fixed landmarks to be selected by |
center |
Should the object 'spec' be centered prior to digitizing? |
surface.sliders |
The number of desired surface sliders |
ptsize |
Size of mesh points (vertices), e.g. 0.1 for dense meshes, 3 for sparse meshes |
Details
Function constructs a template of surface slider semilandmarks. If desired, the user can simultaneously
digitize the fixed points (see digitizing below), however these may have been previously digitized separately
using digit.fixed.
The function finds surface semilandmarks, chosen automatically from the mesh at roughly equal distances, using the nearest-neighbor algorithm outlined in Gunz et al. (2005) and Mitteroecker and Gunz (2009).
The set of fixed and surface slider landmarks are saved in the working directory as a txt file named "template".
This file will then be used to extract a set of similarly numbered surface semilandmarks on subsequent specimens
using the function digitsurface. Because template matching is based on the correspondence of fixed
landmark points in the template and the target specimen, a minimum of four fixed landmarks must be used. However,
to ensure a strong match between the scan and the template, it is recommended that a
higher number of fixed points is used.
For more details see the vignette: vignette("geomorph.digitize3D").
NOTE: Function centers the mesh before digitizing by default (center = TRUE). If one chooses not to center, the specimen may be difficult to manipulate in the rgl window.
Digitizing
Digitizing of fixed landmarks is interactive. 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.
Value
The 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.
The function also returns to the console an n x 3 matrix containing the x,y,z coordinates of the
digitized landmarks.
Author(s)
Erik Otarola-Castillo & Emma Sherratt
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.