From 6505bb7d3963cb5064a59efcd091502b09b60def Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Loriot?= Date: Wed, 21 Sep 2022 11:49:28 +0200 Subject: [PATCH] fix parameters --- Mesh_3/doc/Mesh_3/CGAL/Mesh_3/parameters.h | 753 ++++++++++++--------- Mesh_3/include/CGAL/Mesh_3/parameters.h | 216 +++++- Mesh_3/include/CGAL/make_mesh_3.h | 83 --- Mesh_3/include/CGAL/perturb_mesh_3.h | 1 - 4 files changed, 617 insertions(+), 436 deletions(-) diff --git a/Mesh_3/doc/Mesh_3/CGAL/Mesh_3/parameters.h b/Mesh_3/doc/Mesh_3/CGAL/Mesh_3/parameters.h index cb4f081ba67..d1d2ab57741 100644 --- a/Mesh_3/doc/Mesh_3/CGAL/Mesh_3/parameters.h +++ b/Mesh_3/doc/Mesh_3/CGAL/Mesh_3/parameters.h @@ -2,355 +2,466 @@ namespace CGAL { namespace parameters { - /*! - \ingroup PkgMesh3Parameters - - The function `parameters::manifold()` is used to drive the - meshing algorithm for surfaces. - It ensures that the surface of the output mesh is a manifold surface - without boundaries. - The manifold property of the output mesh can be achieved only if the input surface - is a manifold. - Note that the meshing algorithm provably terminates only if the input - sharp edges have been protected, using the - feature protection (see \ref Mesh_3Protectionof0and1dimensionalExposed). - - \sa `CGAL::make_mesh_3()` - \sa `CGAL::refine_mesh_3()` - \sa `CGAL::parameters::manifold_with_boundary()` - \sa `CGAL::parameters::non_manifold()` - */ - unspecified_type manifold(); - - /*! - \ingroup PkgMesh3Parameters - - The function `parameters::non_manifold()` is used to drive the - meshing algorithm for surfaces. - It does not ensure that the surface of the output mesh is a manifold surface. - The manifold property of the output mesh might nevertheless result from an appropriate - choice of meshing criteria. - \sa `CGAL::make_mesh_3()` - \sa `CGAL::refine_mesh_3()` - \sa `CGAL::parameters::manifold_with_boundary()` - \sa `CGAL::parameters::manifold()` - */ - unspecified_type non_manifold(); - - /*! - \ingroup PkgMesh3Parameters - - The function `parameters::manifold_with_boundary()` is used to drive the - meshing algorithm for surfaces. - It ensures that the surface of the output mesh is a manifold surface which - may have boundaries. - The manifold property of the output mesh can be achieved only if the input surface - is a manifold. - Note that the meshing algorithm provably terminates only if the input - sharp edges have been protected, using the - feature protection (see \ref Mesh_3Protectionof0and1dimensionalExposed). - - \sa `CGAL::make_mesh_3()` - \sa `CGAL::refine_mesh_3()` - \sa `CGAL::parameters::non_manifold()` - \sa `CGAL::parameters::manifold()` - */ - unspecified_type manifold_with_boundary(); +/*! + * \ingroup PkgMesh3Parameters + * + * The function `parameters::manifold()` is used to drive the + * meshing algorithm for surfaces. + * It ensures that the surface of the output mesh is a manifold surface + * without boundaries. + * The manifold property of the output mesh can be achieved only if the input surface + * is a manifold. + * Note that the meshing algorithm provably terminates only if the input + * sharp edges have been protected, using the + * feature protection (see \ref Mesh_3Protectionof0and1dimensionalExposed). + * + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * \sa `CGAL::parameters::manifold_with_boundary()` + * \sa `CGAL::parameters::non_manifold()` + */ +unspecified_type manifold(); /*! -\ingroup PkgMesh3Parameters - -The function `parameters::exude()` allows the user to trigger a call to `exude_mesh_3()` in the -`make_mesh_3()` and `refine_mesh_3()` mesh generation functions. -It also allows the user to pass parameters -to the optimization function `exude_mesh_3()` through these mesh generation functions. - -\cgalHeading{Parameters} - -The parameters are named parameters. They are the same (i.e.\ they have the same -name and the same default values) as the parameters of `exude_mesh_3()` -function. See its manual page for further details. - -\cgalHeading{Example} - -\code{.cpp} -// Mesh generation with an exudation step -C3t3 c3t3 = make_mesh_3(domain, - criteria, - parameters::exude()); - -refine_mesh_3(c3t3, - domain, - criteria, - parameters::exude(parameters::time_limit=10)); -\endcode - -\sa `CGAL::parameters::no_exude()` -\sa `CGAL::exude_mesh_3()` -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` - -*/ -unspecified_type exude( - double parameters::time_limit = 0, - double parameters::sliver_bound = 0); + * \ingroup PkgMesh3Parameters + * + * The function `parameters::non_manifold()` is used to drive the + * meshing algorithm for surfaces. + * It does not ensure that the surface of the output mesh is a manifold surface. + * The manifold property of the output mesh might nevertheless result from an appropriate + * choice of meshing criteria. + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * \sa `CGAL::parameters::manifold_with_boundary()` + * \sa `CGAL::parameters::manifold()` + */ +unspecified_type non_manifold(); /*! -\ingroup PkgMesh3Parameters + * \ingroup PkgMesh3Parameters + * + * The function `parameters::manifold_with_boundary()` is used to drive the + * meshing algorithm for surfaces. + * It ensures that the surface of the output mesh is a manifold surface which + * may have boundaries. + * The manifold property of the output mesh can be achieved only if the input surface + * is a manifold. + * Note that the meshing algorithm provably terminates only if the input + * sharp edges have been protected, using the + * feature protection (see \ref Mesh_3Protectionof0and1dimensionalExposed). + * + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * \sa `CGAL::parameters::non_manifold()` + * \sa `CGAL::parameters::manifold()` + */ +unspecified_type manifold_with_boundary(); -The function `parameters::features()` can be used to specify -that 0 and 1-dimensional features have to be taken into account. -The provided value is a default value that triggers the representation -of corners and curves in the mesh when the domain is a model -of `MeshDomainWithFeatures_3`. +/*! + * \ingroup PkgMesh3Parameters + * + * The function `parameters::exude()` allows the user to trigger a call to `exude_mesh_3()` in the + * `make_mesh_3()` and `refine_mesh_3()` mesh generation functions. + * It also allows the user to pass parameters + * to the optimization function `exude_mesh_3()` through these mesh generation functions. + * + * @tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" + * @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: + * + * \cgalNamedParamsBegin + * \cgalParamNBegin{time_limit} + * \cgalParamDescription{is used to set up, in seconds, a CPU time limit after which the optimization process + * is stopped. This time is measured using the `Real_timer` class. The default value is + * 0 and means that there is no time limit.} + * \cgalParamType{`double`} + * \cgalParamPrecondition{`time_limit >= 0`} + * \cgalParamDefault{0} + * \cgalParamNEnd + * \cgalParamNBegin{sliver_bound} + * \cgalParamDescription{is designed to give, in degrees, a targeted lower bound on dihedral angles of mesh cells. + * The exudation process considers in turn all the mesh cells that have a smallest dihedral + * angle less than sliver_bound and tries to make them disappear by weighting their vertices. + * The optimization process stops when every cell in the mesh achieves this quality. The + * default value is 0 and means that there is no targeted bound: the exuder then runs as long + * as it can improve the smallest dihedral angles of the set of cells incident to some vertices.} + * \cgalParamType{`double`} + * \cgalParamPrecondition{`0 <= sliver_bound <= 180`} + * \cgalParamDefault{0} + * \cgalParamNEnd + * \cgalNamedParamsEnd + * + * \cgalHeading{Example} + * + * \code{.cpp} + * // Mesh generation with an exudation step + * C3t3 c3t3 = make_mesh_3(domain, + * criteria, + * parameters::exude()); + * + * refine_mesh_3(c3t3, + * domain, + * criteria, + * parameters::exude(parameters::time_limit=10)); + * \endcode + * + * \sa `CGAL::parameters::no_exude()` + * \sa `CGAL::exude_mesh_3()` + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * + */ +template +unspecified_type exude(const Named_function_parameters& np = parameters::default_values()); -Provides a `Features_options` value such that -0 and 1-dimensional input features are taken into account -if domain is a model of the refined concept `MeshDomainWithFeatures_3`. - -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` -\sa `CGAL::parameters::no_features()` - -*/ +/*! + * \ingroup PkgMesh3Parameters + * + * The function `parameters::features()` can be used to specify + * that 0 and 1-dimensional features have to be taken into account. + * The provided value is a default value that triggers the representation + * of corners and curves in the mesh when the domain is a model + * of `MeshDomainWithFeatures_3`. + * + * Provides a `Features_options` value such that + * 0 and 1-dimensional input features are taken into account + * if domain is a model of the refined concept `MeshDomainWithFeatures_3`. + * + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * \sa `CGAL::parameters::no_features()` + * + */ unspecified_type features(); /*! -\ingroup PkgMesh3Parameters - -The function `parameters::lloyd()` allows the user to trigger a call of -`lloyd_optimize_mesh_3()` in the mesh generation functions -`make_mesh_3()` and `refine_mesh_3()`. It also allows the user to pass -parameters to the optimization function -`lloyd_optimize_mesh_3()` through these mesh generation functions. - -\cgalHeading{Parameters} - -The parameters are named parameters. They are the same (i.e.\ they have the same -name and the same default values) as the parameters of the `lloyd_optimize_mesh_3()` -function. See its manual page for further details. - -\cgalHeading{Example} - -\code{.cpp} -// Mesh generation with lloyd optimization step -C3t3 c3t3 = make_mesh_3(domain, - criteria, - parameters::lloyd()); - -refine_mesh_3(c3t3, - domain, - criteria, - parameters::lloyd(parameters::time_limit=10)); - -\endcode - -\sa `CGAL::parameters::no_lloyd()` -\sa `CGAL::lloyd_optimize_mesh_3()` -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` - -*/ -unspecified_type lloyd( -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 PkgMesh3Parameters + * + * The function `parameters::lloyd()` allows the user to trigger a call of + * `lloyd_optimize_mesh_3()` in the mesh generation functions + * `make_mesh_3()` and `refine_mesh_3()`. It also allows the user to pass + * parameters to the optimization function + * `lloyd_optimize_mesh_3()` through these mesh generation functions. + * + * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" + * + * @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: + * + * \cgalNamedParamsBegin + * \cgalParamNBegin{time_limit} + * \cgalParamDescription{to set up, in seconds, a CPU time limit after which the optimization process is stopped. + * This time is measured using `CGAL::Real_timer`. 0 means that there is no time limit.} + * \cgalParamType{`double`} + * \cgalParamPrecondition{`time_limit >= 0`} + * \cgalParamDefault{0} + * \cgalParamNEnd + * \cgalParamNBegin{max_iteration_number} + * \cgalParamDescription{limit on the number of performed iterations. 0 means that there is + * no limit on the number of performed iterations.} + * \cgalParamPrecondition{`max_iteration_number >=0`} + * \cgalParamType{`int`} + * \cgalParamDefault{0} + * \cgalParamNEnd + * \cgalParamNBegin{freeze_bound} + * \cgalParamDescription{designed to reduce running time of each optimization iteration. + * Any vertex that has a displacement less than a given fraction of the length + * of its shortest incident edge, is frozen (i.e.\ is not relocated). + * The parameter `freeze_bound` gives the threshold ratio. + * If it is set to 0, freezing of vertices is disabled.} + * \cgalParamPrecondition{`0<= freeze_bound <=1`} + * \cgalParamType{`double`} + * \cgalParamDefault{0.001} + * \cgalParamNEnd + * \cgalParamNBegin{convergence} + * \cgalParamDescription{threshold ratio of stopping criterion based on convergence: the optimization process is stopped + * when at the last iteration the displacement of any vertex is less than + * a given fraction of the length of the shortest edge incident to that vertex.} + * \cgalParamPrecondition{`0 <=convergence <= 1`} + * \cgalParamType{`double`} + * \cgalParamDefault{0.02} + * \cgalParamNEnd + * \cgalParamNBegin{do_freeze} + * \cgalParamDescription{completes the `freeze_bound` parameter. If it is set to `true` (default value), + * frozen vertices will not move anymore in next iterations. Otherwise, at each iteration, any vertex that + * moves, unfreezes all its incident vertices.} + * \cgalParamType{`bool`} + * \cgalParamDefault{true} + * \cgalParamNEnd + * \cgalNamedParamsEnd + * + * \cgalHeading{Example} + * + * \code{.cpp} + * // Mesh generation with lloyd optimization step + * C3t3 c3t3 = make_mesh_3(domain, + * criteria, + * parameters::lloyd()); + * + * refine_mesh_3(c3t3, + * domain, + * criteria, + * parameters::lloyd(parameters::time_limit=10)); + * + * \endcode + * + * \sa `CGAL::parameters::no_lloyd()` + * \sa `CGAL::lloyd_optimize_mesh_3()` + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * + */ +template +unspecified_type lloyd(const Named_function_parameters& np = parameters::default_values()); /*! -\ingroup PkgMesh3Parameters - -The function `parameters::no_exude()` allows the user to tell the mesh generation functions -`make_mesh_3()` and `refine_mesh_3()` that no exudation must be done. - -\cgalHeading{Example} - -\code{.cpp} -// Mesh generation without exudation -C3t3 c3t3 = make_mesh_3(domain, - criteria, - parameters::no_exude()); -\endcode - -\sa `CGAL::parameters::exude()` -\sa `CGAL::exude_mesh_3()` -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` - -*/ + * \ingroup PkgMesh3Parameters + * + * The function `parameters::no_exude()` allows the user to tell the mesh generation functions + * `make_mesh_3()` and `refine_mesh_3()` that no exudation must be done. + * + * \cgalHeading{Example} + * + * \code{.cpp} + * // Mesh generation without exudation + * C3t3 c3t3 = make_mesh_3(domain, + * criteria, + * parameters::no_exude()); + * \endcode + * + * \sa `CGAL::parameters::exude()` + * \sa `CGAL::exude_mesh_3()` + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * + */ unspecified_type no_exude(); /*! -\ingroup PkgMesh3Parameters - -The function `parameters::no_features()` allows the user to prevent the handling -of 0 and 1-dimensional features. This is useful when the -domain is a model of `MeshDomainWithFeatures_3` -and the user does not want corners and curves -to be accurately represented -in the mesh. - -Returns a `Features_options` value that prevents the mesh generator -to take into account 0 and 1-dimensional input features. - -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` -\sa `CGAL::parameters::features()` - -*/ + * \ingroup PkgMesh3Parameters + * + * The function `parameters::no_features()` allows the user to prevent the handling + * of 0 and 1-dimensional features. This is useful when the + * domain is a model of `MeshDomainWithFeatures_3` + * and the user does not want corners and curves + * to be accurately represented + * in the mesh. + * + * Returns a `Features_options` value that prevents the mesh generator + * to take into account 0 and 1-dimensional input features. + * + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * \sa `CGAL::parameters::features()` + * + */ unspecified_type no_features(); /*! -\ingroup PkgMesh3Parameters - -The function `parameters::no_lloyd()` allows the user to tell the mesh generation functions -`make_mesh_3()` and `refine_mesh_3()` that no lloyd optimization must be done. - -\cgalHeading{Example} - -\code{.cpp} -// Mesh generation without lloyd optimization -C3t3 c3t3 = make_mesh_3(domain, - criteria, - parameters::no_lloyd()); -\endcode - -\sa `CGAL::parameters::lloyd()` -\sa `CGAL::lloyd_optimize_mesh_3()` -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` - -*/ + * \ingroup PkgMesh3Parameters + * + * The function `parameters::no_lloyd()` allows the user to tell the mesh generation functions + * `make_mesh_3()` and `refine_mesh_3()` that no lloyd optimization must be done. + * + * \cgalHeading{Example} + * + * \code{.cpp} + * // Mesh generation without lloyd optimization + * C3t3 c3t3 = make_mesh_3(domain, + * criteria, + * parameters::no_lloyd()); + * \endcode + * + * \sa `CGAL::parameters::lloyd()` + * \sa `CGAL::lloyd_optimize_mesh_3()` + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * + */ unspecified_type no_lloyd(); /*! -\ingroup PkgMesh3Parameters - -The function `parameters::no_odt()` allows the user to tell the mesh generation functions -`make_mesh_3()` and `refine_mesh_3()` that no odt optimization must be done. - -\cgalHeading{Example} - -\code{.cpp} -// Mesh generation without odt optimization -C3t3 c3t3 = make_mesh_3(domain, - criteria, - parameters::no_odt()); -\endcode - -\sa `CGAL::parameters::odt()` -\sa `CGAL::odt_optimize_mesh_3()` -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` - -*/ + * \ingroup PkgMesh3Parameters + * + * The function `parameters::no_odt()` allows the user to tell the mesh generation functions + * `make_mesh_3()` and `refine_mesh_3()` that no odt optimization must be done. + * + * \cgalHeading{Example} + * + * \code{.cpp} + * // Mesh generation without odt optimization + * C3t3 c3t3 = make_mesh_3(domain, + * criteria, + * parameters::no_odt()); + * \endcode + * + * \sa `CGAL::parameters::odt()` + * \sa `CGAL::odt_optimize_mesh_3()` + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * + */ unspecified_type no_odt(); /*! -\ingroup PkgMesh3Parameters - -The function `parameters::no_perturb()` allows the user to tell mesh generation global functions -`make_mesh_3()` and `refine_mesh_3()` that no perturbation must be done. - -\cgalHeading{Example} - -\code{.cpp} -// Mesh generation without perturbation -C3t3 c3t3 = make_mesh_3(domain, - criteria, - parameters::no_perturb()); -\endcode - -\sa `CGAL::parameters::perturb()` -\sa `CGAL::perturb_mesh_3()` -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` - -*/ + * \ingroup PkgMesh3Parameters + * + * The function `parameters::no_perturb()` allows the user to tell mesh generation global functions + * `make_mesh_3()` and `refine_mesh_3()` that no perturbation must be done. + * + * \cgalHeading{Example} + * + * \code{.cpp} + * // Mesh generation without perturbation + * C3t3 c3t3 = make_mesh_3(domain, + * criteria, + * parameters::no_perturb()); + * \endcode + * + * \sa `CGAL::parameters::perturb()` + * \sa `CGAL::perturb_mesh_3()` + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * + */ unspecified_type no_perturb(); /*! -\ingroup PkgMesh3Parameters - -The function `parameters::odt()` allows the user to trigger a call to -`CGAL::odt_optimize_mesh_3()` in -`CGAL::make_mesh_3()` and `CGAL::refine_mesh_3()` mesh optimization functions. It also -allows the user to pass parameters to the optimization function -`odt_optimize_mesh_3()` through these mesh generation functions. - -\cgalHeading{Parameters} - -The parameters are named parameters. They are the same (i.e.\ they have the same -name and the same default values) as the parameters of `odt_optimize_mesh_3()` -function. See its manual page for further details. - -\cgalHeading{Example} - -\code{.cpp} -// Mesh generation with odt optimization step -C3t3 c3t3 = make_mesh_3(domain, - criteria, - parameters::odt()); - -refine_mesh_3(c3t3, - domain, - criteria, - parameters::odt(parameters::time_limit=10)); -\endcode - -\sa `CGAL::parameters::no_odt()` -\sa `CGAL::odt_optimize_mesh_3()` -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` - -*/ -unspecified_type odt( -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 PkgMesh3Parameters + * + * The function `parameters::odt()` allows the user to trigger a call to + * `CGAL::odt_optimize_mesh_3()` in + * `CGAL::make_mesh_3()` and `CGAL::refine_mesh_3()` mesh optimization functions. It also + * allows the user to pass parameters to the optimization function + * `odt_optimize_mesh_3()` through these mesh generation functions. + * + * @tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" + * + * @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: + * + * \cgalNamedParamsBegin + * \cgalParamNBegin{time_limit} + * \cgalParamDescription{is used to set up, in seconds, + * a CPU time limit after which the optimization process is stopped. This time is + * measured using `Real_timer`. + * The default value is 0 and means that there is no time limit.} + * \cgalParamType{`double`} + * \cgalParamPrecondition{`time_limit >= 0`} + * \cgalParamDefault{0} + * \cgalParamNEnd + * \cgalParamNBegin{max_iteration_number} + * \cgalParamDescription{sets a limit on the number of performed iterations. + * The default value of 0 means that there is + * no limit on the number of performed iterations.} + * \cgalParamType{`std::size_t`} + * \cgalParamDefault{0} + * \cgalParamNEnd + * \cgalParamNBegin{convergence} + * \cgalParamDescription{is a stopping criterion based on convergence: + * the optimization process is stopped, when at the last iteration, + * the displacement of any vertex is less than a given percentage of the length + * the shortest edge incident to that vertex. + * The parameter `convergence` gives the threshold ratio.} + * \cgalParamType{`double`} + * \cgalParamPrecondition{`0 <= convergence <= 1`} + * \cgalParamDefault{0.02} + * \cgalParamNEnd + * \cgalParamNBegin{freeze_bound} + * \cgalParamDescription{is designed to reduce running time of each optimization iteration. Any vertex + * that has a displacement less than a given percentage of the length of its shortest incident edge, is frozen (i.e.\ is + * not relocated). The parameter `freeze_bound` gives the threshold ratio.} + * \cgalParamType{`double`} + * \cgalParamPrecondition{`0 <= freeze_bound <= 1`} + * \cgalParamDefault{0.01} + * \cgalParamNEnd + * \cgalParamNBegin{do_freeze} + * \cgalParamDescription{completes the `freeze_bound` parameter. If it is set to `true`, + * frozen vertices will not move anymore in next iterations. Otherwise, at each iteration, any vertex that + * moves, unfreezes all its incident vertices.} + * \cgalParamType{`bool`} + * \cgalParamDefault{true} + * \cgalParamNEnd + * \cgalNamedParamsEnd + * + * \cgalHeading{Example} + * + * \code{.cpp} + * // Mesh generation with odt optimization step + * C3t3 c3t3 = make_mesh_3(domain, + * criteria, + * parameters::odt()); + * + * refine_mesh_3(c3t3, + * domain, + * criteria, + * parameters::odt(parameters::time_limit=10)); + * \endcode + * + * \sa `CGAL::parameters::no_odt()` + * \sa `CGAL::odt_optimize_mesh_3()` + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * + */ +template +unspecified_type odt(const Named_function_parameters& np = parameters::default_values()); /*! -\ingroup PkgMesh3Parameters - -The function `parameters::perturb()` allows the user to trigger a call to -`perturb_mesh_3()` in -`make_mesh_3()` and `refine_mesh_3()` mesh generation functions. It also -allows the user to pass parameters -to the optimization function `perturb_mesh_3()` through these mesh generation functions. - -\cgalHeading{Parameters} - -The parameters are named parameters. They are the same (i.e.\ they have the same -name and the same default values) as the parameters of `perturb_mesh_3()` -function. See its manual page for further details. - -\cgalHeading{Example} - -\code{.cpp} -// Mesh generation with a perturbation step -C3t3 c3t3 = make_mesh_3(domain, - criteria, - parameters::perturb()); - -refine_mesh_3(c3t3, - domain, - criteria, - parameters::perturb(parameters::time_limit=10)); - -\endcode - -\sa `CGAL::parameters::no_perturb()` -\sa `CGAL::perturb_mesh_3()` -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` - -*/ -unspecified_type perturb( - double parameters::time_limit = 0, - double parameters::sliver_bound = 0); + * \ingroup PkgMesh3Parameters + * + * The function `parameters::perturb()` allows the user to trigger a call to + * `perturb_mesh_3()` in + * `make_mesh_3()` and `refine_mesh_3()` mesh generation functions. It also + * allows the user to pass parameters + * to the optimization function `perturb_mesh_3()` through these mesh generation functions. + * + * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" + * + * @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: + * + * \cgalNamedParamsBegin + * \cgalParamNBegin{time_limit} + * \cgalParamDescription{is used to set up, in seconds, a CPU time limit after which the optimization process + * is stopped. This time is measured using the `Real_timer` class. The default value is + * 0 and means that there is no time limit.} + * \cgalParamType{`double`} + * \cgalParamPrecondition{`0 <= sliver_bound <= 180`} + * \cgalParamDefault{0} + * \cgalParamNEnd + * \cgalParamNBegin{sliver_bound} + * \cgalParamDescription{is designed to give, in degrees, a targeted lower bound on dihedral angles of mesh cells. + * The exudation process considers in turn all the mesh cells that have a smallest dihedral + * angle less than sliver_bound and tries to make them disappear by weighting their vertices. + * The optimization process stops when every cell in the mesh achieves this quality. The + * default value is 0 and means that there is no targeted bound: the exuder then runs as long + * as it can improve the smallest dihedral angles of the set of cells incident to some vertices.} + * \cgalParamType{`double`} + * \cgalParamPrecondition{`time_limit >= 0`} + * \cgalParamDefault{0} + * \cgalParamNEnd + * \cgalNamedParamsEnd + * + * \cgalHeading{Example} + * + * \code{.cpp} + * // Mesh generation with a perturbation step + * C3t3 c3t3 = make_mesh_3(domain, + * criteria, + * parameters::perturb()); + * + * refine_mesh_3(c3t3, + * domain, + * criteria, + * parameters::perturb(parameters::time_limit=10)); + * + * \endcode + * + * \sa `CGAL::parameters::no_perturb()` + * \sa `CGAL::perturb_mesh_3()` + * \sa `CGAL::make_mesh_3()` + * \sa `CGAL::refine_mesh_3()` + * + */ +template +unspecified_type perturb(const Named_function_parameters& np = parameters::default_values()); } /* namespace parameters */ diff --git a/Mesh_3/include/CGAL/Mesh_3/parameters.h b/Mesh_3/include/CGAL/Mesh_3/parameters.h index ddb0804b466..15184d651b8 100644 --- a/Mesh_3/include/CGAL/Mesh_3/parameters.h +++ b/Mesh_3/include/CGAL/Mesh_3/parameters.h @@ -153,9 +153,60 @@ struct Mesh_3_options { }; // end struct Mesh_3_options +// Features +struct Features_options +{ + Features_options(bool b) : b_(b) {} + bool features() const { return b_; } +private: + bool b_; +}; + +// ----------------------------------- +// Features generator +// ----------------------------------- +// struct Features_option_generator +template +struct Features_options_generator {}; + +template<> +struct Features_options_generator +{ + Features_options operator()() { return Features_options(true); } +}; + +template<> +struct Features_options_generator +{ + Features_options operator()() { return Features_options(false); } +}; + +// struct Domain_features_generator is designed to handle cases where +// MeshDomain::Has_features is not a valid type +template< typename MeshDomain, bool MeshDomainHasHasFeatures > +struct Domain_features_generator {}; + +template< typename MeshDomain > +struct Domain_features_generator< MeshDomain, false > +{ + Features_options operator()() + { + return Features_options_generator()(); + } +}; + +template< typename MeshDomain > +struct Domain_features_generator< MeshDomain, true > +{ + Features_options operator()() + { + return Features_options_generator()(); + } +}; + } // end namespace internal -// Undocumented Boost parameter for refine_mesh_3 and make_mesh_3. +// Undocumented parameter for refine_mesh_3 and make_mesh_3. // Default Mesh_3_options: dump at every stage of the mesh generation. inline internal::Mesh_3_options mesh_3_dump() { @@ -170,14 +221,15 @@ inline internal::Mesh_3_options mesh_3_dump() return options; } - template - struct Base - { - Base(T t) : t_(t) {} - T operator()() const { return t_; } - private: - T t_; - }; + +template +struct Base +{ + Base(T t) : t_(t) {} + T operator()() const { return t_; } +private: + T t_; +}; // ----------------------------------- // Reset_c3t3 (undocumented) @@ -200,7 +252,8 @@ CGAL_BOOLEAN_PARAMETER(Reset,reset_c3t3,no_reset_c3t3) // Perturb // ----------------------------------- template -Named_function_parameters perturb(const CGAL_NP_CLASS& np = parameters::default_values()) +Named_function_parameters +perturb(const CGAL_NP_CLASS& np = parameters::default_values()) { using parameters::choose_parameter; using parameters::get_parameter; @@ -218,23 +271,38 @@ Named_function_parameters -Named_function_parameters perturb(const CGAL_NP_CLASS& ... nps) +Named_function_parameters +perturb(const CGAL_NP_CLASS& ... nps) { return perturb(internal_np::combine_named_parameters(nps...)); } -inline Named_function_parameters no_perturb() +inline Named_function_parameters +no_perturb() { typedef Named_function_parameters Param; return Param(internal::Perturb_options(false)); } +#ifndef CGAL_NO_DEPRECATED_CODE +CGAL_DEPRECATED +inline +Named_function_parameters +perturb(double time_limit_, + double sliver_bound_=0) +{ + return perturb(time_limit(time_limit_). + sliver_bound(sliver_bound_)); +} +#endif + // ----------------------------------- // Exude // ----------------------------------- template -Named_function_parameters exude(const CGAL_NP_CLASS& np = parameters::default_values()) +Named_function_parameters +exude(const CGAL_NP_CLASS& np = parameters::default_values()) { using parameters::choose_parameter; using parameters::get_parameter; @@ -252,22 +320,36 @@ Named_function_parameters -Named_function_parameters exude(const CGAL_NP_CLASS& ... nps) +Named_function_parameters +exude(const CGAL_NP_CLASS& ... nps) { return exude(internal_np::combine_named_parameters(nps...)); } -inline Named_function_parameters no_exude() +inline Named_function_parameters +no_exude() { typedef Named_function_parameters Param; return Param(internal::Exude_options(false)); } +#ifndef CGAL_NO_DEPRECATED_CODE +CGAL_DEPRECATED +inline +Named_function_parameters +exude(double time_limit_, + double sliver_bound_ = 0) +{ + return exude(time_limit(time_limit_).sliver_bound(sliver_bound_)); +} +#endif + // ----------------------------------- // Odt // ----------------------------------- template -Named_function_parameters odt(const CGAL_NP_CLASS& np = parameters::default_values()) +Named_function_parameters +odt(const CGAL_NP_CLASS& np = parameters::default_values()) { using parameters::choose_parameter; using parameters::get_parameter; @@ -286,22 +368,43 @@ Named_function_parameters -Named_function_parameters odt(const CGAL_NP_CLASS& ... nps) +Named_function_parameters +odt(const CGAL_NP_CLASS& ... nps) { return odt(internal_np::combine_named_parameters(nps...)); } -inline Named_function_parameters no_odt() +inline Named_function_parameters +no_odt() { typedef Named_function_parameters Param; return Param(internal::Odt_options(false)); } +#ifndef CGAL_NO_DEPRECATED_CODE +CGAL_DEPRECATED +inline +Named_function_parameters +odt(double time_limit_, + std::size_t max_iteration_number_ = 0, + double convergence_ = 0.02, + double freeze_bound_ = 0.01, + bool do_freeze_ = true) +{ + return odt(time_limit(time_limit_). + max_iteration_number(max_iteration_number_). + convergence(convergence_). + freeze_bound(freeze_bound_). + do_freeze(do_freeze_)); +} +#endif + // ----------------------------------- // Lloyd // ----------------------------------- template -Named_function_parameters lloyd(const CGAL_NP_CLASS& np = parameters::default_values()) +Named_function_parameters +lloyd(const CGAL_NP_CLASS& np = parameters::default_values()) { using parameters::choose_parameter; using parameters::get_parameter; @@ -320,24 +423,44 @@ Named_function_parameters -Named_function_parameters lloyd(const CGAL_NP_CLASS& ... nps) +Named_function_parameters +lloyd(const CGAL_NP_CLASS& ... nps) { return lloyd(internal_np::combine_named_parameters(nps...)); } -inline Named_function_parameters no_lloyd() +inline Named_function_parameters +no_lloyd() { typedef Named_function_parameters Param; return Param(internal::Lloyd_options(false)); } +#ifndef CGAL_NO_DEPRECATED_CODE +CGAL_DEPRECATED +inline +Named_function_parameters +lloyd(double time_limit_, + std::size_t max_iteration_number_ = 0, + double convergence_ = 0.02, + double freeze_bound_ = 0.01, + bool do_freeze_= true) +{ + return lloyd(time_limit(time_limit_). + max_iteration_number(max_iteration_number_). + convergence(convergence_). + freeze_bound(freeze_bound_). + do_freeze(do_freeze_)); +} +#endif + // ----------------------------------- -// Manifold options ------------------ +// Manifold options // ----------------------------------- template -Named_function_parameters manifold_options(const CGAL_NP_CLASS& np = parameters::default_values()) +Named_function_parameters +manifold_options(const CGAL_NP_CLASS& np = parameters::default_values()) { using parameters::choose_parameter; using parameters::get_parameter; @@ -351,23 +474,27 @@ Named_function_parameters -Named_function_parameters manifold_options(const CGAL_NP_CLASS& ... nps) +Named_function_parameters +manifold_options(const CGAL_NP_CLASS& ... nps) { return manifold_options(internal_np::combine_named_parameters(nps...)); } -inline Named_function_parameters manifold() +inline Named_function_parameters +manifold() { typedef Named_function_parameters Param; return Param(internal::Manifold_options(internal::Manifold_options::MANIFOLD)); } -inline Named_function_parameters manifold_with_boundary() +inline Named_function_parameters +manifold_with_boundary() { typedef Named_function_parameters Param; return Param(internal::Manifold_options( internal::Manifold_options::MANIFOLD_WITH_BOUNDARY)); } -inline Named_function_parameters non_manifold() +inline Named_function_parameters +non_manifold() { typedef Named_function_parameters Param; return Param(internal::Manifold_options(internal::Manifold_options::NON_MANIFOLD)); @@ -377,12 +504,13 @@ inline Named_function_parameters -Named_function_parameters mesh_3_options(const CGAL_NP_CLASS& np = parameters::default_values()) +Named_function_parameters +mesh_3_options(const CGAL_NP_CLASS& np = parameters::default_values()) { using parameters::choose_parameter; using parameters::get_parameter; @@ -408,11 +536,37 @@ Named_function_parameters m } template -Named_function_parameters mesh_3_options(const CGAL_NP_CLASS& ... nps) +Named_function_parameters +mesh_3_options(const CGAL_NP_CLASS& ... nps) { return mesh_3_options(internal_np::combine_named_parameters(nps...)); } +// ----------------------------------- +// Features_options +// ----------------------------------- +inline Named_function_parameters +features() { + typedef Named_function_parameters Param; + return Param(internal::Features_options(true)); +} + +inline Named_function_parameters +no_features() { + typedef Named_function_parameters Param; + return Param(internal::Features_options(false)); } + +template < typename MeshDomain > +inline Named_function_parameters +features(const MeshDomain& /*domain*/) +{ +typedef typename internal::Domain_features_generator< + MeshDomain, + CGAL::Mesh_3::internal::has_Has_features::value > Generator; + +typedef Named_function_parameters Param; +return Param(Generator()()); +} } } //namespace CGAL::parameters diff --git a/Mesh_3/include/CGAL/make_mesh_3.h b/Mesh_3/include/CGAL/make_mesh_3.h index a4694082222..6ebd6ab8166 100644 --- a/Mesh_3/include/CGAL/make_mesh_3.h +++ b/Mesh_3/include/CGAL/make_mesh_3.h @@ -34,89 +34,6 @@ namespace CGAL { -namespace parameters { - namespace internal { - // Features - struct Features_options - { - Features_options(bool b) : b_(b) {} - bool features() const { return b_; } - private: - bool b_; - }; - - // ----------------------------------- - // Features generator - // ----------------------------------- - // struct Features_option_generator - template - struct Features_options_generator {}; - - template<> - struct Features_options_generator - { - Features_options operator()() { return Features_options(true); } - }; - - template<> - struct Features_options_generator - { - Features_options operator()() { return Features_options(false); } - }; - - // struct Domain_features_generator is designed to handle cases where - // MeshDomain::Has_features is not a valid type - template< typename MeshDomain, bool MeshDomainHasHasFeatures > - struct Domain_features_generator {}; - - template< typename MeshDomain > - struct Domain_features_generator< MeshDomain, false > - { - Features_options operator()() - { - return Features_options_generator()(); - } - }; - - template< typename MeshDomain > - struct Domain_features_generator< MeshDomain, true > - { - Features_options operator()() - { - return Features_options_generator()(); - } - }; - - } // end namespace internal - - // ----------------------------------- - // Features_options - // ----------------------------------- - inline Named_function_parameters - features() { - typedef Named_function_parameters Param; - return Param(internal::Features_options(true)); - } - - inline Named_function_parameters - no_features() { - typedef Named_function_parameters Param; - return Param(internal::Features_options(false)); } - - template < typename MeshDomain > - inline Named_function_parameters - features(const MeshDomain& /*domain*/) - { - typedef typename internal::Domain_features_generator< - MeshDomain, - CGAL::Mesh_3::internal::has_Has_features::value > Generator; - - typedef Named_function_parameters Param; - return Param(Generator()()); - } - -} // end namespace parameters::internal - // ----------------------------------- // Initialize c3t3 stuff // ----------------------------------- diff --git a/Mesh_3/include/CGAL/perturb_mesh_3.h b/Mesh_3/include/CGAL/perturb_mesh_3.h index ac6d1b338d8..c8b5d87a04e 100644 --- a/Mesh_3/include/CGAL/perturb_mesh_3.h +++ b/Mesh_3/include/CGAL/perturb_mesh_3.h @@ -48,7 +48,6 @@ namespace CGAL { * * \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 and is modified by the algorithm to represent the final optimized mesh