Merge pull request #7672 from JacksonCampolattaro/orthtree-generaliza…

…tion

Orthtree generalization

Installation/CHANGES.md

@@ -44,6 +44,12 @@ Release date: October 2023
 -   Removed the class templates `Gray_image_mesh_domain_3`, `Implicit_mesh_domain_3`, and `Labeled_image_mesh_domain_3`
     which are deprecated since CGAL-4.13.
 
+### [Quadtrees, Octrees, and Orthtrees](https://doc.cgal.org/6.0/Manual/packages.html#PkgOrthtree)
+- **Breaking change**:
+  - Node splitting behavior and per-node data are now customizable via the Traits class.
+  - Nodes are now stored as a property map, with properties of each node accessed by index.
+  - Nearest neighbors functions only work for Orthtrees which provide the necessary functionality.
+
 ### [Polygon Mesh Processing](https://doc.cgal.org/6.0/Manual/packages.html#PkgPolygonMeshProcessing)
 
 -   Added the function `CGAL::Polygon_mesh_processing::interpolated_corrected_curvatures()` which can be used to compute

Orthtree/benchmark/Orthtree/construction.cpp

@@ -12,16 +12,14 @@
 #include <iostream>
 #include <chrono>
 
-typedef CGAL::Exact_predicates_inexact_constructions_kernel Kernel;
-typedef Kernel::Point_3 Point;
-typedef CGAL::Point_set_3<Point> Point_set;
-typedef Point_set::Point_map Point_map;
-
-typedef CGAL::Octree<Kernel, Point_set, Point_map> Octree;
-
-typedef CGAL::Search_traits_3<Kernel> Kd_tree_traits;
-typedef CGAL::Orthogonal_k_neighbor_search<Kd_tree_traits> Kd_tree_search;
-typedef Kd_tree_search::Tree Kdtree;
+using Kernel = CGAL::Exact_predicates_inexact_constructions_kernel;
+using Point = Kernel::Point_3;
+using Point_set = CGAL::Point_set_3<Point>;
+using Point_map = Point_set::Point_map;
+using Octree = CGAL::Octree<Kernel, Point_set, Point_map>;
+using Kd_tree_traits = CGAL::Search_traits_3<Kernel>;
+using Kd_tree_search = CGAL::Orthogonal_k_neighbor_search<Kd_tree_traits>;
+using Kdtree = Kd_tree_search::Tree;
 
 using std::chrono::high_resolution_clock;
 using std::chrono::duration_cast;

Orthtree/benchmark/Orthtree/nearest_neighbor.cpp

@@ -12,21 +12,19 @@
 #include <iostream>
 #include <chrono>
 
-typedef CGAL::Exact_predicates_inexact_constructions_kernel Kernel;
-typedef Kernel::Point_3 Point;
-typedef CGAL::Point_set_3<Point> Point_set;
-typedef Point_set::Point_map Point_map;
-
-typedef CGAL::Octree<Kernel, Point_set, Point_map> Octree;
-
-typedef CGAL::Search_traits_3<Kernel> Kd_tree_traits;
-typedef CGAL::Orthogonal_k_neighbor_search<Kd_tree_traits> Kd_tree_search;
-typedef Kd_tree_search::Tree Kdtree;
-
 using std::chrono::high_resolution_clock;
 using std::chrono::duration_cast;
 using std::chrono::microseconds;
 
