From 049446cbca26fc0f00eadc41d03029f318ebb092 Mon Sep 17 00:00:00 2001 From: Adam Wulkiewicz Date: Wed, 30 Nov 2011 03:22:14 +0000 Subject: [PATCH] changed docs format - from BoostBook to QuickBook [SVN r75740] --- doc/Jamfile.v2 | 29 +- doc/html/geometry_index/introduction.html | 53 +++ doc/html/geometry_index/r_tree.html | 502 ++++++++++++++++++++++ doc/html/index.html | 56 ++- doc/html/index/rtree.html | 472 -------------------- doc/index.qbk | 47 ++ doc/index.xml | 428 ------------------ doc/introduction.qbk | 22 + doc/rtree.qbk | 317 ++++++++++++++ 9 files changed, 985 insertions(+), 941 deletions(-) create mode 100644 doc/html/geometry_index/introduction.html create mode 100644 doc/html/geometry_index/r_tree.html delete mode 100644 doc/html/index/rtree.html create mode 100644 doc/index.qbk delete mode 100644 doc/index.xml create mode 100644 doc/introduction.qbk create mode 100644 doc/rtree.qbk diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 452d93760..2da6b592f 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -1,4 +1,4 @@ -# Boost.Geometry.Index (Spatial Indexes Library) +# Boost.Geometry Index (Spatial Indexes) # # Copyright (c) 2008 Federico J. Fernandez. # Copyright (c) 2011 Adam Wulkiewicz. @@ -7,14 +7,25 @@ # Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at # http://www.boost.org/LICENSE_1_0.txt) -project boost/doc ; -import boostbook : boostbook ; +project geometry_index/doc ; -boostbook geometry-index-doc - : - index.xml +import boostbook ; +import quickbook ; + +boostbook geometry_index-doc : - boost.root=http://www.boost.org/doc/libs/release - pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/doc/html + index.qbk + : +# off +# on +# off +# index.on.type=1 + html + pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/doc/html + chunk.first.sections=1 + toc.section.depth=3 + toc.max.depth=2 + generate.section.toc.level=4 + boost.root=http://www.boost.org/doc/libs/release + enable_index ; - diff --git a/doc/html/geometry_index/introduction.html b/doc/html/geometry_index/introduction.html new file mode 100644 index 000000000..51e8b0631 --- /dev/null +++ b/doc/html/geometry_index/introduction.html @@ -0,0 +1,53 @@ + + + +Introduction + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+

+ The Boost.Geometry Index is intetended to gather containers (spatial indexes) + used for speeding spatial queries up. It is a part of the Boost.Geometry + library. In general, spatial indexes stores geometric objects' representations + and allows searching for objects occupying some space or close to some point + in space. +

+

+ Currently, only one spatial index is implemented - R-tree. +

+
+ + + +
Copyright © 2011 Adam Wulkiewicz, Federico J. Fernandez

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/geometry_index/r_tree.html b/doc/html/geometry_index/r_tree.html new file mode 100644 index 000000000..655a08466 --- /dev/null +++ b/doc/html/geometry_index/r_tree.html @@ -0,0 +1,502 @@ + + + +R-tree + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHome +
+
+

+R-tree +

+
+
Introduction
+
R-tree creation
+
+
Quick + start
+
R-tree + template parameters
+
Values, + Indexables and default Translator
+
Inserting + and splitting algorithms
+
+
Inserting + and removing Values
+
Spatial queries
+
+
Basic + queries
+
Spatial + predicates
+
+
Nearest + neighbors queries
+
+
k + nearest neighbors
+
One + nearest neighbor
+
Distances + predicates
+
Using + spatial predicates
+
+
+
+
+

+ R-tree is a self-balancing search tree with nodes stored with their axis + aligned bounding boxes. Each node's box describes 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 the node are user defined. +

+

+ In order to use the R-tree one must include folowing file. +

+
#include <boost/geometry/extensions/index/rtree/rtree.hpp>
+
+
+
+
+
+
Quick + start
+
R-tree + template parameters
+
Values, + Indexables and default Translator
+
Inserting + and splitting algorithms
+
+
+
+

+ In order to create a R-tree object storing values of type std::pair<Box, size_t> one may use the following code: +

+
using namespace boost::geometry;
+typedef std::pair<Box, size_t> Value;
+index::rtree< Value, index::quadratic<32, 8> > rt;
+
+
+
+
+

+ R-tree has 4 parameters: +

+
rtree<Value, Parameters, Translator, Allocator>
+
+
    +
  • + Value - type of object + which will be stored in the container. +
    • +
  • + Parameters - compile-time + parameters, e.g. inserting/splitting algorithm with min and max nodes' + elements numbers. +
    • +
  • + Translator - type of + object translating Value + objects to Indexable + objects (Point + or Box) + which R-tree can handle. +
    • +
  • + Allocator - the allocator. +
    • +
+
+
+
+

+ R-tree may store Values of any type as long as there is passed + the Translator which knows how to interpret those Values + and extract an object understandable by the R-tree. Those objects are called + Indexables and they are simply of type adapted to Point + or Box + concept. Default Translator index::translator::def<Value> is able to handle Point, + Box, + std::pair<...>, + pointer, iterator or smart pointer. +

+
    +
  • + Indexable = Point + | Box +
    • +
  • + BasicValue = + Indexable | + std::pair<Indexable, T> | std::pair<T, Indexable> +
    • +
  • + Value = BasicValue + | BasicValue* | Iterator<BasicValue> + | SmartPtr<BasicValue> +
    • +
+

+ Examples of Value types: +

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

+ Values may be inserted to the R-tree in many various ways. + Final structure of nodes depends on algorithms used in the process, especially + nodes' splitting algorithm. Currently, three well-known types of R-trees + may be created. +

