mirror of https://github.com/CGAL/cgal
Improve the documentation of the class template AABB_tree
- Group the documented methods that were not. - Document typedefs that are used in the methods declarations. - Use \tparam when relevant. - Fix a comment block that was prefixed with ' ///' or '\t\t///' depending on the lines. That one is particularily nasty because the difference between lines is invisible. But that was confusing Doxygen. - plus minor fixes
This commit is contained in:
Laurent Rineau
parent
3b1ba8ba70
commit
65750effb1
|
|
@ -54,11 +54,17 @@ namespace CGAL {
|
|||
template <typename AABBTraits>
|
||||
class AABB_tree
|
||||
{
|
||||
private:
|
||||
// internal KD-tree used to accelerate the distance queries
|
||||
typedef AABB_search_tree<AABBTraits> Search_tree;
|
||||
|
||||
// type of the primitives container
|
||||
typedef std::vector<typename AABBTraits::Primitive> Primitives;
|
||||
|
||||
public:
|
||||
typedef AABBTraits AABB_traits;
|
||||
|
||||
typedef typename AABBTraits::Primitive::Id Primitive_id;
|
||||
|
||||
/// \name Types
|
||||
///@{
|
||||
|
||||
/// Number type returned by the distance queries.
|
||||
|
|
@ -70,6 +76,10 @@ namespace CGAL {
|
|||
|
||||
/// Type of input primitive.
|
||||
typedef typename AABBTraits::Primitive Primitive;
|
||||
/// Identifier for a primitive in the tree.
|
||||
typedef typename Primitive::Id Primitive_id;
|
||||
/// Unsigned integral size type.
|
||||
typedef typename Primitives::size_type size_type;
|
||||
/// Type of bounding box.
|
||||
typedef typename AABBTraits::Bounding_box Bounding_box;
|
||||
///
|
||||
|
|
@ -77,59 +87,42 @@ namespace CGAL {
|
|||
///
|
||||
typedef typename AABBTraits::Object_and_primitive_id Object_and_primitive_id;
|
||||
|
||||
///@}
|
||||
|
||||
private:
|
||||
// internal KD-tree used to accelerate the distance queries
|
||||
typedef AABB_search_tree<AABBTraits> Search_tree;
|
||||
|
||||
// type of the primitives container
|
||||
typedef std::vector<Primitive> Primitives;
|
||||
|
||||
public:
|
||||
/// \name Types
|
||||
///@{
|
||||
|
||||
/// Unsigned integral size type.
|
||||
typedef typename Primitives::size_type size_type;
|
||||
|
||||
///@}
|
||||
|
||||
public:
|
||||
/// \name Creation
|
||||
///@{
|
||||
|
||||
/**
|
||||
* @brief %Default Constructor.
|
||||
*
|
||||
* Constructs an empty tree.
|
||||
*/
|
||||
/// Constructs an empty tree.
|
||||
AABB_tree();
|
||||
|
||||
/**
|
||||
* @brief Constructor
|
||||
* @brief Builds the datastructure from a sequence of primitives.
|
||||
* @param first iterator over first primitive to insert
|
||||
* @param beyond past-the-end iterator
|
||||
*
|
||||
* Builds the datastructure. Type ConstPrimitiveIterator can be
|
||||
* The tree stays empty if the memory allocation is not successful.
|
||||
* \tparam ConstPrimitiveIterator can be
|
||||
* any const iterator on a container of
|
||||
* AABB_tree::Primitive::id_type such that AABB_tree::Primitive
|
||||
* has a constructor taking a ConstPrimitiveIterator as
|
||||
* argument. The tree stays empty if the memory allocation is not
|
||||
* successful.
|
||||
* argument.
|
||||
*/
|
||||
template<typename ConstPrimitiveIterator>
|
||||
AABB_tree(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond);
|
||||
|
||||
///@}
|
||||
|
||||
/// \name Operations
|
||||
///@{
|
||||
|
||||
/// Clears the current tree and rebuilds it from scratch. See
|
||||
/// constructor above for the parameters.
|
||||
template<typename ConstPrimitiveIterator>
|
||||
void rebuild(ConstPrimitiveIterator first, ConstPrimitiveIterator beyond);
|
||||
|
||||
/// Adds a sequence of primitives to the set of primitives of the
|
||||
/// tree. Type ConstPrimitiveIterator can be any const iterator
|
||||
/// tree. \tparam ConstPrimitiveIterator can be any const iterator
|
||||
/// such that `AABB_tree::Primitive` has a constructor taking an
|
||||
/// ConstPrimitiveIterator as argument.
|
||||
template<typename ConstPrimitiveIterator>
|
||||
|
|
@ -138,22 +131,7 @@ namespace CGAL {
|
|||
/// 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 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
|
||||
/// AABB_tree::build() explicitly to ensure that the next call to
|
||||
/// query functions will not trigger the reconstruction of the
|
||||
/// data structure.
|
||||
void build();
|
||||
|
||||
///@}
|
||||
|
||||
// Non virtual destructor.
|
||||
/// Clears and destroys the tree.
|
||||
~AABB_tree()
|
||||
{
|
||||
clear();
|
||||
|
|
@ -176,6 +154,22 @@ namespace CGAL {
|
|||
|
||||
/// Returns \c true, iff the tree contains no primitive.
|
||||
bool empty() const { return m_primitives.empty(); }
|
||||
///@}
|
||||
|
||||
/// \name Advanced
|
||||
///@{
|
||||
|
||||
/// 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
|
||||
/// AABB_tree::build() explicitly to ensure that the next call to
|
||||
/// query functions will not trigger the reconstruction of the
|
||||
/// data structure.
|
||||
void build();
|
||||
|
||||
///@}
|
||||
|
||||
private:
|
||||
template<typename ConstPointIterator>
|
||||
|
|
@ -187,25 +181,25 @@ public:
|
|||
///@{
|
||||
|
||||
/// Returns `true`, iff the query intersects at least one of
|
||||
/// the input primitives. Type `Query` must be a type for
|
||||
/// the input primitives. \tparam Query must be a type for
|
||||
/// which `do_intersect` predicates are
|
||||
/// defined in the traits class AABBTraits.
|
||||
/// defined in the traits class `AABBTraits`.
|
||||
template<typename Query>
|
||||
bool do_intersect(const Query& query) const;
|
||||
|
||||
/// Returns the number of primitives intersected by the
|
||||
/// query. Type `Query` must be a type for which
|
||||
/// query. \tparam Query must be a type for which
|
||||
/// `do_intersect` predicates are defined
|
||||
/// in the traits class AABBTraits.
|
||||
/// in the traits class `AABBTraits`.
|
||||
template<typename Query>
|
||||
size_type number_of_intersected_primitives(const Query& query) const;
|
||||
|
||||
/// 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()`
|
||||
/// function below. Type `Query` must be a type for which
|
||||
/// function below. \tparam Query must be a type for which
|
||||
/// `do_intersect` predicates are defined
|
||||
/// in the traits class AABBTraits.
|
||||
/// in the traits class `AABBTraits`.
|
||||
template<typename Query, typename OutputIterator>
|
||||
OutputIterator all_intersected_primitives(const Query& query, OutputIterator out) const;
|
||||
|
||||
|
|
@ -214,10 +208,10 @@ public:
|
|||
/// the query intersects at least one of the input primitives. No
|
||||
/// particular order is guaranteed over the tree traversal, such
|
||||
/// that, e.g, the primitive returned is not necessarily the
|
||||
/// closest from the source point of a ray query. Type `Query`
|
||||
/// closest from the source point of a ray query. \tparam Query
|
||||
/// must be a type for which
|
||||
/// `do_intersect` predicates are defined
|
||||
/// in the traits class AABBTraits.
|
||||
/// in the traits class `AABBTraits`.
|
||||
template <typename Query>
|
||||
boost::optional<Primitive_id> any_intersected_primitive(const Query& query) const;
|
||||
|
||||
|
|
@ -228,9 +222,9 @@ public:
|
|||
|
||||
/// Outputs to the iterator the list of all intersections between
|
||||
/// the query and input data, as objects of type
|
||||
/// `Object_and_primitive_id`. Type `Query` must be a type
|
||||
/// `Object_and_primitive_id`. \tparam Query must be a type
|
||||
/// for which `do_intersect` predicates
|
||||
/// and intersections are defined in the traits class AABBTraits.
|
||||
/// and intersections are defined in the traits class `AABBTraits`.
|
||||
template<typename Query, typename OutputIterator>
|
||||
OutputIterator all_intersections(const Query& query, OutputIterator out) const;
|
||||
|
||||
|
|
@ -239,7 +233,7 @@ public:
|
|||
/// intersects at least one of the input primitives. No particular
|
||||
/// order is guaranteed over the tree traversal, such that, e.g,
|
||||
/// the primitive returned is not necessarily the closest from the
|
||||
/// source point of a ray query. Type `Query` must be a type
|
||||
/// source point of a ray query. \tparam Query must be a type
|
||||
/// for which `do_intersect` predicates
|
||||
/// and intersections are defined in the traits class AABBTraits.
|
||||
template <typename Query>
|
||||
|
|
@ -335,12 +329,13 @@ public:
|
|||
|
||||
/// Constructs internal search tree from
|
||||
/// a point set taken on the internal primitives
|
||||
/// returns true iff successful memory allocation
|
||||
/// returns `true` iff successful memory allocation
|
||||
bool accelerate_distance_queries() const;
|
||||
|
||||
/// Constructs an internal KD-tree containing the specified point
|
||||
/// set, to be used as the set of potential hints for accelerating
|
||||
/// the distance queries. `InputIterator` is an iterator with
|
||||
/// the distance queries.
|
||||
/// \tparam `ConstPointIterator` is an iterator with
|
||||
/// value type `Point_and_primitive_id`.
|
||||
template<typename ConstPointIterator>
|
||||
bool accelerate_distance_queries(ConstPointIterator first,
|
||||
|
|
|
|||
Loading…
Reference in New Issue