
\begin{ccRefConcept}{HalfedgeGraph}

%% \ccHtmlCrossLink{}     %% add further rules for cross referencing links
%% \ccHtmlIndexC[concept]{} %% add further index entries

\ccDefinition

The concept \ccRefName\ describes the requirements for a graph that is
structurally equivalent to a polyhedral surface represented by a
halfedge data structure, and it provides an interface for efficient
access to the opposite edge of an edge, and to the successor and
predecessor of an edge in the iterator range of the incoming edges of
a vertex.  Each vertex has a geometric position in space. As in a
halfedge data structure we define the face adjacent to a halfedge to be
to the {\em left} of the halfedge.


\ccHeading{Requirements}

For each {\em directed edge} $e=(v,w)$ its opposite edge $e'=(w,v)$
must be part of the graph.

The incoming edges of a vertex $v$ have a fixed order, that is all
calls of \ccc{in_edges(v,g)} must return the same iterator range,
modulo a cyclic permutation. The order must be {\em clockwise}.

As the \ccRefName\ is equivalent to a polyhedral surface there must exist an embedding
for the vertices and edges such that the ordered edges do not intersect.


\ccRefines
\ccAnchor{http://www.boost.org/libs/graph/doc/IncidenceGraph.html}{IncidenceGraph}\\
\ccAnchor{http://www.boost.org/libs/graph/doc/PropertyGraph.html}{PropertyGraph}

A model of \ccRefName\ must have the {\em interior properties} 
\ccc{edge_is_border} attached to its edges,
and it must have \ccc{vertex_is_border} and \ccc{vertex_point} attached to its vertices.




\ccHeading{Associated Types}


\ccNestedType{halfedge_graph_traits<HalfedgeGraph>::Point}
{The type of the geometric location of a vertex.}


Because (directed) edges must come in pairs, there is the additional
notion of an {\em undirected edge}\footnote{
The directed edges are not called \ccc{halfedges} (as in a
\ccc{HalfedgeDS}) because from the point of view of this graph, being
a refinement of a {\sc Bgl} graph, each directed edge is an
edge in itself. In other words, the unqualified term edge
refers to one and only one directed edge and not to a pair.}
% 
for a pair of opposite directed edges.
The number of undirected edges is exactly half the number of directed edges.

 
Note that the notion of directed and undirected edges does not imply
the existence of two different types.  The type \ccc{edge_descriptor}
is used for both.  An undirected edge must be implicitly handled, and
there is no requirement on which of the directed edges of the undirected edge
must be used to represent it.



  \ccNestedType{halfedge_graph_traits<HalfedgeGraph>::undirected_edge_iterator}
  {An iterator that iterates over one and only one of the directed edges
  in each pair of opposite directed edges. The value type of the iterator 
  is \ccc{boost::graph_traits<HalfedgeGraph>::edge_descriptor}.}{}


\ccHeading{Valid Expressions}

Following the {\sc Bgl} design, the following graph operations are defined as free 
rather than member functions.

  \ccFunction
  {template<class Graph>
  std::pair<typename halfedge_graph_traits<HalfedgeGraph>::undirected_edge_iterator,
            typename halfedge_graph_traits<HalfedgeGraph>::undirected_edge_iterator>
  undirected_edges(Graph const& g );
  }
  {Returns the undirected edges of \ccc{g}.}


An edge $e=(v,w)$ is said to be the {\em opposite edge} of edge $e'=(w,v)$.

  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  opposite_edge(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Returns the opposite edge of \ccc{e}.}
  
An edge $e'=(v,w)$ is called the {\em clockwise neighbor} of edge
$e=(u,w)$, and $e$ the {\em counterclockwise neighbor} of $e'$, iff there
exist two iterators $it$ and $it'$ in the iterator range
\ccc{in_edges(w,g)} such that \ccc{**it == e} and \ccc{**it' == e'},
and \ccc{it' == it++} or \ccc{it} is the last and \ccc{it'} the first
iterator of the iterator range.
 

  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  next_edge_cw(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Returns the clockwise neighbor of \ccc{e}.}
  

  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  next_edge_ccw(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Returns the counterclockwise neighbor of \ccc{e}.}
  
A composition of these access functions yields an access function for
the edge cycle adjacent to the same face.  An edge $e'=(v,w)$ is
called the {\em successor} of edge $e=(u,v)$, and $e$ the {\em
predecessor} of $e'$, iff $e'$ is the clockwise neighbor of the
opposite edge of $e$.
 

  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  next_edge(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Returns the successor of \ccc{e}.}
  
  \ccFunction
  {template<class Graph>
  typename boost::graph_traits<Graph const>::edge_descriptor 
  prev_edge(typename boost::graph_traits<Graph const>::edge_descriptor e, Graph const& g );
  }
  {Returns the predecessor of \ccc{e}.}

\ccHasModels
\ccRefIdfierPage{CGAL::Polyhedron_3<Traits>}

\end{ccRefConcept}
