A halfedge data structure \cite{hds} 
is an edge-centered data structure
capable of maintaining incidence informations of vertices, edges and
faces, for example for planar maps, polyhedra, or other orientable,
two-dimensional surfaces embedded in arbitrary dimension. Each edge is
decomposed into two halfedges with opposite orientations. One incident
face and one incident vertex are stored in each halfedge. For each
face and each vertex, one incident halfedge is stored (see
Fig.\ref{fig:halfedge}). The halfedge is designated as the
connectivity primitive. Connectivity manipulations are based
on the reconfiguration and the mesh traversal is equivalent
to the adjacency walkng of the halfedges. Halfedge data 
structures have been very successful for the design of
algorithms on meshes for several reasons:
\begin{itemize}
\item halfedges contain a constant number of adjacencies. 
\item halfedges encode the mesh orientation
\item navigation around vertices or facets is easy.
\item corner attributes, such as crease normals, is allowed 
to be associated with halfedges.
\end{itemize}

% halfedge
\begin{figure}[htb]
    \centering{\includegraphics[width=7.0cm]{figs/halfedge}}
    \caption{One halfedge and its incident primitives.}
    \label{fig:halfedge}
\end{figure}
        
\cgalhds\ is a combinatorial data structure. The geometric 
interpretation is instantiated by classes encapsulating 
the halfedge data structure. For examples, the \cgalpoly\ 
encapsulates a \hds\ as an oriented 2-manifold with 
possible boundaries. A \hds\ is a class template and 
is used as an argument for \poly. The template 
parameters to instantiate the \hds\lstinline!<Traits,Items,Alloc>! 
will be provided by the \poly\ (or other encapsulating classes).
\emph{Trait} is a geometric traits class supplied by the 
encapsulating classes. It will not be used in \hds\ itself. 
\emph{Items} is a model of the \emph{HalfedgeDSItems} concept
that defines the vertex, halfedge, and face for a halfedge data
structure. \emph{Alloc} is a standard allocator that fulfills all 
requirements of allocators for STL container classes. 

In the \poly, the \hds\ is interfaced and indirectly manipulated
by the \poly. Since \hds\ is the internal representation of the
connectivity structure, primitives travesal of the \poly\ is
supported by the \hds . As a container, the \hds\ provides 
iterators of the primitives, i.e. vertices, halfedges and faces.
This primitive iterators visit the primitives on the storage
order of the internal list or vector. As a connected graph,
the \hds\ provides circulators around vertices or faces.
The circulator visits the halfedges ajacent to the vertex
in CW order and the face in CCW order. Details of using iterators
and circulators can be found at \ref{sec:??}.

Halfedges in a \hds\ also provide a set of low-level 
traversal operators. These operators include the prev(), next(), 
opposite(), vertex(), and face(). The prev(), next() and opposite()
return the handle of the previous, next and opposite
halfedge respectively. The vertex() returns the handle of the 
incidence vertex and the face() returns the handle of the 
incidence face. The next() and opposite() are mandatory and others
are optionally support. Though in this tutorial, a compelete
support is assumed. For how to define a partially support \hds ,
readers should refer to \cite{cgalmanul}.   

TODO: need codes to demo the low level traversal and a figure
explains it. 
