| slider3d {Morpho} | R Documentation |
slides Semilandmarks along curves and surfaces in 3D by minimising bending energy of a thin-plate spline deformation.
Description
slides Semilandmarks along curves and surfaces in 3D. The positions on the surface are sought which minimise bending energy (of a thin-plate spline deformation)
Usage
slider3d(
dat.array,
SMvector,
outlines = NULL,
surp = NULL,
sur.path = NULL,
sur.name = NULL,
meshlist = NULL,
ignore = NULL,
sur.type = "ply",
tol = 1e-05,
deselect = FALSE,
inc.check = TRUE,
recursive = TRUE,
iterations = 0,
initproc = TRUE,
fullGPA = FALSE,
pairedLM = 0,
bending = TRUE,
stepsize = ifelse(bending, 1, 0.5),
mc.cores = parallel::detectCores(),
fixRepro = TRUE,
missingList = NULL,
use.lm = NULL,
smoothnormals = FALSE,
silent = FALSE
)
Arguments
dat.array |
Input k x m x n real array, where k is the number of points, m is the number of dimensions, and n is the sample size. Ideally the dimnames[[3]] vector contains the names of the surface model (without file extension) - e.g. if the model is named "surface.ply", the name of the corresponding matrix of the array would be "surface" |
SMvector |
A vector containing the row indices of (semi-) landmarks on the curve(s) and surfaces 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.path |
Path to the surface models (e.g. ply, obj, stl files) |
sur.name |
character vector: containing the filenames of the corresponding surfaces - e.g. if the dat.array[,,i] belongs to surface_i.ply, sur.name[i] would be surface_i.ply. Only necessary if dat.array does not contain surface names. |
meshlist |
list containing triangular meshes of class 'mesh3d', for
example imported with |
ignore |
vector containing indices of landmarks that are to be ignored. Indices of outlines/surfaces etc will be updated automatically. |
sur.type |
character:if all surfaces are of the same file format and the names stored in dat.array, the file format will be specified here. |
tol |
numeric: Threshold for convergence in the sliding process |
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. |
recursive |
Logical: if TRUE, during the iterations of the sliding process, the outcome of the previous iteration will be used. Otherwise the original configuration will be used in all iterations. |
iterations |
integer: select manually the max. number of iterations that will be performed during the sliding process (usefull, when there is very slow convergence). 0 means iteration until convergence. |
initproc |
requests initial Procrustes fit before sliding. |
fullGPA |
Logical: if FALSE, only a partial procrustes fit will be performed. |
pairedLM |
A X x 2 numeric matrix with the indices of the rows containing paired Landmarks. E.g. the left column contains the lefthand landmarks, while the right side contains the corresponding right hand landmarks. - This will ideally create symmetric mean to get rid of assymetry. |
bending |
if TRUE, bending energy will be minimized, Procrustes distance otherwise. |
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 |
mc.cores |
integer: determines how many cores to use for the computation. The default is autodetect. But in case, it doesn't work as expected cores can be set manually. |
fixRepro |
logical: if |
missingList |
a list of length samplesize containing integer vectors of row indices specifying missing landmars for each specimen. For specimens without missing landmarks enter |
use.lm |
indices specifying a subset of (semi-)landmarks to be used in the rotation step - only used if |
smoothnormals |
logical: if TRUE, tangent planes will be computed from locally smoothed normals |
silent |
logical: if TRUE, console output is suppressed. |
Value
dataslide |
array containing slidden Landmarks in the original space - not yet processed by a Procrustes analysis |
vn.array |
array containing landmark normals |
Warning
Depending on the size of the suface meshes and especially the amount of landmarks this can use an extensive amount of your PC's resources, especially when running in parallel. As the computation time and RAM usage of matrix algebra involved is quadratic to the amount of landmarks used, doubling the amount of semi-landmarks will quadruple computation time and system resource usage. You can easily stall you computer with this function with inappropriate data.
Note
if sur.path = NULL and meshlist = NULL, surface landmarks
are relaxed based on a surface normals approximated by the pointcloud, this can lead to bad results for sparse sets of semilandmarks. Obviously, no projection onto the surfaces will be occur and landmarks will likely be off
the original surface.
Author(s)
Stefan Schlager
References
Klingenberg CP, Barluenga M, and Meyer A. 2002. Shape analysis of symmetric structures: quantifying variation among individuals and asymmetry. Evolution 56(10):1909-1920.
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.
Schlager S. 2012. Sliding semi-landmarks on symmetric structures in three dimensions. American Journal of Physical Anthropology, 147(S52):261. URL: http://dx.doi.org/10.1002/ajpa.21502.
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
Examples
## Not run:
data(nose)
###create mesh for longnose
longnose.mesh <- tps3d(shortnose.mesh,shortnose.lm,longnose.lm,threads=1)
### write meshes to disk
mesh2ply(shortnose.mesh, filename="shortnose")
mesh2ply(longnose.mesh, filename="longnose")
## create landmark array
data <- bindArr(shortnose.lm, longnose.lm, along=3)
dimnames(data)[[3]] <- c("shortnose", "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:nrow(shortnose.lm))[-fix]
slide <- slider3d(data, SMvector=fix, deselect=TRUE, surp=surp,
sur.path=".",iterations=1,mc.cores=1)
# sur.path="." is the current working directory
# now one example with meshes in workspace
meshlist <- list(shortnose.mesh,longnose.mesh)
slide <- slider3d(data, SMvector=fix, deselect=TRUE, surp=surp,
iterations=1, meshlist=meshlist,
mc.cores=1,fixRepro=FALSE)
require(rgl)
## visualize sliding
deformGrid3d(slide$dataslide[,,1],shortnose.lm,ngrid = 0)
## these are fix
spheres3d(slide$dataslide[fix,,1],col=4,radius=0.7)
###finally an example with missing landmarks:
## we assume that coordinates 185:189, 205:209 and 225:229 are in the second config are missing
missingList <- createMissingList(2)
missingList[[2]] <- c(185:189,205:209,225:229)
slideMissing <- slider3d(data, SMvector=fix, deselect=TRUE, surp=surp,
iterations=1, meshlist=meshlist,
mc.cores=1,fixRepro=FALSE,missingList=missingList)
## example with two curves
## Example with surface semilandmarks and two curves
fix <- c(1:5,20:21)
outline1 <- c(304:323)
outline2 <- c(604:623)
outlines <- list(outline1,outline2)
surp <- c(1:623)[-c(fix,outline1,outline2)]
slideWithCurves <- slider3d(data, SMvector=fix, deselect=TRUE, surp=surp,
meshlist=meshlist,iterations=1,mc.cores=1,outlines=outlines)
deformGrid3d(slideWithCurves$dataslide[,,1],shortnose.lm,ngrid = 0)
plot(slideWithCurves)
## finally an example with sliding without meshes by estimating the surface from the
## semi-landmarks
slideWithCurvesNoMeshes <- slider3d(data, SMvector=fix, deselect=TRUE, surp=surp,
iterations=1,mc.cores=1,outlines=outlines)
## compare it to the data with surfaces
deformGrid3d(slideWithCurves$dataslide[,,1],slideWithCurvesNoMeshes$dataslide[,,1],ngrid = 0)
## not too bad, only lonely surface semi-landmarks are a bit off
## End(Not run)