diff --git a/doc/html/geometry_index/r_tree.html b/doc/html/geometry_index/r_tree.html index c8b440eaa..d8f3103ee 100644 --- a/doc/html/geometry_index/r_tree.html +++ b/doc/html/geometry_index/r_tree.html @@ -49,31 +49,21 @@
Insert iterator
-
Spatial queries
+
Queries
-
Basic +
Performing + a query
+
Spatial queries
-
Spatial - predicates
-
Connecting - predicates
-
Value +
Nearest + neighbours queries
+
Value predicate
-
Inserting +
Passing + a set of predicates
+
Inserting query results into the other R-tree
-
Nearest - neighbours queries
-
-
k - nearest neighbours
-
One - nearest neighbour
-
Distances - predicates
-
Using - spatial predicates
-
Reference
boost::geometry::index::rtree
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 263f4d250..cce4835e6 100644 --- a/doc/html/geometry_index/r_tree/creation_and_modification.html +++ b/doc/html/geometry_index/r_tree/creation_and_modification.html @@ -7,7 +7,7 @@ - + @@ -20,7 +20,7 @@
-PrevUpHomeNext +PrevUpHomeNext

@@ -357,7 +357,7 @@
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/geometry_index/r_tree/nearest_neighbours_queries.html b/doc/html/geometry_index/r_tree/nearest_neighbours_queries.html deleted file mode 100644 index 18130e9d5..000000000 --- a/doc/html/geometry_index/r_tree/nearest_neighbours_queries.html +++ /dev/null @@ -1,240 +0,0 @@ - - - -Nearest neighbours queries - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
k - nearest neighbours
-
One - nearest neighbour
-
Distances - predicates
-
Using - spatial predicates
-
-

- Nearest neighbours queries returns Values - which are closest to some point in space. Additionally it is possible to - pass distance predicates in order to define how the distance to the Value should be calculated or minimal and - maximal distances. The examples of some knn queries may be found in the table - below. All queries returns 5 closest Values. - The query point, region and result Values are orange. -

-
----- - - - - - - - - - - -
-

- Basic knn query -

- 		-

- knn query - distance to Indexable's furthest point greather than - ... -

- 		-

- knn query - distance to Indexable's closest point greather than - ... -

-
-

- knn -

- 		-

- knn_inters -

- 		-

- knn_cover -

-
-
-
-

- There are three ways of performing knn queries. Following queries returns - k Values closest to some point in space. For Boxes - Indexables the distance to the nearest point is calculated - by default. -

-

- Method call -

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

- Function call -

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

- Use of operator | -

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

- Another type of nearest neighbour 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_query(pt, returned_value);
-
-

- Function call -

