mirror of
https://github.com/boostorg/geometry.git
synced 2026-02-12 12:12:10 +00:00
640ae6ced6
Added docs regarding inserter and creation of the rtree from the query results. Added info about comparison of tuples in default translator. Merged from index_dev. [SVN r81582]
228 lines
7.5 KiB
Plaintext
228 lines
7.5 KiB
Plaintext
[/============================================================================
|
|
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 = translator::def<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::def<__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 Inserting and splitting 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' splitting algorithm. Currently, three well-known types of R-trees may be created.
|
|
|
|
Linear - classic __rtree__ using splitting algorithm of linear complexity
|
|
|
|
index::rtree< __value__, index::linear<32, 8> > rt;
|
|
|
|
Quadratic - classic __rtree__ using splitting algorithm of quadratic complexity
|
|
|
|
index::rtree< __value__, index::quadratic<32, 8> > rt;
|
|
|
|
R*-tree - splitting algorithm minimizing nodes' overlap with forced reinsertions
|
|
|
|
index::rtree< __value__, index::rstar<32, 8> > rt;
|
|
|
|
[endsect]
|
|
|
|
[section Inserting and splitting algorithms (run-time)]
|
|
|
|
Splitting 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 of Values]
|
|
|
|
The following code creates an __rtree__ using quadratic 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 /]
|