From 3e20800b7fa03ef9bebe9d954c2c8a75d0396a32 Mon Sep 17 00:00:00 2001 From: JacksonCampolattaro Date: Fri, 8 Sep 2023 12:13:27 +0200 Subject: [PATCH] Update documentation for Traits concepts --- .../CollectionPartitioningOrthtreeTraits.h | 9 +- .../doc/Orthtree/Concepts/OrthtreeTraits.h | 101 ++++++++++-------- .../Orthtree/quadtree_build_manually.cpp | 4 +- Orthtree/include/CGAL/Orthtree.h | 4 +- .../include/CGAL/Orthtree_traits_face_graph.h | 6 +- Orthtree/include/CGAL/Orthtree_traits_point.h | 4 +- 6 files changed, 69 insertions(+), 59 deletions(-) diff --git a/Orthtree/doc/Orthtree/Concepts/CollectionPartitioningOrthtreeTraits.h b/Orthtree/doc/Orthtree/Concepts/CollectionPartitioningOrthtreeTraits.h index e56e8578668..19b21aa71a9 100644 --- a/Orthtree/doc/Orthtree/Concepts/CollectionPartitioningOrthtreeTraits.h +++ b/Orthtree/doc/Orthtree/Concepts/CollectionPartitioningOrthtreeTraits.h @@ -12,10 +12,7 @@ \cgalRefines{OrthtreeTraits} - todo: update list of models - \cgalHasModel `CGAL::Orthtree_traits_2` - \cgalHasModel `CGAL::Orthtree_traits_3` - \cgalHasModel `CGAL::Orthtree_traits_d` + \cgalHasModel `CGAL::Orthtree_traits_point` */ class CollectionPartitioningOrthtreeTraits { public: @@ -50,8 +47,8 @@ public: /// @{ /*! - Function used to construct an object of type `Get_geometric_object_for_element`. - */ + * Function used to construct an object of type `Get_geometric_object_for_element`. + */ Get_geometric_object_for_element get_geometric_object_for_element_object() const; /// @} diff --git a/Orthtree/doc/Orthtree/Concepts/OrthtreeTraits.h b/Orthtree/doc/Orthtree/Concepts/OrthtreeTraits.h index fc9e369659f..4360ede2488 100644 --- a/Orthtree/doc/Orthtree/Concepts/OrthtreeTraits.h +++ b/Orthtree/doc/Orthtree/Concepts/OrthtreeTraits.h @@ -5,10 +5,8 @@ The concept `OrthtreeTraits` defines the requirements for the template parameter of the `CGAL::Orthtree` class. - todo: update list of models - \cgalHasModel `CGAL::Orthtree_traits_2` - \cgalHasModel `CGAL::Orthtree_traits_3` - \cgalHasModel `CGAL::Orthtree_traits_d` + \cgalHasModel `CGAL::Orthtree_traits_point` + \cgalHasModel `CGAL::Orthtree_traits_face_graph` */ class OrthtreeTraits { @@ -25,6 +23,8 @@ public: /*! A random access iterator type to enumerate the %Cartesian coordinates of a point. + + todo: This isn't used, should it be? */ typedef unspecified_type Cartesian_const_iterator_d; @@ -34,11 +34,54 @@ public: */ typedef unspecified_type Node_data; + /*! + * \brief Number-type which can take on values indicating adjacency directions. + * + * Must be able to take on values ranging from 0 to the number of faces of the (hyper)cube type, equivalent to 2 * D. + */ typedef unspecified_type Adjacency; ///< Specify the adjacency directions /*! - Functor with an operator to construct a `Point_d` from an appropriate number of x, y, z etc. FT arguments. - */ + * \brief Functor with an operator to create the bounding box of the root node. + * + * The bounding box must enclose all elements contained by the tree. + * It may be tight-fitting. The orthtree constructor produces a bounding cube surrounding this region. + * For traits which assign no data to each node, this can be defined to return a fixed region. + */ + typedef unspecified_type Construct_root_node_bbox; + + /*! + * \brief Functor which initializes the contained elements for the root node. + * + * Each node of a tree has an associated `Node_data` value. + * For most nodes, this is set by `Distribute_node_contents`, but that is not possible for the root node. + * Instead, this functor initializes the `Node_data` of the root node. + * It should take no arguments, and return an instance of `Node_data`. + * + * Typically, the `Node_data` of the root node contains all the elements in the tree. + * For a tree in which each node contains an `std::span` this function would return the span containing all items. + * + */ + typedef unspecified_type Construct_root_node_contents; + + /*! + * \brief Functor which distributes a node's contents to its children. + * + * The functor takes a node index, a tree reference, and a Point_d which is the center of the node. + * It can use tree.children(node_index) to access the children of the node, and tree.data(node_index) + * to access the contents of the node and each of its children. + * It should distribute the contents of the node to each of its children. + * For a tree in which each node contains a span, this may mean rearranging the contents of the original node + * and producing spans containing a subset of its contents for each of its children. + */ + typedef unspecified_type Distribute_node_contents; + + /*! + * \brief Functor with an operator to construct a `Point_d` from an appropriate number of x, y, z etc. FT arguments. + * + * For trees which use a different kernel for the Bbox type, + * the return type of this functor must match the kernel used by the Bbox and not that of the contents. + */ typedef unspecified_type Construct_point_d; /// @} @@ -47,52 +90,24 @@ public: /// @{ /*! - Function used to construct an object of type `Construct_point_d`. - */ - Construct_point_d construct_point_d() const; + * Function used to construct an object of type `Construct_root_node_bbox`. + */ + Construct_root_node_bbox construct_root_node_bbox_object() const; /*! - * \brief Produces a bounding box which encloses the contents of the tree - * - * The bounding box must enclose all elements contained by the tree. - * It may be tight-fitting, the orthtree constructor produces a bounding cube surrounding this region. - * For traits which assign no data to each node, this can be defined to return a fixed region. - * - * @return std::pair, where min and max represent cartesian corners which define a bounding box + * Function used to construct an object of type `Construct_root_node_contents`. */ - Bbox_d root_node_bbox() const; + Construct_root_node_contents construct_root_node_contents_object() const; /*! - * \brief Initializes the contained elements for the root node. - * - * Typically produces a `Node_data` which contains all the elements in the tree. - * e.g. For a tree where each node contains a set of points, - * root_node_contents() will produce the list of all points. - * - * @return The `Node_data` instance to be contained by the root node + * Function used to construct an object of type `Distribute_node_contents`. */ - Node_data root_node_contents() const; + Distribute_node_contents distribute_node_contents_object() const; /*! - * \brief Distributes the `Node_data` contents of a node to its immediate children. - * - * Invoked after a node is split. - * Adds the contents of the node n to each of its children. - * May rearrange or modify n's `Node_data`, but generally expected not to reset n. - * After distributing n's contents, n should still have an list of elements it encloses. - * Each of n's children should have an accurate list of the subset of elements within n they enclose. - * - * For an empty tree, this can be a null-op. - * - * @tparam Node_index The index type used by an orthtree implementation - * @tparam Tree An Orthree implementation - * - * @param n The index of the node who's contents must be distributed. - * @param tree The Orthtree which n belongs to - * @param center The coordinate center of the node n, which its contents should be split around. + * Function used to construct an object of type `Construct_point_d`. */ - template - void distribute_node_contents(Node_index n, Tree& tree, const Point_d& center); + Construct_point_d construct_point_d_object() const; /// @} }; diff --git a/Orthtree/examples/Orthtree/quadtree_build_manually.cpp b/Orthtree/examples/Orthtree/quadtree_build_manually.cpp index f0fe27d1f20..73808cc603b 100644 --- a/Orthtree/examples/Orthtree/quadtree_build_manually.cpp +++ b/Orthtree/examples/Orthtree/quadtree_build_manually.cpp @@ -23,11 +23,11 @@ struct Orthtree_traits_empty : public Orthtree_traits_base_for_dimension typename Self::Bbox_d { return m_bbox; }; } - auto root_node_contents_object() const { return [&]() -> Node_data { return {}; }; } + auto construct_root_node_contents_object() const { return [&]() -> Node_data { return {}; }; } auto distribute_node_contents_object() { return [&](typename Tree::Node_index n, Tree& tree, const typename Self::Point_d& center) -> void {}; diff --git a/Orthtree/include/CGAL/Orthtree.h b/Orthtree/include/CGAL/Orthtree.h index 9172e5d3e23..6bfabf30885 100644 --- a/Orthtree/include/CGAL/Orthtree.h +++ b/Orthtree/include/CGAL/Orthtree.h @@ -214,7 +214,7 @@ public: m_node_properties.emplace(); // init bbox with first values found - auto bbox = m_traits.root_node_bbox_object()(); + auto bbox = m_traits.construct_root_node_bbox_object()(); // Determine dimensions of the root bbox Bbox_dimensions size; @@ -224,7 +224,7 @@ public: // save orthtree attributes m_bbox_min = bbox.min(); m_side_per_depth.push_back(size); - data(root()) = m_traits.root_node_contents_object()(); + data(root()) = m_traits.construct_root_node_contents_object()(); } /// @} diff --git a/Orthtree/include/CGAL/Orthtree_traits_face_graph.h b/Orthtree/include/CGAL/Orthtree_traits_face_graph.h index 144564ebf79..547f02846a8 100644 --- a/Orthtree/include/CGAL/Orthtree_traits_face_graph.h +++ b/Orthtree/include/CGAL/Orthtree_traits_face_graph.h @@ -50,7 +50,7 @@ struct Orthtree_traits_face_graph : public Orthtree_traits_base_for_dimension< using Geom_traits = typename Kernel_traits::type; - auto root_node_bbox_object() const { + auto construct_root_node_bbox_object() const { return [&]() -> Bbox_d { std::array min = {0.0, 0}, max = {0.0, 0}; @@ -72,8 +72,7 @@ struct Orthtree_traits_face_graph : public Orthtree_traits_base_for_dimension< }; } - // SL: not clear to me what it should do from the doc - auto root_node_contents_object() { + auto construct_root_node_contents_object() { return [&]() -> Node_data { return {faces(m_pm).begin(), faces(m_pm).end()}; }; @@ -99,7 +98,6 @@ struct Orthtree_traits_face_graph : public Orthtree_traits_base_for_dimension< }; } - //SL: I find convenient to put it here class Split_predicate_node_min_extent { FT m_min_extent; diff --git a/Orthtree/include/CGAL/Orthtree_traits_point.h b/Orthtree/include/CGAL/Orthtree_traits_point.h index dd4803e07bf..001bd5fc1ab 100644 --- a/Orthtree/include/CGAL/Orthtree_traits_point.h +++ b/Orthtree/include/CGAL/Orthtree_traits_point.h @@ -104,7 +104,7 @@ public: /// \name Operations /// @{ - auto root_node_bbox_object() const { + auto construct_root_node_bbox_object() const { return [&]() -> typename Self::Bbox_d { std::array bbox_min, bbox_max; @@ -136,7 +136,7 @@ public: }; } - auto root_node_contents_object() const { + auto construct_root_node_contents_object() const { return [&]() -> typename Self::Node_data { return {m_point_set.begin(), m_point_set.end()}; };