VizSchema

# Meshes

# Meshes and their metadata

[Variables](https://ice.txcorp.com/vizschema/wiki/Variables) live on meshes. Here we define the attributes of meshes. 

Since most of viz tools treat plots with time on axis as regular plots, time sequences are treated as data on 1D meshes. Such meshes use vsTemporalDimension attribute. They make sense only for structured meshes (defined axis). 

Below, Att signifies an attribute. 

**Jump to**

* [Variables and their metadata](https://ice.txcorp.com/projects/vizschema/wiki/Variables) 

* [Variables that are combined with their meshes](https://ice.txcorp.com/projects/vizschema/wiki/VariablesWithMesh)

* [Data ordering](https://ice.txcorp.com/projects/vizschema/wiki/DataOrdering)

* [Variables defined in terms of other variables](https://ice.txcorp.com/projects/vizschema/wiki/DerivedVariables) 

* [Multidomain metadata](https://ice.txcorp.com/projects/vizschema/wiki/MultiDomainMetaData)

* [Other metadata](https://ice.txcorp.com/projects/vizschema/wiki/OtherMetaData)

**Uniform cartesian meshes**

are meshes with cell lengths constant in each direction. They are represented by an HDF5 group. The data in that group is 

```

Group "mycartgrid" {

  Att vsType = "mesh"                         // Required string

  Att vsKind = "uniform"                      // Required string

  Att vsStartCell = [0, 0, 0]                 // Required integer array if part of a larger mesh

  Att vsNumCells = [200, 200, 104]            // Required integer array giving the number of cells in the x, y, and z directions, respectively

  Att vsIndexOrder = "compMinorC"             // Default value is "compMinorC", with the other choice being "compMinorF".

                                              // ("compMajorC" and "compMajorF" have the same result as the minor variants). 

  Att vsLowerBounds = [-2.5, -2.5, -1.3]      // Required float array

  Att vsUpperBounds = [2.5, 2.5, 1.3]         // Required float array

  Att vsTemporalDimension = 0                 // Optional unsigned integer denoting which axis is time.

                                              // No temporal axis if this attribute is not present.

}

```

* vsType allows the schema to identify this group as a VizSchema mesh. 

* vsKind indicates the kind of mesh, in this case a uniform cartesian mesh. 

* vsStartCell gives the start location of this mesh in some larger mesh contained in many files. 

* vsNumCells gives the number of cells for the mesh (in this file). There is one more node than number of cells in each direction. 

* vsIndexOrder indicates the interpretation of the indices for the data set. See [Data Ordering](https://ice.txcorp.com/vizschema/wiki/DataOrdering). E.g., for "compMinorC", the first index is the x index, the second index is the y index, and the last index is the z index. 

* vsLowerBounds gives the cartesian coordinate of smallest values of the coordinates. 

* vsUpperBounds gives the cartesian coordinate of largest values of the coordinates. 

The optional variables (not implemented in VizSchema 3.0.0), 

* vsTransform allows for the definition of a second mesh that is found from this mesh as a transformation. For example, this mesh could be (r, phi, z) coordinates, and the transformation could be to (x, y, z) coordinates. 

* vsTransformedMesh gives the name of the transformed mesh. 

are also possible. They are shown below. 

**Rectilinear meshes**

are meshes that can be described by a set of 3 1D arrays. The arrays do not need to have uniform variable spacing, which distinguishes this type of mesh from a uniform mesh. 

```

Group "myrectgrid" {

  Att vsType = "mesh"                         // Required string

  Att vsKind = "rectilinear"                  // Required string

  Att vsAxis0 = "axis0"                       // Axis name (optional, default = "axis0") gives to the name of the 

                                              // array containing the points of the first axis.  Must be at this level.

  Att vsAxis1 = "axis1"                       // Axis name (optional, default = "axis1") gives to the name of the 

                                              // array containing the points of the second axis.  Must be at this level.

  Att vsAxis2 = "axis2"                       // Axis name (optional, default = "axis2") gives to the name of the 

                                              // array containing the points of the third axis.  Must be at this level.

  Dataset axis0[n0]                           // Axis data, name must be value of vsAxis0 attribute

  Dataset axis1[n1]                           // Axis data, name must be value of vsAxis1 attribute

                                              // (present for 2-D and 3-D meshes)

  Dataset axis2[n2]                           // Axis data, name must be value of vsAxis2 attribute (present for 3-D meshes)

  Att vsTransform = "cylindricalZRPhi"        // Optional. Declares that this mesh is in cylindricalZRPhi format

  Att vsTransformedMesh = "resultCartGrid"    // Optional name of the transformed (cartesian) mesh.

  Att vsLimits = "mylimits"                   // Optional string

  Att vsTemporalDimension = 0                 // Optional unsigned integer denoting which axis is time.

                                              // No temporal axis if this attribute is not present.

}

```

* vsType allows the schema to identify this group as a VizSchema mesh. 

* vsKind indicates the kind of mesh, in this case a rectilinear mesh. 

* vsLimits points to a [visualization region](https://ice.txcorp.com/vizschema/wiki/OtherMetaData) 

* vsTransform defines a second mesh that is created from this mesh as a transformation. In this example, the mesh is in (z, r, phi) coordinates, and the transformation will be to (x, y, z) coordinates. 

* vsTranformedMesh gives the name of the transformed mesh. If not present, it is given by the name of the group with transformed appended. 

The concept of a transformed mesh (implemented using "vsTransform" attribute) allows one to have the compactness of the rectilinear or uniform mesh description while actually creating a curvilinear mesh. Note that the transforms are implemented only for rectilinear 3D meshes and the only type of the transform is "cylindricalZRPhi" ("Cylindrical" is deprecated but is supported for backward compatibility and means the same as cylindricalZRPhi). Additional or other than 3D transforms will be added as necessary. Many more transformations can be imagined, such as "spherical", "cylindrical(phi,z,r)", "cylindrical(r,-phi,z)", "cartesian(z,x,y)", "ellipsoidal", "WGS84", "equatorial", etc. Also, in BOR (body-of-revolution) situations, the transformation is into the cartesian-like Z-R plane, rather than to cartesian per se. 

**Example** : A 3-D z-r-phi grid could be described by: 

```

Group "myCylindricalGrid" {

  Att vsType = "mesh"            

  Att vsKind = "rectilinear"     

  Att vsAxis0 = "z"                           // The name of the dataset containing values for axis 0

  Att vsAxis1 = "r"                           // The name of the dataset containing values for axis 1

  Att vsAxis2 = "phi"                         // The name of the dataset containing values for axis 2

  Dataset z[n2]                               // Axis data corresponding to vsAxis0

  Dataset r[n0]                               // Axis data corresponding to vsAxis1

  Dataset phi[n1]                             // Axis data corresponding to vsAxis2

  Att vsLimits = "mylimits"                   // Optional string specifying a "limits" group

}

```

**Structured meshes**

Allow each point in the mesh to be specified individually, but the connectivity is fixed. 

Generally speaking, a structured mesh is described by a single dataset. The size of this dataset depends on the spatial dimensionality of the mesh.

A 3-Dimensional mesh will have a dataset with 4 dimensions. The x location of point (i, j, k) is stored in dataset[i][j][k][0], the y location is in dataset[i][j][k][1], and the z location is in dataset[i][j][k][2]. (Assuming Component-Minor ordering).

A 2-Dimensional mesh will have a dataset with 3 dimensions. The x location of point (i, j) is stored in dataset[i][j][0], and the y location is in dataset[i][j][1].

A 1-Dimensional mesh may be formed in two different ways. The first way is a 2-dimensional dataset, where the x location of point (i) is stored in dataset[i][0]. The second way is a 1-d dataset, where the x location of point (i) is stored in dataset[i].

*3D Structured Mesh*

```

Dataset "mesh3dstruct" {

  Att vsType = "mesh"                         // Required string

  Att vsKind = "structured"                   // Required string

  DATASPACE [n0][n1][n2][n3]                  // Required float array

  Att vsIndexOrder = "compMinorC"             // Default value is "compMinorC", with the other choices being 

                                              // "compMinorF", "compMajorC", or "compMajorF". 

  Att vsLimits = "mylimits"                   // Optional string

  Att vsTemporalDimension = 0                 // Optional unsigned integer denoting which axis is time.

                                              // No temporal axis if this attribute is not present.

}

```

* vsKind indicates the kind of mesh 

* vsIndexOrder indicates the interpretation of the indices for the data set. See [Data Ordering](https://ice.txcorp.com/vizschema/wiki/DataOrdering). E.g., for "compMinorC", the first index is the x index, the second index is the y index, the third index is the z index, and the last index is the coordinate index, which therefore must have a value of 3 (i.e. the spatial dimension). 

* vsLimits points to a [visualization region](https://ice.txcorp.com/vizschema/wiki/OtherMetaData) 

*2D Structured Mesh*

```

Dataset "mesh2dstruct" {

  Att vsType = "mesh"                         // Required string

  Att vsKind = "structured"                   // Required string

  DATASPACE [n0][n1][n2]                      // Required float array

  Att vsIndexOrder = "compMinorC"             // Default value is "compMinorC", with the other choices being 

                                              // "compMinorF", "compMajorC", or "compMajorF".

  Att vsLimits = "mylimits"                   // Optional string

  Att vsTemporalDimension = 0                 // Optional unsigned integer denoting which axis is time.

                                              // No temporal axis if this attribute is not present.

}

```

* vsKind indicates the kind of mesh 

* vsIndexOrder indicates the interpretation of the indices for the data set. See [Data Ordering](https://ice.txcorp.com/vizschema/wiki/DataOrdering). E.g., for "compMinorC", the first index is the x index, the second index is the y index, and the last index is the coordinate index, which therefore must have a value of 2 or 3 (i.e. the spatial dimension). 

* vsLimits points to a [visualization region](https://ice.txcorp.com/vizschema/wiki/OtherMetaData) 

*1D Structured Mesh*

Can have either the form, 

```

Dataset "mesh1dstructa" {

  Att vsType = "mesh"                         // Required string

  Att vsKind = "structured"                   // Required string

  Att vsTemporalDimension = 0                 // Optional unsigned integer denoting which axis is time.  No temporal axis if

                                              // this attribute is not present.

  DATASPACE [n0][n1]                          // Required float array

  Att vsIndexOrder = "compMinorC"             // Optional string defaulting to "compMinorC", with the other choice being "compMajorC"

                                              // ("compMinorF" and "compMajorF" have the same result as the C variants). 

}

```

or the form,

``` 

Dataset "mesh1dstructb" {

  Att vsType = "mesh"                         // Required string

  Att vsKind = "structured"                   // Required string

  Att vsTemporalDimension = 0                 // Optional unsigned integer denoting which axis is time.  No temporal axis if

                                              // this attribute is not present.

  DATASPACE [n0]                              // Required float array

}

```

which have equivalent data. This mesh has n0 points, each described by one value. 

* vsKind indicates the kind of mesh 

* vsIndexOrder indicates the interpretation of the indices for the data set. See [Data Ordering](https://ice.txcorp.com/vizschema/wiki/DataOrdering). E.g., for "compMinorC", the first index is the x index, and the second index is the coordinate index, which therefore must have a value of 1, 2, or 3 (i.e. the spatial dimension). If the second index is not present the coordinate index is assumed to be 1 (i.e. the spatial dimension). 

1D meshes have no need for a visualization region. 

**Blanking nodes and/or cells in a structured grid**

Node and cell blanking is a mesh property which allows one to turn off (mask) nodes or cells. An example would be an ocean model with grid nodes located on land or a model using cut cells where the cells outside the domain are tagged as invalid. Zonal/nodal blanking can also be used to turn off ghost cells/nodes. Blanking is achieved by providing nodal/zonal mask arrays (mynmask and myzmask in the example below). The mesh refers to the mask array using the vsNodalMask/vsZonalMask attribute. The mask, whether zonal or nodal, must be a Dataset and have vsType either "zonalMask" or "nodalMask". The values of the mask array are 0 where the mesh nodes/zones are valid, any other value indicating that the node/zone is masked. We recommend using unsigned char as the type of the masked array. The vsIndexOrder can be either "F" for column major indexing (Fortran) or "C" for row major indexing. 

```

GROUP "/" {

  Group "A" {

    Dataset "myzmask" {

      Att vsType = "zonalMask"                    // Required string

      DATASPACE [200, 300, 104] 

      Att vsIndexOrder = "F"                      // "F" for "Fortran", optional string defaulting to "C"

    }

    Dataset "mynmask" {

      Att vsType = "nodalMask"                    // Required string

      DATASPACE [201, 301, 105] 

      Att vsIndexOrder = "F"                      // Optional string with default value "C"

    }

    Group mycartgrid {

      Att vsZonalMask = "myzmask"                 // Optional string

      Att vsNodalMask = "mynmask"                 // Optional string

      Att vsType = "mesh"                         // Required string

      Att vsKind = "uniform"                      // Required string

      Att vsStartCell = [0, 0, 0]                 // Required integer array

      Att vsNumCells = [200, 300, 104]            // Required integer array

      Att vsLowerBounds = [-2.5, -2.5, -1.3]      // Required float array

      Att vsUpperBounds = [2.5, 2.5, 1.3]         // Required float array

    }

  }

```

**Unstructured meshes**

allows each point in the mesh to be specified individually, and also allows connectivity to be specified. 

```

Group "mypolymesh" {

  Att vsType = “mesh”                         // Required string

  Att vsKind = “unstructured”                 // Required string

  Att vsPoints = "points"                     // Optional string for dataset containing the point coordinates

  Att vsEdges = "edges"                       // Optional string for dataset containing the edge connectivity in terms of point indices (version 4.0)

  Att vsFaces = "faces"                       // Optional string for dataset containing the face connectivity in terms of point indices (version 4.0)

  Att vsPolygons = "polygons"                 // Optional string for dataset containing the polygons

  Dataset points [n0_points][n1_points]       // Float or double array of the points referenced by vsPoints

  Dataset edges [n0_edges][n1_edges]          // INTEGER edge to point connectivity array

  Dataset faces [n0_faces][n1_faces]          // INTEGER face to point connectivity array

  Dataset polygons [n0_polys][n1_polys]       // INTEGER array of the polygons referenced by vsPolygons

  Att vsIndexOrder = "compMinorC"             // Optional string defaulting to "compMinorC", with the other choice being "compMajorC"

                                              // ("compMinorF" and "compMajorF" have the same result as the C variants). 

  Att vsLimits = "mylimits"                   // Optional string

}

```

* vsKind indicates the kind of mesh 

* vsPoints is a string that points to the data set containing the points. The dataset is in the same group if the name does not begin with '/". If the string is not given, it defaults to "points". 

* vsEdges is an optional string that points to the data set containing the connectivity of edges in terms of point indices. 

* vsFaces is an optional string that points to the data set containing the connectivity of faces in terms of point indices. 

* vsPolygons is a string that points to the data set containing the vertex indices that make up the polygon elements. The dataset is in the same group if the name does not begin with '/". There may be other element connections, such as tetrahedra or cubes (see below). If the string is not given, it defaults to "polygons". 

* points is a dataset of points. This is an example where the points are in the same group. 

* edges is a dataset of edges. Each row denotes the indices of the points contributing to the edge. Note that edges have a direction. 

* faces is a dataset of faces. Each row denotes the indices of the points contributing to the face. Note that the ordering defines the direction of the face based on the cross product rule. 

* polygons is a dataset of connections that describe polygon elements. This is an example where the connections are in the same group. 

* vsIndexOrder is either "compMinor" (default) or "compMajor". See [Data Ordering](https://ice.txcorp.com/vizschema/wiki/DataOrdering). For "compMinor" the first index is the number of elements while the second index number connections. 

* vsLimits points to a [visualization region](https://ice.txcorp.com/vizschema/wiki/OtherMetaData) 

**The dataset containing the connection information must be INTEGER data**

* vsPolygon and vsPolyhedra datasets 

In compMinor, this dataset has size Nx(M+1), where N is the number of elements and M is the number of connections needed to describe the element. The +1 is necessary because the first value in each row is the number of connections in that row. In this way, the user may have different element types in the same dataset. Each value in a row is interpreted as an index into the points dataset. If the dataset contains connections point, edge, and/or face elements use vsPolygon, if the dataset contains a mixture of solid elements use vsPolyhedra. (For a datasets containing a single element type it is preferable to specify the exact type thus removing the need to specify the number of connections). 

For example, a dataset containing 2 triangles would be of size 2x4.

This example declares that there is a triangle formed by points 1, 2, 3, and another triangle formed by points 2, 3, 4:

```

( (3, 1, 2, 3),

  (3, 2, 3, 4) )

```

A dataset containing 2 triangles and 2 quadrilaterals (quads) would be of size 4x5.

Note that the last value of each row containing a triangle, here shown as '0', is ignored because only the first three points are needed to make a triangle.

This example declares a triangle formed by connecting points 1, 2, 3, another triangle formed by points 2, 3, 4, a quad formed by points 1, 3, 5, 6, and a quad formed by points 3, 5, 6, 7.

```

( (3, 1, 2, 3, 0),

  (3, 2, 3, 4, 0),

  (4, 1, 3, 5, 6),

  (4, 3, 5, 6, 7) )

```

Optionally, instead of using vsPolygon or vsPolyhedra one may specify the exact element type: 

* vsLines = "lines" // "lines" must be an "int32" dataset of size [n0_polys][2] 

* vsTriangles = "triangles" // "triangles" must be an "int32" dataset of size [n0_polys][3] 

* vsQuadrilaterals = "quadrilaterals" // "quadrilaterals" must be an "int32" dataset of size [n0_polys][4] 

* vsTetrahedrals = "tetrahedrals" // "tetrahedrals" must be an "int32" dataset of size [n0_polys][4] 

* vsPyramids = "pyramids" // "pyramids" must be an "int32" dataset of size [n0_polys][5] 

* NOT IMPLEMENTED vsWedge = "wedges" // "wedges" must be an "int32" dataset of size [n0_polys][6] 

* vsHexahedrals = "hexahedrals" // "hexahedrals" must be an "int32" dataset of size [n0_polys][8] 

**Meshes for high order fields**

Describes meshes used by the discontinuous Galerkin method and other higher order discretization schemes. These meshes consist of a coarse mesh, which contains a sub-mesh. The coarse mesh can be of any supported type (unstructured, structured, etc.). Each coarse cell is expected to contain a number of field values, which are located at barycentric coordinate points in the range of 0 to 1. Note that sub-nodes located at coarse cell vertices, edges or faces may share the same physical location as other sub-nodes belonging to a neighbouring coarse cell. In other words, the field can be discontinuous across cell boundaries. 

Meshes for high order fields follow the same structure as their underlying coarse meshes with one difference: there is an additional attribute, vsSubCellLocations, which points to a dataset that contains the barycentric coordinates of the field. All coarse cells share the same barycentric coordinates. The order of the barycentric coordinates is arbitrary. 

```

Group "mypolymesh" {

  Att vsType = “mesh”                                // Required string

  Att vsKind = “unstructured”                        // Can be also be structured, uniform, ...

  Att vsSubCellLocations = "mySubCellLocations"      // Required string 

  ...                                                // Other unstructured grid attributes

  Dataset mySubCellLocations[n_subCell][n_topoDims]  // Barycentric coordinates

}

```

The first dimension of dataset mySubCellLocations, n_subCell, refers to the number of sub-cell grid points and n_topoDims to the number of topological dimensions. 

**Split Datasets**

For Vizschema users needing to store their coordinate data in separate data sets, this feature allows pulling coordinate data from those different data sets and combining them into a single mesh. In particular this feature is targeted at users who also require fast-bit indexing in their data files, which requires storing each coordinate in a separate dataset. 

To use split datasets, the user will not use the standard attribute vsPoints. Instead, the user will use at least one of vsPoints0, vsPoints1, vsPoints2. These attributes must contain a string with the name of the dataset to use for that coordinate. This dataset may be anywhere in the data file, and need not be in the same group. In the event that an unstructured mesh has both the standard attribute vsPoints as well as the split attributes, the standard attribute will be used. 

Note that the following must be true:

1. Each coordinate dataset must be of identical size.

2. Each coordinate dataset must be of the same data type (float, double). 

Here is an example of an unstructured mesh formed by coordinates stored in three separate datasets:

```

Group "mySplitMesh" {

  Att vsType = “mesh”                         // Required string

  Att vsKind = “unstructured”                 // Required string

  Att vsPoints0 = "/x_values"                 // Required string for dataset containing the first coordinate of the points

  Att vsPoints1 = "/y_values"                 // Optional string for dataset containing the second coordinate of the points

  Att vsPoints2 = "/randomGroup/z_values"     // Optional string for dataset containing the third coordinate of the points

  Dataset polygons [n0_polys][n1_polys]       // Integer array of the polygons referenced by vsPolygons

}

Dataset "x_values" [n0_points]                // Dataset containing values of x coordinates

Dataset "y_values" [n0_points]                // Dataset containing values of y coordinates

Group "randomGroup" {

  Dataset "z_values" [n0_points]              // Dataset containing values of z coordinates

```