[[PageOutline]]

= Introduction = 

A mesh defines the vertices in 2D or 3D for a set of values of a [wiki:rp_xml_ele_field '<field>'] element.  The '''<mesh>'''
describes where each value of the [wiki:rp_xml_ele_field <field>] is found.  A mesh contains ''mesh elements'' that
indicate their connectivity (topology) and geometry.   

Meshes can be structured or unstructured grids.

Structured grids get their name from their nature of having a structure implicitly defined by the arrangement of the data. Structured grids have a basic rectangular matrix structure that makes storage and use easy as integer offsets (typically named ''i'', ''j'', and ''k'') can be used to access individual data points. Data points are arranged into rectangular or cubic structures by simply connecting them to their neighboring ''i'', ''j'', and ''k'' cells. For example, volume rendering requires a uniform rectangular grid.

Within structured grids there are several subtypes:
  * Cartesian or Uniform Grid
  * Rectilinear Grid
  * Curvilinear Grid 

Unstructured grids are the exact opposite of structured grids, where the connectivity between points must be explicitly defined for every set of points. This makes them significantly more difficult and complex, and the nice relationships between neighboring cells or edges is no longer automatic and must be constructed manually. However, they are much more flexible in their ability to define complex shapes because they have no constraints on their arrangement.

Unstructured grids are typically defined as points and cells. Cells are collections of points to define basic 2D or 3D primitives such as triangles, cubes, and tetrahedra.

Pick the one that most closely resembles the structure of your data set. 

= How to specify meshes = 

{{{
    <mesh>
        <about>
             <label>3D Mesh</label>
        </about>
        <dim>3</dim>
        <units>um</units>
        <hide>yes</hide>
        ...
    </mesh>
}}}

