deform-mesh

Synopsis

deform-mesh <input> <output> [options]

Description

Iteratively minimizes a deformable surface model energy functional. The gradient of the energy terms are the internal and external forces of the deformable surface model.

Input options

-initial <file>

Point set used to initialize the deformed output mesh. Usually the output of a previous optimization with possibly saved node status (see -save-status). (default: input)

-dof <type> [<dx> [<dy> <dz>]]

Optimize spatial transformation of named <type> to deform the mesh points. The optional <dx>, <dy>, and <dz> arguments specify the control point spacing of free-form deformation (FFD) transformations. Common transformation types are:

  • FFD: Cubic B-spline FFD.
  • SVFFD: Stationary velocity (SV) cubic B-spline FFD.
-image <file>

Intensity image on which external forces are based. (default: none)

-distance-image, -dmap <file>

Euclidean distance image on which implicit surface forces are based. (default: none)

-distance-offset, -dmap-offset <value>

Implicit surface isovalue of -distance-image. (default: 0)

-mask <file>

Mask defining region in which external forces are non-zero. (default: none)

-padding <value>

Padding/Background value of input -image. (default: none)

-inflate-brain

Set default parameters of cortical surface inflation process equivalent to FreeSurfer’s mris_inflate command.

Optimization options

-optimizer <name>

Optimization method used to minimize the energy of the deformable surface model:

  • EulerMethod: Forward Euler integration (default)
  • EulerMethodWithDamping: Forward Euler integration with momentum.
  • EulerMethodWithMomentum: Forward Euler integration with momentum.
  • GradientDescent: Gradient descent optimizer.
  • ConjugateGradientDescent: Conjugate gradient descent.

Line search method used by gradient descent optimizers:

  • Adaptive: Line search with adaptive step length. (default)
  • Brent: Brent’s line search method.
-damping <value>

Damping ratio used by Euler method with momentum modelling the effect of dissipation of kinetic energy.

-momentum <value>

Momentum of Euler method with momentum, i.e., \(1 - damping\) (see -damping)

-mass <value>

Node mass used by Euler methods with momentum. (default: 1)

-levels <max> | <min> <max>

Perform optimization on starting at level <max> until level <min> (> 0). When only the <max> level argument is given, the <min> level is set to 1. On each level, the node forces are averaged \(2^{level-1}\) times which is similar to computing the forces on a coarser mesh. See -force-averaging. (default: 0 0)

-force-averaging <n>...

Number of force averaging steps. (default: 0) Cannot be combined with -magnitude-averaging.

-magnitude-averaging <n>...

Number of force magnitude averaging steps. (default: 0) Cannot be combined with -force-averaging.

-distance-averaging <n>...

Number of -distance force averaging steps. (default: 0)

-steps, -max-steps, -iterations, -max-iterations <n>...

Maximum number of iterations. (default: 100)

-step, -dt <value>...

Length of integration/gradient steps. (default: 1)

-max-dx, -maxdx, -dx <value>...

Maximum displacement of a node at each iteration. By default, the node displacements are normalized by the maximum node displacement. When this option is used, the node displacements are clamped to the specified maximum length instead. (default: -step)

-max-displacement <value>

Maximum distance from input surface. (default: +inf)

-remesh <n>

Remesh surface mesh every n-th iteration. (default: 0)

-remesh-adaptively

Remesh surface mesh using an adaptive edge length interval based on local curvature of the deformed surface mesh or input implicit surface (-distance-image).

-triangle-inversion, -notriangle-inversion

Whether to allow inversion of pair of triangles during surface remeshing. (default: on)

-min-edgelength <value>...

Minimum edge length used for local adaptive remeshing. (default: -1)

-max-edgelength <value>...

Maximum edge length used for local adaptive remeshing. (default: -1)

-min-angle <degrees>...

Minimum angle between edge node normals for an edge be excluded from collapsing during iterative -remesh operations. (default: 180)

-max-angle <degrees>...

Maximum angle between edge node normals for an edge be excluded from splitting during iterative -remesh operations. (default: 180)

-lowpass <n>

Low-pass filter surface mesh every n-th iteration. (default: 0)

-lowpass-iterations <n>

