From 7babc43f75c6257a79dd2acf4990e6f271f3d74d Mon Sep 17 00:00:00 2001
From: Adam Wulkiewicz <adam.wulkiewicz@gmail.com>
Date: Sun, 25 Nov 2012 20:56:38 +0000
Subject: [PATCH] Rtree docs and sample modified.

Rtree introduction expanded.
Quickstart improved.

[SVN r81539]
---
 doc/html/geometry_index/introduction.html     |   2 +-
 doc/html/geometry_index/r_tree.html           |   2 +-
 .../r_tree/creation_and_modification.html     |   6 +-
 .../r_tree/exception_safety.html              |  12 +-
 .../geometry_index/r_tree/introduction.html   | 191 +++++++++++++++++-
 .../r_tree/nearest_neighbours_queries.html    |   2 +-
 .../r_tree/rtree_quickstart.html              |  89 +++++---
 .../r_tree/spatial_queries.html               |   2 +-
 doc/html/index.html                           |   4 +-
 doc/{rtree => }/images/disjoint.png           | Bin
 doc/{rtree => }/images/intersects.png         | Bin
 doc/{rtree => }/images/knn.png                | Bin
 doc/{rtree => }/images/knn_cover.png          | Bin
 doc/{rtree => }/images/knn_inters.png         | Bin
 doc/{rtree => }/images/linear.png             | Bin
 doc/{rtree => }/images/overlaps.png           | Bin
 doc/{rtree => }/images/quadratic.png          | Bin
 doc/{rtree => }/images/rstar.png              | Bin
 doc/{rtree => }/images/within.png             | Bin
 doc/rtree/introduction.qbk                    |  44 +++-
 doc/rtree/quickstart.qbk                      |  26 ++-
 doc/src/examples/rtree/quick_start.cpp        |  42 +++-
 tests/additional_speed.cpp                    |   2 +-
 23 files changed, 356 insertions(+), 68 deletions(-)
 rename doc/{rtree => }/images/disjoint.png (100%)
 rename doc/{rtree => }/images/intersects.png (100%)
 rename doc/{rtree => }/images/knn.png (100%)
 rename doc/{rtree => }/images/knn_cover.png (100%)
 rename doc/{rtree => }/images/knn_inters.png (100%)
 rename doc/{rtree => }/images/linear.png (100%)
 rename doc/{rtree => }/images/overlaps.png (100%)
 rename doc/{rtree => }/images/quadratic.png (100%)
 rename doc/{rtree => }/images/rstar.png (100%)
 rename doc/{rtree => }/images/within.png (100%)

