meshDist: calculates and visualises distances between surface meshes or...
In Morpho: Calculations and Visualisations Related to Geometric Morphometrics

meshDist

R Documentation

calculates and visualises distances between surface meshes or 3D coordinates and a surface mesh.

Description

calculates and visualises distances between surface meshes or 3D coordinates and a surface mesh.

Usage

meshDist(x, ...)

## S3 method for class 'mesh3d'
meshDist(
  x,
  mesh2 = NULL,
  distvec = NULL,
  from = NULL,
  to = NULL,
  steps = 20,
  ceiling = FALSE,
  rampcolors = colorRamps::blue2green2red(steps - 1),
  NAcol = "white",
  file = "default",
  imagedim = "100x800",
  uprange = 1,
  ray = FALSE,
  raytol = 50,
  raystrict = FALSE,
  save = FALSE,
  plot = TRUE,
  sign = TRUE,
  tol = NULL,
  tolcol = "green",
  displace = FALSE,
  shade = TRUE,
  method = c("vcglib", "morpho"),
  add = FALSE,
  scaleramp = TRUE,
  threads = 1,
  titleplot = "Distance in mm",
  ...
)

## S3 method for class 'matrix'
meshDist(
  x,
  mesh2 = NULL,
  distvec = NULL,
  from = NULL,
  to = NULL,
  steps = 20,
  ceiling = FALSE,
  rampcolors = colorRamps::blue2green2red(steps - 1),
  NAcol = "white",
  uprange = 1,
  plot = TRUE,
  sign = TRUE,
  tol = NULL,
  tolcol = "green",
  type = c("s", "p"),
  radius = NULL,
  displace = FALSE,
  add = FALSE,
  scaleramp = FALSE,
  titleplot = "Distance in mm",
  ...
)

Arguments

`x`	reference mesh; object of class "mesh3d" or a n x 3 matrix containing 3D coordinates.
`...`	additional arguments passed to `shade3d`. See `material3d` for details.
`mesh2`	target mesh: either object of class "mesh3d" or a character pointing to a surface mesh (ply, obj or stl file)
`distvec`	vector: optional, a vector containing distances for each vertex/coordinate of `x`, if distvec != NULL, `mesh2` will be ignored.
`from`	numeric: minimum distance to be colorised; default is set to 0 mm
`to`	numeric: maximum distance to be colorised; default is set to the maximum distance
`steps`	integer: determines break points for color ramp: n steps will produce n-1 colors.
`ceiling`	logical: if TRUE, the next larger integer of "to" is used
`rampcolors`	character vector: specify the colors which are used to create a colorramp.
`NAcol`	character: specify color for values outside the range defined by `from` and `to`.
`file`	character: filename for mesh and image files produced. E.g. "mydist" will produce the files mydist.ply and mydist.png
`imagedim`	character of type 100x200 where 100 determines the width and 200 the height of the image.
`uprange`	numeric between 0 and 1: restricts "to" to a quantile of "to", if to is NULL.
`ray`	logical: if TRUE, the search is along vertex normals.
`raytol`	maximum distance to follow a normal.
`raystrict`	logical: if TRUE, only outward along normals will be sought for closest points.
`save`	logical: save a colored mesh.
`plot`	logical: visualise result as 3D-plot and distance charts
`sign`	logical: request signed distances. Only meaningful, if mesh2 is specified or distvec contains signed distances.
`tol`	numeric: threshold to color distances within this threshold green.
`tolcol`	a custom color to color vertices below a threshold defined by `tol`. Default is green.
`displace`	logical: if TRUE, displacement vectors between original and closest points are drawn colored according to the distance.
`shade`	logical: if FALSE, the rendering of the colored surface will be supressed.
`method`	accepts: "vcglib" and "morpho" (and any abbreviation). vcglib uses a command line tool using vcglib headers, morpho uses fortran routines based on a kd-tree search for closest triangles.
`add`	logical: if TRUE, visualization will be added to the rgl window currently in focus
`scaleramp`	logical: if TRUE, the colorramp will be symmetrical for signed distances: spanning from `-max(from,to)` to `max(from,to)`.
`threads`	integer: number of threads to use. 0 = let system decide.
`titleplot`	character: axis description of heatmap.
`type`	character: "s" shows coordinates as spheres, while "p" shows 3D dots.
`radius`	determines size of spheres; if not specified, optimal radius size will be estimated by centroid size of the configuration.

Details

calculates the distances from a mesh or a set of 3D coordinates to another at each vertex; either closest point or along the normals

Value

Returns an object of class "meshDist" if the input is a surface mesh and one of class "matrixDist" if input is a matrix containing 3D coordinates.

`colMesh`	object of mesh3d with colors added
`dists`	vector with distances
`cols`	vector with color values
`params`	list of parameters used

Author(s)

Stefan Schlager

References

Detection of inside/outside uses the algorithm proposed in:

Baerentzen, Jakob Andreas. & Aanaes, H., 2002. Generating Signed Distance Fields From Triangle Meshes. Informatics and Mathematical Modelling, .

Examples


data(nose)##load data
##warp a mesh onto another landmark configuration:
longnose.mesh <- tps3d(shortnose.mesh, shortnose.lm, longnose.lm,threads=1)
## Not run: 
mD <- meshDist(longnose.mesh, shortnose.mesh)
##now change the color ramp
render(mD,rampcolors = c("white","red"))

## End(Not run)
#use unsigned distances and a ramp from blue to red
#color distances < 0.01 green:
## Not run: 
meshDist(longnose.mesh, shortnose.mesh, rampcolors = c("blue", "red"),sign=FALSE, tol=0.5)

## End(Not run)

Morpho documentation built on June 22, 2024, 7:19 p.m.