OpenTTD Source  20241120-master-g6d3adc6169
Kdtree< T, TxyFunc, CoordT, DistT > Class Template Reference

K-dimensional tree, specialised for 2-dimensional space. More...

#include <kdtree.hpp>

Data Structures

struct  node
 Type of a node in the tree. More...
 

Public Member Functions

 Kdtree ()
 Construct a new Kdtree with the given xyfunc.
 
template<typename It >
void Build (It begin, It end)
 Clear and rebuild the tree from a new sequence of elements,. More...
 
void Clear ()
 Clear the tree.
 
void Rebuild ()
 Reconstruct the tree with the same elements, letting it be fully balanced.
 
void Insert (const T &element)
 Insert a single element in the tree. More...
 
void Remove (const T &element)
 Remove a single element from the tree, if it exists. More...
 
size_t Count () const
 Get number of elements stored in tree.
 
FindNearest (CoordT x, CoordT y) const
 Find the element closest to given coordinate, in Manhattan distance. More...
 
template<typename Outputter >
void FindContained (CoordT x1, CoordT y1, CoordT x2, CoordT y2, const Outputter &outputter) const
 Find all items contained within the given rectangle. More...
 
std::vector< T > FindContained (CoordT x1, CoordT y1, CoordT x2, CoordT y2) const
 Find all items contained within the given rectangle. More...
 

Private Types

using node_distance = std::pair< T, DistT >
 A data element and its distance to a searched-for point.
 

Private Member Functions

size_t AddNode (const T &element)
 Create one new node in the tree, return its index in the pool.
 
template<typename It >
CoordT SelectSplitCoord (It begin, It end, int level)
 Find a coordinate value to split a range of elements at.
 
template<typename It >
size_t BuildSubtree (It begin, It end, int level)
 Construct a subtree from elements between begin and end iterators, return index of root.
 
bool Rebuild (const T *include_element, const T *exclude_element)
 Rebuild the tree with all existing elements, optionally adding or removing one more.
 
void InsertRecursive (const T &element, size_t node_idx, int level)
 Insert one element in the tree somewhere below node_idx.
 
std::vector< T > FreeSubtree (size_t node_idx)
 Free all children of the given node. More...
 
size_t RemoveRecursive (const T &element, size_t node_idx, int level)
 Find and remove one element from the tree. More...
 
DistT ManhattanDistance (const T &element, CoordT x, CoordT y) const
 
node_distance FindNearestRecursive (CoordT xy[2], size_t node_idx, int level, DistT limit=std::numeric_limits< DistT >::max()) const
 Search a sub-tree for the element nearest to a given point.
 
template<typename Outputter >
void FindContainedRecursive (CoordT p1[2], CoordT p2[2], size_t node_idx, int level, const Outputter &outputter) const
 
size_t CountValue (const T &element, size_t node_idx) const
 Debugging function, counts number of occurrences of an element regardless of its correct position in the tree.
 
void IncrementUnbalanced (size_t amount=1)
 
bool IsUnbalanced () const
 Check if the entire tree is in need of rebuilding.
 
void CheckInvariant (size_t node_idx, int level, CoordT min_x, CoordT max_x, CoordT min_y, CoordT max_y) const
 Verify that the invariant is true for a sub-tree, assert if not.
 
void CheckInvariant () const
 Verify the invariant for the entire tree, does nothing unless KDTREE_DEBUG is defined.
 

Static Private Member Functions

static node_distance SelectNearestNodeDistance (const node_distance &a, const node_distance &b)
 Ordering function for node_distance objects, elements with equal distance are ordered by less-than comparison.
 

Private Attributes

std::vector< nodenodes
 Pool of all nodes in the tree.
 
std::vector< size_t > free_list
 List of dead indices in the nodes vector.
 
size_t root
 Index of root node.
 
size_t unbalanced
 Number approximating how unbalanced the tree might be.
 

Static Private Attributes

static const size_t INVALID_NODE = SIZE_MAX
 Index value indicating no-such-node.
 
static const size_t MIN_REBALANCE_THRESHOLD = 8
 Arbitrary value for "not worth rebalancing".
 

Detailed Description

template<typename T, typename TxyFunc, typename CoordT, typename DistT>
class Kdtree< T, TxyFunc, CoordT, DistT >

K-dimensional tree, specialised for 2-dimensional space.

This is not intended as a primary storage of data, but as an index into existing data. Usually the type stored by this tree should be an index into an existing array.

This implementation assumes Manhattan distances are used.

Be careful when using this in game code, depending on usage pattern, the tree shape may end up different for different clients in multiplayer, causing iteration order to differ and possibly having elements returned in different order. The using code should be designed to produce the same result regardless of iteration order.

The element type T must be less-than comparable for FindNearest to work.

