From 60dc343582de7d584b6c0e8df027495168d3bd2d Mon Sep 17 00:00:00 2001 From: Adam Wulkiewicz Date: Mon, 28 Nov 2011 15:43:13 +0000 Subject: [PATCH] knn queries description added to doc [SVN r75713] --- doc/html/index.html | 16 +-- doc/html/index/rtree.html | 213 +++++++++++++++++++++++++++++++++----- doc/index.xml | 175 ++++++++++++++++++++++++++++--- 3 files changed, 353 insertions(+), 51 deletions(-) diff --git a/doc/html/index.html b/doc/html/index.html index 1456ee433..ae1ad02c5 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -31,7 +31,7 @@

Copyright © 2008 Federico J. Fernandez

Copyright © 2011 Adam Wulkiewicz

-

Use, modification and distribution is subject to the Boost +

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)

@@ -42,13 +42,13 @@
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
+
R-tree creation
+
Values, Indexables and default Translator
+
Inserting and splitting algorithms
+
Inserting and removing Values
+
Spatial queries
+
Spatial predicates
+
Nearest neighbors queries
diff --git a/doc/html/index/rtree.html b/doc/html/index/rtree.html index 4dba80168..7df2cd5d7 100644 --- a/doc/html/index/rtree.html +++ b/doc/html/index/rtree.html @@ -25,13 +25,13 @@

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

R-tree is a self-balancing search tree with nodes stored with their axis aligned @@ -42,7 +42,7 @@ which may be stored inside the node are user defined.

-R-tree creation

+R-tree creation

R-tree has 4 parameters:

@@ -56,10 +56,13 @@ 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. +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. +Translator - type of object translating Value objects +to Indexable objects (Point or Box) which +R-tree can handle.
  • Allocator - the allocator. @@ -68,7 +71,8 @@ rtree<Value, Parameters, Translator, Allocator>

    -In order to create a R-tree object storing values of type std::pair<Box, int> one may use the following code +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;
@@ -80,13 +84,15 @@ index::rtree< Value, index::quadratic<32, 8> > rt;
 
 
    
 
    
-Values, Indexables and default Translator
    
+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.
+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
      • 
@@ -94,7 +100,7 @@ and they are simply of type adapted to Point or Box concept. Default translator
 
    • Value = BasicValue | BasicValue* | Iterator<BasicValue> | SmartPtr<BasicValue>
      • 
 
    
 
    
-Examples of Value types:
+Examples of Value types:
 
    
 
      
 
    • geometry::model::point<...>
      • 
@@ -107,9 +113,9 @@ Examples of Value types:
 
    
 
    
 
    
-Inserting and splitting algorithms
    
+Inserting and splitting algorithms
    
 
    
-Values may be inserted to the R-tree in many various ways. Final structure of nodes depends
+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.
 
    
@@ -138,7 +144,7 @@ index::rtree< Value, index::rstar<32, 8> > rt;
 
 
    
 
    
-Inserting and removing Values
    
+Inserting and removing Values
    
 
    
 Create
 
    
@@ -168,10 +174,10 @@ index::remove(rt, v);
 
 
    
 
    
-Spatial queries
    
+Spatial queries
    
 
    
 There are three ways to perform a spatial query. Following queries returns
-Values intersecting some box_region.
+Values intersecting some box_region.
 
    
 
      
 
    • 
@@ -204,9 +210,9 @@ BOOST_FOREACH(Value &v, rt | index::query_filtered(box_region))
 
    
 
    
 
    
-Spatial predicates
    
+Spatial predicates
    
 
    
-It is possible to define other relations between queried Values and region/regions
+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.
 
    
 
    @@ -245,7 +251,7 @@ rt.query(
 
    
 
    
 There is special predicate index::value(Fun) taking user-defined function/functor
-which checks if Value should be returned by the query.
+which checks if Value should be returned by the query.
 
    
 
     bool fun(Value const& v)
@@ -264,8 +270,159 @@ rt.query(
 
 
    
 
    
-Nearest neighbor queries
    
-TODO
+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 knn 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/index.xml b/doc/index.xml
index 720454e6a..722e2c286 100644
--- a/doc/index.xml
+++ b/doc/index.xml
@@ -68,10 +68,13 @@ 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.
+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.
+Translator - type of object translating Value objects
+to Indexable objects (Point or Box) which
+R-tree can handle.
 
 Allocator - the allocator.
@@ -79,7 +82,8 @@ rtree<Value, Parameters, Translator, Allocator>
 
 
 
-In order to create a R-tree object storing values of type std::pair<Box, int> one may use the following code
+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;
@@ -91,17 +95,19 @@ 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 Point, Box,
-std::pair<...>, pointer, iterator or smart pointer.
+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:
+Examples of Value types:
 
 geometry::model::point<...>
 geometry::model::point_xy<...>
@@ -114,7 +120,7 @@ Examples of Value types:
 
    
 Inserting and splitting algorithms
 
-Values may be inserted to the R-tree in many various ways. Final structure of nodes depends
+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.
 
@@ -168,7 +174,7 @@ index::remove(rt, v);
 Spatial queries
 
 There are three ways to perform a spatial query. Following queries returns
-Values intersecting some box_region.
+Values intersecting some box_region.
 
 
 Method call
@@ -201,7 +207,7 @@ BOOST_FOREACH(Value &v, rt | index::query_filtered(box_region))
 
    
 Spatial predicates
 
-It is possible to define other relations between queried Values and region/regions
+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
@@ -232,7 +238,7 @@ rt.query(
   , 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.
+which checks if Value should be returned by the query.
 
 bool fun(Value const& v)
 {
@@ -249,8 +255,147 @@ rt.query(
 
    
 
 
    
-Nearest neighbor queries
-TODO
+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 knn 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
+
+
+
    
+