[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9. File formats

This chapter describes the file formats that cannot be modified by the user. (These formats have version numbers that are independent of the Gmsh version number.)

All non-parsed file formats have sections enclosed between $Key and $EndKey tags.

9.1 Gmsh mesh file formats  
9.2 Gmsh post-processing file formats  
9.3 Gmsh node ordering  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1 Gmsh mesh file formats

Please note that the list of nodes and elements in Gmsh's mesh files do not have to be dense or ordered (i.e., the node and element numbers do not have to be given in a consecutive or even an ordered way). A sample C++ program to transform the formats so that all lists are dense and ordered is available in the source distribution (`utils/misc/mshsort.cpp'). This program is also a good example on how to read and write files in the `.msh' format.

9.1.1 Version 1.0  
9.1.2 Version 2.0  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1.1 Version 1.0

The `.msh' file format, version 1.0, is Gmsh's old native mesh file format, now superseeded by the format described in 9.1.2 Version 2.0.

In the `.msh' file format, version 1.0, the file is divided in two sections, defining the nodes ($NOD-$ENDNOD) and the elements ($ELM-$ENDELM) in the mesh:

 
$NOD
number-of-nodes
node-number x-coord y-coord z-coord
...
$ENDNOD
$ELM
number-of-elements
elm-number elm-type reg-phys reg-elem number-of-nodes node-number-list
...
$ENDELM

where

number-of-nodes
is the number of nodes in the mesh.

node-number
is the number (index) of the n-th node in the mesh. Note that the node-numbers do not have to be given in a consecutive (or even an ordered) way.

x-coord y-coord z-coord
are the floating point values giving the X, Y and Z coordinates of the n-th node.

number-of-elements
is the number of elements in the mesh.

elm-number
is the number (index) of the n-th element in the mesh. Note that the elm-numbers do not have to be given in a consecutive (or even an ordered) way.

elm-type
defines the geometrical type of the n-th element:
1
Line (2 nodes).
2
Triangle (3 nodes).
3
Quadrangle (4 nodes).
4
Tetrahedron (4 nodes).
5
Hexahedron (8 nodes).
6
Prism (6 nodes).
7
Pyramid (5 nodes).
8
Second order line (3 nodes: 2 associated with the vertices and 1 with the edge).
9
Second order triangle (6 nodes: 3 associated with the vertices and 3 with the edges).
10
Second order quadrangle (9 nodes: 4 associated with the vertices, 4 with the edges and 1 with the face).
11
Second order tetrahedron (10 nodes: 4 associated with the vertices and 6 with the edges).
12
Second order hexahedron (27 nodes: 8 associated with the vertices, 12 with the edges, 6 with the faces and 1 with the volume).
13
Second order prism (18 nodes: 6 associated with the vertices, 9 with the edges and 3 with the quadrangular faces).
14
Second order pyramid (14 nodes: 5 associated with the vertices, 8 with the edges and 1 with the quadrangular face).
15
Point (1 node).
See below for the ordering of the nodes.

reg-phys
is the number of the physical entity to which the element belongs.

reg-elem
is the number of the elementary entity to which the element belongs.

number-of-nodes
is the number of nodes for the n-th element. This is redundant, but kept for backward compatibility.

node-number-list
is the list of the number-of-nodes node numbers of the n-th element. The ordering of the nodes is given in 9.3 Gmsh node ordering; for second order elements, the first order nodes are given first, followed by the nodes associated with the edges, followed by the nodes associated with the quadrangular faces (if any), followed by the nodes associated with the volume (if any). The ordering of these additional nodes follows the ordering of the edges and quadrangular faces given in 9.3 Gmsh node ordering.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.1.2 Version 2.0

Version 2.0 of the `.msh' file format is Gmsh's new native mesh file format. It is very similar to the old one (see section 9.1.1 Version 1.0), but is more general: it contains information about itself and allows to associate an arbitrary number of integer tags with each element.

