unifyLandmarks: Optimally align a set of partial landmark sets

In StereoMorph: Stereo Camera Calibration and Reconstruction

Optimally align a set of partial landmark sets

Description

This function aligns two or more landmark sets using shared points. Corresponding landmarks are identified by matching row names. The function selects a sequence of alignments that minimizes the step-wise alignment error.

Usage

unifyLandmarks(lm.array, min.common = dim(lm.array)[2], return.on.error = FALSE)

## S3 method for class 'unifyLandmarks'
summary(object, print.tab = '', verbose = TRUE, ...)

Arguments

lm.array	an array of 2D or 3D landmark matrices. These can be read in from a file or files using readLandmarksToArray.
min.common	a minimum number of landmarks to use in the alignment. Must be greater than dim(lm.array)[2].
return.on.error	Logical whether to return NULL if there are an insufficient common points for unification.
object	a list of class "unifyLandmarks" (the output of unifyLandmarks()).
print.tab	Tabs preceding lines printed to console.
verbose	Logical whether to print full error report.
...	further arguments passed to or from other methods.

Details

The input lm.array should be an array of 2D or 3D landmark matrices with row names, such as created by readLandmarksToArray. The first two dimensions of lm.array correspond to the rows and columns of each matrix, respectively. The last dimension of lm.array corresponds to each separate landmark matrix.

unifyLandmarks() first aligns all pair combinations of landmark sets that share the minimum number of points specified by min.common. The two sets that align with the lowest root-mean-square (RMS) error are aligned and the mean positions of all points saved. If there are additional landmark sets, unifyLandmarks() aligns each of these with the combined matrix, again identifying the set that aligns with the least RMS error. The alignment with the least error is saved as the new combined landmark matrix. This is repeated for each remaining landmark set, sequentially aligning remaining landmark sets to the combined landmark matrix.

To align two 2D landmark sets, the sets must share at least two landmarks and to align two 3D landmark sets, the sets must share at least three landmarks. These are the default minimum number of points for alignment. A greater number of common points can be specified using the min.common parameter. Additionally, in the 3D case, these landmarks must not be collinear. If lm.array contains more than two landmark matrices, it is not necessarily required that each landmark set share these minimum number of points with every other landmark set. For example, it may be that two landmark sets do not each separately share the minimum number of landmarks required for alignment with a third landmark set. But if these two landmark sets are combined, they may then share the required number of landmarks with the third set. During each alignment step, unifyLandmarks() skips pairs of matrices that do not share the required number of landmarks. As long as there is some combination of alignments that provide a sufficient number of shared landmarks, all landmark sets can be combined into a single matrix.

If an array consisting of only one landmark matrix is input, the matrix is returned without an alignment operation.

Value

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

lm.matrix	a 2D or 3D landmark matrix.
unify.seq	a vector of the order in which landmark sets were aligned.
unify.error	a matrix of the alignment error for each shared landmark for each alignment (the number of sets minus one).
unify.rmse	a vector of the root-mean-square error of each alignment (the number of sets minus one).

Note

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

Author(s)

Annat Haber, Aaron Olsen

References

Rohlf, F.J. (1990) "Chapter 10. Rotational fit (Procrustes) Methods." Proceedings of the Michigan Morphometrics Workshop. Ed. F. James Rohlf and Fred L. Bookstein. The University of Michigan Museum of Zoology, 1990. 227–236. Info page at lib.umich.edu

See Also

findOptimalPointAlignment

Examples

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

## SET LANDMARK FILES
file <- paste0(fdir, "lm_3d_even_a", 1:3, ".txt")

## READ LANDMARKS INTO ARRAY
lm.array <- readLandmarksToArray(file, row.names=1)

## UNIFY LANDMARKS
unify_lm <- unifyLandmarks(lm.array)

## PRINT UNIFICATION SUMMARY
print(summary(unify_lm))

StereoMorph documentation built on May 25, 2022, 5:06 p.m.