From 0af311c0b33753ff782e0c2d9eb8d7b3e913275b Mon Sep 17 00:00:00 2001 From: GYuvanShankar Date: Fri, 17 Jun 2022 14:30:25 +0530 Subject: [PATCH] New API support and docs for perturb_mesh_3.h --- Mesh_3/doc/Mesh_3/CGAL/perturb_mesh_3.h | 91 -------- Mesh_3/doc/Mesh_3/Doxyfile.in | 3 +- .../Mesh_3/mesh_cubes_intersection.cpp | 2 +- .../mesh_cubes_intersection_with_features.cpp | 2 +- .../examples/Mesh_3/mesh_implicit_domains.cpp | 4 +- .../Mesh_3/mesh_implicit_ellipsoid.cpp | 2 +- .../Mesh_3/mesh_optimization_example.cpp | 2 +- Mesh_3/include/CGAL/perturb_mesh_3.h | 218 +++++++++++++++--- Mesh_3/include/CGAL/refine_mesh_3.h | 4 +- .../test/Mesh_3/test_meshing_determinism.cpp | 2 +- Mesh_3/test/Mesh_3/test_meshing_utilities.h | 2 +- .../include/CGAL/refine_periodic_3_mesh_3.h | 4 +- .../include/CGAL/Named_function_parameters.h | 2 + .../internal/parameters_interface.h | 6 +- 14 files changed, 210 insertions(+), 134 deletions(-) delete mode 100644 Mesh_3/doc/Mesh_3/CGAL/perturb_mesh_3.h diff --git a/Mesh_3/doc/Mesh_3/CGAL/perturb_mesh_3.h b/Mesh_3/doc/Mesh_3/CGAL/perturb_mesh_3.h deleted file mode 100644 index 216f3d5e662..00000000000 --- a/Mesh_3/doc/Mesh_3/CGAL/perturb_mesh_3.h +++ /dev/null @@ -1,91 +0,0 @@ -namespace CGAL { - -/*! -\ingroup PkgMesh3Functions - -The function `perturb_mesh_3()` is a mesh optimizer that -improves the quality of a Delaunay mesh -by changing the positions of some vertices of the mesh. - -The perturber tries to improve the dihedral angles of the worst cells in the mesh -degree by degree: the -step number `n` is considered as successful -if after this step the worst tetrahedron of the mesh has a minimal dihedral -angle larger than `n` degrees. -The perturber exits if this is not the case. - -\pre `time_limit` \f$ \geq\f$ 0 and 0 \f$ \leq\f$ `sliver_bound` \f$ \leq\f$ 180 - -\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. - -The function has two optional parameters which are named parameters (we use the Boost.Parameter library). -Therefore, when calling the function, the parameters can be provided in any order -provided that the names of the parameters are used -(see example at the bottom of this page). - -\cgalHeading{Named Parameters} - -- `parameters::time_limit` -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. - -- `parameters::sliver_bound` -is designed to give, in degrees, a targeted -lower bound on dihedral angles of mesh cells. -The function `perturb_mesh_3()` runs as long as steps are successful -and step number `sliver_bound` (after which -the worst tetrahedron in the mesh has a smallest angle larger than -`sliver_bound` degrees) has not been reached. -The default value is 0 and means that there is no targeted bound: -the perturber then runs as long as -steps are successful. - - -\return -The function `perturb_mesh_3()` returns a value of type `CGAL::Mesh_optimization_return_code` -which is: - - - -\cgalHeading{Example} - -\code{.cpp} -// Perturb until every dihedral angle of the mesh is >= 10 degrees -// No time bound is set -perturb_mesh_3(c3t3, - domain, - parameters::sliver_bound = 10); -\endcode - -\sa `CGAL::Mesh_optimization_return_code` -\sa `CGAL::make_mesh_3()` -\sa `CGAL::refine_mesh_3()` -\sa `CGAL::exude_mesh_3()` -\sa `CGAL::lloyd_optimize_mesh_3()` -\sa `CGAL::odt_optimize_mesh_3()` - -*/ - -template -Mesh_optimization_return_code -perturb_mesh_3(C3T3& c3t3, - const MD& domain, - double parameters::time_limit=0, - double parameters::sliver_bound=0); - -} /* namespace CGAL */ diff --git a/Mesh_3/doc/Mesh_3/Doxyfile.in b/Mesh_3/doc/Mesh_3/Doxyfile.in index 307e18392de..eac8697ced5 100644 --- a/Mesh_3/doc/Mesh_3/Doxyfile.in +++ b/Mesh_3/doc/Mesh_3/Doxyfile.in @@ -9,7 +9,8 @@ INPUT += \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/Mesh_3/generate_label_weights.h \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/exude_mesh_3.h \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/odt_optimize_mesh_3.h \ - ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/lloyd_optimize_mesh_3.h + ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/lloyd_optimize_mesh_3.h \ + ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/perturb_mesh_3.h PROJECT_NAME = "CGAL ${CGAL_DOC_VERSION} - 3D Mesh Generation" HTML_EXTRA_FILES = ${CGAL_PACKAGE_DOC_DIR}/fig/implicit_domain_3.jpg \ ${CGAL_PACKAGE_DOC_DIR}/fig/implicit_domain_4.jpg \ diff --git a/Mesh_3/examples/Mesh_3/mesh_cubes_intersection.cpp b/Mesh_3/examples/Mesh_3/mesh_cubes_intersection.cpp index 6cd90e2e3fe..38f4363a04b 100644 --- a/Mesh_3/examples/Mesh_3/mesh_cubes_intersection.cpp +++ b/Mesh_3/examples/Mesh_3/mesh_cubes_intersection.cpp @@ -84,7 +84,7 @@ int main() C3t3 c3t3 = CGAL::make_mesh_3(domain, criteria, no_exude(), no_perturb()); // Perturbation (maximum cpu time: 10s, targeted dihedral angle: default) - CGAL::perturb_mesh_3(c3t3, domain, time_limit = 10); + CGAL::perturb_mesh_3(c3t3, domain, time_limit_new = 10); // Exudation CGAL::exude_mesh_3(c3t3,CGAL::parameters::time_limit_new=12); diff --git a/Mesh_3/examples/Mesh_3/mesh_cubes_intersection_with_features.cpp b/Mesh_3/examples/Mesh_3/mesh_cubes_intersection_with_features.cpp index a32b9603115..9ef132eaf23 100644 --- a/Mesh_3/examples/Mesh_3/mesh_cubes_intersection_with_features.cpp +++ b/Mesh_3/examples/Mesh_3/mesh_cubes_intersection_with_features.cpp @@ -171,7 +171,7 @@ int main() C3t3 c3t3 = CGAL::make_mesh_3(domain, criteria, no_exude(), no_perturb()); // Perturbation (maximum cpu time: 10s, targeted dihedral angle: default) - CGAL::perturb_mesh_3(c3t3, domain, time_limit = 10); + CGAL::perturb_mesh_3(c3t3, domain, time_limit_new = 10); // Exudation CGAL::exude_mesh_3(c3t3,CGAL::parameters::time_limit_new=12); diff --git a/Mesh_3/examples/Mesh_3/mesh_implicit_domains.cpp b/Mesh_3/examples/Mesh_3/mesh_implicit_domains.cpp index ad284862d75..b3adb97954d 100644 --- a/Mesh_3/examples/Mesh_3/mesh_implicit_domains.cpp +++ b/Mesh_3/examples/Mesh_3/mesh_implicit_domains.cpp @@ -60,10 +60,10 @@ int main() C3t3 c3t3 = CGAL::make_mesh_3(domain, criteria, no_exude(), no_perturb()); // Perturbation (maximum cpu time: 10s, targeted dihedral angle: default) - CGAL::perturb_mesh_3(c3t3, domain, time_limit = 10); + CGAL::perturb_mesh_3(c3t3, domain, time_limit_new = 10); // Exudation - CGAL::exude_mesh_3(c3t3,CGAL::parameters::time_limit_new=12); + CGAL::exude_mesh_3(c3t3, time_limit_new=12); // Output std::ofstream medit_file("out.mesh"); diff --git a/Mesh_3/examples/Mesh_3/mesh_implicit_ellipsoid.cpp b/Mesh_3/examples/Mesh_3/mesh_implicit_ellipsoid.cpp index 9e28374783e..4f3ee34b2e7 100644 --- a/Mesh_3/examples/Mesh_3/mesh_implicit_ellipsoid.cpp +++ b/Mesh_3/examples/Mesh_3/mesh_implicit_ellipsoid.cpp @@ -59,7 +59,7 @@ int main() medit_file.close(); // Perturbation (5s, 12degree) - CGAL::perturb_mesh_3(c3t3, domain, time_limit=5, sliver_bound=12); + CGAL::perturb_mesh_3(c3t3, domain, time_limit_new=5, sliver_bound_new=12); // Exudation CGAL::exude_mesh_3(c3t3); diff --git a/Mesh_3/examples/Mesh_3/mesh_optimization_example.cpp b/Mesh_3/examples/Mesh_3/mesh_optimization_example.cpp index 9f72d6c276a..1053b4f1d21 100644 --- a/Mesh_3/examples/Mesh_3/mesh_optimization_example.cpp +++ b/Mesh_3/examples/Mesh_3/mesh_optimization_example.cpp @@ -55,7 +55,7 @@ int main(int argc, char* argv[]) C3t3 c3t3_bis = CGAL::make_mesh_3(domain, criteria, no_perturb(), no_exude()); - CGAL::perturb_mesh_3(c3t3_bis, domain, time_limit=15); + CGAL::perturb_mesh_3(c3t3_bis, domain, time_limit_new=15); // Output std::ofstream medit_file("out.mesh"); diff --git a/Mesh_3/include/CGAL/perturb_mesh_3.h b/Mesh_3/include/CGAL/perturb_mesh_3.h index 669fad1dfb0..e09b3854b25 100644 --- a/Mesh_3/include/CGAL/perturb_mesh_3.h +++ b/Mesh_3/include/CGAL/perturb_mesh_3.h @@ -34,41 +34,108 @@ #include namespace CGAL { +/*! +\ingroup PkgMesh3Functions -#if defined(BOOST_MSVC) -# pragma warning(push) -# pragma warning(disable:4003) // not enough actual parameters for macro -#endif +The function `perturb_mesh_3()` is a mesh optimizer that +improves the quality of a Delaunay mesh +by changing the positions of some vertices of the mesh. -// see -CGAL_PRAGMA_DIAG_PUSH -// see -CGAL_IGNORE_BOOST_PARAMETER_NAME_WARNINGS +The perturber tries to improve the dihedral angles of the worst cells in the mesh +degree by degree: the +step number `n` is considered as successful +if after this step the worst tetrahedron of the mesh has a minimal dihedral +angle larger than `n` degrees. +The perturber exits if this is not the case. -BOOST_PARAMETER_FUNCTION( - (Mesh_optimization_return_code), - perturb_mesh_3, - parameters::tag, - (required (in_out(c3t3),*) (domain,*) ) - (optional - (time_limit_, *, 0 ) - (sliver_bound_, *, parameters::default_values_for_mesh_3::perturb_sliver_bound ) - (sliver_criterion_, *, - parameters::default_values_for_mesh_3::default_sliver_criterion(c3t3,sliver_bound_)) - (perturbation_vector_, *, - default_perturbation_vector(c3t3,domain,sliver_criterion_)) - ) -) +\pre `time_limit` \f$ \geq\f$ 0 and 0 \f$ \leq\f$ `sliver_bound` \f$ \leq\f$ 180 + +\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 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 ... + @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: + + \cgalNamedParamsBegin + \cgalParamNBegin{time_limit_new} + \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`} + \cgalParamDefault{0} + \cgalParamNBegin{sliver_bound_new} + \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`} + \cgalParamDefault{0} +\cgalNamedParamsEnd + + +\return +The function `perturb_mesh_3()` returns a value of type `CGAL::Mesh_optimization_return_code` +which is: +
    +
  • `CGAL::BOUND_REACHED` when the targeted bound for the smallest dihedral angle in the mesh is reached. +
  • `CGAL::TIME_LIMIT_REACHED` when the time limit is reached. +
  • `CGAL::CANT_IMPROVE_ANYMORE` when the perturbation process stops because the last step is unsuccessful. +
