Orthtree generalization

BGL/include/CGAL/boost/graph/IO/Generic_facegraph_builder.h

@@ -102,10 +102,10 @@ class Generic_facegraph_builder
 
     // Construct the graph
     VPM vpm = choose_parameter(get_parameter(np, internal_np::vertex_point), get_property_map(CGAL::vertex_point, g));
-    VNM vnm = choose_parameter(get_parameter(np, internal_np::vertex_normal_map), VNM());
-    VCM vcm = choose_parameter(get_parameter(np, internal_np::vertex_color_map), VCM());
-    VTM vtm = choose_parameter(get_parameter(np, internal_np::vertex_texture_map), VTM());
-    FCM fcm = choose_parameter(get_parameter(np, internal_np::face_color_map), FCM());
+    VNM vnm = choose_parameter<VNM>(get_parameter(np, internal_np::vertex_normal_map));
+    VCM vcm = choose_parameter<VCM>(get_parameter(np, internal_np::vertex_color_map));
+    VTM vtm = choose_parameter<VTM>(get_parameter(np, internal_np::vertex_texture_map));
+    FCM fcm = choose_parameter<FCM>(get_parameter(np, internal_np::face_color_map));
 
     const bool has_vertex_normals = (is_vnm_requested && !(vertex_normals.empty()));
     const bool has_vertex_colors = (is_vcm_requested && !(vertex_colors.empty()));

Orthtree/doc/Orthtree/Concepts/OrthtreeTraits.h

@@ -29,6 +29,34 @@ class OrthtreeTraits
   typedef unspecified_type Cartesian_const_iterator_d;
   typedef std::array<FT, Dimension::value> Array; ///< Array used for easy point constructions.
 
+
+  /*!
+   * \brief List-like or iterable type contained by each node
+   *
+   * Should provide begin() and end() iterators which span all the items contained by a node.
+   * Must also be default-constructible, because node data is allocated ahead of time.
+   * Many split predicates also expect a `Node_data::size()` method.
+   * For example, this could be a `boost::range` of point indices, or an `std::vector` containing primitives.
+   *
+   * todo: For an empty tree, this should contain something like `std::array<Point_d, 0>`.
+   * This way, nearest_neighbors still compiles, and simply returns nothing because all nodes are empty.
+   * Eventually, nearest_neighbors will be removed and/or moved, and then this won't have to behave like a list.
+   * Once that's done, `boost::none_t` will work for an empty tree.
+   */
+  typedef unspecified_type Node_data;
+
+  /*!
+   * \brief An element of the `Node_data` list-like type.
+   *
+   * Must be constructible from the type produced by dereferencing a `Node_data` iterator.
+   * Typically the same as that type, but can also be an `std::reference_wrapper<>` if the type is not copyable.
+   *
+   * todo: This is only used as part of the return type for `nearest_neighbors()`.
+   * Because `nearest_neighbors()` may be ill defined for empty node types,
+   * this can be omitted in the final version of Orthtree_traits.
+   */
+  typedef unspecified_type Node_data_element;
+
   typedef unspecified_type Adjacency; ///< Specify the adjacency directions
 
   /*!
@@ -56,5 +84,48 @@ class OrthtreeTraits
   */
   Construct_bbox_d construct_bbox_d_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<min, max>, where min and max represent cartesian corners which define a bounding box
+   */
+  std::pair<Array, Array> root_node_bbox() 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
+   */
+  Node_data root_node_contents() 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.
+   */
+  template <typename Node_index, typename Tree>
+  void distribute_node_contents(Node_index n, Tree& tree, const Point_d& center);
+
   /// @}
 };

Orthtree/doc/Orthtree/Orthtree.txt

@@ -73,7 +73,7 @@ split.
 
 \subsection Section_Orthtree_Point_Vector Building an Octree
 
-The `Orthtree` class may be templated with `Orthtree_traits_3` and thus
+The `Orthtree` class may be templated with `Orthtree_traits_point_3` and thus
 behave as an %octree. For convenience, the alias `Octree` is provided.
 
 The following example shows how to create an %octree from a vector of

Orthtree/doc/Orthtree/PackageDescription.txt

