mirror of https://github.com/CGAL/cgal
213 lines
9.0 KiB
TeX
213 lines
9.0 KiB
TeX
% +------------------------------------------------------------------------+
|
|
% | Reference manual page: Polyhedron_incremental_builder_3.tex
|
|
% +------------------------------------------------------------------------+
|
|
% | 17.03.1999 Lutz Kettner
|
|
% | Package: Polyhedron
|
|
% |
|
|
\RCSdef{\RCSPolyhedronincrementalbuilderRev}{$Revision$}
|
|
\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} in the
|
|
Support Library Reference Manual.
|
|
|
|
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_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} in the Support Library Reference Manual.
|
|
|
|
\ccExample
|
|
|
|
A modifier class creates a new triangle in the halfedge data structure
|
|
using the incremental builder.
|
|
|
|
\ccIncludeExampleCode{Polyhedron/polyhedron_prog_incr_builder.C}
|
|
|
|
\end{ccRefClass}
|
|
|
|
% +------------------------------------------------------------------------+
|
|
%%RefPage: end of main body, begin of footer
|
|
\ccRefPageEnd
|
|
% EOF
|
|
% +------------------------------------------------------------------------+
|
|
|