CGAL 6.2 - CGAL and the Boost Graph Library: Helper Functions

CGAL 6.2 - CGAL and the Boost Graph Library

Loading...
Searching...
No Matches
Functions
Helper Functions
Reference Manual

##

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.

All 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 >
std::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 Graph >
bool | CGAL::is_valid_halfedge_graph (const Graph &g, bool verb=false)
| checks the integrity of the graph `g`.
template<typename FaceGraph >
bool | CGAL::is_valid_face_graph (const FaceGraph &g, bool verb=false)
| checks the integrity of the graph `g`.
template<typename Mesh >
bool | CGAL::is_valid_polygon_mesh (const Mesh &g, bool verb=false)
| checks the integrity of the mesh `g`.
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.
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 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::remove_all_elements (FaceGraph &g)
| removes all vertices, edges, and faces from a graph.
template<typename FaceGraph >
void | CGAL::clear (FaceGraph &g)
| removes all vertices, edges, and faces from a graph.
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.
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)`.
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)`.
template<typename Graph , typename FaceRange , typename HalfedgeOutputIterator , typename NamedParameters = parameters::Default_named_parameters>
HalfedgeOutputIterator | CGAL::border_halfedges (const FaceRange &face_range, const Graph &g, HalfedgeOutputIterator out, const NamedParameters &np=parameters::default_values())
| collects the border halfedges of a surface patch defined as a face range.
template<typename Graph , typename OutputIterator >
OutputIterator | CGAL::extract_boundary_cycles (const Graph &g, OutputIterator out)
| extracts boundary cycles as a list of halfedges, with one halfedge per border.
template<typename SourceMesh , typename TargetMesh , typename NamedParameters1 = parameters::Default_named_parameters, typename NamedParameters2 = parameters::Default_named_parameters>
void | CGAL::copy_face_graph (const SourceMesh &sm, TargetMesh &tm, const NamedParameters1 &np1=parameters::default_values(), const NamedParameters2 &np2=parameters::default_values())
| copies a source model of `FaceListGraph` into a target model of a `FaceListGraph`.

## Function Documentation

## ◆ border_halfedges()

template<typename Graph , typename FaceRange , typename HalfedgeOutputIterator , typename NamedParameters = parameters::Default_named_parameters>

HalfedgeOutputIterator CGAL::border_halfedges | ( | const FaceRange & | face_range,
|  | const Graph & | g,
|  | HalfedgeOutputIterator | out,
|  | const NamedParameters & | np = `parameters::default_values()`
| ) |  |

`#include <CGAL/boost/graph/border.h>`

collects the border halfedges of a surface patch defined as a face range.

For each returned halfedge `h`, `opposite(h, g)` belongs to a face of the patch, but `face(h, g)` does not belong to the patch.

Template Parameters

  Graph | model of `HalfedgeGraph`
  FaceRange | a model of `Range` with value type `boost::graph_traits<Graph>::face_descriptor`
  HalfedgeOutputIterator | model of `OutputIterator` holding `boost::graph_traits<Graph>::halfedge_descriptor` for patch border
  NamedParameters | a sequence of Named Parameters

Parameters

  g | the polygon mesh to which the faces in `face_range` belong
  face_range | the range of faces defining the patch whose border halfedges are collected
  out | the output iterator that collects the border halfedges of the patch, seen from outside
  np | an optional sequence of Named Parameters among the ones listed below

Optional Named Parameters

  a property map associating to each face of `g` a unique index between `0` and `num_faces(g) - 1` Type: a class model of `ReadablePropertyMap` with `boost::graph_traits<Graph>::face_descriptor` as key type and `std::size_t` as value type Default: an automatically indexed internal map |

Returns
  `out`

See also
  `extract_boundary_cycles()`

## ◆ clear()

template<typename FaceGraph >

void CGAL::clear | ( | FaceGraph & | g | ) |

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

removes all vertices, edges, and faces from a graph.

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

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

Warning
  If it exists, the `clear()` function of a graph might do more than simply remove elements. For example, `CGAL::Surface_mesh::clear()` collects garbage and removes all property maps added by a call to `CGAL::Surface_mesh::add_property_map()` for all simplex types.

