boost/geometry
2
0
Fork 0
mirror of https://github.com/boostorg/geometry.git synced 2026-02-20 14:52:10 +00:00
Code Issues Projects Releases Wiki Activity

Rtree docs and sample modified.

Browse Source 
Rtree introduction expanded.
Quickstart improved.

[SVN r81539]
This commit is contained in:
Adam Wulkiewicz
2012-11-25 20:56:38 +00:00
parent f7d7e88bbb
commit 7babc43f75
23 changed files with 356 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/html/geometry_index/introduction.html
View File

@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Introduction</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="prev" href="../index.html" title="Chapter&#160;1.&#160;Geometry Index">

2
doc/html/geometry_index/r_tree.html
View File

@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>R-tree</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="prev" href="introduction.html" title="Introduction">

6
doc/html/geometry_index/r_tree/creation_and_modification.html
View File

@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Creation and modification</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="up" href="../r_tree.html" title="R-tree">
<link rel="prev" href="rtree_quickstart.html" title="Quick Start">
@@ -51,7 +51,7 @@
</p>
<pre class="programlisting"><span class="identifier">rtree</span><span class="special">&lt;</span><span class="identifier">Value</span><span class="special">,</span> <span class="identifier">Parameters</span><span class="special">,</span> <span class="identifier">Translator</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">&gt;</span>
</pre>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<code class="computeroutput">Value</code> - type of object which will be stored in the container.
</li>
@@ -88,7 +88,7 @@
or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;...&gt;</span></code>
<code class="computeroutput">Value</code>s.
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<code class="computeroutput">Indexable <span class="special">=</span> <a href="http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_point.html" target="_top">Point</a>
<span class="special">|</span> <a href="http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_box.html" target="_top">Box</a></code>

12
doc/html/geometry_index/r_tree/exception_safety.html
View File

@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Exception safety</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="up" href="../r_tree.html" title="R-tree">
<link rel="prev" href="nearest_neighbours_queries.html" title="Nearest neighbours queries">
@@ -28,7 +28,7 @@
<p>
In order to be exception-safe the R-tree requires:
</p>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Nonthrowing destructor of the <code class="computeroutput">Value</code>.
</li>
@@ -155,7 +155,7 @@
<td>
<p>
<span class="emphasis"><em>nothrow</em></span> or <span class="bold"><strong>strong</strong></span>
<sup>[<a name="geometry_index.r_tree.exception_safety.f0" href="#ftn.geometry_index.r_tree.exception_safety.f0" class="footnote">a</a>]</sup>
<a href="#ftn.geometry_index.r_tree.exception_safety.f0" class="footnote"><sup class="footnote"><a name="geometry_index.r_tree.exception_safety.f0"></a>[a]</sup></a>
</p>
</td>
</tr>
@@ -308,7 +308,7 @@
<td>
<p>
<span class="emphasis"><em>nothrow</em></span> or <span class="bold"><strong>strong</strong></span>
<sup>[<a name="geometry_index.r_tree.exception_safety.f1" href="#ftn.geometry_index.r_tree.exception_safety.f1" class="footnote">b</a>]</sup>
<a href="#ftn.geometry_index.r_tree.exception_safety.f1" class="footnote"><sup class="footnote"><a name="geometry_index.r_tree.exception_safety.f1"></a>[b]</sup></a>
</p>
</td>
</tr>
@@ -350,10 +350,10 @@
</tr>
</tbody>
<tbody class="footnotes"><tr><td colspan="2">
<div class="footnote"><p><sup>[<a id="ftn.geometry_index.r_tree.exception_safety.f0" href="#geometry_index.r_tree.exception_safety.f0" class="para">a</a>] </sup>
<div id="ftn.geometry_index.r_tree.exception_safety.f0" class="footnote"><p><a href="#geometry_index.r_tree.exception_safety.f0" class="para"><sup class="para">[a] </sup></a>
<span class="emphasis"><em>nothrow</em></span> - if allocators are equal, <span class="bold"><strong>strong</strong></span> - otherwise
</p></div>
<div class="footnote"><p><sup>[<a id="ftn.geometry_index.r_tree.exception_safety.f1" href="#geometry_index.r_tree.exception_safety.f1" class="para">b</a>] </sup>
<div id="ftn.geometry_index.r_tree.exception_safety.f1" class="footnote"><p><a href="#geometry_index.r_tree.exception_safety.f1" class="para"><sup class="para">[b] </sup></a>
<span class="emphasis"><em>nothrow</em></span> - if <code class="computeroutput"><span class="identifier">CoordinateType</span></code>
has nonthrowing copy constructor, <span class="bold"><strong>strong</strong></span>
- otherwise

