Reference Manual

Ilker O. Yaz and Sébastien Loriot

This package provides a method to generate a segmentation of a triangulated surface mesh. The algorithm first computes the Shape Diameter Function (SDF) for all facets and applies a graph-cut based algorithm over these values. Low level functions are provided to replace any intermediate step by a custom one.

Introduced in: CGAL 4.4
Depends on: 2D and 3D Fast Intersection and Distance Computation
BibTeX: cgal:y-smsimpl-25b
License: GPL
Windows Demo: CGAL Lab

Classified Reference Pages

Concepts

• #SegmentationGeomTraits

Main Functions

• #CGAL::sdf_values()
• #CGAL::sdf_values_postprocessing()
• #CGAL::segmentation_from_sdf_values()
• #CGAL::segmentation_via_sdf_values()

Modules
	Concepts

Functions
template<class TriangleMesh , class SDFPropertyMap , class PointPropertyMap = typename boost::property_map<TriangleMesh, boost::vertex_point_t>::type, class GeomTraits = typename Kernel_traits<typename boost::property_traits<PointPropertyMap>::value_type>::Kernel>
std::pair< double, double >	CGAL::sdf_values (const TriangleMesh &triangle_mesh, SDFPropertyMap sdf_values_map, double cone_angle=2.0/3.0 *CGAL_PI, std::size_t number_of_rays=25, bool postprocess=true, PointPropertyMap ppmap=PointPropertyMap(), GeomTraits traits=GeomTraits())
	Function computing the Shape Diameter Function over a surface mesh.
template<class TriangleMesh , class SDFPropertyMap >
std::pair< double, double >	CGAL::sdf_values_postprocessing (const TriangleMesh &triangle_mesh, SDFPropertyMap sdf_values_map)
	Function postprocessing raw SDF values computed per facet.
template<class TriangleMesh , class SDFPropertyMap , class SegmentPropertyMap , class PointPropertyMap = typename boost::property_map<TriangleMesh, boost::vertex_point_t>::type, class GeomTraits = typename Kernel_traits<typename boost::property_traits<PointPropertyMap>::value_type>::Kernel>
std::size_t	CGAL::segmentation_from_sdf_values (const TriangleMesh &triangle_mesh, SDFPropertyMap sdf_values_map, SegmentPropertyMap segment_ids, std::size_t number_of_clusters=5, double smoothing_lambda=0.26, bool output_cluster_ids=false, PointPropertyMap ppmap=PointPropertyMap(), GeomTraits traits=GeomTraits())
	Function computing the segmentation of a surface mesh given an SDF value per facet.
template<class TriangleMesh , class SegmentPropertyMap , class PointPropertyMap = typename boost::property_map<TriangleMesh, boost::vertex_point_t>::type, class GeomTraits = typename Kernel_traits<typename boost::property_traits<PointPropertyMap>::value_type>::Kernel>
std::size_t	CGAL::segmentation_via_sdf_values (const TriangleMesh &triangle_mesh, SegmentPropertyMap segment_ids, double cone_angle=2.0/3.0 *CGAL_PI, std::size_t number_of_rays=25, std::size_t number_of_clusters=5, double smoothing_lambda=0.26, bool output_cluster_ids=false, PointPropertyMap ppmap=PointPropertyMap(), GeomTraits traits=GeomTraits())
	Function computing the segmentation of a surface mesh.

Function Documentation

sdf_values()

template<class TriangleMesh , class SDFPropertyMap , class PointPropertyMap = typename boost::property_map<TriangleMesh, boost::vertex_point_t>::type, class GeomTraits = typename Kernel_traits<typename boost::property_traits<PointPropertyMap>::value_type>::Kernel>

std::pair< double, double > CGAL::sdf_values	(	const TriangleMesh &	triangle_mesh,
		SDFPropertyMap	sdf_values_map,
		double	cone_angle = 2.0 / 3.0 * CGAL_PI,
		std::size_t	number_of_rays = 25,
		bool	postprocess = true,
		PointPropertyMap	ppmap = PointPropertyMap(),
		GeomTraits	traits = GeomTraits()
	)

#include <CGAL/mesh_segmentation.h>

Function computing the Shape Diameter Function over a surface mesh.

This function implements the Shape Diameter Function (SDF) as described in [4]. It is possible to compute raw SDF values (without postprocessing). In such a case, -1 is used to indicate when no SDF value could be computed for a facet.

Precondition

is_triangle_mesh(triangle_mesh)

Template Parameters

