Mesh Generation Functions

The two main functions to generate a periodic mesh are make_periodic_3_mesh_3() and refine_periodic_3_mesh_3().

Other functions are provided to optimize an existing periodic mesh.

Functions
template<class C3T3 , class MD , class MC >
C3T3	CGAL::make_periodic_3_mesh_3 (const MD &domain, const MC &criteria, parameters::internal::Features_options features=parameters::features(domain), parameters::internal::Lloyd_options lloyd=parameters::no_lloyd(), parameters::internal::Odt_options odt=parameters::no_odt(), parameters::internal::Perturb_options perturb=parameters::perturb(), parameters::internal::Exude_options exude=parameters::exude())
	The function make_periodic_3_mesh_3() is a 3D periodic mesh generator. More...
template<typename C3T3 , typename MD >
CGAL::Mesh_optimization_return_code	CGAL::lloyd_optimize_periodic_3_mesh_3 (C3T3 &c3t3, const MD &domain, double parameters::time_limit=0, std::size_t parameters::max_iteration_number=0, double parameters::convergence=0.02, double parameters::freeze_bound=0.01, bool parameters::do_freeze=true)
	The function lloyd_optimize_periodic_3_mesh_3() is a periodic mesh optimization process based on the minimization of a global energy function. More...
template<typename C3T3 , typename MD >
Mesh_optimization_return_code	CGAL::odt_optimize_periodic_3_mesh_3 (C3T3 &c3t3, const MD &domain, double parameters::time_limit=0, std::size_t parameters::max_iteration_number=0, double parameters::convergence=0.02, double parameters::freeze_bound=0.01, bool parameters::do_freeze=true)
	The function odt_optimize_periodic_3_mesh_3() is a periodic mesh optimization process based on the minimization of a global energy function. More...
template<typename C3T3 , typename MD >
CGAL::Mesh_optimization_return_code	CGAL::perturb_periodic_3_mesh_3 (C3T3 &c3t3, const MD &domain, double parameters::time_limit=0, double parameters::sliver_bound=0)
	The function perturb_periodic_3_mesh_3() is a mesh optimizer that improves the quality of a Delaunay mesh by changing the positions of some vertices of the mesh. More...
template<typename C3T3 >
CGAL::Mesh_optimization_return_code	CGAL::exude_periodic_3_mesh_3 (C3T3 &c3t3, double parameters::time_limit=0, double parameters::sliver_bound=0)
	The function exude_periodic_3_mesh_3() performs a sliver exudation process on a periodic Delaunay mesh. More...
template<class C3T3 , class MD , class MeshCriteria >
void	CGAL::refine_periodic_3_mesh_3 (C3T3 &c3t3, const MD &mesh_domain, const MC &mesh_criteria, parameters::internal::Lloyd_options lloyd=parameters::no_lloyd(), parameters::internal::Odt_options odt=parameters::no_odt(), parameters::internal::Perturb_options perturb=parameters::perturb(), parameters::internal::Exude_options exude=parameters::exude())
	The function refine_periodic_3_mesh_3() is a 3D periodic mesh generator. More...

Function Documentation

exude_periodic_3_mesh_3()

template<typename C3T3 >

CGAL::Mesh_optimization_return_code CGAL::exude_periodic_3_mesh_3	(	C3T3 &	c3t3,
		double parameters::time_limit	= 0,
		double parameters::sliver_bound	= 0
	)

#include <CGAL/optimize_periodic_3_mesh_3.h>

The function exude_periodic_3_mesh_3() performs a sliver exudation process on a periodic Delaunay mesh.

The sliver exudation process consists in optimizing the weights of vertices of the periodic weighted Delaunay triangulation in such a way that slivers disappear and the quality of the mesh improves.

Warning

This optimizer modifies the weight of vertices of the periodic triangulation and, if called, must be the last optimizer to be called. If the mesh is refined after this optimization has been performed, all improvements will be lost.

This function directly calls exude_mesh_3(), but is provided for convenience. Further information can be found on the documentation of the function exude_mesh_3().

Examples:

Periodic_3_mesh_3/mesh_implicit_shape_with_optimizers.cpp.

lloyd_optimize_periodic_3_mesh_3()

template<typename C3T3 , typename MD >

CGAL::Mesh_optimization_return_code CGAL::lloyd_optimize_periodic_3_mesh_3	(	C3T3 &	c3t3,
		const MD &	domain,
		double parameters::time_limit	= 0,
		std::size_t parameters::max_iteration_number	= 0,
		double parameters::convergence	= 0.02,
		double parameters::freeze_bound	= 0.01,
		bool parameters::do_freeze	= true
	)

#include <CGAL/optimize_periodic_3_mesh_3.h>

The function lloyd_optimize_periodic_3_mesh_3() is a periodic mesh optimization process based on the minimization of a global energy function.

