]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/============================================================================ |
2 | Boost.Geometry Index | |
3 | ||
4 | Copyright (c) 2011-2013 Adam Wulkiewicz. | |
5 | ||
6 | Use, modification and distribution is subject to the Boost Software License, | |
7 | Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at | |
8 | http://www.boost.org/LICENSE_1_0.txt) | |
9 | =============================================================================/] | |
10 | ||
11 | [section Experimental Features] | |
12 | ||
13 | This section describes experimental features which are implemented but unavailable by default. | |
14 | Be aware that they may not be released in the future or functionalities may be released but | |
15 | behind different interface. | |
16 | ||
17 | To enable them one must define `BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL` in compiler's command line or before | |
18 | including spatial index. | |
19 | ||
20 | [heading Nearest query distance calculation] | |
21 | ||
22 | It is possible to define how distance to the non-point `__value__` should be calculated. To do this one may pass | |
23 | a relation object instead of a Point to the nearest predicate, as follows: | |
24 | ||
25 | /* calculate distance to the Indexables' nearest points */ | |
26 | rtree.query(index::nearest(index::to_nearest(pt), k), std::back_inserter(returned_values)); // same as default | |
27 | ||
28 | /* calculate distance to the Indexables' centroid */ | |
29 | rtree.query(index::nearest(index::to_centroid(pt), k), std::back_inserter(returned_values)); | |
30 | ||
31 | /* calculate distance to the Indexables' furthest points */ | |
32 | rtree.query(index::nearest(index::to_furthest(pt), k), std::back_inserter(returned_values)); | |
33 | ||
34 | [heading Path query] | |
35 | ||
36 | Path query returns `k` first `__value__`s intersecting a path defined by a `Segment` or a`Linestring`. The result of a query returning first 5 | |
37 | values intersecting a path is presented below. Path's flow is denoted by blue arrows, returned values are orange. | |
38 | ||
39 | [$img/index/rtree/path.png] | |
40 | ||
41 | To perform this query one may pass a `path()` predicate taking a `Segment` or a `Linestring` and maximum number of `__value__`s which | |
42 | should be returned: | |
43 | ||
44 | rtree.query(index::path(segment, k), std::back_inserter(returned_values)); | |
45 | rtree.query(index::path(linestring, k), std::back_inserter(returned_values)); | |
46 | ||
47 | [warning Only one distance predicate may be used in a query. This means that there can be only one `nearest()` or `path()` predicate passed. Passing more of them will result in compile-time error.] | |
48 | ||
49 | [heading Incremental queries] | |
50 | ||
51 | Sometimes there is a need to stop querying at some desired moment because for example the decision that query should find another value | |
52 | is made after analysis of previously returned values. There can also be desirable to pause querying and resume it later. | |
53 | ||
54 | Currently, those kind of incremental queries are implemented as input (single pass) const iterators, relatively | |
55 | big fat-iterators storing stack used in the tree-traversing process. Because the type of predicates passed | |
56 | to the query varies, the type of the iterator varies as well. | |
57 | ||
58 | Therefore to use query iterators one must pass them to some function template, then types will be deduced | |
59 | automatically. If iterators objects must be stored one may use Boost.Typeof library to retrieve a type from | |
60 | an expression or use C++11 `auto` or `decltype`. | |
61 | ||
62 | /* function call */ | |
63 | std::copy(rtree.qbegin(index::intersects(box)), rtree.qend(index::intersects(box)), std::back_inserter(returned_values)); | |
64 | ||
65 | /* Boost.Typeof */ | |
66 | typedef BOOST_TYPEOF(rtree.qbegin(index::nearest(pt, 5))) const_query_iterator; | |
67 | const_query_iterator first = rtree.qbegin(index::nearest(pt, 5)); | |
68 | const_query_iterator last = rtree.qend(index::nearest(pt, 5)); | |
69 | // ... | |
70 | for ( ; first != last ; ++first ) | |
71 | *first; // do something with Value | |
72 | ||
73 | /* C++11 */ | |
74 | auto first = rtree.qbegin(index::nearest(pt, 5)); | |
75 | auto last = rtree.qend(index::nearest(pt, 5)); | |
76 | // ... | |
77 | for ( ; first != last ; ++first ) | |
78 | *first; // do something with Value | |
79 | ||
80 | `qend()` method is overloaded to return a different, lighter type of iterator which may be compared | |
81 | with query iterator to check if the querying was finished. But since it has different type than the one returned by | |
82 | `qbegin(Pred)` it can't be used with STL-like functions like `std::copy()` which expect that `first` and `last` | |
83 | iterators have the same type. | |
84 | ||
85 | /* function call */ | |
86 | template <typename First, typename Last, typename Out> | |
87 | void my_copy(First first, Last last, Out out) | |
88 | { | |
89 | for ( ; first != last ; ++out, ++first ) | |
90 | *out = *first; | |
91 | } | |
92 | // ... | |
93 | my_copy(rtree.qbegin(index::intersects(box)), rtree.qend(), std::back_inserter(returned_values)); | |
94 | ||
95 | /* Boost.Typeof */ | |
96 | typedef BOOST_TYPEOF(rtree.qbegin(index::nearest(pt, 5))) const_query_iterator; | |
97 | typedef BOOST_TYPEOF(rtree.qend()) end_iterator; | |
98 | const_query_iterator first = rtree.qbegin(index::nearest(pt, 5)); | |
99 | end_iterator last = rtree.qend(); | |
100 | // ... | |
101 | for ( ; first != last ; ++first ) | |
102 | *first; // do something with Value | |
103 | ||
104 | /* C++11 */ | |
105 | auto first = rtree.qbegin(index::nearest(pt, 5)); | |
106 | auto last = rtree.qend(); | |
107 | // ... | |
108 | for ( ; first != last ; ++first ) | |
109 | *first; // do something with Value | |
110 | ||
111 | [endsect] [/ Experimental features /] |