Variational Polygonal/Polyhedral Shape Functions (Version 2.51)

links executables usage compilation changes

This software supports finite-elements-type calculations over polygonal and polyhedral meshes. Supported applications include:

Simulation of deformable solids (with linear elasticity) in 2D and 3D,
Solution of the Franke test in 2D and 3D,
Calculation of Geodesics in Heat on polygonal meshes, and
Gradient domain processing of signals on polygonal meshes.

LINKS

Papers:

[Bunge, Herholz, Sorkine-Hornung, Botsch, and Kazhdan, 2022]

[Crane, Weischedel, and Wardetzky, 2013]

Executables:

Source Code:

Data:

Older Versions:

EXECUTABLES

--in <input polygonal/polyhedral mesh>: This string specifies the the name of the mesh.
For 2D simulations, the input polygonal mesh is assumed to be in PLY format, giving the set of vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z and the set of polygons encoded by a list of vertex indices.
For 3D simulations, the input polyhedral mesh is assumed to be in OVM format.
[--xForm <linear transform>]: This 2x2 (resp. 3x3) set of floating point values describes the entries of the linear transformation initially applied to the solid.
The default values spcify the identity transformation.
[--lock]: If enabled, this flag specifies that the values on the y-axis (resp. yz-plane) should be locked during the course of the animation.
[--gravity <gravitational force>]: This floating point value describes the force of gravity acting on the solid. (Note that without the --lock parameter, using a non-zero value for gravity will have the solid fall off the screen.)
The default value for this parameter is -500,000,000.
[--mg]: If enabled, this flag specifies that a multigrid solver should be used (instead of the default sparse Cholesky solver).
[--vCycles <number of v-cycles per animation step>]: If a multigrid solver is used, ths integer value specifies the number of v-cycles to be performed at each step of the animation.
The default value for this parameter is 1.
[--gsIters <number of Gauss-Seidel iterations per level>]: If a multigrid solver is used, ths integer value specifies the number of Gauss-Seidel iterations to be done within each level of the v-cycle.
The default value for this parameter is 5.

--in <input polygonal/polyhedral mesh>: This string specifies the the name of the mesh.
For 2D simulations, the input polygonal mesh is assumed to be in PLY format, giving the set of vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z and the set of polygons encoded by a list of vertex indices.
For 3D simulations, the input polyhedral mesh is assumed to be in OVM format.
[--mg]: If enabled, this flag specifies that a multigrid solver should be used (instead of the default sparse Cholesky solver).
[--vCycles <number of v-cycles per animation step>]: If a multigrid solver is used, ths integer value specifies the number of v-cycles to be performed at each step of the animation.
The default value for this parameter is 3.
[--gsIters <number of Gauss-Seidel iterations per level>]: If a multigrid solver is used, ths integer value specifies the number of Gauss-Seidel iterations to be done within each level of the v-cycle.
The default value for this parameter is 5.

--in <input polygonal mesh>: This string specifies the the name of the mesh.
The input polygonal mesh is assumed to be in PLY format, giving the set of vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z and the set of polygons encoded by a list of vertex indices.
[--time <diffusion time>]: This floating point values specifies the time for diffusing the source delta function .
The default value for this parameter is 1e-3.
[--mg]: If enabled, this flag specifies that a multigrid solver should be used (instead of the default sparse Cholesky solver).
[--vCycles <number of v-cycles per animation step>]: If a multigrid solver is used, ths integer value specifies the number of v-cycles to be performed at each step of the animation.
The default value for this parameter is 1.
[--gsIters <number of Gauss-Seidel iterations per level>]: If a multigrid solver is used, ths integer value specifies the number of Gauss-Seidel iterations to be done within each level of the v-cycle.
The default value for this parameter is 5.

--in <input polygonal mesh>: This string specifies the the name of the input polygonal mesh.
The polygonal mesh is assumed to be in PLY format, giving the set of vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z and the set of polygons encoded by a list of vertex indices.
[--out <output polygonal mesh>]: This string specifies the the name of the output (processed) polygonal mesh.
The polygonal mesh is assumed to be in PLY format, giving the set of vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z and the set of polygons encoded by a list of vertex indices.
[--gWeight <gradient interpolation weight>]: This floating point value specifies the weight that should be given to gradient interpolation.
The default value for this parameter is 1e-5.
[--gScale <gradient dampening/amplification factor>]: This floating point value specifies the scale that is to be appled to the gradients.
The default value for this parameter is 1, specifying unmodified output.
[--mg]: If enabled, this flag specifies that a multigrid solver should be used (instead of the default sparse Cholesky solver).
[--vCycles <number of v-cycles per animation step>]: If a multigrid solver is used, ths integer value specifies the number of v-cycles to be performed at each step of the animation.
The default value for this parameter is 3.
[--gsIters <number of Gauss-Seidel iterations per level>]: If a multigrid solver is used, this integer value specifies the number of Gauss-Seidel iterations to be done within each level of the v-cycle.
The default value for this parameter is 5.
[--value <data type>]: This integer value specifies which type of per-vertex-data is to be processed. If the value is 0, the vertices' positions will be processed. If the value is 1, the vertices' normals will be processed. If the value is 2, the vertices' colors will be processed. (Note that if the value is 1 and the vertices do not have normals, the code will synthesize them by averaging from the indicent faces.)
The default value for this parameter is 0.

