Mesh Iterators and Circulators

The mesh provides linear iterators (that enumerate vertices, halfedges, edges, and faces) and so called circulators (to iterate around a vertex or a face).

These can be used to easily navigate through a mesh. Each iterator XYZIter also exists in a const version ConstXYZIter.

All iterators and circulators are defined in the namespace OpenMesh::Iterators. They are template classes that expect a mesh as template argument to be fully specified. You should use the iterator/circulator types provided by the mesh itself, i.e. MyMesh::VertexIter instead of OpenMesh::Iterators::VertexIterT<MyMesh>.

The linear iterators are used to enumerate all mesh items, e.g. for rendering purposes. The iterators and their const counterparts are:

MyMesh mesh;

// iterate over all vertices
for (MyMesh::VertexIter v_it=mesh.vertices_begin(); v_it!=mesh.vertices_end(); ++v_it) 
   ...; // do something with *v_it, v_it->, or v_it.handle()

// iterate over all halfedges
for (MyMesh::HalfedgeIter h_it=mesh.halfedges_begin(); v_it!=mesh.halfedges_end(); ++v_it) 
   ...; // do something with *h_it, h_it->, or h_it.handle()

// iterate over all edges
for (MyMesh::EdgeIter e_it=mesh.edges_begin(); v_it!=mesh.edges_end(); ++v_it) 
   ...; // do something with *e_it, e_it->, or e_it.handle()

// iterator over all faces
for (MyMesh::FaceIter f_it=mesh.faces_begin(); v_it!=mesh.faces_end(); ++v_it) 
   ...; // do something with *f_it, f_it->, or f_it.handle()

The corresponding const counterparts are

• ConstVertexIter,
• ConstHalfedgeIter,
• ConstEdgeIter,
• ConstFaceIter.

The linear iterators are (almost) conformant to STL iterators. For a description of their interface see OpenMesh::Concepts::IteratorT.

For efficiency reasons the operation++(int) (post-increment) and operation--(int) (post-decrement) are not implemented. Additionally to the standard operations, each linear iterator provides a method handle(), which returns the handle of the item referred to by the iterator.

Note:

An iterator to an item usually needs more memory than a handle of an item. To store many references to an item, it is therefore better to use handles.

Circulators provide means to enumerate items adjacent to another item of the same or another type. For example, a VertexVertexIter allows to enumerate all vertices immediately adjacent to a (center) vertex (i.e. it allows to enumerate the so-called 1-ring of the center vertex). Analogously, a FaceHalfedgeIter enumerates all the halfedges belonging to a face. In general, CenterItem_AuxiliaryInformation_TargetItem_Iter designates a circulator that enumarates all the target items around a given center item.

The circulators around a vertex are:

• VertexVertexIter: iterate over all neighboring vertices.
• VertexIHalfedgeIter: iterate over all incoming halfedges.
• VertexOHalfedgeIter: iterate over all outgoing halfedges.
• VertexEdgeIter: iterate over all incident edges.
• VertexFaceIter: iterate over all adjacent faces.

The circulators around a face are:

• FaceVertexIter: iterate over the face's vertices.
• FaceHalfedgeIter: iterate over the face's halfedges.
• FaceEdgeIter: iterate over the face's edges.
• FaceFaceIter: iterate over all edge-neighboring faces.

The constructor of a circulator is of the form Circulator(MeshType mesh, TargetHandle center_handle), i.e. it takes a mesh and the handle of the item to iterate around.

All circulators provide the operations listed in OpenMesh::Concepts::CirculatorT, which are basically the same as the iterator funtions.

Furthermore, circulators provide operator \c bool(), which returns true, as long as the circulator hasn't reached the end of the sequence.

Example: The following code enumerates the 1-ring of each vertex:

MyMesh mesh;

// (linearly) iterate over all vertices
for (MyMesh::VertexIter v_it=mesh.vertices_begin(); v_it!=mesh.vertices_end(); ++v_it)
{
  // circulate around the current vertex
  for (MyMesh::VertexVertexIter vv_it=mesh.vv_iter(v_it.handle()); vv_it; ++vv_it)
  {
    // do something with e.g. mesh.point(*vv_it)
  }
}

---