Boost Geometry II

Creation and Modification

Template parameters

模版参数

R-tree has 5 parameters but only 2 are required:
R-tree有5个参数但是只有2个是必须

rtree<Value,
      Parameters,
      IndexableGetter = index::indexable<Value>,
      EqualTo = index::equal_to<Value>,
      Allocator = std::allocator<Value> >

Value - type of object which will be stored in the container,

对象的类型必须存储在容器里

Parameters - parameters type, inserting/splitting algorithm,

参数类型，插入/裂开算法

IndexableGetter - function object translating Value to Indexable (Point or Box) which R-tree can handle,

r-tree对象函数 将Value翻译成可变的（点或者区域）

EqualTo - function object comparing Values,

对象函数 对比Values

Allocator - Values allocator, all allocators needed by the container are created from it.

值的分配算符， 所有的容器被创建时 所需要的分配器

Values and Indexables

R-tree may store Values of any type as long as passed function objects know how to interpret those Values, that is extract an Indexable that the R-tree can handle and compare Values.

R-tree 可以存储任何类型的值，只要passed函数知道如何理解，理解是指能提取出一个R-tree可以控制和比较的可索引的值

By default function objects index::indexable<Value> and index::equal_to<Value> are defined for some typically used Value types which may be stored without defining any additional classes. By default the rtree may store pure Indexables, pairs and tuples. In the case of those two collection types, the Indexable must be the first stored type.

 默认情况下对象函数index::indexable<Value>和index::equal_to<Value>定义一些未储存在任何额外的类里的值.一般来说r-tree可以储存索引，一对和元组.对于这俩个集合类型，索引必定是第一个被存储的类型

Indexable = Point | Box

Value = Indexable | std::pair<Indexable, T> | tuple<Indexable, ...>

By default boost::tuple<...> is supported on all compilers. If the compiler supports C++11 tuples and variadic templates then std::tuple<...> may be used "out of the box" as well.
默认情况下boost::tuple<...>支持所有的编译器，如果编译器支持c++11空间和二元可变模版，那么std::tuple<...>也可以被“即开即用”.

Examples of default Value types:

默认value类型的例子

geometry::model::point<...>
geometry::model::point_xy<...>
geometry::model::box<...>
std::pair<geometry::model::box<...>, unsigned>

boost::tuple<geometry::model::point<...>, int, float>

The predefined index::indexable<Value> returns const reference to the Indexable stored in the Value.
预定义的index::indexable<value>返回的常量引用索引存储在value中

Important
The translation is done quite frequently inside the container - each time the rtree needs it.
每次r-tree需要翻译，翻译都会在容器中运转

The predefined index::equal_to<Value>:

for Point and Box - compares Values with geometry::equals().

在point和box中用geometry::equals()来对比值

for std::pair<...> - compares both components of the Value. The first value stored in the pair is compared before the second one. If the value stored in the pair is a Geometry, geometry::equals() is used. For other types it uses operator==().

在std::pair<..>中 每个元件的value都会被对比.在pair中第一个值先被比较(按顺序作比较).如果存储在pair中的值是一个geometry, 就会用到geometry::equals().对于其他类型就会用operator==()来比较.

for tuple<...> - compares all components of the Value. If the component is a Geometry, geometry::equals() function is used. For other types it uses operator==().

Balancing algorithms compile-time parameters

在tuple<...>中 每个元件的value都会被对比.如果元件是Geometry,就会用geometry::equals()函数.对于其他类型就会用operator==().平衡算法编译参数

Values may be inserted to the R-tree in many various ways. Final internal structure of the R-tree 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.
value被插入到r-tree时可以用各种各样的方法.r-tree内部结构取决于插入过程和参数的算法.最重要的是节点的平衡算法.目前，有三个著名的r-tree类型可以被使用

Linear - classic R-tree using balancing algorithm of linear complexity
Linear - r-tree使用线性复杂的平衡算法

index::rtree< Value, index::linear<16> > rt;

Quadratic - classic R-tree using balancing algorithm of quadratic complexity
Quadratic - r-tree利用二次复杂的平衡算法

index::rtree< Value, index::quadratic<16> > rt;
R*-tree - balancing algorithm minimizing nodes' overlap with forced reinsertions
R*-tree - 平衡算法利用插入减少节点的重复性.

index::rtree< Value, index::rstar<16> > rt;

Balancing algorithms run-time parameters

平衡算法 运算参数

Balancing algorithm parameters may be passed to the R-tree in run-time. To use run-time versions of the R-tree one may pass parameters which names start with dynamic_.
平衡算法参数可以被传递到R-tree中的运行.使用r-tree时传递名字前带有dynamic的参数.

// linear
index::rtree<Value, index::dynamic_linear> rt(index::dynamic_linear(16));


// quadratic
index::rtree<Value, index::dynamic_quadratic> rt(index::dynamic_quadratic(16));


// rstar
index::rtree<Value, index::dynamic_rstar> rt(index::dynamic_rstar(16));
The obvious drawback is a slightly slower R-tree.
最明显的缺点是速度稍慢.

Non-default parameters
Non-default R-tree parameters are described in the reference.


Copying, moving and swapping
The R-tree is copyable and movable container. Move semantics is implemented using Boost.Move library so it's possible to move the container on a compilers without rvalue references support.
r-tree是一个可进行复制和移动的容器.移动容器使用库Boost.Move  移动容器的库.它可以在编译器上移动容器 不支持右值引用

// default constructor
index::rtree< Value, index::rstar<8> > rt1;

// copy constructor
index::rtree< Value, index::rstar<8> > rt2(r1);

// copy assignment
rt2 = r1;


// move constructor
index::rtree< Value, index::rstar<8> > rt3(boost::move(rt1));

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

// swap
rt3.swap(rt2);
Inserting and removing Values
The following code creates an R-tree using quadratic balancing algorithm.
下面的例子使用二次平衡算法的rtree

using namespace boost::geometry;
typedef std::pair<Box, int> Value;
index::rtree< Value, index::quadratic<16> > 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 Values corresponding to geometrical objects (e.g. Polygons) stored in another container.
通常情况下在循环中很多操作例如插入一些相应的集合对象到容器里

Additional interface
The R-tree allows creation, inserting and removing of Values from a range. The range may be passed as [first, last) Iterators pair or as a Range.
在一定范围内r-tree可以进行创建，插入和删除。范围可以在[first,last)迭代器的pair中或者作为一个范围被传递

namespace bgi = boost::geometry::index;
typedef std::pair<Box, int> Value;
typedef bgi::rtree< Value, bgi::linear<32> > 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);
Insert iterator
There are functions like std::copy(), or R-tree'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.
类似于std::copy(),或者r-tree查询复制值到输出的迭代器.为了向在容器中插入值可使用这种插入函数. Geometry.Index提供自己的bgi:: insert_iterator<容器>这是由bgi::inserter()函数生成的。

namespace bgi = boost::geometry::index;
typedef std::pair<Box, int> Value;
typedef bgi::rtree< Value, bgi::linear<32> > 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));