Section: SimBio (1Vi)
Updated: 09 September 2004
vgrid - generate a FEM grid from a labelled Vista volume dataset
vgrid [-option ...] [infile] [outfile]
vgrid expects a labelled Vista image in
VShort or VUByte format which contains a maximum number of 256 labelled
regions (for the marching tets algorithms, currently only 2 regions are allowed).
vgrid converts this voxel dataset into a volumetric mesh
consisting of either cubes or tetrahedra.
The minimum and maxmimum grid dimensions are selectable by command
line arguments (-min and -max).
If the minimum is greater than 1, data are subsampled first
by selecting the most frequent label for a target cell. Setting the maximum
to a value greater than 1 introduces collection of voxels in an octree fashion.
Cubical as well as tetrahedral grids may be generated. Simple cubes with
8 nodes at the vertices (tetrahedra: 4) are assumed. Thus, the cubical
grids produced will only well-defined if they are uniform (min == max).
Tetrahedral grids may be non-uniform (min < max).
In a final step, boundaries may be refined by specifying -smooth shift
or -smooth marching. In the first case, which applies only to uniform hexahedral grids,
nodes close to a boundary at shifted onto the boundary, given a shift constraint as specified by
the argument -shift. The latter case introduces a local refinement
by a tetrahedrization of boundary cells. Note that selecting this option
implies the generation of a tetrahedral mesh.
A small number of output formats are supported, either a Vista graph file,
a simple ASCII mesh format (3D), the GPPView (GeoFEM) format (3D), the GMV format (2D+3D),
the complex2D format of GrAL (2D), and the format of OpenDX (2D).
COMMAND LINE OPTIONS
vgrid accepts the following options:
Prints a message describing options.
- -olevel number
Verbosity level. Default: 1.
Level 0 prints only warnings and errors, level 1 prints global values and progress information,
level 2 gives per-cell output, and level 3 gives even more detailed per-cell output.
- -in infile
Specifies a Vista data file containing the labelled input image.
- -out outfile
Specifies the output file
- -format [hf|vm|ipe|ascii|gmv|gpp|complex2d|dx]
Specifies the output format.
(It is easy to adapt vgrid to output other formats,
look at mesh::vtoa() and its call in gridGenerator::write() for an example.)
hf selects Vista graph format (default).
vm and ipe are variations of the vm format
ascii selects a simple home-grown ASCII mesh format. Volume meshes only.
gmv selects the GMV ASCII format (http://www-xdiv.lanl.gov/XCM/gmv/GMVHome.html).
For both surface and volume meshes.
gpp selects the GPPView/GeoFEM format
(http://geofem.tokyo.rist.or.jp/download_en/gppview.html). Volume meshes only.
complex2d selects the complex2d format of GrAL>.
For surface meshes only.
dx selects the format of OpenDX (http://www.opendx.org).
For surface meshes only.
- -elem type
Specifies the element type of the FEM grid:
tetra5 tetrahedra (a cube divided into 5 tetrahedra)
tetra6a tetrahedra (a cube divided into 6 tetrahedra, linkage a)
tetra6b tetrahedra (a cube divided into 6 tetrahedra, linkage b)
cube cubes (default)
This option currently provides a real choice only in the case of a uniform mesh (min=max).
In the non-uniform case, tetra5 is automatically selected.
- -min number
Specifies the minimum grid dimension (resolution at material interfaces). Default: 4.
Must be a positive integer.
This value can be overridden on a per-interface basis by interface lines
in a material file specified with -material.
- -max number
Specifies the maximum grid dimension (resolution inside a material-homogeneous region).
Default: 4. Must be a positive integer, and a power-of-two multiple of
the value specified with -min (will be adapted otherwise).
This value can be overridden on a per-material basis by material lines
in a material file specified with -material.
- -smooth type
no no boundary smoothing (default)
shift shift boundary nodes (uniform hexahedral meshes only, min=max)
marching refine mesh locally by introducing tetrahedra
- -shift number
Specifies the degree of shifting, must be between 0.0 and 0.49. Default: 0.49.
This option only applies if shift is selected for the -smooth option.
Note: excessive smoothing can degrade the quality of the hex cells.
- -sm_iters number
Specifies the number of iterations for node shifting after marching tetrahedra.
Default: 0 (no smoothing).
- -sm_weights name
Specifies a file containing weights for surface smoothing. The number(s) in this file should
be within -1 and 1. A single number corresponds to usual Laplacian smoothing with this parameter
(1.0 means each surface vertex is moved to the barycenter of its neighbors on the surface).
If there are two or more numbers, there will be -sm_iters cycles through this file,
using the numbers in turn as parameters of single Laplacian smoothing steps.
For instance, putting the numbers 0.5 and -0.5 in the file reduces shrinking.
Google for "smoothing without shrinking".
- -vsm_weights name
Specifies a file containing weights for volume smoothing (ie. smoothing of interior vertices).
This is necessary to avoid degradation of the quality of tetrahedral cells.
Volume smoothing is interleaved with surface smoothing: After each Laplacian surface smoothing
iteration, there is a Laplacian smoothing iteration of the interior vertices.
In order to force different interleaving patterns
(e.g. volumetric smoothing only every three surface smoothing iterations),
one has to insert an appropriate number of zeros into the volumetric smoothing weights file
(2 zeros and the non-zero smoothing parameter in this example).
If this file contains a smoothing value of 0.0, no volume smoothing is performed.
If no file is present, a default value of 0.5 is used.
- -surface [true|false]
If set, only a surface mesh is generated. Implies -smooth marching.
- -material name
Name of an optional parameter file specifying material-dependent meshing information.
See the "FILES" section for more information.
- The following options are only useful in the SimBio context:
- -simbio_mat_ids [true|false]
Use material IDs specified in the SimBio project. Implies the use of a material file
(-material option) with the correct SimBio material names.
- -matdb name
Read material names and IDs from file, instead of using library version.
Has an effect only if -simbio_mat_ids is selected.
- -explicit_links [true|false]
Write explicit vertex-vertex connectivity to the Vista output. Default: false.
Do not write any fields, except materials. Default: false.
Specifies the fixity constraints to be applied to grid nodes:
box read constraints from file box.con.
Constraint nodes lie in a box:
plane read constraints from file plane.con.
xmin ymin zmin
xdim ydim zdim
Constraint nodes lie in a plane:
snodes read constraints from file snodes.con.
plane_dir (Orientation of plane 1: xy, 2: yz 3: zx)
plane_pos (z, x, y position of plane)
Constraint nodes are enumerated by giving their integer coordinates:
n (number of constraint nodes)
x1 y1 z1
x_n y_n z_n
- -np number
Number of partitions in initial node and element partitionings.
When using the marching tetrahedra algorithm and a higher number of partitions,
the partitioning is very bad.
Input and output files can be specified on the command line or allowed to
default to the standard input and output streams.
With the -material option, a file containing information for material specific meshing options
can be specified. The syntax of this file is as follows:
First, a number of lines describing materials, introduced by the keyword material:
material <name> <maxdim> <lower bd> <upper bd> <meshing type> <weight>
is the name of the material (string)
is the maximal element size of the material (analoguous to the global setting by -max)
- <lower bd> <upper bd>
give the label range of the material, i.e. every label L in [<lower bd> <upper bd>] is considered
having this material
- <meshing type>
gives the type of meshing. Currently, only '1' for choosing the global meshing type set via commandline parameters,
and '2' for suppressing meshing of this material are supported.
gives a weight to the material, which is used when subsampling the image. For each material,
the number of voxels having this material is multiplied with the weight before selecting the
majority material. This is a hack to prevent thin structures from disappearing after subsampling.
Second, the resolution of specific material interfaces can be specified,
overriding the global value given with the -min option. Such lines
have the form
interface <mat1> <mat2> <maxdim>
- <mat1> <mat2>
are two material names given in the materials section before
is a number giving the maximal element size at this material interface, that is, each octree cell
containing voxels of both these materials will be of at most this size.
In each line, all values must be present. Material and interface lines may be mixed.
In the following example
material bg 4 0 0 2 1.0
material skull 2 1 1 1 4.0
material brain 8 2 6 1 1.0
material scalp 4 7 7 1 1.0
interface skull brain 1
interface skull scalp 1
interface scalp bg 2
there are 4 materials (bg, skull, scalp, and brain), having labels 0, 1, 2-6, and 7, respectively.
The material bg (for background) is not meshed, skull is meshed with 2 voxels resolution,
scalp with 4 voxels, and brain with 8 voxels.
However, the interfaces between brain and skull as well as skull and scalp
are meshed with 1 voxel resolution.
In contrast, the interface between scalp and bg is meshed only with 2 voxels resolution.
The weight for skull is set to 4.0, which means that an octree cell containing more than 12.5%
skull voxels will get labeled as skull.
vgrid -in img.v -out mesh.gmv -format gmv -min 1 -max 1 -elem cube
This generates an uniform mesh, where each voxel of the image corresponds to a hexahedral cell of the mesh.
vgrid -in img.v -out mesh.gmv -format gmv -min 1 -max 1 -elem tetra5
Generate a uniform mesh, each voxel is represented by 5 tetrahedra.
vgrid -in img.v -out mesh.gmv -format gmv -min 1 -max 4 -elem tetra5
Generate a non-uniform tetrahedral mesh, with maximal edge length 4 times a voxel diameter.
vgrid -in img.v -out mesh.gmv -format gmv -min 1 -max 4 -elem tetra5 -smooth marching
Generate a non-uniform tetrahedral mesh, the boundary between the two materials is smoothed using
the marching tets algorithm.
Note: Only 2 materials are allowed here.
vgrid -in img.v -out mesh.gmv -format gmv -elem tetra5 -material img.mat
Read material meshing parameters from the file img.mat
The marching tetrahedra algorithms is restricted to the two-material case.
If the image contains more then 2 materials to be meshed,
vgrid will print a warning and stop.
The marching tetrahedra algorithm may "eat up" small structures.
Iterated node shifting for hexahedra may result in distorted elements.
There may be ugly spikes at the material interface when using non-uniform meshing together
with marching tets - the more imbalanced the octree, the sharper the possible spikes.
There is no option to balance the octree.
Vgrid homepage http://vgrid.simbio.de
- COMMAND LINE OPTIONS
- SEE ALSO
This document was created by
using the manual pages.
Time: 15:32:10 GMT, October 08, 2004