Connected Components

Two faces are in the same connected component if there is a path of adjacent faces such that all edges between two consecutive faces of the path are not marked as constrained.

Functions
template<typename PolygonMesh , typename FaceOutputIterator , typename NamedParameters >
FaceOutputIterator	CGAL::Polygon_mesh_processing::connected_component (typename boost::graph_traits< PolygonMesh >::face_descriptor seed_face, const PolygonMesh &pmesh, FaceOutputIterator out, const NamedParameters &np)
template<typename PolygonMesh , typename FaceComponentMap , typename NamedParameters >
boost::property_traits< FaceComponentMap >::value_type	CGAL::Polygon_mesh_processing::connected_components (const PolygonMesh &pmesh, FaceComponentMap fcm, const NamedParameters &np)
template<typename PolygonMesh , typename NamedParameters >
std::size_t	CGAL::Polygon_mesh_processing::keep_largest_connected_components (PolygonMesh &pmesh, std::size_t nb_components_to_keep, const NamedParameters &np)
template<typename PolygonMesh , typename ThresholdValueType , typename NamedParameters >
std::size_t	CGAL::Polygon_mesh_processing::keep_large_connected_components (PolygonMesh &pmesh, const ThresholdValueType threshold_value, const NamedParameters &np)
template<typename PolygonMesh , typename ComponentRange , typename FaceComponentMap , typename NamedParameters >
void	CGAL::Polygon_mesh_processing::keep_connected_components (PolygonMesh &pmesh, const ComponentRange &components_to_keep, const FaceComponentMap &fcm, const NamedParameters &np)
template<typename PolygonMesh , typename ComponentRange , typename FaceComponentMap , typename NamedParameters >
void	CGAL::Polygon_mesh_processing::remove_connected_components (PolygonMesh &pmesh, const ComponentRange &components_to_remove, const FaceComponentMap &fcm, const NamedParameters &np)
template<typename PolygonMesh , typename FaceRange , typename NamedParameters >
void	CGAL::Polygon_mesh_processing::remove_connected_components (PolygonMesh &pmesh, const FaceRange &components_to_remove, const NamedParameters &np)
template<typename PolygonMesh , typename FaceRange , typename NamedParameters >
void	CGAL::Polygon_mesh_processing::keep_connected_components (PolygonMesh &pmesh, const FaceRange &components_to_keep, const NamedParameters &np)
template<class PolygonMesh , class PolygonMeshRange , class NamedParameters >
void	CGAL::Polygon_mesh_processing::split_connected_components (const PolygonMesh &pm, PolygonMeshRange &cc_meshes, const NamedParameters &np)

Function Documentation

connected_component()

template<typename PolygonMesh , typename FaceOutputIterator , typename NamedParameters >

FaceOutputIterator CGAL::Polygon_mesh_processing::connected_component	(	typename boost::graph_traits< PolygonMesh >::face_descriptor	seed_face,
		const PolygonMesh &	pmesh,
		FaceOutputIterator	out,
		const NamedParameters &	np
	)

#include <CGAL/Polygon_mesh_processing/connected_components.h>

discovers all the faces in the same connected component as seed_face and records them in out. seed_face will also be added in out.

Template Parameters

PolygonMesh	a model of FaceGraph
FaceOutputIterator	a model of OutputIterator that accepts faces of type boost::graph_traits<PolygonMesh>::face_descriptor.
NamedParameters	a sequence of Named Parameters

Parameters

seed_face	a face of pmesh from which exploration starts to detect the connected component that contains it
pmesh	the polygon mesh
out	the output iterator that collects faces from the same connected component as seed_face
np	optional Named Parameters described below

Named Parameters

edge_is_constrained_map

a property map containing the constrained-or-not status of each edge of pmesh

Returns

the output iterator.

Examples

Polygon_mesh_processing/connected_components_example.cpp.

connected_components()

