feat: Provide boundary loop support for `SurfaceMesh`

[kcrane-rbx]

Currently, SurfaceMesh does not encode boundary loops, as indicated by this warning:

The reason is that, in general, boundary loops in a nonmanifold complex do not necessarily define a collection of disjoint loops. See the example below, for instance, where either (i) "outer" halfedges would have to be assigned to more than one boundary loop or (ii) a subset of possible loops would have to be chosen arbitrarily.

Still, for boundary loops of a SurfaceMesh that are well-defined, this approach feels like a bit of a cop-out. A reasonable policy might be:

• If a collection of boundary edges makes an unambiguous loop, add it to the set of boundary loops.
• Otherwise, retain the current behavior: these edges are marked as boundary edges, but do not belong to any boundary loop.

This policy is indeed harder to understand than "there are no boundary loops on SurfaceMesh." But maybe still strikes a good balance between simplicity and utility.

[kcrane-rbx]

Alternatively, if we do not provide any boundary loop support for SurfaceMesh, then the SurfaceMesh interface should not provide a nBoundaryLoops function, nor a boundaryLoops() function.

This violates the principle of least surprise: users can call these functions, therefore there's an expectation that boundary loops should sometimes be associated with a SurfaceMesh. It's surprising to discover that they are never available.

[kcrane-rbx]

Here's the ad-hoc solution I'm using for now. Notice that, unlike the suggestion above, this routine greedily finds as many loops as it can. But should work perfectly in the case where the boundary is a disjoint collection of loops.

Perhaps we can port something like this into the internal SurfaceMesh implementation.

// Detect boundary loops in a SurfaceMesh
using BLoop = vector<Halfedge>;
vector<BLoop> detectBoundaryLoops(SurfaceMesh& mesh) {
  vector<BLoop> boundaryLoops;
  
  // Mark all halfedges as unvisited
  HalfedgeData<bool> visited(mesh, false);
  
  // Iterate over all halfedges
  for (Halfedge h : mesh.halfedges()) {
    // Skip if already visited or not a boundary halfedge
    if (visited[h] || !h.edge().isBoundary()) {
      continue;
    }
    
    // Found an unvisited boundary halfedge, start tracing a loop
    BLoop newBoundary;
    Halfedge hij = h; // current halfedge
    
    do {
      // Mark current halfedge as visited
      visited[hij] = true;
      newBoundary.push_back(hij);
      
      // Get the vertices of hij
      Vertex i = hij.tailVertex();
      Vertex j = hij.tipVertex();
      
      // Find the next boundary halfedge hjk leaving vertex j
      Halfedge hjk;
      bool foundNext = false;
      for( Halfedge g : j.outgoingHalfedges() ) {
        if( g.edge().isBoundary() && g.tipVertex() != i ) {
          if( !visited[g] || g == h ) { // if we haven't visited this halfedge yet, or we're back to the start
            hjk = g;
            foundNext = true;
            break;
          }
        }
      }
      
      // If we couldn't find a next boundary halfedge, the loop is incomplete
      if (!foundNext) {
        // Drop this incomplete loop and continue with other unvisited halfedges
        std::cout << "Incomplete loop detected with " << newBoundary.size() << " edges" << std::endl;
        newBoundary.clear();
        break;
      }

      // Otherwise, move to the next halfedge
      hij = hjk;
      
    } while (hij != h); // Continue until we return to the start
    
    // If we completed a full loop, add it to our results
    if (!newBoundary.empty()) {
      boundaryLoops.push_back(newBoundary);
    }
  }
  
  return boundaryLoops;
}