songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

clean up Periodic_3_mesh_3 doc

This commit is contained in:
Sébastien Loriot 2022-09-21 17:20:29 +02:00
parent 7a6faa7c38
commit d2cd6244ff
6 changed files with 448 additions and 486 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Mesh_3/include/CGAL/refine_mesh_3.h
View File

@ -153,6 +153,8 @@ private:
* \tparam MC either a model of the concept `MeshCriteria_3` or a model * \tparam MC either a model of the concept `MeshCriteria_3` or a model
* of `MeshCriteriaWithFeatures_3` if the domain has exposed features. * of `MeshCriteriaWithFeatures_3` if the domain has exposed features.
* *
* \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters
*
* \param c3t3 the mesh to be refined that is modified by the refinement process. * \param c3t3 the mesh to be refined that is modified by the refinement process.
* As the refinement process only adds points to the triangulation, all * As the refinement process only adds points to the triangulation, all
* vertices of the triangulation of `c3t3` remain in the * vertices of the triangulation of `c3t3` remain in the

83
Periodic_3_mesh_3/doc/Periodic_3_mesh_3/CGAL/optimize_periodic_3_mesh_3.h
View File

@ -1,83 +0,0 @@
namespace CGAL {
/*!
\ingroup PkgPeriodic3Mesh3Functions
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 \ref thirdpartyEigen library.
*/
template<typename C3T3, typename MD>
CGAL::Mesh_optimization_return_code
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);
/*!
\ingroup PkgPeriodic3Mesh3Functions
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()`.
*/
template<typename C3T3, typename MD>
Mesh_optimization_return_code
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);
/*!
\ingroup PkgPeriodic3Mesh3Functions
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()`.
*/
template<typename C3T3, typename MD>
CGAL::Mesh_optimization_return_code
perturb_periodic_3_mesh_3(C3T3& c3t3,
const MD& domain,
double parameters::time_limit=0,
double parameters::sliver_bound=0);
/*!
\ingroup PkgPeriodic3Mesh3Functions
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()`.
*/
template<typename C3T3>
CGAL::Mesh_optimization_return_code
exude_periodic_3_mesh_3(C3T3& c3t3,
double parameters::time_limit=0,
double parameters::sliver_bound=0);
} /* namespace CGAL */

3
Periodic_3_mesh_3/doc/Periodic_3_mesh_3/Doxyfile.in
View File

