improve doc

Orthtree/doc/Orthtree/PackageDescription.txt

@@ -51,7 +51,7 @@ Quadtree, Octree and Orthtree Reference
 \cgalCRPSection{Traits}
 - `CGAL::Orthtree_traits_point<GeomTraits>`
 - `CGAL::Orthtree_traits_base_for_dimension<GeomTraits>`
-- `CGAL::Orthtree_traits_face_graph<PolygonMesh, VertexPointMap>`
+- `CGAL::Orthtree_traits_face_graph<TriangleMesh, VertexPointMap>`
 
 \cgalCRPSection{Split Predicates}
 - `CGAL::Orthtrees::Maximum_number_of_inliers`

Orthtree/include/CGAL/Orthtree_traits_face_graph.h

@@ -24,29 +24,34 @@
 namespace CGAL {
 
 /*!
-  \ingroup PkgOrthtreeTraits
+\ingroup PkgOrthtreeTraits
 
-  The class `Orthtree_traits_face_graph` can be used as a template parameter of
-  the `Orthtree` class.
+Traits class for the `Orthtree` class to be used to contruct a 3D octree around
+a triangulated surface mesh. Each node of the octree will store all the faces of the
+mesh intersected by its bounding box. The subdivision of the octree is controlled
+by the nested class `Orthtree_traits_face_graph::Split_predicate_node_min_extent`
+to which the minimal extend of a node should be provided.
 
-  \tparam PolygonMesh a model of `FaceGraph`.
-  \tparam VertexPointMap a property map associating points to the vertices of `PolygonMesh`.
+\tparam TriangleMesh a model of `FaceListGraph` with all faces being triangles
+\tparam VertexPointMap a property map associating points to the vertices of `TriangleMesh`
 
-  \cgalModels{OrthtreeTraits}
-  \sa `CGAL::Orthtree_traits_base_for_dimension<GeomTraits, DimensionTag>`
+\todo check how to adapt to non regular splits (cubes vs rectangular cuboid)
+
+\cgalModels{OrthtreeTraits}
+\sa `CGAL::Orthtree_traits_base_for_dimension<GeomTraits, DimensionTag>`
 */
-template <class PolygonMesh, class VertexPointMap>
+template <class TriangleMesh, class VertexPointMap>
 struct Orthtree_traits_face_graph : public Orthtree_traits_base_for_dimension<
   typename Kernel_traits<typename boost::property_traits<VertexPointMap>::value_type>::type,
   Dimension_tag<3> > {
 
-  Orthtree_traits_face_graph(const PolygonMesh& pm, VertexPointMap vpm)
+  Orthtree_traits_face_graph(const TriangleMesh& pm, VertexPointMap vpm)
     : m_pm(pm), m_vpm(vpm) {}
 
   /// \name Types
   /// @{
 
-  using Self = Orthtree_traits_face_graph<PolygonMesh, VertexPointMap>;
+  using Self = Orthtree_traits_face_graph<TriangleMesh, VertexPointMap>;
   using Tree = Orthtree<Self>;
 
   using Point_d = typename Self::Point_d;
@@ -55,10 +60,14 @@ struct Orthtree_traits_face_graph : public Orthtree_traits_base_for_dimension<
   using FT = typename Self::FT;
   using Cartesian_const_iterator_d = typename Self::Cartesian_const_iterator_d;
 
-  using Node_data = std::vector<typename boost::graph_traits<PolygonMesh>::face_descriptor>;
+  using Node_data = std::vector<typename boost::graph_traits<TriangleMesh>::face_descriptor>;
 
   using Geom_traits = typename Kernel_traits<Point_d>::type;
 
+  using Construct_root_node_bbox = std::function<Bbox_d()>;
+  using Construct_root_node_contents = std::function<Node_data()>;
+  using Distribute_node_contents = std::function<void(typename Tree::Node_index, Tree&, const Point_d&)>;
+
   /// @}
 
   /// \name Operations
@@ -101,7 +110,7 @@ struct Orthtree_traits_face_graph : public Orthtree_traits_base_for_dimension<
         Node_data& child_data = tree.data(child);
         Bbox_d bbox = tree.bbox(child);
         for (auto f : ndata) {
-          typename boost::graph_traits<PolygonMesh>::halfedge_descriptor
+          typename boost::graph_traits<TriangleMesh>::halfedge_descriptor
             h = halfedge(f, m_pm);
           typename Geom_traits::Triangle_3 t(get(m_vpm, source(h, m_pm)),
             get(m_vpm, target(h, m_pm)),
@@ -113,12 +122,18 @@ struct Orthtree_traits_face_graph : public Orthtree_traits_base_for_dimension<
       };
   }
 
+  /// @}
+
+  /// Recommanded split predicate to pass to `Orthtree::refine()` function so
+  /// that the octree is refined until a node is either empty or has an extend
+  /// that would be smaller after split than the value provided to the constructor.
   class Split_predicate_node_min_extent {
 
     FT m_min_extent;
 
   public:
 
+    /// constructor with `me` being the minimal value a node extent could be.
     Split_predicate_node_min_extent(FT me)
       : m_min_extent(me) {}
 
@@ -138,11 +153,10 @@ struct Orthtree_traits_face_graph : public Orthtree_traits_base_for_dimension<
     }
   };
 
-  /// @}
 
 private:
 
-  const PolygonMesh& m_pm;
+  const TriangleMesh& m_pm;
   VertexPointMap m_vpm;
 };