Skip to article

 

VTK File Formats

VTK file formats

The Visualization Toolkit provides a number of source and writer objects for reading and writing popular data file formats. The Visualization Toolkit also provides some of its own file formats. The main reason for creating another data file format is to provide a consistent data representation scheme for different types of data sets and to provide an easy method of transferring data between programs. Where possible, we recommend using more widely used formats. But if this is not possible, you can use the Visualization Toolkit formats described here instead. Note that these formats may not be supported by many other tools.

There are two different styles of file formats available in VTK. The simplest are the legacy serial formats, which are easy to read and write both manually and programmatically. However, these formats are less flexible than the XML-based file formats described later in this section. XML formats support random access, parallel I/O, and portable data compression, and are preferred over the sequential VTK file formats when possible.

Simple "Legacy" formats

Legacy VTK file formats consist of 5 main parts.

An overview of the file format is shown in Figure 1. The first three parts are mandatory, and the remaining two are optional. This gives you the flexibility of mixing and matching dataset attributes and geometry, either by manipulating operating system files or by using VTK filters to combine data. Keywords are case-insensitive and can be separated by spaces. Before describing the data file formats, please note the following.

Binary Files. Binary files in VTK are portable between different computer systems, as long as you follow two rules. First, make sure the byte order of the data is correct, and second, make sure the length of each data type is consistent.

Most of the time, VTK manages the byte order of binary files for you. When you write a binary file on one computer and read it from another computer, the bytes representing the data will be automatically rearranged as needed. For example, binary files written on a Sun are stored in big endian order, while files on a PC are stored in little endian order. As a result, files written on a Sun workstation require byte swapping when read on a PC. (See the vtkByteSwap class for implementation details.) The VTK data files described here are written in big endian form.

However, some file formats do not explicitly define the byte order form. You will find that data read or written by external programs or the vtkVolume16Reader, vtkMCubesReader, and vtkMCubesWriter classes may have a different byte order depending on the source system. In such cases, VTK allows you to specify the byte order using methods.

SetDataByteOrderToBigEndian()

SetDataByteOrderToLittleEndian()

Another problem with binary files is that systems may use different numbers of bytes to represent an integer or other native type. For example, some 64-bit systems will represent an integer with 8 bytes, while others will represent an integer with 4 bytes. Currently, the Visualization Toolkit cannot handle transferring binary files between systems with incompatible data lengths. In this case, use ASCII file formats instead.

Dataset format. Visualization Toolkit supports five different dataset formats: structured points, structured grid, rectangular grid, unstructured grid, and polygonal data. Data with implicit topology (structured data such as vtkImageData and vtkStructuredGrid) is ordered with x increasing fastest, then y, then z. These formats are as follows.

Dataset attribute format. Visualization Toolkit supports the following dataset attributes: scalars (one to four components), vectors, normals, texture coordinates (1D, 2D, and 3D), 3×3 tensors, and field data. Additionally, you can define a lookup table that uses the RGBA color specification associated with scalar data. Dataset attributes are supported for both points and cells.

Each attribute data type has a dataName associated with it. This is a character string (without embedded spaces) used to identify a particular piece of data. The dataName is used by VTK readers to extract data. As a result, more than one attribute of the same type may be included in a file. For example, two different scalar fields defined for data set points, pressure and temperature, may be contained in a single file. (If the corresponding dataName is not specified in the VTK reader, the first data of this type is extracted from the file).

Examples. The first example is a cube represented by six polygonal faces. We define a one-component scalar, normals, and field data on the six faces. There are scalar data associated with eight vertices. A lookup table of eight colors associated with point scalars is also defined. IMPORTANT! The file must have the extension .vtk, not .VTK, otherwise a read error will occur.

The following example is for a 3×4×5 volume. Since the lookup table is not defined, the user must either create one in VTK or the default lookup table will be used.

The third example is an unstructured mesh containing twelve of the nineteen VTK cell types (see Figure 2 and Figure 3). The file contains scalar and vector data.

Figure 2 Linear cell types found in VTK. Use the CellType.h include file to control cell types.

Figure 3 Nonlinear cell types found in VTK

The fourth and final example is data represented as a field. You can also see "Working with Field Data" to learn how to manipulate this data. (The data file shown below can be found in its entirety in $VTK_DATA_ROOT/Data/financial.vtk).

In this example, the field is represented using six arrays. Each array has one component and 3188 tuples. Five of the six arrays are of type float, and the last array is of type unsigned_short.

Additional examples are available in the data catalog.

XML File Formats

VTK provides another set of data formats using XML syntax. Although these formats are much more complex than the original VTK format described earlier (see "Simple Legacy Formats"), they support many more features. The main motivation for their development was to simplify streaming data and parallel I/O. Some features of the format include support for compression, portable binary encoding, random access, big endian and little endian byte order, multi-file representation of fragmented data, and new file extensions for different types of VTK data sets. XML also provides many features, especially the ability to extend the file format with application-specific tags. There are two types of VTK XML data files: parallel and serial, as described below.

