CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap > Class Template Reference

#include <CGAL/Variational_medial_axis_sampling.h>

Definition

template<typename TriangleMesh, typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>
class CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >

Algorithm class for extracting a variational medial skeleton from a triangulated surface mesh.

This class takes as input a triangulated surface mesh and iteratively samples the medial axis by optimizing the placement of medial spheres. The result is a non-manifold triangle mesh that captures the medial structure of the shape, consisting of both curve segments (1D) and triangle face patches (2D), derived from the adjacency of clusters associated with each medial sphere.

The process terminates when either the desired number of spheres is reached, or a maximum number of iterations is exceeded.

Note

This method is designed to generate coarse approximations of the medial axis. The number of spheres that can be reliably generated depends on the density of the input surface sampling. For best results, we recommend keeping the total number of medial spheres under nb_samples/100. In addition, the user can explicitly request cluster merging or splitting operations to locally simplify or refine the skeleton structure.

Template Parameters

TriangleMesh	a model of FaceListGraph
ConcurrencyTag	a tag indicating whether the algorithm should run sequentially or in parallel. This determines the execution mode at compile time. Default: CGAL::Sequential_tag Valid values: CGAL::Sequential_tag, CGAL::Parallel_tag, CGAL::Parallel_if_available_tag
AccelerationType	a tag indicating whether the algorithm should use Kd-tree or BVH as acceleration structure. Default: CGAL::KD_tree_tag Valid values: CGAL::KD_tree_tag, CGAL::BVH_tag,
GeomTraits	a model of Kernel Default: CGAL::Kernel_traits< boost::property_traits< boost::property_map<TriangleMesh, CGAL::vertex_point_t>::type >::value_type >::Kernel
VertexPointMap	a model of ReadWritePropertyMap with boost::graph_traits<TriangleMesh>::vertex_descriptor as key and GeomTraits::Point_3 as value type. Default: boost::property_map<TriangleMesh, CGAL::vertex_point_t>::const_type.

Examples

Variational_medial_axis/vmas_class_interface.cpp.

Public Types
using	Sphere_3 = typename GT::Sphere_3
	sphere type
using	FT = typename GT::FT
	number type

Public Member Functions
template<class NamedParameters = parameters::Default_named_parameters>
bool	sample (const NamedParameters &np=parameters::default_values())
	computes a static skeleton based on the Variational Medial Axis Sampling method.
bool	update_single_step (bool enable_split=false)
	updates the medial spheres by performing a single step of the algorithm.
void	update (std::size_t nb_iteration)
	performs a specified number of algorithm iterations.
bool	add_spheres (int nb_sphere)
	adds spheres by iteratively splitting existing spheres.
void	add_sphere_by_id (Sphere_ID sphere_id, int nb_iteration=10)
	adds a new sphere by splitting sphere with the id sphere_id.
void	remove_sphere_by_id (Sphere_ID sphere_id, int nb_iteration=10)
	removes a sphere by its sphere_id.
Medial_skeleton< TriangleMesh, GeomTraits >	skeleton () const
	returns the medial skeleton as a Medial_skeleton object.

Constructor
The constructor of a vmas object. Template Parameters NamedParameters a sequence of Named Parameters Parameters tmesh The input triangle mesh without borders. gt The geometric traits class used for geometric computations. np An optional sequence of Named Parameters, listed below: Optional Named Parameters number_of_spheres The desired number of medial spheres in the resulting skeleton. Type: unsigned int Default: 100 number_of_samples The number of samples on the surface mesh to use for the optimization process. Type: unsigned int Default: max(20000, number_of_spheres * 100) Extra: The number of samples should be significantly larger than the number of spheres.(x100 at least) number_of_iterations The maximum number of iterations for the optimization process. Type: int Default: 1000 lambda A weight balancing the two energy terms (SQEM and Euclidean). Smaller values encourage the skeleton to extend deeper into local geometric features of the shape. Type: FT Default: FT(0.2) Extra: The range of this parameter is (0,1]. random_seed The random seed to sample points on the triangle mesh surface. Type: unsigned int Extra: Fix the random seed so that the result can be reproduced vertex_point_map a property map associating points to the vertices of pmesh Type: a class model of ReadablePropertyMap with boost::graph_traits<PolygonMesh>::vertex_descriptor as key type and Point_3 as value type Default: boost::get(CGAL::vertex_point, pmesh) verbose If true, the algorithm will print detailed information about its progress. Type: bool Default: false
template<class NamedParameters = parameters::Default_named_parameters>
	Variational_medial_axis_sampling (const TriangleMesh &tmesh, const NamedParameters &np=parameters::default_values(), const GT &gt=GT())

Parameters
FT	lambda () const
	returns the lambda parameter for the algorithm.
void	set_lambda (FT lambda)
	sets function for lambda().
int	number_of_spheres () const
	returns the desired number of spheres for the algorithm.
void	set_number_of_spheres (int num)
	sets the desired number of spheres.
