Documentation: VTK-file format
Prelude
The VTK-file format is relatively easy to implement, especially if good and simple examples are provided and good documentation is availible. Basic explanation of the format based on VisuSimples example
VTK-files come in the filetypes ASCII or binary. We - being sane minded - are only interested in the ASCII format. Also VTK-data can be stored in two types, an easy to implement format: legacy or XML. (Being sane minded) we pick the legacy format. (Make no mistake, the XML format is powerful but it simply requires to much overhead for our needs.)

A VTK-file in ASCII using the legacy format consists of five parts.
  • Header: describing the basics of the file
  • Pointdata: all points in the grid geometry
  • Celldata: all cells in the grid geometry based on the point ids
  • Pointdatasets: a block consisting of datasets based on the grid points
  • Celldatasets: a block consisting of datasets based on the grid cells
In the following we describe each of these five parts and how we use them. This is not a complete documentation of the format, more it's a quickstart description of a correct subformat so that you can easily make your own VTK-files.
To each part we write down how many lines are expected. This number is not quite correct, in most of the cases the data values (be it the coordinates, the cell-ids or the cell-types) don't have to be separated linewise. This a convention we use to make reading, verifying, generating and checking VTK-files a bit easier.

The following description is based on an example that is provided in VisuSimples examples directory: example.vtk.
top next
lines: 5
The first line simply describes the version number. The second line can contain what ever you want, for example a bit of information about who generated the file. The third simply determines the filetype: ASCII. The forth describes what kind of data VTK can expected in the rest of the file. There are five different types: Three structured types (STRUCTURED_POINTS, STRUCTURED_GRID, RECTILINEAR_GRID) in which all points somehow lineup or match, not very usable. One surface type (POLYDATA) which doesn't contain volume, not what we need. And finally UNSTRUCTURED_GRID which describes arbitrary combinations of all availible cells types. This is what we like.
The fifth line is empty.
# vtk DataFile Version 3.1 this is an example file created for VisuSimple ASCII DATASET UNSTRUCTURED_GRID
previous top next
lines: #nr_points+2
The first line notes how many points there will be ("9") and in which format they'll be supplied (usually "FLOAT"). Nine lines follow, each line containing the xyz-coordinates of a point.
Based on this list, each point is assigned an id. The first point has id 0, the second point id 1, and so forth, till the last point with id 8.
The last line is empty.
POINTS 9 FLOAT 0 0 0 0 1 0 0 2 0 1 2 0 1 1 0 1 0 0 2 0 0 2 1 0 2 2 0
previous top next
lines: #nr_cells+5
The first line notes how many cells there will be ("4") and how many numbers total will be supplied in the CELLS-block ("20"). Four lines follow, each line containing the information for a cell.
Each cell line starts with a number saying how many point-ids are to be read in that line followed by the list of those point-ids.
Based on this list, each cell is assigned an id. The first cell has id 0, the second id 1, and so forth, till the last cell with id 3.
After all cells have been given points, the cell types have to be set.
This is done in the CELL_TYPES-block.
The CELL_TYPES-line says how many cell-types are to be set. This number has to be the same as the number in the CELLS-line ("4"). The following line is a list of cell-types that are assigned to all cells. The first cell is of type "9", so ist the second cell and so forth.
(Here're two screenshots (screenshot 1, screenshot 2) of all the cell-types documented in the official VTK file format documentation.) Cell-type "9" is a simple 4-point flat polygon (aka a quad).
The last line is empty.
CELLS 4 20 4 0 5 4 1 4 1 4 3 2 4 5 6 7 4 4 4 7 8 3 CELL_TYPES 4 9 9 9 9
previous top next
lines: #nr_datasets*(#nr_points +3)+1
In this segment of the file, datasets that are associated to the points of the grid can be given. The data can either be of scalar- or vector-type.
The first line initiates that pointdata will be supplied in the following lines, the "9" simply says how many points per dataset there are (yes, it's redundant).
We seperate each of the datasets with an empty line. Each of the datasets has two leading lines followed by "9" lines of data.
The first dataset line specifies if "SCALAR"- or "VECTOR"-data will follow. It also assigns a name to the dataset ("HorizontalSpeed" , "Temperature"). The "FLOAT" specifies the format of the data. "FLOAT" will most likely always be good enough.
The second line has to do with color tables and "LOOKUP_TABLE default" will most likely be the only setting you will ever need.
The following "9" lines will either contain per line a scalar-value or a vector-value (consisting of 3 numbers).
The last line is empty.
POINT_DATA 9 SCALARS HorizontalSpeed FLOAT LOOKUP_TABLE default 0 0 0 1 2 1 0 0 0 SCALARS Temperature FLOAT LOOKUP_TABLE default 1 1.1 1.2 2.1 2.5 3.5 1.3 1.4 1.6
previous top
lines: #nr_datasets*(#nr_cells +3)+1
Exactly the same setup as the point-data, only this data is assigned to cells.
CELL_DATA 4 SCALARS Cell_Temperature FLOAT LOOKUP_TABLE default 0 1 2 1
That's it! There's no end-of-file command or comment.
This description is based on an example that is provided in VisuSimples examples directory: example.vtk.