The `.msh' file format, version 2.0, is divided in three sections, defining the file format ($MeshFormat-$EndMeshFormat), the nodes ($Nodes-$EndNodes) and the elements ($Elements-$EndElements) in the mesh:

 
$MeshFormat
2.0 file-type data-size
$EndMeshFormat
$Nodes
number-of-nodes
node-number x-coord y-coord z-coord
...
$EndNodes
$Elements
number-of-elements
elm-number elm-type number-of-tags < tag > ... node-number-list
...
$EndElements

where

file-type
is an integer equal to 0 in the ASCII file format.

data-size
is an integer equal to the size of the floating point numbers used in the file (usually, data-size = sizeof(double)).

number-of-nodes
is the number of nodes in the mesh.

node-number
is the number (index) of the n-th node in the mesh. Note that the node-numbers do not have to be given in a consecutive (or even an ordered) way.

x-coord y-coord z-coord
are the floating point values giving the X, Y and Z coordinates of the n-th node.

number-of-elements
is the number of elements in the mesh.

elm-number
is the number (index) of the n-th element in the mesh. Note that the elm-numbers do not have to be given in a consecutive (or even an ordered) way.

elm-type
defines the geometrical type of the n-th element:
1
Line (2 nodes).
2
Triangle (3 nodes).
3
Quadrangle (4 nodes).
4
Tetrahedron (4 nodes).
5
Hexahedron (8 nodes).
6
Prism (6 nodes).
7
Pyramid (5 nodes).
8
Second order line (3 nodes: 2 associated with the vertices and 1 with the edge).
9
Second order triangle (6 nodes: 3 associated with the vertices and 3 with the edges).
10
Second order quadrangle (9 nodes: 4 associated with the vertices, 4 with the edges and 1 with the face).
11
Second order tetrahedron (10 nodes: 4 associated with the vertices and 6 with the edges).
12
Second order hexahedron (27 nodes: 8 associated with the vertices, 12 with the edges, 6 with the faces and 1 with the volume).
13
Second order prism (18 nodes: 6 associated with the vertices, 9 with the edges and 3 with the quadrangular faces).
14
Second order pyramid (14 nodes: 5 associated with the vertices, 8 with the edges and 1 with the quadrangular face).
15
Point (1 node).
See below for the ordering of the nodes.

number-of-tags
gives the number of tags for the n-th element. By default, Gmsh generates meshes with two tags and reads files with an arbitrary number of tags: see below.

tag
is an integer tag associated with the n-th element. By default, the first tag is the number of the physical entity to which the element belongs; the second is the number of the elementary geometrical entity to which the element belongs; the third is the number of a mesh partition to which the element belongs.

node-number-list
is the list of the node numbers of the n-th element. The ordering of the nodes is given in 9.3 Gmsh node ordering; for second order elements, the first order nodes are given first, followed by the nodes associated with the edges, followed by the nodes associated with the quadrangular faces (if any), followed by the nodes associated with the volume (if any). The ordering of these additional nodes follows the ordering of the edges and quadrangular faces given in 9.3 Gmsh node ordering.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2 Gmsh post-processing file formats

Gmsh can read and write data sets in three different file formats: the "parsed", "ASCII" and "binary" file formats. The parsed format is the oldest and most flexible, but also the slowest to read/write. The ASCII and binary formats are less flexible but allow for faster read/write operations, which is useful for (very) large data sets.

Gmsh can convert any format to any other, either in a script (cf. Save View and PostProcessing.Format in 6.1 Post-processing commands, and 6.3 Post-processing options, respectively) or in the graphical user interface (using the `View->Save as' menu).

9.2.1 Parsed post-processing file format  
9.2.2 ASCII post-processing file format  
9.2.3 Binary post-processing file format  


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2.1 Parsed post-processing file format