@@ -48,7 +48,7 @@
 
 \cgalCRPSection{Traits}
 - `CGAL::Orthtree_traits_2<GeomTraits>`
-- `CGAL::Orthtree_traits_3<GeomTraits>`
+- `CGAL::Orthtree_traits_point_3<GeomTraits>`
 - `CGAL::Orthtree_traits_d<GeomTraits, Dimension>`
 
 \cgalCRPSection{Split Predicates}

Orthtree/examples/Orthtree/CMakeLists.txt

@@ -15,6 +15,8 @@ create_single_source_cgal_program("octree_traversal_manual.cpp")
 create_single_source_cgal_program("octree_traversal_preorder.cpp")
 create_single_source_cgal_program("octree_grade.cpp")
 create_single_source_cgal_program("quadtree_build_from_point_vector.cpp")
+create_single_source_cgal_program("octree_surface_mesh.cpp")
+create_single_source_cgal_program("quadtree_build_manually.cpp")
 
 find_package(Eigen3 3.1.91 QUIET) #(requires 3.1.91 or greater)
 include(CGAL_Eigen_support)

Orthtree/examples/Orthtree/octree_build_from_point_set.cpp

@@ -30,13 +30,13 @@ int main(int argc, char **argv) {
   std::cout << "loaded " << points.number_of_points() << " points\n" << std::endl;
 
   // Create an octree from the points
-  Octree octree(points, points.point_map());
+  Octree octree({points, points.point_map()});
 
   // Build the octree with a small bucket size, using a more verbose method
   octree.refine(CGAL::Orthtrees::Maximum_depth_and_maximum_number_of_inliers(5, 10));
 
   // Print out the tree
-  std::cout << octree;
+  std::cout << octree << std::endl;
 
   return EXIT_SUCCESS;
 }

Orthtree/examples/Orthtree/octree_build_from_point_vector.cpp

@@ -6,7 +6,7 @@
 // Type Declarations
 typedef CGAL::Simple_cartesian<double> Kernel;
 typedef Kernel::Point_3 Point;
-typedef std::list<Point> Point_vector;
+typedef std::vector<Point> Point_vector; // todo: this was changed to std::list at some point; why?
 
 typedef CGAL::Octree<Kernel, Point_vector> Octree;
 