+

+ Linear - classic R-tree using splitting algorithm of linear complexity +

+
index::rtree< Value, index::linear<32, 8> > rt;
+
+

+ Quadratic - classic R-tree using splitting algorithm of quadratic complexity +

+
index::rtree< Value, index::quadratic<32, 8> > rt;
+
+

+ R*-tree - splitting algorithm minimizing nodes' overlap with forced reinsertions +

+
index::rtree< Value, index::rstar<32, 8> > rt;
+
+
+
+
+
+

+ Create +

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

+ Insert and remove by method call +

+
Value v = std::make_pair(Box(...), 0);
+rt.insert(v);
+rt.remove(v);
+
+

+ or by function call +

+
Value v = std::make_pair(Box(...), 0);
+index::insert(rt, v);
+index::remove(rt, v);
+
+
+
+
+
+
Basic + queries
+
Spatial + predicates
+
+
+
+

+ There are three ways to perform a spatial query. Following queries returns + Values intersecting some box_region. +

+

+ Method call +

+
std::vector<Value> returned_values;
+Box box_region(...);
+rt.query(box_region, std::back_inserter(returned_values));
+
+

+ Function call +

+
std::vector<Value> returned_values;
+Box box_region(...);
+index::query(rt, box_region, std::back_inserter(returned_values));
+
+

+ Use of operator | + (as with ranges) +

+
Box box_region(...);
+BOOST_FOREACH(Value & v, rt | index::query_filtered(box_region))
+  ; // do something with v
+
+
+
+
+

+ It is possible to define other relations between queried Values + and region/regions of interest. Names of predicates corresponds to names + of Boost.Geometry + algorithms. +

+
rt.query(box, std::back_inserter(result)); // default case - intersects
+rt.query(index::intersects(box), std::back_inserter(result)); // same as default
+rt.query(index::covered_by(box), std::back_inserter(result));
+rt.query(index::disjont(box), std::back_inserter(result));
+rt.query(index::overlaps(box), std::back_inserter(result));
+rt.query(index::within(box), std::back_inserter(result));
+
+

+ All predicates may be negated, e.g.: +

+
rt.query(index::not_intersects(box), std::back_inserter(result));
+// or
+rt.query(!index::intersects(box), std::back_inserter(result));
+// the same as
+rt.query(index::disjoint(box), std::back_inserter(result));
+
+

+ It's possible to use some number of predicates by passing std::pair<Pred1, Pred2> +

+
rt.query(
+  std::make_pair(index::intersects(box1), !index::within(box2))
+  , std::back_inserter(result));
+
+

+ or boost::tuple<Pred1, Pred2, Pred3, ...> +

+
rt.query(
+  boost::make_tuple(
+    index::intersects(box1), !index::within(box2), index::overlaps(box3))
+  , std::back_inserter(result));
+
+

+ There is also a unique predicate index::value(...) taking user-defined function/functor + which checks if Value should be returned by the query. +

+
bool fun(__value const& v)
+{
+  return v.is_red();
+}
+
+// ...
+
+rt.query(
+  boost::make_pair(index::intersects(box), index::value(fun))
+  , std::back_inserter(result));
+
+
+
+
+
+
+
k + nearest neighbors
+
One + nearest neighbor
+
Distances + predicates
+
Using + spatial predicates
+
+
+
+

+ There are three ways of performing knn queries. Following queries returns + k Values closest to some point in space. For Boxes + Indexables closest point of a Box + is taken into account by default. +

+

+ Method call +

+
std::vector<Value> returned_values;
+Point pt(...);
+rt.nearest(pt, k, std::back_inserter(returned_values));
+
+

+ Function call +

+
std::vector<Value> returned_values;
+Point pt(...);
+index::nearest(rt, pt, k, std::back_inserter(returned_values));
+
+

+ Use of operator | +

+
Point pt(...);
+BOOST_FOREACH(Value & v, rt | index::nearest_filtered(pt, k))
+  ; // do something with v
+
+
+
+
+

+ Another type of nearest neighbor query is searching for the one closest + Value. If it is found, 1 is returned by the method or function. + This kind of query has only two forms. +

+

+ Method call +

+
Value returned_value;
+Point pt(...);
+size_t n = rt.nearest(pt, returned_value);
+
+

+ Function call +

+
Value Value returned_value;
+Point pt(...);
+size_t n = index::nearest(rt, pt, returned_value);
+
+
+
+
+

+ It is possible to define if calculated distance between query point and + Value should be greater, lesser or between some other distances. + Those are called DistancesPredicates + and may be defined as follows. +

+
std::vector<__Value__> returned_values;
+Point pt(...);
+
+/* default - without bounds */
+index::nearest(rt, pt, k, std::back_inserter(returned_values));
+
+/* same as default */
+index::nearest(rt, index::unbounded(pt), k, std::back_inserter(returned_values));
+
+/* distance must be greater than or equal to 10 */
+index::nearest(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values));
+
+/* distance must be lesser than or equal to 500 */
+index::nearest(rt, index::max_bounded(pt, 500), k, std::back_inserter(returned_values));
+
+/* distance must be between 10 and 500 */
+index::nearest(rt, index::bounded(pt, 10, 500), k, std::back_inserter(returned_values));
+
+

+ Furthermore, it's possible to define if the closest, furthest or centroidal + point of the non-point __Indexable__ + should be taken into account in the routine calculating distance. +