Template Parameters

  FaceGraph | model of `MutableHalfedgeGraph` and `MutableFaceGraph`

Parameters

  g | the graph to clear

See also
  `CGAL::remove_all_elements()`

## ◆ copy_face_graph()

template<typename SourceMesh , typename TargetMesh , typename NamedParameters1 = parameters::Default_named_parameters, typename NamedParameters2 = parameters::Default_named_parameters>

void CGAL::copy_face_graph | ( | const SourceMesh & | sm,
|  | TargetMesh & | tm,
|  | const NamedParameters1 & | np1 = `parameters::default_values()`,
|  | const NamedParameters2 & | np2 = `parameters::default_values()`
| ) |  |

`#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

  SourceMesh | a model of `FaceListGraph`. The descriptor types `boost::graph_traits<SourceMesh>::vertex_descriptor` and `boost::graph_traits<SourceMesh>::face_descriptor` must be models of `Hashable`.
  TargetMesh | a model of `FaceListGraph`
  NamedParameters1 | a sequence of Named Parameters
  NamedParameters2 | a sequence of Named Parameters

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

Parameters

  sm | the source mesh
  tm | the target mesh
  np1 | an 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

  np2 | an 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.

## ◆ extract_boundary_cycles()

template<typename Graph , typename OutputIterator >

OutputIterator CGAL::extract_boundary_cycles | ( | const Graph & | g,
|  | OutputIterator | out
| ) |  |

`#include <CGAL/boost/graph/border.h>`

extracts boundary cycles as a list of halfedges, with one halfedge per border.

Template Parameters

  Graph | a model of `HalfedgeListGraph`
  OutputIterator | a model of `OutputIterator` holding objects of type `boost::graph_traits<Graph>::halfedge_descriptor`

Parameters

  g | a polygon mesh
  out | an output iterator where the border halfedges will be put

See also
  `border_halfedges()`

## ◆ 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

  Graph | a model of `FaceGraph`.

Parameters

  he | a halfedge of `g` whose index in `face(he, tm)` is sought
  g | an 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

  FaceGraph | model of `FaceGraph`

Parameters

  g | the 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 FaceGraph >

bool CGAL::is_valid_face_graph | ( | const FaceGraph & | g,
|  | bool | verb = `false`
| ) |  |

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

checks the integrity of the graph `g`.

The graph `g` is a valid face graph if it is a valid halfedge graph, and 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`).

Parameters

  g | the graph to test
  verb | if `true`, the details of the check will be written in the standard output

Template Parameters

  FaceGraph | a model of `FaceListGraph` and `HalfedgeListGraph`

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 the graph `g`.

The graph `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

  g | the graph to test
  verb | if `true`, the details of the check will be written in the standard output.

Template Parameters

  Graph | a 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 the mesh `g`.

The mesh `g` is a valid polygon mesh if it is a valid face graph and if it follows the rules defined in PolygonMesh.

Parameters

  g | the `Mesh` to test
  verb | if `true`, the details of the check will be written in the standard output

Template Parameters

  Mesh | a model of `FaceListGraph` and `HalfedgeListGraph`

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.

## ◆ remove_all_elements()

template<typename FaceGraph >

void CGAL::remove_all_elements | ( | FaceGraph & | g | ) |

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

removes all vertices, edges, and faces from a graph.

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

Note that some graphs have a specialized version of this function to improve complexity.

Warning
  This function does not perform anything more than what is advertised above. It is up to the user to e.g. clean garbage or remove internal property maps (if relevant, and desired).

Template Parameters

  FaceGraph | model of `MutableHalfedgeGraph` and `MutableFaceGraph`

Parameters

  g | the graph whose elements will be removed

See also
  `CGAL::clear()`

## ◆ 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

  Graph | a model of `FaceGraph`

Parameters

  vd | a vertex of `g` whose index is sought
  fd | a face of `g` in which the index of `vd` is sought
  g | a mesh of type `Graph`

Precondition
  `vd` is a vertex of `fd`.