CGAL join_face source code analysis

location: CGAL\boost\graph\Euler_operations.h

http://doc.cgal.org/latest/BGL/group__PkgBGLEulerOperations.html#ga34c26f38b0453d3bad610963da8b24ee

namespace EulerImpl {

template<typename Graph>
typename boost::graph_traits<Graph>::halfedge_descriptor
join_face(typename boost::graph_traits<Graph>::halfedge_descriptor h,
          Graph& g)
{
 typedef typename boost::graph_traits<Graph> Traits;
  typedef typename Traits::halfedge_descriptor           halfedge_descriptor;

  typedef typename Traits::face_descriptor               face_descriptor;


  halfedge_descriptor hop = opposite(h,g);
  halfedge_descriptor hprev = prev(h, g), gprev = prev(hop, g);
  face_descriptor f = face(h, g), f2 = face(hop, g);

  internal::remove_tip(hprev, g);

  internal::remove_tip(gprev, g);

  if(! is_border(hop,g)){
    remove_face(f2, g);
  }
  bool fnull = is_border(h,g);

  
  halfedge_descriptor hprev2 = hprev;
  while(hprev2 != gprev) {
    hprev2 = next(hprev2, g);
    set_face(hprev2, f, g);
  }
  
  if (! fnull)
    set_halfedge(f, hprev, g);
  set_halfedge(target(hprev,g), hprev, g);
  set_halfedge(target(gprev,g), gprev, g);
  //  internal::set_constant_vertex_is_border(g, target(h, g));
  //  internal::set_constant_vertex_is_border(g, target(opposite(h, g), g));

  remove_edge(edge(h, g), g);
  return hprev;

}
} // namespace EulerImpl

this function is to joint two faces which halfedge h is next to.

okay, let us explain the code line by line,

  halfedge_descriptor hop = opposite(h,g);
  halfedge_descriptor hprev = prev(h, g), gprev = prev(hop, g);
  face_descriptor f = face(h, g), f2 = face(hop, g);

these three lines are to set some varibles which I marked above.

  internal::remove_tip(hprev, g);

  internal::remove_tip(gprev, g);

the remove_tip function is like below:

template <typename Graph>
void
remove_tip(typename boost::graph_traits<Graph>::halfedge_descriptor const& h
           , Graph& g)
{ 
  set_next(h, next(opposite(next(h, g), g), g), g);
}

the function these two lines is to set:

hprev->next = AC

gprev->next = BD

note: the set_next do bilateral work.

 if(! is_border(hop,g)){
    remove_face(f2, g);
  }

if f2 is not null_face, remove it

  halfedge_descriptor hprev2 = hprev;
  while(hprev2 != gprev) {
    hprev2 = next(hprev2, g);
    set_face(hprev2, f, g);
  }

these lines set the face of AC,CB to f

  bool fnull = is_border(h,g);
  if (! fnull)
    set_halfedge(f, hprev, g);

if f exists, set the halfedge of f to hprev

  set_halfedge(target(hprev,g), hprev, g);
  set_halfedge(target(gprev,g), gprev, g);

these two lines are little bit confused, first, let's introduce some basic conceptions

Each edge is represented by two halfedges with opposite orientation. Each halfedge stores a reference to an incident face and to an incident vertex. Additionally, it stores a reference to the next and previous halfedge incident to its incident face. For each face and each vertex an incident halfedge is stored.

note this part, for each vertex an incident halfedge is stored. However, for a vertex, there may be several incident halfedges, threrefore, we must decide which one is choosed to be stored.

these two lines are to do this thing.

remove_edge(edge(h, g), g);

then we remove edge h from the graph.