This function directly calls lloyd_optimize_mesh_3(), but is provided for convenience. Further information can be found on the documentation of the function lloyd_optimize_mesh_3().

Note

This function requires the Eigen library.

Examples:

Periodic_3_mesh_3/mesh_implicit_shape_with_optimizers.cpp.

make_periodic_3_mesh_3()

template<class C3T3 , class MD , class MC >

C3T3 CGAL::make_periodic_3_mesh_3	(	const MD &	domain,
		const MC &	criteria,
		parameters::internal::Features_options	features = parameters::features(domain),
		parameters::internal::Lloyd_options	lloyd = parameters::no_lloyd(),
		parameters::internal::Odt_options	odt = parameters::no_odt(),
		parameters::internal::Perturb_options	perturb = parameters::perturb(),
		parameters::internal::Exude_options	exude = parameters::exude()
	)

#include <CGAL/make_periodic_3_mesh_3.h>

The function make_periodic_3_mesh_3() is a 3D periodic mesh generator.

It produces simplicial meshes which discretize 3D periodic domains.

The periodic mesh generation algorithm is a Delaunay refinement process followed by an optimization phase. The criteria driving the Delaunay refinement process may be tuned to achieve the user needs with respect to the size of mesh elements, the accuracy of boundaries approximation, etc.

The optimization phase is a sequence of optimization processes, amongst the following available optimizers: an ODT-smoothing, a Lloyd smoothing, a sliver perturber, and a sliver exuder. Each optimization process can be activated or not, according to the user requirements and available time. By default, only the perturber and the exuder are activated. Note that the benefits of the exuder will be lost if the mesh is further refined afterward, and that ODT-smoothing, Lloyd-smoothing, and sliver perturber should never be called after the sliver exuder. In the case of further refinement, only the sliver exuder can be used.

The function outputs the mesh to an object which provides iterators to traverse the resulting mesh data structure or can be written to a file (see Examples ).

Template Parameters

C3T3	is required to be a model of the concept MeshComplex_3InTriangulation_3. This is the return type. The type C3T3 is in particular required to provide a nested type C3T3::Triangulation for the 3D periodic triangulation embedding the periodic mesh. The vertex and cell base classes of the triangulation C3T3::Triangulation are required to be models of the concepts MeshVertexBase_3 and Periodic_3TriangulationDSVertexBase_3, and of the concepts MeshCellBase_3 and Periodic_3TriangulationDSCellBase_3, respectively.
MD	is required to be a model of the concept Periodic_3MeshDomain_3, or of the refined concept Periodic_3MeshDomainWithFeatures_3 if the domain has corners and curve segments that need to be accurately represented in the mesh. The argument domain is the sole link through which the domain to be discretized is known by the mesh generation algorithm.
MC	is required to be a model of the concept MeshCriteria_3, or a model of the refined concept MeshCriteriaWithFeatures_3 if the domain has exposed features. The argument criteria of type MC specifies the size and shape requirements for mesh tetrahedra and surface facets. These criteria form the rules which drive the refinement process. All mesh elements satisfy those criteria at the end of the refinement process. In addition, if the domain has features, the argument criteria provides a sizing field to guide the discretization of 1-dimensional exposed features.

Named Parameters

• features allows the user to specify whether 0 and 1-dimensional features have to be taken into account or not when the domain is a model of Periodic_3MeshDomainWithFeatures_3. The type Features of this parameter is an internal undescribed type. The library provides functions to construct appropriate values of that type.
  • parameters::features(domain) sets features according to the domain, i.e. 0 and 1-dimensional features are taken into account if domain is a Periodic_3MeshDomainWithFeatures_3. This is the default behavior if parameter features is not specified.
  • parameters::no_features() prevents the representation of 0 and 1-dimensional features in the mesh.

The four additional parameters are optimization parameters. They control which optimization processes are performed and allow the user to tune the parameters of the optimization processes. Individual optimization parameters are not described here as they are internal types (see instead the documentation page of each optimizer). For each optimization algorithm, there exist two global functions that allow to enable or disable the optimizer:

• lloyd: parameters::lloyd() and parameters::no_lloyd() are designed to trigger or not a call to lloyd_optimize_periodic_3_mesh_3() function and to set the parameters of this optimizer. If one parameter is not set, the default value of lloyd_optimize_periodic_3_mesh_3() is used for this parameter.
• ODT: parameters::odt() and parameters::no_odt() are designed to trigger or not a call to odt_optimize_periodic_3_mesh_3 function and to set the parameters of this optimizer. If one parameter is not set, the default value of odt_optimize_periodic_3_mesh_3() is used for this parameter.
• perturb: parameters::perturb() and parameters::no_perturb() are designed to trigger or not a call to perturb_periodic_3_mesh_3 function and to set the parameters of this optimizer. If one parameter is not set, the default value of CGAL::perturb_periodic_3_mesh_3 is used for this parameter, except for the time bound which is set to be equal to the refinement CPU time.
• exude: parameters::exude() and parameters::no_exude() are designed to trigger or not a call to exude_periodic_3_mesh_3() function and to override to set the parameters of this optimizer. If one parameter is not set, the default value of exude_periodic_3_mesh_3() is used for this parameter, except for the time bound which is set to be equal to the refinement CPU time.

