alignLandmarksToMidline: Aligns bilateral landmarks to the midline plane

In aaronolsen/StereoMorph: Stereo Camera Calibration and Reconstruction

Aligns bilateral landmarks to the midline plane

Description

This function aligns a set of bilateral landmarks to the midline plane. Midline landmarks and the mean position of bilateral landmarks are both used to define the midline plane.

Usage

	
alignLandmarksToMidline(lm.matrix, left = '(_l[_]?|_left[_]?)([0-9]*$)', 
                        right = '(_r[_]?|_right[_]?)([0-9]*$)',
                        left.remove = '\\2', right.remove = '\\2', 
                        use = rep(TRUE, dim(lm.matrix)[1]), average = FALSE)

## S3 method for class 'alignLandmarksToMidline'
summary(object, ...)

Arguments

lm.matrix	a 2D or 3D matrix with landmark names as row names.
left	a regular expression to identify left landmarks in the row names of lm.matrix.
right	a regular expression to identify right landmarks in the row names of lm.matrix.
left.remove	an expression for input to the gsub() function indicating which element of left in parentheses should be removed to create a landmark name that is not side-specific (see "Details").
right.remove	an expression for input to the gsub() function indicating which element of right in parentheses should be removed to create a landmark name that is not side-specific (see "Details").
use	a vector of TRUE or FALSE values of the same length as the number of landmarks to specify which landmarks will be used in aligning to the midline. Default is that all landmarks are used.
average	Whether to average left and right landmarks after alignment. Can be left false if landmarks previously reflected with average equal to TRUE (see reflectMissingLandmarks).
object	a list of class "alignLandmarksToMidline" (output of this function).
...	further arguments passed to or from other methods.

Details

Currently, the function only accepts left/right designations by matching a regular expression to the landmark name. This is preferable in that it allows for easier match up between bilateral landmarks (based on their common name without a side annotation). The default regular expression identifies left landmarks by a name ending in "_L", "_l", "_left" or "_LEFT", optionally followed by numbers. For example, "hamulus_left", "hamulus_L" and "zymgomatic_arch_l012" would all be identified as landmarks on the left side. Similarly, "hamulus_right", "hamulus_R" and "zymgomatic_arch_r012" would all be identified as landmarks on the right side. Landmarks not identified as left or right are assumed to fall on the midline.

In order to find corresponding left and right landmarks, the function requires the left.remove and right.remove arguments. The left.remove and right.remove arguments are passed to the base function gsub() as the replacement argument. This is used to generate a landmark name that is not side-specific. For example, "hamulus_left" and "zymgomatic_arch_l012" would become "hamulus" and "zymgomatic_arch012". These will be reverted to their original names at return.

Once corresponding right and left landmarks have been identified, the function finds the mean positions of all bilateral landmarks and the positions of all midline landmarks. These points are used to define the midline. After alignment, the specimen will have the midline axis as the last column (z in 3D, y in 2D), the longest non-midline axis as the first column (x in 3D), and the second non-midline axis as y for 3D. No further rotation and reflection is done, therefore the specimen may be facing any direction along each of the axes.

This function returns the aligned landmarks and an error vector, midline.error. This is a vector of the squared z-coordinate of the midline landmarks (the distance between each midline landmark and the midline plane). If reflectMissingLandmarks was called on the landmarks prior to alignLandmarksToMidline() with average equal to TRUE, then all of the midline points will fall exactly along the midline. Thus, the error vector will consist entirely of zeros (or near-zero values).

Value

a list of class "alignLandmarksToMidline" with the following elements:

lm.matrix	a 2D or 3D matrix of landmarks aligned to the midline.
midline.error	a vector of the errors (distances) between each midline landmark and the midline plane.

Note

This function was modified by A Olsen from the R function AMP() written by A Haber.

Author(s)

Annat Haber, Aaron Olsen

See Also

readLandmarksToMatrix

Examples

## FIND THE FILE DIRECTORY FOR EXTRA R PACKAGE FILES
fdir <- paste0(path.package("StereoMorph"), "/extdata/")

## GET LANDMARKS
file <- paste0(fdir, "lm_3d_unify.txt")

## LOAD FILES INTO A MATRIX
lm.matrix <- readLandmarksToMatrix(file=file, row.names=1)

## ALIGN TO MIDLINE
align_landmarks <- alignLandmarksToMidline(lm.matrix=lm.matrix)

## PRINT SUMMARY OF ERRORS
print(summary(align_landmarks))

aaronolsen/StereoMorph documentation built on June 2, 2022, 4:09 a.m.