CGAL 5.3.2 - CGAL and the Boost Graph Library

Generic convenience functions for testing if an edge is a border edge, if a mesh is triangular, for conversion between models of different FaceGraph concepts, etc.

Most functions are in the header file <CGAL/boost/graph/helpers.h>

Functions

template<typename FaceGraph >
bool CGAL::is_border (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true if the halfedge hd is on a border.
 
template<typename FaceGraph >
bool CGAL::is_border_edge (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true if the halfedge hd or the opposite halfedge is on a border.
 
template<typename FaceGraph >
bool CGAL::is_border (typename boost::graph_traits< FaceGraph >::edge_descriptor ed, const FaceGraph &g)
 returns true if the edge e is on a border.
 
template<typename FaceGraph >
boost::optional< typename boost::graph_traits< FaceGraph >::halfedge_descriptor > CGAL::is_border (typename boost::graph_traits< FaceGraph >::vertex_descriptor vd, const FaceGraph &g)
 returns a halfedge which is on a border and whose target vertex is vd, if such a halfedge exists.
 
template<typename FaceGraph >
bool CGAL::is_closed (const FaceGraph &g)
 returns true if there are no border edges.
 
template<typename FaceGraph >
bool CGAL::is_bivalent (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true if the target of hd has exactly two incident edges.
 
template<typename FaceGraph >
bool CGAL::is_bivalent_mesh (const FaceGraph &g)
 returns true if all vertices have exactly two incident edges.
 
template<typename FaceGraph >
bool CGAL::is_trivalent (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true if the target of hd has exactly three incident edges.
 
template<typename FaceGraph >
bool CGAL::is_trivalent_mesh (const FaceGraph &g)
 returns true if all vertices have exactly three incident edges.
 
template<typename FaceGraph >
bool CGAL::is_isolated_triangle (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true iff the connected component denoted by hd is a triangle. More...
 
template<typename FaceGraph >
bool CGAL::is_triangle (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true iff the face denoted by hd is a triangle, that is it has three incident halfedges.
 
template<typename FaceGraph >
bool CGAL::is_triangle_mesh (const FaceGraph &g)
 returns true if all faces are triangles.
 
template<typename FaceGraph >
bool CGAL::is_isolated_quad (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true iff the connected component denoted by hd is a quadrilateral.
 
template<typename FaceGraph >
bool CGAL::is_quad (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true iff the face denoted by hd is a quad, that is it has four incident halfedges.
 
template<typename FaceGraph >
bool CGAL::is_quad_mesh (const FaceGraph &g)
 returns true if all faces are quadrilaterals.
 
template<typename FaceGraph >
bool CGAL::is_tetrahedron (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true iff the connected component denoted by hd is a tetrahedron.
 
template<typename Graph >
bool CGAL::is_valid_halfedge_graph (const Graph &g, bool verb=false)
 checks the integrity of g. More...
 
template<typename Graph >
bool CGAL::is_valid_face_graph (const Graph &g, bool verb=false)
 checks the integrity of g. More...
 
template<typename Mesh >
bool CGAL::is_valid_polygon_mesh (const Mesh &g, bool verb=false)
 checks the integrity of g. More...
 
template<typename FaceGraph >
bool CGAL::is_hexahedron (typename boost::graph_traits< FaceGraph >::halfedge_descriptor hd, const FaceGraph &g)
 returns true iff the connected component denoted by hd is a hexahedron.
 
template<typename FaceGraph >
void CGAL::clear (FaceGraph &g)
 removes all vertices, faces and halfedges from a graph. More...
 
template<typename FaceGraph >
bool CGAL::is_empty (const FaceGraph &g)
 checks whether the graph is empty, by checking that it does not contain any vertex. More...
 
template<typename Graph >
int CGAL::vertex_index_in_face (const typename boost::graph_traits< Graph >::vertex_descriptor vd, const typename boost::graph_traits< Graph >::face_descriptor fd, const Graph &g)
 returns the number of calls to next() one has to apply to the halfedge hd for source(hd, mesh) == vd to be true, starting from hd = halfedge(fd, tm). More...
 
template<typename Graph >
int CGAL::halfedge_index_in_face (typename boost::graph_traits< Graph >::halfedge_descriptor he, const Graph &g)
 returns the number of calls to next(hd, tm) one has to apply to hd for hd == he to be true, starting from hd = halfedge(face(he, tm), tm). More...
 
template<typename Graph , typename P >
boost::graph_traits< Graph >::halfedge_descriptor CGAL::make_triangle (const P &p0, const P &p1, const P &p2, Graph &g)
 creates an isolated triangle with its vertices initialized to p0, p1 and p2, and adds it to the graph g. More...
 
template<typename Graph , typename P >
boost::graph_traits< Graph >::halfedge_descriptor CGAL::make_quad (const P &p0, const P &p1, const P &p2, const P &p3, Graph &g)
 creates an isolated quad with its vertices initialized to p0, p1, p2, and p3, and adds it to the graph g. More...
 
template<typename Graph , typename P >
boost::graph_traits< Graph >::halfedge_descriptor CGAL::make_hexahedron (const P &p0, const P &p1, const P &p2, const P &p3, const P &p4, const P &p5, const P &p6, const P &p7, Graph &g)
 creates an isolated hexahedron with its vertices initialized to p0, p1, ... , and p7, and adds it to the graph g. More...
 
template<typename Graph , typename P >
boost::graph_traits< Graph >::halfedge_descriptor CGAL::make_tetrahedron (const P &p0, const P &p1, const P &p2, const P &p3, Graph &g)
 creates an isolated tetrahedron with its vertices initialized to p0, p1, p2, and p3, and adds it to the graph g. More...
 
template<class Graph , class P >
boost::graph_traits< Graph >::halfedge_descriptor CGAL::make_regular_prism (typename boost::graph_traits< Graph >::vertices_size_type nb_vertices, Graph &g, const P &base_center=P(0, 0, 0), typename CGAL::Kernel_traits< P >::Kernel::FT height=1.0, typename CGAL::Kernel_traits< P >::Kernel::FT radius=1.0, bool is_closed=true)
 creates a triangulated regular prism, outward oriented, having nb_vertices vertices in each of its bases and adds it to the graph g. More...
 
template<class Graph , class P >
boost::graph_traits< Graph >::halfedge_descriptor CGAL::make_pyramid (typename boost::graph_traits< Graph >::vertices_size_type nb_vertices, Graph &g, const P &base_center=P(0, 0, 0), typename CGAL::Kernel_traits< P >::Kernel::FT height=1.0, typename CGAL::Kernel_traits< P >::Kernel::FT radius=1.0, bool is_closed=true)
 creates a pyramid, outward oriented, having nb_vertices vertices in its base and adds it to the graph g. More...
 
template<class Graph , class P >
boost::graph_traits< Graph >::halfedge_descriptor CGAL::make_icosahedron (Graph &g, const P &center=P(0, 0, 0), typename CGAL::Kernel_traits< P >::Kernel::FT radius=1)
 creates an icosahedron, outward oriented, centered in center and adds it to the graph g. More...
 
template<class Graph , class CoordinateFunctor >
boost::graph_traits< Graph >::halfedge_descriptor CGAL::make_grid (typename boost::graph_traits< Graph >::vertices_size_type i, typename boost::graph_traits< Graph >::vertices_size_type j, Graph &g, const CoordinateFunctor &calculator, bool triangulated=false)
 creates a row major ordered grid with i cells along the width and j cells along the height and adds it to the graph g. More...
 
template<typename SourceMesh , typename TargetMesh , typename NamedParameters1 , typename NamedParameters2 >
void CGAL::copy_face_graph (const SourceMesh &sm, TargetMesh &tm, const NamedParameters1 &np1, const NamedParameters2 &np2)
 copies a source model of FaceListGraph into a target model of a FaceListGraph. More...
 

Function Documentation

◆ clear()

template<typename FaceGraph >
void CGAL::clear ( FaceGraph g)

#include <CGAL/boost/graph/helpers.h>

removes all vertices, faces and halfedges from a graph.

Calls remove_edge(), remove_vertex(), and remove_face() for each edge, vertex or face.

If the graph has a member function clear(), it will be called instead.

Template Parameters
FaceGraphmodel of MutableHalfedgeGraph and MutableFaceGraph
Parameters
gthe graph to clear

◆ copy_face_graph()

template<typename SourceMesh , typename TargetMesh , typename NamedParameters1 , typename NamedParameters2 >
void CGAL::copy_face_graph ( const SourceMesh &  sm,
TargetMesh &  tm,
const NamedParameters1 &  np1,
const NamedParameters2 &  np2 
)

#include <CGAL/boost/graph/copy_face_graph.h>

copies a source model of FaceListGraph into a target model of a FaceListGraph.

OutputIterators can be provided to produce a mapping between source and target elements. The target graph is not cleared.

Template Parameters
SourceMesha model of FaceListGraph. The descriptor types boost::graph_traits<SourceMesh>::vertex_descriptor and boost::graph_traits<SourceMesh>::face_descriptor must be models of Hashable.
TargetMesha model of FaceListGraph
NamedParameters1a sequence of Named Parameters
NamedParameters2a sequence of Named Parameters

The types sm_vertex_descriptor and sm_face_descriptor must be models of the concept Hashable.

Parameters
smthe source mesh
tmthe target mesh
np1an optional sequence of Named Parameters among the ones listed below
Optional Named Parameters
  • a property map associating points to the vertices of sm
  • Type: a class model of ReadWritePropertyMap with boost::graph_traits<SourceMesh>::vertex_descriptor as key type and Point_3 as value type
  • Default: boost::get(CGAL::vertex_point, sm)
  • Extra: If this parameter is omitted, an internal property map for CGAL::vertex_point_t must be available in SourceMesh.

  • an OutputIterator containing the pairs source-vertex, target-vertex.
  • Type: a class model of OutputIterator accepting std::pair<boost::graph_traits<SourceMesh>::vertex_descriptor, boost::graph_traits<TargetMesh>::vertex_descriptor>
  • Default: Emptyset_iterator
  • Extra: If this parameter is given, then vertex_to_vertex_map cannot be used.

  • an OutputIterator containing the pairs source-halfedge, target-halfedge.
  • Type: a class model of OutputIterator accepting std::pair<boost::graph_traits<SourceMesh>::halfedge_descriptor, boost::graph_traits<TargetMesh>::halfedge_descriptor>
  • Default: Emptyset_iterator
  • Extra: If this parameter is given, then halfedge_to_halfedge_map cannot be used.

  • an OutputIterator containing the pairs source-face, target-face.
  • Type: a class model of OutputIterator accepting std::pair<boost::graph_traits<SourceMesh>::face_descriptor, boost::graph_traits<TargetMesh>::face_descriptor>
  • Default: Emptyset_iterator
  • Extra: If this parameter is given, then face_to_face_map cannot be used.

  • a property map storing for each vertex of a source mesh the corresponding vertex of another mesh
  • Type: a class model of ReadWritePropertyMap with boost::graph_traits<SourceMesh>::vertex_descriptor as key type and boost::graph_traits<TargetMesh>::vertex_descriptor as value type.
  • Default: unused
  • Extra: A typical use case is mapping the vertices from a source mesh to its copy's after a copy_face_graph() operation.

  • a property map storing for each halfedge of a source mesh the corresponding halfedge of another mesh
  • Type: a class model of ReadWritePropertyMap with boost::graph_traits<SourceMesh>::halfedge_descriptor as key type and boost::graph_traits<TargetMesh>::halfedge_descriptor as value type
  • Default: unused
  • Extra: A typical use case is mapping the halfedges from a source mesh to its copy's after a copy_face_graph()operation.

  • a property map storing for each face of a source mesh the corresponding face of another mesh
  • Type: a class model of ReadWritePropertyMap with boost::graph_traits<SourceMesh>::face_descriptor as key type and boost::graph_traits<TargetMesh>::face_descriptor as value type
  • Default: unused
  • Extra: A typical use case is mapping the faces from a source mesh to its copy's after a copy_face_graph() operation
Parameters
np2an optional sequence of Named Parameters among the ones listed below
Optional Named Parameters
  • a property map associating points to the vertices of tm
  • Type: a class model of ReadWritePropertyMap with boost::graph_traits<TargetMesh>::vertex_descriptor as key type and Point_3 as value type
  • Default: boost::get(CGAL::vertex_point, tm)
  • Extra: If this parameter is omitted, an internal property map for CGAL::vertex_point_t must be available in TargetMesh.

The points from sm to tm are converted using CGAL::Cartesian_converter<SourceKernel, TargetKernel>. SourceKernel and TargetKernel are deduced using CGAL::Kernel_traits from the value types of the vertex point maps.

Other properties are not copied.

Examples:
BGL_polyhedron_3/copy_polyhedron.cpp, BGL_surface_mesh/surface_mesh_partition.cpp, and Surface_mesh_segmentation/extract_segmentation_into_mesh_example.cpp.

◆ halfedge_index_in_face()

template<typename Graph >
int CGAL::halfedge_index_in_face ( typename boost::graph_traits< Graph >::halfedge_descriptor  he,
const Graph &  g 
)

#include <CGAL/boost/graph/helpers.h>

returns the number of calls to next(hd, tm) one has to apply to hd for hd == he to be true, starting from hd = halfedge(face(he, tm), tm).

Template Parameters
Grapha model of FaceGraph.
Parameters
hea halfedge of g whose index in face(he, tm) is sought
gan object of type Graph

◆ is_empty()

template<typename FaceGraph >
bool CGAL::is_empty ( const FaceGraph g)

#include <CGAL/boost/graph/helpers.h>

checks whether the graph is empty, by checking that it does not contain any vertex.

Template Parameters
FaceGraphmodel of FaceGraph
Parameters
gthe graph to test

◆ is_isolated_triangle()

template<typename FaceGraph >
bool CGAL::is_isolated_triangle ( typename boost::graph_traits< FaceGraph >::halfedge_descriptor  hd,
const FaceGraph g 
)

#include <CGAL/boost/graph/helpers.h>

returns true iff the connected component denoted by hd is a triangle.

Precondition
g must be valid.

◆ is_valid_face_graph()

template<typename Graph >
bool CGAL::is_valid_face_graph ( const Graph &  g,
bool  verb = false 
)

#include <CGAL/boost/graph/helpers.h>

checks the integrity of g.

g is valid if it is a valid HalfedgeListGraph, if it follows the rules of the FaceListGraph concept, and all of its associations are reciprocal. For example, face(halfedge(f,g),g) must be f. calls is_valid_halfedge_graph()

Parameters
gthe Graph to test.
verbif true, the details of the check will be written in the standard output.
Template Parameters
Grapha model of FaceListGraph
Returns
true if g is valid, false otherwise.
See also
is_valid_halfedge_graph()

◆ is_valid_halfedge_graph()

template<typename Graph >
bool CGAL::is_valid_halfedge_graph ( const Graph &  g,
bool  verb = false 
)

#include <CGAL/boost/graph/helpers.h>

checks the integrity of g.

g is valid if it follows the rules of the HalfedgeListGraph concept, and all of its associations are reciprocal. For example, prev(next(h, g), g) must be h, and next(prev(h, g), g) must be h.

Parameters
gthe Graph to test.
verbif true, the details of the check will be written in the standard output.
Template Parameters
Grapha model of HalfedgeListGraph
Returns
true if g is valid, false otherwise.

◆ is_valid_polygon_mesh()

template<typename Mesh >
bool CGAL::is_valid_polygon_mesh ( const Mesh &  g,
bool  verb = false 
)

#include <CGAL/boost/graph/helpers.h>

checks the integrity of g.

g is valid if it is a valid FaceListGraph and it has distinct faces on each side of an edge. calls is_valid_face_graph().

Parameters
gthe Mesh to test.
verb: if true, the details of the check will be written in the standard output.
Template Parameters
Mesha model of FaceListGraph and HalfedgeListGraph, and follows the definition of a PolygonMesh
Returns
true if g is valid, false otherwise.
See also
is_valid_face_graph()
is_valid_halfedge_graph()
Examples:
BGL_polyhedron_3/copy_polyhedron.cpp.

◆ make_grid()

template<class Graph , class CoordinateFunctor >
boost::graph_traits<Graph>::halfedge_descriptor CGAL::make_grid ( typename boost::graph_traits< Graph >::vertices_size_type  i,
typename boost::graph_traits< Graph >::vertices_size_type  j,
Graph &  g,
const CoordinateFunctor &  calculator,
bool  triangulated = false 
)

#include <CGAL/boost/graph/generators.h>

creates a row major ordered grid with i cells along the width and j cells along the height and adds it to the graph g.

An internal property map for CGAL::vertex_point_t must be available in Graph.

Parameters
ithe number of cells along the width.
jthe number of cells along the height.
gthe graph in which the grid will be created.
calculatorthe functor that will assign coordinates to the grid vertices.
triangulateddecides if a cell is composed of one quad or two triangles. If triangulated is true, the diagonal of each cell is oriented from (0,0) to (1,1) in the cell coordinates.
Template Parameters
CoordinateFunctora function object providing: Point_3 operator()(size_type I, size_type J), with Point_3 being the value_type of the internal property_map for CGAL::vertex_point_t and outputs an object of type boost::property_traits<boost::property_map<Graph,CGAL::vertex_point_t>::type>::value_type. It will be called with arguments (w, h), with w in [0..i] and h in [0..j].
Default: a point with positive integer coordinates (w, h, 0), with w in [0..i] and h in [0..j]
Returns
the non-border non-diagonal halfedge that has the target vertex associated with the first point of the grid (default is (0,0,0) ).

◆ make_hexahedron()

template<typename Graph , typename P >
boost::graph_traits<Graph>::halfedge_descriptor CGAL::make_hexahedron ( const P &  p0,
const P &  p1,
const P &  p2,
const P &  p3,
const P &  p4,
const P &  p5,
const P &  p6,
const P &  p7,
Graph &  g 
)

#include <CGAL/boost/graph/generators.h>

creates an isolated hexahedron with its vertices initialized to p0, p1, ... , and p7, and adds it to the graph g.

hexahedron.png
Returns
the halfedge that has the target vertex associated with p0, in the face with the vertices with the points p0, p1, p2, and p3.
Examples:
BGL_surface_mesh/gwdwg.cpp.

◆ make_icosahedron()

template<class Graph , class P >
boost::graph_traits<Graph>::halfedge_descriptor CGAL::make_icosahedron ( Graph &  g,
const P &  center = P(0,0,0),
typename CGAL::Kernel_traits< P >::Kernel::FT  radius = 1 
)

#include <CGAL/boost/graph/generators.h>

creates an icosahedron, outward oriented, centered in center and adds it to the graph g.

Parameters
gthe graph in which the icosahedron will be created.
centerthe center of the sphere in which the icosahedron is inscribed.
radiusthe radius of the sphere in which the icosahedron is inscribed.
Returns
the halfedge that has the target vertex associated with the first point in the first face.

◆ make_pyramid()

template<class Graph , class P >
boost::graph_traits<Graph>::halfedge_descriptor CGAL::make_pyramid ( typename boost::graph_traits< Graph >::vertices_size_type  nb_vertices,
Graph &  g,
const P &  base_center = P(0,0,0),
typename CGAL::Kernel_traits< P >::Kernel::FT  height = 1.0,
typename CGAL::Kernel_traits< P >::Kernel::FT  radius = 1.0,
bool  is_closed = true 
)

#include <CGAL/boost/graph/generators.h>

creates a pyramid, outward oriented, having nb_vertices vertices in its base and adds it to the graph g.

If center is (0, 0, 0), then the first point of the base is (radius, 0, 0)

Parameters
nb_verticesthe number of vertices in the base. It must be greater than or equal to 3.
gthe graph in which the pyramid will be created
base_centerthe center of the circle in which the base is inscribed.
heightthe distance between the base and the apex.
radiusthe radius of the circle in which the base is inscribed.
is_closeddetermines if the base must be created or not. If is_closed is true, center is a vertex.
Returns
the halfedge that has the target vertex associated with the apex point in the first face.

◆ make_quad()

template<typename Graph , typename P >
boost::graph_traits<Graph>::halfedge_descriptor CGAL::make_quad ( const P &  p0,
const P &  p1,
const P &  p2,
const P &  p3,
Graph &  g 
)

#include <CGAL/boost/graph/generators.h>

creates an isolated quad with its vertices initialized to p0, p1, p2, and p3, and adds it to the graph g.

Returns
the non-border halfedge that has the target vertex associated with p0.
Examples:
BGL_surface_mesh/write_inp.cpp.

◆ make_regular_prism()

template<class Graph , class P >
boost::graph_traits<Graph>::halfedge_descriptor CGAL::make_regular_prism ( typename boost::graph_traits< Graph >::vertices_size_type  nb_vertices,
Graph &  g,
const P &  base_center = P(0,0,0),
typename CGAL::Kernel_traits< P >::Kernel::FT  height = 1.0,
typename CGAL::Kernel_traits< P >::Kernel::FT  radius = 1.0,
bool  is_closed = true 
)

#include <CGAL/boost/graph/generators.h>

creates a triangulated regular prism, outward oriented, having nb_vertices vertices in each of its bases and adds it to the graph g.

If center is (0, 0, 0), then the first point of the prism is (radius, height, 0)

Parameters
nb_verticesthe number of vertices per base. It must be greater than or equal to 3.
gthe graph in which the regular prism will be created.
base_centerthe center of the circle in which the lower base is inscribed.
heightthe distance between the two bases.
radiusthe radius of the circles in which the bases are inscribed.
is_closeddetermines if the bases must be created or not. If is_closed is true, center is a vertex.
Returns
the halfedge that has the target vertex associated with the first point in the first face.

◆ make_tetrahedron()

template<typename Graph , typename P >
boost::graph_traits<Graph>::halfedge_descriptor CGAL::make_tetrahedron ( const P &  p0,
const P &  p1,
const P &  p2,
const P &  p3,
Graph &  g 
)

#include <CGAL/boost/graph/generators.h>

creates an isolated tetrahedron with its vertices initialized to p0, p1, p2, and p3, and adds it to the graph g.

tetrahedron.png
Returns
the halfedge that has the target vertex associated with p0, in the face with the vertices with the points p0, p1, and p2.

◆ make_triangle()

template<typename Graph , typename P >
boost::graph_traits<Graph>::halfedge_descriptor CGAL::make_triangle ( const P &  p0,
const P &  p1,
const P &  p2,
Graph &  g 
)

#include <CGAL/boost/graph/generators.h>

creates an isolated triangle with its vertices initialized to p0, p1 and p2, and adds it to the graph g.

Returns
the non-border halfedge that has the target vertex associated with p0.
Examples:
Polyhedron/poly_derivation.cpp, Property_map/dynamic_properties.cpp, and Surface_mesh/sm_derivation.cpp.

◆ vertex_index_in_face()

template<typename Graph >
int CGAL::vertex_index_in_face ( const typename boost::graph_traits< Graph >::vertex_descriptor  vd,
const typename boost::graph_traits< Graph >::face_descriptor  fd,
const Graph &  g 
)

#include <CGAL/boost/graph/helpers.h>

returns the number of calls to next() one has to apply to the halfedge hd for source(hd, mesh) == vd to be true, starting from hd = halfedge(fd, tm).

Template Parameters
Grapha model of FaceGraph
Parameters
vda vertex of g whose index is sought
fda face of g in which the index of vd is sought
ga mesh of type Graph
Precondition
vd is a vertex of fd.