+
std::vector<Value> returned_values;
+Point pt(...);
+
+/* default - distance between __indexable__'s closest point and a query point
+must be greater than 10 */
+index::nearest(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values));
+
+/* same as default - distance between __indexable__'s closest point and a query point
+must be greater than 10 */
+index::nearest(rt, index::min_bounded(pt, index::near(10)), k, std::back_inserter(returned_values));
+
+/* distance between __indexable__'s furthest point and a query point
+must be greater than 10 */
+index::nearest(rt, index::min_bounded(pt, index::far(10)), k, std::back_inserter(returned_values));
+
+/* distance between __indexable__'s centroid and a query point
+must be greater than 10 */
+index::nearest(rt, index::min_bounded(pt, index::centroid(10)), k, std::back_inserter(returned_values));
+
+
+
+
+

+ It is possible to use spatial predicates described before in nearest neighbors + queries. +

+
Value returned_value;
+std::vector<Value> returned_values;
+
+Point pt(...);
+Box b(...);
+
+size_t n1 = rt.nearest(index::bounded(pt, index::far(1), 10), index::intersects(b), returned_value);
+
+size_t n2 = index::nearest(rt, pt, k, index::within(b), std::back_inserter(returned_values));
+
+BOOST_FOREACH(Value & v, rt | index::nearest_filtered(pt, k, index::covered_by(b)))
+  ; // do something with v
+
+
+
+
+ + + +
Copyright © 2011 Adam Wulkiewicz, Federico J. Fernandez

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

+
+
+
+PrevUpHome +
+ + diff --git a/doc/html/index.html b/doc/html/index.html index 3e4d34b68..e4aca4690 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -1,11 +1,11 @@ -Chapter 1. Boost.Geometry.Index +Chapter 1. Geometry Index 0.7 - - + + @@ -17,55 +17,47 @@
More
-
Next
+
Next

-Chapter 1. Boost.Geometry.Index

-

-Federico J. Fernandez -

+Chapter 1. Geometry Index 0.7

Adam Wulkiewicz

-

Copyright © 2008 Federico J. Fernandez

-

Copyright © 2011 Adam Wulkiewicz

+

+Federico J. Fernandez +

+

Copyright © 2011 Adam Wulkiewicz, Federico J. Fernandez

-

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

+