template<typename PolygonMesh , typename FaceComponentMap , typename NamedParameters >

boost::property_traits<FaceComponentMap>::value_type CGAL::Polygon_mesh_processing::connected_components	(	const PolygonMesh &	pmesh,
		FaceComponentMap	fcm,
		const NamedParameters &	np
	)

#include <CGAL/Polygon_mesh_processing/connected_components.h>

computes for each face the index of the corresponding connected component.

Template Parameters

PolygonMesh	a model of FaceListGraph
FaceComponentMap	a model of WritablePropertyMap with boost::graph_traits<PolygonMesh>::face_descriptor as key type and boost::graph_traits<PolygonMesh>::faces_size_type as value type.
NamedParameters	a sequence of Named Parameters

Parameters

pmesh	the polygon mesh
fcm	the property map with indices of components associated to faces in pmesh
np	optional Named Parameters described below

Named Parameters

edge_is_constrained_map	a property map containing the constrained-or-not status of each edge of pmesh
face_index_map	a property map containing the index of each face of pmesh

Returns

the number of connected components.

Examples

Polygon_mesh_processing/connected_components_example.cpp, Polygon_mesh_processing/face_filtered_graph_example.cpp, and Polygon_mesh_processing/orientation_pipeline_example.cpp.

keep_connected_components() [1/2]

template<typename PolygonMesh , typename ComponentRange , typename FaceComponentMap , typename NamedParameters >

void CGAL::Polygon_mesh_processing::keep_connected_components	(	PolygonMesh &	pmesh,
		const ComponentRange &	components_to_keep,
		const FaceComponentMap &	fcm,
		const NamedParameters &	np
	)

#include <CGAL/Polygon_mesh_processing/connected_components.h>

keeps the connected components designated by theirs ids in components_to_keep, and removes the other connected components as well as all isolated vertices. The connected component id of a face is given by fcm.

Note

If the removal of the connected components makes pmesh a non-manifold surface, then the behavior of this function is undefined.

Template Parameters

PolygonMesh	a model of FaceListGraph and MutableFaceGraph
NamedParameters	a sequence of Named Parameters
ComponentRange	a range of ids convertible to std::size
FaceComponentMap	a model of ReadWritePropertyMap with boost::graph_traits<PolygonMesh>::face_descriptor as key type and boost::graph_traits<PolygonMesh>::faces_size_type as value type.

Parameters

components_to_keep	the range of ids of connected components to keep
pmesh	the polygon mesh
fcm	the property map with indices of components associated to faces in pmesh. After calling this function, the values of fcm are undefined.
np	optional Named Parameters described below

Named Parameters

vertex_index_map

a property map containing the index of each vertex of pmesh

keep_connected_components() [2/2]

template<typename PolygonMesh , typename FaceRange , typename NamedParameters >

void CGAL::Polygon_mesh_processing::keep_connected_components	(	PolygonMesh &	pmesh,
		const FaceRange &	components_to_keep,
		const NamedParameters &	np
	)

#include <CGAL/Polygon_mesh_processing/connected_components.h>

keeps the connected components designated by the faces in components_to_keep, and removes the other connected components and all isolated vertices.

Note

If the removal of the connected components makes pmesh a non-manifold surface, then the behavior of this function is undefined.

Template Parameters

PolygonMesh	a model of FaceListGraph and MutableFaceGraph
NamedParameters	a sequence of Named Parameters
FaceRange	a range of boost::graph_traits<PolygonMesh>::face_descriptor indicating the connected components to be kept.

Parameters

pmesh	the polygon mesh
components_to_keep	a face range, including one face or more on each component to be kept
np	optional Named Parameters, amongst those described below

Named Parameters

edge_is_constrained_map	a property map containing the constrained-or-not status of each edge of pmesh
face_index_map	a property map containing the index of each face of pmesh
vertex_index_map	a property map containing the index of each vertex of pmesh

keep_large_connected_components()

