geometry/doc/rtree/creation.qbk

[/============================================================================
  Boost.Geometry Index

  Copyright (c) 2011-2012 Adam Wulkiewicz.

  Use, modification and distribution is subject to the Boost Software License,
  Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt)
=============================================================================/]

[section Creation and modification]

[section Template parameters]

__rtree__ has 4 parameters:

 rtree<Value, Parameters, Translator = index::translator<Value>, Allocator> = std::allocator<Value> >

* `__value__` - type of object which will be stored in the container,
* `Parameters` - parameters type, inserting/splitting algorithm,
* `__translator__` - type of object translating `Value` objects to
  `__indexable__` objects (`__point__` or `__box__`) which __rtree__ can handle,
* `Allocator` - `Value`s allocator, all allocators needed by the container are created from it.

[endsect]

[section Values, Indexables and default Translator]

__rtree__ may store `__value__`s of any type as long the `__translator__` knows how to interpret those `__value__`s
and extract an object that the __rtree__ can handle. Those objects are called
`__indexable__`s in this documentation. Each type adapted to `__point__` or `__box__` concept is an `__indexable__`.
`__value__`s types which can be handled by the default `__translator__` - `index::translator<__value__>`
are defined as follows:

* `__indexable__ = __point__ | __box__`
* `__value__ = Indexable | std::pair<__indexable__, T> | boost::tuple<__indexable__, ...>`

Examples of default `__value__` types:

 geometry::model::point<...>
 geometry::model::point_xy<...>
 geometry::model::box<...>
 std::pair<geometry::model::box<...>, unsigned>
 boost::tuple<geometry::model::point<...>, int, float>

A `__translator__` is a type which knows how to handle `__value__`s. It has two purposes:

* it translates `__value__` to a more suitable `__indexable__` type which is needed by most of operations,
* performs a comparison of `__value__` which is needed by the removing process.

A `__translator__` translates the `__value__` each time the __rtree__ needs it. For this reason
it should rather return const reference to the `__indexable__` than a copy.

If comparison of two `__value__`s is required, the default translator:

* for `__point__` and `__box__` - compares `__value__`s with geometry::equals().
* for `std::pair<...>` - compares both components of the `__value__`. The first one is compared with `geometry::equals()`.
  If the second one is a `Geometry`, `geometry::equals()` function is used. For other types it uses `operator==()`.
* for `boost::tuple<...>` - compares all components of the `__value__`. If the component is a `Geometry`, `geometry::equals()`
  function is used. For other types it uses `operator==()`.

[endsect]

[section Balancing algorithms (compile-time)]

`__value__`s may be inserted to the __rtree__ in many various ways. Final internal structure
of the __rtree__ depends on algorithms used in the insertion process and parameters. The most important is
nodes' balancing algorithm. Currently, three well-known types of R-trees may be created.

Linear - classic __rtree__ using balancing algorithm of linear complexity

 index::rtree< __value__, index::linear<32, 8> > rt;

Quadratic - classic __rtree__ using balancing algorithm of quadratic complexity

 index::rtree< __value__, index::quadratic<32, 8> > rt;

R*-tree - balancing algorithm minimizing nodes' overlap with forced reinsertions
 
 index::rtree< __value__, index::rstar<32, 8> > rt;

[endsect]

[section Balancing algorithms (run-time)]

Balancing algorithm parameters may be passed to the __rtree__ in run time.
To use run-time versions of the __rtree__ one may pass parameters defined in index::runtime
namespace.

 // linear
 index::rtree<__value__, index::runtime::linear> rt(index::runtime::linear(32, 8));

 // quadratic
 index::rtree<__value__, index::runtime::quadratic> rt(index::runtime::quadratic(32, 8));

 // rstar
 index::rtree<__value__, index::runtime::rstar> rt(index::runtime::rstar(32, 8));

The obvious drawback is a slightly slower __rtree__.

[endsect]

[section Copying, moving and swapping]

The __rtree__ is copyable and movable container. Move semantics is implemented using Boost.Move library
which also supports compilers not supporting rvalue references.

 // default constructor
 index::rtree< __value__, index::quadratic<32, 8> > rt1;

 // copy constructor
 index::rtree< __value__, index::quadratic<32, 8> > rt2(r1);

 // copy assignment
 rt2 = r1;

 // move constructor
 index::rtree< __value__, index::quadratic<32, 8> > rt3(boost::move(rt1));

 // move assignment
 rt3 = boost::move(rt2);

 // swap
 rt3.swap(rt2);

[endsect]

[section Inserting and removing Values]

The following code creates an __rtree__ using quadratic balancing algorithm.

 using namespace boost::geometry;
 typedef std::pair<Box, int> __value__;
 index::rtree< __value__, index::quadratic<32, 8> > rt;

To insert or remove a `__value__' by method call one may use the following
code.

 __value__ v = std::make_pair(__box__(...), 0);

 rt.insert(v);

 rt.remove(v);

To insert or remove a `__value__' by function call one may use the following
code.

 __value__ v = std::make_pair(__box__(...), 0);

 index::insert(rt, v);

 index::remove(rt, v);

Typically you will perform those operations in a loop in order to e.g. insert
some number of `__value__`s corresponding to geometrical objects (e.g. `Polygons`)
stored in another container.

[endsect]

[section Additional interface]

The __rtree__ allows creation, inserting and removing of Values from a range. The range may be passed as
[first, last) Iterators pair or as a Range.

 namespace bgi = boost::geometry::index;
 typedef std::pair<Box, int> __value__;
 typedef bgi::rtree< __value__, bgi::linear<32, 8> > RTree;

 std::vector<__value__> values;
 /* vector filling code, here */

 // create R-tree with default constructor and insert values with insert(Value const&)
 RTree rt1;
 BOOST_FOREACH(__value__ const& v, values)
    rt1.insert(v);

 // create R-tree with default constructor and insert values with insert(Iter, Iter)
 RTree rt2;
 rt2.insert(values.begin(), values.end());

 // create R-tree with default constructor and insert values with insert(Range)
 RTree rt3;
 rt3.insert(values);

 // create R-tree with constructor taking Iterators
 RTree rt4(values.begin(), values.end());

 // create R-tree with constructor taking Range
 RTree rt5(values);

 // remove values with remove(Value const&)
 BOOST_FOREACH(__value__ const& v, values)
    rt1.remove(v);

 // remove values with remove(Iter, Iter)
 rt2.remove(values.begin(), values.end());

 // remove values with remove(Range)
 rt3.remove(values);

[endsect]

[section Insert iterator]

There are functions like `std::copy()`, or __rtree__'s queries that copy values to an output iterator.
In order to insert values to a container in this kind of function insert iterators may be used.
Geometry.Index provide its own `bgi::insert_iterator<Container>` which is generated by
`bgi::inserter()` function.

 namespace bgi = boost::geometry::index;
 typedef std::pair<Box, int> __value__;
 typedef bgi::rtree< __value__, bgi::linear<32, 8> > RTree;

 std::vector<__value__> values;
 /* vector filling code, here */

 // create R-tree and insert values from the vector
 RTree rt1;
 std::copy(values.begin(), values.end(), bgi::inserter(rt1));
 
 // create R-tree and insert values returned by a query
 RTree rt2;
 rt1.spatial_query(Box(/*...*/), bgi::inserter(rt2));

[endsect]

[endsect] [/ Creation and modification /]