--in <input polygonal mesh>: This string specifies the the name of the input polygonal mesh.
The polygonal mesh is assumed to be in PLY format, giving the set of vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z, the x-, y-, and z-coordinates of the normals encoded by the properties nx, ny, and nz, and the set of polygons encoded by a list of vertex indices.
[--out <output principal curvature directions>]: This string specifies the the name of the file to which the (extrinsic) principal curvature directions will be written, scaled by the associated curvature values.
[--kMin]: If enabled, this flag specifies that the output tangent vectors will correspond to the directions of minimal curvature. Otherwise they will correspond to the directions of maximal curvature.

--in <input polygonal mesh>: This string specifies the the name of the input polygonal mesh.
The polygonal mesh is assumed to be in PLY format, giving the set of vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y and the set of polygons encoded by a list of vertex indices.
--inVF <input tangent vector field>: This string specifies the the name of the file prescribing the per-face tangent vectors.
[--out <output polygonal mesh>]: This string specifies the the name of the output polygonal mesh.
The polygonal mesh is assumed to be in PLY format, giving the set of vertices with the x-, y-, and z-coordinates of the positions encoded by the properties x, y, and z, the colors encoded by the properties red, green, and blue, and the set of polygons encoded by a list of vertex indices.
[--mg]: If enabled, this flag specifies that a multigrid solver should be used (instead of the default sparse Cholesky solver).
[--vCycles <number of v-cycles per animation step>]: If a multigrid solver is used, ths integer value specifies the number of v-cycles to be performed at each step of the animation.
The default value for this parameter is 20.
[--gsIters <number of Gauss-Seidel iterations per level>]: If a multigrid solver is used, ths integer value specifies the number of Gauss-Seidel iterations to be done within each level of the v-cycle.
The default value for this parameter is 5.

USAGE EXAMPLES (WITH SAMPLE DATA)
For testing purposes, a number of polgonal/polyhedral models are provided (using the .ply and .ovm extensions respectively).

Linear Elasticity in 2D

To run this executable you must specify the input polygonal mesh. For example, to see the deformation of the unit square, tessellated by a Voronoi diagram, deforming under the action of gravity, with the vertices on the left side locked, and using a direct solver to advance time-steps, execute:

% Bin/*/DeformableSolids2D --in ../VPSF.Data/square.voronoi.3.ply --lock

To see the deformation of the unit square, tessellated using concave polygons, evolving to its rest state after an initial anisotropic scaling is applied, using a hierarchical solver to advance time-steps, execute:

% Bin/*/DeformableSolids2D --in ../VPSF.Data/square.concave.3.ply --gravity 0 --xForm 2 0 0 0.5 --mg

You can toggle the animtation by hitting [SPACE] and you can step through the animation by hitting "+".
You can also interact with the animation by left-clicking to drag a vertex.

Linear Elasticity in 3D

To run this executable you must specify the input polyhedral mesh. For example, to see the deformation of a unit cube, tessellated by a Voronoi diagram, deforming under the action of gravity, with the vertices on the left side locked, and using a direct solver to advance time-steps, execute:

% Bin/*/DeformableSolids3D --in ../VPSF.Data/cube.voronoi.3.ovm --lock

To see the deformation of the unit cube, tessellated using truncated cells, evolving to its rest state after an initial anisotropic scaling is applied, using a hierarchical solver to advance time-steps, execute:

% Bin/*/DeformableSolids3D --in ../VPSF.Data/cube.truncated.3.ovm --gravity 0 --xForm 2 0 0 0 1 0 0 0 0.5 --mg

You can toggle the animtation by hitting [SPACE] and you can step through the animation by hitting "+".
You can pan by by dragging with the left mouse button while holding down the [CTRL] key.
You can rotate by dragging with the left mouse button.
You can also rotate by using the "q", "w" , "a", "z", "s", and "x" keys.