diff --git a/doc/html/geometry_index/introduction.html b/doc/html/geometry_index/introduction.html
index dd8b1efc4..aea9c9dc7 100644
--- a/doc/html/geometry_index/introduction.html
+++ b/doc/html/geometry_index/introduction.html
@@ -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">
diff --git a/doc/html/geometry_index/r_tree.html b/doc/html/geometry_index/r_tree.html
index f204ae1ba..610c173c3 100644
--- a/doc/html/geometry_index/r_tree.html
+++ b/doc/html/geometry_index/r_tree.html
@@ -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">
diff --git a/doc/html/geometry_index/r_tree/creation_and_modification.html b/doc/html/geometry_index/r_tree/creation_and_modification.html
index 003c41cdf..8725a9e0f 100644
--- a/doc/html/geometry_index/r_tree/creation_and_modification.html
+++ b/doc/html/geometry_index/r_tree/creation_and_modification.html
@@ -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>
diff --git a/doc/html/geometry_index/r_tree/exception_safety.html b/doc/html/geometry_index/r_tree/exception_safety.html
index 7307cace6..6b34a74f4 100644
--- a/doc/html/geometry_index/r_tree/exception_safety.html
+++ b/doc/html/geometry_index/r_tree/exception_safety.html
@@ -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
diff --git a/doc/html/geometry_index/r_tree/introduction.html b/doc/html/geometry_index/r_tree/introduction.html
index 68a64d201..d86263e93 100644
--- a/doc/html/geometry_index/r_tree/introduction.html
+++ b/doc/html/geometry_index/r_tree/introduction.html
@@ -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>
diff --git a/doc/html/geometry_index/r_tree/nearest_neighbours_queries.html b/doc/html/geometry_index/r_tree/nearest_neighbours_queries.html
index 304962a7f..6a2482203 100644
--- a/doc/html/geometry_index/r_tree/nearest_neighbours_queries.html
+++ b/doc/html/geometry_index/r_tree/nearest_neighbours_queries.html
@@ -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">
diff --git a/doc/html/geometry_index/r_tree/rtree_quickstart.html b/doc/html/geometry_index/r_tree/rtree_quickstart.html
index 039a6a09b..5e2471181 100644
--- a/doc/html/geometry_index/r_tree/rtree_quickstart.html
+++ b/doc/html/geometry_index/r_tree/rtree_quickstart.html
@@ -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
diff --git a/doc/html/geometry_index/r_tree/spatial_queries.html b/doc/html/geometry_index/r_tree/spatial_queries.html
index 2c7c62057..910bf2c5b 100644
--- a/doc/html/geometry_index/r_tree/spatial_queries.html
+++ b/doc/html/geometry_index/r_tree/spatial_queries.html
@@ -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">
diff --git a/doc/html/index.html b/doc/html/index.html
index 37c643eb6..d8aade2bd 100644
--- a/doc/html/index.html
+++ b/doc/html/index.html
@@ -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>
diff --git a/doc/rtree/images/disjoint.png b/doc/images/disjoint.png
similarity index 100%
rename from doc/rtree/images/disjoint.png
rename to doc/images/disjoint.png
diff --git a/doc/rtree/images/intersects.png b/doc/images/intersects.png
similarity index 100%
rename from doc/rtree/images/intersects.png
rename to doc/images/intersects.png
diff --git a/doc/rtree/images/knn.png b/doc/images/knn.png
similarity index 100%
rename from doc/rtree/images/knn.png
rename to doc/images/knn.png
diff --git a/doc/rtree/images/knn_cover.png b/doc/images/knn_cover.png
similarity index 100%
rename from doc/rtree/images/knn_cover.png
rename to doc/images/knn_cover.png
diff --git a/doc/rtree/images/knn_inters.png b/doc/images/knn_inters.png
similarity index 100%
rename from doc/rtree/images/knn_inters.png
rename to doc/images/knn_inters.png
diff --git a/doc/rtree/images/linear.png b/doc/images/linear.png
similarity index 100%
rename from doc/rtree/images/linear.png
rename to doc/images/linear.png
diff --git a/doc/rtree/images/overlaps.png b/doc/images/overlaps.png
similarity index 100%
rename from doc/rtree/images/overlaps.png
rename to doc/images/overlaps.png
diff --git a/doc/rtree/images/quadratic.png b/doc/images/quadratic.png
similarity index 100%
rename from doc/rtree/images/quadratic.png
rename to doc/images/quadratic.png
diff --git a/doc/rtree/images/rstar.png b/doc/images/rstar.png
similarity index 100%
rename from doc/rtree/images/rstar.png
rename to doc/images/rstar.png
diff --git a/doc/rtree/images/within.png b/doc/images/within.png
similarity index 100%
rename from doc/rtree/images/within.png
rename to doc/images/within.png
diff --git a/doc/rtree/introduction.qbk b/doc/rtree/introduction.qbk
index dc283360f..95e13a022 100644
--- a/doc/rtree/introduction.qbk
+++ b/doc/rtree/introduction.qbk
@@ -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]
+
+
diff --git a/doc/rtree/quickstart.qbk b/doc/rtree/quickstart.qbk
index 822aa43d7..0f28622b8 100644
--- a/doc/rtree/quickstart.qbk
+++ b/doc/rtree/quickstart.qbk
@@ -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.
diff --git a/doc/src/examples/rtree/quick_start.cpp b/doc/src/examples/rtree/quick_start.cpp
index 99f9fdd39..33eb2147f 100644
--- a/doc/src/examples/rtree/quick_start.cpp
+++ b/doc/src/examples/rtree/quick_start.cpp
@@ -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;
diff --git a/tests/additional_speed.cpp b/tests/additional_speed.cpp
index 5744e457b..71d669b90 100644
--- a/tests/additional_speed.cpp
+++ b/tests/additional_speed.cpp
@@ -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;