From b740c31bc1b9184d17772eae8dd2d1938c5c1fb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Loriot?= Date: Tue, 20 Sep 2022 18:03:47 +0200 Subject: [PATCH] clean up make_mesh_3 and refine_mesh_3 --- Mesh_3/include/CGAL/exude_mesh_3.h | 2 +- Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h | 15 +- Mesh_3/include/CGAL/make_mesh_3.h | 323 +++++++++---------- Mesh_3/include/CGAL/odt_optimize_mesh_3.h | 2 +- Mesh_3/include/CGAL/refine_mesh_3.h | 329 ++++++++++---------- 5 files changed, 317 insertions(+), 354 deletions(-) diff --git a/Mesh_3/include/CGAL/exude_mesh_3.h b/Mesh_3/include/CGAL/exude_mesh_3.h index 911a4cf5ce6..78d3d644de3 100644 --- a/Mesh_3/include/CGAL/exude_mesh_3.h +++ b/Mesh_3/include/CGAL/exude_mesh_3.h @@ -41,7 +41,7 @@ namespace CGAL { * 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. * - * @tparam C3T3 is required to be a model of the concept `MeshComplex_3InTriangulation_3`. + * @tparam C3T3 a model of the concept `MeshComplex_3InTriangulation_3`. * @tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * @param c3t3 the initial mesh that will be modified by the algorithm to represent the final optimized mesh. diff --git a/Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h b/Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h index 226cdbdeb10..5215190a1a8 100644 --- a/Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h +++ b/Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h @@ -51,21 +51,12 @@ namespace CGAL { * in a special way so as to preserve an accurate * representation of the domain boundaries. * - * \tparam C3T3 is required to be a model of the concept - * `MeshComplex_3InTriangulation_3`. - * The argument `c3t3`, passed by - * reference, provides the initial mesh - * and is modified by the algorithm - * to represent the final optimized mesh. - * - * \tparam MD is required to be a model of the concept - * `MeshDomain_3`. The argument `domain` must be the `MD` - * object used to create the `c3t3` parameter. - * + * \tparam C3T3 a model of the concept `MeshComplex_3InTriangulation_3`. + * \tparam MD a model of the concept `MeshDomain_3`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * @param c3t3 the initial mesh that will be modified by the algorithm to represent the final optimized mesh. - * @param domain the domain to be discretized + * @param domain the domain used to create the `c3t3` parameter * @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: * * \cgalNamedParamsBegin diff --git a/Mesh_3/include/CGAL/make_mesh_3.h b/Mesh_3/include/CGAL/make_mesh_3.h index c083b325ba4..2634dab6665 100644 --- a/Mesh_3/include/CGAL/make_mesh_3.h +++ b/Mesh_3/include/CGAL/make_mesh_3.h @@ -361,176 +361,159 @@ struct C3t3_initializer < C3T3, MD, MC, true, CGAL::Tag_false > // ----------------------------------- /*! -\ingroup PkgMesh3Functions - -The function `make_mesh_3()` is a 3D -mesh generator. It produces simplicial meshes which discretize -3D domains. - -The 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 \ref Mesh_3_section_examples ). - - -\tparam C3T3 is required to be a model of -the concept `MeshComplex_3InTriangulation_3`, -and a model of `MeshComplexWithFeatures_3InTriangulation_3` -if the domain is a model of `MeshDomainWithFeatures_3`. -This is the return type. -The type `C3T3` is in particular required to provide a nested type -`C3T3::Triangulation` for the 3D triangulation -embedding the mesh. The vertex and cell base classes of the -triangulation `C3T3::Triangulation` are required to be models of the -concepts `MeshVertexBase_3` and `MeshCellBase_3` -respectively. - -\tparam MD is required to be a model of -the concept `MeshDomain_3`, or of the refined concept -`MeshDomainWithFeatures_3` -if the domain has corners and curves 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. - -\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. -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. - -\tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" - - @param domain the domain to be discretized - @param criteria the criteria - @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: - -\cgalNamedParamsBegin - \cgalParamNBegin{features_options} - \cgalParamDescription{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 `MeshDomainWithFeatures_3`. - The type `Features` of this parameter is an internal undescribed type. - The library provides functions to construct appropriate values of that type. - } - \cgalParamType{`parameters::features()' OR `parameters::features(domain)`} - \cgalParamDefault{`parameters::features(domain)`} - - \cgalParamNBegin{manifold_option} - \cgalParamDescription{allows the user to drive the meshing algorithm, - and ensure that the output mesh surface follows the given manifold criterion. - It can be activated with `parameters::manifold()`, `parameters::manifold_with_boundary()` - and `parameters::non_manifold()`. Note that the meshing algorithm cannot generate a manifold - surface if the input surface is not manifold.} - \cgalParamType{`parameters::manifold()` OR `parameters::manifold_with_boundary()` OR `parameters::non_manifold()`} - \cgalParamDefault{`parameters::non_manifold()`} - - \cgalParamNBegin{lloyd_options} - \cgalParamDescription{`parameters::lloyd()` and `parameters::no_lloyd()` are designed to - trigger or not a call to `lloyd_optimize_mesh_3()` function and to set the - parameters of this optimizer. If one parameter is not set, the default value of - `lloyd_optimize_mesh_3()` is used for this parameter.} - \cgalParamType{`parameters::lloyd()` OR `parameters::no_lloyd()`} - \cgalParamDefault{`parameters::no_lloyd()`} - - \cgalParamNBegin{odt_options} - \cgalParamDescription{`parameters::odt()` and `parameters::no_odt()` are designed to - trigger or not a call to `odt_optimize_mesh_3()` function and - to set the parameters of this optimizer. - If one parameter is not set, the default value of - `odt_optimize_mesh_3()` is used for this parameter.} - \cgalParamType{`parameters::odt()` OR `parameters::no_odt()`} - \cgalParamDefault{`parameters::no_odt()`} - - \cgalParamNBegin{perturb_options} - \cgalParamDescription{`parameters::perturb()` and `parameters::no_perturb()` are designed to - trigger or not a call to `perturb_mesh_3()` function and - to set the parameters of this optimizer. If one parameter is not set, the default value of - `perturb_mesh_3()` is used for this parameter, except for the time bound which is set to be - equal to the refinement CPU time.} - \cgalParamType{`parameters::perturb()` and `parameters::no_perturb()`} - \cgalParamDefault{`parameters::no_perturb`} - - \cgalParamNBegin{exude_options} - \cgalParamDescription{parameters::exude()` and `parameters::no_exude()` are designed to - trigger or not a call to `exude_mesh_3()` function and to override to set the - parameters of this optimizer. If one parameter is not set, the default value of - `exude_mesh_3()` is used for this parameter, except for the time bound which is set to be - equal to the refinement CPU time.} - \cgalParamType{`parameters::exude()` and `parameters::no_exude()`} - \cgalParamDefault{`parameters::no_exude`} - -\cgalNamedParamsEnd - -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*, *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. - -\sa `refine_mesh_3()` -\sa `parameters::features()` -\sa `parameters::no_features()` -\sa `parameters::manifold()` -\sa `parameters::manifold_with_boundary()` -\sa `parameters::non_manifold()` -\sa `exude_mesh_3()` -\sa `perturb_mesh_3()` -\sa `lloyd_optimize_mesh_3()` -\sa `odt_optimize_mesh_3()` -\sa `parameters::exude()` -\sa `parameters::no_exude()` -\sa `parameters::perturb()` -\sa `parameters::no_perturb()` -\sa `parameters::lloyd()` -\sa `parameters::no_lloyd()` -\sa `parameters::odt()` -\sa `parameters::no_odt()` -*/ - + * \ingroup PkgMesh3Functions + * + * The function `make_mesh_3()` is a 3D + * mesh generator. It produces simplicial meshes which discretize + * 3D domains. + * + * The 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 \ref Mesh_3_section_examples ). + * + * \tparam C3T3 either a model of the concept `MeshComplex_3InTriangulation_3` or + * of `MeshComplexWithFeatures_3InTriangulation_3` if `MD` + * is a model of `MeshDomainWithFeatures_3`. + * The type `C3T3` is in particular required to provide a nested type + * `C3T3::Triangulation` for the 3D triangulation + * embedding the mesh. The vertex and cell base classes of the + * triangulation `C3T3::Triangulation` are required to be models of the + * concepts `MeshVertexBase_3` and `MeshCellBase_3` respectively. + * + * \tparam MD either a model of the concept `MeshDomain_3` or of + * `MeshDomainWithFeatures_3` if 0 and 1-dimensional features + * of the input complex have to be accurately represented in the mesh. + * + * \tparam MC either a model of the concept `MeshCriteria_3` or a model + * of `MeshCriteriaWithFeatures_3` if the domain has exposed features. + * + * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" + * + * \param domain the domain used to create the `c3t3` parameter. It is the sole link through which the domain + * to be discretized is known by the mesh generation algorithm. + * \param criteria 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. + * + * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: + * + * \cgalNamedParamsBegin + * \cgalParamNBegin{Feature preservation options} + * \cgalParamDescription{If the domain is a model of `MeshDomainWithFeatures_3`, 0 and 1-dimensional features can be + * taken into account while generating the mesh. The following two named parameters control + * this option: + * } + * \cgalParamDefault{`parameters::features(domain)`} + * \cgalParamNEnd + * \cgalParamNBegin{Topological options (manifoldness)} + * \cgalParamDescription{In order to drive the meshing algorithm and ensure that the output mesh follows a desired topological criterion, + * three named parameters control this option: + * + * Note that the meshing algorithm cannot generate a manifold surface if the input surface is not manifold.} + * \cgalParamDefault{`parameters::non_manifold()`} + * \cgalParamNEnd + * \cgalParamNBegin{Lloyd optimization} + * \cgalParamDescription{`lloyd_optimize_mesh_3()` can optionally be called after the meshing process. + * Two named parameters control this behavior: + * } + * \cgalParamDefault{`parameters::no_lloyd()`} + * \cgalParamNEnd + * \cgalParamNBegin{ODT optimization} + * \cgalParamDescription{`odt_optimize_mesh_3()` can optionally be called after the meshing process. + * Two named parameters control this behavior: + * } + * \cgalParamDefault{`parameters::no_odt()`} + * \cgalParamNEnd + * \cgalParamNBegin{Mesh perturbation} + * \cgalParamDescription{`perturb_mesh_3()` can optionally be called after the meshing process. + * Two named parameters control this behavior: + * } + * \cgalParamDefault{`parameters::perturb()`} + * \cgalParamNEnd + * \cgalParamNBegin{Mesh exudation} + * \cgalParamDescription{`exude_mesh_3()` can optionally be called after the meshing process. + * Two named parameters control this behavior: + * } + * \cgalParamDefault{`parameters::exude()`} + * \cgalParamNEnd + * \cgalNamedParamsEnd + * + * 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. + * + * \sa `refine_mesh_3()` + * \sa `parameters::features()` + * \sa `parameters::no_features()` + * \sa `parameters::manifold()` + * \sa `parameters::manifold_with_boundary()` + * \sa `parameters::non_manifold()` + * \sa `exude_mesh_3()` + * \sa `perturb_mesh_3()` + * \sa `lloyd_optimize_mesh_3()` + * \sa `odt_optimize_mesh_3()` + * \sa `parameters::exude()` + * \sa `parameters::no_exude()` + * \sa `parameters::perturb()` + * \sa `parameters::no_perturb()` + * \sa `parameters::lloyd()` + * \sa `parameters::no_lloyd()` + * \sa `parameters::odt()` + * \sa `parameters::no_odt()` + */ template C3T3 make_mesh_3(MeshDomain& domain, MeshCriteria& criteria, const CGAL_NP_CLASS& np = parameters::default_values()) { diff --git a/Mesh_3/include/CGAL/odt_optimize_mesh_3.h b/Mesh_3/include/CGAL/odt_optimize_mesh_3.h index 2d0fae5d32d..0d939726df9 100644 --- a/Mesh_3/include/CGAL/odt_optimize_mesh_3.h +++ b/Mesh_3/include/CGAL/odt_optimize_mesh_3.h @@ -52,7 +52,6 @@ namespace CGAL { * * @tparam C3T3 a model of the concept `MeshComplex_3InTriangulation_3` * @tparam MeshDomain a model of the concept `MeshDomain_3` - * * @tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * * @param c3t3 the initial mesh and is modified by the algorithm to represent the final optimized mesh. @@ -102,6 +101,7 @@ namespace CGAL { * \cgalParamDefault{true} * \cgalParamNEnd * \cgalNamedParamsEnd + * * \return a value of type `CGAL::Mesh_optimization_return_code` which is: *