Morpho (version 2.12)

placePatch: Project semi-landmarks from a predefined atlas onto all specimen in a sample

Description

Project semi-landmarks from a predefined atlas onto all specimen in a sample. Various mechanisms are implemented to avoid errorneous placement on the wrong surface layer (e.g. inside the bone).

Usage

placePatch(
  atlas,
  dat.array,
  path,
  prefix = NULL,
  fileext = ".ply",
  ray = TRUE,
  inflate = NULL,
  tol = inflate,
  relax.patch = TRUE,
  keep.fix = NULL,
  rhotol = NULL,
  silent = FALSE,
  mc.cores = 1
)

Value

array containing the projected coordinates appended to the data.array specified in the input. In case dat.array is a matrix only a matrix is returned.

Arguments

atlas

object of class "atlas" created by createAtlas

dat.array

k x 3 x n array containing reference landmarks of the sample or a matrix in case of only one target specimen.

path

character: specify the directory where the surface meshes of the sample are stored.

prefix

character: prefix to the specimens names (stored in dimnames(dat.array)[[3]]) to match the corresponding file names. If dat.array has no dimnames (e.g. because it is a matrix - see example below), this can also be a character vector containing the filenames to which fileext will be appended.

fileext

character: file extension of the surface meshes.

ray

logical: projection will be along surface normals instead of simple closest point search.

inflate

inflate (or deflate - if negative sign) the semilandmarks along the normals of the deformed atlas to make sure that they stay on the outside (inside) of the target mesh.

tol

numeric: threshold to follow the ray back after inflation. See details below. If no surface is hit after tol mm, the simple closest point will be used.

relax.patch

logical: request relaxation minimising bending energy toward the atlas.

keep.fix

integer: rowindices of those landmarks that are not allowed to be relaxed in case relax.patch=TRUE. If not specified, all landmarks will be kept fix. This is preferably set during atlas creation with createAtlas: In case you specified corrCurves on the atlas, you should define explicitly which landmarks (also on the curves) are supposed to fix to prevent them from sliding.

rhotol

numeric: maximum amount of deviation a hit point's normal is allowed to deviate from the normal defined on the atlas. If relax.patch=TRUE, those points exceeding this value will be relaxed freely (i.e. not restricted to tangent plane).

silent

logical: suppress messages.

mc.cores

run in parallel (experimental stuff now even available on Windows). On windows this will only lead to a significant speed boost for many configurations, as all required packages (Morpho and Rvcg) need to be loaded by each newly spawned process.

Author

Stefan Schlager

Details

This function allows the (relatively) easy projection of surface points defined on an atlas onto all surface of a given sample by Thin-Plate Spline deformation and additional mechanisms to avoid distortions. The algorithm can be outlined as followed.

1. relax curves (if specified) against atlas.

2. deform atlas onto targets by TPS based on predefined landmarks (and curves).

3. project coordinates on deformed atlas onto target mesh

4. 'inflate' or 'deflate' configuration along their normals to make sure all coordinates are on the outside/inside

5. Project inflated points back onto surface along these normals.

6. Check if normals are roughly pointing into the same direction as those on the (deformed) atlas.

7. Relax all points against atlas.

8. the predefined coordinates will note change afterwards!

References

Schlager S. 2013. Soft-tissue reconstruction of the human nose: population differences and sexual dimorphism. PhD thesis, Universitätsbibliothek Freiburg. URL: http://www.freidok.uni-freiburg.de/volltexte/9181/.

See Also

createAtlas, relaxLM, checkLM, slider3d, tps3d

Examples

if (FALSE) {
data(nose)
require(rgl)
###create mesh for longnose
longnose.mesh <- tps3d(shortnose.mesh,shortnose.lm,longnose.lm,threads=1)
## create atlas
fix <- c(1:5,20:21)
atlas <- createAtlas(shortnose.mesh, landmarks =
           shortnose.lm[fix,], patch=shortnose.lm[-c(1:5,20:21),])
## view atlas

plotAtlas(atlas)

## create landmark array with only fix landmarks
data <- bindArr(shortnose.lm[fix,], longnose.lm[fix,], along=3)
dimnames(data)[[3]] <- c("shortnose", "longnose")

### write meshes to disk
mesh2ply(shortnose.mesh, filename="shortnose")
mesh2ply(longnose.mesh, filename="longnose")

patched <- placePatch(atlas, data, path="./", inflate=5)
## now browse through placed patches
checkLM(patched, path="./", atlas=atlas)

## same example with only one target specimen
data <- longnose.lm[fix, ]

patched <- placePatch(atlas, data, prefix="longnose", path="./", inflate=5)
wire3d(longnose.mesh,col=3)
spheres3d(patched)
}