mesh - surface meshes in waLBerla

# How are meshes handled in the mesh module?

## OpenMesh

We use OpenMesh (https://www.openmesh.org/) for loading, storing and manipulating meshes in waLBerla. OpenMesh is a C++-library developed at RWTH Aachen based on the halfedge data structure. Details can be found at the documentation of OpenMesh.

## Mesh data types

To make things easy, we have predefined some OpenMesh types in TriangleMeshes.h. mesh::TriangleMesh is the default and should be used as first choice. Points and normals use walberla::real_t as the scalar type while everything else sticks to OpenMesh's defaults. FloatTriangleMesh uses float as the scalar type used in points and normals. You can use mesh::FloatTriangleMesh to save some memory if you have large meshes. mesh::PythonTriangleMesh matches the mesh definition used by OpenMesh's python module. So if you want to fiddle with meshes from C++ and Python mesh::PythonTriangleMesh might be the right choice.

Meshes can be loaded from any file format supported by OpenMesh including obj, off, ply, stl and a custom om format. To load a mesh at large scale simulations waLBerla provides the function readAndBroadcast() which reads a file from disk on a single process and broadcasts it. This way the pressure on the file system is kept to a minmum.

## Conversion between OpenMesh and waLBerla data types

OpenMesh and waLBerla use different vector data types. The file MatrixVectorOperations.h provides the functions toWalberla() and toOpenMesh() to convert between both vector data types. Additionally, it provides a multiplication operator for OpenMesh's vector and waLBerla's math::Matrix3 class.

Additional to the OpenMesh support, waLBerla has a geometry::TriangleMesh class in its geometry module. This class has a simple, adjacency-style data structure. If the use of this mesh type is still required, conversion routines convertOpenMeshToWalberla() and convertWalberlaToOpenMesh() can be found in MeshConversion.h.

# How can I setup my simulation using the mesh module?

## Initilization of mesh distance data structures

To set up the simulation using a surface mesh, waLBerla needs to compute distances to the surface and determine the location of points relative to mesh. The necessary data structure is called mesh::TriangleDistance and is defined in DistanceComputations.h. It adds the necessary information to the mesh's triangles and offers functions to compute a signed point<->triangle distance. It also offers to compute a asigned point<->mesh distance but this is only recommended for smaller meshes with only a few triangles. Larger meshes should use a mesh::DistanceOctree which reduces the number of evaluated point<->mesh distances significantly from $\mathcal O(n)$ to $\mathcal O(\log n)$. If you are only interested whether a point is contained in the mesh you can use the mesh::DistanceOctree with geometry::ContainmentOctree to get faster results.

## Files

file  BlockForestInitialization.cpp

file  RefinementSelection.h

file  BoundaryInfo.h

file  BoundaryInfo.h

file  BoundaryLocationFunction.h

file  BoundarySetup.cpp

file  ColorToBoundaryMapper.h

file  DistanceOctree.h

file  DistanceFunction.h

file  MatrixVectorOperations.h

file  mesh_module.dox

file  MeshConversion.h

file  MeshIO.h

file  MeshOperations.h

file  OpenMeshBufferTypeExtensions.h

file  DefaultTesselation.h

file  PeVTKMeshWriter.h

file  TriangleMeshes.h

file  QHull.h

file  TriangleMeshes.h

file  CommonFilters.h

file  DistributedVTKMeshWriter.h

file  VTKMeshWriter.h