From e085a47b19fb03f425c97f380eb0b24bb1ad2f3f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Loriot?= Date: Thu, 15 Sep 2022 12:49:13 +0200 Subject: [PATCH] fix doc warnings/errors in Mesh_3 --- .../doc/Mesh_3/CGAL/Labeled_mesh_domain_3.h | 321 ------------------ .../{refine_mesh_3.h => Mesh_3/parameters.h} | 30 +- Mesh_3/doc/Mesh_3/CGAL/Mesh_criteria_3.h | 161 --------- Mesh_3/doc/Mesh_3/Doxyfile.in | 2 +- Mesh_3/include/CGAL/Labeled_mesh_domain_3.h | 117 +++++-- Mesh_3/include/CGAL/Mesh_3/parameters.h | 18 +- Mesh_3/include/CGAL/Mesh_criteria_3.h | 143 ++++++-- Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h | 2 +- Mesh_3/include/CGAL/make_mesh_3.h | 6 +- Mesh_3/include/CGAL/refine_mesh_3.h | 6 +- 10 files changed, 227 insertions(+), 579 deletions(-) delete mode 100644 Mesh_3/doc/Mesh_3/CGAL/Labeled_mesh_domain_3.h rename Mesh_3/doc/Mesh_3/CGAL/{refine_mesh_3.h => Mesh_3/parameters.h} (92%) delete mode 100644 Mesh_3/doc/Mesh_3/CGAL/Mesh_criteria_3.h diff --git a/Mesh_3/doc/Mesh_3/CGAL/Labeled_mesh_domain_3.h b/Mesh_3/doc/Mesh_3/CGAL/Labeled_mesh_domain_3.h deleted file mode 100644 index c5e547f7f6b..00000000000 --- a/Mesh_3/doc/Mesh_3/CGAL/Labeled_mesh_domain_3.h +++ /dev/null @@ -1,321 +0,0 @@ -namespace CGAL { - -/*! -\ingroup PkgMesh3Domains - -\brief The class `Labeled_mesh_domain_3` implements indexed domains. - -This class is a model of concept `MeshDomain_3`. - -Any boundary facet is labeled , with a, where b!=0. - -This class includes a labeling function that provides the index of the subdomain in which any -query point lies. An intersection between a segment and bounding -surfaces is detected when both segment endpoints are associated with different -values of subdomain indices. The intersection is then constructed by bisection. -The bisection stops when the query segment is shorter than an error bound -`e` given by the product of the -length of the diagonal of the bounding box (in world coordinates), or the radius of the bounding sphere, and -a relative error bound passed as argument to the constructor of `Labeled_mesh_domain_3`. - -This class has a constructor taking a labeling function. It has also three -static template member functions that act as named constructors: -
    -
  • `create_gray_image_mesh_domain()`, to create a domain from a 3D gray image, -
  • `create_labeled_image_mesh_domain()`, to create a domain from a 3D labeled image, and -
  • `create_implicit_mesh_domain()`, to create a domain from an implicit function. -
- -\tparam BGT is a geometric traits class that provides -the basic operations to implement -intersection tests and intersection computations -through a bisection method. This parameter must be instantiated -with a model of the concept `BisectionGeometricTraits_3`. - -\cgalHeading{Labeling function} - -A labeling function `f` must return `0` if the point isn't located in any subdomain. The return type of labeling functions is an integer. - -Let `p` be a Point. -
    -
  • `f(p)=0` means that `p` is outside domain.
    • -
  • `f(p)=a`, `a!=0` means that `p` is inside subdomain `a`.
    • -
-`CGAL::Implicit_multi_domain_to_labeling_function_wrapper` is a good candidate for this template parameter -if there are several components to mesh. - -The function type can be any model of the concept `Callable` compatible with the signature `Subdomain_index(const Point_3&)`: it can be a function, a function object, a lambda expression... that takes a `%Point_3` as argument, and returns a type convertible to `Subdomain_index`. - -\cgalModels MeshDomain_3 - -\sa `Implicit_multi_domain_to_labeling_function_wrapper` -\sa `CGAL::make_mesh_3()`. - -*/ -template -class Labeled_mesh_domain_3 -{ -public: - -/// \name Types -///@{ - -/// The subdomain index of this model of `MeshDomain_3`. -typedef int Subdomain_index; - -/// The type of object that stores the function using type-erasure -typedef std::function Labeling_function; - -///@} -/// \name Types imported from the geometric traits class -///@{ - -/// The point type of the geometric traits class -typedef typename Geom_traits::Point_3 Point_3; -/// The sphere type of the geometric traits class -typedef typename Geom_traits::Sphere_3 Sphere_3; -/// The iso-cuboid type of the geometric traits class -typedef typename Geom_traits::Iso_cuboid_3 Iso_cuboid_3; -/// The number type (a field type) of the geometric traits class -typedef typename Geom_traits::FT FT; -///@} - -/// \name Creation -/// @{ -/*! \brief Construction from a function, a bounding -object and a relative error bound. - -This constructor uses named parameters (from the Boost Parameter -Library). They can be specified in any order. - -\cgalHeading{Named Parameters} -- `parameters::function` (mandatory) the labeling function, compatible with `Labeling_function`. -- `parameters::bounding_object` (mandatory) the bounding object is either a bounding sphere (of type `Sphere_3`), a bounding box (type `Bbox_3`), or a bounding `Iso_cuboid_3`. It bounds the meshable space. -- `parameters::relative_error_bound` (optional) the relative error bound used to compute intersection points between the implicit surface and query segments. The -bisection is stopped when the length of the intersected segment is less than the product of `relative_error_bound` by the diameter of the bounding object. Its default value is `FT(1e-3)`. - -\cgalHeading{Example} -From the example (\ref Mesh_3/mesh_implicit_domains_2.cpp): -\snippet Mesh_3/mesh_implicit_domains_2.cpp Domain creation - - */ -template -Labeled_mesh_domain_3(const A_i&...); - -///@} - -/// \name Creation of domains from implicit functions - -/*! -\brief Construction from an implicit function -\deprecated This function is deprecated since \cgal 5.6, the overload using `NamedParameters` must be used instead. - -This static method is a named constructor. It constructs a domain -whose bounding surface is described implicitly as the zero level set of a -function. The domain to be discretized is assumed to be the domain where -the function has negative values. - -The method takes as argument a bounding sphere which is required to -circumscribe the surface and to have its center inside the domain. - -This constructor uses named parameters (from the Boost Parameter -Library). They can be specified in any order. - -\cgalHeading{Named Parameters} -
    -
  • `parameters::function` (mandatory) the implicit function, -compatible with the signature `FT(Point_3)`: it takes a point as argument, -and returns a scalar value. That object must be model of `CopyConstructible`. -
  • `parameters::bounding_object` (mandatory) the bounding object is -either a bounding sphere (of type `Sphere_3`), a bounding box (type -`Bbox_3`), or a bounding `Iso_cuboid_3`. It must bounds the surface, and -its center must be inside the domain. -
- -\cgalHeading{Examples} - -From the example (\ref Mesh_3/mesh_implicit_sphere.cpp), where the name of -the parameters is not specified, as they are given is the same order as the -parameters definition: - -\snippet Mesh_3/mesh_implicit_sphere.cpp Domain creation - -From the example (\ref Mesh_3/mesh_implicit_sphere_variable_size.cpp): - -\snippet Mesh_3/mesh_implicit_sphere_variable_size.cpp Domain creation - - */ -template -static -Labeled_mesh_domain_3 -create_implicit_mesh_domain(A_i&...); - -/// \name Creation of domains from 3D images - - -/*! -\brief Construction from a 3D gray image -\deprecated This function is deprecated since \cgal 5.6, the overload using `NamedParameters` must be used instead. - -This static method is a named constructor. It constructs a domain -described by a 3D gray image. A 3D gray image is a grid of voxels, -where each voxel is associated with a gray level value. Unless otherwise specified by the parameter `image_values_to_subdom_indices`, the domain to -be discretized is the union of voxels that lie inside a surface -described by an isolevel value, called \a isovalue. The voxels lying -inside the domain have gray level values that are larger than the -isovalue. - -The value of voxels is interpolated to a gray level value at any query point. - -This constructor uses named parameters (from the Boost Parameter -Library). They can be specified in any order. - -\cgalHeading{Named Parameters} -The parameters are optional unless otherwise specified. -
    - -
  • `parameters::image` (mandatory) the input 3D image. Must -be a `CGAL::Image_3` object. - -
  • `parameters::iso_value` the isovalue, inside - `image`, of the surface describing the boundary of the object to be - meshed. Its default value is `0`. - -
  • `parameters::image_values_to_subdom_indices` a function or - a function object, compatible with the signature - `Subdomain_index(double)`. This function returns the subdomain index - corresponding to a pixel value. If this parameter is used, then the - parameter `iso_value` is ignored. - -
  • `parameter::value_outside` the value attached to voxels - outside of the domain to be meshed. It should be lower than - `iso_value`. Its default value is `0`. - -
  • `parameter::relative_error_bound` is the relative error - bound, relative to the diameter of the box of the image. Its default - value is `FT(1e-3)`.
- -\cgalHeading{Examples} - -From the example (\ref Mesh_3/mesh_3D_gray_image.cpp), where the name -of the parameters is not specified, as they are given is the same -order as the parameters definition: - -\snippet Mesh_3/mesh_3D_gray_image.cpp Domain creation - -From the example (\ref Mesh_3/mesh_3D_gray_vtk_image.cpp): - -\snippet Mesh_3/mesh_3D_gray_vtk_image.cpp Domain creation - - */ -template -static -Labeled_mesh_domain_3 -create_gray_image_mesh_domain(A_i&...); - -/*! -\brief Construction from a 3D labeled image -\deprecated This function is deprecated since \cgal 5.6, the overload using `NamedParameters` must be used instead. - -This static method is a named constructor. It constructs a -domain described by a 3D labeled image. A 3D labeled image is a grid -of voxels, where each voxel is associated with an index (a subdomain -index) characterizing the subdomain in which the voxel lies. The -domain to be discretized is the union of voxels that have non-zero -values. - -This constructor uses named parameters (from the Boost Parameter -Library). They can be specified in any order. - -\cgalHeading{Named Parameters} -The parameters are optional unless otherwise specified. -
    - -
  • `parameters::image` (mandatory) the input 3D image. Must -be a `CGAL::Image_3` object. - -
  • `parameters::weights` an input 3D image that provides -weights associated to each voxel (the word type is `unsigned char`, -and the voxels values are integers between 0 and 255). -The weights image can be generated with `CGAL::Mesh_3::generate_label_weights()`. -Its dimensions must be the same as the dimensions of `parameters::image`. - -
  • `parameter::value_outside` the value attached to voxels - outside of the domain to be meshed. Its default value is `0`. - -
  • `parameter::relative_error_bound` is the relative error - bound, relative to the diameter of the box of the image. Its default - value is `FT(1e-3)`.
- -\cgalHeading{Example} - -From the example (\ref Mesh_3/mesh_3D_image.cpp): - -\snippet Mesh_3/mesh_3D_image.cpp Domain creation - -From the example (\ref Mesh_3/mesh_3D_weighted_image.cpp), -where the labeled image is used with a precomputed 3D image of weights : - -\snippet Mesh_3/mesh_3D_weighted_image.cpp Domain creation - - */ -template -static -Labeled_mesh_domain_3 -create_labeled_image_mesh_domain(A_i&...); - -/// \name Deprecated constructors -/// -/// Those three constructors have been deprecated since CGAL-4.13, and -/// replaced by the constructor using the Boost Parameter Library. -/// -/// @{ - -/*! -\brief Construction from a labeling function, a bounding Sphere and a relative error bound. -\param f the labeling function. -\param bounding_sphere the bounding sphere of the meshable space. -\param relative_error_bound is the relative error bound used to compute intersection points between the implicit surface and query segments. The -bisection is stopped when the length of the intersected segment is less than the product of `relative_error_bound` by the radius of -`bounding_sphere`. -\deprecated This constructor is deprecated since CGAL-4.13, and -replaced by the constructor using the Boost Parameter Library. -*/ -Labeled_mesh_domain_3(Labeling_function f, - const Sphere_3& bounding_sphere, - const FT& relative_error_bound = FT(1e-3)); - -/*! -\brief Construction from a labeling function, a bounding box and a relative error bound. -\param f the labeling function. -\param bbox the bounding box of the meshable space. -\param relative_error_bound is the relative error bound used to compute intersection points between the implicit surface and query segments. The -bisection is stopped when the length of the intersected segment is less than the product of `relative_error_bound` by the diagonal of -`bounding_box`. -\deprecated This constructor is deprecated since CGAL-4.13, and -replaced by the constructor using the Boost Parameter Library. -*/ -Labeled_mesh_domain_3(Labeling_function f, - const Bbox_3& bbox, - const FT& relative_error_bound = FT(1e-3)); - -/*! -\brief Construction from a function, a bounding Iso_cuboid_3 and a relative error bound. -\param f the function. -\param bbox the bounding box of the meshable space. -\param relative_error_bound is the relative error bound used to compute intersection points between the implicit surface and query segments. The -bisection is stopped when the length of the intersected segment is less than the product of `relative_error_bound` by the diagonal of -`bounding_box`. -\deprecated This constructor is deprecated since CGAL-4.13, and -replaced by the constructor using the Boost Parameter Library. -*/ -Labeled_mesh_domain_3(Labeling_function f, - const Iso_cuboid_3& bbox, - const FT& relative_error_bound = FT(1e-3)); - -/// @} - -}; /* end Labeled_mesh_domain_3 */ -} /* end namespace CGAL */ diff --git a/Mesh_3/doc/Mesh_3/CGAL/refine_mesh_3.h b/Mesh_3/doc/Mesh_3/CGAL/Mesh_3/parameters.h similarity index 92% rename from Mesh_3/doc/Mesh_3/CGAL/refine_mesh_3.h rename to Mesh_3/doc/Mesh_3/CGAL/Mesh_3/parameters.h index 73c6ba18270..391455094c1 100644 --- a/Mesh_3/doc/Mesh_3/CGAL/refine_mesh_3.h +++ b/Mesh_3/doc/Mesh_3/CGAL/Mesh_3/parameters.h @@ -20,7 +20,7 @@ namespace parameters { \sa `CGAL::parameters::manifold_with_boundary()` \sa `CGAL::parameters::non_manifold()` */ - parameters::internal::Manifold_options manifold(); + unspecified_type manifold(); /*! \ingroup PkgMesh3Parameters @@ -35,7 +35,7 @@ namespace parameters { \sa `CGAL::parameters::manifold_with_boundary()` \sa `CGAL::parameters::manifold()` */ - parameters::internal::Manifold_options non_manifold(); + unspecified_type non_manifold(); /*! \ingroup PkgMesh3Parameters @@ -55,7 +55,7 @@ namespace parameters { \sa `CGAL::parameters::non_manifold()` \sa `CGAL::parameters::manifold()` */ - parameters::internal::Manifold_options manifold_with_boundary(); + unspecified_type manifold_with_boundary(); /*! \ingroup PkgMesh3Parameters @@ -91,15 +91,15 @@ refine_mesh_3(c3t3, \sa `CGAL::refine_mesh_3()` */ -parameters::internal::Exude_options exude( +unspecified_type exude( double parameters::time_limit = 0, double parameters::sliver_bound = 0); /*! \ingroup PkgMesh3Parameters -The function `parameters::features()` provides a value of internal type `Features` -to specify if 0 and 1-dimensional features have to be taken into account. +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`. @@ -113,7 +113,7 @@ if domain is a model of the refined concept `MeshDomainWithFeatures_3`. \sa `CGAL::parameters::no_features()` */ -parameters::internal::Features_options features(); +unspecified_type features(); /*! \ingroup PkgMesh3Parameters @@ -151,7 +151,7 @@ refine_mesh_3(c3t3, \sa `CGAL::refine_mesh_3()` */ -parameters::internal::Lloyd_options lloyd( +unspecified_type lloyd( double parameters::time_limit = 0, std::size_t parameters::max_iteration_number = 0, double parameters::convergence = 0.02, @@ -179,7 +179,7 @@ C3t3 c3t3 = make_mesh_3(domain, \sa `CGAL::refine_mesh_3()` */ -parameters::internal::Exude_options no_exude(); +unspecified_type no_exude(); /*! \ingroup PkgMesh3Parameters @@ -199,7 +199,7 @@ to take into account 0 and 1-dimensional input features. \sa `CGAL::parameters::features()` */ -parameters::internal::Features_options no_features(); +unspecified_type no_features(); /*! \ingroup PkgMesh3Parameters @@ -222,7 +222,7 @@ C3t3 c3t3 = make_mesh_3(domain, \sa `CGAL::refine_mesh_3()` */ -parameters::internal::Lloyd_options no_lloyd(); +unspecified_type no_lloyd(); /*! \ingroup PkgMesh3Parameters @@ -245,7 +245,7 @@ C3t3 c3t3 = make_mesh_3(domain, \sa `CGAL::refine_mesh_3()` */ -parameters::internal::Odt_options no_odt(); +unspecified_type no_odt(); /*! \ingroup PkgMesh3Parameters @@ -268,7 +268,7 @@ C3t3 c3t3 = make_mesh_3(domain, \sa `CGAL::refine_mesh_3()` */ -parameters::internal::Perturb_options no_perturb(); +unspecified_type no_perturb(); /*! \ingroup PkgMesh3Parameters @@ -305,7 +305,7 @@ refine_mesh_3(c3t3, \sa `CGAL::refine_mesh_3()` */ -parameters::internal::Odt_options odt( +unspecified_type odt( double parameters::time_limit = 0, std::size_t parameters::max_iteration_number = 0, double parameters::convergence = 0.02, @@ -348,7 +348,7 @@ refine_mesh_3(c3t3, \sa `CGAL::refine_mesh_3()` */ -parameters::internal::Perturb_options perturb( +unspecified_type perturb( double parameters::time_limit = 0, double parameters::sliver_bound = 0); diff --git a/Mesh_3/doc/Mesh_3/CGAL/Mesh_criteria_3.h b/Mesh_3/doc/Mesh_3/CGAL/Mesh_criteria_3.h deleted file mode 100644 index f6511eda70b..00000000000 --- a/Mesh_3/doc/Mesh_3/CGAL/Mesh_criteria_3.h +++ /dev/null @@ -1,161 +0,0 @@ -namespace CGAL { - -/*! -\ingroup PkgMesh3MeshClasses - -The class `Mesh_criteria_3` is a model of both concepts `MeshCriteria_3` -and `MeshCriteriaWithFeatures_3`. -It gathers the refinement criteria for mesh tetrahedra and -surface facets where -surface facets are facets in the mesh approximating the domain surface patches. -In addition, for domain with exposed 1-dimensional features, -the class `Mesh_criteria_3` -handles the definition of a sizing field to guide the discretization of -1-dimensional features. - -\tparam Tr has to be instantiated with the type used for -`C3T3::Triangulation`, -where `C3T3` is the model of `MeshComplex_3InTriangulation_3` -used in the mesh generation process, -and `C3T3::Triangulation` its nested triangulation type. - -\cgalModels `MeshCriteria_3` - -\cgalHeading{Example} - -\code{.cpp} - -// Create a Mesh_criteria_3 object with all cell and facet parameters set -Mesh_criteria_3 criteria (parameters::facet_angle=30, - parameters::facet_size=1, - parameters::facet_distance=0.1, - parameters::cell_radius_edge_ratio=2, - parameters::cell_size=1.5); - -// Create a Mesh_criteria_3 object with size ignored (note that the order changed) -Mesh_criteria_3 criteria (parameters::cell_radius_edge_ratio=2, - parameters::facet_angle=30, - parameters::facet_distance=0.1); - -\endcode - -\sa `MeshCriteria_3` -\sa `MeshCriteriaWithFeatures_3` -\sa `MeshCellCriteria_3` -\sa `MeshEdgeCriteria_3` -\sa `MeshFacetCriteria_3` -\sa `MeshDomainField_3` -\sa `CGAL::Mesh_cell_criteria_3` -\sa `CGAL::Mesh_edge_criteria_3` -\sa `CGAL::Mesh_facet_criteria_3` -\sa `CGAL::Mesh_facet_topology` - -*/ -template< typename Tr > -class Mesh_criteria_3 -{ -public: - -/// \name Types -/// @{ - -/*! -The criteria for edges. -*/ -typedef Mesh_edge_criteria_3 Edge_criteria; - -/*! -The criteria for facets. -*/ -typedef Mesh_facet_criteria_3 Facet_criteria; - -/*! -The -criteria for cells. -*/ -typedef Mesh_cell_criteria_3 Cell_criteria; - -/// @} - -/// \name Creation -/// @{ - -/*! -Construction from facet and cell criteria. The edge criteria are ignored -in this case. -*/ -Mesh_criteria_3(const Facet_criteria& facet_criteria, - const Cell_criteria& cell_criteria); - -/*! -Construction from edge, facet and cell criteria. -*/ -Mesh_criteria_3(const Edge_criteria& edge_criteria, - const Facet_criteria& facet_criteria, - const Cell_criteria& cell_criteria); - -/*! -\brief Construction from criteria parameters. This constructor uses named -parameters (from Boost.Parameter) for convenient criteria -construction. - -\tparam FT must be a model of `Field` -\tparam Fieldi (`i`=1,..,4) should be either a model -of the concept `Field` or a model of the concept `MeshDomainField_3` - -The parameters are named parameters and can be passed in any order -provided their name is given (see example below). The name of each -parameter is the one that is written in the description of the -function (e.g. `parameters::facet_size`). - -The description of each parameter is as follows: - -- `edge_size`: a scalar field (resp. a constant) providing a space varying -(resp. a uniform) -upper bound for the lengths of curve edges. This parameter has to be set to a positive -value when 1-dimensional features protection is used. - -- `facet_angle`: a lower bound for the angles (in degrees) of the -surface mesh facets. - -- `facet_size`: a scalar field (resp. a constant) describing -a space varying (resp. a uniform) upper-bound or for the radii of the surface Delaunay balls. - -- `facet_distance`: a scalar field (resp. a constant) describing a space varying (resp. a uniform) -upper bound for the distance between the facet circumcenter and the center of its surface -Delaunay ball. - -- `facet_topology`: the set of topological constraints -which have to be verified by each surface facet. The default value is -`CGAL::FACET_VERTICES_ON_SURFACE`. See `Mesh_facet_topology` manual page to -get all possible values. - -- `cell_radius_edge_ratio`: an upper bound for the radius-edge ratio of the mesh tetrahedra. - -- `cell_size`: a scalar field (resp. a constant) describing -a space varying (resp. a uniform) upper-bound for the circumradii of the mesh tetrahedra. - -Note that each size or distance parameter can be specified using two ways: either as -a scalar field or as a numerical value when the field is uniform. - -Each parameter has a special default value `ignored` which means that the -corresponding criterion will be ignored. -Numerical sizing or distance values, as well as scalar fields -should be given in the unit used for coordinates of points in the mesh domain class -of the mesh generation process. - -*/ -template -Mesh_criteria_3(Field1 parameters::edge_size = ignored, - FT parameters::facet_angle = ignored, - Field2 parameters::facet_size = ignored, - Field3 parameters::facet_distance = ignored, - Mesh_facet_topology parameters::facet_topology = CGAL::FACET_VERTICES_ON_SURFACE, - FT parameters::cell_radius_edge_ratio = ignored, - Field4 parameters::cell_size = ignored); - -/// @} - -}; /* end Mesh_criteria_3 */ -} /* end namespace CGAL */ diff --git a/Mesh_3/doc/Mesh_3/Doxyfile.in b/Mesh_3/doc/Mesh_3/Doxyfile.in index 759b92514da..1cc04ed4dbe 100644 --- a/Mesh_3/doc/Mesh_3/Doxyfile.in +++ b/Mesh_3/doc/Mesh_3/Doxyfile.in @@ -14,7 +14,7 @@ INPUT += \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/refine_mesh_3.h \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/make_mesh_3.h \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/Labeled_mesh_domain_3.h \ - ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/Mesh_criteria_3.h + ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/Mesh_criteria_3.h \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/Mesh_facet_topology.h \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/Mesh_vertex_base_3.h \ ${CGAL_PACKAGE_INCLUDE_DIR}/CGAL/Mesh_cell_base_3.h \ diff --git a/Mesh_3/include/CGAL/Labeled_mesh_domain_3.h b/Mesh_3/include/CGAL/Labeled_mesh_domain_3.h index 20f622733c0..8e9b13fb37f 100644 --- a/Mesh_3/include/CGAL/Labeled_mesh_domain_3.h +++ b/Mesh_3/include/CGAL/Labeled_mesh_domain_3.h @@ -217,18 +217,60 @@ protected: FT squared_error_bound_; }; // Labeled_mesh_domain_3_impl_details -/** - * \class Labeled_mesh_domain_3 - * - * Function f must take his values into N. - * Let p be a Point. - * - f(p)=0 means that p is outside domain. - * - f(p)=a, a!=0 means that p is inside subdomain a. - * - * Any boundary facet is labelled , with a, where b!=0. - */ +/*! +\ingroup PkgMesh3Domains + +\brief The class `Labeled_mesh_domain_3` implements indexed domains. + +This class is a model of concept `MeshDomain_3`. + +Any boundary facet is labeled , with a, where b!=0. + +This class includes a labeling function that provides the index of the subdomain in which any +query point lies. An intersection between a segment and bounding +surfaces is detected when both segment endpoints are associated with different +values of subdomain indices. The intersection is then constructed by bisection. +The bisection stops when the query segment is shorter than an error bound +`e` given by the product of the +length of the diagonal of the bounding box (in world coordinates), or the radius of the bounding sphere, and +a relative error bound passed as argument to the constructor of `Labeled_mesh_domain_3`. + +This class has a constructor taking a labeling function. It has also three +static template member functions that act as named constructors: +
    +
  • `create_gray_image_mesh_domain()`, to create a domain from a 3D gray image, +
  • `create_labeled_image_mesh_domain()`, to create a domain from a 3D labeled image, and +
  • `create_implicit_mesh_domain()`, to create a domain from an implicit function. +
+ +\tparam BGT is a geometric traits class that provides +the basic operations to implement +intersection tests and intersection computations +through a bisection method. This parameter must be instantiated +with a model of the concept `BisectionGeometricTraits_3`. + +\cgalHeading{Labeling function} + +A labeling function `f` must return `0` if the point isn't located in any subdomain. The return type of labeling functions is an integer. + +Let `p` be a Point. +
    +
  • `f(p)=0` means that `p` is outside domain.
    • +
  • `f(p)=a`, `a!=0` means that `p` is inside subdomain `a`.
    • +
+`CGAL::Implicit_multi_domain_to_labeling_function_wrapper` is a good candidate for this template parameter +if there are several components to mesh. + +The function type can be any model of the concept `Callable` compatible with the signature `Subdomain_index(const Point_3&)`: it can be a function, a function object, a lambda expression... that takes a `%Point_3` as argument, and returns a type convertible to `Subdomain_index`. + +\cgalModels MeshDomain_3 + +\sa `Implicit_multi_domain_to_labeling_function_wrapper` +\sa `CGAL::make_mesh_3()`. + +*/ templateBoost Parameter +Library). They can be specified in any order. + +\cgalHeading{Named Parameters} +- `parameters::function` (mandatory) the labeling function, compatible with `Labeling_function`. +- `parameters::bounding_object` (mandatory) the bounding object is either a bounding sphere (of type `Sphere_3`), a bounding box (type `Bbox_3`), or a bounding `Iso_cuboid_3`. It bounds the meshable space. +- `parameters::relative_error_bound` (optional) the relative error bound used to compute intersection points between the implicit surface and query segments. The +bisection is stopped when the length of the intersected segment is less than the product of `relative_error_bound` by the diameter of the bounding object. Its default value is `FT(1e-3)`. + +\cgalHeading{Example} +From the example (\ref Mesh_3/mesh_implicit_domains_2.cpp): +\snippet Mesh_3/mesh_implicit_domains_2.cpp Domain creation + + */ template Labeled_mesh_domain_3(const CGAL_NP_CLASS& np = parameters::default_values()) :Impl_details(parameters::get_parameter(np, internal_np::function_param), @@ -308,7 +369,9 @@ public: { } - /** +///@} + + /* * Backward-compatibility constructors, with `null_subdomain_index` as * fourth parameter. * @{ @@ -342,7 +405,7 @@ public: construct_pair_functor(), null, p_rng) {} - /** + /* * @} */ @@ -364,7 +427,7 @@ public: This constructor uses named parameters . They can be specified in any order. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" - \param image the input 3D image. Must be a `CGAL::Image_3` object. + \param image_ the input 3D image. Must be a `CGAL::Image_3` object. \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: @@ -493,7 +556,7 @@ public: This constructor uses named parameters . They can be specified in any order. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" - \param image the input 3D image. Must be a `CGAL::Image_3` object. + \param image_ the input 3D image. Must be a `CGAL::Image_3` object. \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: @@ -720,9 +783,9 @@ From the example (\ref Mesh_3/mesh_implicit_sphere_variable_size.cpp): /// @} /** - * Constructs a set of \ccc{n} points on the surface, and output them to - * the output iterator \ccc{pts} whose value type is required to be - * \ccc{std::pair}. + * Constructs a set of `n` points on the surface, and output them to + * the output iterator `pts` whose value type is required to be + * `std::pair`. */ struct Construct_initial_points { @@ -750,7 +813,7 @@ From the example (\ref Mesh_3/mesh_implicit_sphere_variable_size.cpp): } /** - * Returns true if point~\ccc{p} is in the domain. If \ccc{p} is in the + * Returns true if point~`p` is in the domain. If `p` is in the * domain, the parameter index is set to the index of the subdomain * including $p$. It is set to the default value otherwise. */ @@ -775,12 +838,12 @@ From the example (\ref Mesh_3/mesh_implicit_sphere_variable_size.cpp): Is_in_domain is_in_domain_object() const { return Is_in_domain(*this); } /** - * Returns true is the element \ccc{type} intersect properly any of the + * Returns true is the element `type` intersect properly any of the * surface patches describing the either the domain boundary or some * subdomain boundary. - * \ccc{Type} is either \ccc{Segment_3}, \ccc{Ray_3} or \ccc{Line_3}. + * `Type is either `Segment_3`, `Ray_3` or `Line_3`. * Parameter index is set to the index of the intersected surface patch - * if \ccc{true} is returned and to the default \ccc{Surface_patch_index} + * if `true` is returned and to the default `Surface_patch_index` * value otherwise. */ struct Do_intersect_surface @@ -849,12 +912,12 @@ From the example (\ref Mesh_3/mesh_implicit_sphere_variable_size.cpp): } /** - * Returns a point in the intersection of the primitive \ccc{type} + * Returns a point in the intersection of the primitive `type` * with some boundary surface. - * \ccc{Type1} is either \ccc{Segment_3}, \ccc{Ray_3} or \ccc{Line_3}. - * The integer \ccc{dimension} is set to the dimension of the lowest + * `Type1` is either `Segment_3`, `Ray_3` or `Line_3`. + * The integer `dimension` is set to the dimension of the lowest * dimensional face in the input complex containing the returned point, and - * \ccc{index} is set to the index to be stored at a mesh vertex lying + * `index` is set to the index to be stored at a mesh vertex lying * on this face. */ struct Construct_intersection diff --git a/Mesh_3/include/CGAL/Mesh_3/parameters.h b/Mesh_3/include/CGAL/Mesh_3/parameters.h index 29aded71b4e..745666f470c 100644 --- a/Mesh_3/include/CGAL/Mesh_3/parameters.h +++ b/Mesh_3/include/CGAL/Mesh_3/parameters.h @@ -7,21 +7,17 @@ // $Id$ // SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-Commercial // -// -// -// -//****************************************************************************** -// File Description : Named Function Parameters specific code -//****************************************************************************** -#ifndef CGAL_PARAMETERS_H -#define CGAL_PARAMETERS_H + +#ifndef CGAL_MESH_3_PARAMETERS_H +#define CGAL_MESH_3_PARAMETERS_H #include #include #include #include -namespace parameters{ +namespace CGAL { +namespace parameters { // ----------------------------------- // Perturb @@ -241,6 +237,6 @@ Named_function_parameters m } -} //namespace parameters +} } //namespace CGAL::parameters -#endif //CGAL_PARAMETERS_H \ No newline at end of file +#endif //CGAL_MESH_3_PARAMETERS_H \ No newline at end of file diff --git a/Mesh_3/include/CGAL/Mesh_criteria_3.h b/Mesh_3/include/CGAL/Mesh_criteria_3.h index 8c4ed59c305..4778361f245 100644 --- a/Mesh_3/include/CGAL/Mesh_criteria_3.h +++ b/Mesh_3/include/CGAL/Mesh_criteria_3.h @@ -125,8 +125,58 @@ private: -// Class Mesh_criteria_3 -// Provides default mesh criteria to drive Mesh_3 process + +/*! +\ingroup PkgMesh3MeshClasses + +The class `Mesh_criteria_3` is a model of both concepts `MeshCriteria_3` +and `MeshCriteriaWithFeatures_3`. +It gathers the refinement criteria for mesh tetrahedra and +surface facets where +surface facets are facets in the mesh approximating the domain surface patches. +In addition, for domain with exposed 1-dimensional features, +the class `Mesh_criteria_3` +handles the definition of a sizing field to guide the discretization of +1-dimensional features. + +\tparam Tr has to be instantiated with the type used for +`C3T3::Triangulation`, +where `C3T3` is the model of `MeshComplex_3InTriangulation_3` +used in the mesh generation process, +and `C3T3::Triangulation` its nested triangulation type. + +\cgalModels `MeshCriteria_3` + +\cgalHeading{Example} + +\code{.cpp} + +// Create a Mesh_criteria_3 object with all cell and facet parameters set +Mesh_criteria_3 criteria (parameters::facet_angle=30, + parameters::facet_size=1, + parameters::facet_distance=0.1, + parameters::cell_radius_edge_ratio=2, + parameters::cell_size=1.5); + +// Create a Mesh_criteria_3 object with size ignored (note that the order changed) +Mesh_criteria_3 criteria (parameters::cell_radius_edge_ratio=2, + parameters::facet_angle=30, + parameters::facet_distance=0.1); + +\endcode + +\sa `MeshCriteria_3` +\sa `MeshCriteriaWithFeatures_3` +\sa `MeshCellCriteria_3` +\sa `MeshEdgeCriteria_3` +\sa `MeshFacetCriteria_3` +\sa `MeshDomainField_3` +\sa `CGAL::Mesh_cell_criteria_3` +\sa `CGAL::Mesh_edge_criteria_3` +\sa `CGAL::Mesh_facet_criteria_3` +\sa `CGAL::Mesh_facet_topology` + +*/ template , typename FacetCriteria = Mesh_facet_criteria_3, @@ -143,9 +193,32 @@ class Mesh_criteria_3 CellCriteria> Base; public: +#ifdef DOXYGEN_RUNNING +/// \name Types +/// @{ + +/*! +The criteria for edges. +*/ +typedef Mesh_edge_criteria_3 Edge_criteria; + +/*! +The criteria for facets. +*/ +typedef Mesh_facet_criteria_3 Facet_criteria; + +/*! +The +criteria for cells. +*/ +typedef Mesh_cell_criteria_3 Cell_criteria; + +/// @} +#else typedef typename Base::Edge_criteria Edge_criteria; typedef typename Base::Facet_criteria Facet_criteria; typedef typename Base::Cell_criteria Cell_criteria; +#endif // Constructor Mesh_criteria_3(Facet_criteria facet_criteria, @@ -161,51 +234,47 @@ public: facet_criteria, cell_criteria) {} /*! - \brief Construction from criteria parameters. - This constructor uses named - parameters (from Boost.Parameter) for convenient criteria - construction. + \brief Construction from criteria parameters. - \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" + \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: + \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: - \cgalNamedParamsBegin - \cgalParamNBegin{edge_size} - \cgalParamDescription{a scalar field (resp. a constant) providing a space varying - (resp. a uniform) - upper bound for the lengths of curve edges. This parameter has to be set to a positive - value when 1-dimensional features protection is used.} + \cgalNamedParamsBegin + \cgalParamNBegin{edge_size} + \cgalParamDescription{a scalar field (resp. a constant) providing a space varying + (resp. a uniform) + upper bound for the lengths of curve edges. This parameter has to be set to a positive + value when 1-dimensional features protection is used.} - \cgalParamNBegin{facet_angle} - \cgalParamDescription{a lower bound for the angles (in degrees) of the - surface mesh facets.} + \cgalParamNBegin{facet_angle} + \cgalParamDescription{a lower bound for the angles (in degrees) of the + surface mesh facets.} - \cgalParamNBegin{facet_size} - \cgalParamDescription{ a scalar field (resp. a constant) describing - a space varying (resp. a uniform) upper-bound or for the radii of the surface Delaunay balls.} + \cgalParamNBegin{facet_size} + \cgalParamDescription{ a scalar field (resp. a constant) describing + a space varying (resp. a uniform) upper-bound or for the radii of the surface Delaunay balls.} - \cgalParamNBegin{facet_distance} - \cgalParamDescription{ a scalar field (resp. a constant) describing a space varying (resp. a uniform) - upper bound for the distance between the facet circumcenter and the center of its surface - Delaunay ball.} - \cgalParamNBegin{facet_topology} - \cgalParamDescription{ the set of topological constraints - which have to be verified by each surface facet. See `Mesh_facet_topology` manual page to - get all possible values.} - \cgalParamDefault{CGAL::FACET_VERTICES_ON_SURFACE} + \cgalParamNBegin{facet_distance} + \cgalParamDescription{ a scalar field (resp. a constant) describing a space varying (resp. a uniform) + upper bound for the distance between the facet circumcenter and the center of its surface + Delaunay ball.} + \cgalParamNBegin{facet_topology} + \cgalParamDescription{ the set of topological constraints + which have to be verified by each surface facet. See `Mesh_facet_topology` manual page to + get all possible values.} + \cgalParamDefault{CGAL::FACET_VERTICES_ON_SURFACE} - \cgalParamNBegin{cell_radius_edge_ratio} - \cgalParamDescription{ an upper bound for the radius-edge ratio of the mesh tetrahedra.} + \cgalParamNBegin{cell_radius_edge_ratio} + \cgalParamDescription{ an upper bound for the radius-edge ratio of the mesh tetrahedra.} - \cgalParamNBegin{cell_size} - \cgalParamDescription{ a scalar field (resp. a constant) describing - a space varying (resp. a uniform) upper-bound for the circumradii of the mesh tetrahedra.} + \cgalParamNBegin{cell_size} + \cgalParamDescription{ a scalar field (resp. a constant) describing + a space varying (resp. a uniform) upper-bound for the circumradii of the mesh tetrahedra.} - \cgalNamedParamsEnd - */ - + \cgalNamedParamsEnd + */ template Mesh_criteria_3(const CGAL_NP_CLASS& np = parameters::default_values()): Base(np) { diff --git a/Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h b/Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h index dcf5b3ad5b7..e0e9dfdcf13 100644 --- a/Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h +++ b/Mesh_3/include/CGAL/lloyd_optimize_mesh_3.h @@ -66,7 +66,7 @@ object used to create the `c3t3` parameter. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" -@param cdt the initial mesh that will be modified by the algorithm to represent the final optimized mesh. +@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 np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: diff --git a/Mesh_3/include/CGAL/make_mesh_3.h b/Mesh_3/include/CGAL/make_mesh_3.h index 522101ba0a3..c083b325ba4 100644 --- a/Mesh_3/include/CGAL/make_mesh_3.h +++ b/Mesh_3/include/CGAL/make_mesh_3.h @@ -425,11 +425,9 @@ of 1-dimensional exposed features. \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" - @param c3t3 the mesh to be refined. @param domain the domain to be discretized @param criteria the criteria - - The following are optional named parameters. + @param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: \cgalNamedParamsBegin \cgalParamNBegin{features_options} @@ -495,7 +493,7 @@ of 1-dimensional exposed features. \cgalNamedParamsEnd - The optimization parameters can be passed in an arbitrary order. If one parameter +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()`. diff --git a/Mesh_3/include/CGAL/refine_mesh_3.h b/Mesh_3/include/CGAL/refine_mesh_3.h index 9347a3f02c5..95be2940420 100644 --- a/Mesh_3/include/CGAL/refine_mesh_3.h +++ b/Mesh_3/include/CGAL/refine_mesh_3.h @@ -277,7 +277,7 @@ inline internal::Mesh_3_options mesh_3_dump() CGAL_BOOLEAN_PARAMETER(Reset,reset_c3t3,no_reset_c3t3) } // end namespace parameters -#include + /*! \ingroup PkgMesh3Functions @@ -357,6 +357,7 @@ of 1-dimensional exposed features. \param c3t3 the mesh to be refined. \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. The following four parameters are optional optimization parameters. They control which optimization processes are performed @@ -601,4 +602,7 @@ void refine_mesh_3_impl(C3T3& c3t3, } #endif // DOXYGEN_RUNNING } // end namespace CGAL + +#include + #endif // CGAL_REFINE_MESH_3_H