+ + +\cgalHeading{Example} + +\code{.cpp} +// Perturb until every dihedral angle of the mesh is >= 10 degrees +// No time bound is set +perturb_mesh_3(c3t3, + domain, + parameters::sliver_bound = 10); +\endcode + +\sa `CGAL::Mesh_optimization_return_code` +\sa `CGAL::make_mesh_3()` +\sa `CGAL::refine_mesh_3()` +\sa `CGAL::exude_mesh_3()` +\sa `CGAL::lloyd_optimize_mesh_3()` +\sa `CGAL::odt_optimize_mesh_3()` + +*/ + + +template +Mesh_optimization_return_code perturb_mesh_3(C3T3& c3t3, MeshDomain& domain, const CGAL_NP_CLASS& np = parameters::default_values()) { - CGAL_USE(sliver_bound_); - return perturb_mesh_3_impl(c3t3, domain, time_limit_, sliver_criterion_, - perturbation_vector_); + using parameters::choose_parameter; + using parameters::get_parameter; + double time_limit = choose_parameter(get_parameter(np,internal_np::maximum_running_time),0); + auto sliver_bound = choose_parameter(get_parameter(np,internal_np::lower_sliver_bound), parameters::default_values_for_mesh_3::perturb_sliver_bound); + auto sliver_criterion = choose_parameter(get_parameter(np, internal_np::sliver_criteria), parameters::default_values_for_mesh_3::default_sliver_criterion(c3t3,sliver_bound)); + auto perturbation_vector = choose_parameter(get_parameter(np,internal_np::perturb_vector), default_perturbation_vector(c3t3,domain,sliver_criterion)); + return perturb_mesh_3_impl(c3t3, domain, time_limit, sliver_criterion, perturbation_vector); } -CGAL_PRAGMA_DIAG_POP -#if defined(BOOST_MSVC) -# pragma warning(pop) -#endif +#ifndef DOXYGEN_RUNNING +#ifndef CGAL_NO_DEPRECATED_CODE + template + Mesh_optimization_return_code perturb_mesh_3(C3T3& c3t3, MeshDomain& domain, const NP_PACK& ... nps) + { + return perturb_mesh_3(c3t3,domain, internal_np::combine_named_parameters(nps...)); + } +#endif //CGAL_NO_DEPRECATED_CODE template `parameters::time_limit` +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. + +- `parameters::sliver_bound` +is designed to give, in degrees, a targeted +lower bound on dihedral angles of mesh cells. +The function `perturb_mesh_3()` runs as long as steps are successful +and step number `sliver_bound` (after which +the worst tetrahedron in the mesh has a smallest angle larger than +`sliver_bound` degrees) has not been reached. +The default value is 0 and means that there is no targeted bound: +the perturber then runs as long as +steps are successful. +\return +The function `perturb_mesh_3()` returns a value of type `CGAL::Mesh_optimization_return_code` +which is: +
    +
  • `CGAL::BOUND_REACHED` when the targeted bound for the smallest dihedral angle in the mesh is reached. +
  • `CGAL::TIME_LIMIT_REACHED` when the time limit is reached. +
  • `CGAL::CANT_IMPROVE_ANYMORE` when the perturbation process stops because the last step is unsuccessful. +
