From d16be0790603178ac091db0916134d562c38efd3 Mon Sep 17 00:00:00 2001 From: Andreas Fabri Date: Thu, 27 Dec 2012 20:36:04 +0100 Subject: [PATCH] polish AABB Tree --- AABB_tree/doc/AABB_tree/aabb_tree.txt | 18 +++++------ .../CGAL/AABB_polyhedron_segment_primitive.h | 5 ++-- .../CGAL/AABB_polyhedron_triangle_primitive.h | 5 ++-- AABB_tree/include/CGAL/AABB_traits.h | 11 ++++--- AABB_tree/include/CGAL/AABB_tree.h | 30 +++++++++---------- 5 files changed, 35 insertions(+), 34 deletions(-) diff --git a/AABB_tree/doc/AABB_tree/aabb_tree.txt b/AABB_tree/doc/AABB_tree/aabb_tree.txt index a46d2c0063b..c00ed75fcb2 100644 --- a/AABB_tree/doc/AABB_tree/aabb_tree.txt +++ b/AABB_tree/doc/AABB_tree/aabb_tree.txt @@ -61,15 +61,15 @@ objects. Tests: -- Function AABB_tree::do_intersect() tests if the input primitives are +- Function `AABB_tree::do_intersect()` tests if the input primitives are intersected by the query. This function is fast as it involves only predicates and stops after the first encountered intersection. -- Function AABB_tree::number_of_intersected_primitives counts all +- Function `AABB_tree::number_of_intersected_primitives()` counts all intersected primitives. -- Function AABB_tree::all_intersected_primitives enumerates all intersected +- Function `AABB_tree::all_intersected_primitives()` enumerates all intersected primitives ids without constructing the corresponding intersection objects. -- Function AABB_tree::any_intersected_primitive returns the first +- Function `AABB_tree::any_intersected_primitive()` returns the first encountered intersecting primitive id (if any) without constructing the corresponding intersection object, and stops after the first encountered intersection. Note that the traversal order of the tree is @@ -78,9 +78,9 @@ the intersections with respect to the query. Constructions: -- Function AABB_tree::all_intersections() detects and constructs all +- Function `AABB_tree::all_intersections()` detects and constructs all intersection objects with the input primitives. -- Function AABB_tree::any_intersection() detects and constructs the first +- Function `AABB_tree::any_intersection()` detects and constructs the first encountered intersection and constructs the corresponding object. This function is fast as it stops after the first encountered intersection. @@ -156,7 +156,7 @@ triangle query and the closest point from a point query. The AABB tree is a static data structure, but it allows to insert primitives, and will internally rebuild triggered by the first query, -or because the user calls the `AABB_tree::build` method. The following +or because the user calls the `AABB_tree::build()` method. The following example illustrates this for two polyhedral surfaces. \include AABB_insertion_example.cpp @@ -267,7 +267,7 @@ surface mesh. \cgalFigureBegin{figAABB-tree-bench,bench.png} -Number of queries per second against number of triangles for the knot model with 14K (shown), 57K, 230K and 921K triangles. We call the `all_intersections` function with segment queries randomly chosen within the bounding box. +Number of queries per second against number of triangles for the knot model with 14K (shown), 57K, 230K and 921K triangles. We call the `all_intersections()` function with segment queries randomly chosen within the bounding box. \cgalFigureEnd The following table measures the number of `AABB_tree::all_intersections()` @@ -322,7 +322,7 @@ query and location of query in space. - %Kernel: The type of \cgal kernel turns out to dominate the final execution times, the maximum performances being obtained with the - simple Cartesian kernel parameterized with the double precision + `Simple_cartesian` kernel parameterized with the double precision number type. In applications where the intersection and distance execution times are crucial it is possible to use this kernel for the AABB tree in combination with a more robust kernel for the main diff --git a/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h b/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h index 04c5ea24253..84cd551e67e 100644 --- a/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h +++ b/AABB_tree/include/CGAL/AABB_polyhedron_segment_primitive.h @@ -39,10 +39,11 @@ namespace CGAL { /// AABB tree is built should not be deleted while the AABB tree /// is in use. /// - /// The template parameter \c GeomTraits provides a \c %Point_3 + /// \tparam GeomTraits must provide a \c %Point_3 /// type, used as \c Point, and a \c %Segment_3 type, used as \c /// Datum and constructible from two arguments of type \c - /// Point. The template parameter \c Polyhedron should be a + /// Point. + /// \tparam Polyhedron must be a /// \c CGAL::Polyhedron_3 whose points have type \c Point. /// /// \sa \ref AABBPrimitive diff --git a/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h b/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h index 4f579c69294..495db426c33 100644 --- a/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h +++ b/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h @@ -35,10 +35,11 @@ namespace CGAL { /// the polyhedron from which the AABB tree is built should not be /// deleted while the AABB tree is in use. /// - /// The template parameter \c GeomTraits provides a \c %Point_3 + /// \tparam GeomTraits must provides a \c %Point_3 /// type, used as \c Point, and a \c %Triangle_3 type, used as \c /// Datum and constructible from three arguments of type \c - /// Point. The template parameter \c Polyhedron should be a + /// Point. + /// \tparam Polyhedron must be a /// \c CGAL::Polyhedron_3 whose points have type \c Point. /// /// \sa \ref AABBPrimitive diff --git a/AABB_tree/include/CGAL/AABB_traits.h b/AABB_tree/include/CGAL/AABB_traits.h index d2fcb4087ca..d5a15084746 100644 --- a/AABB_tree/include/CGAL/AABB_traits.h +++ b/AABB_tree/include/CGAL/AABB_traits.h @@ -44,12 +44,11 @@ namespace CGAL { /// constructions are implemented. It handles points, rays, lines and /// segments as query types for intersection detection and /// computations, and it handles points as query type for distance -/// queries. The template parameter \c GeomTraits provides the -/// geometric types as well as the intersection tests and computations -/// required. This type must be a model of the concept \ref AABBGeomTraits. -/// The template parameter \c Primitive provides the -/// type of primitives stored in the AABB_tree. This parameter must be -/// a model of the concept \ref AABBPrimitive. +/// queries. +/// \tparam GeomTraits must be a model of the concept \ref AABBGeomTraits, +/// snd provide the geometric types as well as the intersection tests and computations. +/// \tparam Primitive must be a model of the concept \ref AABBPrimitive and provide the +/// type of primitives stored in the AABB_tree. /// /// \sa \ref AABBTraits /// \sa AABB_tree diff --git a/AABB_tree/include/CGAL/AABB_tree.h b/AABB_tree/include/CGAL/AABB_tree.h index 0230bd29c91..aabddbd4255 100644 --- a/AABB_tree/include/CGAL/AABB_tree.h +++ b/AABB_tree/include/CGAL/AABB_tree.h @@ -128,21 +128,21 @@ namespace CGAL { template void rebuild(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond); - /// Add a sequence of primitives to the set of primitive of the - /// AABB_tree. Type InputIterator can be any const iterator - /// such that AABB_tree::Primitive has a constructor taking an - /// InputIterator as argument. + /// Adds a sequence of primitives to the set of primitives of the + /// tree. Type ConstPrimitiveIterator can be any const iterator + /// such that `AABB_tree::Primitive` has a constructor taking an + /// ConstPrimitiveIterator as argument. template void insert(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond); - /// Add a primitive to the set of primitives of the AABB_tree. + /// Adds a primitive to the set of primitives of the tree. inline void insert(const Primitive& p); /// \name Advanced ///@{ - /// After one or more calls to AABB_tree::insert the internal data - /// structure of AABB_tree must be reconstructed. This procedure + /// After one or more calls to `AABB_tree::insert()` the internal data + /// structure of the tree must be reconstructed. This procedure /// has a complexity of \f$O(n log(n))\f$, where \f$n\f$ is the number of /// primitives of the tree. This procedure is called implicitly /// at the first call to a query member function. You can call @@ -153,13 +153,13 @@ namespace CGAL { ///@} - // Non virtual destructor + // Non virtual destructor. ~AABB_tree() { clear(); } - /// Clears the tree AABB_tree. + /// Clears the tree. void clear() { // clear AABB tree @@ -174,7 +174,7 @@ namespace CGAL { /// Returns the number of primitives in the tree. size_type size() const { return m_primitives.size(); } - /// Returns \c true, iff tree contains no primitive. + /// Returns \c true, iff the tree contains no primitive. bool empty() const { return m_primitives.empty(); } private: @@ -202,7 +202,7 @@ public: /// Outputs to the iterator the list of all intersected primitives /// ids. This function does not compute the intersection points - /// and is hence faster than the function `all_intersections` + /// and is hence faster than the function `all_intersections()` /// function below. Type `Query` must be a type for which /// `do_intersect` predicates are defined /// in the traits class AABBTraits. @@ -252,7 +252,7 @@ public: /// Returns the minimum squared distance between the query point /// and all input primitives. Method - /// `accelerate_distance_queries` should be called before the + /// `accelerate_distance_queries()` should be called before the /// first distance query, so that an internal secondary search /// structure is build, for improving performance. FT squared_distance(const Point& query) const; @@ -260,7 +260,7 @@ public: /// 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 + /// 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. @@ -269,7 +269,7 @@ public: /// 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 + /// 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. @@ -319,7 +319,7 @@ public: /// 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 + /// `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