CGAL::Polyhedron_incremental_builder_3<HDS>

Definition

The auxiliary class Polyhedron_incremental_builder_3<HDS> 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) [Phi96], OpenInventor [Wer94] or VRML [BPP95, VRM96]. Polyhedron_incremental_builder_3<HDS> needs access to the internal halfedge data structure of type HDS of the polyhedral surface. It is intended to be used within a modifier, see 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 cerr if the 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 HDS must support vertices (i.e., Supports_halfedge_vertex $$ CGAL::Tag_true). Vertices and facets can be added in arbitrary order as long as a call to 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: 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 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.

#include <CGAL/Polyhedron_incremental_builder_3.h>

Types

Constants

Creation

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:

begin_surface $$(add_vertex $$| $$(begin_facet add_vertex_to_facet$$* end_facet$$))* end_surface

Additional Operations

See Also

CGAL::Polyhedron_3<Traits>
HalfedgeDS
CGAL::Modifier_base.

Example

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

File: examples/Polyhedron/polyhedron_prog_incr_builder.cpp

#include <CGAL/Simple_cartesian.h>
#include <CGAL/Polyhedron_incremental_builder_3.h>
#include <CGAL/Polyhedron_3.h>

// A modifier creating a triangle with the incremental builder.
template <class HDS>
class Build_triangle : public CGAL::Modifier_base<HDS> {
public:
    Build_triangle() {}
    void operator()( HDS& hds) {
        // Postcondition: `hds' is a valid polyhedral surface.
        CGAL::Polyhedron_incremental_builder_3<HDS> B( hds, true);
        B.begin_surface( 3, 1, 6);
        typedef typename HDS::Vertex   Vertex;
        typedef typename Vertex::Point Point;
        B.add_vertex( Point( 0, 0, 0));
        B.add_vertex( Point( 1, 0, 0));
        B.add_vertex( Point( 0, 1, 0));
        B.begin_facet();
        B.add_vertex_to_facet( 0);
        B.add_vertex_to_facet( 1);
        B.add_vertex_to_facet( 2);
        B.end_facet();
        B.end_surface();
    }
};

typedef CGAL::Simple_cartesian<double>     Kernel;
typedef CGAL::Polyhedron_3<Kernel>         Polyhedron;
typedef Polyhedron::HalfedgeDS             HalfedgeDS;

int main() {
    Polyhedron P;
    Build_triangle<HalfedgeDS> triangle;
    P.delegate( triangle);
    CGAL_assertion( P.is_triangle( P.halfedges_begin()));
    return 0;
}