+ + +\cgalHeading{Example} + +\code{.cpp} +// Perturb until every dihedral angle of the mesh is >= 10 degrees +// No time bound is set +perturb_mesh_3(c3t3, + domain, + parameters::sliver_bound = 10); +\endcode + +\sa `CGAL::Mesh_optimization_return_code` +\sa `CGAL::make_mesh_3()` +\sa `CGAL::refine_mesh_3()` +\sa `CGAL::exude_mesh_3()` +\sa `CGAL::lloyd_optimize_mesh_3()` +\sa `CGAL::odt_optimize_mesh_3()` + +*/ + +template +Mesh_optimization_return_code +perturb_mesh_3(C3T3& c3t3, + const MD& domain, + double parameters::time_limit=0, + double parameters::sliver_bound=0); + +} /* namespace CGAL */ + +#endif //DOXYGEN_RUNNING } //namespace CGAL diff --git a/Mesh_3/include/CGAL/refine_mesh_3.h b/Mesh_3/include/CGAL/refine_mesh_3.h index cc441aba124..1c0e5f2035d 100644 --- a/Mesh_3/include/CGAL/refine_mesh_3.h +++ b/Mesh_3/include/CGAL/refine_mesh_3.h @@ -598,8 +598,8 @@ void refine_mesh_3_impl(C3T3& c3t3, perturb_mesh_3(c3t3, domain, - parameters::time_limit = perturb_time_limit, - parameters::sliver_bound = perturb.bound()); + parameters::time_limit_new = perturb_time_limit, + parameters::sliver_bound_new = perturb.bound()); dump_c3t3(c3t3, mesh_options.dump_after_perturb_prefix); } diff --git a/Mesh_3/test/Mesh_3/test_meshing_determinism.cpp b/Mesh_3/test/Mesh_3/test_meshing_determinism.cpp index 068a3e495bc..000202adef4 100644 --- a/Mesh_3/test/Mesh_3/test_meshing_determinism.cpp +++ b/Mesh_3/test/Mesh_3/test_meshing_determinism.cpp @@ -109,7 +109,7 @@ void test() oss.clear(); //PERTURB (3) - CGAL::perturb_mesh_3(c3t3, domain, sliver_bound=perturb_bound); + CGAL::perturb_mesh_3(c3t3, domain, sliver_bound_new=perturb_bound); c3t3.output_to_medit(oss); output_c3t3.push_back(oss.str());//[i*5+3] oss.clear(); diff --git a/Mesh_3/test/Mesh_3/test_meshing_utilities.h b/Mesh_3/test/Mesh_3/test_meshing_utilities.h index 159bd61f160..03a123aca35 100644 --- a/Mesh_3/test/Mesh_3/test_meshing_utilities.h +++ b/Mesh_3/test/Mesh_3/test_meshing_utilities.h @@ -164,7 +164,7 @@ struct Tester // Quality should increase C3t3 perturb_c3t3(c3t3); std::cerr << "Perturb...\n"; - CGAL::perturb_mesh_3(perturb_c3t3, domain, CGAL::parameters::time_limit=5); + CGAL::perturb_mesh_3(perturb_c3t3, domain, CGAL::parameters::time_limit_new =5); verify_c3t3(perturb_c3t3,domain,domain_type,v,v); verify_c3t3_quality(c3t3,perturb_c3t3); verify_c3t3_volume(perturb_c3t3, volume*0.95, volume*1.05); diff --git a/Periodic_3_mesh_3/include/CGAL/refine_periodic_3_mesh_3.h b/Periodic_3_mesh_3/include/CGAL/refine_periodic_3_mesh_3.h index 22a1cf99fd8..87833d80c00 100644 --- a/Periodic_3_mesh_3/include/CGAL/refine_periodic_3_mesh_3.h +++ b/Periodic_3_mesh_3/include/CGAL/refine_periodic_3_mesh_3.h @@ -284,8 +284,8 @@ void refine_periodic_3_mesh_3_impl(C3T3& c3t3, perturb_time_limit = perturb.time_limit(); perturb_mesh_3(c3t3, domain, - parameters::time_limit = perturb_time_limit, - parameters::sliver_bound = perturb.bound()); + parameters::time_limit_new = perturb_time_limit, + parameters::sliver_bound_new = perturb.bound()); dump_c3t3(c3t3, mesh_options.dump_after_perturb_prefix); } diff --git a/STL_Extension/include/CGAL/Named_function_parameters.h b/STL_Extension/include/CGAL/Named_function_parameters.h index 913def099b1..2ac35c9ec46 100644 --- a/STL_Extension/include/CGAL/Named_function_parameters.h +++ b/STL_Extension/include/CGAL/Named_function_parameters.h @@ -343,6 +343,8 @@ const Boost_parameter_compatibility_wrapper seeds_end_new; const Boost_parameter_compatibility_wrapper mark_new; const Boost_parameter_compatibility_wrapper do_freeze_new; +const Boost_parameter_compatibility_wrapper sliver_criterion_new; +const Boost_parameter_compatibility_wrapper perturbation_vector_new; //Compatibility wrappers for exude_mesh_3.h const Boost_parameter_compatibility_wrapper sliver_bound_new; #endif diff --git a/STL_Extension/include/CGAL/STL_Extension/internal/parameters_interface.h b/STL_Extension/include/CGAL/STL_Extension/internal/parameters_interface.h index 8bf45442913..a56cc034084 100644 --- a/STL_Extension/include/CGAL/STL_Extension/internal/parameters_interface.h +++ b/STL_Extension/include/CGAL/STL_Extension/internal/parameters_interface.h @@ -251,4 +251,8 @@ CGAL_add_named_parameter(i_seed_end_iterator_t, i_seed_end_iterator, i_seed_end_ //List of named parameters used in exude_mesh_3.h CGAL_add_named_parameter(lower_sliver_bound_t,lower_sliver_bound,lower_sliver_bound) -CGAL_add_named_parameter(freeze_t,freeze,freeze) \ No newline at end of file +CGAL_add_named_parameter(freeze_t,freeze,freeze) + +//List of named parameters used in perturb_mesh_3.h +CGAL_add_named_parameter(sliver_criteria_t, sliver_criteria, sliver_criteria) +CGAL_add_named_parameter(perturb_vector_t, perturb_vector, perturb_vector)