Morpho (version 2.12)

relaxLM: relax one specific landmark configuration against a reference

Description

relax one specific landmark configuration against a reference (e.g. a sample mean)

Usage

relaxLM(lm, ...)
# S3 method for matrix
relaxLM(
  lm,
  reference,
  SMvector,
  outlines = NULL,
  surp = NULL,
  sur.name = NULL,
  mesh = NULL,
  tol = 1e-05,
  deselect = FALSE,
  inc.check = TRUE,
  iterations = 0,
  fixRepro = TRUE,
  missing = NULL,
  bending = TRUE,
  stepsize = ifelse(bending, 1, 0.5),
  use.lm = NULL,
  silent = FALSE,
  ...
)
# S3 method for mesh3d
relaxLM(
  lm,
  reference,
  tol = 1e-05,
  deselect = FALSE,
  inc.check = TRUE,
  iterations = 0,
  fixRepro = TRUE,
  missing = NULL,
  bending = FALSE,
  stepsize = ifelse(bending, 1, 0.5),
  use.lm = NULL,
  silent = FALSE,
  ...
)

Value

returns kx3 matrix of slidden landmarks

Arguments

lm

k x 3 or k x 2 matrix containing landmark data to be slidden - or a triangular mesh of class "mesh3d". See details

...

additonal arguments - currently unused

reference

k x 3 or k x 2 matrix containing landmark of the reference, or a mesh with the same amount of vertices as there are landmarks in lm.

SMvector

A vector containing the row indices of (semi-) landmarks on the curve(s) that are allowed to slide

outlines

A vector (or if threre are several curves) a list of vectors (containing the rowindices) of the (Semi-)landmarks forming the curve(s) in the successive position on the curve - including the beginning and end points, that are not allowed to slide.

surp

integer vector containing the row indices of semi-landmarks positioned on surfaces.

sur.name

character: containing the filename of the corresponding surface.When specified, mesh has to be NULL. If sur.name=NULL and mesh=NULL, the tangent planes will be estimated from the point cloud.

mesh

triangular mesh of class "mesh3d" loaded into the R workspace, when specified, "sur.name" has to be NULL.

tol

numeric: Threshold for convergence in the sliding proces. Full Procrustes distance between actual result and previous iteration.

deselect

Logical: if TRUE, the SMvector is interpreted as those landmarks, that are not allowed to slide.

inc.check

Logical: if TRUE, the program stops when convergence criterion starts increasing and reports result from last iteration.

iterations

integer: maximum amounts the algorithm runs - even when 'tol' is not reached. When iterations=0, the algorithm runs until convergence.

fixRepro

logical: if TRUE, fix landmarks will also be projected onto the surface. If you have landmarks not on the surface, select fixRepro=FALSE

missing

vector of integers, specifying row indices of missing (semi-)landmarks. They will be relaxed freely in 3D and not projected onto the target (works only for 2D data).

bending

if TRUE, bending energy will be minimized, Procrustes distance otherwise (not suggested with large shape differences)

stepsize

integer: dampening factor for the amount of sliding. Useful to keep semi-landmarks from sliding too far off the surface. The displacement is calculated as \(\Upsilon = \Upsilon^0 + stepsize * UT\). Default is set to 1 for bending=TRUE and 0.5 for bending=FALSE.

use.lm

indices specifying a subset of (semi-)landmarks to be used in the rotation step - only used if bending=FALSE.

silent

logical: if TRUE, console output is suppressed.

Author

Stefan Schlager

Details

if lm is a surface mesh, all vertices will be treated as semilandmarks and a allowed to freely slide along the surface.

References

Gunz, P., P. Mitteroecker, and F. L. Bookstein. 2005. Semilandmarks in Three Dimensions, in Modern Morphometrics in Physical Anthropology. Edited by D. E. Slice, pp. 73-98. New York: Kluwer Academic/Plenum Publishers.

See Also

slider3d

Examples

require(rgl)
data(nose)
### relax shornose against longnose

# define fix landmarks
fix <- c(1:5,20:21)
# define surface patch by specifying row indices of matrices
# all except those defined as fix
surp <- c(1:dim(shortnose.lm)[1])[-fix]
 
relax <- relaxLM(shortnose.lm,
         longnose.lm, mesh=shortnose.mesh, iterations=1,
         SMvector=fix, deselect=TRUE, surp=surp)

## example minimizing Procrustes distance when displacement is not
## dampened by stepsize
relaxProcD <- relaxLM(shortnose.lm,
         longnose.lm, mesh=shortnose.mesh, iterations=1,
         SMvector=fix, deselect=TRUE, surp=c(1:623)[-fix],bending=FALSE,stepsize=1)

if (FALSE) {
# visualize differences red=before and green=after sliding
deformGrid3d(shortnose.lm, relax, ngrid=0)

 
# visualize differences minimizing Procrusted distances red=before and green=after sliding

deformGrid3d(shortnose.lm, relaxProcD, ngrid=0)
## no smooth displacement, now let's check the distances:
rot2ref <- rotonto(relaxProcD,longnose.lm)
angle.calc(rot2ref$X,rot2ref$Y)
# 0.2492027 Procrustes distance between reference and slided shape
# (minimizing Procrustes distance)
rot2refBend <- rotonto(relax,longnose.lm)
angle.calc(rot2refBend$X,rot2refBend$Y)
# 0.2861322 Procrustes distance between reference and slided shape
# (minimizing bending energy)

rot2refOrig <- rotonto(shortnose.lm,longnose.lm)
angle.calc(rot2refOrig$X,rot2refOrig$Y)
# 0.3014957 Procrustes distance between reference and original shape
##result: while minimizing Procrustes distance, displacement is not
##guaranteed to be smooth

# add surface
wire3d(shortnose.mesh, col="white")


## finally relax two meshes with corresponding vertices:

mediumnose.mesh <- tps3d(shortnose.mesh,shortnose.lm, (shortnose.lm+longnose.lm)/2,threads=1)
## we use Procrustes distance as criterion as bending energy is pretty slow because
## of too many coordinates (more than 3000 is very unreasonable).
relaxMesh <- relaxLM(shortnose.mesh,mediumnose.mesh,iterations=2,bending=FALSE,stepsize=0.05)
}