songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

BGL user manual improvements

This commit is contained in:
Mael Rouxel-Labbé 2018-02-08 18:16:17 +01:00
parent e87001f764
commit d9d2668c8d
2 changed files with 161 additions and 129 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

284
BGL/doc/BGL/BGL.txt
View File

@ -22,95 +22,104 @@ Furthermore, this package extends the \sc{Bgl}
by introducing concepts such as `HalfedgeGraph` and `FaceGraph`
allowing to handle *halfedges* and *faces*.
These concepts reflect the design of the halfedge data structure described
in Chapter \ref PkgHDSSummary, with opposite halfedges, and the circular
sequence of halfedges around vertices and around faces.
in Chapter \ref PkgHDSSummary, with opposite halfedges and circular
sequences of halfedges around vertices and around faces.
This chapter is organized as follows. Section \ref BGLA present
the ideas of \sc{Bgl} in a nutshell. Section \ref BGLHeader explains
where to find header files and the chosen naming conventions, as we blend two
different libraries. The four following sections give examples for
how the surface mesh, the polyhedron, the arrangement, and the 2D triangulation classes
are adapted to \sc{Bgl}. Starting with Section \ref BGLExtensions, we introduce
new concepts, classes, and functions that extend the functionalities of the \sc{Bgl}.
This chapter is organized as follows:
- The first section, Section \ref BGLA, summarizes the main ideas of the \sc{Bgl}.
- Section \ref BGLHeader then explains where to find header files and the chosen naming conventions, as we blend two
different libraries.
- The four following sections give examples on how to use CGAL graph and mesh data structures
such as
\link PkgSurfaceMeshSummary Surface_mesh \endlink,
\link PkgPolyhedronSummary Polyhedron \endlink,
\link PkgArrangement2Summary Arrangement_2 \endlink, and the
\link PkgTriangulation2Summary 2D triangulation \endlink classes as models of the \sc{Bgl} concepts.
- Starting with Section \ref BGLExtensions, we introduce new graph concepts, classes,
and functions that extend the functionalities of the \sc{Bgl}.
\section BGLA A Short Introduction to the Boost Graph Library
The algorithms of \sc{Bgl} operate on models of the various <I>graph concepts</I>.
The <I>traits class</I> `boost::graph_traits` enable the algorithms determining the types of vertices and edges
The algorithms of the \sc{Bgl} operate on models of various <I>graph concepts</I>.
The <I>traits class</I> `boost::graph_traits` enable algorithms to determine the types of vertices and edges
(similar to `std::iterator_traits` for iterators).
<I>Free functions</I> that operate on graphs enable the algorithms to obtain,
<I>Free functions</I> that operate on graphs enable algorithms to obtain,
for example, the source vertex of an edge, or all edges incident to a vertex. The algorithms
use <I>property maps</I> to associate information with vertices and edges.
The algorithms enable <I>visitors</I> to register callbacks that are called
later on during the execution of the algorithms. Finally, the graph algorithms use
the <I>named parameter</I> mechanism, which enambles passing the arguments in
the <I>named parameter</I> mechanism, which enables passing the arguments in
arbitrary order.
\subsection BGLGraphConcepts Graph Concepts
\sc{Bgl} introduces several <a href="http://www.boost.org/libs/graph/doc/graph_concepts.html">graph concepts</a>,
The \sc{Bgl} introduces several <a href="http://www.boost.org/libs/graph/doc/graph_concepts.html">graph concepts</a>,
which have different sets of characteristics and requirements.
For example iterating through all vertices or all edges in a graph, obtaining the outgoing
edges of a vertex, or also the in-going edges, inserting vertices and edges into a graph, and removing vertices and edges from a graph.
For example, iterating through all vertices or all edges in a graph, obtaining the outgoing
or in-going edges of a vertex, inserting vertices and edges into a graph,
and removing vertices and edges from a graph.
\subsection BGLTheGraphTraitsClass The Graph Traits Class
An algorithm operating on a graph model determines types with the help of the traits class
<a href="http://www.boost.org/libs/graph/doc/graph_traits.html">boost::graph_traits</a>.
Such types are the `vertex_descriptor`,
which is similar to a vertex handle in \cgal data structures,
the `edge_descriptor` which is similar to the halfedge handle in
the halfedge data structure and to the type `Edge` in 2D triangulations.
which is similar to a vertex handle in \cgal data structures, or
the `edge_descriptor`, which is similar to the \link HalfedgeDSHalfedge halfedge handle \endlink in
the halfedge data structure or to the type \link Triangulation_2::Edge Edge \endlink in 2D triangulations.
There are also iterators, such as the `vertex_iterator`, which is similar
to a vertex iterator in \cgal data structures, and the `out_edge_iterator`,
which is similar to the edge circulator; it enables to iterate through the edges
incident to a vertex. The iterators are similar and not equivalent,
because their value type is a `vertex_descriptor`, whereas in
\cgal handles, iterators, and circulators all have the same value
type, namely the vertex or edge type. Given a graph type `G` the
definition of a vertex descriptor looks as follows:
type, namely the vertex or edge types.
Given a graph type `G`, definitions of descriptors and iterators look as follows:
\code {.cpp}
boost::graph_traits<Graph>::vertex_descriptor vd;
boost::graph_traits<Graph>::edge_iterator ei;
...
\endcode
\subsection BGLFreeFunctionsforExploringaGraph Free Functions for Exploring a Graph
The algorithms obtain incidence information with the help of global
Algorithms obtain incidence information in graphs with the help of global
functions such as:
- `std::pair<vertex_iterator,vertex_iterator> vertices(const Graph& g);` for obtaining an iterator range providing access to all the vertices, or
- `int num_vertices(const Graph&);` for obtaining the number of vertices of a graph, or
- `vertex_descriptor source(edge_descriptor, const Graph&);` for
obtaining the source vertex of an edge.
- `std::pair<vertex_iterator,vertex_iterator> vertices(const Graph& g);` to obtain an iterator range providing access to all the vertices, or
- `int num_vertices(const Graph&);` to obtain the number of vertices of a graph, or
- `vertex_descriptor source(edge_descriptor, const Graph&);` to obtain the source vertex of an edge.
Note, that the way we have written the types is a simplification, that is in reality
the signature of the first of the above functions is
Note, that the way we have written the types is a simplification; in reality,
the signature of the first of the above functions is:
\code{.cpp}
typedef boost::graph_traits<Graph>::vertex_iterator vertex_iterator;
std::pair<vertex_iterator,vertex_iterator> vertices(const Graph& g);
\endcode
\subsection BGLPropertyMaps Property Maps
Another feature extensively used in \sc{Bgl} is the *property map*,
Another feature extensively used in the \sc{Bgl} is the *property map*,
which is offered by the <a href="http://www.boost.org/libs/property_map/doc/property_map.html">Boost Property Map Library</a>. Property maps
are a general purpose interface for mapping key objects to
corresponding value objects.
\sc{Bgl} uses property maps to associate information with vertices and edges.
The \sc{Bgl} uses property maps to associate information with vertices and edges.
This mechanism uses a traits class (`boost::property_traits`) and free
functions for obtaining (`get`) and writing (`put`) information in vertices,
edges, and also halfedges and faces for models of the \cgal graph concepts.
For example, \sc{Bgl}
functions to read (`get`) and write (`put`) information in vertices,
edges, and also in halfedges and faces for models of the \cgal graph concepts.
For example, the \sc{Bgl}
Dijksta's shortest path algorithm writes the predecessor of each vertex, as
well as the distance to the source in such a property map.
well as the distance to the source in such a property map.
Some default property maps are associated with the graph types. They
are called *internal property maps* and can be retrieved using an
overload of the function `get()`. For example, pm = get(boost::vertex_index, g)
overload of the function `get()`. For example,
\code{.cpp}
pm = get(boost::vertex_index, g)
\endcode
returns a property map that associates an index
in the range `[0, num_vertices(g))` with each vertex of the graph.
This reduces the number of parameters to pass.
@ -118,38 +127,46 @@ The data itself may be stored in the vertex or the edge, or it may
be stored in an external data structure, or it may be computed on
the fly. This is an implementation detail of a particular property map.
See also the Chapter \ref PkgProperty_mapSummary.
See also Chapter \ref PkgProperty_mapSummary.
\subsection BGLVisitors Visitors
Visitors are objects that provide functions that are called at
specified event points by the algorithm they visit.
The functions as well as the event points are algorithm specific. Examples of event points in graph algorithms are when a vertex is traversed the first time, or when all outgoing edges of a vertex are traversed.<BR>
Visitors are objects that provide functions to be called at
specified event points by the algorithm that they visit.
The functions as well as the event points are algorithm-specific.
Examples of such event points in graph algorithms are when a vertex is traversed the first time,
or when all outgoing edges of a vertex have been traversed.<BR>
See also Section <A HREF="http://www.boost.org/libs/graph/doc/visitor_concepts.html">Visitor Concepts</A>
in the \sc{Bgl} manual.
\subsection BGLNamedParameters Named Parameters
The notion of named parameters was introduced in the BGL.
You can read about it in the following site: http://www.boost.org/libs/graph/doc/bgl_named_params.html.
Named parameters allow the user to specify only those parameters which are really needed, by name, making the parameter ordering unimportant.
The notion of <I>named parameters</I> was introduced in the \sc{Bgl},
and allow the user to specify only those parameters which are really needed, by name, making the parameter ordering unimportant.
See also <a href="http://www.boost.org/libs/graph/doc/bgl_named_params.html">this page</a>
in the manual of the \sc{Bgl} for more information.
Say there is a function `f()` that takes 3 parameters called name, age and gender, and you have variables `n`, `a` and `g` to pass as parameters to that function. Without named parameters, you would call it like this: `f(n,a,g)`, whereas with named parameters, you call it like this: `f(name(n).age(a).gender(g))`.
That is, you give each parameter a name by wrapping it into a function whose name matches that of the parameter. The entire list of named parameters is really a composition of function calls separated by a dot ( .). Thus, if the function takes a mix of mandatory and named parameters, you use a comma to separate the last non-named parameter from the first named parameters, like this:
`f(non_named_par0, non_named_par1, name(n).age(a).gender(g))`
When you use named parameters, the ordering is irrelevant, so `f(name(n).age(a).gender(g))` is equivalent to `f(age(a).gender(g).name(n))`, and you can just omit any named parameter that has a default value.
Say there is a function `f()` that takes 3 parameters called name, age and gender,
and you have variables `n`, `a` and `g` to pass as parameters to that function.
Without named parameters, you would call it like this: `f(n,a,g)`,
whereas with named parameters, you call it like this: `f(name(n).age(a).gender(g))`.
That is, you give each parameter a name by wrapping it into a function whose name
matches that of the parameter. The entire list of named parameters is really
a composition of function calls separated by a dot ("."). Thus, if the function
takes a mix of mandatory and named parameters, you use a comma to separate
the last non-named parameter from the first named parameters, like this:
\code{.cpp}
f(non_named_par0, non_named_par1, name(n).age(a).gender(g))
\endcode
When you use named parameters, the ordering is irrelevant, so `f(name(n).age(a).gender(g))`
is equivalent to `f(age(a).gender(g).name(n))`, and you can just omit any named parameter that has a default value.
The sequence of named parameters should start with `CGAL::parameters::`.
\subsubsection BGLNamedParametersExample Example
See below a sample call of a function that uses the optional BGL named parameters.
Below is a sample call of a function that uses the optional BGL named parameters.
\code
// pmesh : polygon mesh with patches to be refined
@ -158,36 +175,49 @@ See below a sample call of a function that uses the optional BGL named parameter
// vertices_out : output iterator into which descriptors of new vertices are put
// vertex_point_map : the property map with the points associated to the vertices of `pmesh`
// density_control_factor : factor to control density of the output mesh
refine(pmesh
, faces
, faces_out
, vertices_out
, CGAL::Polygon_mesh_processing::parameters::vertex_point_map(vpmap)
.density_control_factor(d));
refine(pmesh,
faces,
faces_out,
vertices_out,
CGAL::parameters::vertex_point_map(vpmap)
.density_control_factor(d));
\endcode
\section BGLHeader Header Files, Namespaces, and Naming Conventions
Partial specializations of the `boost::graph_traits<Graph>` for the \cgal package `PACKAGE` are in the
namespace `boost` and in the header file `CGAL/boost/graph/graph_traits_PACKAGE.h`. The
free functions are in the namespace `CGAL`, as the compiler uses argument dependent lookup to find them.
The %Euler operations are in the namespace `CGAL::Euler`, as the function `remove_face()` is at
the same time a low level and an %Euler operation.
Concerning the naming conventions we have to use those of \sc{Bgl}, as we have to fulfill the requirements of the concepts defined in \sc{Bgl}.
This package provides the necessary classes and functions that enable using the
some \cgal data structures as models of the \sc{Bgl} graph concepts.
To this end, we offer partial specializations of the `boost::graph_traits<Graph>` for various \cgal packages.
For each such package, denoted `PACKAGE`, the partial specializations live in
the namespace `boost` and are located in the header file `CGAL/boost/graph/graph_traits_PACKAGE.h`.
Free functions are in the namespace `CGAL`, and the compiler uses argument-dependent lookup to find them.
%Euler operations, described in Section \ref BGLEulerOperations, are in the namespace `CGAL::Euler`, as the function `remove_face()` is at
the same time a low-level and an %Euler operation.
Concerning the naming conventions, we have to use those of the \sc{Bgl},
as to fulfill the requirements of the concepts defined in the \sc{Bgl}.
Note that these partial specializations are often providing more than
is required, making these classes not only models of the graph concepts
of the \sc{Bgl}, but also models of the CGAL graph concepts, that will
described in detail in Section \ref BGLExtensions. Correspondence tables
between the types of a \cgal data structure and their \sc{Bgl} equivalents
can be found in the \ref PkgBGLTraits documentation page.
We present in the following sections some examples of utilization of some
\cgal data structures as \sc{Bgl} graphs.
\section BGLSurface_mesh The Class Surface_mesh as Model of the Boost Graph Concept
The class `Surface_mesh` is a model of most of \sc{Bgl} graph
concepts as well as the concepts provided by \cgal. A full list can
be found in the documentation of `boost::graph_traits`. The examples show how to use some of
the \sc{Bgl} algorithms with `Surface_mesh` and show how to use
The class `Surface_mesh` is a model of most of the graph concepts of the \sc{Bgl}
as well as the concepts provided by \cgal. A complete list can
be found in the documentation of \link BGLSMGT boost::graph_traits \endlink.
The examples show how to use some of the \sc{Bgl} algorithms with `Surface_mesh` and show how to use
the concepts provided by \cgal to implement a simple algorithm.
\subsection BGLExampleMinimumSpanningTreeofaSurfaceMesh Example: Minimum Spanning Tree of a Surface_mesh
The following example program computes the minimum spanning tree on a surface mesh.
More examples can be found in the chapters
More examples can be found in Chapters
\ref PkgSurfaceMeshSimplificationSummary, \ref PkgSurfaceSegmentationSummary, and \ref PkgSurfaceMeshDeformationSummary.
The surface mesh class uses integer indices to address vertices and edges,
@ -195,14 +225,12 @@ and it comes with a built-in property mechanism that maps nicely on the \sc{Bgl}
\cgalExample{BGL_surface_mesh/prim.cpp}
\section BGLPolyhedral The Class Polyhedron_3 as Model of the Boost Graph Concept
The class `Polyhedron_3` is a model of most of \sc{Bgl} graph
concepts as well as the concepts provided by \cgal. A full list can
be found in the documentation of `boost::graph_traits`. The examples show how to use some of
the \sc{Bgl} algorithms with `Polyhedron_3` and show how to use
The class `Polyhedron_3` is a model of most of the graph concepts of the \sc{Bgl}
as well as the concepts provided by \cgal. A complete list can
be found in the documentation of \link BGLPolyGT boost::graph_traits \endlink.
The examples show how to use some of the \sc{Bgl} algorithms with `Polyhedron_3` and show how to use
the concepts provided by \cgal to implement a simple algorithm.
\subsection BGLExampleMinimumSpanningTreeofaPolyhedral Example: Minimum Spanning Tree of a Polyhedral Surface
@ -223,15 +251,18 @@ The main function illustrates the access to the `id()` field.
\cgalExample{BGL_polyhedron_3/kruskal_with_stored_id.cpp}
\section BGLTriangulations Triangulations as Models of the Boost Graph Concept
Triangulations have vertices and faces. An edge is a pair of a face handle and the
Triangulations have vertices and faces, allowing for a direct translation
as a graph. An edge is defined as a pair of a face handle and the
index of the edge.
Particular care has to be taken with the infinite vertex and its incident
edges. One can either use a `boost::filtered_graph` in order to make the infinite edges
edges. One can either use a
<a href="http://www.boost.org/libs/graph/doc/filtered_graph.html">boost::filtered_graph</a>
in order to make the infinite edges
invisible, or one can have a property map that returns an infinite length
for these edges.
A complete list can be found in the documentation of \link BGLT2GT boost::graph_traits \endlink.
A classical example for an algorithm that is a combination of
computational geometry and graph theory is the <I>Euclidean Minimum
@ -250,7 +281,7 @@ integers in the range `[0, t.number_of_vertices())`.
\subsection BGLExampleStoringtheVertexIDintheVertex Example: Storing the Vertex ID in the Vertex
The algorithms of \sc{Bgl} extensively use of the indices of
The algorithms of the \sc{Bgl} extensively use of the indices of
vertices. In the previous example we stored the indices in a `std::map`
and turned that map in a property map. This property map was then
passed as argument to the shortest path function.
@ -269,8 +300,8 @@ for the Delaunay triangulation.
\section BGLArrangements Arrangements as Models of the Boost Graph Concept
\cgal offers the graph traits for the arrangement
itself as well as for its dual graph.
\cgal offers a partial specialization of the boost graph traits for its arrangement
class as well as for its dual graph.
\subsection arr_sssecbgl_primal Example for the Arrangement as Graph
@ -291,11 +322,11 @@ edges in our <I>boost</I> graph.
Given an `Arrangement_2` instance, we can efficiently traverse its
vertices and halfedges. Thus, the arrangement graph is a model of the concepts
`VertexListGraph` and `EdgeListGraph` introduced by \sc{Bgl}.
`VertexListGraph` and `EdgeListGraph` introduced by the \sc{Bgl}.
At the same time, we use an iterator adapter of the circulator over the
halfedges incident to a vertex (`Halfedge_around_target_circulator` - see
Section \ref arr_sssectr_vertex "Traversal Methods for an Arrangement Vertex"
of the chaper on arrangements), so it is possible to go over the ingoing
of the chapter on arrangements), so it is possible to go over the ingoing
and outgoing edges of a vertex in linear time. Thus, our arrangement graph
is a model of the concept `BidirectionalGraph` (this concept refines
`IncidenceGraph`, which requires only the traversal of outgoing edges).
@ -305,14 +336,17 @@ It is important to notice that the vertex descriptors we use are
to gain more efficiency in most \sc{Bgl} algorithm, it is better to have them
indexed \f$ 0, 1, \ldots, (n-1)\f$, where \f$ n\f$ is the number of vertices. We
therefore introduce the `Arr_vertex_index_map<Arrangement>` class-template,
which maintains a mapping of vertex handles to indices, as required by
which maintains a mapping of vertex handles to indices, as required by the
\sc{Bgl}. An instance of this class must be attached to a valid arrangement
vertex when it is created. It uses the notification mechanism (see
Section \ref arr_secnotif) to automatically maintain the mapping of vertices
to indices, even when new vertices are inserted into the arrangement or
existing vertices are removed.
In most algorithm provided by \sc{Bgl}, the output is given by
A complete description of the types correspondences
can be found in the documentation of \link BGLArgtGT boost::graph_traits \endlink.
In most algorithm provided by the \sc{Bgl}, the output is given by
<I>property maps</I>, such that each map entry corresponds to a vertex.
For example, when we compute the shortest paths from a given source vertex
\f$ s\f$ to all other vertices we can obtain a map of distances and a map of
@ -325,7 +359,7 @@ template allows for an efficient mapping of `Vertex_handle` objects to
properties of type `Type`. Note however that unlike the
`Arr_vertex_index_map` class, the vertex property-map class is not
kept synchronized with the number of vertices in the arrangement, so it
should not be reused in calls to \sc{Bgl} functions in case the arrangement
should not be reused in calls to the \sc{Bgl} functions in case the arrangement
is modified in between these calls.
\cgalFigureBegin{figex_bgl,ex_bgl.png}
@ -334,7 +368,7 @@ An arrangement of 7 line segments, as constructed by `ex_bgl_primal_adapter.cpp`
In the following example we construct an arrangement of 7 line segments,
as shown in \cgalFigureRef{figex_bgl},
then use \sc{Bgl} Dijkstra's shortest-paths algorithm to compute
then use the \sc{Bgl} Dijkstra's shortest-paths algorithm to compute
the graph distance of all vertices from the leftmost vertex in the
arrangement \f$ v_0\f$. Note the usage of the `Arr_vertex_index_map` and
the `Arr_vertex_property_map` classes. The latter one, instantiated by
@ -379,41 +413,40 @@ accordingly:
\cgalExample{BGL_arrangement_2/arrangement_dual.cpp}
\section BGLExtensions Extensions of the BGL
The previous sections introduced partial specializations
and free functions so that several \cgal data structures are adapted as models of some
of the \sc{Bgl} graph concepts.
In this section, we introduce new concepts, iterators, and property maps inspired
by the functionalities of the BGL.
by the functionalities of the \sc{Bgl}.
\subsection BGLExtensionsGraphConcepts Graph concepts
In this section, we define a set of new concepts to extend the
functionality of \sc{Bgl} in order to match \ref PkgHDSSummary more
closely and to enable writing generic algorithms, which operate on data structures that
have faces and halfedges.
In order to match \ref PkgHDSSummary more closely and to enable writing generic algorithms
which operate on data structures that have faces and halfedges, we define
a set of new concepts to extend the <a href="http://www.boost.org/libs/graph/doc/graph_concepts.html">graph concepts of the BGL</a>:
`HalfedgeGraph` refines
<a href="http://www.boost.org/libs/graph/doc/BidirectionalGraph.html">`Bidirectional Graph`</a> with operations to accommodate halfedge data structures.
Given a halfedge, say `h`, the concept `HalfedgeGraph` requires the provision
- `HalfedgeGraph` refines <a href="http://www.boost.org/libs/graph/doc/Graph.html">`Graph`</a>
with operations to accommodate halfedge data structures:
given a halfedge, say `h`, the concept `HalfedgeGraph` requires the provision
of the halfedge opposite to `h`, the halfedge that succeeds `h`,
and the halfedge that precedes `h`.
`MutableHalfedgeGraph` adds the requirement for operations to
change the next/previous relation and to adjust the target of a halfedge.
`FaceGraph` adds the requirements to explicitly handle faces in
a graph, to provide quick access to incident halfedges of a face, and to
enable access from every halfedge to an adjacent face. `FaceListGraph`
adds the requirement for efficient traversal of
faces. `MutableFaceGraph` adds requirements to change adjacency of
- `HalfedgeListGraph` adds the requirement for efficient traversal of
the halfedges of the graph.
- `MutableHalfedgeGraph` adds the requirement for operations to
change next/previous relations and to adjust the target of a halfedge.
- `FaceGraph` adds the requirements to explicitly handle faces in
a graph, to provide quick access to the incident halfedges of a face, and to
enable access from every halfedge to an adjacent face.
- `FaceListGraph` adds the requirement for efficient traversal of
the faces of a graph.
- `MutableFaceGraph` adds requirements to change adjacency of
faces and halfedges, and to remove and add faces.
The halfedge extensions are used by the surface simplification algorithms,
which follow the design of \sc{Bgl} as sketched in Section \ref BGLA.
A summary of the expressions and types associated with each of these concepts
as well as a refinement relation graph can be found in the
\ref PkgBGLConcepts documentation page.
\subsection BGLIteratorsAndCirculators Iterators and Circulators
@ -427,17 +460,18 @@ to the halfedge where we started. All halfedges traversed on the way are inciden
in another cycle, namely the cycle of halfedges which are incident to
the same vertex.
A complete list of these traversal tools can be found in \link PkgBGLIterators the reference manual\endlink.
For convenience, two iterator and circulator types enable the traversal of all halfedges
incident to a given face, and all halfedges having a given vertex as target.
These types are not part of the concept `HalfedgeGraph`, but they
are class templates that work for any model of this concept.
A complete list of these traversal tools can be found in \link PkgBGLIterators the reference manual\endlink.
\subsubsection BGLExampleIncidentVertices Example: Finding Incident Vertices in a HalfedgeGraph
The following example shows several functions that enable navigating in a `HalfedgeGraph`.
The following example shows several functions to navigate in a `HalfedgeGraph`.
We have two implementations of the operation that finds the vertices adjacent to a vertex `v`.
Let us have a look at the first version. Given a vertex descriptor `vd`,
we first call `halfedge(vd,g)` to obtain the halfedge with `vd` as target.
Applying `source()` then gives us an adjacent vertex. We then get to the next halfedge
@ -447,7 +481,7 @@ going to the opposite halfedge.
The second version does the `%next()` and `%opposite()` jumping with an iterator.
Note that when calling `source()` we have to dereference `hi`, as the function
expects a halfedge descriptor and not a halfedge iterator.
Also note that `halfedges_around_target()` expects a halfedge, and not a vertex.
Also observe that `halfedges_around_target()` expects a halfedge, and not a vertex.
This provides the user with the ability to start the traversal at a specific
halfedge incident to the input vertex (and not the arbitrary incident halfedge
stored in the vertex record.)
@ -475,14 +509,12 @@ The lifetime of a dynamic property is bound to the lifetime
of the property map: reference counting is used to delete the property
when no map refers to it.
Dynamic property tags such as `dynamic_vertex_property_t` are a generalization of
Dynamic property tags, such as `dynamic_vertex_property_t`, are a generalization of
`boost::vertex_index_t`, as they have a template parameter for the
value type of the dynamic property map, and a default value.
`boost::property_map<G,T>::%type` is used to obtain the
`boost::property_map<G,T>::%type` is used to obtain the
type of the dynamic property map for a graph of type `G`, for a
dynamic property tag `T`. This type must be default constructible and assignable.
As for ordinary properties, the function `%get()` is overloaded and
serves for retrieving a property map for a given graph and dynamic
property tag, as well as for retrieving a value for a given key and
@ -521,32 +553,32 @@ face of `G`. The dual graph has an edge whenever two faces of `G` are
separated from each other by an edge. Thus, each edge `e` of `G` has a
corresponding dual edge, the edge that connects the two faces on
either side of `e`.
Computing the dual graph of a graph has many uses, for example when one wishes
to compute the connected components of a mesh.
The class template `Dual` is an adaptor that creates the dual view of
a `FaceGraph`. Faces of the original graph correspond to vertices in
the `Dual` and vice versa.
The dual graph comes in handy when one wants to compute the connected
component of a surface mesh.
Note that border edges in a `Dual` have the `null_face` of the
original graph as either source or target. This is unusual and might
break other algorithms since edges are always assumed to have non-null
vertices as a source and target. It is possible to filter border edges
using `boost::filtered_graph` as shown in the following example.
vertices as a source and target. It is nevertheless possible to filter border edges
using <a href="http://www.boost.org/libs/graph/doc/filtered_graph.html">boost::filtered_graph</a>,
as shown in the following example.
\cgalExample{BGL_surface_mesh/surface_mesh_dual.cpp}
\subsection BGLSeamMesh The Seam Mesh
The class `Seam_mesh` allows to mark edges of a mesh as <em>seam edges</em>
so that they <em>virtually</em> become border edges when exploring a seam mesh with the BGL API.
so that they <em>virtually</em> become border edges when exploring a seam mesh with the \sc{Bgl} API.
The input mesh is referred to as <em>underlying</em> mesh of the seam mesh.
We denote `tm` and `sm` the underlying mesh and the seam mesh respectively.
Figure \cgalFigureRef{fig_Seam_mesh_1} shows an example of mesh on which two
edges, defined by the halfedge pairs `h2-h3` and `h6-h7`, are marked as seams.
The introduction of virtual borders modifies the elementary BGL graph traversal
The introduction of virtual borders modifies the elementary \sc{Bgl} graph traversal
operations: when we circulate around the target of `h7` in the underlying mesh,
we traverse `h7`, `h1`, `h3`, `h5`, before arriving at `h7` again.
However, when we circulate in the seam mesh, we traverse `h7`, `h1`, `h3*`,

6
BGL/doc/BGL/CGAL/Triangulation_vertex_base_with_id_2.h
View File

@ -8,11 +8,11 @@ concept `TriangulationVertexBase_2`, the base vertex of a
2D-triangulation. It provides an integer field that can be used to
index vertices for \sc{Bgl} algorithms.
Note that the user is in charge to set the index correctly before
running a graph algorithm.
Note that the user is in charge of setting indices correctly before
running a graph algorithm.
\tparam TriangulationTraits_2 is the geometric traits class
and must be a model of `TriangulationTraits_2` which provides the `Point_2`.
and must be a model of `TriangulationTraits_2`.
\tparam TriangulationVertexBase_2 must be a vertex base class from which
`Triangulation_vertex_base_with_id_2` derives. It has the default