OpenTTD Source
20241108-master-g80f628063a
|
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 (TxyFunc xyfunc) | |
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. | |
T | 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 () |
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) |
Verify that the invariant is true for a sub-tree, assert if not. | |
void | CheckInvariant () |
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< node > | nodes |
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. | |
TxyFunc | xyfunc |
Functor to extract a coordinate from an element. | |
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. | |
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.
T | Type stored in the tree, should be cheap to copy. |
TxyFunc | Functor type to extract coordinate from a T value and dimension index (0 or 1). |
CoordT | Type of coordinate values extracted via TxyFunc. |
DistT | Type to use for representing distance values. |
Definition at line 35 of file kdtree.hpp.
|
inline |
Clear and rebuild the tree from a new sequence of elements,.
It | Iterator type for element sequence. |
begin | First element in sequence. |
end | One 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().
|
inline |
Find all items contained within the given rectangle.
Definition at line 475 of file kdtree.hpp.
|
inline |
Find all items contained within the given rectangle.
x1 | Start first coordinate, points found are greater or equals to this. |
y1 | Start second coordinate, points found are greater or equals to this. |
x2 | End first coordinate, points found are less than this. |
y2 | End second coordinate, points found are less than this. |
outputter | Callback used to return values from the search. |
Definition at line 459 of file kdtree.hpp.
References Kdtree< T, TxyFunc, CoordT, DistT >::Count().
|
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.
|
inlineprivate |
Free all children of the given node.
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.
|
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.
|
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.
Referenced by Sign::UpdateVirtCoord(), Town::UpdateVirtCoord(), and Waypoint::UpdateVirtCoord().
|
inlineprivate |
Find and remove one element from the tree.
element | The element to search for |
node_idx | Sub-tree to search in |
level | Current depth in the tree |
Definition at line 184 of file kdtree.hpp.