int	max_iteration () const
	returns the maximum number of iterations for the algorithm.
void	set_max_iteration (int max_iter)
	sets the maximum number of iterations.

Member Function Documentation

add_sphere_by_id()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

void CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::add_sphere_by_id	(	Sphere_ID	sphere_id,
		int	nb_iteration = 10
	)

adds a new sphere by splitting sphere with the id sphere_id.

This function is aimed to be called during interactive sessions, where the use can specify a sphere to split and add a new sphere based on the split vertex.

Parameters

sphere_id	The ID of the sphere to split.
nb_iteration	Number of optimization iterations to perform after adding the sphere (default: 10).

add_spheres()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

bool CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::add_spheres

(

int

nb_sphere

)

adds spheres by iteratively splitting existing spheres.

This function attempts to add the specified number of spheres by running the algorithm with sphere splitting enabled until either the target number is reached or maximum iterations are exceeded.

Parameters

nb_sphere

Number of spheres to add

Precondition

nb_sphere must be positive

At least one sphere must already exist

Returns

True if spheres were added successfully, false otherwise.

Examples

Variational_medial_axis/vmas_class_interface.cpp.

lambda()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

FT CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::lambda

(

)

const

returns the lambda parameter for the algorithm.

This parameter controls the balance between the SQEM and Euclidean energy terms. Smaller values encourage the skeleton to extend deeper into local geometric features of the shape.

max_iteration()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

int CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::max_iteration

(

)

const

returns the maximum number of iterations for the algorithm.

In case the algorithm does not converge, it will stop after this number of iterations.

remove_sphere_by_id()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

void CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::remove_sphere_by_id	(	Sphere_ID	sphere_id,
		int	nb_iteration = 10
	)

removes a sphere by its sphere_id.

This function is aimed to be called during interactive sessions, where the user can specify a sphere to remove.

Parameters

sphere_id	The ID of the sphere to remove.
nb_iteration	Number of optimization iterations to perform after removing the sphere (default: 10).

sample()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

template<class NamedParameters = parameters::Default_named_parameters>

bool CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::sample

(

const NamedParameters &

np = parameters::default_values()

)

computes a static skeleton based on the Variational Medial Axis Sampling method.

Template Parameters

NamedParameters

a sequence of Named Parameters

Parameters

np	an optional sequence of Named Parameters, listed below:

Optional Named Parameters

number_of_spheres The desired number of medial spheres in the resulting skeleton. Type: unsigned int Default: 100
number_of_samples The number of samples on the surface mesh to use for the optimization process. Type: unsigned int Default: max(20000, number_of_spheres * 100) Extra: The number of samples should be significantly larger than the number of spheres.(x100 at least)
number_of_iterations The maximum number of iterations for the optimization process. Type: int Default: 1000
lambda A weight balancing the two energy terms (SQEM and Euclidean). Smaller values encourage the skeleton to extend deeper into local geometric features of the shape. Type: FT Default: FT(0.2) Extra: The range of this parameter is (0,1].
random_seed The random seed to sample points on the triangle mesh surface. Type: unsigned int Extra: Fix the random seed so that the result can be reproduced
verbose If true, the algorithm will print detailed information about its progress on the standard output. Type: bool Default: false

Examples

Variational_medial_axis/vmas_class_interface.cpp.

set_lambda()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

void CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::set_lambda

(

FT

lambda

)

sets function for lambda().

Note: The value of lambda must be strictly positive; if set to zero, it will default to 0.2.

skeleton()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

Medial_skeleton< TriangleMesh, GeomTraits > CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::skeleton

(

)

const

returns the medial skeleton as a Medial_skeleton object.

This function builds a medial skeleton from the current state of the medial sphere mesh. It extracts the vertices, edges, and faces from the medial sphere mesh and constructs the medial skeleton accordingly.

Returns

A Medial_skeleton object containing the medial skeleton data.

Examples

Variational_medial_axis/vmas_class_interface.cpp.

update()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

void CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::update

(

std::size_t

nb_iteration

)

performs a specified number of algorithm iterations.

This function allows manual control over the algorithm execution, performing only position optimization without sphere splitting.

Parameters

nb_iteration

Number of iterations to perform

Examples

Variational_medial_axis/vmas_class_interface.cpp.

update_single_step()

template<typename TriangleMesh , typename ConcurrencyTag = Sequential_tag, typename AccelerationType = KD_tree_tag, typename GeomTraits = Default, typename VertexPointMap = Default>

bool CGAL::Variational_medial_axis_sampling< TriangleMesh, ConcurrencyTag, AccelerationType, GeomTraits, VertexPointMap >::update_single_step

(

bool

enable_split = false

)

updates the medial spheres by performing a single step of the algorithm.

This function performs one iteration of the algorithm, updating sphere positions and computing errors. It can optionally enable sphere splitting based on convergence criteria.

Parameters

enable_split

If true, allows sphere splitting based on convergence criteria.

Returns

truet if the algorithm has converged,false` otherwise.