Franke Test in 2D

To run this executable you must specify the input polygonal mesh. For example, to run the test on the unit square tessellated by a Voronoi diagram and using a direct solver, execute:

% Bin/*/FrankeTest2D --in ../VPSF.Data/square.voronoi.3.ply

To run the test on the unit square tessellated using concave polygons and using a hierarchical solver, execute:

% Bin/*/FrankeTest2D --in ../VPSF.Data/square.concave.3.ply --mg

Franke Test in 3D

To run this executable you must specify the input polyhedral mesh. For example, to run the test on the unit cube, tessellated by a Voronoi diagram, and using a direct solver, execute:

% Bin/*/FrankeTest3D --in ../VPSF.Data/cube.voronoi.3.ovm

To run the test on the unit cube, tessellated using truncated cells, and using a hierarchical solver, execute:

% Bin/*/FrankeTest3D --in ../VPSF.Data/cube.truncated.3.ovm --mg

Geodesics in Heat

To run this executable you must specify the input polygonal mesh. For example, to visualize single-source geodesics on the model of the Armadillo Man, using a direct solver, execute:

% Bin/*/GeodesicsInHeat --in ../VPSF.Data/armadillo.ply

To visualize single-source geodesics on the model of the Fanblade, using a hierarchical solver, execute:

% Bin/*/GeodesicsInHeat --in ../VPSF.Data/fanblade.ply --mg

You can specify the geodesic source by left-clicking while holding down the [SHIFT] key.
You can pan by by dragging with the left mouse button while holding down the [CTRL] key.
You can rotate by dragging with the left mouse button.
You can also rotate by using the "q", "w" , "a", "z", "s", and "x" keys.

Gradient Domain Processing

To run this executable you must specify the input and output polygonal meshes as well as the gradient interpolation weight and the gradient dampening/amplification scale. For example, to smooth the Bunny model using a direct solver, execute:

% Bin/*/GradientDomainProcessing --in ../VPSF.Data/bunny.ply --gScale 0 --out bunny.smooth.ply

For more aggressive smoothing, you can increase the gradient interpolation weight:

% Bin/*/GradientDomainProcessing --in ../VPSF.Data/bunny.ply --gScale 0 --out bunny.smooth.ply --gWeight 1e-3

To sharpen the Armadillo Man model using a hierarchical solver, execute:

% Bin/*/GradientDomainProcessing --in ../VPSF.Data/armadillo.ply --gScale 2 --out armadillo.sharp.ply --mg

Line Integral Convolution

Generating a line-integral-convolution visualizing the maximal curvature directions requires three steps -- defining a smooth normal field, computing the maximal curvature direction, and diffusing a random noise signal using a metric defined by the maximal curvature directions. We provide the steps for synthesizing a visualization of the maximal curvature directions on the Fertility model, using a multigrid solver.

To compute a smoothed normal field, execute:
% Bin/*/GradientDomainProcessing --in ../VPSF.Data/fertility.ply --gScale 0 --gWeight 1e-3 --out fertility.normal.ply --value 1 --mg
(For this example we smooth more aggressively, setting --gWeight=1e-3.)
To compute the maximal curvature directions, execute:
% Bin/*/PrincipalCurvature --in fertility.normal.ply --out fertility.kmax
To generate the line-integral-convolution visualization, execute:
% Bin/*/LineIntegralConvolution --in fertility.normal.ply --inVF fertility.kmax --out fertility.lic.ply --mg

We make two observations about this executable. First, to compute the smooth normal field we diffuse more aggressively, using a gradient weight of --gWeight=1e-3, ten times larger than the default value. (This is neccessary for capturing a more global notion of curvature.) Second, the default number of v-cycles for the multigrid solver is 20. (This is necessary because the severe anisotropy makes the multigrid solver converge less efficiently.)

COMPILATION AND EXECUTION

The Windows executables require both the glew and glut dynamically linked libraries to run. These can be found here and should be included either in the directory with the executables, or in the directory from which the executables are run.
Compiling under Windows requires both the glew and glut libraries. These can be found here and should be placed in the output directory for linkage.
The implementation uses the standard Eigen source code. If your system supports MKL it may be possible to develop faster executables by #define'ing the EIGEN_USE_MKL_ALL flag in Misha/PreProcess.h and ensuring that the associated include/library directories are set correctly.

HISTORY OF CHANGES

Version 2:

Added support for regularizing within the kernel.

Version 2.5:

Added line-integral-convolution code.

Version 2.51:

Added more linear-algebraic functionality to AutoDiff.

HOME