% +------------------------------------------------------------------------+
% | Reference manual page: Polyhedron_incremental_builder_3.tex
% +------------------------------------------------------------------------+
% | 17.03.1999   Lutz Kettner
% | Package: Polyhedron
% | 
\RCSdef{\RCSPolyhedronincrementalbuilderRev}{$Id$}
\RCSdefDate{\RCSPolyhedronincrementalbuilderDate}{$Date$}
% +------------------------------------------------------------------------+

\ccRefPageBegin

%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+


\begin{ccRefClass}{Polyhedron_incremental_builder_3<HDS>}
\label{pagePolyIncrBuilder}

\ccDefinition
\ccCreationVariable{B}
  
The auxiliary class \ccClassTemplateName\ supports the incremental
construction of polyhedral surfaces, which is for example convenient
when constructing polyhedral surfaces from file formats, such as the
Object File Format (OFF)~\cite{cgal:p-gmgv16-96},
OpenInventor~\cite{cgal:w-impoo-94} or 
VRML~\cite{cgal:bpp-vrml-95,cgal:vrmls-96}.
\ccClassTemplateName\ needs access to the internal halfedge data
structure of type \ccc{HDS} of the polyhedral surface. It is intended
to be used within a modifier, see \ccc{CGAL::Modifier_base}.

The incremental builder might be of broader interest for other uses of
the halfedge data structures, but it is specifically bound to the
definition of polyhedral surfaces given here. During construction all
conditions of polyhedral surfaces are checked and in case of violation
an error status is set. A diagnostic message will be issued to
\ccc{cerr} if the \ccc{verbose} flag has been set at construction
time.

The incremental construction starts with a list of all point
coordinates and concludes with a list of all facet polygons. Edges are
not explicitly specified. They are derived from the vertex incidence
information provided from the facet polygons. The polygons are given as a
sequence of vertex indices.  The halfedge data structure \ccc{HDS} must
support vertices (i.e., \ccc{Supports_halfedge_vertex} $\equiv$
\ccc{CGAL::Tag_true}). Vertices and facets can be added in arbitrary order
as long as a call to \ccc{add_vertex_to_facet()} refers only to a
vertex index that is already known. Some methods return already
handles to vertices, facets, and halfedges newly constructed. They can
be used to initialize additional fields, however, the incidences in
the halfedge-data structure are not stable and are not allowed to be
changed.

The incremental builder can work in two modes: \ccc{RELATIVE_INDEXING} (the
default), in which a polyhedral surface already contained in the
halfedge data structure is ignored and all indices are relative to the
newly added surface, or \ccc{ABSOLUTE_INDEXING}, in which all indices are
absolute indices including an already existing polyhedral surface. The
former mode allows to create easily independent connected components,
while the latter mode allows to to continue the construction of an
existing surface, the absolute indexing allows to address existing
vertices when creating new facets.

\ccInclude{CGAL/Polyhedron_incremental_builder_3.h}

\ccTypes

\ccThree{typedef typename HalfedgeDS::Halfedge_handleMMMMM}{Halfedge_handle;}{}
\ccTwo{typedef typename HalfedgeDS::Halfedge_handleMMMMM}{}

\ccNestedType{HalfedgeDS}{halfedge data structure \ccc{HDS}.}
\ccGlue
\ccNestedType{Point_3}{point type of the vertex.}
\ccGlue
\ccNestedType{size_type}{size type.}

\ccTypedef{typedef typename HalfedgeDS::Vertex_handle   Vertex_handle;}{}
\ccGlue
\ccTypedef{typedef typename HalfedgeDS::Halfedge_handle Halfedge_handle;}{}
\ccGlue
\ccTypedef{typedef typename HalfedgeDS::Face_handle    Facet_handle;}{}

\ccConstants

\ccEnum{enum { RELATIVE_INDEXING, ABSOLUTE_INDEXING};}{two different indexing modes.}