+using Kernel = CGAL::Exact_predicates_inexact_constructions_kernel;
+using Point = Kernel::Point_3;
+using Point_set = CGAL::Point_set_3<Point>;
+using Point_map = Point_set::Point_map;
+using Octree = CGAL::Octree<Kernel, Point_set, Point_map>;
+using Kd_tree_traits = CGAL::Search_traits_3<Kernel>;
+using Kd_tree_search = CGAL::Orthogonal_k_neighbor_search<Kd_tree_traits>;
+using Kdtree = Kd_tree_search::Tree;
+
 int main(int argc, char **argv) {
 
   int num_runs = 100;
@@ -103,8 +101,8 @@ int main(int argc, char **argv) {
       // Time how long it takes to find neighbors using the octree
       auto octreeTime = bench<microseconds>(
               [&] {
-                std::vector<Point> nearest_neighbors;
-                octree.nearest_neighbors(search_point, k, std::back_inserter(nearest_neighbors));
+                std::vector<Point_set::Index> nearest_neighbors;
+                octree.nearest_k_neighbors(search_point, k, std::back_inserter(nearest_neighbors));
               }
       );
 

Orthtree/benchmark/Orthtree/util.h

@@ -10,8 +10,8 @@
 template<class Kernel>
 CGAL::Point_set_3<typename Kernel::Point_3> generate(size_t num_points = 1) {
 
-  typedef typename Kernel::Point_3 Point;
-  typedef CGAL::Point_set_3<Point> Point_set;
+  using Point = typename Kernel::Point_3;
+  using Point_set = CGAL::Point_set_3<Point>;
 
   // Create an empty point set
   Point_set points;

Orthtree/doc/Orthtree/Concepts/CollectionPartitioningOrthtreeTraits.h

@@ -0,0 +1,101 @@
+/*!
+  \ingroup PkgOrthtreeConcepts
+  \cgalConcept
+
+  Refinement of the `OrthtreeTraitsWithData` concept, adding requirements for the
+  traits class of a `CGAL::Orthtree` in order to supports nearest-neighbor searching.
+
+  Nearest neighbor searches expect a tree where `Node_data` is a model of `ForwardRange`.
+  The leaf nodes of the tree represent an exclusive partition of the elements contained in the tree.
+  This means that no element should be contained by more than one node.
+
+  \cgalRefines{OrthtreeTraitsWithData}
+
+  \cgalHasModelsBegin
+  \cgalHasModels{CGAL::Orthtree_traits_point<GeomTraits, PointRange, PointMap, DimensionTag>}
+  \cgalHasModelsEnd
+*/
+class CollectionPartitioningOrthtreeTraits {
+public:
+
+
+  /// \name Types
+  /// @{
+
+  /*!
+   * Sphere Type used for the shrinking-sphere approach for neighbor queries; needs to be copy assignable.
+   */
+  using Sphere_d = unspecified_type;
+
+  /*!
+   * \brief The data type contained by each node; must be a model of `ForwardRange` in addition to default constructible, copy constructible and copy assignable.
+   */
+  using Node_data = unspecified_type;
+
+  /*!
+   * \brief An element of the `Node_data` list-like type.
+   *
+   * Must be constructible from the value type of a `Node_data::iterator`.
+   * Typically the same as that type, but can also be an `std::reference_wrapper<>` if the type is not copyable.
+   */
+  using Node_data_element = unspecified_type;
+
+  /*!
+   * \brief Functor with an operator that calculates the squared distance of a `Node_data_element` from a point.
+   *
+   * Provides the operator:
+   * `FT operator()(const Node_data_element&, const Point_d&)`
+   */
+  using Squared_distance_of_element = unspecified_type;
+
+  /*!
+   * \brief Functor with an operator that constructs a `Sphere_d` from a provided center and squared radius.
+   *
+   * Provides the operator:
+   * `Sphere_d operator()(const Point_d&, const FT&)`
+  */
+  using Construct_sphere_d = unspecified_type;
+
+  /*!
+   * \brief Functor with an operator that provides the center of a `Sphere_d`.
+   *
+   * Provides the operator:
+   * `Point_d operator()(const Sphere_d&)`
+  */
+  using Construct_center_d = unspecified_type;
+
+  /*!
+   * \brief Functor with an operator that provides the squared radius of a `Sphere_d`.
+   *
+   * Provides the operator:
+   * `FT operator()(const Sphere_d&)`
+  */
+  using Compute_squared_radius_d = unspecified_type;
+
+  /// @}
+
+  /// \name Operations
+  /// @{
+
+  /*!
+   * constructs an object of type `ConstructSphere_d`.
+   */
+  Construct_sphere_d construct_sphere_d_object() const;
+
+  /*!
+   * constructs an object of type `ConstructCenter_d`.
+   */
+  Construct_center_d construct_center_d_object() const;
+
+  /*!
+   * constructs an object of type `ComputeSquaredRadius_d`.
+   */
+  Compute_squared_radius_d compute_squared_radius_d_object() const;
+
+  /*!
+   * constructs an object of type `Squared_distance_of_element`.
+   */
+  Squared_distance_of_element squared_distance_of_element_object() const;
+
+  /// @}
+};

Orthtree/doc/Orthtree/Concepts/OrthtreeTraits.h

@@ -6,9 +6,9 @@
   template parameter of the `CGAL::Orthtree` class.
 
   \cgalHasModelsBegin
-  \cgalHasModels{CGAL::Orthtree_traits_2<GeomTraits>}
-  \cgalHasModels{CGAL::Orthtree_traits_3<GeomTraits>}
-  \cgalHasModels{CGAL::Orthtree_traits_d<GeomTraits,Dimension>}
+  \cgalHasModels{CGAL::Orthtree_traits_point<GeomTraits, PointRange, PointMap, dimension>}
+  \cgalHasModels{CGAL::Orthtree_traits_face_graph<PolygonMesh, VPM>}
+  \cgalHasModels{CGAL::Orthtree_traits_base<K, dimension>}
   \cgalHasModelsEnd
 */
 class OrthtreeTraits
@@ -17,46 +17,62 @@ class OrthtreeTraits
 
   /// \name Types
   /// @{
-
-  typedef unspecified_type Dimension; ///< Dimension type (see `CGAL::Dimension_tag`).
-  typedef unspecified_type Bbox_d; ///< Bounding box type.
-  typedef unspecified_type FT; ///< The number type of the %Cartesian coordinates of types `Point_d`
-  typedef unspecified_type Point_d; ///< Point type.
-  typedef unspecified_type Sphere_d; ///< The sphere type for neighbor queries.
+  using Node_index = unspecified_type; ///< An integer type for nodes
+  constexpr int dimension; ///< Dimension.
+  using FT = unspecified_type; ///< The number type of the %Cartesian coordinates of types `Point_d`
+  using Point_d = unspecified_type; ///< Point type.
+  using Bbox_d = unspecified_type; ///< Bounding box type. Must be constructible from a pair of `Point_d` objects.
 
   /*!
     A random access iterator type to enumerate the
-    %Cartesian coordinates of a point.
+    %Cartesian coordinates of a point of type `Point_d`.
   */
-  typedef unspecified_type Cartesian_const_iterator_d;
-  typedef std::array<FT, Dimension::value> Array; ///< Array used for easy point constructions.
+  using Cartesian_const_iterator_d = unspecified_type;
 
-  typedef unspecified_type Adjacency; ///< Specify the adjacency directions
+  /*!
+   * \brief Integral 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)rectangle type, equivalent to 2 * D.
+   */
+  using Adjacency = unspecified_type; ///< Specify the adjacency directions
 
   /*!
-    Functor with an operator to construct a `Point_d` from an `Array` object.
-  */
-  typedef unspecified_type Construct_point_d_from_array;
+   * \brief Functor with an operator to create the bounding box of the root node.
+   *
+   * Provides the operator:
+   * `Bbox_d operator()()`
+   *
+   * The bounding box must enclose all elements contained by the tree.
+   * It may be tight-fitting. The orthtree constructor produces a bounding box surrounding this region.
+   * For traits which assign no data to each node, this can be defined to return a fixed region.
+   */
+  using Construct_root_node_bbox = unspecified_type;
 
   /*!
-    Functor with an operator to construct a `Bbox_d` from two `Array` objects (coordinates of minimum and maximum points).
-  */
-  typedef unspecified_type Construct_bbox_d;
+   * \brief Functor with an operator to construct a `Point_d` from an initializer list of type `FT`.
+   *
+   * Provides the operator:
+   * `Point_d operator()(arg1, arg2,...)`
+   *
+   * For trees which use a different kernel for the bounding box type,
+   * the return type of this functor must match the kernel used by the bounding box type and not that of the contents.
+   */
+  using Construct_point_d = unspecified_type;
 
   /// @}
 
   /// \name Operations
   /// @{
 
   /*!
-    Function used to construct an object of type `Construct_point_d_from_array`.
-  */
-  Construct_point_d_from_array construct_point_d_from_array_object() const;
+   * constructs an object of type `Construct_root_node_bbox`.
+   */
+  Construct_root_node_bbox construct_root_node_bbox_object() const;
 
   /*!
-    Function used to construct an object of type `Construct_bbox_d`.
-  */
-  Construct_bbox_d construct_bbox_d_object() const;
+   * constructs an object of type `Construct_point_d`.
+   */
+  Construct_point_d construct_point_d_object() const;
 
   /// @}
 };

Orthtree/doc/Orthtree/Concepts/OrthtreeTraitsWithData.h

@@ -0,0 +1,76 @@
+/*!
+  \ingroup PkgOrthtreeConcepts
+  \cgalConcept
+
+  The concept `OrthtreeTraitsWithData` defines the requirements for the
+  template parameter of the `CGAL::Orthtree` class for a node type that stores data.
+
+  \cgalRefines{OrthtreeTraits}
+
+  \cgalHasModelsBegin
+  \cgalHasModels{CGAL::Orthtree_traits_point<GeomTraits, PointRange, PointMap, dimension>}
+  \cgalHasModels{CGAL::Orthtree_traits_face_graph<PolygonMesh, VPM>}
+  \cgalHasModels{CGAL::Orthtree_traits_base<K, dimension>}
+  \cgalHasModelsEnd
+*/
+class OrthtreeTraitsWithData
+{
+public:
+
+  /// \name Types
+  /// @{
+  /*!
+   * \brief The data type contained by each node. Must be default constructible, copy constructible and copy assignable.
+   */
+  using Node_data = unspecified_type;
+
+  /*!
+   * \brief Functor which initializes elements contained by the root node.
+   *
+   * Each node of a tree has an associated `Node_data` value.
+   * This functor initializes the `Node_data` of the root node.
+   * It takes no arguments, and returns an instance of `Node_data`.
+   *
+   * Provides the operator:
+   * `Node_data operator()()`
+   *
+   * Typically, the `Node_data` of the root node contains all the elements in the tree.
+   * For a tree in which each node contains a span (such as `std::span()`) this function would return the span containing all items.
+   *
+   */
+  using Construct_root_node_contents = unspecified_type;
+
+  /*!
+   * \brief Functor which fills the contents of the nodes children.
+   *
+   * Provides the operator:
+   * `void operator()(Node_index, Orthtree<Traits>&, const Point_d&)`
+   *
+   * The functor is called during refinement of the `Orthtree` on a node after it has been split. The purpose of the functor is to
+   * distribute the `Node_data`, accessible via `tree.data()`, to the data of the nodes children, accessible via `tree.children()`.
+   * The first parameter is the `Node_index` of the node. The second parameter provides the instance of the `Orthtree`
+   * and the last parameter is the barycenter of the node which will be used as shared corner amongst the children of the node.
+   *
+   * 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.
+   * For compatibility with locate, the center of the node is considered to be part of the upper half.
+   */
+  using Distribute_node_contents = unspecified_type;
+
+  /// @}
+
+  /// \name Operations
+  /// @{
+
+  /*!
+   * constructs an object of type `Construct_root_node_contents`.
+   */
+  Construct_root_node_contents construct_root_node_contents_object() const;
+
+  /*!
+   * constructs an object of type `Distribute_node_contents`.
+   */
+  Distribute_node_contents distribute_node_contents_object() const;
+
+  /// @}
+};