TriangleMesh	a model of FaceListGraph
SDFPropertyMap	a ReadWritePropertyMap with boost::graph_traits<TriangleMesh>::face_descriptor as key and double as value type
GeomTraits	a model of SegmentationGeomTraits
PointPropertyMap	a ReadablePropertyMap with boost::graph_traits<TriangleMesh>::vertex_descriptor as key and GeomTraits::Point_3 as value type.

Parameters

	triangle_mesh	surface mesh on which SDF values are computed
[out]	sdf_values_map	the SDF value of each facet
	cone_angle	opening angle in radians for the cone of each facet
	number_of_rays	number of rays picked in the cone of each facet. In our experiments, we observe that increasing the number of rays beyond the default has little effect on the quality of the segmentation result
	postprocess	if true, CGAL::sdf_values_postprocessing() is called on raw SDF value computed.
	traits	traits class
	ppmap	point property map. An overload is provided with get(boost::vertex_point,triangle_mesh) as default.

Returns

minimum and maximum raw SDF values if postprocess is true, otherwise minimum and maximum SDF values (before linear normalization)

Examples

Surface_mesh_segmentation/extract_segmentation_into_mesh_example.cpp, Surface_mesh_segmentation/sdf_values_example.cpp, Surface_mesh_segmentation/segmentation_from_sdf_values_SM_example.cpp, Surface_mesh_segmentation/segmentation_from_sdf_values_example.cpp, and Surface_mesh_segmentation/segmentation_with_facet_ids_example.cpp.

sdf_values_postprocessing()

template<class TriangleMesh , class SDFPropertyMap >

std::pair< double, double > CGAL::sdf_values_postprocessing	(	const TriangleMesh &	triangle_mesh,
		SDFPropertyMap	sdf_values_map
	)

#include <CGAL/mesh_segmentation.h>

Function postprocessing raw SDF values computed per facet.

Postprocessing steps applied :

• Facets with -1 SDF values are assigned the average SDF value of their edge-adjacent neighbors. If there is still a facet having -1 SDF value, the minimum valid SDF value assigned to it. Note that this step is not inherited from the paper. The main reason for not assigning 0 to facets with no SDF values (i.e., -1) is that it can obstruct log-normalization process which takes place at the beginning of CGAL::segmentation_from_sdf_values().
• SDF values are smoothed with bilateral filtering.
• SDF values are linearly normalized between [0,1].

See the section Postprocessing of Raw SDF Values for more details.

Precondition

is_triangle_mesh(triangle_mesh)

Raw values should be greater or equal to 0. -1 indicates when no value could be computed

Template Parameters

TriangleMesh	a model of FaceListGraph
SDFPropertyMap	a ReadWritePropertyMap with boost::graph_traits<TriangleMesh>::face_descriptor as key and double as value type

Parameters

	triangle_mesh	surface mesh on which SDF values are computed
[in,out]	sdf_values_map	the SDF value of each facet

Returns

minimum and maximum SDF values before linear normalization

segmentation_from_sdf_values()

template<class TriangleMesh , class SDFPropertyMap , class SegmentPropertyMap , class PointPropertyMap = typename boost::property_map<TriangleMesh, boost::vertex_point_t>::type, class GeomTraits = typename Kernel_traits<typename boost::property_traits<PointPropertyMap>::value_type>::Kernel>

std::size_t CGAL::segmentation_from_sdf_values	(	const TriangleMesh &	triangle_mesh,
		SDFPropertyMap	sdf_values_map,
		SegmentPropertyMap	segment_ids,
		std::size_t	number_of_clusters = 5,
		double	smoothing_lambda = 0.26,
		bool	output_cluster_ids = false,
		PointPropertyMap	ppmap = PointPropertyMap(),
		GeomTraits	traits = GeomTraits()
	)

#include <CGAL/mesh_segmentation.h>

Function computing the segmentation of a surface mesh given an SDF value per facet.

This function fills a property map which associates a segment-id (in [0, number of segments -1]) or a cluster-id (in [0, number_of_clusters -1]) to each facet. A segment is a set of connected facets which are placed under the same cluster (see Figure 77.5).

Note

Log-normalization is applied on sdf_values_map before segmentation. As described in the original paper [4], this normalization is done to preserve thin parts of the mesh by increasing the distance between smaller SDF values and reducing it between larger ones.

There is no direct relation between the parameter number_of_clusters and the final number of segments after segmentation. However, setting a large number of clusters will result in a detailed segmentation of the mesh with a large number of segments.

Precondition

is_triangle_mesh(triangle_mesh)

number_of_clusters > 0

Template Parameters