template<typename PolygonMesh , typename ThresholdValueType , typename NamedParameters >

std::size_t CGAL::Polygon_mesh_processing::keep_large_connected_components	(	PolygonMesh &	pmesh,
		const ThresholdValueType	threshold_value,
		const NamedParameters &	np
	)

#include <CGAL/Polygon_mesh_processing/connected_components.h>

removes connected components whose size is (strictly) smaller than a given threshold value, where the size of a connected component is computed as the sum of the individual sizes of all the faces of the connected component. By default, the size of a face is 1 (and thus the size of a connected component is the number of faces it contains), but it is also possible to pass custom sizes, such as the area of the face.

Template Parameters

PolygonMesh	a model of FaceListGraph and MutableFaceGraph
ThresholdValueType	the type of the threshold value
NamedParameters	a sequence of Named Parameters

Parameters

pmesh	the polygon mesh
threshold_value	any connected component with a size (strictly) smaller than this value will be discarded
np	optional Named Parameters, amongst those described below

Named Parameters

edge_is_constrained_map	a property map containing the constrained-or-not status of each edge of pmesh
face_index_map	a property map containing the index of each face of pmesh
vertex_index_map	a property map containing the index of each vertex of pmesh
face_size_map	a property map containing a size for each face of pmesh. The value type of this property map is chosen by the user, but must be constructible from 0 and support operator+=() and comparisons.
dry_run	a Boolean parameter. If set to true, the mesh will not be altered, but the number of components that would be removed is returned. The default value is false.
output_iterator	a model of OutputIterator with value type face_descriptor. When using the "dry run" mode (see parameter dry_run), faces that would be removed by the algorithm can be collected with this output iterator.

Precondition

If a face size property map is passed by the user, ThresholdValueType must be the same type as the value type of the property map. Otherwise, ThresholdValueType must be std::size_t.

Returns

the number of connected components removed (ignoring isolated vertices).

Examples

Polygon_mesh_processing/connected_components_example.cpp.

keep_largest_connected_components()

template<typename PolygonMesh , typename NamedParameters >

std::size_t CGAL::Polygon_mesh_processing::keep_largest_connected_components	(	PolygonMesh &	pmesh,
		std::size_t	nb_components_to_keep,
		const NamedParameters &	np
	)

#include <CGAL/Polygon_mesh_processing/connected_components.h>

removes the small connected components and all isolated vertices. Keep the nb_components_to_keep largest connected components, where the size of a connected component is computed as the sum of the individual sizes of all the faces of the connected component. By default, the size of a face is 1 (and thus the size of a connected component is the number of faces it contains), but it is also possible to pass custom sizes, such as the area of the face.

Template Parameters

PolygonMesh	a model of FaceListGraph and MutableFaceGraph
NamedParameters	a sequence of Named Parameters

Parameters

pmesh	the polygon mesh
nb_components_to_keep	the number of components to be kept. If this number is larger than the number of components in the mesh, all components are kept.
np	optional Named Parameters, amongst those described below

Named Parameters

edge_is_constrained_map	a property map containing the constrained-or-not status of each edge of pmesh
face_index_map	a property map containing the index of each face of pmesh
vertex_index_map	a property map containing the index of each vertex of pmesh
face_size_map	a property map containing a size for each face of pmesh. The value type of this property map is chosen by the user, but must be constructible from 0 and support operator+=() and comparisons.
dry_run	a Boolean parameter. If set to true, the mesh will not be altered, but the number of components that would be removed is returned. The default value is false.
output_iterator	a model of OutputIterator with value type face_descriptor. When using the "dry run" mode (see parameter dry_run), faces that would be removed by the algorithm can be collected with this output iterator.

Returns

the number of connected components removed (ignoring isolated vertices).

Examples

Polygon_mesh_processing/connected_components_example.cpp.

remove_connected_components() [1/2]

template<typename PolygonMesh , typename ComponentRange , typename FaceComponentMap , typename NamedParameters >

