From 6718ae179edccd52acab8f806bca71620596b068 Mon Sep 17 00:00:00 2001 From: Adam Wulkiewicz Date: Mon, 28 Nov 2011 04:16:43 +0000 Subject: [PATCH] docs added [SVN r75702] --- doc/Jamfile.v2 | 20 +++ doc/html/index.html | 73 ++++++++++ doc/html/index/rtree.html | 280 ++++++++++++++++++++++++++++++++++++++ doc/index.xml | 255 ++++++++++++++++++++++++++++++++++ 4 files changed, 628 insertions(+) create mode 100644 doc/Jamfile.v2 create mode 100644 doc/html/index.html create mode 100644 doc/html/index/rtree.html create mode 100644 doc/index.xml diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 new file mode 100644 index 000000000..452d93760 --- /dev/null +++ b/doc/Jamfile.v2 @@ -0,0 +1,20 @@ +# Boost.Geometry.Index (Spatial Indexes Library) +# +# 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) + +project boost/doc ; +import boostbook : boostbook ; + +boostbook geometry-index-doc + : + index.xml + : + boost.root=http://www.boost.org/doc/libs/release + pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/doc/html + ; + diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100644 index 000000000..166f29cad --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,73 @@ + + + +Chapter 1. Boost.Geometry.Index + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
Next
+
+
+

+Chapter 1. Boost.Geometry.Index

+

+Federico J. Fernandez +

+

+Adam Wulkiewicz +

+

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)

+
+
+
+

Table of Contents

+
+
Introduction
+
R-tree
+
+
R-tree creation
+
Values, Indexables and default Translator
+
Inserting and splitting algorithms
+
Inserting and removing Values
+
Spatial queries
+
Spatial predicates
+
Nearest neighbor 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.

+
+
+ + + +
+
+
Next
+ + diff --git a/doc/html/index/rtree.html b/doc/html/index/rtree.html new file mode 100644 index 000000000..3fc70121c --- /dev/null +++ b/doc/html/index/rtree.html @@ -0,0 +1,280 @@ + + + +R-tree + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHome +
+
+

+R-tree

+
+
R-tree creation
+
Values, Indexables and default Translator
+
Inserting and splitting algorithms
+
Inserting and removing Values
+
Spatial queries
+
Spatial predicates
+
Nearest neighbor queries
+
+

+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. +

+
+

+R-tree creation

+

+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. +
    • +
+

+

+

+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;
+
+

+

+
+
+

+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 Points, Boxes, std::pairs, pointers and iterators. +

+
    +
  • Indexable = Point | Box
    • +
  • BasicValue = Indexable | std::pair<Indexable, T> | std::pair<T, Indexable>
    • +
  • Value = BasicValue | BasicValue* | Iterator<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 +

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

+or by function call +

+
+index::insert(rt, std::make_pair(Box(...), 0));
+index::remove(rt, std::make_pair(Box(...), 0));
+
+

+

+
+
+

+Spatial 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<P1, P2> +

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

+or boost::tuple<P1, P2, P3, ...> +

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

+There is special 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));
+
+

+

+
+
+

+Nearest neighbor queries

+TODO +
+
+ + + +
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.xml b/doc/index.xml new file mode 100644 index 000000000..440fa90df --- /dev/null +++ b/doc/index.xml @@ -0,0 +1,255 @@ + + + + + + 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 + +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. + + +
+R-tree creation + +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. + + + + +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; + + +
+ +
+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 Points, Boxes, std::pairs, pointers and iterators. + +Indexable = Point | Box +BasicValue = Indexable | std::pair<Indexable, T> | std::pair<T, Indexable> +Value = BasicValue | BasicValue* | Iterator<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 + +rt.insert(std::make_pair(Box(...), 0)); +rt.remove(std::make_pair(Box(...), 0)); + +or by function call + +index::insert(rt, std::make_pair(Box(...), 0)); +index::remove(rt, std::make_pair(Box(...), 0)); + + +
+ +
+Spatial 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<P1, P2> + +rt.query( + std::make_pair(index::intersects(box1), !index::within(box2)) + , std::back_inserter(result)); + +or boost::tuple<P1, P2, P3, ...> + +rt.query( + boost::make_tuple(index::intersects(box1), !index::within(box2), index::overlaps(box3)) + , std::back_inserter(result)); + +There is special 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)); + + +
+ +
+Nearest neighbor queries +TODO +
+ +
+ +