@ -2,7 +2,8 @@
INPUT += \ INPUT += \
${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/make_periodic_3_mesh_3.h \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/make_periodic_3_mesh_3.h \
${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/refine_periodic_3_mesh_3.h ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/refine_periodic_3_mesh_3.h \
${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/optimize_periodic_3_mesh_3.h
PROJECT_NAME = "CGAL ${CGAL_DOC_VERSION} - 3D Periodic Mesh Generation" PROJECT_NAME = "CGAL ${CGAL_DOC_VERSION} - 3D Periodic Mesh Generation"
EXTRACT_ALL = false EXTRACT_ALL = false
HIDE_UNDOC_CLASSES = true HIDE_UNDOC_CLASSES = true

318
Periodic_3_mesh_3/include/CGAL/make_periodic_3_mesh_3.h
View File

@ -167,167 +167,163 @@ struct C3t3_initializer<C3T3, MeshDomain, MeshCriteria, true, CGAL::Tag_true>
// ----------------------------------- // -----------------------------------
/*! /*!
\ingroup PkgPeriodic3Mesh3Functions * \ingroup PkgPeriodic3Mesh3Functions
*
The function `make_periodic_3_mesh_3()` is a 3D periodic mesh generator. * The function `make_periodic_3_mesh_3()` is a 3D periodic mesh generator.
It produces simplicial meshes which discretize 3D periodic domains. * It produces simplicial meshes which discretize 3D periodic domains.
The periodic mesh generation algorithm is a Delaunay refinement process * The periodic mesh generation algorithm is a Delaunay refinement process
followed by an optimization phase. The criteria driving the Delaunay refinement * followed by an optimization phase. The criteria driving the Delaunay refinement
process may be tuned to achieve the user needs with respect to * process may be tuned to achieve the user needs with respect to
the size of mesh elements, the accuracy of boundaries approximation, * the size of mesh elements, the accuracy of boundaries approximation,
etc. * etc.
The optimization phase is a sequence of optimization processes, * The optimization phase is a sequence of optimization processes,
amongst the following available optimizers: an ODT-smoothing, * amongst the following available optimizers: an ODT-smoothing,
a Lloyd smoothing, a sliver perturber, and a sliver exuder. * a Lloyd smoothing, a sliver perturber, and a sliver exuder.
Each optimization process can be activated or not, according to the user requirements * Each optimization process can be activated or not, according to the user requirements
and available time. * and available time.
By default, only the perturber and the exuder are activated. * By default, only the perturber and the exuder are activated.
Note that the benefits of the exuder will be lost if the mesh * Note that the benefits of the exuder will be lost if the mesh
is further refined afterward, and that ODT-smoothing, Lloyd-smoothing, * is further refined afterward, and that ODT-smoothing, Lloyd-smoothing,
and sliver perturber should never be called after the sliver exuder. * and sliver perturber should never be called after the sliver exuder.
In the case of further refinement, only the sliver exuder can be used. * 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 * 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 * traverse the resulting mesh data structure or can be written to a file
(see \ref Periodic_3_mesh_3_section_examples ). * (see \ref Periodic_3_mesh_3_section_examples ).
*
*
\tparam C3T3 is required to be a model of * \tparam C3T3 is required to be a model of
the concept `MeshComplex_3InTriangulation_3`. This is the return type. * the concept `MeshComplex_3InTriangulation_3`. This is the return type.
The type `C3T3` is in particular required to provide a nested type * The type `C3T3` is in particular required to provide a nested type
`C3T3::Triangulation` for the 3D triangulation * `C3T3::Triangulation` for the 3D triangulation
embedding the mesh. The vertex and cell base classes of the * embedding the mesh. The vertex and cell base classes of the
triangulation `C3T3::Triangulation` are required to be models of the * triangulation `C3T3::Triangulation` are required to be models of the
concepts `MeshVertexBase_3` and `MeshCellBase_3` * concepts `MeshVertexBase_3` and `MeshCellBase_3`
respectively. * respectively.
*
\tparam MD is required to be a model of * \tparam MD is required to be a model of
the concept `MeshDomain_3`, or of the refined concept * the concept `MeshDomain_3`, or of the refined concept
`MeshDomainWithFeatures_3` * `MeshDomainWithFeatures_3`
if the domain has corners and curves that need to be accurately represented in the mesh. * if the domain has corners and curves that need to be accurately represented in the mesh.
The argument `domain` * The argument `domain`
is the sole link through which the domain * is the sole link through which the domain
to be discretized is known by the mesh generation algorithm. * to be discretized is known by the mesh generation algorithm.
*
\tparam MC has to be a model of the concept * \tparam 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. * `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 * The argument `criteria` of type `MC` specifies the
size and shape requirements for mesh tetrahedra * size and shape requirements for mesh tetrahedra
and surface facets. These criteria * and surface facets. These criteria
form the rules which drive the refinement process. All mesh elements * form the rules which drive the refinement process. All mesh elements
satisfy those criteria at the end of the refinement process. * satisfy those criteria at the end of the refinement process.
In addition, if the domain has features, the argument * In addition, if the domain has features, the argument
`criteria` provides a sizing field to guide the discretization * `criteria` provides a sizing field to guide the discretization
of 1-dimensional exposed features. * of 1-dimensional exposed features.
*
\tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters"
*
*
\param domain the domain to be discretized * \param domain the domain to be discretized
\param criteria the criteria * \param criteria the criteria
\param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below:
*
\cgalNamedParamsBegin * \cgalNamedParamsBegin
\cgalParamNBegin{features_options} * \cgalParamSectionBegin{Feature preservation options}
\cgalParamDescription{allows the user to specify whether 0 and 1-dimensional features have to be * \cgalParamDescription{If the domain is a model of `MeshDomainWithFeatures_3`, 0 and 1-dimensional features can be
taken into account or not * taken into account while generating the mesh. The following two named parameters control
when the domain is a model of `MeshDomainWithFeatures_3`. * this option:
The type `Features` of this parameter is an internal undescribed type. * <UL>
The library provides functions to construct appropriate values of that type. * <LI>\link parameters::features() `parameters::features(domain)` \endlink
<UL> * <LI>`parameters::no_features()`
<LI>\link parameters::features() `parameters::features(domain)` \endlink sets `features` according to the domain, * </UL>}
i.e.\ 0 and 1-dimensional features are taken into account if `domain` is a * \cgalParamDefault{`parameters::features(domain)`}
`MeshDomainWithFeatures_3`. This is the default behavior * \cgalParamSectionEnd
if parameter `features` is not specified. * \cgalParamSectionBegin{Topological options (manifoldness)}
<LI>`parameters::no_features()` prevents the representation * \cgalParamDescription{In order to drive the meshing algorithm and ensure that the output mesh follows a desired topological criterion,
of 0 and 1-dimensional features in the mesh. * three named parameters control this option:
</UL>} * <UL>
\cgalParamType{`parameters::features()' OR `parameters::features(domain)`} * <LI>`parameters::manifold()`
\cgalParamDefault{`parameters::features(domain)`} * <LI>`parameters::manifold_with_boundary()`
* <LI>`parameters::non_manifold()`
\cgalParamNBegin{manifold_option} * </UL>
\cgalParamDescription{allows the user to drive the meshing algorithm, * Note that the meshing algorithm cannot generate a manifold surface if the input surface is not manifold.}
and ensure that the output mesh surface follows the given manifold criterion. * \cgalParamDefault{`parameters::non_manifold()`}
It can be activated with `parameters::manifold()`, `parameters::manifold_with_boundary()` * \cgalParamSectionEnd
and `parameters::non_manifold()`. Note that the meshing algorithm cannot generate a manifold * \cgalParamSectionBegin{Lloyd optimization}
surface if the input surface is not manifold.} * \cgalParamDescription{`lloyd_optimize_mesh_3()` can optionally be called after the meshing process.
\cgalParamType{`parameters::manifold()` OR `parameters::manifold_with_boundary()` OR `parameters::non_manifold()`} * Two named parameters control this behavior:
\cgalParamDefault{`parameters::non_manifold()`} * <UL>
* <LI> `parameters::no_lloyd()`
\cgalParamNBegin{lloyd_options} * <LI> `parameters::lloyd_optimize_mesh_3()`
\cgalParamDescription{`parameters::lloyd()` and `parameters::no_lloyd()` are designed to * </UL>}
trigger or not a call to `lloyd_optimize_mesh_3()` function and to set the * \cgalParamDefault{`parameters::no_lloyd()`}
parameters of this optimizer. If one parameter is not set, the default value of * \cgalParamSectionEnd
`lloyd_optimize_mesh_3()` is used for this parameter.} * \cgalParamSectionBegin{ODT optimization}
\cgalParamType{`parameters::lloyd()` OR `parameters::no_lloyd()`} * \cgalParamDescription{`odt_optimize_mesh_3()` can optionally be called after the meshing process.
\cgalParamDefault{`parameters::no_lloyd()`} * Two named parameters control this behavior:
* <UL>
\cgalParamNBegin{odt_options} * <LI> `parameters::no_odt()`
\cgalParamDescription{`parameters::odt()` and `parameters::no_odt()` are designed to * <LI> `parameters::odt()`
trigger or not a call to `odt_optimize_mesh_3()` function and * </UL>}
to set the parameters of this optimizer. * \cgalParamDefault{`parameters::no_odt()`}
If one parameter is not set, the default value of * \cgalParamSectionEnd
`odt_optimize_mesh_3()` is used for this parameter.} * \cgalParamSectionBegin{Mesh perturbation}
\cgalParamType{`parameters::odt()` OR `parameters::no_odt()`} * \cgalParamDescription{`perturb_mesh_3()` can optionally be called after the meshing process.
\cgalParamDefault{`parameters::no_odt()`} * Two named parameters control this behavior:
* <UL>
\cgalParamNBegin{perturb_options} * <LI> `parameters::no_perturb()`
\cgalParamDescription{`parameters::perturb()` and `parameters::no_perturb()` are designed to * <LI> `parameters::perturb()`
trigger or not a call to `perturb_mesh_3()` function and * </UL>}
to set the parameters of this optimizer. If one parameter is not set, the default value of * \cgalParamDefault{`parameters::perturb()`}
`perturb_mesh_3()` is used for this parameter, except for the time bound which is set to be * \cgalParamSectionEnd
equal to the refinement CPU time.} * \cgalParamSectionBegin{Mesh exudation}
\cgalParamType{`parameters::perturb()` and `parameters::no_perturb()`} * \cgalParamDescription{`exude_mesh_3()` can optionally be called after the meshing process.
\cgalParamDefault{`parameters::no_perturb`} * Two named parameters control this behavior:
* <UL>
\cgalParamNBegin{exude_options} * <LI> `parameters::exude()`
\cgalParamDescription{parameters::exude()` and `parameters::no_exude()` are designed to * <LI> `parameters::no_exude()`
trigger or not a call to `exude_mesh_3()` function and to override to set the * </UL>}
parameters of this optimizer. If one parameter is not set, the default value of * \cgalParamDefault{`parameters::exude()`}
`exude_mesh_3()` is used for this parameter, except for the time bound which is set to be * \cgalParamSectionEnd
equal to the refinement CPU time.} * \cgalNamedParamsEnd
\cgalParamType{`parameters::exude()` and `parameters::no_exude()`} *
\cgalParamDefault{`parameters::no_exude`} * 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
\cgalNamedParamsEnd * `no_lloyd()`, `no_odt()`, `perturb()` and `exude()`.
*
The optimization parameters can be passed in an arbitrary order. If one parameter * Note that whatever may be the optimization processes activated,
is not passed, its default value is used. The default values are * they are always launched in the order that is a suborder
`no_lloyd()`, `no_odt()`, `perturb()` and `exude()`. * of the following (see user manual for further
* details): *ODT-smoother*, *Lloyd-smoother*, *perturber*, and *exuder*.
Note that whatever may be the optimization processes activated, *
they are always launched in the order that is a suborder * Beware that optimization of the mesh is obtained
of the following (see user manual for further * by perturbing mesh vertices and modifying the mesh connectivity
details): *ODT-smoother*, *Lloyd-smoother*, *perturber*, and *exuder*. * and that this has an impact
* on the strict compliance to the refinement criteria.
Beware that optimization of the mesh is obtained * Though a strict compliance to mesh criteria
by perturbing mesh vertices and modifying the mesh connectivity * is guaranteed at the end of the Delaunay refinement, this may no longer be true after
and that this has an impact * some optimization processes. Also beware that the default behavior does involve some
on the strict compliance to the refinement criteria. * optimization processes.
Though a strict compliance to mesh criteria *
is guaranteed at the end of the Delaunay refinement, this may no longer be true after * \sa `refine_periodic_3_mesh_3()`
some optimization processes. Also beware that the default behavior does involve some * \sa `make_mesh_3()`
optimization processes. * \sa `parameters::features()`
* \sa `parameters::no_features()`
\sa `refine_periodic_3_mesh_3()` * \sa `parameters::manifold()`
\sa `make_mesh_3()` * \sa `parameters::manifold_with_boundary()`
\sa `parameters::features()` * \sa `parameters::non_manifold()`
\sa `parameters::no_features()` * \sa `exude_mesh_3()`
\sa `parameters::manifold()` * \sa `perturb_mesh_3()`
\sa `parameters::manifold_with_boundary()` * \sa `lloyd_optimize_mesh_3()`
\sa `parameters::non_manifold()` * \sa `odt_optimize_mesh_3()`
\sa `exude_mesh_3()` * \sa `parameters::exude()`
\sa `perturb_mesh_3()` * \sa `parameters::no_exude()`
\sa `lloyd_optimize_mesh_3()` * \sa `parameters::perturb()`
\sa `odt_optimize_mesh_3()` * \sa `parameters::no_perturb()`
\sa `parameters::exude()` * \sa `parameters::lloyd()`
\sa `parameters::no_exude()` * \sa `parameters::no_lloyd()`
\sa `parameters::perturb()` * \sa `parameters::odt()`
\sa `parameters::no_perturb()` * \sa `parameters::no_odt()`
\sa `parameters::lloyd()` */
\sa `parameters::no_lloyd()`
\sa `parameters::odt()`
\sa `parameters::no_odt()`
*/
template<typename C3T3, typename MeshDomain, typename MeshCriteria, typename CGAL_NP_TEMPLATE_PARAMETERS> template<typename C3T3, typename MeshDomain, typename MeshCriteria, typename CGAL_NP_TEMPLATE_PARAMETERS>
C3T3 make_periodic_3_mesh_3(MeshDomain& domain, MeshCriteria& criteria, const CGAL_NP_CLASS& np = parameters::default_values()) C3T3 make_periodic_3_mesh_3(MeshDomain& domain, MeshCriteria& criteria, const CGAL_NP_CLASS& np = parameters::default_values())
{ {

49
Periodic_3_mesh_3/include/CGAL/optimize_periodic_3_mesh_3.h
View File

@ -24,6 +24,15 @@
namespace CGAL { namespace CGAL {
// ---------------------------------- pertuber --------------------------------- // ---------------------------------- pertuber ---------------------------------
/*!
* \ingroup PkgPeriodic3Mesh3Functions
*
* 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()`.
*/
template<typename C3T3, typename MeshDomain, typename CGAL_NP_TEMPLATE_PARAMETERS> template<typename C3T3, typename MeshDomain, typename CGAL_NP_TEMPLATE_PARAMETERS>
Mesh_optimization_return_code perturb_periodic_3_mesh_3(C3T3& c3t3, MeshDomain& domain, const CGAL_NP_CLASS& np = parameters::default_values()) Mesh_optimization_return_code perturb_periodic_3_mesh_3(C3T3& c3t3, MeshDomain& domain, const CGAL_NP_CLASS& np = parameters::default_values())
{ {
@ -47,7 +56,23 @@ Mesh_optimization_return_code perturb_periodic_3_mesh_3(const CGAL_NP_CLASS& ...
return perturb_periodic_3_mesh_3(internal_np::combine_named_parameters(nps...)); return perturb_periodic_3_mesh_3(internal_np::combine_named_parameters(nps...));
} }
// ---------------------------------- exuder ----------------------------------- // ---------------------------------- exuder -----------------------------------
/*!
* \ingroup PkgPeriodic3Mesh3Functions
*
* 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()`.
*/
template<typename C3T3, typename CGAL_NP_TEMPLATE_PARAMETERS> template<typename C3T3, typename CGAL_NP_TEMPLATE_PARAMETERS>
Mesh_optimization_return_code exude_periodic_3_mesh_3(C3T3& c3t3,const CGAL_NP_CLASS& np = parameters::default_values()) Mesh_optimization_return_code exude_periodic_3_mesh_3(C3T3& c3t3,const CGAL_NP_CLASS& np = parameters::default_values())
{ {
@ -56,7 +81,6 @@ Mesh_optimization_return_code exude_periodic_3_mesh_3(C3T3& c3t3,const CGAL_NP_C
int time_limit=choose_parameter(get_parameter(np,internal_np::maximum_running_time),0); int time_limit=choose_parameter(get_parameter(np,internal_np::maximum_running_time),0);
double sliver_bound= choose_parameter(get_parameter(np,internal_np::lower_sliver_bound),parameters::default_values_for_mesh_3::exude_sliver_bound); double sliver_bound= choose_parameter(get_parameter(np,internal_np::lower_sliver_bound),parameters::default_values_for_mesh_3::exude_sliver_bound);
return exude_mesh_3_impl(c3t3,time_limit,sliver_bound); return exude_mesh_3_impl(c3t3,time_limit,sliver_bound);
} }
template<typename C3T3, typename ... CGAL_NP_TEMPLATE_PARAMETERS_VARIADIC> template<typename C3T3, typename ... CGAL_NP_TEMPLATE_PARAMETERS_VARIADIC>
Mesh_optimization_return_code exude_periodic_3_mesh_3(C3T3& c3t3, const CGAL_NP_CLASS& ... nps) Mesh_optimization_return_code exude_periodic_3_mesh_3(C3T3& c3t3, const CGAL_NP_CLASS& ... nps)
@ -70,7 +94,15 @@ Mesh_optimization_return_code exude_periodic_3_mesh_3(const CGAL_NP_CLASS& ... n
} }
// ------------------------------ odt optimizer -------------------------------- // ------------------------------ odt optimizer --------------------------------
/*!
* \ingroup PkgPeriodic3Mesh3Functions
*
* 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()`.
*/
template<typename C3T3,typename MeshDomain,typename CGAL_NP_TEMPLATE_PARAMETERS> template<typename C3T3,typename MeshDomain,typename CGAL_NP_TEMPLATE_PARAMETERS>
Mesh_optimization_return_code odt_optimize_periodic_3_mesh_3(C3T3& c3t3, MeshDomain& domain, const CGAL_NP_CLASS& np = parameters::default_values()) Mesh_optimization_return_code odt_optimize_periodic_3_mesh_3(C3T3& c3t3, MeshDomain& domain, const CGAL_NP_CLASS& np = parameters::default_values())
{ {
@ -97,6 +129,17 @@ Mesh_optimization_return_code odt_optimize_periodic_3_mesh_3(const CGAL_NP_CLASS
// ------------------------------- lloyd optimizer ----------------------------- // ------------------------------- lloyd optimizer -----------------------------
/*!
* \ingroup PkgPeriodic3Mesh3Functions
*
* 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 \ref thirdpartyEigen library.
*/
template<typename C3T3, typename MeshDomain, typename CGAL_NP_TEMPLATE_PARAMETERS> template<typename C3T3, typename MeshDomain, typename CGAL_NP_TEMPLATE_PARAMETERS>
Mesh_optimization_return_code lloyd_optimize_periodic_3_mesh_3(C3T3& c3t3, MeshDomain& domain,const CGAL_NP_CLASS& np = parameters::default_values()) Mesh_optimization_return_code lloyd_optimize_periodic_3_mesh_3(C3T3& c3t3, MeshDomain& domain,const CGAL_NP_CLASS& np = parameters::default_values())
{ {

337
Periodic_3_mesh_3/include/CGAL/refine_periodic_3_mesh_3.h
View File

@ -134,174 +134,177 @@ void project_points(C3T3& c3t3,
} // namespace internal } // namespace internal
/*! /*!
\ingroup PkgPeriodic3Mesh3Functions * \ingroup PkgPeriodic3Mesh3Functions
*
The function `refine_periodic_3_mesh_3()` is a 3D periodic * The function `refine_periodic_3_mesh_3()` is a 3D periodic
mesh generator. It produces periodic simplicial meshes which discretize * mesh generator. It produces periodic simplicial meshes which discretize
3D periodic domains. * 3D periodic domains.
*
The periodic mesh generation algorithm is a Delaunay refinement process * The periodic mesh generation algorithm is a Delaunay refinement process
followed by an optimization phase. * followed by an optimization phase.
The criteria driving the Delaunay refinement * The criteria driving the Delaunay refinement
process may be tuned to achieve the user needs with respect to * process may be tuned to achieve the user needs with respect to
the size of mesh elements, the accuracy of boundaries approximation, etc. * the size of mesh elements, the accuracy of boundaries approximation, etc.
*
The optimization phase is a sequence of optimization processes, * The optimization phase is a sequence of optimization processes,
amongst the following available optimizers: an ODT-smoothing, * amongst the following available optimizers: an ODT-smoothing,
a Lloyd smoothing, a sliver perturber, and a sliver exuder. * a Lloyd smoothing, a sliver perturber, and a sliver exuder.
Each optimization process can be activated or not, according to the user requirements * Each optimization process can be activated or not, according to the user requirements
and available time. * and available time.
By default, only the perturber and the exuder are activated. * By default, only the perturber and the exuder are activated.
Note that the benefits of the exuder will be lost if the mesh * Note that the benefits of the exuder will be lost if the mesh
is further refined afterward. * is further refined afterward.
*
\attention The function template `refine_periodic_3_mesh_3()` may be used * \attention The function template `refine_periodic_3_mesh_3()` may be used
to refine a previously computed mesh, e.g.: * to refine a previously computed mesh, e.g.:
\code{.cpp} * \code{.cpp}
C3T3 c3t3 = CGAL::make_periodic_3_mesh_3<C3T3>(domain,criteria); * C3T3 c3t3 = CGAL::make_periodic_3_mesh_3<C3T3>(domain,criteria);
*
CGAL::refine_periodic_3_mesh_3(c3t3, domain, new_criteria); * CGAL::refine_periodic_3_mesh_3(c3t3, domain, new_criteria);
\endcode * \endcode
*
\attention Note that the triangulation must form at all times a simplicial complex within * \attention Note that the triangulation must form at all times a simplicial complex within
a single copy of the domain (see Sections \ref P3Triangulation3secspace and \ref P3Triangulation3secintro * a single copy of the domain (see Sections \ref P3Triangulation3secspace and \ref P3Triangulation3secintro
of the manual of 3D periodic triangulations). It is the responsability of the user to provide * 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 * a triangulation that satisfies this condition when calling the refinement
function `refine_periodic_3_mesh_3`. The underlying triangulation of a mesh * 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()` * complex obtained through `make_periodic_3_mesh_3()` or `refine_periodic_3_mesh_3()`
will always satisfy this condition. * will always satisfy this condition.
*
*
\tparam C3T3 is required to be a model of * \tparam C3T3 is required to be a model of
the concept * the concept
`MeshComplex_3InTriangulation_3`. * `MeshComplex_3InTriangulation_3`.
The argument `c3t3` is passed by * The argument `c3t3` is passed by
reference as this object is modified by the refinement process. As the * reference as this object is modified by the refinement process. As the
refinement process only adds points to the triangulation, all * refinement process only adds points to the triangulation, all
vertices of the triangulation of `c3t3` remain in the * vertices of the triangulation of `c3t3` remain in the
mesh during the refinement process. Object `c3t3` can be used to insert * mesh during the refinement process. Object `c3t3` can be used to insert
specific points in the domain to ensure that they will be contained in the * specific points in the domain to ensure that they will be contained in the
final triangulation. * final triangulation.
The type `C3T3` is in particular required to provide a nested type * The type `C3T3` is in particular required to provide a nested type
`C3T3::Triangulation` for the 3D triangulation * `C3T3::Triangulation` for the 3D triangulation
embedding the mesh. The vertex and cell base classes of the * embedding the mesh. The vertex and cell base classes of the
triangulation `C3T3::Triangulation` are required to be models of the * triangulation `C3T3::Triangulation` are required to be models of the
concepts `MeshVertexBase_3` and `MeshCellBase_3` * concepts `MeshVertexBase_3` and `MeshCellBase_3`
respectively. * respectively.
*
\tparam MD is required to be a model of * \tparam MD is required to be a model of
the concept `Periodic_3MeshDomain_3` or of the refined concept * the concept `Periodic_3MeshDomain_3` or of the refined concept
`Periodic_3MeshDomainWithFeatures_3` if 0 and 1-dimensional features * `Periodic_3MeshDomainWithFeatures_3` if 0 and 1-dimensional features
of the input complex have to be accurately represented in the mesh. * of the input complex have to be accurately represented in the mesh.
The argument `domain` is the sole link through which the domain * The argument `domain` is the sole link through which the domain
to be discretized is known by the mesh generation algorithm. * to be discretized is known by the mesh generation algorithm.
*
\tparam MC is required to be a model of the concept * \tparam MC is required to be a model of the concept
`MeshCriteria_3`, or a model of the refined concept `MeshCriteriaWithFeatures_3` * `MeshCriteria_3`, or a model of the refined concept `MeshCriteriaWithFeatures_3`
if the domain has exposed features. The argument `criteria` of * if the domain has exposed features. The argument `criteria` of
type `MC` specifies the * type `MC` specifies the
size and shape requirements for mesh tetrahedra * size and shape requirements for mesh tetrahedra
and surface facets. These criteria * and surface facets. These criteria
form the rules which drive the refinement process. All mesh elements * form the rules which drive the refinement process. All mesh elements
satisfy those criteria at the end of the refinement process. * satisfy those criteria at the end of the refinement process.
In addition, if the domain has features, the argument * In addition, if the domain has features, the argument
`criteria` provides a sizing field to guide the discretization * `criteria` provides a sizing field to guide the discretization
of 1-dimensional exposed features. * of 1-dimensional exposed features.
*
\param c3t3 the mesh to be refined. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters
\param domain the domain to be discretized *
\param criteria the criteria * \param c3t3 the mesh to be refined.
\param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: * \param domain the domain to be discretized
* \param criteria the criteria
The following four parameters are optional optimization parameters. * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below:
They control which optimization processes are performed *
and allow the user to tune the parameters of the optimization processes. * The following four parameters are optional optimization parameters.
Individual optimization parameters are not described here as they are * They control which optimization processes are performed
internal types (see instead the documentation page of each optimizer). * and allow the user to tune the parameters of the optimization processes.
For each optimization algorithm, there exist two global functions * Individual optimization parameters are not described here as they are
that allow to enable or disable the optimizer: * internal types (see instead the documentation page of each optimizer).
* For each optimization algorithm, there exist two global functions
\cgalNamedParamsBegin * that allow to enable or disable the optimizer:
\cgalParamNBegin{manifold_option} *
\cgalParamDescription{allows the user to drive the meshing algorithm, * \cgalNamedParamsBegin
and ensure that the output mesh surface follows the given manifold criterion. * \cgalParamSectionBegin{Topological options (manifoldness)}
It can be activated with `parameters::manifold()`, `parameters::manifold_with_boundary()` * \cgalParamDescription{In order to drive the meshing algorithm and ensure that the output mesh follows a desired topological criterion,
and `parameters::non_manifold()`. Note that the meshing algorithm cannot generate a manifold * three named parameters control this option:
surface if the input surface is not manifold.} * <UL>
\cgalParamType{`parameters::manifold()` OR `parameters::manifold_with_boundary()` OR `parameters::non_manifold()`} * <LI>`parameters::manifold()`
\cgalParamDefault{`parameters::non_manifold()`} * <LI>`parameters::manifold_with_boundary()`
* <LI>`parameters::non_manifold()`
\cgalParamNBegin{lloyd_options} * </UL>
\cgalParamDescription{`parameters::lloyd()` and `parameters::no_lloyd()` are designed to * Note that the meshing algorithm cannot generate a manifold surface if the input surface is not manifold.}
trigger or not a call to `lloyd_optimize_mesh_3()` function and to set the * \cgalParamDefault{`parameters::non_manifold()`}
parameters of this optimizer. If one parameter is not set, the default value of * \cgalParamSectionEnd
`lloyd_optimize_mesh_3()` is used for this parameter.} * \cgalParamSectionBegin{Lloyd optimization}
\cgalParamType{`parameters::lloyd()` OR `parameters::no_lloyd()`} * \cgalParamDescription{`lloyd_optimize_mesh_3()` can optionally be called after the meshing process.
\cgalParamDefault{`parameters::no_lloyd()'} * Two named parameters control this behavior:
* <UL>
\cgalParamNBegin{odt_options} * <LI> `parameters::no_lloyd()`
\cgalParamDescription{`parameters::odt()` and `parameters::no_odt()` are designed to * <LI> `parameters::lloyd_optimize_mesh_3()`
trigger or not a call to `odt_optimize_mesh_3()` function and * </UL>}
to set the parameters of this optimizer. * \cgalParamDefault{`parameters::no_lloyd()`}
If one parameter is not set, the default value of * \cgalParamSectionEnd
`odt_optimize_mesh_3()` is used for this parameter.} * \cgalParamSectionBegin{ODT optimization}
\cgalParamType{`parameters::odt()` OR `parameters::no_odt()`} * \cgalParamDescription{`odt_optimize_mesh_3()` can optionally be called after the meshing process.
\cgalParamDefault{`parameters::no_odt()`} * Two named parameters control this behavior:
* <UL>
\cgalParamNBegin{perturb_options} * <LI> `parameters::no_odt()`
\cgalParamDescription{`parameters::perturb()` and `parameters::no_perturb()` are designed to * <LI> `parameters::odt()`
trigger or not a call to `perturb_mesh_3()` function and * </UL>}
to set the parameters of this optimizer. If one parameter is not set, the default value of * \cgalParamDefault{`parameters::no_odt()`}
`perturb_mesh_3()` is used for this parameter, except for the time bound which is set to be * \cgalParamSectionEnd
equal to the refinement CPU time.} * \cgalParamSectionBegin{Mesh perturbation}
\cgalParamType{`parameters::perturb()` and `parameters::no_perturb()`} * \cgalParamDescription{`perturb_mesh_3()` can optionally be called after the meshing process.
\cgalParamDefault{`parameters::no_perturb`} * Two named parameters control this behavior:
* <UL>
\cgalParamNBegin{exude_options} * <LI> `parameters::no_perturb()`
\cgalParamDescription{parameters::exude()` and `parameters::no_exude()` are designed to * <LI> `parameters::perturb()`
trigger or not a call to `exude_mesh_3()` function and to override to set the * </UL>}
parameters of this optimizer. If one parameter is not set, the default value of * \cgalParamDefault{`parameters::perturb()`}
`exude_mesh_3()` is used for this parameter, except for the time bound which is set to be * \cgalParamSectionEnd
equal to the refinement CPU time.} * \cgalParamSectionBegin{Mesh exudation}
\cgalParamType{`parameters::exude()` and `parameters::no_exude()`} * \cgalParamDescription{`exude_mesh_3()` can optionally be called after the meshing process.
\cgalParamDefault{`parameters::no_exude`} * Two named parameters control this behavior:
* <UL>
\cgalNamedParamsEnd * <LI> `parameters::exude()`
* <LI> `parameters::no_exude()`
The optimization parameters can be passed in arbitrary order. If one parameter * </UL>}
is not passed, its default value is used. The default values are * \cgalParamDefault{`parameters::exude()`}
`no_lloyd()`, `no_odt()`, `perturb()` and `exude()`. * \cgalParamSectionEnd
Note that whatever may be the optimization processes activated, * \cgalNamedParamsEnd
they are always launched in the order that is a suborder *
of the following (see user manual for further * The optimization parameters can be passed in arbitrary order. If one parameter
details): *ODT-smoother*, *Lloyd-smoother*, *perturber*, and *exuder*. * is not passed, its default value is used. The default values are
* `no_lloyd()`, `no_odt()`, `perturb()` and `exude()`.
Beware that optimization of the mesh is obtained * Note that whatever may be the optimization processes activated,
by perturbing mesh vertices and modifying the mesh connectivity * they are always launched in the order that is a suborder
and that this has an impact * of the following (see user manual for further
on the strict compliance to the refinement criteria. * details): *ODT-smoother*, *Lloyd-smoother*, *perturber*, and *exuder*.
Though a strict compliance to mesh criteria *
is guaranteed at the end of the Delaunay refinement, this may no longer be true after * Beware that optimization of the mesh is obtained
some optimization processes. Also beware that the default behavior does involve some * by perturbing mesh vertices and modifying the mesh connectivity
optimization processes. * and that this has an impact
* on the strict compliance to the refinement criteria.
\sa `make_periodic_3_mesh_3()` * Though a strict compliance to mesh criteria
\sa `refine_mesh_3()` * is guaranteed at the end of the Delaunay refinement, this may no longer be true after
\sa `exude_periodic_3_mesh_3()` * some optimization processes. Also beware that the default behavior does involve some
\sa `perturb_periodic_3_mesh_3()` * optimization processes.
\sa `lloyd_optimize_periodic_3_mesh_3()` *
\sa `odt_optimize_periodic_3_mesh_3()` * \sa `make_periodic_3_mesh_3()`
\sa `parameters::exude` * \sa `refine_mesh_3()`
\sa `parameters::no_exude` * \sa `exude_periodic_3_mesh_3()`
\sa `parameters::perturb` * \sa `perturb_periodic_3_mesh_3()`
\sa `parameters::no_perturb` * \sa `lloyd_optimize_periodic_3_mesh_3()`
\sa `parameters::lloyd` * \sa `odt_optimize_periodic_3_mesh_3()`
\sa `parameters::no_lloyd` * \sa `parameters::exude`
\sa `parameters::odt` * \sa `parameters::no_exude`
\sa `parameters::no_odt` * \sa `parameters::perturb`
* \sa `parameters::no_perturb`
* \sa `parameters::lloyd`
* \sa `parameters::no_lloyd`
* \sa `parameters::odt`
* \sa `parameters::no_odt`
*/ */
template<typename C3T3, typename MeshDomain, typename MeshCriteria, typename CGAL_NP_TEMPLATE_PARAMETERS> template<typename C3T3, typename MeshDomain, typename MeshCriteria, typename CGAL_NP_TEMPLATE_PARAMETERS>
void refine_periodic_3_mesh_3(C3T3& c3t3, MeshDomain& domain, MeshCriteria& criteria, const CGAL_NP_CLASS& np = parameters::default_values()) void refine_periodic_3_mesh_3(C3T3& c3t3, MeshDomain& domain, MeshCriteria& criteria, const CGAL_NP_CLASS& np = parameters::default_values())
{ {