OpenVolumeMesh is shipped with a set of useful iterators and circulators to comfortably address the entities (local neighborhood of entities) in a polyhedral mesh. See Section Iterators and Circulators for a more detailed description of all available iterators and circulators. In this tutorial, we examine how to use the iterators that come along with OpenVolumeMesh.

In the first example, we simply iterate over all half-edges of a mesh using the OpenVolumeMesh::HalfEdgeIter iterator class:

// Instantiate e.g. a geometric hexahedral mesh
OpenVolumeMesh::GeometricHexahedralMeshV3d myMesh;
using HEH = OpenVolumeMesh::HalfEdgeHandle;
 
// Fill mesh with geometry
 
// Iterate over all half-edges
for(const HEH heh: myMesh.halfedges()) {
    // ...
}

In the next example, we iterate over all incident outgoing half-edges of a given vertex. Note that this iterator needs bottom-up incidences which are computed automatically per default. Otherwise, the iterator would not be valid. See Section The Bottom-Up Incidence Relation for information on the bottom-up incidences.

// Instantiate a polyhedral mesh
OpenVolumeMesh::GeometricPolyhedralMeshV3f myMesh;
using HEH = OpenVolumeMesh::HalfEdgeHandle;
using VH = OpenVolumeMesh::VertexHandle;
 
// Fill mesh with geometry
...
 
// Get first vertex in mesh
VH vh = *(myMesh.vertices_begin());
 
// Iterate over all outgoing half-edges of vertex vh
for(const HEH voh: myMesh.outgoing_halfedges(vh)) {
    // `voh` is a halfedge with from_vertex == vh
    ...
}

In the last example, we create a hexahedral mesh and use its specialized OpenVolumeMesh::CellSheetCellIter iterator class. This iterator expects a cell handle as parameter and iterates over all adjacent cells in the same sheet. A sheet is, in the terms of the spatial twist continuum, short STC, a "layer" of hexahedra as illustrated in the following figure. For rurther reading on STC, refer to "The spatial twist continuum: A connectivity based method for representing all-hexahedral finite element meshes" by Peter Murdoch et al. The gray shaded hexahedra form a sheet, all other cells (except the outlines of the boundary cells) are invisible in this illustration.

Starting from a hexahedron, we determine its virtual axis that is orthogonal to the desired sheet (note that there are always two opposing virtual axes that are orthogonal to such a sheet). We create our sheet iterator by passing the reference cell's handle as well as an orthogonal virtual axis with respect to that cell to the iterator's constructor. The iterators then iterates over all directly adjacent cells in the same sheet (those hexahedra that share a common face with the reference hexahedron). Consider the following code:

// Instantiate a hexahedral mesh
OpenVolumeMesh::GeometricHexahedralMeshV3d myMesh;
using CH = OpenVolumeMesh::CellHandle;
 
// Fill mesh with geometry
...
 
// Get handle of first cell
CH ch = *(myMesh.cells_begin());
 
// Iterate over the hexahedra in the same sheet that are adjacent
// to the reference hexahedron (cell handle ch)
for (const CH ch: myMesh.cell_sheet_cells()) {
    // ...
}