Number of -lowpass filter iterations. (default: 100)

-lowpass-band <band>

Low-pass filtering band argument, usually in the range [0, 2]. (default: 0.75)

-nointersection

Hard non-self-intersection constraint for surface meshes. (default: off)

-mind, -min-distance <value>

Minimum distance to other triangles in front of a given triangle.

-minw, -min-width <value>

Minimum distance to other triangles in the back of a given triangle.

-max-collision-angle <degrees>

Maximum angle between vector connecting centers of nearby triangles and the face normal of the reference triangle for a collision to be detected. When the triangles are within the same flat neighborhood of the surface mesh, this angle will be close to 90 degrees. This parameter reduces false collision detection between neighboring triangles. (default: 45)

-fast-collision-test

Use fast approximate triangle-triangle collision test based on distance of their centers only. (default: off)

-reset-status

Set status of all mesh nodes to active again after each level (see -levels). (default: off)

Deformable model options

-neighborhood <n>

Size of node neighborhoods used by internal force terms that consider more than only the adjacent nodes, but also up to n-connected nodes. (default: 2)

-distance <w>

Weight of implicit surface distance. (default: 0)

-distance-measure <name>

Implicit surface distance measure used by -distance:

  • minimum: Minimum surface distance (see -distance-image, default)
  • normal: Estimate distance by casting rays along normal direction.
-balloon-inflation, -balloon <w>

Weight of inflation force based on local intensity statistics. (default: 0)

-balloon-deflation <w>

Weight of deflation force based on local intensity statistics. (default: 0)

-balloon-min <intensity>

Global lower intensity threshold for -balloon-inflation or -balloon-deflation. (default: -inf)

-balloon-max <intensity>

Global upper intensity threshold for -balloon-inflation or -balloon-deflation. (default: +inf)

-balloon-range <min> <max>

Global intensity thresholds for -balloon-inflation or -balloon-deflation. (default: [-inf +inf])

-balloon-radius <r>

Radius for local intensity statistics of -balloon-inflation or -balloon-deflation. (default: 7 times voxel size)

-balloon-sigma <sigma>

Local intensity standard deviation scaling factor of -balloon-inflation or -balloon-deflation. (default: 5)

-balloon-mask <file>

Image mask used for local intensity statistics for -balloon-inflation or -balloon-deflation. (default: interior of deformed surface)

-edges <w>

Weight of image edge force. (default: 0)

-edge-distance <w>

Weight of closest image edge distance force. (default: 0)

-inflation <w>

Weight of surface inflation force used for cortical surface inflation. (default: 0)

-bending-energy <w>

Weight of bending energy of -dof transformation. (default: 0)

-spring <w>

Weight of internal spring force. (default: 0)

-normal-spring, -nspring <w>

Weight of internal spring force in normal direction. (default: 0)

-tangential-spring, -tspring <w>

Weight of internal spring force in tangent plane. (default: 0)

-normalized-spring <w>

Weight of internal spring force normalized w.r.t. force in normal direction. (default: 0)

-curvature <w>

Weight of surface curvature. (default: 0)

-quadratic-curvature, -qcurvature <w>

Weight of surface curvature estimated by quadratic fit of node neighbor to tangent plane distance. (default: 0)

-distant-quadratic-curvature, -distant-qcurvature <w>

Weight of -quadratic-curvature proportional to the -distance magnitude. (default: 0)

-mean-curvature, -mcurvature <w>

Weight of mean curvature constraint. (default: 0)

-distant-mean-curvature, -distant-mcurvature <w>

Weight of -mean-curvature proportional to the -distance magnitude. (default: 0)

-gauss-curvature, -gcurvature <w>

Weight of Gauss curvature constraint. (default: 0)

-distant-gauss-curvature, -distant-gcurvature <w>

Weight of -gauss-curvature proportional to the -distance magnitude. (default: 0)

-distortion <w>

Weight of metric distortion.

-stretching <w>

Weight of spring force based on difference of neighbor distance compared to initial distance. (default: 0)

-repulsion <w>

Weight of node repulsion force. (default: 0)

-repulsion-radius <r>

Radius of node repulsion force. (default: average edge length)

-repulsion-distance <r>

