Navigation and Iteration

Collection Iterators

Use these routines to iterate over all of the elements in the mesh.

Note: Generally, modifying the mesh while iterating is allowed, but the new elements may or may not be iterated over, and previous elements might even appear again later later in the iteration after modifying.

---

SurfaceMesh::vertices()

Iterate over the vertices in a mesh.

for(Vertex v : mesh.vertices()) {
  // do science here
}

SurfaceMesh::halfedges()

Iterate over all of the halfedges in a mesh (both interior and exterior, if the mesh has boundary).

for(Halfedge he : mesh.halfedges()) {
  // do science here
}

SurfaceMesh::interiorHalfedges()

Iterate over the interior halfedges in a mesh.

for(Halfedge he : mesh.interiorHalfedges()) {
  // do science here
}

Note that on a boundary edge between vertices i <--> j, this set will only include a halfedge from i --> j, but not from j --> i (or vice versa).

SurfaceMesh::exteriorHalfedges()

Iterate over the exterior halfedges in a mesh. (only useful on ManifoldSurfaceMesh)

for(Halfedge he : mesh.exteriorHalfedges()) {
  // do science here
}

Note that on a boundary edge between vertices i <--> j, this set will only include a halfedge from i --> j, but not from j --> i (or vice versa).

SurfaceMesh::edges()

Iterate over the edges in a mesh.

for(Edge e : mesh.edges()) {
  // do science here
}

SurfaceMesh::faces()

Iterate over the faces in a mesh.

for(Face f : mesh.faces()) {
  // do science here
}

SurfaceMesh::boundaryLoops()

Iterate over the boundary loops for a mesh.

Remember that only ManifoldSurfaceMeshs have well-defined boundary loops.

for(BoundaryLoop bl : mesh.boundaryLoops()) {
  // do science here
}

Neighborhood Iterators

Use these routines to iterate over the neighbors of a mesh element.

Note: neighborhoods on $\Delta$-complexes

The iterators in this section may have unexpected behavior in the advanced case of a $\Delta$-complex, when there are (e.g.) self-edges, or multiple edges between a pair of vertices. Essentially, these iterators always naively traverse the local neighborhood, even if that neighborhood might include duplicate elements.

For instance, if a $\Delta$-complex has multiple edges connecting vertex va to vertex vb, then iterating va.adjacentVertices() will return vb multiple times.

Of course, for ordinary triangle mesh they will behave as expected. See the Delta complex section for more information.

---

Around a vertex

Vertex::outgoingHalfedges()

Iterate over the halfedges which point outward from a vertex.

for(Halfedge he : vert.outgoingHalfedges()) {
  assert(he.vertex() == vert); // true
  // do science here
}

Vertex::incomingHalfedges()

Iterate over the halfedges which point inward at a vertex.

for(Halfedge he : vert.incomingHalfedges()) {
  assert(he.twin().vertex() == vert); // true
  // do science here
}

Vertex::adjacentVertices()

Iterate over the vertices edge-connected to this vertex.

for(Vertex v : vert.adjacentVertices()) {
  // do science here
}

Vertex::adjacentEdges()

Iterate over the edges incident on this vertex.

for(Edge e : vert.adjacentEdges()) {
  // do science here
}

Vertex::adjacentFaces()

Iterate over the faces incident on this vertex.

for(Face f : vert.adjacentFaces()) {
  // do science here
}

Around an edge

Edge::adjacentHalfedges()

Iterate over the halfedges incident on this edge.

for(Halfedge he : edge.adjacentHalfedges()) {
  // do science here
}

Edge::adjacentFaces()

Iterate over the (one or two) faces incident on this edge.

for(Face f : edge.adjacentFaces()) {
  // do science here
}

Edge::adjacentVertices()

Iterate over the (two) vertices which are endpoints of the edge.

for (Vertex v : edge.adjacentVertices()) {
  // do science here
}

Note: unlike most navigators, this routine actually returns a fixed-size array, so you can alternately write things like:

std::array<Vertex, 2> verts = edge.adjacentVertices();

Edge::diamondBoundary()

Iterate over the four halfedges bounding the diamond with this edge as its center diagonal.

More precisely, for an interior edge on a manifold triangle mesh, this returns

Halfedge he = edge.halfedge();
return {he.next(), he.next().next(), he.twin().next(), he.twin().next().next()}

Example:

for (Halfedge he : edge.diamondBoundary()) {
  // do science here
}

Throws an exception if there are non-triangular faces, the edge is on the boundary, or if the edge is nonmanifold.

Note: unlike most navigators, this routine actually returns a fixed-size array, so you can alternately write things like:

std::array<Halfedge, 4> halfedges = edge.diamondBoundary();

Around a face

Face::adjacentVertices()

Iterate over the vertices adjacent to a face.

for(Vertex v : face.adjacentVertices()) {
  // do science here
}

Face::adjacentHalfedges()

Iterate over the halfedges incident on a face.

for(Halfedge he : face.adjacentHalfedges()) {
  // do science here
}

Face::adjacentEdges()

Iterate over the edges on the boundary of a face.

for(Edge e : face.adjacentEdges()) {
  // do science here
}

Face::adjacentFaces()

Iterate over the faces adjacent to a face, across each edge.

for(Face f : face.adjacentFaces()) {
  // do science here
}

Around a boundary loop

BoundaryLoop::adjacentVertices()

Iterate over the vertices adjacent to a boundary loop.

for(Vertex v : boundaryLoop.adjacentVertices()) {
  // do science here
}

BoundaryLoop::adjacentHalfedges()

Iterate over the (exterior) halfedges incident on a boundary loop.

for(Halfedge he : boundaryLoop.adjacentHalfedges()) {
  // do science here
}

BoundaryLoop::adjacentEdges()

Iterate over the edges on the boundary of a boundary loop.

for(Edge e : boundaryLoop.adjacentEdges()) {
  // do science here
}

Accessors

Use these routines to access elements of the mesh by their index.

Warning

The indexing routines in the section are only valid when the mesh is compressed.

---

Halfedge SurfaceMesh::halfedge(size_t index)

Constructs a reference to the i’th halfedge in the mesh. 0 <= index < nHalfedges().

Vertex SurfaceMesh::vertex(size_t index)

Constructs a reference to the i’th vertex in the mesh. 0 <= index < nVertices().

Face SurfaceMesh::face(size_t index)

Constructs a reference to the i’th face in the mesh. 0 <= index < nFaces().

Edge SurfaceMesh::edge(size_t index)

Constructs a reference to the i’th edge in the mesh. 0 <= index < nEdges().

Face SurfaceMesh::face(size_t index)

Constructs a reference to the i’th face in the mesh. 0 <= index < nFaces().

Face SurfaceMesh::boundaryLoop(size_t index)

Constructs a reference to the i’th boundary loop in the mesh. 0 <= index < nBoundaryLoops().