All meshes should have '''<dim>''', '''<units>''' and '''<hide>''' subelements.  
There are three basic formats for meshes, given by the subelements '''<grid>''', '''<unstructured>''', and '''<vtk>'''.  It is an error to have more than one in a '''<mesh>''' definition.

 '''<about><label>'''::
   This is the label for the mesh.  It's used to label the output if the mesh isn't hidden.
 '''<dim>'''::
   This defines the number of coordinates on each line of the points list.  It should be either "2" or "3". It is an error if this is missing from the mesh definition.
 '''<units>'''::
   This is the units for the X, Y, and Z coordinates of the mesh.  If one units name is present, then all axes use the same units.  Otherwise you can specify a units name for each axis.
 '''<labels>'''::
   This tag holds labels for the X, Y and Z axes which are used by the mesh viewer.  The labels for the 3 axes are separated by spaces, so double quotes must be used around a label with spaces.
 '''<hide>'''::  
   This value should be "yes" or "no".  This says if the mesh should be displayed as an output.  Typically this would be set to "yes" when using a '''<field>''' output referencing the mesh.  If you don't have a field and want to visualize the mesh without color mapping, set this to "no".
 '''<grid>'''::
     Defines a structured grid such as a rectangular or curvilinear grid. Structured grids have a very compact representation.  Cells and points are indexed by i,j,k of grid lines. Grid lines run through the entire domain.   
  '''<unstructured>'''::
     Defines an unstructured grid that is composed of cells: triangles, quads, tetrahedrons, hexahedrons, wedges, pyramids, etc. The cells can be all one type like triangles, or mixed.  Cells can be arbitrarily positioned.  Grid lines do not have to run through the entire domain (there can be holes).
  '''<vtk>'''::
     Uses the [http://www.vtk.org/VTK/img/file-formats.pdf VTK legacy file format] to describe the mesh. 
= Structured Grids =

A '''<grid>''' element describes a structured grid.  Structured grids include rectangular grids, non-uniform rectilinear grid, and curvilinear grid. 

== Uniform Rectangular Grid ==

[[Image(uniform_rectilinear_grid_2d.png, title="A uniform rectangular grid in 2D grid")]]               
[[Image(uniform_rectlinear_mesh.jpg, "A uniform rectangular grid in 3D")]]

In a uniform rectangular grid the grid lines run along each axis. You specify the minimum and maximum values, and the number of grid lines for each axis.  For 2D grids you specify the X and Y axes.  For 3D grids you specify the X, Y, and Z axes.

The subelements '''<xaxis>''', '''<yaxis>''', and '''<zaxis>''' are used to describe each axis. 
 '''<xaxis><min>'''::
   Minimum value for the X-axis. 
 '''<xaxis><max>'''::
   Maximum value for the X-axis. 
 '''<xaxis><numpoints>'''::
   Number points on the X-axis, including the minimum and maximum values.
 '''<yaxis><min>'''::
   Minimum value for the Y-axis. 
 '''<yaxis><max>'''::
   Maximum value for the Y-axis. 
 '''<yaxis><numpoints>'''::
   Number points on the Y-axis, including the minimum and maximum values.
 '''<zaxis><min>'''::
   Minimum value for the Z-axis. This is needed only for 3D grids.
 '''<zaxis><max>'''::
   Maximum value for the Z-axis. This is needed only for 3D grids.
 '''<zaxis><numpoints>'''::
   Number points on the Z-axis, including the minimum and maximum values. This is needed only for 3D grids.
 
Below is an example of 2D uniform rectangular grid.  

{{{
    <mesh>
        <dim>2</dim>
        <units>m</units>
        <hide>yes</hide>
        <grid>
            <xaxis>
                <min>0.0</min>
                <max>1.0</max>
                <numpoints>50</numpoints>
            </xaxis>
            <yaxis>
                <min>0.0</min>
                <max>1.0</max>
                <numpoints>50</numpoints>
            </yaxis>
        </grid>
    </mesh>
}}}

 
Both the X and Y axes of the mesh contain 50 points, evenly spaced between 0.0 and 1.0.
The '''<min>''', '''<max>''', and '''<numpoints>''' subelements define the 
the minimum axis position, the maximum axis position, and the number of uniform points between
them (including the minimum and maximum).

== Non-uniform Rectilinear Grid ==

[[Image(rectilinear2d.png, title="A nonuniform rectilinear 2D grid")]]
[[Image(rectilinear3d.png, title="A nonuniform rectilinear 3D grid")]]

Another form of a structured grid is a non-uniform or irregular rectilinear grid. You specify the points on each axis using the 
'''<xcoords>''', '''<ycoords>''', and '''<zcoords>''' subelements.

 '''<xcoords>'''::  
   A list all the coordinates on the X-axis.  The coordinates do not have to be uniformly spaced.
 '''<ycoords>'''::  
   A list all the coordinates on the Y-axis.  The coordinates do not have to be uniformly spaced.
 '''<zcoords>'''::  
   A list all the coordinates on the Z-axis.  The coordinates do not have to be uniformly spaced.

Here is an example of an irregular rectilinear 2D grid.

{{{
    <mesh>
        <dim>2</dim>
        <units>m</units>
        <hide>yes</hide>
        <grid>
            <xcoords>
                0.0 0.0204081632653 
                0.0408163265306 0.0612244897959 0.0816326530612 0.102040816327
                0.122448979592 0.142857142857 0.163265306122 
                ...
                0.836734693878 0.857142857143 0.877551020408 0.897959183673 
                0.918367346939 0.938775510204 0.959183673469
                0.979591836735 1.0
            </xcoords>
            <ycoords>
                0.0 0.0204081632653 0.0408163265306 0.0612244897959
                0.0816326530612 0.102040816327
                ... 
                0.836734693878 0.857142857143 0.877551020408 
                0.897959183673 0.918367346939 0.938775510204 
                0.959183673469 
                0.979591836735 1.0
            </ycoords>
        </grid>
    </mesh>
}}}

This is the same mesh as the uniform 2D grid example above except that we specify each point along the X and Y axes in '''<xcoords>''' and '''<ycoords>''' elements.


== Curvilinear Grid == 

[[Image(200px-Meshes_Curvilinear_StructuredGrid.png, title="A curvilinear 3D grid")]]

In a curvilinear grid you specify to locations of each point in the grid. The grid lines do not need to be aligned to any axis.

{{{
    <mesh>
        <dim>3</dim>
        <units>m</units>
        <hide>yes</hide>
        <grid>
            <xdim>20</xdim>
            <ydim>30</ydim>
            <zdim>40</ydim>
            <points>
                3.90799e-16 9.85395e-06 0.00041631 
                0.00176643 0.00364602 0.0259133 
                0.000922976 0.00487217 0.0552675 
                0.00454433 0.00233178 0.0833129 
                0.00931732 0.0056806 0.105561 
                0.000508319 0.00767051 0.125189 
                ...
            </points>
        </grid>
    </mesh>
}}}

The number of points is determined by the '''<xdim>''', '''<ydim>''', and '''<zdim>''' values. It is the product of the values.

  '''<xdim>''':: 
    The number of coordinates along the X-axis.
  '''<ydim>'''::
    The number of coordinates along the Y-axis.
  '''<zdim>'''::
    The number of coordinates along the Z-axis.  This is needed only for 3D 
  '''<points>'''::
    This is a list of points that represent the mesh.  The points do not need to be aligned. If this is a 2D grid, then every 2 numbers represent a point in the mesh.  In a 3D grid, every 3 numbers represent a point in the mesh.  The number of points is the product of the '''<xdim>''', '''<ydim>''', and '''<zdim>''' values.

 = Unstructured Grids =

Unstructured grids are composed of cells: hexahedrons, wedges, pyramids, etc. The cells can be all one type like triangles, or mixed.  Cells can be arbitrarily positioned.  Grid lines do not have to run through the entire domain (there can be holes). All unstructured grids use '''<points>''' to specify the vertices of the cells.

 '''<points>'''::  
   These are the points of all the vertices.  Each line should contain two or three numbers, depending upon the dimensionality of the mesh.

 == Triangles ==

[[Image(triangular_grid.jpg, "A triangular mesh")]]
[[Image(vtktriangle.png, "A triangle cell")]]

A '''<triangles>''' subelement in an unstructured grid describes a triangular grid consisting of all triangle cells.  It contains a '''<points>''' subelement
that defines all the vertices used by the triangles.  The '''<triangles>''' subelement defines the indices of each vertex (numbered from zero) that make up each triangle.  Every three indices describe a triangle.

{{{
    <mesh>
        <dim>2</dim>
        <units>m</units>
        <hide>yes</hide>
        <unstructured>
            <points>
                0.0 0.0
                0.02040816326530612 0.0
                0.04081632653061224 0.0
                0.061224489795918366 0.0
                0.08163265306122448 0.0
                0.1020408163265306 0.0
                0.12244897959183673 0.0
                0.14285714285714285 0.0
                ...
            </points>
            <triangles>
                93 44 43
                98 49 48
                19 70 20
                25 76 26
                29 80 30
                34 85 35
                ...
            </triangles>
        </unstructured>
    </mesh>
}}}

 '''<points>'''::  
   These are the points of all the vertices.  Each line should contain two numbers in 2D, or three numbers in 3D, representing coordinates of the point.
 '''<triangles>'''::
   This is the list of indices for each triangle.  The indices are numbered from zero and indicate the index of the point in '''<points>'''.   There are 3 indices per triangle.
    

 == Quads ==

 [[Image(quad2d.png, align=bottom, title="A 2D quad mesh")]]
 [[Image(quad3d.png, align=bottom, title="A 3D quad mesh")]]
 [[Image(vtkquad.png, "A quad cell")]]

A '''<quads>''' subelement in an unstructured grid describes a grid consisting of all quadrilateral cells.  It contains a '''<points>''' subelement
that defines all the vertices used by the triangles.  The '''<quads>''' subelement defines the indices of each vertex (numbered from zero) that make up each quadrilateral.  Every four indices describe a quadrilateral cell.

{{{
    <mesh>
        <dim>2</dim>
        <units>m</units>
        <hide>yes</hide>
        <unstructured>
            <points>
                0.0 0.0
                1.0 0.0
                2.0 0.0
                3.0 0.0
                4.0 0.0
                0.0 1.0
                ...
            </points>
            <quads>
                0 1 6 5
                1 2 7 6
                2 3 8 7
                3 4 9 8
                5 6 11 10
                ...
            </quads>
        </unstructured>
    </mesh>
}}}

 '''<points>'''::  
   These are the points of all the vertices.  Each line should contain two numbers in 2D, or three numbers in 3D, representing coordinates of the point.
 '''<quads>'''::
   This is the list of indices for each quadrilateral cell.  The indices are numbered from zero and indicate the index of the point in '''<points>'''.   There are 4 indices per quadrilateral cell.
    
 == Tetrahedrons ==
[[Image(TetrahedralGridColored.jpg, align=bottom, title="A tetrahedral mesh")]]
[[Image(vtktetra.png, "A tetrahedron cell")]]

A '''<tetrahedrons>''' subelement in an unstructured grid describes a grid consisting of all tetrahedral cells.  It contains a '''<points>''' subelement
that defines all the vertices used by the tetrahedrons.  The '''<tetrahedrons>''' subelement defines the indices of each vertex (numbered from zero) that make up each tetrahederon.  Every four indices describe a tetrahedron.

{{{
    <mesh>
        <dim>3</dim>
        <units>m</units>
        <hide>yes</hide>
        <unstructured>
            <points>
                9.78032 -1.80307 0.98754
               -9.4657 -2.99572 1.00759
                5.52579 -6.91009 4.59944
               -4.16239 -5.64701 7.08914
               -2.90309 -9.09061 -2.79763
                5.32889 -7.28927 -4.22598
                0 -2.00419 -9.77107
                7.03844 4.39577 -5.5911
                ...
            </points>
            <tetrahedrons>
                54 32 26 7
                37 54 36 5
                33 36 26 12
                32 37 33 6
                32 37 33 54
                ...
            </tetrahedrons>
        </unstructured>
    </mesh>
}}}

 '''<points>'''::  
   These are the points of all the vertices.  Each line should contain three numbers representing the X, Y and Z coordinates of the point.
 '''<tetrahedrons>'''::
   This is the list of indices for each tetrahedron.  The indices are numbered from zero and indicate the index of the point in '''<points>'''.   There are 4 indices per tetrahedron.
    

 == Hexahedrons ==
 [[Image(hexgrid.png, align=bottom, title="A hexahedron mesh")]]
 [[Image(hexgrid2.png, align=bottom, title="A hexahedron mesh")]]
 [[Image(vtkhexa.png, "A hexahedron cell")]]

A '''<hexahedrons>''' subelement in an unstructured grid describes a grid consisting of all hexahedral cells.  It contains a '''<points>''' subelement
that defines all the vertices used by the hexahedrons.  The '''<hexahedrons>''' subelement defines the indices of each vertex (numbered from zero) that make up each hexahederon.  Every eight indices describe a hexahedron.

{{{
    <mesh>
        <dim>3</dim>
        <units>m</units>
        <hide>yes</hide>
        <unstructured>
            <points>
                0.0 0.0 0.0
                1.0 0.0 0.0
                2.0 0.0 0.0
                3.0 0.0 0.0
                4.0 0.0 0.0
                0.0 1.0 0.0
                ...
            </points>
            <hexahedrons>
                0 1 6 5 25 26 31 30
                1 2 7 6 26 27 32 31
                2 3 8 7 27 28 33 32
                3 4 9 8 28 29 34 33
                5 6 11 10 30 31 36 35
                8 9 14 13 33 34 39 38
                ...
            </hexahedrons>
        </unstructured>
    </mesh>
}}}

 '''<points>'''::  
   These are the points of all the vertices.  Each line should contain three numbers representing the X, Y and Z coordinates of the point.
 '''<hexahedrons>'''::
   This is the list of indices for each hexahedron.  The indices are numbered from zero and indicate the index of the point in '''<points>'''.   There are 8 indices per hexahedron.
    
 == Wedges ==
 [[Image(vtkwedge.png, "A wedge cell")]]

A '''<wedges>''' subelement in an unstructured grid describes a grid consisting of all wedge cells.  It contains a '''<points>''' subelement
that defines all the vertices used by the wedges.  The '''<wedges>''' subelement defines the indices of each vertex (numbered from zero) that make up each wedge.  Every six indices describe a wedge.
{{{
    <mesh>
        <dim>3</dim>
        <units>m</units>
        <hide>yes</hide>
        <unstructured>
            <points>
                1.441430e+05 4.158160e+05 0.000000e+00
                1.445344e+05 4.179627e+05 0.000000e+00
                1.439527e+05 4.205476e+05 0.000000e+00
                1.442696e+05 4.230602e+05 0.000000e+00
                1.417173e+05 4.235800e+05 0.000000e+00
                1.400681e+05 4.226783e+05 0.000000e+00
                ...
            </points>
            <wedges>
                66 67 68 9676 9677 9678
                37 38 39 9647 9648 9649
                37 39 40 9647 9649 9650
                66 68 69 9676 9678 9679
                398 399 794 10008 10009 10404
                ...
            </wedges>
        </unstructured>
    </mesh>
}}}

 '''<points>'''::  
   These are the points of all the vertices.  Each line should contain three numbers representing the X, Y and Z coordinates of the point.
 '''<wedges>'''::
   This is the list of indices for each wedge.  The indices are numbered from zero and indicate the index of the point in '''<points>'''.   There are 4 indices per wedge.
    
 == Pyramids ==
 [[Image(vtkpyramid.png, "A pyramid cell")]]

A '''<pyramids>''' subelement in an unstructured grid describes a grid consisting of all pyramid cells.  It contains a '''<points>''' subelement
that defines all the vertices used by the pyramids.  The '''<pyramids>''' subelement defines the indices of each vertex (numbered from zero) that make up each pyramid.  Every six indices describe a pyramid.

{{{
    <mesh>
        <dim>3</dim>
        <units>m</units>
        <hide>yes</hide>
        <unstructured>
            <points>
                0.0 0.0 0.0
                1.0 0.0 0.0
                2.0 0.0 0.0
                3.0 0.0 0.0
                4.0 0.0 0.0
                0.0 1.0 0.0
                ...
            </points>
            <pyramids>
                0 1 6 5 25
                1 2 7 6 26
                2 3 8 7 27
                3 4 9 8 28
                5 6 11 10 29
                ...
            </pyramids>
        </unstructured>
    </mesh>
}}}

 '''<points>'''::  
   These are the points of all the vertices.  Each line should contain three numbers representing the X, Y and Z coordinates of the point.
 '''<pyramids>'''::
   This is the list of indices for each pyramid.  The indices are numbered from zero and indicate the index of the point in '''<points>'''.   There are 5 indices per tetrahedron.
    
 == Hybrid Cells ==

The '''<cells>''' subelement in an unstructured grid describes a grid consisting of possibly different types of cells.  It contains a '''<points>''' subelement
that defines all the vertices used by the cells.  The '''<celltypes>''' subelement describes the types of cells.  The '''<cells>''' subelement defines the indices of each vertex (numbered from zero) that make up each cell.  The number of indices is determined by the type of the cell. Each cell has a VTK cell ID listed below.

  ||Vertex          ||1||
  ||Poly Vertex     ||2||
  ||Line            ||3||
  ||Poly Line       ||4||
  ||Triangle        ||5||
  ||Triangle Strip  ||6||
  ||Polygon         ||7||
  ||Pixel           ||8||
  ||Quad            ||9||
  ||Tetra           ||10||
  ||Voxel           ||11||
  ||Hexahedron      ||12||
  ||Wedge           ||13||
  ||Pyramid         ||14||
  ||Pentagonal Prism||15||
  ||Hexagonal Prism ||16||
 
 '''<points>'''::  
   These are the points of all the vertices.  Each line should contain two numbers in 2D, or three numbers in 3D, representing coordinates of the point.
 '''<celltypes>'''::
   This is a list of cell types. The cell type can be a name such as "quad" or "tetrahedron", or a cell ID.  If there is only one cell type, this means that all cells are of this type.  Otherwise, the list must describe the cell type for each cell. 
 '''<cells>'''::
   This is the list of indices for each cell.  The indices are numbered from zero and indicate the index of the point in '''<points>'''.   The number of indices is determined from the cell type.

{{{
    <mesh>
        <dim>2</dim>
        <units>m</units>
        <hide>yes</hide>
        <unstructured>
            <points>
                0.0 0.0
                0.02040816326530612 0.0
                0.04081632653061224 0.0
                0.061224489795918366 0.0
                0.08163265306122448 0.0
                0.1020408163265306 0.0
                0.12244897959183673 0.0
                0.14285714285714285 0.0
                ...
            </points>
            <cells>
                93 44 43
                98 49 48
                19 70 20
                25 76 26
                29 80 30
                34 85 35
                ...
            </cells>
            </celltypes>triangle</celltypes>
        </unstructured>
    </mesh>
}}}


 == Point Clouds == 

The point cloud is a special case of a unstructured grid. 
A point cloud mesh contains no explicit connectivity.  It is implicitly converted into triangular mesh in 2D or a tetrahedral mesh in 3D.   The '''<points>''' subelement
indicates where the individual points are located in the cloud. Each line of '''<points>''' specifies a point in the cloud.   There are no '''<cells>''' or '''<celltype>''' subelements. .

'''''Note: It is a bad idea to convert your data that has a known mesh into a point cloud. The mesh generated for point clouds will be inferior to the one actually used by the dataset.'''''

 '''<points>'''::  
   These are the points of the mesh.  Each line specifies a point in the cloud.  Each line should contain two numbers in 2D, or three numbers in 3D, representing coordinates of the point

The following is an example of a 2D cloud.

{{{
    <mesh>
        <dim>2</dim>
        <units>m</units>
        <hide>yes</hide>
        <unstructured>
            <points>
               0.0 0.0
               0.0204081632653 0.0
               0.0408163265306 0.0
               0.0612244897959 0.0
               ...
               0.918367346939 1.0
               0.938775510204 1.0
               0.959183673469 1.0
               0.979591836735 1.0
               1.0 1.0
             </points>
        </unstructured>
    </mesh>
}}}


 = VTK Legacy File Format =

A '''<vtk>''' element uses the VTK legacy file format to describe the mesh.  The advantage of describing the mesh in VTK file format is that you can have heterogeneous cell types. 

The '''<vtk>''' element contains only a part of a VTK file.  It consists of 

 * a '''DATASET''' keyword and the dataset type ('''STRUCTURED_POINTS''', '''STRUCTURED_GRID''', '''UNSTRUCTUTRED_GRID''', '''POLYDATA''', or '''RECTILINEAR_GRID''') and 
 * the dataset definition itself. 

'''POINT_DATA''' and '''CELL_DATA''' are not included.  They will be added by the '''<field>''' that is using this mesh.   

{{{
    <mesh>
        <dim>2</dim>
        <units>m</units>
        <hide>yes</hide>
        <vtk>DATASET UNSTRUCTURED_GRID
POINTS 2500 float
    0.0 0.0 0
    0.0204082 0.0 0
    0.0408163 0.0 0
    0.0612245 0.0 0
    0.0816327 0.0 0
    0.102041 0.0 0
    ...
CELLS 4802 19208
    3 93 44 43
    3 98 49 48
    3 19 70 20
    3 25 76 26
    3 29 80 30
    3 34 85 35
    ...
CELL_TYPES 4802
    5
    5
    5
    5
    5
    5
    ...
        </vtk>
    </mesh>
}}}


You can see working code in the [browser:trunk/examples/zoo zoo of examples] in the [browser:trunk/examples/zoo/mesh mesh example] or on the hub in the directory /apps/rappture/examples/zoo/mesh.