\ccCreation
\ccThree{Halfedge_handle}{B.add_vertex( Point}{}
\ccThreeToTwo

\ccConstructor{Polyhedron_incremental_builder_3(HDS& hds, 
               bool verbose = false);}
 {stores a reference to the halfedge data structure \ccc{hds} of a
   polyhedral surface in its internal state. An existing polyhedral
   surface in \ccc{hds} remains unchanged. The incremental builder
   appends the new polyhedral surface. If \ccc{verbose} is \ccc{true},
   diagnostic messages will be printed to \ccc{cerr} in case of
   malformed input data.}

\ccHeading{Surface Creation}

To build a polyhedral surface, the following regular expression gives
the correct and allowed order and nesting of method calls from this
section:

{\it
    \hspace*{6mm} begin\_surface $($add\_vertex $|$ 
                  $($begin\_facet add\_vertex\_to\_facet$\:*$
                            end\_facet\/$))\:*$ end\_surface
}


\ccMethod{void begin_surface( size_type v, size_type f, size_type h = 0,
                              int mode = RELATIVE_INDEXING);}
{starts the construction. $v$ is the number of new vertices
    to expect, $f$ the number of new facets, and $h$ the number of
    new halfedges. If $h$ is unspecified (\ccc{== 0}) it is estimated using
    Euler's equation (plus 5\% for the so far unknown holes and genus of
    the object). These values are used to reserve space in the
    halfedge data structure \ccc{hds}. If the representation supports
    insertion these values do not restrict the class of constructible
    polyhedra. If the representation does not support insertion the
    object must fit into the reserved sizes.\\
    If \ccc{mode} is set to \ccc{ABSOLUTE_INDEXING} the incremental builder
    uses absolute indexing and the vertices of the old polyhedral surface
    can be used in new facets (needs preprocessing time linear in the
    size of the old surface). Otherwise relative indexing is used 
    starting with new indices for the new construction.}

\ccMethod{Vertex_handle add_vertex( const Point_3& p);}{
    adds a new vertex for $p$ and returns its handle.}

\ccMethod{Facet_handle begin_facet();}{
    starts a new facet and returns its handle.}

\ccMethod{void add_vertex_to_facet( size_type i);}{adds a vertex with
  index $i$ to the current facet. The first point added with
  \ccc{add_vertex()} has the index 0 if \ccc{mode} was set to 
  \ccc{RELATIVE_INDEXING}, otherwise the first vertex in the 
  referenced \ccc{hds} has the index 0.}

\ccMethod{Halfedge_handle end_facet();}{ends a newly constructed facet.
     Returns the handle to the halfedge incident to the new facet that points
     to the vertex added first. The halfedge can be safely used to traverse
     the halfedge cycle around the new facet.}

\ccMethod{void end_surface();}{ends the construction.}

\ccHeading{Additional Operations}

\ccMethod{template <class InputIterator>
    Halfedge_handle add_facet( InputIterator first, InputIterator beyond);}{
    is a synonym for \ccc{begin_facet()}, a call to \ccc{add_vertex_to_facet()} for each
    value in the range \ccc{[first,beyond)}, and a call to \ccc{end_facet()}.
    Returns the return value of \ccc{end_facet()}.
    \ccPrecond{The value type of \ccc{InputIterator} is \ccc{std::size_t}.
    All indices must refer to vertices already added.}}

\ccMethod{template <class InputIterator>
    bool test_facet( InputIterator first, InputIterator beyond);}{
    returns \ccc{true} if a facet described by the vertex indices in the range 
    \ccc{[first,beyond)} can be successfully inserted, e.g., with 
    \ccc{add_facet(first,beyond)}.
    \ccPrecond{The value type of \ccc{InputIterator} is \ccc{std::size_t}.
    All indices must refer to vertices already added.}}

\ccMethod{Vertex_handle vertex( std::size_t i);}{
    returns handle for the vertex of index $i$, or \ccc{Vertex_handle} if 
    there is no $i$-th vertex.}

\ccMethod{bool error() const;}{returns error status of the builder.}

\ccMethod{void rollback();}{undoes all changes made to the halfedge
  data structure since the last \ccc{begin_surface()} in relative
  indexing, and deletes the whole surface in absolute indexing.
  It needs a new call to \ccc{begin_surface()} to start inserting again.}

\ccMethod{bool check_unconnected_vertices();}{returns
  \ccc{true} if unconnected vertices are detected. If \ccc{verbose} was set to
  \ccc{true} (see the constructor above) debug information about the
  unconnected vertices is printed.}

\ccMethod{bool remove_unconnected_vertices();}{returns
  \ccc{true} if all unconnected vertices could be removed successfully.
  This happens either if no unconnected vertices had appeared or if the
  halfedge data structure supports the removal of individual elements.}


\ccSeeAlso

\ccRefIdfierPage{CGAL::Polyhedron_3<Traits>}\\
\ccRefIdfierPage{HalfedgeDS}\\
\ccc{CGAL::Modifier_base}.

\ccExample

A modifier class creates a new triangle in the halfedge data structure
using the incremental builder.

\ccIncludeExampleCode{Polyhedron/polyhedron_prog_incr_builder.cpp}

\end{ccRefClass}

% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd
% EOF
% +------------------------------------------------------------------------+