+ Distributed under the Boost Software License, Version 1.0. (See accompanying + file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +

Table of Contents

-
Introduction
-
R-tree
+
Introduction
+
R-tree
-
Introduction
-
R-tree creation
-
Inserting and removing Values
-
Spatial queries
-
Nearest neighbors queries
+
Introduction
+
R-tree creation
+
Inserting + and removing Values
+
Spatial queries
+
Nearest + neighbors queries
-
-

-Introduction

-

The Boost.Geometry.Index library is intetended to gather containers -(spatial indexes) used for speeding spatial queries up. In general, indexes -stores geometric objects' representations and allows searching for objects -occupying some space or close to some point in space. -

-

Currently, only one spatial index is implemented - the R-tree.

-
- +

Last revised: November 30, 2011 at 03:13:32 GMT
-
Next
+
Next
diff --git a/doc/html/index/rtree.html b/doc/html/index/rtree.html deleted file mode 100644 index efa6bc1a8..000000000 --- a/doc/html/index/rtree.html +++ /dev/null @@ -1,472 +0,0 @@ - - - -R-tree - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHome -
-
-

-R-tree

-
-
Introduction
-
R-tree creation
-
Inserting and removing Values
-
Spatial queries
-
Nearest neighbors queries
-
-
-

-Introduction

-

-R-tree is a self-balancing search tree with nodes stored with their axis aligned -bounding boxes. Each node's box describes 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 the node are user defined. -

-

-In order to use the R-tree one must include folowing file. -

-
-#include <boost/geometry/extensions/index/rtree/rtree.hpp>
-
-

-

-
-
-

-R-tree creation

-
-
Quick start
-
R-tree template parameters
-
Values, Indexables and default Translator
-
Inserting and splitting algorithms
-
-
-

-Quick start

-

-In order to create a R-tree object storing values of type -std::pair<Box, int> one may use the following code -

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

-

-
-
-

-R-tree template parameters

-

-R-tree has 4 parameters: -

-
-rtree<Value, Parameters, Translator, Allocator>
-
-

-

-
    -
  • -Value - type of object which will be stored in the container. -
    • -
  • -Parameters - compile-time parameters, e.g. inserting/splitting -algorithm with min and max nodes' elements numbers. -
    • -
  • -Translator - type of object translating Value objects -to Indexable objects (Point or Box) which -R-tree can handle. -
    • -
  • -Allocator - the allocator. -
    • -
-

-

-
-
-

-Values, Indexables and default Translator

-

-R-tree may store Values of any type as long as there is passed -the Translator which knows how to interpret those Values -and extract an object understandable by the R-tree. Those objects are called -Indexables and they are simply of type adapted to Point -or Box concept. Default translator index::translator::def<Value> -is able to handle Point, Box, std::pair<...>, -pointer, iterator or smart pointer. -

-
    -
  • Indexable = Point | Box
    • -
  • BasicValue = Indexable | std::pair<Indexable, T> | std::pair<T, Indexable>
    • -
  • Value = BasicValue | BasicValue* | Iterator<BasicValue> | SmartPtr<BasicValue>
    • -
-

-Examples of Value types: -

-
    -
  • geometry::model::point<...>
    • -
  • geometry::model::point_xy<...>
    • -
  • geometry::model::box<...>
    • -
  • std::pair<geometry::model::box<...>, size_t>
    • -
-

-

-
-
-

-Inserting and splitting algorithms

-

-Values may be inserted to the R-tree in many various ways. Final structure of nodes depends -on algorithms used in the process, especially nodes' splitting algorithm. Currently, three -well-known types of R-trees may be created. -

-
    -
  • -Linear - classic R-tree using splitting algorithm of linear complexity -
    -index::rtree< Value, index::linear<32, 8> > rt;
-
    -
    • -
  • -Quadratic - classic R-tree using splitting algorithm of quadratic complexity -
    -index::rtree< Value, index::quadratic<32, 8> > rt;
-
    -
    • -
  • -R*-tree - splitting algorithm minimizing nodes' overlap with forced reinsertions -
    -index::rtree< Value, index::rstar<32, 8> > rt;
-
    -
    • -
-

-

-
-
-
-

-Inserting and removing Values

-

-Create -

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

-Insert and remove by method call -

-
-Value v = std::make_pair(Box(...), 0);
-rt.insert(v);
-rt.remove(v);
-
-

-or by function call -

-
-Value v = std::make_pair(Box(...), 0);
-index::insert(rt, v);
-index::remove(rt, v);
-
-

-

-
-
-

-Spatial queries

-
-
Basic queries
-
Spatial predicates
-
-
-

-Basic queries

-

-There are three ways to perform a spatial query. Following queries returns -Values intersecting some box_region. -

-
    -
  • -Method call -
    -std::vector<Value> returned_values;
-Box box_region(...);
-rt.query(box_region, std::back_inserter(returned_values));
-
    -
    • -
  • -Function call -
    -std::vector<Value> returned_values;
-Box box_region(...);
-index::query(rt, box_region, std::back_inserter(returned_values));
-
    -
    • -
  • -Use of operator | (as with ranges) -
    -Box box_region(...);
-BOOST_FOREACH(Value &v, rt | index::query_filtered(box_region))
-  ;// do something with v
-
    -
    • -
-

-

-
-
-

-Spatial predicates

-

-It is possible to define other relations between queried Values and region/regions -of interest. Names of predicates corresponds to names of Boost.Geometry algorithms. -

-
-rt.query(box, std::back_inserter(result)); // default case - intersects
-rt.query(index::intersects(box), std::back_inserter(result)); // same as default
-rt.query(index::covered_by(box), std::back_inserter(result));
-rt.query(index::disjont(box), std::back_inserter(result));
-rt.query(index::overlaps(box), std::back_inserter(result));
-rt.query(index::within(box), std::back_inserter(result));
-
-

-All predicates may be negated, e.g.: -

-
-rt.query(index::not_intersects(box), std::back_inserter(result));
-// or
-rt.query(!index::intersects(box), std::back_inserter(result));
-// the same as
-rt.query(index::disjoint(box), std::back_inserter(result));
-
-

-It's possible to use some number of predicates by passing std::pair<Pred1, Pred2> -

-
-rt.query(
-  std::make_pair(index::intersects(box1), !index::within(box2))
-  , std::back_inserter(result));
-
-

-or boost::tuple<Pred1, Pred2, Pred3, ...> -

-
-rt.query(
-  boost::make_tuple(index::intersects(box1), !index::within(box2), index::overlaps(box3))
-  , std::back_inserter(result));
-
-

-There is special predicate index::value(Fun) taking user-defined function/functor -which checks if Value should be returned by the query. -

-
-bool fun(Value const& v)
-{
-  return v.is_red();
-}
-
-// ...
-
-rt.query(
-  boost::make_pair(index::intersects(box), index::value(fun))
-  , std::back_inserter(result));
-
-

-

-
-
-
-

-Nearest neighbors queries

-
-
k nearest neighbors
-
One nearest neighbor
-
Distances predicates
-
Using spatial predicates
-
-
-

-k nearest neighbors

-

-There are three ways of performing knn queries. Following queries returns -k Values closest to some point in space. For Boxes -Indexables closest point of a Box is taken into -account by default. -

-
    -
  • -Method call -
    -std::vector<Value> returned_values;
-Point pt(...);
-rt.nearest(pt, k, std::back_inserter(returned_values));
-
    -
    • -
  • -Function call -
    -std::vector<Value> returned_values;
-Point pt(...);
-index::nearest(rt, pt, k, std::back_inserter(returned_values));
-
    -
    • -
  • -Use of operator |
    -Point pt(...);
-BOOST_FOREACH(Value &v, rt | index::nearest_filtered(pt, k))
-  ;// do something with v
-
    -
    • -
-

-

-
-
-

-One nearest neighbor

-

-Another type of nearest neighbor query is searching for the one closest Value. -If it is found, 1 is returned by the method or function. This kind of query -has only two forms. -

-
    -
  • -Method call -
    -Value returned_value;
-Point pt(...);
-size_t n = rt.nearest(pt, returned_value);
-
    -
    • -
  • -Function call -
    -Value returned_value;
-Point pt(...);
-size_t n = index::nearest(rt, pt, returned_value);
-
    -
    • -
-

-

-
-
-

-Distances predicates

-

-It is possible to define if calculated distance between query point and Value should be -greater, lesser or between some other distances. Those are called DistancesPredicates and -may be defined as follows. -

-
-std::vector<Value> returned_values;
-Point pt(...);
-
-/* default - without bounds */
-index::nearest(rt, pt, k, std::back_inserter(returned_values));
-
-/* same as default */
-index::nearest(rt, index::unbounded(pt), k, std::back_inserter(returned_values));
-
-/* distance must be greater than or equal to 10 */
-index::nearest(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values));
-
-/* distance must be lesser than or equal to 500 */
-index::nearest(rt, index::max_bounded(pt, 500), k, std::back_inserter(returned_values));
-
-/* distance must be between 10 and 500 */
-index::nearest(rt, index::bounded(pt, 10, 500), k, std::back_inserter(returned_values));
-
-
-

-

-

-Furthermore, it's possible to define if the closest, furthest or centroidal point of the -non-point Indexable should be taken into account in the routine calculating distance. -

