Document KdTree class and its methods

Author: Q-Minh

source/pbat/geometry/KdTree.h

@@ -1,3 +1,13 @@
+/**
+ * @file KdTree.h
+ * @author Quoc-Minh Ton-That ([email protected])
+ * @brief This file contains the KdTree class.
+ * @date 2025-02-12
+ *
+ * @copyright Copyright (c) 2025
+ *
+ */
+
 #ifndef PBAT_GEOMETRY_KD_TREE_H
 #define PBAT_GEOMETRY_KD_TREE_H
 
@@ -14,6 +24,9 @@
 namespace pbat {
 namespace geometry {
 
+/**
+ * @brief Node of a KDTree
+ */
 struct KdTreeNode
 {
     Index lc{-1}; ///< Index of left child of this node in the KDTree. -1 if no left child.
@@ -24,23 +37,48 @@ struct KdTreeNode
     std::size_t n{0}; ///< Number of points encapsulated in this node's AABB starting from begin and
                       ///< continuing in contiguous memory in the permutation list until begin + n.
 
-    Index depth{0};
-
+    Index depth{0}; ///< Depth of this node in the KDTree.
+    /**
+     * @brief Returns true if this node has a left child, false otherwise
+     * @return true if this node has a left child, false otherwise
+     */
     bool HasLeftChild() const { return lc > -1; }
+    /**
+     * @brief Returns true if this node has a right child, false otherwise
+     * @return true if this node has a right child, false otherwise
+     */
     bool HasRightChild() const { return rc > -1; }
+    /**
+     * @brief Returns true if this node is a leaf node, false otherwise
+     * @return true if this node is a leaf node, false otherwise
+     */
     [[maybe_unused]] bool IsLeafNode() const
     {
         return (not HasLeftChild()) and (not HasRightChild());
     }
+    /**
+     * @brief Returns true if this node is an internal node, false otherwise
+     * @return true if this node is an internal node, false otherwise
+     */
     [[maybe_unused]] bool IsInternalNode() const { return HasLeftChild() or HasRightChild(); }
 };
 
+/**
+ * @brief KDTree class
+ * @tparam Dims Number of dimensions of the points' coordinate system in the k-D tree
+ */
 template <int Dims>
 class KdTree
 {
   public:
     KdTree() = default;
 
+    /**
+     * @brief Construct a k-D tree from a set of points
+     * @tparam TDerivedP Eigen dense expression type
+     * @param P Points to construct the k-D tree from
+     * @param maxPointsInLeaf Maximum number of points in a leaf node
+     */
     template <class TDerivedP>
     KdTree(Eigen::DenseBase<TDerivedP> const& P, std::size_t maxPointsInLeaf = 10);
 
@@ -51,35 +89,77 @@ class KdTree
 
   public:
     /**
-     * @brief
-     * @param visit Returns true if the node's children should be visited, false otherwise
-     * @param stop Returns true if the search should stop
-     * @param root
+     * @brief Breadth-first search over the k-D tree
+     * @tparam FVisit Callable with signature `bool(Index, KdTreeNode const&)`
+     * @tparam FStop Callable with signature `bool(Index, KdTreeNode const&)`
+     * @param visit Callback invoked when visiting a node. Returns true if the node's children
+     * should be visited, false otherwise
+     * @param stop Callback invoked when visiting a node. Returns true if the search should stop,
+     * false otherwise
+     * @param root Index of the root node to start the search from
      */
     template <class FVisit, class FStop = decltype(fStopDefault)>
     void BreadthFirstSearch(FVisit visit, FStop stop = fStopDefault, Index root = 0) const;
 
     /**
-     * @brief
-     * @param visit Returns true if the node's children should be visited, false otherwise
-     * @param stop Returns true if the search should stop
-     * @param root
+     * @brief Depth-first search over the k-D tree
+     * @tparam FVisit Callable with signature `bool(Index, KdTreeNode const&)`
+     * @tparam FStop Callable with signature `bool(Index, KdTreeNode const&)`
+     * @param visit Callback invoked when visiting a node. Returns true if the node's children
+     * @param stop Callback invoked when visiting a node. Returns true if the search should stop,
+     * @param root Index of the root node to start the search from
      */
     template <class FVisit, class FStop = decltype(fStopDefault)>
     void DepthFirstSearch(FVisit visit, FStop stop = fStopDefault, Index root = 0) const;
 
+    /**
+     * @brief Construct a k-D tree from a set of points
+     * @tparam TDerivedP Eigen dense expression type
+     * @param P Points to construct the k-D tree from
+     * @param maxPointsInLeaf Maximum number of points in a leaf node
+     */
     template <class TDerivedP>
     void Construct(Eigen::DenseBase<TDerivedP> const& P, std::size_t maxPointsInLeaf);
 
+    /**
+     * @brief Returns the nodes of the k-D tree
+     * @return Nodes of the k-D tree
+     */
     std::vector<KdTreeNode> const& Nodes() const { return mNodes; }
-
+    /**
+     * @brief Returns the permutation of the points in the k-D tree
+     *
+     * The permutation is such that mPermutation[i] gives the index of point i in the original point
+     * set given to Construct().
+     *
+     * @return Permutation of the points in the k-D tree
+     */
     std::vector<Index> const& Permutation() const { return mPermutation; }
-
+    /**
+     * @brief Returns the points in a node
+     * @param nodeIdx Index of the node
+     * @return Range of points in the node
+     */
     auto PointsInNode(Index const nodeIdx) const;
-
+    /**
+     * @brief Returns the points in a node
+     * @param node Reference to k-D tree node
+     * @return Range of points in the node
+     */
     auto PointsInNode(KdTreeNode const& node) const;
 
   protected:
+    /**
+     * @brief Recursive construct call that constructs a sub-tree of the full k-D tree
+     * @tparam TDerivedP Eigen dense expression type
+     * @param nodeIdx Index of the sub-tree root node
+     * @param P Points to construct the k-D tree from
+     * @param aabb Axis-aligned bounding box of the points contained in the sub-tree
+     * @param begin Index of the first point in the permutation list contained in the sub-tree
+     * @param n Number of points in the permutation list starting from begin contained in the
+     * sub-tree
+     * @param maxPointsInLeaf Maximum number of points in a leaf node
+     */
     template <class TDerivedP>
     void DoConstruct(
         Index const nodeIdx,
@@ -88,11 +168,20 @@ class KdTree
         Index const begin,
         std::size_t const n,
         std::size_t maxPointsInLeaf);
-
+    /**
+     * @brief Adds a node to the k-D tree's node list
+     *
+     * @param begin Index of the first point in the permutation list contained in the sub-tree
+     * rooted in the added node
+     * @param n Number of points in the permutation list starting from begin contained in the
+     * sub-tree rooted in the added node
+     * @param depth Depth of the added node in the k-D tree
+     * @return Index of the added node in the k-D tree's node list
+     */
     Index AddNode(Index begin, std::size_t n, Index depth);
 
   private:
-    std::vector<Index> mPermutation; ///< permutation_[i] gives the index of point i in
+    std::vector<Index> mPermutation; ///< mPermutation[i] gives the index of point i in
                                      ///< the original points list given to
                                      ///< construct(std::vector<Vector3> const& points).
     std::vector<KdTreeNode> mNodes;  ///< KDTree nodes.