191
doc/html/geometry_index/r_tree/introduction.html
View File

@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Introduction</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="up" href="../r_tree.html" title="R-tree">
<link rel="prev" href="../r_tree.html" title="R-tree">
@@ -27,12 +27,191 @@
<a name="geometry_index.r_tree.introduction"></a><a class="link" href="introduction.html" title="Introduction">Introduction</a>
</h3></div></div></div>
<p>
R-tree is a self-balancing search tree. Each tree's node store a box descring
the space occupied by children nodes. At the bottom of the structure, there
are leaf-nodes which contains values (geometric objects representations).
Minimal and maximal numbers of values/children which may be stored inside
each node are user defined.
R-tree is a tree data structure used for spatial searching. It was proposed
by Antonin Guttman in 1984 <a href="#ftn.geometry_index.r_tree.introduction.f0" class="footnote"><sup class="footnote"><a name="geometry_index.r_tree.introduction.f0"></a>[1]</sup></a> as an expansion of B-tree for multi-dimensional data. It may
be used to store points or volumetric data in order to perform a spatial
query later. This query may return objects that are inside some area or are
close to some point in space.
</p>
<p>
The R-tree structure is presented on the image below. Each R-tree's node
store a box descring the space occupied by its children nodes. At the bottom
of the structure, there are leaf-nodes which contains values (geometric objects
representations).
</p>
<p>
<span class="inlinemediaobject"><img src="../../../images/rstar.png" alt="rstar"></span>
</p>
<p>
The number of maximum and mininimum node's elements must be specified by
the user. If the number of elements reaches it's maximum the new node is
created and elements are split between nodes. If the number of elements in
node is too small, the node is deleted and elements are reinserted into the
tree.
</p>
<p>
The R-tree is a self-balanced data structure. The key part of balancing algorithm
is node splitting algorithm mentioned before <a href="#ftn.geometry_index.r_tree.introduction.f1" class="footnote"><sup class="footnote"><a name="geometry_index.r_tree.introduction.f1"></a>[2]</sup></a> <a href="#ftn.geometry_index.r_tree.introduction.f2" class="footnote"><sup class="footnote"><a name="geometry_index.r_tree.introduction.f2"></a>[3]</sup></a>. Each algorithm would produce different splits so the internal
structure of a tree may be different for each one of them. In general more
complex algorithms analyses elements better and produces less overlapping
nodes. This is a "better" split because later, in the searching
process less nodes must be traversed in order to find desired obejcts. On
the other hand more complex analysis takes more time. In general faster inserting
will result in slower searching and vice versa. Example structures of trees
created by use of three different algorithms and operations time are presented
below.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
</th>
<th>
<p>
linear algorithm
</p>
</th>
<th>
<p>
quadratic algorithm
</p>
</th>
<th>
<p>
R*-tree
</p>
</th>
</tr></thead>
<tbody>
<tr>
<td>
<p>
<span class="bold"><strong>Structure</strong></span>
</p>
</td>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/linear.png" alt="linear"></span>
</p>
</td>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/quadratic.png" alt="quadratic"></span>
</p>
</td>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/rstar.png" alt="rstar"></span>
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="bold"><strong>1M Values inserts</strong></span>
</p>
</td>
<td>
<p>
1.85s
</p>
</td>
<td>
<p>
3.10s
</p>
</td>
<td>
<p>
24.52s
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="bold"><strong>1M spatial queries</strong></span>
</p>
</td>
<td>
<p>
8.60s
</p>
</td>
<td>
<p>
2.74s
</p>
</td>
<td>
<p>
1.31s
</p>
</td>
</tr>
<tr>
<td>
<p>
<span class="bold"><strong>100k knn queries</strong></span>
</p>
</td>
<td>
<p>
3.49s
</p>
</td>
<td>
<p>
1.59s
</p>
</td>
<td>
<p>
0.84s
</p>
</td>
</tr>
</tbody>
</table></div>
<p>
Key features of this implementation of the R-tree are:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
three different creation algorithms - linear, quadratic or rstar,
</li>
<li class="listitem">
parameters (including maximal and minimal number of elements) may be
passed as compile- or run-time parameters - compile-time version is faster,
</li>
<li class="listitem">
capable to store arbitrary Value type,
</li>
<li class="listitem">
sophisticated queries - e.g. search for 5 nearest values intersecting
some region but not within the other one.
</li>
</ul></div>
<div class="footnotes">
<br><hr style="width:100; align:left;">
<div id="ftn.geometry_index.r_tree.introduction.f0" class="footnote"><p><a href="#geometry_index.r_tree.introduction.f0" class="para"><sup class="para">[1] </sup></a>
Guttman, A. (1984). <span class="emphasis"><em>R-Trees: A Dynamic Index Structure for Spatial
Searching</em></span> footnote
</p></div>
<div id="ftn.geometry_index.r_tree.introduction.f1" class="footnote"><p><a href="#geometry_index.r_tree.introduction.f1" class="para"><sup class="para">[2] </sup></a>
Greene, D. (1989). <span class="emphasis"><em>An implementation and performance analysis
of spatial data access methods</em></span>
</p></div>
<div id="ftn.geometry_index.r_tree.introduction.f2" class="footnote"><p><a href="#geometry_index.r_tree.introduction.f2" class="para"><sup class="para">[3] </sup></a>
Beckmann, N.; Kriegel, H. P.; Schneider, R.; Seeger, B. (1990). <span class="emphasis"><em>The
R*-tree: an efficient and robust access method for points and rectangles</em></span>
</p></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>

