- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages

# 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)
      }
    }