The optimization parameters can be passed in an arbitrary order. If one parameter is not passed, its default value is used. The default values are no_lloyd(), no_odt(), perturb() and exude().

Note that whatever may be the optimization processes activated, they are always launched in the order that is a suborder of the following (see user manual for further details): ODT-smoother, Lloyd-smoother, perturb, exude.

Beware that optimization of the mesh is obtained by perturbing mesh vertices and modifying the mesh connectivity and that this has an impact on the strict compliance to the refinement criteria. Though a strict compliance to mesh criteria is guaranteed at the end of the Delaunay refinement, this may no longer be true after some optimization processes. Also beware that the default behavior does involve some optimization processes.

See also

refine_periodic_3_mesh_3()

make_mesh_3()

parameters::features()

parameters::no_features()

exude_periodic_3_mesh_3()

perturb_periodic_3_mesh_3()

lloyd_optimize_periodic_3_mesh_3()

odt_optimize_periodic_3_mesh_3()

parameters::exude()

parameters::no_exude()

parameters::perturb()

parameters::no_perturb()

parameters::lloyd()

parameters::no_lloyd()

parameters::odt()

parameters::no_odt()

odt_optimize_periodic_3_mesh_3()

template<typename C3T3 , typename MD >

Mesh_optimization_return_code CGAL::odt_optimize_periodic_3_mesh_3	(	C3T3 &	c3t3,
		const MD &	domain,
		double parameters::time_limit	= 0,
		std::size_t parameters::max_iteration_number	= 0,
		double parameters::convergence	= 0.02,
		double parameters::freeze_bound	= 0.01,
		bool parameters::do_freeze	= true
	)

#include <CGAL/optimize_periodic_3_mesh_3.h>

The function odt_optimize_periodic_3_mesh_3() is a periodic mesh optimization process based on the minimization of a global energy function.

This function directly calls odt_optimize_mesh_3(), but is provided for convenience. Further information can be found on the documentation of the function odt_optimize_mesh_3().

Examples:

Periodic_3_mesh_3/mesh_implicit_shape_with_optimizers.cpp.

perturb_periodic_3_mesh_3()

template<typename C3T3 , typename MD >

CGAL::Mesh_optimization_return_code CGAL::perturb_periodic_3_mesh_3	(	C3T3 &	c3t3,
		const MD &	domain,
		double parameters::time_limit	= 0,
		double parameters::sliver_bound	= 0
	)

#include <CGAL/optimize_periodic_3_mesh_3.h>

The function perturb_periodic_3_mesh_3() is a mesh optimizer that improves the quality of a Delaunay mesh by changing the positions of some vertices of the mesh.

This function directly calls perturb_mesh_3(), but is provided for convenience. Further information can be found on the documentation of the function perturb_mesh_3().

Examples:

Periodic_3_mesh_3/mesh_implicit_shape_with_optimizers.cpp.

refine_periodic_3_mesh_3()

template<class C3T3 , class MD , class MeshCriteria >

void CGAL::refine_periodic_3_mesh_3	(	C3T3 &	c3t3,
		const MD &	mesh_domain,
		const MC &	mesh_criteria,
		parameters::internal::Lloyd_options	lloyd = parameters::no_lloyd(),
		parameters::internal::Odt_options	odt = parameters::no_odt(),
		parameters::internal::Perturb_options	perturb = parameters::perturb(),
		parameters::internal::Exude_options	exude = parameters::exude()
	)

#include <CGAL/refine_periodic_3_mesh_3.h>

The function refine_periodic_3_mesh_3() is a 3D periodic mesh generator.

It produces periodic simplicial meshes which discretize 3D periodic domains.

The periodic mesh generation algorithm is a Delaunay refinement process followed by an optimization phase. The criteria driving the Delaunay refinement process may be tuned to achieve the user needs with respect to the size of mesh elements, the accuracy of boundaries approximation, etc.

The optimization phase is a sequence of optimization processes, amongst the following available optimizers: an ODT-smoothing, a Lloyd smoothing, a sliver perturber, and a sliver exuder. Each optimization process can be activated or not, according to the user requirements and available time. By default, only the perturber and the exuder are activated. Note that the benefits of the exuder will be lost if the mesh is further refined afterward.

Attention

The function template refine_periodic_3_mesh_3() may be used to refine a previously computed mesh, e.g.:

