libkdtree++ README
==================

libkdtree++ is (c) 2004 Martin F. Krafft <krafft@ailab.ch>
and distributed under the terms of the Artistic Licence.
See the file ./COPYING in the source distribution for more information.

Revision: $Id: README,v 1.3 2004/05/15 22:49:29 krafft Exp $

Introduction
------------

libkdtree++ is a C++ template container implementation of k-dimensional space
sorting, using a kd-tree. It:

  - sports an unlimited number of dimensions (in theory)
  - can store any data structure, provided the data structure provides
    operator[0 - k-1] to access the individual dimensional
    components (arrays, std::vector already do) and a std::less
    implementation for the type of dimensional components
  - has support for custom allocators
  - implements iterators
  - provides standard find as well as range queries
  - has amortised O(lg n) time (O(n lg n) worst case) on most
    operations (insert/erase/find optimised) and worst-case O(n) space.
  - provides a means to rebalance and thus optimise the tree.
  - exists in its own namespace
  - uses STL coding style, basing a lot of the code on stl_tree.h

Notes
-----

Note that the library is not (yet) complete and it's not thoroughly tested.
However, given the effort and grief I went through in writing it, I would
like to make it available to folks, get people to test it, and hopefully have
some peeps submit improvements. If you have any suggestions, please write to
me at krafft@ailab.ch.

It's not yet documented, although the usage should be fairly straight
forward. I am hoping to find someone else to document it as I suck at
documentation and as the author, it's exceptionally difficult to stay
didactically correct.

Credits
-------

While the library was written all by myself, it would not have been possible
without the help of a number of people. Foremost, I would like to thank the
folks from the #c++ channel on Freenode, specifically orbitz, quix, Erwin,
pwned, wcstok, dasOp, Chaku (if I left anyone out, let me know). Finally,
I thank the Artificial Intelligence Laboratory of the University of Zurich,
Dr. Peter Eggenberger and Gabriel Gmez for giving me the opportunity to write
this stuff.

Since libkdtree++ makes an effort to stay as close as possible to the feel of
a STL container, concepts and inspiration was gained from the SGI C++
implementation of red-black trees (stl_tree.h).

Usage
-----

A simple example program is provided in the ./examples directory
(/usr/share/doc/libkdtree++-dev/examples on Debian).

The library supports pkg-config. Thus, to compile with the library,

  #include <kdtree++/kdtree.hpp>

and append the output of `pkg-config libkdtree++ --cflags` to your $CPPFLAGS.

Have fun.
