Skip to main content

kd_tree

Template class implementing a k-dimensional tree data structure for efficient nearest neighbor and radius search operations.

Template parameters

PointT
typename
Point type that supports array-style indexing with operator[]
Dim
std::size_t
Number of dimensions in the point space

Constructor

kd_tree(pts)
constructor
Constructs a KD-tree from a vector of pointsParameters:
  • pts (const std::vector<PointT>*): Pointer to vector of points to index
The constructor builds the tree structure for efficient spatial queries.

Methods

Finds all points within a specified radius of a query pointParameters:
  • q (const PointT&): Query point
  • eps (double): Search radius (epsilon)
Returns: Vector of indices of points within distance eps from query point q

Internal structure

node
struct
Internal node structure containing:
  • index (std::size_t): Index of the point in the original vector
  • left (std::size_t): Index of left child node
  • right (std::size_t): Index of right child node
  • axis (std::size_t): Splitting axis for this node

Private members

pts_
const std::vector<PointT>*
Pointer to the vector of points
nodes_
std::vector<node>
Vector of tree nodes representing the KD-tree structure

Static helper methods

coord
static double
Extracts coordinate value from a point at specified axisParameters:
  • p (const PointT&): Point
  • axis (std::size_t): Dimension axis
Returns: Coordinate value at the specified axis
dist_sq
static double
Computes squared Euclidean distance between two pointsParameters:
  • a (const PointT&): First point
  • b (const PointT&): Second point
Returns: Squared distance between points a and b

Example usage

#include "KD-Tree/kd_tree.h"
#include <vector>
#include <array>

// Define 2D points
using Point2D = std::array<double, 2>;

// Create a set of 2D points
std::vector<Point2D> points = {
    {1.0, 2.0},
    {3.0, 4.0},
    {5.0, 1.0},
    {7.0, 6.0},
    {2.0, 8.0}
};

// Build KD-tree for 2D space
kd_tree<Point2D, 2> tree(&points);

// Query point
Point2D query = {3.5, 4.5};

// Find all points within radius 2.0
std::vector<std::size_t> neighbors = tree.radius_search(query, 2.0);

// neighbors contains indices of points within distance 2.0 from query
for (std::size_t idx : neighbors) {
    // Process neighbor points[idx]
}

Example with 3D points

#include "KD-Tree/kd_tree.h"
#include <vector>
#include <array>

// Define 3D points
using Point3D = std::array<double, 3>;

std::vector<Point3D> points_3d = {
    {1.0, 2.0, 3.0},
    {4.0, 5.0, 6.0},
    {7.0, 8.0, 9.0}
};

// Build KD-tree for 3D space
kd_tree<Point3D, 3> tree_3d(&points_3d);

// Radius search in 3D
Point3D query_3d = {4.5, 5.5, 6.5};
auto results = tree_3d.radius_search(query_3d, 1.5);

Use cases

The KD-tree is particularly useful for:
  • DBSCAN clustering: Finding neighbors within epsilon radius
  • Nearest neighbor search: Efficient spatial queries
  • Range queries: Finding all points within a specified region
  • High-dimensional data: Scales well with moderate dimensionality

Performance

  • Construction time: O(n log n) where n is the number of points
  • Radius search: O(log n) average case, O(n) worst case
  • Space complexity: O(n) for storing tree nodes

Build docs developers (and LLMs) love