C3T3 c3t3 = CGAL::make_periodic_3_mesh_3<C3T3>(domain,criteria);

CGAL::refine_periodic_3_mesh_3(c3t3, domain, new_criteria);

Note that the triangulation must form at all times a simplicial complex within a single copy of the domain (see Sections The Flat Torus and Representation of the manual of 3D periodic triangulations). It is the responsability of the user to provide a triangulation that satisfies this condition when calling the refinement function refine_periodic_3_mesh_3. The underlying triangulation of a mesh complex obtained through make_periodic_3_mesh_3() or refine_periodic_3_mesh_3() will always satisfy this condition.

Template Parameters

C3T3	is required to be a model of the concept MeshComplex_3InTriangulation_3. The argument c3t3 is passed by reference as this object is modified by the refinement process. As the refinement process only adds points to the triangulation, all vertices of the triangulation of c3t3 remain in the mesh during the refinement process. The object c3t3 can be used to insert specific points in the domain to ensure that they will be contained in the final triangulation. The type C3T3 is in particular required to provide a nested type C3T3::Triangulation for the 3D periodic triangulation embedding the periodic mesh. The vertex and cell base classes of the triangulation C3T3::Triangulation are required to be models of the concepts MeshVertexBase_3 and Periodic_3TriangulationDSVertexBase_3, and of the concepts MeshCellBase_3 and Periodic_3TriangulationDSCellBase_3, respectively.
MD	is required to be a model of the concept Periodic_3MeshDomain_3 or of the refined concept Periodic_3MeshDomainWithFeatures_3 if 0 and 1-dimensional features of the input complex have to be accurately represented in the mesh. The argument domain is the sole link through which the domain to be discretized is known by the mesh generation algorithm.
MC	has to be a model of the concept MeshCriteria_3, or a model of the refined concept MeshCriteriaWithFeatures_3 if the domain has exposed features. The argument criteria of type MC specifies the size and shape requirements for mesh tetrahedra and surface facets. These criteria form the rules which drive the refinement process. All mesh elements satisfy those criteria at the end of the refinement process. In addition, if the domain has features, the argument criteria provides a sizing field to guide the discretization of 1-dimensional exposed features.

The four additional parameters are optimization parameters. They control which optimization processes are performed and allow the user to tune the parameters of the optimization processes. Individual optimization parameters are not described here as they are internal types (see instead the documentation page of each optimizer). For each optimization algorithm, there exist two global functions that allow to enable or disable the optimizer:

Named Parameters

• lloyd parameters::lloyd() and parameters::no_lloyd() are designed to trigger or not a call to lloyd_optimize_periodic_3_mesh_3() function and to set the parameters of this optimizer. If one parameter is not set, the default value of lloyd_optimize_periodic_3_mesh_3() is used for this parameter.
• ODT parameters::odt() and parameters::no_odt() are designed to trigger or not a call to odt_optimize_periodic_3_mesh_3() function and to set the parameters of this optimizer. If one parameter is not set, the default value of odt_optimize_periodic_3_mesh_3() is used for this parameter.
• perturb parameters::perturb() and parameters::no_perturb() are designed to trigger or not a call to perturb_periodic_3_mesh_3() function and to set the parameters of this optimizer. If one parameter is not set, the default value of perturb_periodic_3_mesh_3() is used for this parameter, except for the time bound which is set to be equal to the refinement CPU time.
• exude parameters::exude() and parameters::no_exude() are designed to trigger or not a call to exude_periodic_3_mesh_3() function and to override to set the parameters of this optimizer. If one parameter is not set, the default value of exude_periodic_3_mesh_3() is used for this parameter, except for the time bound which is set to be equal to the refinement CPU time.

The optimization parameters can be passed in arbitrary order. If one parameter is not passed, its default value is used. The default values are no_lloyd(), no_odt(), perturb() and exude(). Note that whatever may be the optimization processes activated, they are always launched in the order that is a suborder of the following (see user manual for further details): ODT-smoother, Lloyd-smoother, perturber, and exuder.

Beware that optimization of the mesh is obtained by perturbing mesh vertices and modifying the mesh connectivity and that this has an impact on the strict compliance to the refinement criteria. Though a strict compliance to mesh criteria is guaranteed at the end of the Delaunay refinement, this may no longer be true after some optimization processes. Also beware that the default behavior does involve some optimization processes.

See also

make_periodic_3_mesh_3()

refine_mesh_3()

exude_periodic_3_mesh_3()

perturb_periodic_3_mesh_3()

lloyd_optimize_periodic_3_mesh_3()

odt_optimize_periodic_3_mesh_3()

parameters::exude

parameters::no_exude

parameters::perturb

parameters::no_perturb

parameters::lloyd

parameters::no_lloyd

parameters::odt

parameters::no_odt