void CGAL::Polygon_mesh_processing::remove_connected_components	(	PolygonMesh &	pmesh,
		const ComponentRange &	components_to_remove,
		const FaceComponentMap &	fcm,
		const NamedParameters &	np
	)

#include <CGAL/Polygon_mesh_processing/connected_components.h>

Removes in pmesh the connected components designated by theirs ids in components_to_remove as well as all isolated vertices. The connected component id of a face is given by fcm.

Note

If the removal of the connected components makes pmesh a non-manifold surface, then the behavior of this function is undefined.

Template Parameters

PolygonMesh	a model of FaceListGraph and MutableFaceGraph
NamedParameters	a sequence of Named Parameters
ComponentRange	a range of ids convertible to std::size
FaceComponentMap	a model of ReadWritePropertyMap with boost::graph_traits<PolygonMesh>::face_descriptor as key type and boost::graph_traits<PolygonMesh>::faces_size_type as value type.

Parameters

components_to_remove	the range of ids of connected components to remove
pmesh	the polygon mesh
fcm	the property map with indices of components associated to faces in pmesh. After calling this function, the values of fcm are undefined.
np	optional Named Parameters described below

Named Parameters

vertex_index_map

a property map containing the index of each vertex of pmesh

remove_connected_components() [2/2]

template<typename PolygonMesh , typename FaceRange , typename NamedParameters >

void CGAL::Polygon_mesh_processing::remove_connected_components	(	PolygonMesh &	pmesh,
		const FaceRange &	components_to_remove,
		const NamedParameters &	np
	)

#include <CGAL/Polygon_mesh_processing/connected_components.h>

keeps the connected components not designated by the faces in components_to_remove, and removes the other connected components and all isolated vertices.

Note

If the removal of the connected components makes pmesh a non-manifold surface, then the behavior of this function is undefined.

Template Parameters

PolygonMesh	a model of FaceListGraph and MutableFaceGraph
NamedParameters	a sequence of Named Parameters
FaceRange	a range of boost::graph_traits<PolygonMesh>::face_descriptor indicating the connected components to be removed.

Parameters

components_to_remove	a face range, including one face or more on each component to be removed
pmesh	the polygon mesh
np	optional Named Parameters, amongst those described below

Named Parameters

edge_is_constrained_map	a property map containing the constrained-or-not status of each edge of pmesh
face_index_map	a property map containing the index of each face of pmesh
vertex_index_map	a property map containing the index of each vertex of pmesh

split_connected_components()

template<class PolygonMesh , class PolygonMeshRange , class NamedParameters >

void CGAL::Polygon_mesh_processing::split_connected_components	(	const PolygonMesh &	pm,
		PolygonMeshRange &	cc_meshes,
		const NamedParameters &	np
	)

#include <CGAL/Polygon_mesh_processing/connected_components.h>

identifies the connected components of pm and pushes back a new PolygonMesh for each connected component in cc_meshes.

Template Parameters

PolygonMesh	a model of FaceListGraph
PolygonMeshRange	a model of SequenceContainer with PolygonMesh as value type.
NamedParameters	a sequence of Named Parameters

Parameters

pm	the polygon mesh
cc_meshes	container that is filled with the extracted connected components.
np	an optional sequence of Named Parameters among the ones listed below

Named Parameters

edge_is_constrained_map	a property map containing the constrained-or-not status of each edge of pm
face_index_map	a property map containing a unique index for each face initialized from 0 to num_faces(pm)
vertex_index_map	a property map containing a unique index for each vertex initialized 0 to num_vertices(pm)
halfedge_index_map	a property map containing a unique index for each halfedge initialized 0 to num_halfedges(pm)
face_patch_map	a property map with the patch id's associated to the faces of pm. Instance of a class model of ReadPropertyMap. If not provided, an internal map will be filled with a call to connected_components() with edge_is_constrained_map() (if provided).