SimBio-Vgrid

Section: SimBio (1Vi)
Updated: 09 September 2004

NAME

vgrid - generate a FEM grid from a labelled Vista volume dataset

SYNOPSIS

vgrid [-option ...] [infile] [outfile]

DESCRIPTION

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:

-help

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. Default: false.

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

-nofields

Do not write any fields, except materials. Default: false.

-constraint

Specifies the fixity constraints to be applied to grid nodes:


no     none
box    read constraints from file box.con. 
       Constraint nodes lie in a box:


  ConstraintID
  xmin ymin zmin
  xdim ydim zdim

plane read constraints from file plane.con.
Constraint nodes lie in a plane:


ConstraintID
plane_dir       (Orientation of plane 1: xy, 2: yz  3: zx)
plane_pos       (z, x, y position of plane)

snodes read constraints from file snodes.con.
Constraint nodes are enumerated by giving their integer coordinates:


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

FILES

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>

where

<name>: is the name of the material (string)
<maxdim>: 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.
<weight>: 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>

where

<mat1> <mat2>: are two material names given in the materials section before
<maxdim>: 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.

EXAMPLES

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

LIMITATIONS

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.

AUTHOR

Guntram Berti

This document was created by man2html, using the manual pages.
Time: 15:32:10 GMT, October 08, 2004