Variational Polygonal/Polyhedral Shape Functions (Version 2.7)

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: Win64
Source Code: ZIP GitHub
Data: ZIP
Older Versions: V2.6 V2.51 V2.5 V2 V1

---

EXECUTABLES

DeformableSolids2D/DeformableSolids3D: Supports the simulation of deformable solids in 2D and 3D using linear elasticity. The executable launches an interactive viewer that provides a visualization of the deforming solid. The solid can deform either through the action of gravity or by applying a prescribed linear transformation and having the solid evolve towards its rest state. (In 2D, the applications supports selecting and dragging of individual vertices.)
Hit [SPACE] to start the simulation or "+" to advance one time-step.

--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.

FrankeTest2D/FrankeTest3D: Supports the evaluation of function space quality by solving a Poisson equation over the unit square/cube, with boundary values fixed to the analytic values of the Franke test function. The executable takes in geometry, and outputs the RMS of the solution (compared to the analytic solution).

--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.

GeodesicsInHeat: Supports the interactive visualization of single-source geodesics on the surface of polygonal mesh using the heat method.
Left-clicking while holding down the [SHIFT] key selects the source.

--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.

GradientDomainProcessing: Supports the gradient domain smoothing and sharpening of surface geometry by solving a screened Poisson equation where the target values are given by the input geometry and the the target gradients are given by the dampened/amplified gradients of the input.

--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.

PrincipalCurvature: Supports the computation of per-face, extrinsic principal curvature directions by approximating the derivative of the normals across edges.

--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.

LineIntegralConvolution: Supports the generation of a line-integral-convolution visualization of a tangent vector field by diffusing a random scalar field with respect to an anisotropic metric that compresses distances along the the prescribed tangent directions.

--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.

1. 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.)
2. To compute the maximal curvature directions, execute:

   % Bin/*/PrincipalCurvature --in fertility.normal.ply --out fertility.kmax

3. 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.

Version 2.6:

• Bug fixes in AutoDiff.

Version 2.7:

• Cleaned up AutoDiff:
  • Changed Tensor to use UIntPack.
  • Replaced Window with MultiDimensionalArray.
  • Removed dependence of MultiDimensionalArray on UIntPack.

---

HOME