Template Parameters
TType stored in the tree, should be cheap to copy.
TxyFuncFunctor type to extract coordinate from a T value and dimension index (0 or 1).
CoordTType of coordinate values extracted via TxyFunc.
DistTType to use for representing distance values.

Definition at line 35 of file kdtree.hpp.

Member Function Documentation

◆ Build()

template<typename T , typename TxyFunc , typename CoordT , typename DistT >
template<typename It >
void Kdtree< T, TxyFunc, CoordT, DistT >::Build ( It  begin,
It  end 
)
inline

Clear and rebuild the tree from a new sequence of elements,.

Template Parameters
ItIterator type for element sequence.
Parameters
beginFirst element in sequence.
endOne past last element in sequence.

Definition at line 362 of file kdtree.hpp.

References Kdtree< T, TxyFunc, CoordT, DistT >::BuildSubtree(), and Kdtree< T, TxyFunc, CoordT, DistT >::CheckInvariant().

◆ FindContained() [1/2]

template<typename T , typename TxyFunc , typename CoordT , typename DistT >
std::vector<T> Kdtree< T, TxyFunc, CoordT, DistT >::FindContained ( CoordT  x1,
CoordT  y1,
CoordT  x2,
CoordT  y2 
) const
inline

Find all items contained within the given rectangle.

Note
End coordinates are exclusive, x1<x2 && y1<y2 is a precondition.

Definition at line 475 of file kdtree.hpp.

◆ FindContained() [2/2]

template<typename T , typename TxyFunc , typename CoordT , typename DistT >
template<typename Outputter >
void Kdtree< T, TxyFunc, CoordT, DistT >::FindContained ( CoordT  x1,
CoordT  y1,
CoordT  x2,
CoordT  y2,
const Outputter &  outputter 
) const
inline

Find all items contained within the given rectangle.

Note
Start coordinates are inclusive, end coordinates are exclusive. x1<x2 && y1<y2 is a precondition.
Parameters
x1Start first coordinate, points found are greater or equals to this.
y1Start second coordinate, points found are greater or equals to this.
x2End first coordinate, points found are less than this.
y2End second coordinate, points found are less than this.
outputterCallback used to return values from the search.

Definition at line 459 of file kdtree.hpp.

References Kdtree< T, TxyFunc, CoordT, DistT >::Count().

◆ FindNearest()

template<typename T , typename TxyFunc , typename CoordT , typename DistT >
T Kdtree< T, TxyFunc, CoordT, DistT >::FindNearest ( CoordT  x,
CoordT  y 
) const
inline

Find the element closest to given coordinate, in Manhattan distance.

For multiple elements with the same distance, the one comparing smaller with a less-than comparison is chosen.

Definition at line 441 of file kdtree.hpp.

◆ FreeSubtree()

template<typename T , typename TxyFunc , typename CoordT , typename DistT >
std::vector<T> Kdtree< T, TxyFunc, CoordT, DistT >::FreeSubtree ( size_t  node_idx)
inlineprivate

Free all children of the given node.

Returns
Collection of elements that were removed from tree.

Definition at line 153 of file kdtree.hpp.

References Kdtree< T, TxyFunc, CoordT, DistT >::node::element, Kdtree< T, TxyFunc, CoordT, DistT >::INVALID_NODE, Kdtree< T, TxyFunc, CoordT, DistT >::node::left, and Kdtree< T, TxyFunc, CoordT, DistT >::node::right.

◆ Insert()

template<typename T , typename TxyFunc , typename CoordT , typename DistT >
void Kdtree< T, TxyFunc, CoordT, DistT >::Insert ( const T &  element)
inline

Insert a single element in the tree.

Repeatedly inserting single elements may cause the tree to become unbalanced. Undefined behaviour if the element already exists in the tree.

Definition at line 398 of file kdtree.hpp.

◆ Remove()

template<typename T , typename TxyFunc , typename CoordT , typename DistT >
void Kdtree< T, TxyFunc, CoordT, DistT >::Remove ( const T &  element)
inline

Remove a single element from the tree, if it exists.

Since elements are stored in interior nodes as well as leaf nodes, removing one may require a larger sub-tree to be re-built. Because of this, worst case run time is as bad as a full tree rebuild.

Definition at line 417 of file kdtree.hpp.

◆ RemoveRecursive()

template<typename T , typename TxyFunc , typename CoordT , typename DistT >
size_t Kdtree< T, TxyFunc, CoordT, DistT >::RemoveRecursive ( const T &  element,
size_t  node_idx,
int  level 
)
inlineprivate

Find and remove one element from the tree.

Parameters
elementThe element to search for
node_idxSub-tree to search in
levelCurrent depth in the tree
Returns
New root node index of the sub-tree processed

Definition at line 184 of file kdtree.hpp.


The documentation for this class was generated from the following file: