The RTree class
===============

The main class for the :mod:`librtree` package, load it with

.. code-block:: python

   from librtree import RTree

Given a set or rectangles (or higher dimensional cuboids) and
their associated ids, one can build an :class:`RTree` using the
:meth:`csv_read() <librtree.RTree.csv_read>` class method or repeated
calls to the :meth:`add_rect() <librtree.RTree.add_rect>` instance
method.  The former is more performant since it avoids routing the
rectangles through the Python-C interface.

Once the :class:`RTree` instance is created one can make spatial queries
against it with the :meth:`search() <librtree.RTree.search>` method; one
passes a rectangle to the method and it applies a user-supplied function
to all of the input rectangles which intersect it.

It may be convenient to serialise the :class:`RTree` for faster loading,
the library implements a custom binary format, BSRT (binary serialised
R-tree) which can be written by the
:meth:`bsrt_write() <librtree.RTree.bsrt_write>` instance method and read
with the :meth:`bsrt_read() <librtree.RTree.bsrt_read>` class method.
One can also serialise to JSON, but this results in a much larger file (a
factor of ten) and so correspondingly slow to read/write. Useful,
nevertheless, for debugging and loading into a native Python :class:`dict`
format (see the :meth:`to_dict() <librtree.RTree.to_dict>` method).

All rectangles used in the library are simply lists (or tuples) of
floats, the lower value for each dimension, followed by the upper
value for each dimension. Thus

.. code:: python

   (0, 0, 1, 2)

is the rectangle with 0 ≤ x ≤ 1 and 0 ≤ y ≤ 2. Upper and lower values
may coincide (to create a line segment in 2-space, for example) but
a lower value larger than the upper value will cause an error.

It is anticipated that the ids passed to the library will be used as
an index for application specific data to which this rectangle relates
(its location in a list, or a DB id) but this is entirely at the
discretion of the caller, the library makes no use of the value,
treating it as payload.  In particular, the value may be non-unique
and may be zero. One should note that the id type used internally
by the library is determined at compile-time and by default this is
a 64-bit unsigned integer.


.. autoclass:: librtree.RTree
   :members:
   :undoc-members:
   :special-members: __eq__
   :show-inheritance: