Mars.Common.Core.Collections.SimpleTree.BinaryTree<Mars.Common.Collections.KdTreeNode<T>>.Traverse(Mars.Common.Core.Collections.SimpleTree.BinaryTraversalMethod<Mars.Common.Collections.KdTreeNode<T>>)

Namespace: Mars.Common.Collections

Assembly: Mars.Common.dll

Syntax

public class KdTree<T> : KdTreeBase<KdTreeNode<T>>, IEnumerable<KdTreeNode<T>>

Type Parameters

Name	Description
T	The type of the value being stored.

Remarks

A k-d tree (short for k-dimensional tree) is a space-partitioning data structure for organizing points in a k-dimensional space. k-d trees are a useful data structure for several applications, such as searches involving a multidimensional search key (e.g. range searches and nearest neighbor searches). k-d trees are a special case of binary space partitioning trees.

The k-d tree is a binary tree in which every node is a k-dimensional point. Every non- leaf node can be thought of as implicitly generating a splitting hyperplane that divides the space into two parts, known as half-spaces. Points to the left of this hyperplane represent the left subtree of that node and points right of the hyperplane are represented by the right subtree. The hyperplane direction is chosen in the following way: every node in the tree is associated with one of the k-dimensions, with the hyperplane perpendicular to that dimension's axis. So, for example, if for a particular split the "x" axis is chosen, all points in the subtree with a smaller "x" value than the node will appear in the left subtree and all points with larger "x" value will be in the right subtree. In such a case, the hyperplane would be set by the x-value of the point, and its normal would be the unit x-axis.

References:

ScienceDirect, Log-logarithmic worst-case range queries are possible in space Θ(N). Available on: https://www.sciencedirect.com/science/article/pii/0020019083900753?via%3Dihub

Examples

// This is the same example found in Wikipedia page on
// k-d trees: http://en.wikipedia.org/wiki/K-d_tree

// Suppose we have the following set of points:

double[][] points =
{
new double[] { 2, 3 },
new double[] { 5, 4 },
new double[] { 9, 6 },
new double[] { 4, 7 },
new double[] { 8, 1 },
new double[] { 7, 2 },
};


// To create a tree from a set of points, we use
KdTree<int> tree = KdTree.FromData<int>(points);

// Now we can manually navigate the tree
KdTreeNode<int> node = tree.Root.Left.Right;

// Or traverse it automatically
foreach (KdTreeNode<int> n in tree)
{
double[] location = n.Position;
Assert.Equal(2, location.Length);
}

// Given a query point, we can also query for other
// points which are near this point within a radius

double[] query = new double[] { 5, 3 };

// Locate all nearby points within an euclidean distance of 1.5
// (answer should be be a single point located at position (5,4))
KdTreeNodeCollection<int> result = tree.Nearest(query, radius: 1.5); 

// We can also use alternate distance functions
tree.Distance = Mars.Numerics.Distance.Manhattan;

// And also query for a fixed number of neighbor points
// (answer should be the points at (5,4), (7,2), (2,3))
KdTreeNodeCollection<int> neighbors = tree.Nearest(query, neighbors: 3);

Constructors

KdTree(Int32)

Creates a new KdTree<T>.

Declaration

public KdTree(int dimensions)

Parameters

Type	Name	Description
System.Int32	dimensions	The number of dimensions in the tree.

KdTree(Int32, KdTreeNode<T>)

Creates a new KdTree<T>.

Declaration

public KdTree(int dimension, KdTreeNode<T> root)

Parameters

Type	Name	Description
System.Int32	dimension	The number of dimensions in the tree.
KdTreeNode<T>	root	The Root node, if already existent.

KdTree(Int32, KdTreeNode<T>, Int32, Int32)

Creates a new KdTree<T>.

Declaration

public KdTree(int dimension, KdTreeNode<T> root, int count, int leaves)

Parameters

Type	Name	Description
System.Int32	dimension	The number of dimensions in the tree.
KdTreeNode<T>	root	The Root node, if already existent.
System.Int32	count	The number of elements in the Root node.
System.Int32	leaves	The number of leaves linked through the Root node.

Methods

Add(Position, T)

Adds a new Position to this tree

Declaration

public void Add(Position position, T value)

Parameters

Type	Name	Description
Position	position	A Position with respective coordinate, geospatial or not
T	value	The value to be inserted

Add(Double[], T)

Inserts a value in the tree at the desired position.

Declaration

public void Add(double[] position, T value)

Parameters

Type	Name	Description
System.Double[]	position	A double-vector with the same number of elements as dimensions in the tree.
T	value	The value to be inserted.

Create(Double[][], T[], Int32, Int32, Int32, Int32, ElementComparer, ref Int32)

Declaration

protected static KdTreeNode<T> Create(double[][] points, T[] values, int depth, int k, int start, int length, ElementComparer comparer, ref int leaves)

Parameters

Type	Name	Description
System.Double[][]	points
T[]	values
System.Int32	depth
System.Int32	k
System.Int32	start
System.Int32	length
ElementComparer	comparer
System.Int32	leaves

Returns

Type	Description
KdTreeNode<T>

Implements

System.Collections.Generic.IEnumerable<>