Gmsh's oldest post-processing format ("parsed") is read by Gmsh's script parser (see also 6.1 Post-processing commands). You can thus, for example, embed parsed post-processing views directly into your geometrical descriptions (see, e.g., 7.4 `t4.geo').

The parsed format is very powerful, since all the values are expressions, and it can be easily generated "on-the-fly", as there is no header containing a priori information on the size of the data set. Its syntax is also very permissive, which makes it ideal for testing purposes. Its main disadvantage resides in the overhead introduced by the parser, which makes loading a view in parsed format slower than loading a view in ASCII or binary format. This is only a disadvantage for very large data sets, tough.

A post-processing view in parsed format is defined as follows (there can be one or more views in the same file):

 
View "string" {
  type ( list-of-coords ) { list-of-values };
  ...
};

The 26 objects that can be displayed are:

 
                    type  #list-of-coords  #list-of-values
------------------------------------------------------------
scalar point        SP    3            1  * nb-time-steps
vector point        VP    3            3  * nb-time-steps
tensor point        TP    3            9  * nb-time-steps
scalar line         SL    6            2  * nb-time-steps
vector line         VL    6            6  * nb-time-steps
tensor line         TL    6            18 * nb-time-steps
scalar triangle     ST    9            3  * nb-time-steps
vector triangle     VT    9            9  * nb-time-steps
tensor triangle     TT    9            27 * nb-time-steps
scalar quadrangle   SQ    12           4  * nb-time-steps
vector quadrangle   VQ    12           12 * nb-time-steps
tensor quadrangle   TQ    12           36 * nb-time-steps
scalar tetrahedron  SS    12           4  * nb-time-steps
vector tetrahedron  VS    12           12 * nb-time-steps
tensor tetrahedron  TS    12           36 * nb-time-steps
scalar hexahedron   SH    24           8  * nb-time-steps
vector hexahedron   VH    24           24 * nb-time-steps
tensor hexahedron   TH    24           72 * nb-time-steps
scalar prism        SI    18           6  * nb-time-steps
vector prism        VI    18           18 * nb-time-steps
tensor prism        TI    18           54 * nb-time-steps
scalar pyramid      SY    15           5  * nb-time-steps
vector pyramid      VY    15           15 * nb-time-steps
tensor pyramid      TY    15           45 * nb-time-steps
text 2d             T2    4            arbitrary
text 3d             T3    5            arbitrary

The coordinates are given `by node'(7), i.e.:

The values are given by time step, by node and by component, i.e.:
 
comp1-node1-time1, comp2-node1-time1, comp3-node1-time1,
comp1-node2-time1, comp2-node2-time1, comp3-node2-time1,
comp1-node3-time1, comp2-node3-time1, comp3-node3-time1,
comp1-node1-time2, comp2-node1-time2, comp3-node1-time2,
comp1-node2-time2, comp2-node2-time2, comp3-node2-time2,
comp1-node3-time2, comp2-node3-time2, comp3-node3-time2,
...


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2.2 ASCII post-processing file format

The ASCII post-processing file is divided in several sections: one format section, enclosed between $PostFormat-$EndPostFormat tags, and one or more post-processing views, enclosed between $View-$EndView tags:

 
$PostFormat
1.2 file-type data-size
$EndPostFormat
$View
view-name nb-time-steps
nb-scalar-points nb-vector-points nb-tensor-points
nb-scalar-lines nb-vector-lines nb-tensor-lines
nb-scalar-triangles nb-vector-triangles nb-tensor-triangles
nb-scalar-quadrangles nb-vector-quadrangles nb-tensor-quadrangles
nb-scalar-tetrahedra nb-vector-tetrahedra nb-tensor-tetrahedra
nb-scalar-hexahedra nb-vector-hexahedra nb-tensor-hexahedra
nb-scalar-prisms nb-vector-prisms nb-tensor-prisms
nb-scalar-pyramids nb-vector-pyramids nb-tensor-pyramids
nb-text2d nb-text2d-chars nb-text3d nb-text3d-chars
time-step-values
< scalar-point-value > ...
< vector-point-value > ...
< tensor-point-value > ...
< scalar-line-value > ...
< vector-line-value > ...
< tensor-line-value > ...
< scalar-triangle-value > ...
< vector-triangle-value > ...
< tensor-triangle-value > ...
< scalar-quadrangle-value > ...
< vector-quadrangle-value > ...
< tensor-quadrangle-value > ...
< scalar-tetrahedron-value > ...
< vector-tetrahedron-value > ...
< tensor-tetrahedron-value > ...
< scalar-hexahedron-value > ...
< vector-hexahedron-value > ...
< tensor-hexahedron-value > ...
< scalar-prism-value > ...
< vector-prism-value > ...
< tensor-prism-value > ...
< scalar-pyramid-value > ...
< vector-pyramid-value > ...
< tensor-pyramid-value > ...
< text2d > ... < text2d-chars > ...
< text3d > ... < text3d-chars > ...
$EndView

where

file-type
is an integer equal to 0 in the ASCII file format.

data-size
is an integer equal to the size of the floating point numbers used in the file (usually, data-size = sizeof(double)).

view-name
is a string containing the name of the view (max. 256 characters).

nb-time-steps
is an integer giving the number of time steps in the view.

nb-scalar-points
nb-vector-points
...
are integers giving the number of scalar points, vector points, ... in the view.

nb-text2d
nb-text3d
are integers giving the number of 2D and 3D text strings in the view.

nb-text2d-chars
nb-text3d-chars
are integers giving the total number of characters in the 2D and 3D strings.

time-step-values
is a list of nb-time-steps double precision numbers giving the value of the time (or any other variable) for which an evolution was saved.

scalar-point-value
vector-point-value
...
are lists of double precision numbers giving the node coordinates and the values associated with the nodes of the nb-scalar-points scalar points, nb-vector-points vector points, ..., for each of the time-step-values.

For example, vector-triangle-value is defined as:
 
coord1-node1 coord1-node2 coord1-node3
coord2-node1 coord2-node2 coord2-node3
coord3-node1 coord3-node2 coord3-node3
comp1-node1-time1 comp2-node1-time1 comp3-node1-time1
comp1-node2-time1 comp2-node2-time1 comp3-node2-time1
comp1-node3-time1 comp2-node3-time1 comp3-node3-time1
comp1-node1-time2 comp2-node1-time2 comp3-node1-time2
comp1-node2-time2 comp2-node2-time2 comp3-node2-time2
comp1-node3-time2 comp2-node3-time2 comp3-node3-time2
...

text2d
is a list of 4 double precision numbers:
 
coord1 coord2 style index
where coord1 and coord2 give the coordinates of the leftmost element of the 2D string in screen coordinates, index gives the starting index of the string in text2d-chars and style is currently unused.

text2d-chars
is a list of nb-text2d-chars characters. Substrings are separated with the `^' character (which is a forbidden character in regular strings).

text3d
is a list of 5 double precision numbers
 
coord1 coord2 coord3 style index
where coord1, coord2 and coord3 give the coordinates of the leftmost element of the 3D string in model (real world) coordinates, index gives the starting index of the string in text3d-chars and style is currently unused.

text3d-chars
is a list of nb-text3d-chars chars. Substrings are separated with the `^' character.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.2.3 Binary post-processing file format

The binary post-processing file format is the same as the ASCII file format described in 9.2.2 ASCII post-processing file format, except that:

  1. file-type equals 1.
  2. all lists of floating point numbers and characters are written in binary format
  3. there is an additional integer, of value 1, written before time-step-values. This integer is used for detecting if the computer on which the binary file was written and the computer on which the file is read are of the same type (little or big endian).

Here is a pseudo C code to write a post-processing file in binary format:

 
int one = 1;

fprintf(file, "$PostFormat\n");
fprintf(file, "%g %d %d\n", 1.2, 1, sizeof(double));
fprintf(file, "$EndPostFormat\n");
fprintf(file, "$View\n");
fprintf(file, "%s %d "
  "%d %d %d "
  "%d %d %d "
  "%d %d %d "
  "%d %d %d "
  "%d %d %d "
  "%d %d %d "
  "%d %d %d "
  "%d %d %d "
  "%d %d %d %d\n", 
  view-name, nb-time-steps,
  nb-scalar-points, nb-vector-points, nb-tensor-points,
  nb-scalar-lines, nb-vector-lines, nb-tensor-lines,
  nb-scalar-triangles, nb-vector-triangles, nb-tensor-triangles,
  nb-scalar-quadrangles, nb-vector-quadrangles, nb-tensor-quadrangles,
  nb-scalar-tetrahedra, nb-vector-tetrahedra, nb-tensor-tetrahedra,
  nb-scalar-hexahedra, nb-vector-hexahedra, nb-tensor-hexahedra,
  nb-scalar-prisms, nb-vector-prisms, nb-tensor-prisms,
  nb-scalar-pyramids, nb-vector-pyramids, nb-tensor-pyramids,
  nb-text2d, nb-text2d-chars, nb-text3d, nb-text3d-chars);
fwrite(&one, sizeof(int), 1, file);
fwrite(time-step-values, sizeof(double), nb-time-steps, file);
fwrite(all-scalar-point-values, sizeof(double), ..., file);
...
fprintf(file, "\n$EndView\n");
In this pseudo-code, all-scalar-point-values is the array of double precision numbers containing all the scalar-point-value lists, put one after each other in order to form a long array of doubles. The principle is the same for all other kinds of values.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.3 Gmsh node ordering

For all mesh and post-processing file formats, the reference elements are defined as follows:

 
Point:
        v
        |
        |
   -----1-----u
        |
        |

 
Line:
                  edge 1: nodes 1 2
        v
        |
        |
   --1-----2--u
        |
        |

 
Triangle:
                  edge 1: nodes 1 2
   v                   2:       2 3
   |                   3:       3 1
   |
   3
   |\
   | \
   |__\___u
   1   2

 
Quadrangle:
                  edge 1: nodes 1 2   quad. face 1: nodes 1 2 3 4
        v              2:       2 3
        |              3:       3 4
     4--|--3           4:       4 1
     |  |  |
   -----------u
     |  |  |
     1--|--2
        |

 
Tetrahedron:
                  edge 1: nodes 1 2
   v                   2:       2 3
   |                   3:       3 1
   |                   4:       4 1
   |                   5:       4 3
   3                   6:       4 2
   |\                
   | \
   |__\2_____u
   1\ /
     \4
      \
       w

 
Hexahedron:
                  edge 1: nodes 1 2   quad. face 1: nodes 1 2 3 4
        v              2:       1 4              2:       1 2 5 6
        |              3:       1 5              3:       1 4 5 8
        |              4:       2 3              4:       2 3 6 7
   4----|--3           5:       2 6              5:       3 4 7 8
   |\   |  |\          6:       3 4              6:       5 6 7 8
   | 8-------7         7:       3 7
   | |   ----|---u     8:       4 8
   1-|---\-2 |         9:       5 6
    \|    \ \|        10:       5 8
     5-----\-6        11:       6 7
            \         12:       7 8
             w

 
Prism:
                  edge 1: nodes 1 2   quad. face 1: nodes 1 2 4 5
      v                2:       1 3              2:       1 3 4 6
    3 |                3:       1 4              3:       2 3 5 6
    |\|                4:       2 3
    | |                5:       2 5
    1_|2               6:       3 6
     \| 6              7:       4 5
      |_|_\___u        8:       4 6
       \|  \           9:       5 6
        4 __5
         \
          \
           w

 
Pyramid:
                  edge 1: nodes 1 2   quad. face 1: nodes 1 2 3 4
        v              2        1 4
        |              3        1 5
        |              4        2 3
    4---|---3          5        2 5
    | \ |  /|          6        3 4
    |  \ -/-|---u      7        3 5
    |  / 5\ |          8        4 5
    1/----\-2
           \
            \
             w


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

Back to geuz.org/gmsh