From cbd7dfc7936462e0b78f393afd7bb26c20a7e42a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Loriot?= Date: Wed, 22 Apr 2020 15:43:46 +0200 Subject: [PATCH] document the new behavior --- AABB_tree/doc/AABB_tree/aabb_tree.txt | 9 +++--- AABB_tree/include/CGAL/AABB_tree.h | 40 ++++++++++++--------------- 2 files changed, 23 insertions(+), 26 deletions(-) diff --git a/AABB_tree/doc/AABB_tree/aabb_tree.txt b/AABB_tree/doc/AABB_tree/aabb_tree.txt index 7bb8e36d7dc..bae44091af3 100644 --- a/AABB_tree/doc/AABB_tree/aabb_tree.txt +++ b/AABB_tree/doc/AABB_tree/aabb_tree.txt @@ -423,10 +423,11 @@ primitives at the leafs of the tree. The ball radius is then shrunk to the distance between `p` and `q` for all remaining recursive traversals of the tree. Efficiency is achieved through setting the initial ball radius to a small value still guaranteed to intersect the -input primitives. This is achieved by constructing through the -function `AABB_tree::accelerate_distance_queries()` an internal secondary data +input primitives. This is achieved by constructing an internal secondary data structure which provides a good hint to the algorithm at the beginning -of the traversal. +of the traversal (done by default). +Calling `do_not_accelerate_distance_queries()` will disable +the construction and the usage of this internal secondary data structure. \section aabb_tree_history Design and Implementation History @@ -437,7 +438,7 @@ queries and primitives was developed by Camille Wormser. In 2009, Pierre Alliez, Stéphane Tayeb and Camille Wormser made the implementation CGAL-compliant, with the help of Laurent Rineau for optimizing the tree construction. The authors wish to thank Andreas -Fabri, Jane Tournois, Mariette Yvinec and Sylvain Lefèbvre for +Fabri, Jane Tournois, Mariette Yvinec and Sylvain Lefèbvre for helpful comments and discussions. */ diff --git a/AABB_tree/include/CGAL/AABB_tree.h b/AABB_tree/include/CGAL/AABB_tree.h index 2e9c17f8327..c4650f5b947 100644 --- a/AABB_tree/include/CGAL/AABB_tree.h +++ b/AABB_tree/include/CGAL/AABB_tree.h @@ -172,7 +172,7 @@ namespace CGAL { } /// Clears the tree and the search tree if it was constructed, - /// and switches on the usage of the search tree to find the hints for the distance queries + /// and switches on the usage of the search tree to find the hint for the distance queries void clear() { // clear AABB tree @@ -344,30 +344,21 @@ public: ///@{ /// Returns the minimum squared distance between the query point - /// and all input primitives. Method - /// `accelerate_distance_queries()` should be called before the - /// first distance query, so that an internal secondary search - /// structure is build, for improving performance. + /// and all input primitives. /// \pre `!empty()` FT squared_distance(const Point& query) const; /// Returns the point in the union of all input primitives which /// is closest to the query. In case there are several closest /// points, one arbitrarily chosen closest point is - /// returned. Method `accelerate_distance_queries()` should be - /// called before the first distance query, so that an internal - /// secondary search structure is build, for improving - /// performance. + /// returned. /// \pre `!empty()` Point closest_point(const Point& query) const; /// Returns a `Point_and_primitive_id` which realizes the /// smallest distance between the query point and all input - /// primitives. Method `accelerate_distance_queries()` should be - /// called before the first distance query, so that an internal - /// secondary search structure is build, for improving - /// performance. + /// primitives. /// \pre `!empty()` Point_and_primitive_id closest_point_and_primitive(const Point& query) const; @@ -407,19 +398,18 @@ public: /// one may want to provide a much better hint than a vertex of /// the triangle soup could be. It could be, for example, the /// barycenter of one of the triangles. But, except with the use - /// of an exact constructions kernel, one cannot easily construct + /// of a kernel with exact constructions, one cannot easily construct /// points other than the vertices, that lie exactly on a triangle /// soup. Hence, providing a good hint sometimes means not being /// able to provide it exactly on the primitives. In rare /// occasions, this hint can be returned as the closest point. /// In order to accelerate distance queries significantly, the /// AABB tree builds an internal KD-tree containing a set of - /// potential hints, when the method - /// `accelerate_distance_queries()` is called. This KD-tree - /// provides very good hints that allow the algorithms to run much - /// faster than with a default hint (such as the - /// `reference_point` of the first primitive). The set of - /// potential hints is a sampling of the union of the primitives, + /// potential hints. This KD-tree provides very good hints + /// that allow the algorithms to run much faster than + /// when `do_not_accelerate_distance_queries()` that makes the + /// hint to always be the `reference_point` of the first primitive. + /// The set of potential hints is a sampling of the union of the primitives, /// which is obtained, by default, by calling the method /// `reference_point` of each of the primitives. However, such /// a sampling with one point per primitive may not be the most @@ -427,18 +417,24 @@ public: /// inserting more than one sample on them. Conversely, a sparser /// sampling with less than one point per input primitive is /// relevant in some cases. + /// The internal KD-tree is always used if no call to `do_not_accelerate_distance_queries()` + /// was made since object creation or the last call to `clear()`. It will be built by + /// the first distance query or by a call to `accelerate_distance_queries()`. ///@{ /// Constructs internal search tree from /// a point set taken on the internal primitives /// returns `true` iff successful memory allocation bool accelerate_distance_queries(); - ///Turns off the lazy construction of the internal search tree. + /// Turns off the usage of the internal search tree and clears it if it was already constructed. void do_not_accelerate_distance_queries(); /// Constructs an internal KD-tree containing the specified point /// set, to be used as the set of potential hints for accelerating - /// the distance queries. + /// the distance queries. Note that the search tree built in + /// this function will not be invalidated by the insertion of a new + /// primitive, and an explicit call to `accelerate_distance_queries()` + /// is needed to update the search tree. /// \tparam ConstPointIterator is an iterator with /// value type `Point_and_primitive_id`. template