Add documentation of the filter

Surface_mesh_simplification/doc/Surface_mesh_simplification/CGAL/Surface_mesh_simplification/Policies/Edge_collapse/Bounded_normal_change_filter.h

@@ -0,0 +1,53 @@
+
+namespace CGAL {
+namespace Surface_mesh_simplification {
+
+/*!
+\ingroup PkgSurfaceMeshSimplificationRef
+
+The class `Bounded_normal_change_filter` is a model for the `GetFilter` concept.
+It rejects the placement if the nested filter rejects it, or
+if any triangle in the profile changes the normal by more than 90 degree, in this order.
+
+
+\tparam Get_filter_ must be a model of the concept `GetFilter`.  It defaults to a class that does
+not filter any placement.
+
+\cgalModels `GetFilter`
+
+*/
+template <typename GetFilter_>
+class Bounded_normal_change_filter {
+public:
+
+  /// \name Creation
+  /// @{
+
+  /*!
+  %Default constructor
+  */
+  Bounded_normal_change_filter();
+
+  /*!
+  Constructor
+
+  \param get_filter is the filter that will be filtered.
+  */
+  Bounded_normal_change_filter(const GetFilter_& get_filter);
+
+  /// @}
+
+  /// \name Operations
+  /// @{
+
+  /*!
+  Returns the placement, if it does not get filtered by the wrapped filter
+  and if no triangle in the profile has its normal changed by more than 90 degree.
+  */
+  boost::optional<typename Edge_profile::Point> operator()(const Edge_profile& profile) const;
+
+  /// @}
+
+}; /* end Surface_mesh_simplification::Bounded_normal_change_filter */
+} // namespace Surface_Mesh_Simplification
+} // namespace CGAL

Surface_mesh_simplification/doc/Surface_mesh_simplification/CGAL/Surface_mesh_simplification/Policies/Edge_collapse/Bounded_normal_change_placement.h

@@ -5,6 +5,10 @@ namespace Surface_mesh_simplification {
 /*!
 \ingroup PkgSurfaceMeshSimplificationRef
 
+\deprecated This class is deprecated since \cgal 5.2 and the use of
+`Bounded_normal_change_filter` should be preferred.
+
+
 The class `Bounded_normal_change_placement` is a model for the `GetPlacement` concept
 which serves as a filter for another placement. It rejects the placement if any
 triangle in the profile changes the normal by more than 90 degree.
@@ -40,7 +44,7 @@ public:
 
   /*!
   Returns the placement computed by `get_placement`, if no
-  triangle in the profile has its normal change by more than 90 degree.
+  triangle in the profile has its normal changed by more than 90 degree.
   */
   boost::optional<typename Edge_profile::Point> operator()(const Edge_profile& profile) const;
 

Surface_mesh_simplification/doc/Surface_mesh_simplification/CGAL/Surface_mesh_simplification/edge_collapse.h

@@ -55,6 +55,12 @@ the number of edges effectively removed.
     \cgalParamDefault{`CGAL::Surface_mesh_simplification::LindstromTurk_placement<TriangleMesh>`}
   \cgalParamNEnd
 
+  \cgalParamNBegin{get_filter}
+    \cgalParamDescription{a policy which returns the filter for a placement}
+    \cgalParamType{a model of the concept `GetFilter`}
+    \cgalParamDefault{no placement gets filtered}
+  \cgalParamNEnd
+
   \cgalParamNBegin{edge_is_constrained_map}
     \cgalParamDescription{a property map containing the constrained-or-not status of each edge of `tmesh`}
     \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits<TriangleMesh>::%edge_descriptor`
@@ -102,4 +108,3 @@ int edge_collapse(TriangleMesh& tmesh,
 
 } // namespace Surface_mesh_simplification
 } /* namespace CGAL */
-

Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetFilter.h

@@ -0,0 +1,39 @@
+/*!
+\ingroup PkgSurfaceMeshSimplificationConcepts
+\cgalConcept
+
+The concept `GetFilter` describes the requirements for the <I>policy
+function object</I> which gets the <I>collapse placement</I> of an edge,
+that is, the new position of the vertex that remains after a
+halfedge-collapse operation.
+
+The placement returned is a `boost::optional` value (i.e., it can
+be absent). The value `boost::none` indicates that the edge should not be collapsed.
+
+\cgalRefines `DefaultConstructible`
+\cgalRefines `CopyConstructible`
+
+\cgalHasModel `CGAL::Surface_mesh_simplification::Bounded_normal_change_filter<Placement>`
+\cgalHasModel `CGAL::Surface_mesh_simplification::FastEnvelopeFilter<GeomTraits,Placement>`
+*/
+
+
+class GetFilter
+{
+public:
+
+  /// The class Edge_profile regroups useful information about an edge, such as its incident vertices and faces.
+  typedef CGAL::Surface_mesh_simplification::Edge_profile Edge_profile;
+
+  /// \name Operations
+  /// @{
+
+  /*!
+  filters the placement.
+
+  */
+  boost::optional<Edge_profile::Point> operator()(const Edge_profile& profile, boost::optional<Edge_profile::Point> placement) const;
+
+  /// @}
+
+}; /* end GetPlacement */

Surface_mesh_simplification/doc/Surface_mesh_simplification/PackageDescription.txt

@@ -27,6 +27,7 @@
 - `StopPredicate`
 - `GetCost`
 - `GetPlacement`
+- `GetFilter`
 - `EdgeCollapseSimplificationVisitor`
 
 \cgalCRPSection{Functions}
@@ -44,5 +45,6 @@
 - `CGAL::Surface_mesh_simplification::LindstromTurk_placement<TriangleMesh>`
 - `CGAL::Surface_mesh_simplification::GarlandHeckbert_policies<TriangleMesh, GeomTraits>`
 - `CGAL::Surface_mesh_simplification::Bounded_normal_change_placement<Placement>`
+- `CGAL::Surface_mesh_simplification::Bounded_normal_change_filter<Filter>`
 - `CGAL::Surface_mesh_simplification::Constrained_placement<Placement, TriangleMesh>`
 */

Surface_mesh_simplification/doc/Surface_mesh_simplification/Surface_mesh_simplification.txt

@@ -336,11 +336,15 @@ results in a self intersection when one edge is collapsed using the Lindstrom-Tu
 Simple mesh before and after the collapse of edge `v-w` into vertex `w`. While the normals of `f1` and `f2` are almost equal, they are opposed after the edge collapse.
 \cgalFigureEnd
 
-The class `Surface_mesh_simplification::Bounded_normal_change_placement` is a placement that checks if
+The class `Surface_mesh_simplification::Bounded_normal_change_filter` checks if
-another placement would invert the normal of a face around the stars of the
+a placement would invert the normal of a face around the stars of the
 two vertices of an edge that is candidate for an edge collapse.  It then
 rejects this placement by returning `boost::none`.
 
+\note This filter class replaces the usage of the class `Surface_mesh_simplification::Bounded_normal_change_placement`.
+Using the filter is faster as it is only performed on the edge to be collapsed next,
+and not during the update on all edges incident to the vertex that is the result of the edhe collapse.
+
 \cgalExample{Surface_mesh_simplification/edge_collapse_bounded_normal_change.cpp}
 
 \subsection Surface_mesh_simplificationExamplewithVisitor Example with Visitor