-
-std::vector<Value> returned_values;
-Point pt(...);
-
-/* default - distance between Indexable's closest point and a query point
-must be greater than 10 */
-index::nearest(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values));
-
-/* same as default - distance between Indexable's closest point and a query point
-must be greater than 10 */
-index::nearest(rt, index::min_bounded(pt, index::near(10)), k, std::back_inserter(returned_values));
-
-/* distance between Indexable's furthest point and a query point
-must be greater than 10 */
-index::nearest(rt, index::min_bounded(pt, index::far(10)), k, std::back_inserter(returned_values));
-
-/* distance between Indexable's centroid and a query point
-must be greater than 10 */
-index::nearest(rt, index::min_bounded(pt, index::centroid(10)), k, std::back_inserter(returned_values));
-
-

-

-
-
-

-Using spatial predicates

-

-It is possible to use spatial predicates described before in nearest neighbors queries. -

-
-Value returned_value;
-std::vector<Value> returned_values;
-
-Point pt(...);
-Box b(...);
-
-size_t n1 = rt.nearest(index::bounded(pt, index::far(1), 10), index::intersects(b), returned_value);
-
-size_t n2 = index::nearest(rt, pt, k, index::within(b), std::back_inserter(returned_values));
-
-BOOST_FOREACH(Value &v, rt | index::nearest_filtered(pt, k, index::covered_by(b)))
-  ;// do something with v
-
-

-

-
-
-
- - - -
Copyright © 2008 Federico J. Fernandez
Copyright © 2011 Adam Wulkiewicz

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

