VDT User's Guide
Copyright (C) 1999, Petr Krysl
VDT stands for (V)ariational (D)elaunay (T)riangulation.
This algorithm, which had been proposed by M. Ortiz and
myself (see the References), generates
tetrahedral decomposition of a general solid body, whose surface is
given as a collection of triangular facets. The principle idea is to
modify the constraints in such a way as to make them appear in an
unconstrained triangulation of the vertex set a priori. The
vertex set positions are randomized to guarantee existence of a unique
triangulation which satisfies the Delaunay empty-sphere property.
(Algorithms for robust, parallelized construction of such
triangulations are available.) In order to make the boundary of the
solid appear as a collection of tetrahedral faces, we iterate two
operations, edge flip and edge split with the insertion of additional
vertex, until all of the boundary facets are present in the
tetrahedral mesh. The outcome of the vertex insertion is another
triangulation of the input surfaces, but one which is represented as a
subset of the tetrahedral faces. To determine if a constraining facet
is present in the unconstrained Delaunay triangulation of the current
vertex set, we use the results of Rajan which re-formulate Delaunay
triangulation as a linear programming problem.
Contents
The input file consists of control directives
and the surface mesh
data: point and boundary facet specification.
mesh_size arg
where arg is the default, uniform mesh size to use throughout
the mesh.
bdry_pt_shift_mult arg
where arg is the multiplier. This directive is identical in
effect to the command-line option -bdry_pt_shift_mult;
see details in the section on
Command line options.
gen_pt_shift_mult arg
where arg is the multiplier. This directive is identical in
effect to the command-line option -gen_pt_shift_mult;
see details in the section on
Command line options.
gen_interior_pts
This directive is identical in
effect to the command-line option -gen_interior_pts;
see details in the section on
Command line options.
gen_near_surf_pts
This directive is identical in
effect to the command-line option -gen_near_surf_pts;
see details in the section on
Command line options.
lp_size_limit arg
where arg is the max LP problem size.
This directive is identical in
effect to the command-line option -lp_size_limit;
see details in the section on
Command line options.
input_version arg
where arg is the input version statement (might be
given for example by the RCS $Id: vdtuguide.html,v 1.1.1.1 2001/07/24 02:11:23 pkrysl Exp $ code).
First, one can insert some control commands.
Then specify the points: For each point use one line of the form
PT id x y z {mesh_size_at_point}
where PT is the keyword. id is the point identifier
(positive integer), x,y,z are the coordinates,
mesh_size_at_point is the (optional) desired mesh size at
that point.
Then follow boundary facets: For each unique triangular facet specify
BSF pt0 pt1 pt2 surf_id {reg_id0} {reg_id1}
where BSF is the keyword, pt0,pt1,pt2 are three
point identifiers in counter-clockwise order when looking against the
outer normal of the facet (for a one-sided surface, outer normal
points out of the body), surf_id is the surface identifier
(positive integer would do), and and reg_idN are optional
region identifiers. Reg_id1 is on the side to which the
normal points, reg_id0 is on the other side (inside for
one-sided surfaces). If the facet is incident on one region only, the
region specified is reg_id0 (reg_id1 may be then
specified as zero). If the facet represents an embedded sheet in a 3D
region, reg_id0 == reg_id1.
The idea behind the surface id is that triangles which may be considered
part of a single surface may be modified by the Delaunayzation
algorithm. In particular, many sorts of re-triangulations are allowed
for triangles on a single surface, but disallowed if the triangles are
on distinct surfaces. If the triangle-surface associations are not
available to you, just specify surf_id=1.
Notes:
- If a facet bounds only a single region, it should be oriented such
that its three points, pt0...pt2 are three point identifiers in ccw
order when looking against the outer normal of the facet (for a
one-sided surface, outer normal points out of the body). In other
words, the normal is defined by the fact that the points are traversed
in ccw order when looking against the arrow of the normal. Only one
region identifier will be supplied in this case. (You don't want the
second region, infinite in extent, to be meshed, do you? :-)
- If a facet bounds two regions, it should be again oriented such that
the first region, reg_id0, is that for which the three points are in
ccw order when looking against the outer normal. The second region,
reg_id1, is `pierced' by this normal, that's what I mean by `outer'
normal. It's outer with respect to the region reg_id0.
When at a loss, try running either the VDT program or the scripts with
the option -help. It should give you a hint how to
proceed.
- Running vdt:
VDT comes with a default driver, vdtdriv.c. This driver
knows how
to read the VDT input file and calls the VDT library to do the proper
things. Run vdt
(all lowercase) as vdt -i inpfile, where inpfile is the input file. Brief usage
message is printed for each recognized option when vdt is
run as vdt -help. Detailed description of options is
given in a separate section on vdt
command line
options.
- Front-end script: vdt.sh is a front-end to
vdt in that it knows something about default
directories and suffixes of files, and tries to run
vdt either on the VDT input file it found, or on a
copy extracted by gunzip, decompress,
co, get or a combination thereof.
- Test script: testvdt.sh:
VDT provides a script for automatic testing of the installation.
Run testvdt.sh in the source directory VDT/src.
This script runs vdt for many input files from the
VDT/inputs directory and writes a detailed resume to the
stdout, plus an even more complete log is written to
test.log. testvdt.sh may be given the option
-giface to run the test with graphic output. There are
also other options; run testvdt.sh -help to see a brief
usage message.
- Get script: vdtget.sh: VDT input files may be
compressed, or checked in under RCS or SCCS. This script
knows about some default directories and suffixes, and
tries to find the input file you want and give it to you in
human-readable form.
- Architecture script: vdtarch.sh is an auxiliary
script. It uses GNU config.guess and config.sub to deduce the
architecture on which it is run and prints the result.
-
-help Prints short usage hint for each option recognized.
-
-report_opts Prints options as they are being set.
Useful for finding out what the default settings are.
-
-i arg, where arg = input file. Input file for the mesher.
See the section on Input specification for details of
the format and conventions.
-
-giface Run the mesher with a graphical interface.
The bundled (and so far only) interface is Elixir (as of Dec
1999). Some controls specific to the mesher are accessible
from the "Custom" menu.
-
-true_name arg, where arg = true
input file name. Useful when vdt is run from within a script
(such as vdt.sh), and the input file is for instance gzipped.
Thus, eventhough the mesher reads, say, ainp.vin, it knows that
it really accesses ainp.vin.gz.
-
-test_mode Run in test mode. Used by testvdt.sh.
-
-auto_mode Run in automatic mode. Does not wait for
user interaction in graphic mode, but proceeds automatically
through the mesh generation.
-
-no_intr Run in no-interrupt mode. Interrupts (^c)
during advancing front triangulation cause a menu to be
displayed. Selections include
- s stop
- a abort
- c continue
- X go to graphic interface.
Useful for graphical debugging, or just for prevention of
accidental killing of the mesher.
-
-giface Use graphical interface. See details elsewhere.
-
-report_opts Prints options as they are being set.
See writeup elsewhere.
-
-help Prints short usage for each option recognized.
See details elsewhere.
-
-dump_tet_wrl Dump tetrahedra as VRML entities. The
printout goes to stdout.
-
-dump_tet_egf Dump tetrahedra as EGF entities. The
printout goes to stdout.
-
-dump_bsf_egf Dump boundary facets as EGF entities. The
printout goes to stdout.
-
-dump_data Dump data in the VDT input format. The
printout goes to stdout.
-
-dump_t3d Dump mesh in the T3D output format. The
printout goes to stdout.
-
-gen_interior_pts Instructs the mesher to generate
interior points. The points are placed using an octree.
-
-gen_near_surf_pts Instructs the mesher to generate
near-surface points. Points near the surface are placed
offset from the facets by a certain amount.
-
-inject_surf_proj Instructs the mesher to inject
projections of points close to surfaces onto the surfaces.
This might prevent excessive work (or even failure) in the
Delaunayzation procedure.
-
-eval_mesh_size_from_pt The mesh size is to be
evaluated from mesh sizes associated with points. (Default
is to use the uniform mesh size supplied for the whole mesh.)
The mesh size at a given location is determined from mesh size
values associated with points in the neighborhood (of size
given by the largest mesh size value in the whole mesh).
-
-bdry_pt_shift_mult arg, where arg = bdry pt shift
multiplier (>0). Determines by how much a point on the
boundary surface should by randomly shifted to make the
triangulation unique (in a statistical sense). The actual
shift s is computed as s = bdry_pt_shift_mult *
ms, where ms is the mesh size at the location
of the point to shift.
-
-gen_pt_shift_mult arg, where arg = generated pt shift
multiplier (>0). Determines by how much a point in the
interior should by randomly shifted to make the
triangulation unique (in a statistical sense). The actual
shift s is computed as s = gen_pt_shift_mult *
ms, where ms is the mesh size at the location
of the point to shift.
-
-near_surf_test arg, where arg = near-surface test
(0=ignore,1=dist,2=circumsphere). Determines how the test for
nearby points should be performed when generating interior
points.
-
-reset_locs arg, where arg = 0 (=FALSE), or any other
number (=TRUE). Reset locations of points (un-randomize) at
the end, yes or no.
-
-keep_slivers Keep slivers in the mesh. Default is
to try to remove the slivers by various topological and
geometrical operations.
-
-retri_to_desliver Try to remove slivers by
re-triangulation. The output of stage (i-1) is fed to the
stage (i) as input, plus some points which are injected at
circumcenters of slivers in an attempt to remove the slivers
at stage (i).
-
-inject_surf_proj Inject projections of points close
to surfaces. This option is described elsewhere, but here we
mention that it can make the resulting mesh "nicer" looking.
-
-sliver_dihed_angle arg, where arg = sliver dihedral angle
in degrees (>0). The smallest dihedral angle a tetrahedron
may display without being considered a sliver.
-
-nranges arg, where arg = number of quality ranges. When
printing the mesh quality statistics, use as many ranges as
specified here.
-
-inject_surf_proj Inject projections of points close
to surfaces. This option has been described elsewhere, but
here we mention that injecting points which are very close to
a constraining surface may prevent the surface Delaunayzation
algorithm to fail (it has to fail, for example, if a point is exactly at a
constraining surface without being classified as
being located on the surface).
-
-orient_initial_af Orient initial advancing front.
The surface facets are expected to be oriented and labeled
with regions which they bound as described in the section on
Input specification. If they are not oriented
properly, this option may be used to repair the initial
advancing front.
-
-allow_flips arg, where arg = allow flips (0=FALSE; TRUE
otherwise). The surface Delaunayzation algorithm uses
"diagonal" flips and edge splits (with the insertion of
surface points) to enforce
-
-bdry_pt_shift_mult arg, where arg = bdry pt shift
multiplier (>0). This option had been described more fully elsewhere.
-
-lp_size_limit arg, where arg = limit size of LP. While
testing the Delaunayhood of facets, linear-programming
problems (LPP's) are often solved. Here one can limit the size of the
largest LPP's whose solution is still attempted; larger
problems than that are not attempted and the check of the
facet is based on other checks (perhaps not as precise, but cheaper).
-
-report_opts Prints options as they are being set.
-
-gdebug Debug graphically. Shows the progression of
surface Delaunayzation and the generation of the tetrahedra.
Don't try it with really big meshes; it's going to be slow.
-
-maxdebug Debug by performing certain (expensive)
verifications: it checks for duplicate tetrahedra, and Delaunay
property of surface facets is checked using the most expensive
(and most precise) computations.
-
-pdebug Debug information is printed to the stderr.
It produces a lot of output.
The mesher is encapsulated in a library, libvdt.a (or libvdt.so if
a dynamic version is available/desired). The public interface to
the mesher functionality is described in the header vdtpub.h.
Dependencies (in this order):
- Elixir (libesi.a and libelixir.a) (only if graphic
interface had been compiled into libvdt.a).
- G3D (libg3d.a).
- PiRaT (libpirat.a).
- LOBS (liblobs3d.a).
- Ckit (libckit.a).
- Meschach (libmeschach.a or meschach.a).
- lp_solve (libpk.a).
- Krysl, P. and M. Ortiz (1999):
Variational Delaunay Approach to the Generation of Tetrahedral Finite
Element Meshes, to appear, International
Journal for Numerical Methods in Engineering.
(Download postscript of draft)
Peter Krysl
Last modified: Fri Dec 17 12:53:05 PST 1999