[GRASS-SVN] r66100 - grass/trunk/lib/btree2
svn_grass at osgeo.org
svn_grass at osgeo.org
Fri Sep 4 13:00:26 PDT 2015
Author: wenzeslaus
Date: 2015-09-04 13:00:26 -0700 (Fri, 04 Sep 2015)
New Revision: 66100
Added:
grass/trunk/lib/btree2/btree2.dox
Removed:
grass/trunk/lib/btree2/README
Modified:
grass/trunk/lib/btree2/kdtree.h
Log:
dox: basic Doxygenization of btree2/kdtree docs
Include text provided by mmetz in:
https://lists.osgeo.org/pipermail/grass-dev/2015-January/072701.html
https://lists.osgeo.org/pipermail/grass-dev/2015-January/072784.html
Deleted: grass/trunk/lib/btree2/README
===================================================================
--- grass/trunk/lib/btree2/README 2015-09-04 19:40:31 UTC (rev 66099)
+++ grass/trunk/lib/btree2/README 2015-09-04 20:00:26 UTC (rev 66100)
@@ -1,94 +0,0 @@
-
-Red-Black tree
-==============
-
-#include <grass/rbtree.h>
-
-and link to BTREE2LIB
-
-to make use of the binary balanced (Red-Black) search tree
-
-NOTE: duplicates are not supported
-
-see also grass/rbtree.h for instructions on how to use it
-
-/* custom compare function */
-int my_compare_fn(const void *a, const void *b)
-{
- if ((mydatastruct *) a < (mydatastruct *) b)
- return -1;
- else if ((mydatastruct *) a > (mydatastruct *) b)
- return 1;
- else if ((mydatastruct *) a == (mydatastruct *) b)
- return 0;
-}
-
-/* create and initialize tree: */
-struct RB_TREE *mytree = rbtree_create(my_compare_fn, item_size);
-
-/* insert items to tree: */
- struct mydatastruct data = <some data>;
-
- if (rbtree_insert(mytree, &data) == 0)
- G_warning("could not insert data");
-
-/* find item in tree: */
- struct mydatastruct data = <some data>;
-
- if (rbtree_find(mytree, &data) == 0)
- G_message("data not found");
-
-/* delete item from tree: */
- struct mydatastruct data = <some data>;
-
- if (rbtree_remove(mytree, &data) == 0)
- G_warning("could not find data in tree");
-
-/* traverse tree (get all items in tree in ascending order): */
- struct RB_TRAV trav;
-
- rbtree_init_trav(&trav, tree);
- while ((data = rbtree_traverse(&trav)) != NULL) {
- if (my_compare_fn(data, threshold_data) == 0) break;
- /* do something with data */
- }
-
-/* get a selection of items: all data > data1 and < data2
- * start in tree where data is last smaller or first larger compared to data1 */
- struct RB_TRAV trav;
-
- rbtree_init_trav(&trav, tree);
- data = rbtree_traverse_start(&trav, &data1);
- /* do something with data */
- while ((data = rbtree_traverse(&trav)) != NULL) {
- if (data > data2) break;
- /* do something with data */
- }
-
-/* destroy tree: */
- rbtree_destroy(mytree);
-
-/* debug the whole tree with */
- rbtree_debug(mytree, mytree->root);
-
-
-k-d tree
-========
-
-#include <grass/kdtree.h>
-
-and link to BTREE2LIB
-
-/* create a new k-d tree, here 3D */
-struct kdtree *t = kdtree_create(3, NULL);
-
-/* insert items */
-for (i = 0; i < npoints; i++)
- kdtree_insert(t, c, i, 1);
-
-/* find nearest neighbor for each point */
-for (i = 0; i < npoints; i++)
- int found = kdtree_knn(t, c, &uid, &dist, 1, i);
-
-/* destroy the tree */
- kdtree_destroy(t);
Copied: grass/trunk/lib/btree2/btree2.dox (from rev 66075, grass/trunk/lib/btree2/README)
===================================================================
--- grass/trunk/lib/btree2/btree2.dox (rev 0)
+++ grass/trunk/lib/btree2/btree2.dox 2015-09-04 20:00:26 UTC (rev 66100)
@@ -0,0 +1,175 @@
+/*! \page btree2 btree2 library
+
+\tableofcontents
+
+Red-Black tree
+==============
+
+Include and linking
+-------------------
+
+To make use of the binary balanced (Red-Black) search tree include:
+
+ #include <grass/rbtree.h>
+
+and link to `BTREE2LIB` in a Makefile.
+
+\note
+ Duplicates are not supported.
+
+Example
+-------
+
+Define custom compare function:
+
+ int my_compare_fn(const void *a, const void *b)
+ {
+ if ((mydatastruct *) a < (mydatastruct *) b)
+ return -1;
+ else if ((mydatastruct *) a > (mydatastruct *) b)
+ return 1;
+ else if ((mydatastruct *) a == (mydatastruct *) b)
+ return 0;
+ }
+
+Create and initialize tree:
+
+ struct RB_TREE *mytree = rbtree_create(my_compare_fn, item_size);
+
+Insert items to tree:
+
+ struct mydatastruct data = <some data>;
+
+ if (rbtree_insert(mytree, &data) == 0)
+ G_warning("could not insert data");
+
+Find item in tree:
+
+ struct mydatastruct data = <some data>;
+
+ if (rbtree_find(mytree, &data) == 0)
+ G_message("data not found");
+
+Delete item from tree:
+
+ struct mydatastruct data = <some data>;
+
+ if (rbtree_remove(mytree, &data) == 0)
+ G_warning("could not find data in tree");
+
+Traverse tree (get all items in tree in ascending order):
+
+ struct RB_TRAV trav;
+
+ rbtree_init_trav(&trav, tree);
+ while ((data = rbtree_traverse(&trav)) != NULL) {
+ if (my_compare_fn(data, threshold_data) == 0) break;
+ // do something with data (using C++ comments because of Doxygen)
+ }
+
+Get a selection of items: all data > data1 and < data2.
+Start in tree where data is last smaller or first larger compared to data1:
+
+ struct RB_TRAV trav;
+
+ rbtree_init_trav(&trav, tree);
+ data = rbtree_traverse_start(&trav, &data1);
+ // do something with data
+ while ((data = rbtree_traverse(&trav)) != NULL) {
+ if (data > data2) break;
+ // do something with data
+ }
+
+Destroy tree:
+
+ rbtree_destroy(mytree);
+
+Debug the whole tree with:
+
+ rbtree_debug(mytree, mytree->root);
+
+See also \ref rbtree.h for more instructions on how to use it.
+
+
+k-d tree
+========
+
+Description
+-----------
+
+k-d tree is a multidimensional (k-dimensional) binary search tree for
+nearest neighbor search.
+
+This k-d tree finds the exact nearest neighbor(s), not some
+approximation. It supports up to 255 dimensions. It is dynamic, i.e.
+points can be inserted and removed at any time. It is balanced to
+improve search performance. It provides k nearest neighbor search
+(find k neighbors to a given coordinate) as well as radius or distance
+search (find all neighbors within radius, i.e. not farther away than
+radius to a given coordinate).
+
+
+Include and linking
+-------------------
+
+Include:
+
+ #include <grass/kdtree.h>
+
+and link to `BTREE2LIB` in a Makefile.
+
+
+Example
+-------
+
+Create a new k-d tree (here 3D):
+
+ struct kdtree *t = kdtree_create(3, NULL);
+
+Insert items:
+
+ for (i = 0; i < npoints; i++)
+ kdtree_insert(t, c, i, 1);
+
+Find nearest neighbor for each point:
+
+ for (i = 0; i < npoints; i++)
+ int found = kdtree_knn(t, c, &uid, &dist, 1, i);
+
+Destroy the tree:
+
+ kdtree_destroy(t);
+
+
+Example usages
+--------------
+
+- Nearest neighbor statistics: test if points are randomly
+ distributed. For example, an older version of GRASS addon `v.nnstat`
+ used an external k-d tree from PCL (which in turn uses flann)
+ which finds the approximate, not the exact nearest neighbor.
+ The GRASS-native k-d tree always finds the real nearest neighbor.
+
+- Spatial cluster analysis: a point cloud can be partitioned into
+ separate clusters where points within each cluster are closer to each
+ other than to points of another cluster. For example, as used in
+ \gmod{v.cluster}.
+
+- %Point cloud thinning: a sample can be generated from a large point
+ cloud by specifying a minimum distance between sample points.
+
+- This k-d tree is used by \gmod{v.clean} `tool=snap` (Vect_snap_lines()),
+ reducing both memory consumption and processing time.
+
+
+See also
+========
+
+- \ref rbtree.h
+- \ref kdtree.h
+- \ref rtree.h
+- \ref btree.h
+- [Wikipedia article on Red-black_tree](https://en.wikipedia.org/wiki/Red-black_tree)
+- [Wikipedia article on k-d tree](https://en.wikipedia.org/wiki/K-d_tree)
+
+*/
Modified: grass/trunk/lib/btree2/kdtree.h
===================================================================
--- grass/trunk/lib/btree2/kdtree.h 2015-09-04 19:40:31 UTC (rev 66099)
+++ grass/trunk/lib/btree2/kdtree.h 2015-09-04 20:00:26 UTC (rev 66100)
@@ -1,152 +1,173 @@
/*!
- * \file kdtree.c
+ * \file kdtree.h
*
- * \brief binary search tree
+ * \brief Dynamic balanced k-d tree implementation
*
- * 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:
+ *
* (C) 2014 by the GRASS Development Team
*
* This program is free software under the GNU General Public License
* (>=v2). Read the file COPYING that comes with GRASS for details.
*
* \author Markus Metz
- */
-
-/***********************************************************************
- * k-d tree:
- * multidimensional binary search tree for nearest neighbor search
- *
+ *
+ * \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:
*
- * 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)
- *
- * USAGE:
- * create a new k-d tree
- * kdtree_create();
- *
- * insert points into the tree
- * kdtree_insert();
- *
- * optionally optimize the tree:
- * kdtre_optimize
- *
- * search k nearest neighbours
- * kdtree_knn();
- *
- * search all neighbors in radius
- * kdtree_dnn();
- *
- * destroy the tree:
- * kdtree_destroy();
- *
- ***********************************************************************/
+ * 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 */
- double *c; /* coordinates */
- int uid; /* unique id of this node */
- struct kdnode *child[2]; /* link to children: link[0] for smaller, link[1] for larger */
+ unsigned char dim; /*!< split dimension of this node */
+ unsigned char depth; /*!< depth at this node */
+ 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 */
+ 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 */
+ 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 */
};
-/* creae a new k-d tree */
-struct kdtree *kdtree_create(char ndims, /* number of dimensions */
- int *btol); /* optional balancing tolerance */
+/*! creae a new k-d tree */
+struct kdtree *kdtree_create(char ndims, /*!< number of dimensions */
+ int *btol); /*!< optional balancing tolerance */
-/* destroy a tree */
+/*! destroy a tree */
void kdtree_destroy(struct kdtree *t);
-/* clear a tree, removing all entries */
+/*! 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 */
+/*! 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
+/*! 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 */
+int kdtree_remove(struct kdtree *t, /*!< k-d tree */
+ double *c, /*!< coordinates */
+ int uid); /*!< the point's unique id */
-/* find k nearest neighbors
+/*! 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 */
+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
+/*! 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 */
+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
+/*! 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 */
+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
+/*! 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 */
+void kdtree_optimize(struct kdtree *t, /*!< k-d tree */
+ int level); /*!< optimization level */
-/* initialize tree traversal
+/*! initialize tree traversal
* (re-)sets trav structure
* returns 0
*/
int kdtree_init_trav(struct kdtrav *trav, struct kdtree *tree);
-/* traverse the 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
More information about the grass-commit
mailing list