-
Value Value returned_value;
-Point pt(...);
-size_t n = index::nearest_query(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_query(rt, pt, k, std::back_inserter(returned_values));
-
-/* same as default */
-index::nearest_query(rt, index::unbounded(pt), k, std::back_inserter(returned_values));
-
-/* distance must be greater than or equal to 10 */
-index::nearest_query(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values));
-
-/* distance must be lesser than or equal to 500 */
-index::nearest_query(rt, index::max_bounded(pt, 500), k, std::back_inserter(returned_values));
-
-/* distance must be between 10 and 500 */
-index::nearest_query(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_query(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_query(rt, index::min_bounded(pt, index::to_nearest(10)), k, std::back_inserter(returned_values));
-
-/* distance between Indexable's furthest point and a query point
-must be greater than 10 */
-index::nearest_query(rt, index::min_bounded(pt, index::to_furthest(10)), k, std::back_inserter(returned_values));
-
-/* distance between Indexable's centroid and a query point
-must be greater than 10 */
-index::nearest_query(rt, index::min_bounded(pt, index::to_centroid(10)), k, std::back_inserter(returned_values));
-
-
-
-
-

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

-
Value returned_value;
-std::vector<Value> returned_values;
-
-Point pt(...);
-Box b(...);
-
-size_t n1 = rt.nearest_query(index::bounded(pt, index::to_furthest(1), 10), index::intersects(b), returned_value);
-
-size_t n2 = index::nearest_query(rt, pt, k, index::within(b), std::back_inserter(returned_values));
-
-BOOST_FOREACH(Value & v, rt | index::adaptors::nearest_queried(pt, k, index::covered_by(b)))
-  ; // do something with v
-
-
-
- - - -
Copyright © 2011-2013 Adam Wulkiewicz

- 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/queries.html b/doc/html/geometry_index/r_tree/queries.html new file mode 100644 index 000000000..7c642bc32 --- /dev/null +++ b/doc/html/geometry_index/r_tree/queries.html @@ -0,0 +1,538 @@ + + + +Queries + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Performing + a query
+
Spatial + queries
+
Nearest + neighbours queries
+
Value + predicate
+
Passing + a set of predicates
+
Inserting + query results into the other R-tree
+
+

+ Queries returns Values which + meets some predicates. Currently supported are three types of predicates: +

+
    +
  • + spatial predicates - defining relationship between stored Values and + some Geometry, +
    • +
  • + nearest predicates - defining relationship between stored Values and + some Point, +
    • +
  • + value predicate - passing user-defined functor to the query. +
    • +
+

+ For example queries may be used to retrieve Values: +

+
    +
  • + intersecting some area but not within other area, +
    • +
  • + are nearest to some point, +
    • +
  • + overlapping a box and has user-defined property. +
    • +
+
+
+

+ There are three ways to perform a query. In the following example Box + is used as the predicate, this is a default spatial predicate described + in the following section. Following queries returns Values + intersecting some region defined as a Box. + These three methods are: +

+

+ 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 pipe operator generating a range +

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

+ Spatial query returns Values which are related somehow to a geometry or + some number of geometries. Names of spatial predicates corresponds to names + of Boost.Geometry + algorithms. Examples of some basic queries may be found in tables below. + The query region and result Values + are orange. +

+
+++++++ + + + + + + + + + + + + + + +
+

+ intersects(Box) - default +

+ 		+

+ covered_by(Box) +

+ 		+

+ disjoint(Box) +

+ 		+

+ overlaps(Box) +

+ 		+

+ within(Box) +

+
+

+ intersects +

+ 		+

+ within +

+ 		+

+ disjoint +

+ 		+

+ overlaps +

+ 		+

+ within +

+
+
+++++ + + + + + + + + + + +
+

+ intersects(Ring) +

+ 		+

+ intersects(Polygon) +

+ 		+

+ intersects(MultiPolygon) +

+
+

+ intersects_ring +

+ 		+

+ intersects_poly +

+ 		+

+ intersects_mpoly +

+
+

+ To use a spatial predicate one may pass a geometry (which is a default + case) or use one of the functions defined in boost::geometry::index + namespace to define it explicitly. +

+
rt.query(box, std::back_inserter(result));                    // default case - intersects
+rt.query(index::intersects(box), std::back_inserter(result)); // the 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::intersects(box), std::back_inserter(result));
+// the same as
+rt.query(index::disjoint(box), std::back_inserter(result));
+
+
+
+
+

+ Nearest neighbours queries returns Values + which are closest to some point in space. Additionally it is possible to + pass distance predicates in order to define how the distance to the Value should be calculated or minimal + and maximal distances. The examples of some knn queries may be found in + the table below. All queries returns 5 closest Values. + The query point, region and result Values are orange. +

+
+++++ + + + + + + + + + + +
+

+ Basic knn query +

+ 		+

+ knn query - distance to Indexable's furthest point greather than + ... +

+ 		+

+ knn query - distance to Indexable's closest point greather than + ... +

+
+

+ knn +

+ 		+

+ knn_inters +

+ 		+

+ knn_cover +

+
+
+
+

+ There are three ways of performing knn queries. Following queries returns + k Values closest to some point in space. For Boxes + Indexables the distance to the nearest point is calculated + by default. +

+

+ Method call +

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

+ Function call +

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

+ Use of operator | +

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

+ Another type of nearest neighbour 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.query(index::nearest(pt), returned_value);
+
+

+ Function call +

+
Value Value returned_value;
+Point pt(...);
+size_t n = index::query(rt, index::nearest(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::query(rt, index::nearest(pt, k), std::back_inserter(returned_values));
+
+/* same as default */
+index::query(rt, index::nearest(index::unbounded(pt), k), std::back_inserter(returned_values));
+
+/* distance must be greater than or equal to 10 */
+index::query(rt, index::nearest(index::min_bounded(pt, 10), k), std::back_inserter(returned_values));
+
+/* distance must be lesser than or equal to 500 */
+index::query(rt, index::nearest(index::max_bounded(pt, 500), k), std::back_inserter(returned_values));
+
+/* distance must be between 10 and 500 */
+index::query(rt, index::nearest(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::query(rt, index::nearest(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::query(rt, index::nearest(index::min_bounded(pt, index::to_nearest(10)), k), std::back_inserter(returned_values));
+
+/* distance between Indexable's furthest point and a query point
+must be greater than 10 */
+index::query(rt, index::nearest(index::min_bounded(pt, index::to_furthest(10)), k), std::back_inserter(returned_values));
+
+/* distance between Indexable's centroid and a query point
+must be greater than 10 */
+index::query(rt, index::nearest(index::min_bounded(pt, index::to_centroid(10)), k), std::back_inserter(returned_values));
+
+
+
+
+
+

+ There is a unique predicate index::value(...) taking user-defined function/functor + which checks if Value should be returned by the query. It + may be used to check some specific conditions for user-defined Values. +

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

+ It's possible to use some number of predicates in one query by passing: +

+
    +
  • + std::pair<Pred1, + Pred2>, +
    • +
  • + boost::tuple<Pred1, + Pred2, + Pred3, + ...> +
    • +
  • + predicates connected by operator&& e.g. Pred1 + && Pred2 + && Pred3 + && .... +
    • +
+

+ These predicates are connected by logical AND. Passing all predicates together + not only makes possible to construct advanced queries but is also faster + than separate calls because the tree is traversed only once. Traversing + is continued and Values + are returned only if all predicates are met. Predicates are checked left-to-right + so placing most restictive predicates first should accelerate the search. +

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

+ Of course it's possible to connect different types of predicates together. +

+
rt.query(index::nearest(index::bounded(pt, index::to_furthest(1), 10)) && index::intersects(b), returned_value);
+
+index::query(rt, index::nearest(pt, k) && index::within(b), std::back_inserter(returned_values));
+
+BOOST_FOREACH(Value & v, rt | index::adaptors::queried(index::nearest(pt, k) && index::covered_by(b)))
+  ; // do something with v
+
+
+
+
+

+ There are several ways of inserting Values returned by a query to the other + R-tree container. The most basic way is creating a temporary container + for Values and insert them later. +

+
namespace bgi = boost::geometry::index;
+typedef std::pair<Box, int> Value;
+typedef bgi::rtree< Value, bgi::linear<32, 8> > RTree;
+
+RTree rt1;
+/* some inserting into the tree */
+
+std::vector<Value> result;
+rt1.query(Box(/*...*/), std::back_inserter(result));
+RTree rt2(result.begin(), result.end());
+
+

+ However there are better ways. One of these methods is mentioned in the + "Creation and modification" section. The insert iterator may + be passed directly to the query, which will be the fastest way of inserting + query results because temporary container won't be used. +

+
RTree rt3;
+rt1.query(Box(/*...*/), bgi::inserter(rt3));
+
+

+ If you like Boost.Range you'll appreciate the third option. You may pass + the result Range directly to the constructor. However in this case the + temporary container is created. +

+
RTree rt4(rt1 | bgi::adaptors::queried(Box(/*...*/)));
+
+
+
+ + + +
Copyright © 2011-2013 Adam Wulkiewicz

+ 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/r_tree_creation.html b/doc/html/geometry_index/r_tree/r_tree_creation.html deleted file mode 100644 index 649317bf6..000000000 --- a/doc/html/geometry_index/r_tree/r_tree_creation.html +++ /dev/null @@ -1,184 +0,0 @@ - - - -R-tree creation - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
R-tree - template parameters
-
Values, - Indexables and default Translator
-
Inserting - and splitting algorithms
-
Inserting - and removing Values
-
-
-
-

- 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 the Translator - is passed as parameter. It knows how to interpret those Values - and extract an object understandable by the R-tree. Those objects are called - Indexables. Each type adapted to Point - or Box - concept is an Indexable. 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 internal structure of the R-tree depends on algorithms used in the - insertion process. The most important is 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;
-
-
-
-
-

- Following code creates an R-tree using quadratic algorithm. -

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

- To insert or remove Value's by method calls one may use the following code. -

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

- To insert or remove Value's by function calls one may use the following - code. -

-
Value v = std::make_pair(Box(...), 0);
-index::insert(rt, v);
-index::remove(rt, v);
-
-
-
- - - -
Copyright © 2011, 2012 Adam Wulkiewicz
Copyright © 2008 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/reference.html b/doc/html/geometry_index/r_tree/reference.html index 2f968054b..4afc486ec 100644 --- a/doc/html/geometry_index/r_tree/reference.html +++ b/doc/html/geometry_index/r_tree/reference.html @@ -6,7 +6,7 @@ - + @@ -19,7 +19,7 @@
-PrevUpHome +PrevUpHome

@@ -47,7 +47,7 @@ boost::geometry::index::rtree

- + The R-tree spatial index.

@@ -6913,7 +6913,7 @@ The R-tree spatial index. boost::geometry::index::linear

- + Linear r-tree creation algorithm parameters.

@@ -6988,7 +6988,7 @@ Linear r-tree creation algorithm parameters. boost::geometry::index::quadratic

- + Quadratic r-tree creation algorithm parameters.

@@ -7063,7 +7063,7 @@ Quadratic r-tree creation algorithm parameters. boost::geometry::index::rstar

- + R*-tree creation algorithm parameters.

@@ -7167,7 +7167,7 @@ R*-tree creation algorithm parameters. boost::geometry::index::runtime::linear

- + Linear r-tree creation algorithm parameters.

@@ -7303,7 +7303,7 @@ Linear r-tree creation algorithm parameters. boost::geometry::index::runtime::quadratic

- + Quadratic r-tree creation algorithm parameters.

@@ -7439,7 +7439,7 @@ Quadratic r-tree creation algorithm parameters. boost::geometry::index::runtime::rstar

- + R*-tree creation algorithm parameters.

@@ -10167,7 +10167,7 @@ R*-tree creation algorithm parameters. boost::geometry::index::translator::def

- + The default translator.

@@ -10237,7 +10237,7 @@ The default translator. boost::geometry::index::translator::index

- + The index translator.

@@ -10533,7 +10533,7 @@ The index translator.
-PrevUpHome +PrevUpHome
diff --git a/doc/html/geometry_index/r_tree/rtree_quickstart.html b/doc/html/geometry_index/r_tree/rtree_quickstart.html index ca0b0696c..e0430d0a4 100644 --- a/doc/html/geometry_index/r_tree/rtree_quickstart.html +++ b/doc/html/geometry_index/r_tree/rtree_quickstart.html @@ -116,7 +116,7 @@ 
// 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.query(query_box, std::back_inserter(result_s));

@@ -130,7 +130,7 @@ 

// find 5 nearest values to a point
 std::vector<value> result_n;
-rtree.nearest_query(point(0, 0), 5, std::back_inserter(result_n));
+rtree.query(bgi::nearest(point(0, 0), 5), std::back_inserter(result_n));

diff --git a/doc/html/geometry_index/r_tree/spatial_queries.html b/doc/html/geometry_index/r_tree/spatial_queries.html deleted file mode 100644 index bef9c43e5..000000000 --- a/doc/html/geometry_index/r_tree/spatial_queries.html +++ /dev/null @@ -1,308 +0,0 @@ - - - -Spatial queries - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
Basic - queries
-
Spatial - predicates
-
Connecting - predicates
-
Value - predicate
-
Inserting - query results into the other R-tree
-
-

- Spatial queries returns Values - which meets some predicates. For instance it may be used to retrieve Values - intersecting some area or are within some other area. Names of predicates - corresponds to names of Boost.Geometry - algorithms. The examples of some basic queries may be found in tables below. - The query region and result Values - are orange. -

-
------- - - - - - - - - - - - - - - -
-

- intersects(Box) - default -

- 		-

- covered_by(Box) -

- 		-

- disjoint(Box) -

- 		-

- overlaps(Box) -

- 		-

- within(Box) -

-
-

- intersects -

- 		-

- within -

- 		-

- disjoint -

- 		-

- overlaps -

- 		-

- within -

-
-
----- - - - - - - - - - - -
-

- intersects(Ring) -

- 		-

- intersects(Polygon) -

- 		-

- intersects(MultiPolygon) -

-
-

- intersects_ring -

- 		-

- intersects_poly -

- 		-

- intersects_mpoly -

-
-
-
-

- There are three ways to perform a spatial query. Following queries returns - Values intersecting some region defined as a box in this example. -

-

- Method call -

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

- Function call -

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

- Use of pipe operator generating a range -

-
Box box_region(...);
-BOOST_FOREACH(Value & v, rt | index::adaptors::spatial_queried(box_region))
-  ; // do something with v
-
-
-
-
-

- To explicitly define one of the predicates one may pass it to the spatial_query() - as the first argument. -

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

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

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

- It's possible to use some number of predicates in one time by passing - std::pair<Pred1, Pred2> - or boost::tuple<Pred1, Pred2, Pred3, ...>. These predicates are connected - by logical AND. Passing all predicates together not only makes possible - to construct advanced queries but is also faster than separate calls because - the tree is traversed only once. Traversing is continued and Values are returned only if all predicates - are met. Predicates are checked left-to-right so placing most restictive - predicates first should accelerate the search. -

-
rt.spatial_query(
-  std::make_pair(
-    index::intersects(box1), !index::within(box2) ),
-  std::back_inserter(result));
-
-rt.spatial_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.spatial_query(
-  boost::make_pair(
-    index::intersects(box), index::value(fun) ),
-  std::back_inserter(result));
-
-
-
-
-

- There are several ways of inserting Values returned by a query to the other - R-tree container. The most basic way is creating a temporary container - for Values and insert them later. -

-
namespace bgi = boost::geometry::index;
-typedef std::pair<Box, int> Value;
-typedef bgi::rtree< Value, bgi::linear<32, 8> > RTree;
-
-RTree rt1;
-/* some inserting into the tree */
-
-std::vector<Value> result;
-rt1.spatial_query(Box(/*...*/), std::back_inserter(result));
-RTree rt2(result.begin(), result.end());
-
-

- However there are better ways. One of these methods is mentioned in the - "Creation and modification" section. The insert iterator may - be passed directly to the query, which will be the fastest way of inserting - query results because temporary container won't be used. -

-
RTree rt3;
-rt1.spatial_query(Box(/*...*/), bgi::inserter(rt3));
-
-

- If you like Boost.Range you'll appreciate the third option. You may pass - the result Range directly to the constructor. -

-
RTree rt4(rt1 | bgi::adaptors::spatial_queried(Box(/*...*/)));
-
-
-
- - - -
Copyright © 2011-2013 Adam Wulkiewicz

- 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/index.html b/doc/html/index.html index 3f2ec733d..edb363969 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -43,16 +43,14 @@
Quick Start
Creation and modification
-
Spatial queries
-
Nearest - neighbours queries
+
Queries
Reference
- +

Last revised: January 26, 2013 at 00:31:44 GMT

Last revised: January 26, 2013 at 01:20:57 GMT
diff --git a/doc/rtree.qbk b/doc/rtree.qbk index ee42c8a74..8321a6d16 100644 --- a/doc/rtree.qbk +++ b/doc/rtree.qbk @@ -13,9 +13,7 @@ [include rtree/introduction.qbk] [include rtree/quickstart.qbk] [include rtree/creation.qbk] -[include rtree/spatial_query.qbk] -[include rtree/nearest_query.qbk] -[/include rtree/exception_safety.qbk] +[include rtree/query.qbk] [section:reference Reference] diff --git a/doc/rtree/nearest_query.qbk b/doc/rtree/nearest_query.qbk deleted file mode 100644 index f993de169..000000000 --- a/doc/rtree/nearest_query.qbk +++ /dev/null @@ -1,137 +0,0 @@ -[/============================================================================ - Boost.Geometry Index - - Copyright (c) 2011-2012 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 Nearest neighbours queries] - -Nearest neighbours queries returns `Value`s which are closest to some point in space. -Additionally it is possible to pass distance predicates in order to define how the distance -to the `Value` should be calculated or minimal and maximal distances. The examples of some knn -queries may be found in the table below. All queries returns 5 closest `Values`. -The query point, region and result Values are orange. - -[table -[[Basic knn query] [knn query - distance to Indexable's furthest point greather than ...] [knn query - distance to Indexable's closest point greather than ...]] -[[[$../images/knn.png]] [[$../images/knn_inters.png]] [[$../images/knn_cover.png]]] -] - -[section k nearest neighbours] - -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 the distance to the nearest point is calculated by default. - -Method call - - std::vector<__value__> returned_values; - __point__ pt(...); - rt.nearest_query(pt, k, std::back_inserter(returned_values)); - -Function call - - std::vector<__value__> returned_values; - __point__ pt(...); - index::nearest_query(rt, pt, k, std::back_inserter(returned_values)); - -Use of `operator |` - - __point__ pt(...); - BOOST_FOREACH(__value__ & v, rt | index::adaptors::nearest_queried(pt, k)) - ; // do something with v - -[endsect] - -[section One nearest neighbour] - -Another type of nearest neighbour 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_query(pt, returned_value); - -Function call - - __value__ Value returned_value; - __point__ pt(...); - size_t n = index::nearest_query(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_query(rt, pt, k, std::back_inserter(returned_values)); - - /* same as default */ - index::nearest_query(rt, index::unbounded(pt), k, std::back_inserter(returned_values)); - - /* distance must be greater than or equal to 10 */ - index::nearest_query(rt, index::min_bounded(pt, 10), k, std::back_inserter(returned_values)); - - /* distance must be lesser than or equal to 500 */ - index::nearest_query(rt, index::max_bounded(pt, 500), k, std::back_inserter(returned_values)); - - /* distance must be between 10 and 500 */ - index::nearest_query(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_query(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_query(rt, index::min_bounded(pt, index::to_nearest(10)), k, std::back_inserter(returned_values)); - - /* distance between Indexable's furthest point and a query point - must be greater than 10 */ - index::nearest_query(rt, index::min_bounded(pt, index::to_furthest(10)), k, std::back_inserter(returned_values)); - - /* distance between Indexable's centroid and a query point - must be greater than 10 */ - index::nearest_query(rt, index::min_bounded(pt, index::to_centroid(10)), k, std::back_inserter(returned_values)); - -[endsect] - -[section Using spatial predicates] - -It is possible to use spatial predicates described before in nearest neighbours queries. - - __value__ returned_value; - std::vector<__value__> returned_values; - - __point__ pt(...); - __box__ b(...); - - size_t n1 = rt.nearest_query(index::bounded(pt, index::to_furthest(1), 10), index::intersects(b), returned_value); - - size_t n2 = index::nearest_query(rt, pt, k, index::within(b), std::back_inserter(returned_values)); - - BOOST_FOREACH(Value & v, rt | index::adaptors::nearest_queried(pt, k, index::covered_by(b))) - ; // do something with v - -[endsect] - -[endsect] [/ Nearest neighbours queries /] diff --git a/doc/rtree/query.qbk b/doc/rtree/query.qbk new file mode 100644 index 000000000..3ce7f051f --- /dev/null +++ b/doc/rtree/query.qbk @@ -0,0 +1,273 @@ +[/============================================================================ + Boost.Geometry Index + + Copyright (c) 2011-2012 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 Queries] + +Queries returns `Value`s which meets some predicates. Currently supported are three types of predicates: + +* spatial predicates - defining relationship between stored Values and some Geometry, +* nearest predicates - defining relationship between stored Values and some Point, +* value predicate - passing user-defined functor to the query. + +For example queries may be used to retrieve Values: + +* intersecting some area but not within other area, +* are nearest to some point, +* overlapping a box and has user-defined property. + +[section Performing a query] + +There are three ways to perform a query. In the following example `__box__` is used as +the predicate, this is a default spatial predicate described in the following section. +Following queries returns `__value__`s intersecting some region defined as a `__box__`. +These three methods are: + +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 pipe operator generating a range + + __box__ box_region(...); + BOOST_FOREACH(__value__ & v, rt | index::adaptors::queried(box_region)) + ; // do something with v + +[endsect] + +[section Spatial queries] + +Spatial query returns Values which are related somehow to a geometry or some number of geometries. +Names of spatial predicates corresponds to names of __boost_geometry__ algorithms. Examples of some +basic queries may be found in tables below. The query region and result `Value`s are orange. + +[table +[[intersects(Box) - default] [covered_by(Box)] [disjoint(Box)] [overlaps(Box)] [within(Box)]] +[[[$../images/intersects.png]] [[$../images/within.png]] [[$../images/disjoint.png]] [[$../images/overlaps.png]] [[$../images/within.png]]] +] + +[table +[[intersects(Ring)] [intersects(Polygon)] [intersects(MultiPolygon)]] +[[[$../images/intersects_ring.png]] [[$../images/intersects_poly.png]] [[$../images/intersects_mpoly.png]]] +] + +To use a spatial predicate one may pass a geometry (which is a default case) or use one of the functions defined in +`boost::geometry::index` namespace to define it explicitly. + + rt.query(box, std::back_inserter(result)); // default case - intersects + rt.query(index::intersects(box), std::back_inserter(result)); // the 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::intersects(box), std::back_inserter(result)); + // the same as + rt.query(index::disjoint(box), std::back_inserter(result)); + +[endsect] + +[section Nearest neighbours queries] + +Nearest neighbours queries returns `Value`s which are closest to some point in space. +Additionally it is possible to pass distance predicates in order to define how the distance +to the `Value` should be calculated or minimal and maximal distances. The examples of some knn +queries may be found in the table below. All queries returns 5 closest `Values`. +The query point, region and result Values are orange. + +[table +[[Basic knn query] [knn query - distance to Indexable's furthest point greather than ...] [knn query - distance to Indexable's closest point greather than ...]] +[[[$../images/knn.png]] [[$../images/knn_inters.png]] [[$../images/knn_cover.png]]] +] + +[section k nearest neighbours] + +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 the distance to the nearest point is calculated by default. + +Method call + + std::vector<__value__> returned_values; + __point__ pt(...); + rt.query(index::nearest(pt, k), std::back_inserter(returned_values)); + +Function call + + std::vector<__value__> returned_values; + __point__ pt(...); + index::query(rt, index::nearest(pt, k), std::back_inserter(returned_values)); + +Use of `operator |` + + __point__ pt(...); + BOOST_FOREACH(__value__ & v, rt | index::adaptors::queried(index::nearest(pt, k))) + ; // do something with v + +[endsect] + +[section One nearest neighbour] + +Another type of nearest neighbour 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.query(index::nearest(pt), returned_value); + +Function call + + __value__ Value returned_value; + __point__ pt(...); + size_t n = index::query(rt, index::nearest(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::query(rt, index::nearest(pt, k), std::back_inserter(returned_values)); + + /* same as default */ + index::query(rt, index::nearest(index::unbounded(pt), k), std::back_inserter(returned_values)); + + /* distance must be greater than or equal to 10 */ + index::query(rt, index::nearest(index::min_bounded(pt, 10), k), std::back_inserter(returned_values)); + + /* distance must be lesser than or equal to 500 */ + index::query(rt, index::nearest(index::max_bounded(pt, 500), k), std::back_inserter(returned_values)); + + /* distance must be between 10 and 500 */ + index::query(rt, index::nearest(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::query(rt, index::nearest(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::query(rt, index::nearest(index::min_bounded(pt, index::to_nearest(10)), k), std::back_inserter(returned_values)); + + /* distance between Indexable's furthest point and a query point + must be greater than 10 */ + index::query(rt, index::nearest(index::min_bounded(pt, index::to_furthest(10)), k), std::back_inserter(returned_values)); + + /* distance between Indexable's centroid and a query point + must be greater than 10 */ + index::query(rt, index::nearest(index::min_bounded(pt, index::to_centroid(10)), k), std::back_inserter(returned_values)); + +[endsect] + +[endsect] + +[section Value predicate] + +There is a unique predicate `index::value(...)` taking user-defined function/functor +which checks if `__value__` should be returned by the query. It may be used to check +some specific conditions for user-defined Values. + + bool fun(__value__ const& v) + { + return v.is_red(); + } + + // ... + + rt.query(index::intersects(box) && index::value(fun), + std::back_inserter(result)); + +[endsect] + +[section Passing a set of predicates] + +It's possible to use some number of predicates in one query by passing: + +* `std::pair`, +* `boost::tuple` +* predicates connected by `operator&&` e.g. `Pred1 && Pred2 && Pred3 && ...`. + +These predicates are connected by logical AND. Passing all predicates together not only makes possible +to construct advanced queries but is also faster than separate calls because the tree is traversed only once. +Traversing is continued and `Value`s are returned only if all predicates are met. Predicates are checked +left-to-right so placing most restictive predicates first should accelerate the search. + + rt.query(index::intersects(box1) && !index::within(box2), + std::back_inserter(result)); + + rt.query(index::intersects(box1) && !index::within(box2) && index::overlaps(box3), + std::back_inserter(result)); + +Of course it's possible to connect different types of predicates together. + + rt.query(index::nearest(index::bounded(pt, index::to_furthest(1), 10)) && index::intersects(b), returned_value); + + index::query(rt, index::nearest(pt, k) && index::within(b), std::back_inserter(returned_values)); + + BOOST_FOREACH(Value & v, rt | index::adaptors::queried(index::nearest(pt, k) && index::covered_by(b))) + ; // do something with v + +[endsect] + +[section Inserting query results into the other R-tree] + +There are several ways of inserting Values returned by a query to the other R-tree container. +The most basic way is creating a temporary container for Values and insert them later. + + namespace bgi = boost::geometry::index; + typedef std::pair __value__; + typedef bgi::rtree< __value__, bgi::linear<32, 8> > RTree; + + RTree rt1; + /* some inserting into the tree */ + + std::vector result; + rt1.query(Box(/*...*/), std::back_inserter(result)); + RTree rt2(result.begin(), result.end()); + +However there are better ways. One of these methods is mentioned in the "Creation and modification" section. +The insert iterator may be passed directly to the query, which will be the fastest way of inserting +query results because temporary container won't be used. + + RTree rt3; + rt1.query(Box(/*...*/), bgi::inserter(rt3)); + +If you like Boost.Range you'll appreciate the third option. You may pass the result Range directly to the +constructor. However in this case the temporary container is created. + + RTree rt4(rt1 | bgi::adaptors::queried(Box(/*...*/))); + +[endsect] + +[endsect] [/ Queries /] diff --git a/doc/rtree/spatial_query.qbk b/doc/rtree/spatial_query.qbk deleted file mode 100644 index 0d19e27b7..000000000 --- a/doc/rtree/spatial_query.qbk +++ /dev/null @@ -1,142 +0,0 @@ -[/============================================================================ - Boost.Geometry Index - - Copyright (c) 2011-2012 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 Spatial queries] - -Spatial queries returns `Value`s which meets some predicates. For instance it may be used to -retrieve Values intersecting some area or are within some other area. Names of predicates -corresponds to names of __boost_geometry__ algorithms. The examples of some -basic queries may be found in tables below. The query region and result `Value`s are orange. - -[table -[[intersects(Box) - default] [covered_by(Box)] [disjoint(Box)] [overlaps(Box)] [within(Box)]] -[[[$../images/intersects.png]] [[$../images/within.png]] [[$../images/disjoint.png]] [[$../images/overlaps.png]] [[$../images/within.png]]] -] - -[table -[[intersects(Ring)] [intersects(Polygon)] [intersects(MultiPolygon)]] -[[[$../images/intersects_ring.png]] [[$../images/intersects_poly.png]] [[$../images/intersects_mpoly.png]]] -] - -[section Basic queries] - -There are three ways to perform a spatial query. Following queries returns -`__value__`s intersecting some region defined as a box in this example. - -Method call - - std::vector<__value__> returned_values; - __box__ box_region(...); - rt.spatial_query(box_region, std::back_inserter(returned_values)); - -Function call - - std::vector<__value__> returned_values; - __box__ box_region(...); - index::spatial_query(rt, box_region, std::back_inserter(returned_values)); - -Use of pipe operator generating a range - - __box__ box_region(...); - BOOST_FOREACH(__value__ & v, rt | index::adaptors::spatial_queried(box_region)) - ; // do something with v -[endsect] - -[section Spatial predicates] - -To explicitly define one of the predicates one may pass it to the `spatial_query()` as -the first argument. - - rt.spatial_query(box, std::back_inserter(result)); // default case - intersects - rt.spatial_query(index::intersects(box), std::back_inserter(result)); // the same as default - rt.spatial_query(index::covered_by(box), std::back_inserter(result)); - rt.spatial_query(index::disjont(box), std::back_inserter(result)); - rt.spatial_query(index::overlaps(box), std::back_inserter(result)); - rt.spatial_query(index::within(box), std::back_inserter(result)); - -All predicates may be negated, e.g.: - - rt.spatial_query(!index::intersects(box), std::back_inserter(result)); - // the same as - rt.spatial_query(index::disjoint(box), std::back_inserter(result)); - -[endsect] - -[section Connecting predicates] - -It's possible to use some number of predicates in one time by passing `std::pair` -or `boost::tuple`. These predicates are connected by logical AND. -Passing all predicates together not only makes possible to construct advanced queries but is also -faster than separate calls because the tree is traversed only once. Traversing is continued and -`Value`s are returned only if all predicates are met. Predicates are checked left-to-right so placing -most restictive predicates first should accelerate the search. - - rt.spatial_query( - std::make_pair( - index::intersects(box1), !index::within(box2) ), - std::back_inserter(result)); - - rt.spatial_query( - boost::make_tuple( - index::intersects(box1), !index::within(box2), index::overlaps(box3) ), - std::back_inserter(result)); - -[endsect] - -[section Value predicate] - -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.spatial_query( - boost::make_pair( - index::intersects(box), index::value(fun) ), - std::back_inserter(result)); - -[endsect] - -[section Inserting query results into the other R-tree] - -There are several ways of inserting Values returned by a query to the other R-tree container. -The most basic way is creating a temporary container for Values and insert them later. - - namespace bgi = boost::geometry::index; - typedef std::pair __value__; - typedef bgi::rtree< __value__, bgi::linear<32, 8> > RTree; - - RTree rt1; - /* some inserting into the tree */ - - std::vector result; - rt1.spatial_query(Box(/*...*/), std::back_inserter(result)); - RTree rt2(result.begin(), result.end()); - -However there are better ways. One of these methods is mentioned in the "Creation and modification" section. -The insert iterator may be passed directly to the query, which will be the fastest way of inserting -query results because temporary container won't be used. - - RTree rt3; - rt1.spatial_query(Box(/*...*/), bgi::inserter(rt3)); - -If you like Boost.Range you'll appreciate the third option. You may pass the result Range directly to the -constructor. - - RTree rt4(rt1 | bgi::adaptors::spatial_queried(Box(/*...*/))); - -[endsect] - -[endsect] [/ Spatial queries /] diff --git a/doc/src/examples/rtree/quick_start.cpp b/doc/src/examples/rtree/quick_start.cpp index 806f2f08a..917fa1df7 100644 --- a/doc/src/examples/rtree/quick_start.cpp +++ b/doc/src/examples/rtree/quick_start.cpp @@ -55,13 +55,13 @@ int main(void) // find values intersecting some area defined by a box box query_box(point(0, 0), point(5, 5)); std::vector result_s; - rtree.spatial_query(query_box, std::back_inserter(result_s)); + rtree.query(query_box, std::back_inserter(result_s)); //] //[rtree_quickstart_nearest_query // find 5 nearest values to a point std::vector result_n; - rtree.nearest_query(point(0, 0), 5, std::back_inserter(result_n)); + rtree.query(bgi::nearest(point(0, 0), 5), std::back_inserter(result_n)); //] //[rtree_quickstart_output