diff --git a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/clip.h b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/clip.h index 05ca9388ebb..56004241df4 100644 --- a/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/clip.h +++ b/Polygon_mesh_processing/include/CGAL/Polygon_mesh_processing/clip.h @@ -404,6 +404,7 @@ void split_along_edges(TriangleMesh& tm, /** * \ingroup PMP_corefinement_grp + * * clips `tm` by keeping the part that is inside the volume \link coref_def_subsec bounded \endlink * by `clipper`. * If `tm` is closed, the clipped part can be closed too if the named parameter `clip_volume` is set to `true`. @@ -423,30 +424,51 @@ void split_along_edges(TriangleMesh& tm, * @param np_tm optional sequence of \ref pmp_namedparameters "Named Parameters" among the ones listed below * @param np_c optional sequence of \ref pmp_namedparameters "Named Parameters" among the ones listed below * + * * \cgalNamedParamsBegin - * \cgalParamBegin{vertex_point_map} - * the property map with the points associated to the vertices of `tm` (`clipper`). - * If this parameter is omitted, an internal property map for - * `CGAL::vertex_point_t` must be available in `TriangleMesh` - * \cgalParamEnd - * \cgalParamBegin{face_index_map} - * a property map containing a unique index for each face of `tm` (`clipper`). - * \cgalParamEnd - * \cgalParamBegin{visitor} a class model of `PMPCorefinementVisitor` - * that is used to track the creation of new faces. - * \cgalParamEnd - * \cgalParamBegin{throw_on_self_intersection} if `true`, - * the set of triangles closed to the intersection of `tm` and `clipper` will be - * checked for self-intersections and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` - * will be thrown if at least one is found. Default value is `false`. - * \cgalParamEnd - * \cgalParamBegin{clip_volume} if `true` and `tm` is closed, the clipping will be done on - * the volume \link coref_def_subsec bounded \endlink by `tm` rather than on its surface - * (i.e., `tm` will be kept closed). Default value is `false`. - * \cgalParamEnd - * \cgalParamBegin{use_compact_clipper} if `false`, the parts of `tm` coplanar with `clipper` - * will not be part of the output. Default value is `true`. - * \cgalParamEnd + * \cgalParamNBegin{vertex_point_map} + * \cgalParamDescription{a property map associating points to the vertices of `tm` (resp. `clipper`)} + * \cgalParamType{a class model of `ReadablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} + * \cgalParamDefault{`boost::get(CGAL::vertex_point, tm (resp. clipper))`} + * \cgalParamExtra{if this parameter is omitted an internal property map for `CGAL::vertex_point_t` must be available in `TriangleMesh`} + * \cgalParamNEnd + * + * \cgalParamNBegin{face_index_map} + * \cgalParamDescription{a property map associating to each face of `tm` (`clipper`) a unique index between `0` and `num_faces(tm (resp. clipper)) - 1`} + * \cgalParamType{a class model of `ReadablePropertyMap` with `boost::graph_traits::%face_descriptor` as key type and `std::size_t` as value type} + * \cgalParamDefault{an automatically indexed internal map} + * \cgalParamExtra{if the property map is writable, the indices of the faces of `tm` and `clipper` will be set after refining `tm` with the intersection with `clipper`} + * \cgalParamNEnd + * + * \cgalParamNBegin{visitor} + * \cgalParamDescription{a visitor used to track the creation of new faces} + * \cgalParamType{a class model of `PMPCorefinementVisitor`} + * \cgalParamDefault{`Corefinement::Default_visitor`} + * \cgalParamNEnd + * + * \cgalParamNBegin{throw_on_self_intersection} + * \cgalParamDescription{if `true` the set of triangles closed to the intersection of `tm` and `clipper` will be + * checked for self-intersections and `Corefinement::Self_intersection_exception` + * will be thrown if at least one self-intersection is found} + * \cgalParamType{Boolean} + * \cgalParamDefault{`false`} + * \cgalParamNEnd + * + * \cgalParamNBegin{clip_volume} + * \cgalParamDescription{if `true` and `tm` is closed, the clipping will be done on the volume + * \link coref_def_subsec bounded \endlink by `tm` rather than on its surface + * (i.e., `tm` will be kept closed)} + * \cgalParamType{Boolean} + * \cgalParamDefault{`false`} + * \cgalParamNEnd + * + * \cgalParamNBegin{use_compact_clipper} + * \cgalParamDescription{if `false`, the parts of `tm` coplanar with `clipper` will not be part of the output.} + * \cgalParamType{Boolean} + * \cgalParamDefault{`false`} + * \cgalParamExtra{This option has an effect only if a surface and not a volume is clipped, + * (i.e., if `clip_volume` is `false` or if `tm` is open).} + * \cgalParamNEnd * \cgalNamedParamsEnd * * @return `true` if the output surface mesh is manifold. @@ -479,6 +501,7 @@ clip(TriangleMesh& tm, * * \note In the current implementation it is not possible to set the vertex point map and the default will be used. `Plane_3` must be * from the same %Kernel as the point of the vertex point map. + * * \pre \link CGAL::Polygon_mesh_processing::does_self_intersect() `!CGAL::Polygon_mesh_processing::does_self_intersect(tm)` \endlink * * @tparam TriangleMesh a model of `MutableFaceGraph`, `HalfedgeListGraph` and `FaceListGraph`. @@ -492,20 +515,41 @@ clip(TriangleMesh& tm, * @param np optional sequence of \ref pmp_namedparameters "Named Parameters" among the ones listed below * * \cgalNamedParamsBegin - * \cgalParamBegin{visitor} a class model of `PMPCorefinementVisitor` - * that is used to track the creation of new faces. - * \cgalParamEnd - * \cgalParamBegin{throw_on_self_intersection} if `true`, - * the set of triangles closed to the intersection of `tm` and `plane` will be - * checked for self-intersections and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` - * will be thrown if at least one is found. Default value is `false`. - * \cgalParamEnd - * \cgalParamBegin{clip_volume} if `true` and `tm` is closed, the clipping will be done on - * the volume \link coref_def_subsec bounded \endlink by `tm` rather than on its surface - * (i.e., `tm` will be kept closed). Default value is `false`. - * \cgalParamEnd - * \cgalParamBegin{use_compact_clipper} if `false` the parts of `tm` coplanar with `plane` - * will not be part of the output. Default value is `true`. + * \cgalParamNBegin{vertex_point_map} + * \cgalParamDescription{a property map associating points to the vertices of `tm`} + * \cgalParamType{a class model of `ReadablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} + * \cgalParamDefault{`boost::get(CGAL::vertex_point, tm)`} + * \cgalParamNEnd + * + * \cgalParamNBegin{visitor} + * \cgalParamDescription{a visitor used to track the creation of new faces} + * \cgalParamType{a class model of `PMPCorefinementVisitor`} + * \cgalParamDefault{`Corefinement::Default_visitor`} + * \cgalParamNEnd + * + * \cgalParamNBegin{throw_on_self_intersection} + * \cgalParamDescription{if `true`, the set of triangles closed to the intersection of `tm` + * and `plane` will be checked for self-intersections + * and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` + * will be thrown if at least one self-intersection is found} + * \cgalParamType{Boolean} + * \cgalParamDefault{`false`} + * \cgalParamNEnd + * + * \cgalParamNBegin{clip_volume} + * \cgalParamDescription{if `true` and `tm` is closed, the clipping will be done on + * the volume \link coref_def_subsec bounded \endlink by `tm` + * rather than on its surface (i.e., `tm` will be kept closed)} + * \cgalParamType{Boolean} + * \cgalParamDefault{`false`} + * \cgalParamNEnd + * + * \cgalParamNBegin{use_compact_clipper} + * \cgalParamDescription{if `false` the parts of `tm` coplanar with `plane` will not be part of the output} + * \cgalParamType{Boolean} + * \cgalParamDefault{`true`} + * \cgalParamNEnd + * * \cgalNamedParamsEnd * * @return `true` if the output surface mesh is manifold. @@ -566,19 +610,29 @@ bool clip(TriangleMesh& tm, * @param np_s optional sequence of \ref pmp_namedparameters "Named Parameters" among the ones listed below * * \cgalNamedParamsBegin - * \cgalParamBegin{vertex_point_map} - * the property map with the points associated to the vertices of `tm` (`splitter`). - * If this parameter is omitted, an internal property map for - * `CGAL::vertex_point_t` must be available in `TriangleMesh` - * \cgalParamEnd - * \cgalParamBegin{visitor} a class model of `PMPCorefinementVisitor` - * that is used to track the creation of new faces. - * \cgalParamEnd - * \cgalParamBegin{throw_on_self_intersection} if `true`, - * the set of triangles closed to the intersection of `tm` and `splitter` will be - * checked for self-intersections and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` - * will be thrown if at least one is found. - * \cgalParamEnd + * \cgalParamNBegin{vertex_point_map} + * \cgalParamDescription{a property map associating points to the vertices of `tm` (`splitter`)} + * \cgalParamType{a class model of `ReadablePropertyMap` with `boost::graph_traits::%vertex_descriptor` as key type and `%Point_3` as value type} + * \cgalParamDefault{`boost::get(CGAL::vertex_point, tm)`} + * \cgalParamDefault{If this parameter is omitted, an internal property map for + * `CGAL::vertex_point_t` must be available in `TriangleMesh`} + * \cgalParamNEnd + * + * \cgalParamNBegin{visitor} + * \cgalParamDescription{a visitor used to track the creation of new faces} + * \cgalParamType{a class model of `PMPCorefinementVisitor`} + * \cgalParamDefault{`Corefinement::Default_visitor`} + * \cgalParamNEnd + * + * \cgalParamNBegin{throw_on_self_intersection} + * \cgalParamDescription{if `true`, the set of triangles closed to the intersection of `tm` + * and `splitter` will be checked for self-intersections + * and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` + * will be thrown if at least one self-intersection is found} + * \cgalParamType{Boolean} + * \cgalParamDefault{`false`} + * \cgalParamNEnd + * * \cgalNamedParamsEnd */ template ::%vertex_descriptor` as key type and `%Point_3` as value type} + * \cgalParamDefault{`boost::get(CGAL::vertex_point, tm)`} + * \cgalParamNEnd + * + * \cgalParamNBegin{visitor} + * \cgalParamDescription{a visitor used to track the creation of new faces} + * \cgalParamType{a class model of `PMPCorefinementVisitor`} + * \cgalParamDefault{`Corefinement::Default_visitor`} + * \cgalParamNEnd + * + * \cgalParamNBegin{throw_on_self_intersection} + * \cgalParamDescription{if `true`, the set of triangles closed to the intersection of `tm` + * and `plane` will be checked for self-intersections + * and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` + * will be thrown if at least one self-intersection is found} + * \cgalParamType{Boolean} + * \cgalParamDefault{`false`} + * \cgalParamNEnd + * * \cgalNamedParamsEnd */ template ::%vertex_descriptor` as key type and `%Point_3` as value type} + * \cgalParamDefault{`boost::get(CGAL::vertex_point, tm)`} + * \cgalParamNEnd + * + * \cgalParamNBegin{visitor} + * \cgalParamDescription{a visitor used to track the creation of new faces} + * \cgalParamType{a class model of `PMPCorefinementVisitor`} + * \cgalParamDefault{`Corefinement::Default_visitor`} + * \cgalParamNEnd + * + * \cgalParamNBegin{throw_on_self_intersection} + * \cgalParamDescription{if `true`, the set of triangles closed to the intersection of `tm` + * and `iso_cuboid` will be checked for self-intersections + * and `CGAL::Polygon_mesh_processing::Corefinement::Self_intersection_exception` + * will be thrown if at least one self-intersection is found} + * \cgalParamType{Boolean} + * \cgalParamDefault{`false`} + * \cgalParamNEnd + * + * \cgalParamNBegin{clip_volume} + * \cgalParamDescription{if `true` and `tm` is closed, the clipping will be done on + * the volume \link coref_def_subsec bounded \endlink by `tm` + * rather than on its surface (i.e., `tm` will be kept closed)} + * \cgalParamType{Boolean} + * \cgalParamDefault{`false`} + * \cgalParamNEnd + * + * \cgalParamNBegin{use_compact_clipper} + * \cgalParamDescription{if `false` the parts of `tm` coplanar with `plane` will not be part of the output} + * \cgalParamType{Boolean} + * \cgalParamDefault{`true`} + * \cgalParamNEnd + * * \cgalNamedParamsEnd * * @return `true` if the output surface mesh is manifold.