-
-
-
-PrevUpHome -
- - diff --git a/doc/index.qbk b/doc/index.qbk new file mode 100644 index 000000000..feb00e062 --- /dev/null +++ b/doc/index.qbk @@ -0,0 +1,47 @@ +[/============================================================================ + Boost.Geometry Index (Spatial Indexes) + + Copyright (c) 2008 Federico J. Fernandez. + Copyright (c) 2011 Adam Wulkiewicz. + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + +[library Geometry Index + [quickbook 1.5] + [version 0.7] + [authors [Wulkiewicz, Adam], [Fernandez, Federico J.]] + [copyright 2011 Adam Wulkiewicz, Federico J. Fernandez] + [purpose Documentation of Boost.Geometry Index library] + [license + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt]) + ] + [id geometry] + [category geometry] +] + +[def __box__ [@http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_box.html Box]] +[def __point__ [@http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_point.html Point]] + +[def __boost__ [@http://www.boost.org/libs/libraries.htm Boost]] +[def __boost_geometry__ [@http://www.boost.org/libs/geometry/doc/html/index.html Boost.Geometry]] +[def __boost_geometry_index__ Boost.Geometry Index] + +[def __rtree__ R-tree] + +[def __value__ Value] +[def __parameters__ Parameters] +[def __translator__ Translator] +[def __allocator__ Allocator] +[def __indexable__ Indexable] + +[def __cgeometry__ [@http://www.boost.org/libs/geometry/doc/html/index.html geometry]] +[def __cboost__ [@http://www.boost.org/libs/libraries.htm boost]] + +[include introduction.qbk] + +[include rtree.qbk] diff --git a/doc/index.xml b/doc/index.xml deleted file mode 100644 index f41b06921..000000000 --- a/doc/index.xml +++ /dev/null @@ -1,428 +0,0 @@ - - - - - - Federico J. - Fernandez - - - Adam - Wulkiewicz - - - - 2008 - Federico J. Fernandez - - - 2011 - Adam Wulkiewicz - - - - Use, modification and distribution is subject to the Boost - Software License, Version 1.0. (See accompanying file - LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - - - Spatial indexes for faster spatial and knn queries. - - - -Boost.Geometry.Index - -
-Introduction -The Boost.Geometry.Index library is intetended to gather containers -(spatial indexes) used for speeding spatial queries up. In general, indexes -stores geometric objects' representations and allows searching for objects -occupying some space or close to some point in space. - - -Currently, only one spatial index is implemented - the R-tree. -
- -
-R-tree - -
-Introduction - -R-tree is a self-balancing search tree with nodes stored with their axis aligned -bounding boxes. Each node's box describes 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 the node are user defined. - - - -In order to use the R-tree one must include folowing file. - -#include <boost/geometry/extensions/index/rtree/rtree.hpp> - - -
- -
-R-tree creation - -
-Quick start - -In order to create a R-tree object storing values of type -std::pair<Box, int> one may use the following code - -using namespace boost::geometry; -typedef std::pair<Box, int> Value; -index::rtree< Value, index::quadratic<32, 8> > rt; - - -
- -
-R-tree template parameters - -R-tree has 4 parameters: - -rtree<Value, Parameters, Translator, Allocator> - - - -Value - type of object which will be stored in the container. - - -Parameters - compile-time parameters, e.g. inserting/splitting -algorithm with min and max nodes' elements numbers. - - -Translator - type of object translating Value objects -to Indexable objects (Point or Box) which -R-tree can handle. - - -Allocator - the allocator. - - - -
- -
-Values, Indexables and default Translator - -R-tree may store Values of any type as long as there is passed -the Translator which knows how to interpret those Values -and extract an object understandable by the R-tree. Those objects are called -Indexables and they are simply of type adapted to Point -or Box concept. Default translator index::translator::def<Value> -is able to handle Point, Box, std::pair<...>, -pointer, iterator or smart pointer. - -Indexable = Point | Box -BasicValue = Indexable | std::pair<Indexable, T> | std::pair<T, Indexable> -Value = BasicValue | BasicValue* | Iterator<BasicValue> | SmartPtr<BasicValue> - -Examples of Value types: - -geometry::model::point<...> -geometry::model::point_xy<...> -geometry::model::box<...> -std::pair<geometry::model::box<...>, size_t> - - -
- -
-Inserting and splitting algorithms - -Values may be inserted to the R-tree in many various ways. Final structure of nodes depends -on algorithms used in the process, especially nodes' splitting algorithm. Currently, three -well-known types of R-trees may be created. - - -Linear - classic R-tree using splitting algorithm of linear complexity - -index::rtree< Value, index::linear<32, 8> > rt; - - - -Quadratic - classic R-tree using splitting algorithm of quadratic complexity - -index::rtree< Value, index::quadratic<32, 8> > rt; - - - -R*-tree - splitting algorithm minimizing nodes' overlap with forced reinsertions - -index::rtree< Value, index::rstar<32, 8> > rt; - - - - -
- -
- -
-Inserting and removing Values - -Create - -using namespace boost::geometry; -typedef std::pair<Box, int> Value; -index::rtree< Value, index::quadratic<32, 8> > rt; - -Insert and remove by method call - -Value v = std::make_pair(Box(...), 0); -rt.insert(v); -rt.remove(v); - -or by function call - -Value v = std::make_pair(Box(...), 0); -index::insert(rt, v); -index::remove(rt, v); - - -
- -
-Spatial queries - -
-Basic queries - -There are three ways to perform a spatial query. Following queries returns -Values intersecting some box_region. - - -Method call - -std::vector<Value> returned_values; -Box box_region(...); -rt.query(box_region, std::back_inserter(returned_values)); - - - -Function call - -std::vector<Value> returned_values; -Box box_region(...); -index::query(rt, box_region, std::back_inserter(returned_values)); - - - -Use of operator | (as with ranges) - -Box box_region(...); -BOOST_FOREACH(Value &v, rt | index::query_filtered(box_region)) - ;// do something with v - - - - -
- -
-Spatial predicates - -It is possible to define other relations between queried Values and region/regions -of interest. Names of predicates corresponds to names of Boost.Geometry algorithms. - -rt.query(box, std::back_inserter(result)); // default case - intersects -rt.query(index::intersects(box), std::back_inserter(result)); // same as default -rt.query(index::covered_by(box), std::back_inserter(result)); -rt.query(index::disjont(box), std::back_inserter(result)); -rt.query(index::overlaps(box), std::back_inserter(result)); -rt.query(index::within(box), std::back_inserter(result)); - -All predicates may be negated, e.g.: - -rt.query(index::not_intersects(box), std::back_inserter(result)); -// or -rt.query(!index::intersects(box), std::back_inserter(result)); -// the same as -rt.query(index::disjoint(box), std::back_inserter(result)); - -It's possible to use some number of predicates by passing std::pair<Pred1, Pred2> - -rt.query( - std::make_pair(index::intersects(box1), !index::within(box2)) - , std::back_inserter(result)); - -or boost::tuple<Pred1, Pred2, Pred3, ...> - -rt.query( - boost::make_tuple(index::intersects(box1), !index::within(box2), index::overlaps(box3)) - , std::back_inserter(result)); - -There is special predicate index::value(Fun) taking user-defined function/functor -which checks if Value should be returned by the query. - -bool fun(Value const& v) -{ - return v.is_red(); -} - -// ... - -rt.query( - boost::make_pair(index::intersects(box), index::value(fun)) - , std::back_inserter(result)); - - -
- -
- -
-Nearest neighbors queries - -
-k nearest neighbors - -There are three ways of performing knn queries. Following queries returns -k Values closest to some point in space. For Boxes -Indexables closest point of a Box is taken into -account by default. - - -Method call - -std::vector<Value> returned_values; -Point pt(...); -rt.nearest(pt, k, std::back_inserter(returned_values)); - - - -Function call - -std::vector<Value> returned_values; -Point pt(...); -index::nearest(rt, pt, k, std::back_inserter(returned_values)); - - - -Use of operator | - -Point pt(...); -BOOST_FOREACH(Value &v, rt | index::nearest_filtered(pt, k)) - ;// do something with v - - - - -
- -
-One nearest neighbor - -Another type of nearest neighbor query is searching for the one closest Value. -If it is found, 1 is returned by the method or function. This kind of query -has only two forms. - - -Method call - -Value returned_value; -Point pt(...); -size_t n = rt.nearest(pt, returned_value); - - - -Function call - -Value returned_value; -Point pt(...); -size_t n = index::nearest(rt, pt, returned_value); - - - - -
- -
-Distances predicates - -It is possible to define if calculated distance between query point and Value should be -greater, lesser or between some other distances. Those are called DistancesPredicates and -may be defined as follows. - -std::vector<Value> returned_values; -Point pt(...); - -/* default - without bounds */ -index::nearest(rt, pt, k, std::back_inserter(returned_values)); - -/* same as default */ -index::nearest(rt, index::unbounded(pt), k, std::back_inserter(returned_values)); - -/* distance must be greater than or equal to 10 */ -index::nearest(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values)); - -/* distance must be lesser than or equal to 500 */ -index::nearest(rt, index::max_bounded(pt, 500), k, std::back_inserter(returned_values)); - -/* distance must be between 10 and 500 */ -index::nearest(rt, index::bounded(pt, 10, 500), k, std::back_inserter(returned_values)); - - - - - -Furthermore, it's possible to define if the closest, furthest or centroidal point of the -non-point Indexable should be taken into account in the routine calculating distance. - -std::vector<Value> returned_values; -Point pt(...); - -/* default - distance between Indexable's closest point and a query point -must be greater than 10 */ -index::nearest(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values)); - -/* same as default - distance between Indexable's closest point and a query point -must be greater than 10 */ -index::nearest(rt, index::min_bounded(pt, index::near(10)), k, std::back_inserter(returned_values)); - -/* distance between Indexable's furthest point and a query point -must be greater than 10 */ -index::nearest(rt, index::min_bounded(pt, index::far(10)), k, std::back_inserter(returned_values)); - -/* distance between Indexable's centroid and a query point -must be greater than 10 */ -index::nearest(rt, index::min_bounded(pt, index::centroid(10)), k, std::back_inserter(returned_values)); - - - -
- -
-Using spatial predicates - -It is possible to use spatial predicates described before in nearest neighbors queries. - -Value returned_value; -std::vector<Value> returned_values; - -Point pt(...); -Box b(...); - -size_t n1 = rt.nearest(index::bounded(pt, index::far(1), 10), index::intersects(b), returned_value); - -size_t n2 = index::nearest(rt, pt, k, index::within(b), std::back_inserter(returned_values)); - -BOOST_FOREACH(Value &v, rt | index::nearest_filtered(pt, k, index::covered_by(b))) - ;// do something with v - - -
- -
- -
- - diff --git a/doc/introduction.qbk b/doc/introduction.qbk new file mode 100644 index 000000000..cbb53fad2 --- /dev/null +++ b/doc/introduction.qbk @@ -0,0 +1,22 @@ +[/============================================================================ + Boost.Geometry Index (Spatial Indexes) + + Copyright (c) 2008 Federico J. Fernandez. + Copyright (c) 2011 Adam Wulkiewicz. + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + +[section Introduction] + +The __boost_geometry_index__ is intetended to gather containers +(spatial indexes) used for speeding spatial queries up. It is a part of the +__boost_geometry__ library. +In general, spatial indexes stores geometric objects' representations and +allows searching for objects occupying some space or close to some point in space. + +Currently, only one spatial index is implemented - __rtree__. + +[endsect] diff --git a/doc/rtree.qbk b/doc/rtree.qbk new file mode 100644 index 000000000..e449d7e34 --- /dev/null +++ b/doc/rtree.qbk @@ -0,0 +1,317 @@ +[/============================================================================ + Boost.Geometry Index (Spatial Indexes) + + Copyright (c) 2008 Federico J. Fernandez. + Copyright (c) 2011 Adam Wulkiewicz. + + Use, modification and distribution is subject to the Boost Software License, + Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) +=============================================================================/] + +[section R-tree] + +[section Introduction] + +__rtree__ is a self-balancing search tree with nodes stored with their axis aligned +bounding boxes. Each node's box describes 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 the node are user defined. + +In order to use the __rtree__ one must include folowing file. + + #include + +[endsect] + +[section R-tree creation] + +[section Quick start] + +In order to create a __rtree__ object storing values of type `std::pair<__box__, size_t>` +one may use the following code: + + using namespace __cboost__::__cgeometry__; + typedef std::pair<__box__, size_t> Value; + index::rtree< Value, index::quadratic<32, 8> > rt; + +[endsect] + +[section R-tree template parameters] + +__rtree__ has 4 parameters: + + rtree + +* `Value` - type of object which will be stored in the container. +* `Parameters` - compile-time parameters, e.g. inserting/splitting + algorithm with min and max nodes' elements numbers. +* `Translator` - type of object translating `Value` objects to + `Indexable` objects (`__point__` or `__box__`) which __rtree__ can handle. +* `Allocator` - the allocator. + +[endsect] + +[section Values, Indexables and default Translator] + +__rtree__ may store `__value__`s of any type as long as there is passed +the `__translator__` which knows how to interpret those `__value__`s +and extract an object understandable by the __rtree__. Those objects are called +`__indexable__`s and they are simply of type adapted to `__point__` +or `__box__` concept. Default `__translator__` `index::translator::def` +is able to handle `__point__`, `__box__`, `std::pair<...>`, pointer, iterator +or smart pointer. + +* `__indexable__ = __point__ | __box__` +* `BasicValue = Indexable | std::pair<__indexable__, T> | std::pair` +* `__value__ = BasicValue | BasicValue* | Iterator | SmartPtr` + +Examples of `__value__` types: + + geometry::model::point<...> + geometry::model::point_xy<...> + geometry::model::box<...> + std::pair, size_t> + +[endsect] + +[section Inserting and splitting algorithms] + +`__value__`s may be inserted to the __rtree__ in many various ways. Final structure of nodes depends +on algorithms used in the process, especially nodes' splitting algorithm. Currently, three +well-known types of R-trees may be created. + +Linear - classic __rtree__ using splitting algorithm of linear complexity + + index::rtree< __value__, index::linear<32, 8> > rt; + +Quadratic - classic __rtree__ using splitting algorithm of quadratic complexity + + index::rtree< __value__, index::quadratic<32, 8> > rt; + +R*-tree - splitting algorithm minimizing nodes' overlap with forced reinsertions + + index::rtree< __value__, index::rstar<32, 8> > rt; + +[endsect] + +[endsect] [/ R-tree creation /] + +[section Inserting and removing Values] + +Create + + using namespace boost::geometry; + typedef std::pair __value__; + index::rtree< __value__, index::quadratic<32, 8> > rt; + +Insert and remove by method call + + __value__ v = std::make_pair(__box__(...), 0); + rt.insert(v); + rt.remove(v); + +or by function call + + __value__ v = std::make_pair(__box__(...), 0); + index::insert(rt, v); + index::remove(rt, v); + +[endsect] + +[section Spatial queries] + +[section Basic queries] + +There are three ways to perform a spatial query. Following queries returns +`__value__`s intersecting some box_region. + +Method call + + std::vector<__value__> returned_values; + __box__ box_region(...); + rt.query(box_region, std::back_inserter(returned_values)); + +Function call + + std::vector<__value__> returned_values; + __box__ box_region(...); + index::query(rt, box_region, std::back_inserter(returned_values)); + +Use of `operator |` (as with ranges) + + __box__ box_region(...); + BOOST_FOREACH(__value__ & v, rt | index::query_filtered(box_region)) + ; // do something with v +[endsect] + +[section Spatial predicates] + +It is possible to define other relations between queried `__value__`s and region/regions +of interest. Names of predicates corresponds to names of __boost_geometry__ algorithms. + + rt.query(box, std::back_inserter(result)); // default case - intersects + rt.query(index::intersects(box), std::back_inserter(result)); // same as default + rt.query(index::covered_by(box), std::back_inserter(result)); + rt.query(index::disjont(box), std::back_inserter(result)); + rt.query(index::overlaps(box), std::back_inserter(result)); + rt.query(index::within(box), std::back_inserter(result)); + +All predicates may be negated, e.g.: + + rt.query(index::not_intersects(box), std::back_inserter(result)); + // or + rt.query(!index::intersects(box), std::back_inserter(result)); + // the same as + rt.query(index::disjoint(box), std::back_inserter(result)); + +It's possible to use some number of predicates by passing `std::pair` + + rt.query( + std::make_pair(index::intersects(box1), !index::within(box2)) + , std::back_inserter(result)); + +or `boost::tuple` + + rt.query( + boost::make_tuple( + index::intersects(box1), !index::within(box2), index::overlaps(box3)) + , std::back_inserter(result)); + +There is also a unique predicate `index::value(...)` taking user-defined function/functor +which checks if `__value__` should be returned by the query. + + bool fun(__value const& v) + { + return v.is_red(); + } + + // ... + + rt.query( + boost::make_pair(index::intersects(box), index::value(fun)) + , std::back_inserter(result)); + +[endsect] + +[endsect] [/ Spatial queries /] + +[section Nearest neighbors queries] + +[section k nearest neighbors] + +There are three ways of performing knn queries. Following queries returns +k `__value__`s closest to some point in space. For `__box__`es +`__indexable__`s closest point of a `__box__` is taken into account by default. + +Method call + + std::vector<__value__> returned_values; + __point__ pt(...); + rt.nearest(pt, k, std::back_inserter(returned_values)); + +Function call + + std::vector<__value__> returned_values; + __point__ pt(...); + index::nearest(rt, pt, k, std::back_inserter(returned_values)); + +Use of `operator |` + + __point__ pt(...); + BOOST_FOREACH(__value__ & v, rt | index::nearest_filtered(pt, k)) + ; // do something with v + +[endsect] + +[section One nearest neighbor] + +Another type of nearest neighbor query is searching for the one closest `__value__`. +If it is found, 1 is returned by the method or function. This kind of query +has only two forms. + +Method call + + __value__ returned_value; + __point__ pt(...); + size_t n = rt.nearest(pt, returned_value); + +Function call + + __value__ Value returned_value; + __point__ pt(...); + size_t n = index::nearest(rt, pt, returned_value); + +[endsect] + +[section Distances predicates] + +It is possible to define if calculated distance between query point and `__value__` should be +greater, lesser or between some other distances. Those are called `DistancesPredicate`s and +may be defined as follows. + + std::vector<__Value__> returned_values; + __point__ pt(...); + + /* default - without bounds */ + index::nearest(rt, pt, k, std::back_inserter(returned_values)); + + /* same as default */ + index::nearest(rt, index::unbounded(pt), k, std::back_inserter(returned_values)); + + /* distance must be greater than or equal to 10 */ + index::nearest(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values)); + + /* distance must be lesser than or equal to 500 */ + index::nearest(rt, index::max_bounded(pt, 500), k, std::back_inserter(returned_values)); + + /* distance must be between 10 and 500 */ + index::nearest(rt, index::bounded(pt, 10, 500), k, std::back_inserter(returned_values)); + +Furthermore, it's possible to define if the closest, furthest or centroidal point of the +non-point `__Indexable__` should be taken into account in the routine calculating distance. + + std::vector<__value__> returned_values; + __point__ pt(...); + + /* default - distance between __indexable__'s closest point and a query point + must be greater than 10 */ + index::nearest(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values)); + + /* same as default - distance between __indexable__'s closest point and a query point + must be greater than 10 */ + index::nearest(rt, index::min_bounded(pt, index::near(10)), k, std::back_inserter(returned_values)); + + /* distance between __indexable__'s furthest point and a query point + must be greater than 10 */ + index::nearest(rt, index::min_bounded(pt, index::far(10)), k, std::back_inserter(returned_values)); + + /* distance between __indexable__'s centroid and a query point + must be greater than 10 */ + index::nearest(rt, index::min_bounded(pt, index::centroid(10)), k, std::back_inserter(returned_values)); + +[endsect] + +[section Using spatial predicates] + +It is possible to use spatial predicates described before in nearest neighbors queries. + + __value__ returned_value; + std::vector<__value__> returned_values; + + __point__ pt(...); + __box__ b(...); + + size_t n1 = rt.nearest(index::bounded(pt, index::far(1), 10), index::intersects(b), returned_value); + + size_t n2 = index::nearest(rt, pt, k, index::within(b), std::back_inserter(returned_values)); + + BOOST_FOREACH(Value & v, rt | index::nearest_filtered(pt, k, index::covered_by(b))) + ; // do something with v + +[endsect] + +[endsect] [/ Nearest neighbors queries /] + +[endsect] [/ R-tree /]