In XML format, VTK datasets are classified into one of two categories.

By convention, each data type and file type is mapped to a specific file extension. The types and corresponding extensions are:

All VTK XML file types are valid XML documents.* The document-level element is VTKFile:

Element attributes:

type — The file type (the marked items in the previous list).

version — The file version number in "major.minor" format.

byte_order — The machine byte order in which the data is stored. This is either "BigEndian" or "LittleEndian".

compressor — Some data in the file may be compressed. Specifies the vtkDataCompressor subclass that was used to compress the data.

Inside the VTKFile element is an element whose name corresponds to the data format type (i.e. the type attribute). This element describes the topology of the data set and differs for serial and parallel formats, which are described as follows.

Sequential XML file formats. The VTKFile element contains one element whose name corresponds to the type of dataset the file describes. We call this a dataset element, which is one of ImageData, RectilinearGrid, StructuredGrid, PolyData, or UnstructuredGrid. A dataset element contains one or more Piece elements, each describing a portion of the dataset. Together, the dataset element and the Piece elements define the entire dataset.

Each dataset part must define the geometry (points and cells) of that part, along with the data associated with each point or cell. The geometry is specified differently for each dataset type, but each part of each dataset contains PointData and CellData elements that define the data for each point and cell in the part. The general structure for each sequential data set format is as follows:

Each data set describes the data associated with its points and cells using the XML elements PointData and CellData as follows:

VTK allows you to associate an arbitrary number of data arrays with the points and cells of a data set. Each data array is described by a DataArray element, which, among other things, gives each array a name.

The following PointData and CellData attributes are used to specify the active arrays by name:

Scalars — The name of the active scalar array, if any.

Vectors — The name of the active vector array, if any.

Normals — The name of the active normal array, if any.

Tensors — The name of the active tensor array, if any.

TCoords — The name of the active texture coordinate array, if any.

Some data sets describe their points and cells using various combinations of the following common elements:

All data and geometry specifications use DataArray elements to describe their actual contents as follows:

The attributes of DataArray elements are described as follows:

type — The data type of one component of the array. It is one of Int8, UInt8, Int16, UInt16, Int32, UInt32, Int64, UInt64, Float32, Float64. Note: 64-bit integer types are supported only if VTK_USE_64BIT_IDS (CMake variable — see "CMake") is enabled or the platform is 64-bit.

Name — The name of the array. This is usually a short description of the data stored in the array.

NumberOfComponents — The number of components per value in the array.

format — The way the data values ​​themselves are stored in the file. This is "ascii", "binary", or "appended".

offset — If the format attribute is "appended", this specifies the offset from the start of the appended data section to the start of this array's data. The format attribute selects one of three ways to store the data values: format=”ascii” — The data is listed in ASCII directly inside the DataArray element. Spaces are used for separation.

format=”binary” — The data is encoded in base64 and listed contiguously inside the DataArray element. The data may also be compressed before encoding in base64. The byte order of the data corresponds to that specified in the byte_order attribute of the VTKFile element.

format=”appended” — Data is stored in the “appended data” section. Since many DataArray elements may store their data in this section, the offset attribute is used to specify where each DataArray’s data starts. This format is used by default by VTK writers.

The appended data section is stored in the AppendedData element, which is nested in the VTKFile after the dataset element:

The appended data section starts with the first character after the underscore inside the AppendedData element. The underscore is not part of the data, but is always present. The data in this section is always in binary form, but may be compressed and/or base64 encoded. The byte order of the data corresponds to that specified by the byte_order attribute of the VTKFile element. The data of each DataArray is stored contiguously and is appended immediately after the data of the previous DataArray, without a separator. The offset attribute of a DataArray specifies the offset of the file position from the first character after the underscore to the beginning of its data.

Parallel File Formats. Parallel file formats do not actually store any data in the file. Instead, the data is broken up into pieces, each of which is stored in a sequential file of the same type of data set.

The VTKFile element contains a single element whose name matches the type of dataset the file describes, but with a "P" prefix. We call this a parallel dataset element, which is one of PImageData, PRectilinearGrid, PStructuredGrid, PPolyData, or PUnstructuredGrid.

The parallel dataset element and those nested within it specify the types of data arrays used to store points, point data, and cell data (the type of arrays used to store cells is fixed by VTK). The element does not actually contain any data, but instead includes a list of Piece elements that specify the source from which each piece should be read. Individual parts are stored in the corresponding serial file format. The parallel file must specify the type and structure information so that readers can update the pipeline information without actually reading the part files.

The general structure for each parallel dataset format is as follows:

Each data set uses PPointData and PCellData elements to describe the types of data arrays associated with its points and cells.

For data sets that require point specification, the following elements mirror their counterparts in the sequential file format:

All data and geometry specifications use PDataArray elements to describe data array types:

Example. Below is a complete example defining a vtkPolyData, representing a cube with some scalar data on its points and faces.