2
doc/html/geometry_index/r_tree/nearest_neighbours_queries.html
View File

@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Nearest neighbours queries</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="up" href="../r_tree.html" title="R-tree">
<link rel="prev" href="spatial_queries.html" title="Spatial queries">

89
doc/html/geometry_index/r_tree/rtree_quickstart.html
View File

@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Quick Start</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="up" href="../r_tree.html" title="R-tree">
<link rel="prev" href="introduction.html" title="Introduction">
@@ -35,23 +35,32 @@
</p>
<p>
</p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">/</span><span class="identifier">geometries</span><span class="special">/</span><span class="identifier">point_xy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">/</span><span class="identifier">geometries</span><span class="special">/</span><span class="identifier">box</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">/</span><span class="identifier">extensions</span><span class="special">/</span><span class="identifier">index</span><span class="special">/</span><span class="identifier">rtree</span><span class="special">/</span><span class="identifier">rtree</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="comment">// to store queries results</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
<span class="comment">// just for output</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">foreach</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">bg</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">geometry</span><span class="special">;</span>
<span class="keyword">namespace</span> <span class="identifier">bgi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">geometry</span><span class="special">::</span><span class="identifier">index</span><span class="special">;</span>
</pre>
<p>
</p>
<p>
It is possible to store user-defined types in the R-tree. To keep it simple
we will use predefined <a href="http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_point.html" target="_top">Point</a>
and <a href="http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_box.html" target="_top">Box</a>.
Typically you'll store e.g. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">Box</span><span class="special">,</span> <span class="identifier">MyGeometryId</span><span class="special">&gt;</span></code> in the R-tree. <code class="computeroutput"><span class="identifier">MyGeometryId</span></code>
will be some indentifier of a complex <code class="computeroutput"><span class="identifier">Geometry</span></code>
stored in other container, e.g. index type of a <code class="computeroutput"><span class="identifier">Polygon</span></code>
stored in the vector or an iterator of list of <code class="computeroutput"><span class="identifier">Ring</span></code>s.
To keep it simple to define <code class="computeroutput"><span class="identifier">Value</span></code>
we will use predefined <a href="http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_box.html" target="_top">Box</a>
and unsigned int.
</p>
<p>
</p>
@@ -62,54 +71,86 @@
<p>
</p>
<p>
R-tree may be created using various algorithm and parameters. In this example
we will use quadratic algorithm. Maximum number of elements in nodes are
set to 32, minimum to 8.
R-tree may be created using various algorithm and parameters. You should
choose the algorithm you'll find the best for your purpose. In this example
we will use quadratic algorithm. Parameters are passed as template parameters.
Maximum number of elements in nodes are set to 32, minimum to 8.
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">bgi</span><span class="special">::</span><span class="identifier">rtree</span><span class="special">&lt;</span> <span class="identifier">value</span><span class="special">,</span> <span class="identifier">bgi</span><span class="special">::</span><span class="identifier">quadratic</span><span class="special">&lt;</span><span class="number">32</span><span class="special">,</span> <span class="number">8</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">rtree</span><span class="special">;</span>
<pre class="programlisting"><span class="comment">// create the rtree using default constructor</span>
<span class="identifier">bgi</span><span class="special">::</span><span class="identifier">rtree</span><span class="special">&lt;</span> <span class="identifier">value</span><span class="special">,</span> <span class="identifier">bgi</span><span class="special">::</span><span class="identifier">quadratic</span><span class="special">&lt;</span><span class="number">32</span><span class="special">,</span> <span class="number">8</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">rtree</span><span class="special">;</span>
</pre>
<p>
</p>
<p>
Inserting values into the R-tree may be done by calling insert() method.
Typically <code class="computeroutput"><span class="identifier">Value</span></code>s will be
generated in a loop from e.g. <code class="computeroutput"><span class="identifier">Polygon</span></code>s
stored in some other container. In this case <code class="computeroutput"><span class="identifier">Box</span></code>
objects will probably be created with <code class="computeroutput"><span class="identifier">geometry</span><span class="special">::</span><span class="identifier">make_envelope</span><span class="special">()</span></code> function. But to keep it simple lets just
generate some boxes manually and insert them into the R-tree by using <code class="computeroutput"><span class="identifier">insert</span><span class="special">()</span></code>
method.
</p>
<p>
</p>
<pre class="programlisting"><span class="comment">// create some box</span>
<span class="comment">// this typically will be an envelope of some geometry</span>
<span class="identifier">box</span> <span class="identifier">b</span><span class="special">(</span><span class="identifier">point</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">),</span> <span class="identifier">point</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">10</span><span class="special">));</span>
<span class="comment">// insert new value</span>
<span class="identifier">rtree</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span> <span class="number">0</span><span class="special">));</span>
<pre class="programlisting"><span class="comment">// create some values</span>
<span class="keyword">for</span> <span class="special">(</span> <span class="keyword">unsigned</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span> <span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="number">10</span> <span class="special">;</span> <span class="special">++</span><span class="identifier">i</span> <span class="special">)</span>
<span class="special">{</span>
<span class="comment">// create a box</span>
<span class="identifier">box</span> <span class="identifier">b</span><span class="special">(</span><span class="identifier">point</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="identifier">i</span><span class="special">),</span> <span class="identifier">point</span><span class="special">(</span><span class="identifier">i</span> <span class="special">+</span> <span class="number">0.5f</span><span class="special">,</span> <span class="identifier">i</span> <span class="special">+</span> <span class="number">0.5f</span><span class="special">));</span>
<span class="comment">// insert new value</span>
<span class="identifier">rtree</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span> <span class="identifier">i</span><span class="special">));</span>
<span class="special">}</span>
</pre>
<p>
</p>
<p>
There are various types of spatial queries that may be performed, they can
be even combined together in one call. For simplicity, default one is used.
be even combined together in one call. For simplicity, we use the default
one. The following query return values intersecting a box. The sequence of
<code class="computeroutput"><span class="identifier">Values</span></code> in the result is not
specified.
</p>
<p>
</p>
<pre class="programlisting"><span class="comment">// find values intersecting a box</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">value</span><span class="special">&gt;</span> <span class="identifier">result</span><span class="special">;</span>
<span class="identifier">rtree</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">b</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
<pre class="programlisting"><span class="comment">// find values intersecting some area defined by a box</span>
<span class="identifier">box</span> <span class="identifier">query_box</span><span class="special">(</span><span class="identifier">point</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">),</span> <span class="identifier">point</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">5</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">value</span><span class="special">&gt;</span> <span class="identifier">result_s</span><span class="special">;</span>
<span class="identifier">rtree</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">query_box</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result_s</span><span class="special">));</span>
</pre>
<p>
</p>
<p>
Default k-nearest neighbors query may be performed as follows.
Other type of query is k-nearest neighbor search. It returns some number
of values nearest to some point in space. The default knn query may be performed
as follows. The sequence of <code class="computeroutput"><span class="identifier">Values</span></code>
in the result is not specified.
</p>
<p>
</p>
<pre class="programlisting"><span class="comment">// find 5 nearest values to a point</span>
<span class="identifier">rtree</span><span class="special">.</span><span class="identifier">nearest_query</span><span class="special">(</span><span class="identifier">point</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">),</span> <span class="number">5</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">value</span><span class="special">&gt;</span> <span class="identifier">result_n</span><span class="special">;</span>
<span class="identifier">rtree</span><span class="special">.</span><span class="identifier">nearest_query</span><span class="special">(</span><span class="identifier">point</span><span class="special">(</span><span class="number">0</span><span class="special">,</span> <span class="number">0</span><span class="special">),</span> <span class="number">5</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result_n</span><span class="special">));</span>
</pre>
<p>
</p>
<p>
At the end we'll print results.
</p>
<p>
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"spatial query result:"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">BOOST_FOREACH</span><span class="special">(</span><span class="identifier">value</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">result_s</span><span class="special">)</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">bg</span><span class="special">::</span><span class="identifier">wkt</span><span class="special">&lt;</span><span class="identifier">box</span><span class="special">&gt;(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">first</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" - "</span> <span class="special">&lt;&lt;</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">second</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"knn query result:"</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
<span class="identifier">BOOST_FOREACH</span><span class="special">(</span><span class="identifier">value</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">result_n</span><span class="special">)</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">bg</span><span class="special">::</span><span class="identifier">wkt</span><span class="special">&lt;</span><span class="identifier">box</span><span class="special">&gt;(</span><span class="identifier">v</span><span class="special">.</span><span class="identifier">first</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="string">" - "</span> <span class="special">&lt;&lt;</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">second</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
</pre>
<p>
</p>
<h4>
<a name="geometry_index.r_tree.rtree_quickstart.h0"></a>
<span><a name="geometry_index.r_tree.rtree_quickstart.more"></a></span><a class="link" href="rtree_quickstart.html#geometry_index.r_tree.rtree_quickstart.more">More</a>
<span class="phrase"><a name="geometry_index.r_tree.rtree_quickstart.more"></a></span><a class="link" href="rtree_quickstart.html#geometry_index.r_tree.rtree_quickstart.more">More</a>
</h4>
<p>
More information about the R-tree implementation, other algorithms and queries

2
doc/html/geometry_index/r_tree/spatial_queries.html
View File

@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Spatial queries</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="up" href="../r_tree.html" title="R-tree">
<link rel="prev" href="creation_and_modification.html" title="Creation and modification">

4
doc/html/index.html
View File

@@ -3,7 +3,7 @@
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Chapter&#160;1.&#160;Geometry Index</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="next" href="geometry_index/introduction.html" title="Introduction">
</head>
@@ -56,7 +56,7 @@
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: November 24, 2012 at 22:04:48 GMT</small></p></td>
<td align="left"><p><small>Last revised: November 25, 2012 at 20:52:29 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

0
doc/rtree/images/disjoint.png → doc/images/disjoint.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.2 KiB

After

Width:  |  Height:  |  Size: 2.2 KiB

0
doc/rtree/images/intersects.png → doc/images/intersects.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.2 KiB

After

Width:  |  Height:  |  Size: 2.2 KiB

0
doc/rtree/images/knn.png → doc/images/knn.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.7 KiB

After

Width:  |  Height:  |  Size: 2.7 KiB

0
doc/rtree/images/knn_cover.png → doc/images/knn_cover.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.0 KiB

After

Width:  |  Height:  |  Size: 3.0 KiB

0
doc/rtree/images/knn_inters.png → doc/images/knn_inters.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.0 KiB

After

Width:  |  Height:  |  Size: 3.0 KiB

0
doc/rtree/images/linear.png → doc/images/linear.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.1 KiB

After

Width:  |  Height:  |  Size: 2.1 KiB

0
doc/rtree/images/overlaps.png → doc/images/overlaps.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.2 KiB

After

Width:  |  Height:  |  Size: 2.2 KiB

0
doc/rtree/images/quadratic.png → doc/images/quadratic.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.0 KiB

After

Width:  |  Height:  |  Size: 2.0 KiB

0
doc/rtree/images/rstar.png → doc/images/rstar.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.0 KiB

After

Width:  |  Height:  |  Size: 2.0 KiB

0
doc/rtree/images/within.png → doc/images/within.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.2 KiB

After

Width:  |  Height:  |  Size: 2.2 KiB

44
doc/rtree/introduction.qbk
View File

@@ -10,9 +10,45 @@
[section Introduction]
__rtree__ is a self-balancing search tree. Each tree's node store a box descring the space occupied by children nodes.
At the bottom of the structure, there are leaf-nodes which contains values
(geometric objects representations). Minimal and maximal numbers of values/children
which may be stored inside each node are user defined.
__rtree__ is a tree data structure used for spatial searching. It was proposed by
Antonin Guttman in 1984 [footnote Guttman, A. (1984). /R-Trees: A Dynamic Index Structure for Spatial Searching/ footnote]
as an expansion of B-tree for multi-dimensional data. It may be used to store points or volumetric data in order to
perform a spatial query later. This query may return objects that are inside some area or are close to some point in space.
The __rtree__ structure is presented on the image below. Each __rtree__'s node store a box descring the space occupied by
its children nodes. At the bottom of the structure, there are leaf-nodes which contains values
(geometric objects representations).
[$../images/rstar.png]
The number of maximum and mininimum node's elements must be specified by the user. If the number of elements reaches it's maximum
the new node is created and elements are split between nodes. If the number of elements in node is too small, the node is deleted
and elements are reinserted into the tree.
The __rtree__ is a self-balanced data structure. The key part of balancing algorithm is node splitting algorithm mentioned before
[footnote Greene, D. (1989). /An implementation and performance analysis of spatial data access methods/ ]
[footnote Beckmann, N.; Kriegel, H. P.; Schneider, R.; Seeger, B. (1990). /The R*-tree: an efficient and robust access method for points and rectangles/ ].
Each algorithm would produce different splits so the internal structure of a tree may be different for each one of them.
In general more complex algorithms analyses elements better and produces less overlapping nodes. This is a "better" split because
later, in the searching process less nodes must be traversed in order to find desired obejcts. On the other hand more complex analysis
takes more time. In general faster inserting will result in slower searching and vice versa. Example structures of trees created by use
of three different algorithms and operations time are presented below.
[table
[[] [linear algorithm] [quadratic algorithm] [R*-tree]]
[[*Structure*][[$../images/linear.png]] [[$../images/quadratic.png]] [[$../images/rstar.png]]]
[[*1M Values inserts*] [1.85s] [3.10s] [24.52s]]
[[*1M spatial queries*][8.60s] [2.74s] [1.31s]]
[[*100k knn queries*] [3.49s] [1.59s] [0.84s]]
]
Key features of this implementation of the __rtree__ are:
* three different creation algorithms - linear, quadratic or rstar,
* parameters (including maximal and minimal number of elements) may be passed as compile- or run-time parameters - compile-time version is faster,
* capable to store arbitrary __value__ type,
* sophisticated queries - e.g. search for 5 nearest values intersecting some region but not within the other one.
[endsect]

26
doc/rtree/quickstart.qbk
View File

@@ -17,29 +17,41 @@ The code below assumes that following files are included and namespaces used.
[rtree_quickstart_include]
It is possible to store user-defined types in the R-tree. To keep it simple we will
use predefined __point__ and __box__.
Typically you'll store e.g. `std::pair<Box, MyGeometryId>` in the __rtree__. `MyGeometryId`
will be some indentifier of a complex `Geometry` stored in other container, e.g. index type
of a `Polygon` stored in the vector or an iterator of list of `Ring`s. To keep it simple to
define `Value` we will use predefined __box__ and unsigned int.
[rtree_quickstart_valuetype]
R-tree may be created using various algorithm and parameters. In this example we will
use quadratic algorithm. Maximum number of elements in nodes are set to 32, minimum to 8.
R-tree may be created using various algorithm and parameters. You should choose the algorithm you'll
find the best for your purpose. In this example we will use quadratic algorithm. Parameters are
passed as template parameters. Maximum number of elements in nodes are set to 32, minimum to 8.
[rtree_quickstart_create]
Inserting values into the R-tree may be done by calling insert() method.
Typically `Value`s will be generated in a loop from e.g. `Polygon`s stored in some other container.
In this case `Box` objects will probably be created with `geometry::make_envelope()` function.
But to keep it simple lets just generate some boxes manually and insert them into the R-tree by
using `insert()` method.
[rtree_quickstart_insert]
There are various types of spatial queries that may be performed, they can be even combined together
in one call. For simplicity, default one is used.
in one call. For simplicity, we use the default one. The following query return values intersecting
a box. The sequence of `Values` in the result is not specified.
[rtree_quickstart_spatial_query]
Default k-nearest neighbors query may be performed as follows.
Other type of query is k-nearest neighbor search. It returns some number of values nearest to some point
in space. The default knn query may be performed as follows. The sequence of `Values` in the result is not specified.
[rtree_quickstart_nearest_query]
At the end we'll print results.
[rtree_quickstart_output]
[h3 More]
More information about the R-tree implementation, other algorithms and queries may be found in
other parts of this documentation.

42
doc/src/examples/rtree/quick_start.cpp
View File

@@ -10,14 +10,19 @@
//[rtree_quickstart_include
#include <vector>
#include <boost/geometry.hpp>
#include <boost/geometry/geometries/point_xy.hpp>
#include <boost/geometry/geometries/box.hpp>
#include <boost/geometry/extensions/index/rtree/rtree.hpp>
// to store queries results
#include <vector>
// just for output
#include <iostream>
#include <boost/foreach.hpp>
namespace bg = boost::geometry;
namespace bgi = boost::geometry::index;
//]
@@ -31,26 +36,41 @@ int main(void)
//]
//[rtree_quickstart_create
// create the rtree using default constructor
bgi::rtree< value, bgi::quadratic<32, 8> > rtree;
//]
//[rtree_quickstart_insert
// create some box
// this typically will be an envelope of some geometry
box b(point(0, 0), point(10, 10));
// insert new value
rtree.insert(std::make_pair(b, 0));
// create some values
for ( unsigned i = 0 ; i < 10 ; ++i )
{
// create a box
box b(point(i, i), point(i + 0.5f, i + 0.5f));
// insert new value
rtree.insert(std::make_pair(b, i));
}
//]
//[rtree_quickstart_spatial_query
// find values intersecting a box
std::vector<value> result;
rtree.spatial_query(b, std::back_inserter(result));
// find values intersecting some area defined by a box
box query_box(point(0, 0), point(5, 5));
std::vector<value> result_s;
rtree.spatial_query(query_box, std::back_inserter(result_s));
//]
//[rtree_quickstart_nearest_query
// find 5 nearest values to a point
rtree.nearest_query(point(0, 0), 5, std::back_inserter(result));
std::vector<value> result_n;
rtree.nearest_query(point(0, 0), 5, std::back_inserter(result_n));
//]
//[rtree_quickstart_output
std::cout << "spatial query result:" << std::endl;
BOOST_FOREACH(value const& v, result_s)
std::cout << bg::wkt<box>(v.first) << " - " << v.second << std::endl;
std::cout << "knn query result:" << std::endl;
BOOST_FOREACH(value const& v, result_n)
std::cout << bg::wkt<box>(v.first) << " - " << v.second << std::endl;
//]
return 0;

2
tests/additional_speed.cpp
View File

@@ -21,7 +21,7 @@ int main()
namespace bgi = bg::index;
size_t values_count = 1000000;
size_t queries_count = 100000;
size_t queries_count = 1000000;
std::vector< std::pair<float, float> > coords;