@@ -24,10 +24,10 @@ int main() {
   points.emplace_back(-1, 1, 1);
 
   // Create an octree from the points
-  Octree octree(points);
+  Octree octree({points});
 
   // Build the octree
-  octree.refine(10, 20);
+  octree.refine(10, 1);
 
   // Print out the tree
   std::cout << octree;

Orthtree/examples/Orthtree/octree_build_with_custom_split.cpp

@@ -21,11 +21,13 @@ struct Split_by_ratio {
 
   std::size_t ratio;
 
-  Split_by_ratio(std::size_t ratio) : ratio(ratio) {}
+  explicit Split_by_ratio(std::size_t ratio) : ratio(ratio) {}
 
-  template<class Node>
-  bool operator()(const Node &n) const {
-    return n.size() > (ratio * n.depth());
+  template<typename Node_index, typename Tree>
+  bool operator()(Node_index i, const Tree &tree) const {
+    std::size_t num_points = tree.data(i).size();
+    std::size_t depth = tree.depth(i);
+    return num_points > (ratio * depth);
   }
 };
 
@@ -45,7 +47,7 @@ int main(int argc, char **argv) {
   std::cout << "loaded " << points.number_of_points() << " points" << std::endl;
 
   // Create an octree from the points
-  Octree octree(points, points.point_map());
+  Octree octree({points, points.point_map()});
 
   // Build the octree using our custom split predicate
   octree.refine(Split_by_ratio(2));

Orthtree/examples/Orthtree/octree_find_nearest_neighbor.cpp

@@ -16,7 +16,7 @@ typedef Point_set::Point_map Point_map;
 
 typedef CGAL::Octree<Kernel, Point_set, Point_map> Octree;
 
-int main(int argc, char **argv) {
+int main(int argc, char** argv) {
 
   // Point set will be used to hold our points
   Point_set points;
@@ -32,28 +32,26 @@ int main(int argc, char **argv) {
   std::cout << "loaded " << points.number_of_points() << " points" << std::endl;
 
   // Create an octree from the points
-  Octree octree(points, points.point_map());
+  Octree octree({points, points.point_map()});
 
   // Build the octree
   octree.refine(10, 20);
 
   // Find the nearest points to a few locations
   std::vector<Point> points_to_find = {
-          {0, 0, 0},
-          {1, 1, 1},
-          {-1, -1, -1},
-          {-0.46026, -0.25353, 0.32051},
-          {-0.460261, -0.253533, 0.320513}
+    {0,         0,         0},
+    {1,         1,         1},
+    {-1,        -1,        -1},
+    {-0.46026,  -0.25353,  0.32051},
+    {-0.460261, -0.253533, 0.320513}
   };
-  for (const Point& p : points_to_find)
-    octree.nearest_neighbors
-      (p, 1, // k=1 to find the single closest point
-       boost::make_function_output_iterator
-       ([&](const Point& nearest)
-        {
-          std::cout << "the nearest point to (" << p <<
-            ") is (" << nearest << ")" << std::endl;
-        }));
+  for (const Point& p: points_to_find)
+    octree.nearest_neighbors(
+      p, 1, // k=1 to find the single closest point
+      boost::make_function_output_iterator([&](const Point_set::Index& nearest) {
+        std::cout << "the nearest point to (" << p << ") is (" << points.point(nearest) << ")" << std::endl;
+      })
+    );
 
   return EXIT_SUCCESS;
 }

Orthtree/examples/Orthtree/octree_grade.cpp

@@ -28,7 +28,7 @@ int main() {
   points.emplace_back(-1.0001, 1, 1);
 
   // Create an octree from the points
-  Octree octree(points);
+  Octree octree({points});
 
   // Build the octree with a small bucket size, so we get a deep node
   octree.refine(10, 2);

Orthtree/examples/Orthtree/octree_surface_mesh.cpp

@@ -0,0 +1,69 @@
+#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
+#include <CGAL/Surface_mesh.h>
+
+#include <CGAL/Octree.h>
+#include <CGAL/Orthtree_traits_face_graph.h>
+
+#include <CGAL/boost/graph/IO/polygon_mesh_io.h>
+
+using K = CGAL::Exact_predicates_inexact_constructions_kernel;
+using Mesh = CGAL::Surface_mesh<K::Point_3>;
+
+using OTraits = CGAL::Orthtree_traits_face_graph<Mesh, Mesh::Property_map<Mesh::Vertex_index, K::Point_3>>;
+using Octree = CGAL::Orthtree<OTraits>;
+
+void dump_as_polylines(const Octree& ot)
+{
+  // SL: I cheated for this part and looked at the implementation
+    std::ofstream out("octree.polylines.txt");
+    for (Octree::Node_index node : ot.traverse(CGAL::Orthtrees::Leaves_traversal<Octree>(ot)))
+    {
+      if (!ot.is_leaf(node))
+        continue;
+      CGAL::Bbox_3 bb = ot.bbox(node);
+      out << "2 " << bb.xmin() << " " << bb.ymin() << " " << bb.zmin()
+          << "  " << bb.xmax() << " " << bb.ymin() << " " << bb.zmin() << "\n";
+      out << "2 " << bb.xmin() << " " << bb.ymin() << " " << bb.zmin()
+          << "  " << bb.xmin() << " " << bb.ymax() << " " << bb.zmin() << "\n";
+      out << "2 " << bb.xmax() << " " << bb.ymin() << " " << bb.zmin()
+          << "  " << bb.xmax() << " " << bb.ymax() << " " << bb.zmin() << "\n";
+      out << "2 " << bb.xmin() << " " << bb.ymax() << " " << bb.zmin()
+          << "  " << bb.xmax() << " " << bb.ymax() << " " << bb.zmin() << "\n";
+//
+      out << "2 " << bb.xmin() << " " << bb.ymin() << " " << bb.zmin()
+          << "  " << bb.xmin() << " " << bb.ymin() << " " << bb.zmax() << "\n";
+      out << "2 " << bb.xmax() << " " << bb.ymin() << " " << bb.zmin()
+          << "  " << bb.xmax() << " " << bb.ymin() << " " << bb.zmax() << "\n";
+      out << "2 " << bb.xmin() << " " << bb.ymax() << " " << bb.zmin()
+          << "  " << bb.xmin() << " " << bb.ymax() << " " << bb.zmax() << "\n";
+      out << "2 " << bb.xmax() << " " << bb.ymax() << " " << bb.zmin()
+          << "  " << bb.xmax() << " " << bb.ymax() << " " << bb.zmax() << "\n";
+//
+      out << "2 " << bb.xmin() << " " << bb.ymin() << " " << bb.zmax()
+          << "  " << bb.xmax() << " " << bb.ymin() << " " << bb.zmax() << "\n";
+      out << "2 " << bb.xmin() << " " << bb.ymin() << " " << bb.zmax()
+          << "  " << bb.xmin() << " " << bb.ymax() << " " << bb.zmax() << "\n";
+      out << "2 " << bb.xmax() << " " << bb.ymin() << " " << bb.zmax()
+          << "  " << bb.xmax() << " " << bb.ymax() << " " << bb.zmax() << "\n";
+      out << "2 " << bb.xmin() << " " << bb.ymax() << " " << bb.zmax()
+          << "  " << bb.xmax() << " " << bb.ymax() << " " << bb.zmax() << "\n";
+    }
+}
+
+int main(int argc, char** argv)
+{
+  const std::string filename = (argc > 1) ? argv[1] : CGAL::data_file_path("meshes/elephant.off");
+
+  Mesh mesh;
+  if(!CGAL::IO::read_polygon_mesh(filename, mesh))
+  {
+    std::cerr << "Error: cannot read file" << std::endl;
+    return EXIT_FAILURE;
+  }
+
+  Octree tree({mesh, mesh.points()});
+  OTraits::Split_predicate_node_min_extent sp(0.01);
+  tree.refine(sp);
+
+  dump_as_polylines(tree);
+}

Orthtree/examples/Orthtree/octree_traversal_custom.cpp

@@ -3,6 +3,7 @@
 
 #include <CGAL/Simple_cartesian.h>
 #include <CGAL/Octree.h>
+#include <CGAL/Orthtree/IO.h>
 #include <CGAL/Point_set_3.h>
 #include <CGAL/Point_set_3/IO.h>
 
@@ -15,22 +16,29 @@ typedef Point_set::Point_map Point_map;
 typedef CGAL::Octree<Kernel, Point_set, Point_map> Octree;
 typedef Octree::Node Node;
 
-struct First_branch_traversal
-{
-  Node first (Node root) const
-  {
-    return root;
+template <typename Tree>
+struct First_branch_traversal {
+
+  const Tree& m_orthtree;
+
+  explicit First_branch_traversal(const Tree& orthtree) : m_orthtree(orthtree) {}
+
+  typename Tree::Node_index first_index() const {
+    return m_orthtree.root();
   }
 
-  Node next (Node n) const
-  {
-    if (n.is_leaf())
-      return Node();
-    return n[0];
+  typename Tree::Maybe_node_index next_index(typename Tree::Node_index n) const {
+
+    // Stop when we reach the base of the tree
+    if (m_orthtree.is_leaf(n))
+      return {};
+
+    // Always descend the first child
+    return m_orthtree.child(n, 0);
   }
 };
 
-int main(int argc, char **argv) {
+int main(int argc, char** argv) {
 
   // Point set will be used to hold our points
   Point_set points;
@@ -46,14 +54,15 @@ int main(int argc, char **argv) {
   std::cout << "loaded " << points.number_of_points() << " points\n" << std::endl;
 
   // Create an octree from the points
-  Octree octree(points, points.point_map());
+  Octree octree({points, points.point_map()});
 
   // Build the octree
   octree.refine();
 
   // Print out the first branch using custom traversal
-  for (auto &node : octree.traverse<First_branch_traversal>())
-    std::cout << node << std::endl;
+  for (auto node: octree.traverse<First_branch_traversal<Octree>>()) {
+    std::cout << octree.to_string(node) << std::endl;
+  }
 
   return EXIT_SUCCESS;
 }