From 85bb0775e8e126329ecce96c3b3d338a98d28b14 Mon Sep 17 00:00:00 2001 From: Andreas Fabri Date: Mon, 2 Nov 2020 14:44:46 +0000 Subject: [PATCH] Improve documentation --- .../Polygon_mesh_processing.txt | 6 +++--- .../include/CGAL/Envelope.h | 8 ++++---- .../Policies/Edge_collapse/Envelope_filter.h | 2 +- .../Concepts/GetCost.h | 3 +-- .../Concepts/GetFilter.h | 11 +++++++---- .../Concepts/GetPlacement.h | 2 +- .../Surface_mesh_simplification.txt | 19 +++++++++++++++---- 7 files changed, 32 insertions(+), 19 deletions(-) diff --git a/Polygon_mesh_processing/doc/Polygon_mesh_processing/Polygon_mesh_processing.txt b/Polygon_mesh_processing/doc/Polygon_mesh_processing/Polygon_mesh_processing.txt index 03196ea3d93..3b02c8e31bd 100644 --- a/Polygon_mesh_processing/doc/Polygon_mesh_processing/Polygon_mesh_processing.txt +++ b/Polygon_mesh_processing/doc/Polygon_mesh_processing/Polygon_mesh_processing.txt @@ -536,11 +536,11 @@ package \refPkgSurfaceMeshSimplification, in order to simplify respecting a tole \subsubsection InsideExample Polyhedral Envelope Example \cgalExample{Polygon_mesh_processing/polyhedral_envelope.cpp} -The algorithm is described in \cgalCite{cgal:wshap-eepec-20} and can be summarized as follows. -First for each triangle a prism is constructed with an offset of \f$ \epsilon/\sqrt(3) \f$, +The algorithm is described in \cgalCite{cgal:Wwshap-eepec-20} and can be summarized as follows. +First for each triangle a prism is constructed with an offset of \f$ \epsilon/\sqrt(3) \f$ where \f$ \epsilon\f$ is the tolerance, and all prisms are stored in an AABB tree. For a query point the algorithm checks if is inside a prism. For a query segment or triangle the algorithms checks if the query is completely covered. -The details of how to check the covering can be found in the paper of Wang et al. \cgalCite{cgal:Wwshap-eepec-20} +The details of how to check this covering can be found in the paper of Wang et al. \subsection PMPShapePredicates Shape Predicates diff --git a/Polygon_mesh_processing/include/CGAL/Envelope.h b/Polygon_mesh_processing/include/CGAL/Envelope.h index 778c34c8922..8163c0326ce 100644 --- a/Polygon_mesh_processing/include/CGAL/Envelope.h +++ b/Polygon_mesh_processing/include/CGAL/Envelope.h @@ -87,7 +87,7 @@ namespace CGAL { /** * \ingroup PkgPolygonMeshProcessingRef * This class provides a test whether a query point, segment, or triangle - * is inside or outside a polyhedral envelope of a triangle soup. + * is inside or outside a polyhedral envelope of a triangle mesh. * * @tparam GeomTraits a geometric traits class, model of `Kernel` */ @@ -1815,7 +1815,7 @@ private: public: /*! - * \returns `true` if the query point is inside the polygonal envelope. + * \returns `true`, iff the query point is inside the polygonal envelope. */ bool @@ -1835,7 +1835,7 @@ public: /*! - * \returns `true` if the query segment is inside the polygonal envelope. + * \returns `true`, iff the query segment defined by the points `source` and `target` is inside the polygonal envelope. */ bool operator()(const Point_3& source, const Point_3& target) const @@ -1855,7 +1855,7 @@ public: /*! - * \returns `true` if the query triangle is inside the envelope. + * \returns `true`, iff the query triangle formed by the points `t0`, `t1`, and `t2` is inside the envelope. */ bool operator()(const Point_3& t0, const Point_3& t1, const Point_3& t2) const diff --git a/Surface_mesh_simplification/doc/Surface_mesh_simplification/CGAL/Surface_mesh_simplification/Policies/Edge_collapse/Envelope_filter.h b/Surface_mesh_simplification/doc/Surface_mesh_simplification/CGAL/Surface_mesh_simplification/Policies/Edge_collapse/Envelope_filter.h index d4335573bd6..840499398af 100644 --- a/Surface_mesh_simplification/doc/Surface_mesh_simplification/CGAL/Surface_mesh_simplification/Policies/Edge_collapse/Envelope_filter.h +++ b/Surface_mesh_simplification/doc/Surface_mesh_simplification/CGAL/Surface_mesh_simplification/Policies/Edge_collapse/Envelope_filter.h @@ -18,7 +18,7 @@ not filter any placement. \sa `Envelope` */ -template +template class Envelope_filter { public: diff --git a/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetCost.h b/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetCost.h index 906bfae3fc8..05cc98d4698 100644 --- a/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetCost.h +++ b/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetCost.h @@ -22,7 +22,7 @@ class GetCost { public: - /// The class Edge_profile regroups useful information about an edge, such as its incident vertices and faces. + /// 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 @@ -38,4 +38,3 @@ public: /// @} }; /* end GetCost */ - diff --git a/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetFilter.h b/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetFilter.h index 3e790a19f6f..c1bff79d2c3 100644 --- a/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetFilter.h +++ b/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetFilter.h @@ -3,7 +3,10 @@ \cgalConcept The concept `GetFilter` describes the requirements for the policy -function object which gets the profile and placement of an edge. +function object which gets the profile and placement of an edge +and which can filter the placement. The filtering is only done when +an edge is taken from the priority queue in order to get collapsed, +and neither when the edge is inserted or updated in the priority queue. 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. @@ -11,8 +14,8 @@ be absent). The value `boost::none` indicates that the edge should not be collap \cgalRefines `DefaultConstructible` \cgalRefines `CopyConstructible` -\cgalHasModel `CGAL::Surface_mesh_simplification::Bounded_normal_change_filter` -\cgalHasModel `CGAL::Surface_mesh_simplification::FastEnvelopeFilter` +\cgalHasModel `CGAL::Surface_mesh_simplification::Bounded_normal_change_filter` +\cgalHasModel `CGAL::Surface_mesh_simplification::Envelope_filter` */ @@ -20,7 +23,7 @@ class GetFilter { public: - /// The class Edge_profile regroups useful information about an edge, such as its incident vertices and faces. + /// 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 diff --git a/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetPlacement.h b/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetPlacement.h index da415685d46..e48fbe8ccb7 100644 --- a/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetPlacement.h +++ b/Surface_mesh_simplification/doc/Surface_mesh_simplification/Concepts/GetPlacement.h @@ -27,7 +27,7 @@ class GetPlacement { public: - /// The class Edge_profile regroups useful information about an edge, such as its incident vertices and faces. + /// 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 diff --git a/Surface_mesh_simplification/doc/Surface_mesh_simplification/Surface_mesh_simplification.txt b/Surface_mesh_simplification/doc/Surface_mesh_simplification/Surface_mesh_simplification.txt index baa73cbbb5c..155ff718379 100644 --- a/Surface_mesh_simplification/doc/Surface_mesh_simplification/Surface_mesh_simplification.txt +++ b/Surface_mesh_simplification/doc/Surface_mesh_simplification/Surface_mesh_simplification.txt @@ -185,8 +185,8 @@ the mesh as much as possible. \subsection Surface_mesh_simplificationCostStrategyPolicies Cost Strategy Policies -The cost strategy used by the algorithm is selected by means of two policies: -`GetPlacement` and `GetCost`. +The cost strategy used by the algorithm is selected by means of three policies: +`GetPlacement`, `GetCost`, and `GetFilter`. The `GetPlacement` policy is called to compute the new position for the remaining vertex after the halfedge-collapse. It returns @@ -209,7 +209,7 @@ But this is a trade-off: the cost of a collapse is a function of the placement (the new position chosen for the remaining vertex) so before `GetCost` is called for each and every edge, `GetPlacement` must also be called to obtain the placement parameter to the cost function. -But that placement, which is a 3D Point, is not attached to each and every edge since +But that placement, which is a 3D point, is not attached to each and every edge since that would easily triple the additional storage requirement. On the one hand, this dramatically saves on memory but on the other hand is a processing waste because when an edge is effectively collapsed, `GetPlacement` @@ -223,6 +223,17 @@ must be called several times just as well. Caching the placement can only avoid very last call, when the edge is collapsed, but not all the previous calls which are needed because the placement (and cost) changes. +We have not yet explained what the `GetFilter` policy is about. +While the cost is a scalar that is used in the priority queue, there may be +additional criteria coming in to decide if the edge collapse shall be performed or not. +While such a criterion could be easily integrated into the cost function, +that is setting the cost to infinity in order not to be considered a candidate for a collapse, +we test the criterion only for an edge when it is the next edge to collapse. +This makes the mesh simplification faster in case the computation of the +criterion is expensive, for example when we check if the simplified mesh +is in a tolerance envelope of the input mesh. + + \section Surface_mesh_simplificationAPI API \subsection Surface_mesh_simplificationAPIOverview API Overview @@ -343,7 +354,7 @@ 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. +and not during the update of all edges incident to the vertex that is the result of the edge collapse. \cgalExample{Surface_mesh_simplification/edge_collapse_bounded_normal_change.cpp}