Frontface radius of node repulsion force. (default: average edge length)

-repulsion-width <r>

Backface radius of node repulsion force. (default: average edge length)

-collision <w>

Weight of triangle repulsion force.

-normal <w>

Constant force along outwards normal direction (positive weight) or inwards normal direction (negative weight).

Stopping criterion options

-extrinsic-energy

Consider only sum of external energy terms as total energy value of deformable model functional. Internal forces still contribute to the gradient of the functional, but are excluded from the energy function value (see -epsilon and -min-energy). (default: off)

-epsilon <value>

Minimum change of deformable surface energy convergence criterion.

-delta <value>...

Minimum maximum node displacement or -dof parameter value. (default: 1e-6)

-min-energy <value>

Target deformable surface energy value. (default: 0)

-min-active <ratio>...

Minimum ratio of active nodes in [0, 1]. (default: 0)

-inflation-error <threshold>

Threshold of surface inflation RMS measure. (default: off)

Output options

-track [<name>]

Record sum of node displacements along normal direction. The integrated displacements are stored in the point data array named “NormalDisplacement” by default or with the specified <name>. (default: off)

-track-zero-mean [<name>]

Same as -track, but subtract mean from tracked values. This option is implicit when -inflate-brain is given to inflate a cortical brain surface. The default output array name is “SulcalDepth”. Otherwise, the default point data array name is “NormalDisplacementZeroMean”. (default: off)

-track-zero-median [<name>]

Same as -track, but subtract median from tracked values. The default point data array name is “NormalDisplacementZeroMedian”. (default: off)

-track-unit-variance [<name>]

Same as -track, but divide tracked values by their standard deviation. The default point data array name is “NormalDisplacementUnitVariance”. (default: off)

-track-zvalues [<name>]

Same as -track, but subtract mean from tracked values and divide by standard deviation. The resulting values are the Z-score normalized standard scores of the tracked displacements. The default point data array name is “NormalDisplacementZValues”. (default: off)

-track-zero-median-zvalues [<name>]

Same as -track, but subtract median from tracked values and divide by standard deviation. It can be used with -inflate-brain to obtain a normalized curvature measure. The default point data array name is “NormalDisplacementZeroMedianZValues”. (default: off)

-track-without-momentum

When tracking the total displacement of a node in normal direction using the EulerMethodWithMomentum -optimizer as used in particular by -inflate-brain, exclude the momentum from the. tracked displacement. This is idential to FreeSurfer’s mrisTrackTotalDisplacement used for the curvature output of mris_inflate. The correct curvature value is, however, obtained by including the momentum component as it integrates the actual amount by which each node is displaced during the Euler steps. Not using this option corresponds to the mrisTrackTotalDisplacementNew function. (default: off)

-notrack

Do not track node displacements along normal direction.

-center-output

Center output mesh such that center is at origin. (default: off)

-match-area

Scale output mesh by ratio of input and output surface area. (default: off)

-match-sampling

Resample output mesh at corresponding positions of input mesh. This option is only useful in conjunction with -remesh. (default: off)

-save-status

Save node status (active/passive) to output file. (default: off)

-ascii | -nobinary

Write legacy VTK in ASCII format. (default: off)

-binary | -noascii

Write legacy VTK in binary format. (default: on)

-compress, -nocompress

Write XML VTK file with or without compression. (default: on)

-debug-prefix <prefix>

File name prefix for -debug output. (default: deform_mesh_)

-debug-interval <n>

Write -debug output every n-th iteration. (default: 10)

-level-prefix, -nolevel-prefix

Write -debug output without level prefix in file names. (default: on)

Advanced options

-par <name> <value>

Advanced option to set surface model or optimizer parameter.

Standard options

-v, -verbose [n]

Increase/Set verbosity of output messages. (default: 1)

-debug [level]

Increase/Set debug level for output of intermediate results. (default: 0)

-version [major.minor]

Print version and exit or set version to emulate.

-revision

Print revision (or version) number only and exit.

-h, -help

Print help and exit.

Terminal options

-color, -nocolor

Enable/disable colored output. (default: off)

Parallelization options

-threads <n>

Use maximal <n> threads for parallel execution. (default: automatic)