diff --git a/Orthtree/doc/Orthtree/Orthtree.txt b/Orthtree/doc/Orthtree/Orthtree.txt index 5696b64bc5e..08230bb8f3f 100644 --- a/Orthtree/doc/Orthtree/Orthtree.txt +++ b/Orthtree/doc/Orthtree/Orthtree.txt @@ -61,9 +61,15 @@ behave as a %quadtree. For convenience, the alias `Quadtree` is provided. The following example shows how to create a %quadtree object from a vector of `Point_2` objects and refine it, which means constructing the tree's space subdivision itself, using a maximum depth of 10 and a -maximum number of inliers per node (bucket size) of 5: +maximum number of inliers per node (bucket size) of 5. The refinement +is stopped as soon as one of the condition is violated: if a node has +more inliers than `bucket_size` but is already at `max_depth`, it is +not split. Similarly, a node that is at a depth smaller than +`max_depth` but already has fewer inliers than `bucket_size` is not +split. -\cgalExample{Orthtree/quadtree_build_from_point_vector.cpp} + +\CGALEXAMPLE{Orthtree/quadtree_build_from_point_vector.cpp} \subsection Section_Orthtree_Point_Vector Building an Octree diff --git a/Orthtree/include/CGAL/Orthtree.h b/Orthtree/include/CGAL/Orthtree.h index 3e158360746..fef35cc7c32 100644 --- a/Orthtree/include/CGAL/Orthtree.h +++ b/Orthtree/include/CGAL/Orthtree.h @@ -168,7 +168,15 @@ public: The constructed orthtree has a root node, with no children, that contains the points passed. That root node has a bounding box that encloses all of the points passed, with padding according to the - `enlarge_ratio`. This single-node orthtree is valid and compatible + `enlarge_ratio`. + + That root node is built as a `n`-cube (square in 2D, cube in 3D, + etc.) whose edge size is the longest bounding box edge multiplied + by `enlarge_ratio`. Using an `enlarge_ratio>1.0` prevents some + points from being exactly on the border of some cells, which can + lead to over-refinement. + + This single-node orthtree is valid and compatible with all Orthtree functionality, but any performance benefits are unlikely to be realized until `refine()` is called. @@ -278,8 +286,12 @@ public: The split predicate is a `std::function` that takes a Node and returns a Boolean value (where `true` implies that a Node needs to - be split, `false` that the Node should be a leaf). This function - function may be called several times with different predicate. + be split, `false` that the Node should be a leaf). + + This function function may be called several times with different + predicates: in that case, nodes already split are left unaltered, + while nodes that were not split and for which `split_predicate` + returns `true` are split. \param split_predicate determines whether or not a node needs to be subdivided. @@ -333,7 +345,13 @@ public: This is equivalent to calling `refine(Orthtrees::Maximum_depth_and_maximum_number_of_inliers(min_depth, - bucket_size))` + bucket_size))`. + + The refinement is stopped as soon as one of the condition is + violated: if a node has more inliers than `bucket_size` but is + already at `max_depth`, it is not split. Similarly, a node that is + at a depth smaller than `max_depth` but already has fewer inliers + than `bucket_size`, it is not split. \param max_depth deepest a tree is allowed to be (nodes at this depth will not be split). \param bucket_size maximum points a node is allowed to contain. @@ -420,7 +438,7 @@ public: \sa `Node::operator[]()` \param index the index of the child node. - \return a reference to the node. + \return the accessed node. */ Node operator[](std::size_t index) const { return m_root[index]; } diff --git a/Orthtree/include/CGAL/Orthtree/Node.h b/Orthtree/include/CGAL/Orthtree/Node.h index 31623fdf420..472fcf39724 100644 --- a/Orthtree/include/CGAL/Orthtree/Node.h +++ b/Orthtree/include/CGAL/Orthtree/Node.h @@ -161,15 +161,17 @@ private: /*! \brief creates a new node, optionally as the child of a parent - If no parent is provided, the node created is assumed to be the root of a tree. - This means that the parent reference is a nullptr, and the depth is zero. - If a parent is provided, the node becomes the child of that parent. - In that case, an index should be passed, telling this node its relationship to its parent. - Depth and global coordinates are automatically determined in the constructor, - and should generally be considered immutable after construction. + If no parent is provided, the node created is assumed to be the + root of a tree. This means that `parent.is_null()` returns + `true`, and the depth is zero. If a parent is provided, the node + becomes the child of that parent. In that case, an index should + be passed, telling this node its relationship to its parent. + Depth and global coordinates are automatically determined in the + constructor, and should generally be considered immutable after + construction. - \param parent A reference to the node containing this one - \param index This node's relationship to its parent + \param parent the node containing this one + \param index this node's relationship to its parent */ explicit Node(Self parent, Local_coordinates local_coordinates) : m_data (new Data(parent)) { diff --git a/Orthtree/include/CGAL/Orthtree/Split_predicates.h b/Orthtree/include/CGAL/Orthtree/Split_predicates.h index 2f6f0d97eb4..35d710bdaff 100644 --- a/Orthtree/include/CGAL/Orthtree/Split_predicates.h +++ b/Orthtree/include/CGAL/Orthtree/Split_predicates.h @@ -38,7 +38,7 @@ public: m_bucket_size(bucket_size) {} /*! - \brief returns `true` if `n` should be splitted, `false` otherwise. + \brief returns `true` if `n` should be split, `false` otherwise. */ template bool operator()(const Node &n) const { @@ -50,7 +50,7 @@ public: \ingroup PkgOrthtreeSplitPredicates \brief A class used to choose when a node should be split depending on the depth. - This predicate makes a node splitted if its depth is lower than a certain limit. + This predicate makes a node split if its depth is lower than a certain limit. */ class Maximum_depth { @@ -64,7 +64,7 @@ public: Maximum_depth(std::size_t max_depth) : m_max_depth(max_depth) {} /*! - \brief returns `true` if `n` should be splitted, `false` otherwise. + \brief returns `true` if `n` should be split, `false` otherwise. */ template bool operator()(const Node &n) const { @@ -76,9 +76,16 @@ public: \ingroup PkgOrthtreeSplitPredicates \brief A class used to choose when a node should be split depending on the depth and the number of inliers. - This predicate makes a note splitted if it contains more than a + This predicate makes a note split if it contains more than a certain number of items and if its depth is lower than a certain limit. + + The refinement is stopped as soon as one of the condition is + violated: if a node has more inliers than `bucket_size` but is + already at `max_depth`, it is not split. Similarly, a node that is + at a depth smaller than `max_depth` but already has fewer inliers + than `bucket_size`, it is not split. + */ class Maximum_depth_and_maximum_number_of_inliers { @@ -93,7 +100,7 @@ public: m_max_depth(max_depth), m_bucket_size(bucket_size) {} /*! - \brief returns `true` if `n` should be splitted, `false` otherwise. + \brief returns `true` if `n` should be split, `false` otherwise. */ template