kdtree.h

Go to the documentation of this file.

/*!
 * \file kdtree.h
 *
 * \brief Dynamic balanced k-d tree implementation
 *
 * k-d tree is a multidimensional (k-dimensional) binary search tree for
 * nearest neighbor search and is part of \ref btree2.
 *
 * Copyright and license:
 *
 * SPDX-FileCopyrightText: 2014 GRASS Development Team
 * SPDX-License-Identifier: GPL-2.0-or-later
 *
 * \author Markus Metz
 *
 * \par References
 * Bentley, J. L. (1975). "Multidimensional binary search trees used for
 * associative searching". Communications of the ACM 18 (9): 509.
 * doi:10.1145/361002.361007
 *
 * \par Features
 * - This k-d tree is a dynamic tree:
 *   elements can be inserted and removed any time.
 * - This k-d tree is balanced:
 *   subtrees have a similar depth (the difference in subtrees' depths is
 *   not allowed to be larger than the balancing tolerance).
 *
 * Here is a structure of basic usage:
 *
 * Create a new k-d tree:
 *
 *     kdtree_create(...);
 *
 * Insert points into the tree:
 *
 *     kdtree_insert(...);
 *
 * Optionally optimize the tree:
 *
 *     kdtree_optimize(...);
 *
 * Search k nearest neighbors:
 *
 *     kdtree_knn(...);
 *
 * Search all neighbors in radius:
 *
 *     kdtree_dnn(...);
 *
 * Destroy the tree:
 *
 *     kdtree_destroy(...);
 *
 * \todo
 * Doxygen ignores comment for last parameter after `);`.
 * The parameter description now goes to the end of function description.
 *
 * \todo
 * Include formatting to function descriptions.
 */
 
/*!
 * \brief Node for k-d tree
 */
struct kdnode {
    unsigned char dim;     /*!< split dimension of this node */
    unsigned char depth;   /*!< depth at this node */
    unsigned char balance; /*!< flag to indicate if balancing is needed */
    double *c;             /*!< coordinates */
    int uid;               /*!< unique id of this node */
    struct kdnode
        *child[2]; /*!< link to children: `[0]` for smaller, `[1]` for larger */
};
 
/*!
 * \brief k-d tree
 */
struct kdtree {
    unsigned char ndims;    /*!< number of dimensions */
    unsigned char *nextdim; /*!< split dimension of child nodes */
    int csize;              /*!< size of coordinates in bytes */
    int btol;               /*!< balancing tolerance */
    size_t count;           /*!< number of items in the tree */
    struct kdnode *root;    /*!< tree root */
};
 
/*!
 * \brief k-d tree traversal
 */
struct kdtrav {
    struct kdtree *tree;      /*!< tree being traversed */
    struct kdnode *curr_node; /*!< current node */
    struct kdnode *up[256];   /*!< stack of parent nodes */
    int top;                  /*!< index for stack */
    int first;                /*!< little helper flag */
};
 
/*! create a new k-d tree */
struct kdtree *kdtree_create(char ndims, /*!< number of dimensions */
                             int *btol   /*!< optional balancing tolerance */
);
 
/*! destroy a tree */
void kdtree_destroy(struct kdtree *t);
 
/*! clear a tree, removing all entries */
void kdtree_clear(struct kdtree *t);
 
/*! insert an item (coordinates c and uid) into the k-d tree */
int kdtree_insert(struct kdtree *t, /*!< k-d tree */
                  double *c,        /*!< coordinates */
                  int uid,          /*!< the point's unique id */
                  int dc            /*!< allow duplicate coordinates */
);
 
/*! remove an item from the k-d tree
 * coordinates c and uid must match */
int kdtree_remove(struct kdtree *t, /*!< k-d tree */
                  double *c,        /*!< coordinates */
                  int uid           /*!< the point's unique id */
);
 
/*! find k nearest neighbors
 * results are stored in uid (uids) and d (squared distances)
 * optionally an uid to be skipped can be given
 * useful when searching for the nearest neighbors of an item
 * that is also in the tree */
int kdtree_knn(struct kdtree *t, /*!< k-d tree */
               double *c,        /*!< coordinates */
               int *uid,         /*!< unique ids of the neighbors */
               double *d,        /*!< squared distances to the neighbors */
               int k,            /*!< number of neighbors to find */
               int *skip         /*!< unique id to skip */
);
 
/*! find all nearest neighbors within distance aka radius search
 * results are stored in puid (uids) and pd (squared distances)
 * memory is allocated as needed, the calling fn must free the memory
 * optionally an uid to be skipped can be given */
int kdtree_dnn(
    struct kdtree *t, /*!< k-d tree */
    double *c,        /*!< coordinates */
    int **puid,       /*!< unique ids of the neighbors */
    double **pd,      /*!< squared distances to the neighbors */
    double maxdist,   /*!< radius to search around the given coordinates */
    int *skip         /*!< unique id to skip */
);
 
/*! find all nearest neighbors within range aka box search
 * the range is specified with min and max for each dimension as
 * (min1, min2, ..., minn, max1, max2, ..., maxn)
 * results are stored in puid (uids) and pd (squared distances)
 * memory is allocated as needed, the calling fn must free the memory
 * optionally an uid to be skipped can be given */
int kdtree_rnn(struct kdtree *t, /*!< k-d tree */
               double *c,        /*!< coordinates for range */
               int **puid,       /*!< unique ids of the neighbors */
               int *skip         /*!< unique id to skip */
);
 
/*! k-d tree optimization, only useful if the tree will be heavily used
 * (more searches than items in the tree)
 * level 0 = a bit, 1 = more, 2 = a lot */
void kdtree_optimize(struct kdtree *t, /*!< k-d tree */
                     int level         /*!< optimization level */
);
 
/*! initialize tree traversal
 * (re-)sets trav structure
 * returns 0
 */
int kdtree_init_trav(struct kdtrav *trav, struct kdtree *tree);
 
/*! traverse the tree
 * useful to get all items in the tree non-recursively
 * struct kdtrav *trav needs to be initialized first
 * returns 1, 0 when finished
 */
int kdtree_traverse(struct kdtrav *trav, double *c, int *uid);