ASCII VTK Files

The ASCII Legacy VTK File Format

Th ASCII Legacy VTK format is one good way to get data into VisIt without having to write a complex binary file. It's well supported in VisIt, and supports a wide range of data set and mesh types. VisIt handles a variety of features which are not well exposed by the VTK reader (e.g. materials, parallelism), but this is a good starting point.

The documentation on the format itself is here: http://www.vtk.org/VTK/img/file-formats.pdf Note that this document also describes the newer XML-based formats, which are more complex. They work fine, but lack the simplicity and ease of use of the legacy formats. If you need the advanced features of the XML formats, you might examine other formats apart from the VTK ones.

We have a "VisItWriter" library (here: VisItWriter ), which has C and Python functions to write these meshes. If you want to write them yourself, they are rather simple. See the PDF for full documentation, but here are a few examples:

Some general notes about the format:

• the number of values one each line for the points, data, etc. sections is not strict; you can add a line break for every point, value, or put several values on one line, but try to keep it in sane limits (e.g. 4096 characters per line is a limitation on some systems)
• the header information must appear exactly, including spaces and capitalization
• you can have multiple variables: just list them one after the other in the appropriate (CELL_DATA or POINT_DATA) section, and try to keep the variable names well-formed, e.g. with letters/numbers/underscores like you'd use in C/C++

One quadrilateral in a polygonal ("polydata") mesh

# vtk DataFile Version 3.0
vtk output
ASCII
DATASET POLYDATA
POINTS 4 float
0 0 0
1 0 0
1.1 1.1 0
0 1 0
POLYGONS 1 5
4 0 1 2 3
CELL_DATA 1
POINT_DATA 4
SCALARS nodal float
LOOKUP_TABLE default
0 1 2 1.1

Notes:

• the number of values one each line for the points, data, etc. sections is not strict
• this has no cell data
• the "4" at the beginning of the polygon data denotes the number of vertices in that polygon; each polygon has one
• this type of mesh supports only VERTICES, LINES, and POLYGONS -- not 3D cells

A one-cell 2D rectilinear mesh

# vtk DataFile Version 3.0
vtk output
ASCII
DATASET RECTILINEAR_GRID
DIMENSIONS 2 2 1
X_COORDINATES 2 float
0 1
Y_COORDINATES 2 float
0 1
Z_COORDINATES 1 float
0
CELL_DATA 1
POINT_DATA 4
FIELD FieldData 1
nodal 1 4 float
0 1 1.1 2

Notes:

• note that this style used FIELD data for a scalar array
• for a 2D grid like this, the Z coordinate must still exist, and be equal to zero
• for a 3D grid, just make the third dimension greater than one

A six-cell (12-point) 2D rectilinear mesh

# vtk DataFile Version 3.0
vtk output
ASCII
DATASET RECTILINEAR_GRID
DIMENSIONS 3 4 1
X_COORDINATES 3 float
0 2 4
Y_COORDINATES 4 float
1 2 3 4
Z_COORDINATES 1 float
0
CELL_DATA 6
FIELD FieldData 1
cellscalar 1 6 float
1.1 7.5 1.2 1.5 2.6 8.1
POINT_DATA 12

A one-cell 2D curvilinear (structured, but not rectilinear) mesh

# vtk DataFile Version 3.0
vtk output
ASCII
DATASET STRUCTURED_GRID
DIMENSIONS 2 2 1
POINTS 4 float
0 0 0
1 0 0
0 1 0
1.1 1.1 0
CELL_DATA 1
POINT_DATA 4
FIELD FieldData 1
nodal 1 4 float
0 1 1.1 2

Notes:

• the difference between this file and the rectilinear one above is that the every point in the grid has a fully defined X, Y, and Z coordinate
• See http://www.cacr.caltech.edu/~slombey/asci/vtk/vtk_formats.simple.html for details on the vtk format.

A one-cell 2D unstructured mesh

# vtk DataFile Version 3.0
vtk output
ASCII
DATASET UNSTRUCTURED_GRID
POINTS 4 float
0 0 0
1 0 0
0 1 0
1.1 1.1 0
CELLS 1 5
4 0 1 3 2
CELL_TYPES 1
9
CELL_DATA 1
POINT_DATA 4
FIELD FieldData 1
nodal 1 4 float
0 1 1.1 2

Notes:

• This happens to be a single quadrilateral, and could be done using a structured grid
• You need to specify not just the cell connectivity array, but a cell type array; consult the PDF for cell type values and cell orderings
• See http://www.cacr.caltech.edu/~slombey/asci/vtk/vtk_formats.simple.html for details on the vtk format.

A single structured cube with vectors

# vtk DataFile Version 3.0
vtk output
ASCII
DATASET STRUCTURED_GRID
DIMENSIONS 2 2 2
POINTS 8 float
0 0.2 0 0.1 0.184843 0 0 0.25 0
0.1 0.234843 0 0 0.2 0.333333 0.1 0.184843 0.333333
0 0.25 0.333333 0.1 0.234843 0.333333

CELL_DATA 1
SCALARS cellval float
LOOKUP_TABLE default
1489
VECTORS cellvec float
.6 .7 .5 

POINT_DATA 8
SCALARS ptval float
LOOKUP_TABLE default
0 1 2 3 4 5 6 7
VECTORS ptvec float
0 0.0287671 0 0 0.0258604 0 0 0.0287671 0
0 0.0258604 0 0 0.0287671 0 0 0.0258604 0
0 0.0287671 0 0 0.0258604 0

Notes:

• See http://www.cacr.caltech.edu/~slombey/asci/vtk/vtk_formats.simple.html for details on the vtk format.

A polygonal ("polydata") mesh with just lines, not vertices or polygons

# vtk DataFile Version 3.0
vtk output
ASCII
DATASET POLYDATA
POINTS 4 float
0 0 0
9 0 0
0 9 0
9 0 9
LINES 5 15
2 0 1
2 1 3
2 3 2
2 2 0
2 0 3
CELL_DATA 5
scalars cellvar float
LOOKUP_TABLE default
2.0 2.4 2.1 2.2 2.3
POINT_DATA 4
scalars pointvar float
LOOKUP_TABLE default
1.2 1.3 1.4 1.5

A water molecule, using the polydata format

# vtk DataFile Version 3.0
vtk output
ASCII
DATASET POLYDATA

POINTS 3 float
1.0 0.5 1.5
0.2 0.1 0.8
0.4 0.2 2.3

LINES 2 6
2 0 1
2 0 2

VERTICES 3 6
1 0
1 1
1 2

POINT_DATA 3
SCALARS element float
LOOKUP_TABLE default
8 1 1
SCALARS somefield float
LOOKUP_TABLE default
0.687 0.262 0.185

Notes:

• the bonds are the LINES; these are optional for molecular data, and you can always use a CreateBonds operator to create them at runtime inside VisIt
• you must specify VERTICES if you want point elements; for molecular data, this is obviously what you want to do for atoms
• call the atomic number array "element" to help VisIt find it automatically

See Also

• The VisItWriter tiny library to write VTK files
• Time and Cycle in VTK files
• Materials in VTK files