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

9. File formats

This chapter describes the file formats that cannot be modified by the user. These formats have a version number (currently 1.2), independent of the Gmsh version number (currently 1.51).

All non-parsed file formats have sections enclosed between $KEY and $ENDKEY tags.

9.1 Gmsh mesh file format  
9.2 Gmsh ASCII post-processing file format  
9.3 Gmsh binary post-processing file format  
9.4 Gmsh parsed post-processing file format  
9.5 Gmsh node ordering  


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

9.1 Gmsh mesh file 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, 1 edge).
2
Triangle (3 nodes, 3 edges).
3
Quadrangle (4 nodes, 4 edges).
4
Tetrahedron (4 nodes, 6 edges, 4 faces).
5
Hexahedron (8 nodes, 12 edges, 6 faces).
6
Prism (6 nodes, 9 edges, 5 faces).
7
Pyramid (5 nodes, 8 edges, 5 faces).
15
Point (1 node).

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 (separated by white space, without commas).


[ < ] [ > ]   [ << ] [ 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, 1 edge).
2
Triangle (3 nodes, 3 edges).
3
Quadrangle (4 nodes, 4 edges).
4
Tetrahedron (4 nodes, 6 edges, 4 faces).
5
Hexahedron (8 nodes, 12 edges, 6 faces).
6
Prism (6 nodes, 9 edges, 5 faces).
7
Pyramid (5 nodes, 8 edges, 5 faces).
15
Point (1 node).

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 (separated by white space, without commas).


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

9.2 Gmsh 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.3 Gmsh binary post-processing file format

The binary post-processing file format is the same as the ASCII file format described in 9.2 Gmsh 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 the beginning of 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.4 Gmsh parsed post-processing file format

For relatively small data sets Gmsh provides an additional post-processing format, which is read by Gmsh's script parser. You can thus, for example, embed small post-processing views directly into your geometrical descriptions (see e.g. 7.4 `t4.geo'). This format is also useful for testing purposes: its syntax is very permissive, and you can easily generate it by hand or on the fly. The format of the parsed post-processing file is the following:

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

The 26 objects that can be displayed are the same as in the ASCII or binary post-processing file formats:

 
                    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

For historical reasons, contrary to the ASCII and binary post-processing file formats, the coordinates are given `by node', i.e.:

The values are given in the same order as for the ASCII and binary post-processing file formats.


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

9.5 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:       1 -> 3                  
   |                   3:       2 -> 3                  
   |                           
   3              face 1: edges 1 -2 3   nodes 1 2 3
   |\        
   | \       
   |__\___u                    
   1   2                       

 
Quadrangle:
                  edge 1: nodes 1 -> 2 
        v              2:       1 -> 4                    
        |              3:       2 -> 3                    
     4--|--3           4:       3 -> 4 
     |  |  |     
   -----------u   face 1: edges 1 -2 3 4   nodes 1 2 3 4
     |  |  |     
     1--|--2      
        |         

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

 
Hexahedron:
                  edge 1: nodes 1 -> 2
        v              2:       1 -> 4
        |              3:       1 -> 5
        |              4:       2 -> 3
   4----|--3           5:       2 -> 6
   |\   |  |\          6:       3 -> 4
   | 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         
                  face 1: edges  1 -3  5 -9    nodes 1 2 6 5
                       2:       -1  2 -4 -6          1 4 3 2  
                       3:       -2  3 -8  10         1 5 8 4
                       4:        4 -5  7 -11         2 3 7 6
                       5:        6 -7  8 -12         3 4 8 7
                       6:        9 -10 11 12         5 6 7 8

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

 
Pyramid:
                  edge 1: nodes 1 -> 2
        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              
           \      face 1: edges  1  5 -3       nodes 1 2 5  
            \          2:        2 -6 -4 -1          1 4 3 2
             w         3:        3 -8 -2             1 5 4  
                       4:        4  7 -5             2 3 5  
                       5:        6  8 -7             3 4 5  


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

Back to geuz.org/gmsh