TriangleMesh	a model of FaceListGraph
SDFPropertyMap	a ReadablePropertyMap with boost::graph_traits<TriangleMesh>::face_descriptor as key and double as value type
SegmentPropertyMap	a ReadWritePropertyMap with boost::graph_traits<TriangleMesh>::face_descriptor as key and std::size_t as value type
GeomTraits	a model of SegmentationGeomTraits
PointPropertyMap	a ReadablePropertyMap with boost::graph_traits<TriangleMesh>::vertex_descriptor as key and GeomTraits::Point_3 as value type.

Parameters

	triangle_mesh	surface mesh corresponding to the SDF values
	sdf_values_map	the SDF value of each facet between [0-1]
[out]	segment_ids	the segment or cluster id of each facet
	number_of_clusters	number of clusters for the soft clustering
	smoothing_lambda	factor which indicates the importance of the surface features for the energy minimization. It is recommended to choose a value in the interval [0,1]. See the section Hard clustering for more details.
	output_cluster_ids	if false fill segment_ids with segment-ids, and with cluster-ids otherwise (see Figure 77.5)
	traits	traits class
	ppmap	point property map. An overload is provided with get(boost::vertex_point,triangle_mesh) as default.

Returns

number of segments if output_cluster_ids is set to false and number_of_clusters otherwise

Examples

Surface_mesh_segmentation/extract_segmentation_into_mesh_example.cpp, Surface_mesh_segmentation/segmentation_from_sdf_values_SM_example.cpp, Surface_mesh_segmentation/segmentation_from_sdf_values_example.cpp, and Surface_mesh_segmentation/segmentation_with_facet_ids_example.cpp.

segmentation_via_sdf_values()

template<class TriangleMesh , class SegmentPropertyMap , class PointPropertyMap = typename boost::property_map<TriangleMesh, boost::vertex_point_t>::type, class GeomTraits = typename Kernel_traits<typename boost::property_traits<PointPropertyMap>::value_type>::Kernel>

std::size_t CGAL::segmentation_via_sdf_values	(	const TriangleMesh &	triangle_mesh,
		SegmentPropertyMap	segment_ids,
		double	cone_angle = 2.0 / 3.0 * CGAL_PI,
		std::size_t	number_of_rays = 25,
		std::size_t	number_of_clusters = 5,
		double	smoothing_lambda = 0.26,
		bool	output_cluster_ids = false,
		PointPropertyMap	ppmap = PointPropertyMap(),
		GeomTraits	traits = GeomTraits()
	)

#include <CGAL/mesh_segmentation.h>

Function computing the segmentation of a surface mesh.

This function is equivalent to calling the functions CGAL::sdf_values() and CGAL::segmentation_from_sdf_values() with the same parameters.

Note

There is no direct relation between the parameter number_of_clusters and the final number of segments after segmentation. However, setting a large number of clusters will result in a detailed segmentation of the mesh with a large number of segments.

For computing segmentations of the mesh with different parameters (i.e. number of levels, and smoothing lambda), it is more efficient to first compute the SDF values using CGAL::sdf_values() and use them in different calls to CGAL::segmentation_from_sdf_values().

Precondition

is_triangle_mesh(triangle_mesh)

number_of_clusters > 0

Template Parameters

TriangleMesh	a model of FaceListGraph
SegmentPropertyMap	a ReadWritePropertyMap with boost::graph_traits<TriangleMesh>::face_descriptor as key and std::size_t as value type
GeomTraits	a model of SegmentationGeomTraits
PointPropertyMap	a ReadablePropertyMap with boost::graph_traits<TriangleMesh>::vertex_descriptor as key and GeomTraits::Point_3 as value type.

Parameters

	triangle_mesh	surface mesh on which SDF values are computed
[out]	segment_ids	the segment or cluster id of each facet
	cone_angle	opening angle in radians for the cone of each facet
	number_of_rays	number of rays picked in the cone of each facet. In our experiments, we observe that increasing the number of rays beyond the default has a little effect on the quality of the segmentation result
	number_of_clusters	number of clusters for the soft clustering
	smoothing_lambda	factor which indicates the importance of the surface features for the energy minimization. It is recommended to choose a value in the interval [0,1]. See the section Hard clustering for more details.
	output_cluster_ids	if false fill segment_ids with segment-ids, and with cluster-ids otherwise (see Figure 77.5)
	traits	traits class
	ppmap	point property map. An overload is provided with get(boost::vertex_point,triangle_mesh) as default.

Returns

number of segments if output_cluster_ids is set to false and number_of_clusters otherwise

Examples

Surface_mesh_segmentation/segmentation_via_sdf_values_example.cpp.