boost/geometry
2
0
Fork 0
mirror of https://github.com/boostorg/geometry.git synced 2026-02-14 00:42:09 +00:00
Code Issues Projects Releases Wiki Activity
Files
379166e1f77c00a135ded5ed5ca20337f13fee07
geometry/doc/html/geometry_index/r_tree/spatial_queries.html
Adam Wulkiewicz 3f1d769d9f Added MultiPolygon spatial query picture to docs. 
Added MultiPolygon query to GLUT Vis.

[SVN r81921]
2012-12-13 22:37:06 +00:00

309 lines
26 KiB
HTML
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Spatial queries</title>
<link rel="stylesheet" href="http://www.boost.org/doc/libs/release/doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.77.1">
<link rel="home" href="../../index.html" title="Chapter&#160;1.&#160;Geometry Index">
<link rel="up" href="../r_tree.html" title="R-tree">
<link rel="prev" href="creation_and_modification.html" title="Creation and modification">
<link rel="next" href="nearest_neighbours_queries.html" title="Nearest neighbours queries">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="http://www.boost.org/doc/libs/release/boost.png"></td>
<td align="center"><a href="http://www.boost.org/doc/libs/release/index.html">Home</a></td>
<td align="center"><a href="http://www.boost.org/doc/libs/release/libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="http://www.boost.org/doc/libs/release/more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="creation_and_modification.html"><img src="http://www.boost.org/doc/libs/release/doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../r_tree.html"><img src="http://www.boost.org/doc/libs/release/doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="http://www.boost.org/doc/libs/release/doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="nearest_neighbours_queries.html"><img src="http://www.boost.org/doc/libs/release/doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="geometry_index.r_tree.spatial_queries"></a><a class="link" href="spatial_queries.html" title="Spatial queries">Spatial queries</a>
</h3></div></div></div>
<div class="toc"><dl>
<dt><span class="section"><a href="spatial_queries.html#geometry_index.r_tree.spatial_queries.basic_queries">Basic
queries</a></span></dt>
<dt><span class="section"><a href="spatial_queries.html#geometry_index.r_tree.spatial_queries.spatial_predicates">Spatial
predicates</a></span></dt>
<dt><span class="section"><a href="spatial_queries.html#geometry_index.r_tree.spatial_queries.connecting_predicates">Connecting
predicates</a></span></dt>
<dt><span class="section"><a href="spatial_queries.html#geometry_index.r_tree.spatial_queries.value_predicate">Value
predicate</a></span></dt>
<dt><span class="section"><a href="spatial_queries.html#geometry_index.r_tree.spatial_queries.inserting_query_results_into_the_other_r_tree">Inserting
query results into the other R-tree</a></span></dt>
</dl></div>
<p>
Spatial queries returns <code class="computeroutput"><span class="identifier">Value</span></code>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 <a href="http://www.boost.org/libs/geometry/doc/html/index.html" target="_top">Boost.Geometry</a>
algorithms. The examples of some basic queries may be found in tables below.
The query region and result <code class="computeroutput"><span class="identifier">Value</span></code>s
are orange.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
intersects(Box) - default
</p>
</th>
<th>
<p>
covered_by(Box)
</p>
</th>
<th>
<p>
disjoint(Box)
</p>
</th>
<th>
<p>
overlaps(Box)
</p>
</th>
<th>
<p>
within(Box)
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/intersects.png" alt="intersects"></span>
</p>
</td>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/within.png" alt="within"></span>
</p>
</td>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/disjoint.png" alt="disjoint"></span>
</p>
</td>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/overlaps.png" alt="overlaps"></span>
</p>
</td>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/within.png" alt="within"></span>
</p>
</td>
</tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
intersects(Ring)
</p>
</th>
<th>
<p>
intersects(Polygon)
</p>
</th>
<th>
<p>
intersects(MultiPolygon)
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/intersects_ring.png" alt="intersects_ring"></span>
</p>
</td>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/intersects_poly.png" alt="intersects_poly"></span>
</p>
</td>
<td>
<p>
<span class="inlinemediaobject"><img src="../../../images/intersects_mpoly.png" alt="intersects_mpoly"></span>
</p>
</td>
</tr></tbody>
</table></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="geometry_index.r_tree.spatial_queries.basic_queries"></a><a class="link" href="spatial_queries.html#geometry_index.r_tree.spatial_queries.basic_queries" title="Basic queries">Basic
queries</a>
</h4></div></div></div>
<p>
There are three ways to perform a spatial query. Following queries returns
<code class="computeroutput">Value</code>s intersecting some region defined as a box in this example.
</p>
<p>
Method call
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span>Value<span class="special">&gt;</span> <span class="identifier">returned_values</span><span class="special">;</span>
<a href="http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_box.html" target="_top">Box</a> <span class="identifier">box_region</span><span class="special">(...);</span>
<span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">box_region</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">returned_values</span><span class="special">));</span>
</pre>
<p>
Function call
</p>
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span>Value<span class="special">&gt;</span> <span class="identifier">returned_values</span><span class="special">;</span>
<a href="http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_box.html" target="_top">Box</a> <span class="identifier">box_region</span><span class="special">(...);</span>
<span class="identifier">index</span><span class="special">::</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">rt</span><span class="special">,</span> <span class="identifier">box_region</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">returned_values</span><span class="special">));</span>
</pre>
<p>
Use of pipe operator generating a range
</p>
<pre class="programlisting"><a href="http://www.boost.org/libs/geometry/doc/html/geometry/reference/concepts/concept_box.html" target="_top">Box</a> <span class="identifier">box_region</span><span class="special">(...);</span>
<span class="identifier">BOOST_FOREACH</span><span class="special">(</span>Value <span class="special">&amp;</span> <span class="identifier">v</span><span class="special">,</span> <span class="identifier">rt</span> <span class="special">|</span> <span class="identifier">index</span><span class="special">::</span><span class="identifier">adaptors</span><span class="special">::</span><span class="identifier">spatial_queried</span><span class="special">(</span><span class="identifier">box_region</span><span class="special">))</span>
<span class="special">;</span> <span class="comment">// do something with v</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="geometry_index.r_tree.spatial_queries.spatial_predicates"></a><a class="link" href="spatial_queries.html#geometry_index.r_tree.spatial_queries.spatial_predicates" title="Spatial predicates">Spatial
predicates</a>
</h4></div></div></div>
<p>
To explicitly define one of the predicates one may pass it to the <code class="computeroutput"><span class="identifier">spatial_query</span><span class="special">()</span></code>
as the first argument.
</p>
<pre class="programlisting"><span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">box</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span> <span class="comment">// default case - intersects</span>
<span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">index</span><span class="special">::</span><span class="identifier">intersects</span><span class="special">(</span><span class="identifier">box</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span> <span class="comment">// the same as default</span>
<span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">index</span><span class="special">::</span><span class="identifier">covered_by</span><span class="special">(</span><span class="identifier">box</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
<span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">index</span><span class="special">::</span><span class="identifier">disjont</span><span class="special">(</span><span class="identifier">box</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
<span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">index</span><span class="special">::</span><span class="identifier">overlaps</span><span class="special">(</span><span class="identifier">box</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
<span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">index</span><span class="special">::</span><span class="identifier">within</span><span class="special">(</span><span class="identifier">box</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
</pre>
<p>
All predicates may be negated, e.g.:
</p>
<pre class="programlisting"><span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(!</span><span class="identifier">index</span><span class="special">::</span><span class="identifier">intersects</span><span class="special">(</span><span class="identifier">box</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
<span class="comment">// the same as</span>
<span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">index</span><span class="special">::</span><span class="identifier">disjoint</span><span class="special">(</span><span class="identifier">box</span><span class="special">),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="geometry_index.r_tree.spatial_queries.connecting_predicates"></a><a class="link" href="spatial_queries.html#geometry_index.r_tree.spatial_queries.connecting_predicates" title="Connecting predicates">Connecting
predicates</a>
</h4></div></div></div>
<p>
It's possible to use some number of predicates in one time by passing
<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">Pred1</span><span class="special">,</span> <span class="identifier">Pred2</span><span class="special">&gt;</span></code>
or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">Pred1</span><span class="special">,</span> <span class="identifier">Pred2</span><span class="special">,</span> <span class="identifier">Pred3</span><span class="special">,</span> <span class="special">...&gt;</span></code>. 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 <code class="computeroutput"><span class="identifier">Value</span></code>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.
</p>
<pre class="programlisting"><span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span>
<span class="identifier">index</span><span class="special">::</span><span class="identifier">intersects</span><span class="special">(</span><span class="identifier">box1</span><span class="special">),</span> <span class="special">!</span><span class="identifier">index</span><span class="special">::</span><span class="identifier">within</span><span class="special">(</span><span class="identifier">box2</span><span class="special">)</span> <span class="special">),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
<span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_tuple</span><span class="special">(</span>
<span class="identifier">index</span><span class="special">::</span><span class="identifier">intersects</span><span class="special">(</span><span class="identifier">box1</span><span class="special">),</span> <span class="special">!</span><span class="identifier">index</span><span class="special">::</span><span class="identifier">within</span><span class="special">(</span><span class="identifier">box2</span><span class="special">),</span> <span class="identifier">index</span><span class="special">::</span><span class="identifier">overlaps</span><span class="special">(</span><span class="identifier">box3</span><span class="special">)</span> <span class="special">),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="geometry_index.r_tree.spatial_queries.value_predicate"></a><a class="link" href="spatial_queries.html#geometry_index.r_tree.spatial_queries.value_predicate" title="Value predicate">Value
predicate</a>
</h4></div></div></div>
<p>
There is also a unique predicate <code class="computeroutput"><span class="identifier">index</span><span class="special">::</span><span class="identifier">value</span><span class="special">(...)</span></code> taking user-defined function/functor
which checks if <code class="computeroutput">Value</code> should be returned by the query.
</p>
<pre class="programlisting"><span class="keyword">bool</span> <span class="identifier">fun</span><span class="special">(</span>Value <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">)</span>
<span class="special">{</span>
<span class="keyword">return</span> <span class="identifier">v</span><span class="special">.</span><span class="identifier">is_red</span><span class="special">();</span>
<span class="special">}</span>
<span class="comment">// ...</span>
<span class="identifier">rt</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span>
<span class="identifier">boost</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span>
<span class="identifier">index</span><span class="special">::</span><span class="identifier">intersects</span><span class="special">(</span><span class="identifier">box</span><span class="special">),</span> <span class="identifier">index</span><span class="special">::</span><span class="identifier">value</span><span class="special">(</span><span class="identifier">fun</span><span class="special">)</span> <span class="special">),</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="geometry_index.r_tree.spatial_queries.inserting_query_results_into_the_other_r_tree"></a><a class="link" href="spatial_queries.html#geometry_index.r_tree.spatial_queries.inserting_query_results_into_the_other_r_tree" title="Inserting query results into the other R-tree">Inserting
query results into the other R-tree</a>
</h4></div></div></div>
<p>
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.
</p>
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">bgi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">geometry</span><span class="special">::</span><span class="identifier">index</span><span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">Box</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&gt;</span> Value<span class="special">;</span>
<span class="keyword">typedef</span> <span class="identifier">bgi</span><span class="special">::</span><span class="identifier">rtree</span><span class="special">&lt;</span> Value<span class="special">,</span> <span class="identifier">bgi</span><span class="special">::</span><span class="identifier">linear</span><span class="special">&lt;</span><span class="number">32</span><span class="special">,</span> <span class="number">8</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">RTree</span><span class="special">;</span>
<span class="identifier">RTree</span> <span class="identifier">rt1</span><span class="special">;</span>
<span class="comment">/* some inserting into the tree */</span>
<span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="identifier">Value</span><span class="special">&gt;</span> <span class="identifier">result</span><span class="special">;</span>
<span class="identifier">rt1</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">Box</span><span class="special">(/*...*/),</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">back_inserter</span><span class="special">(</span><span class="identifier">result</span><span class="special">));</span>
<span class="identifier">RTree</span> <span class="identifier">rt2</span><span class="special">(</span><span class="identifier">result</span><span class="special">.</span><span class="identifier">begin</span><span class="special">(),</span> <span class="identifier">result</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span>
</pre>
<p>
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.
</p>
<pre class="programlisting"><span class="identifier">RTree</span> <span class="identifier">rt3</span><span class="special">;</span>
<span class="identifier">rt1</span><span class="special">.</span><span class="identifier">spatial_query</span><span class="special">(</span><span class="identifier">Box</span><span class="special">(/*...*/),</span> <span class="identifier">bgi</span><span class="special">::</span><span class="identifier">inserter</span><span class="special">(</span><span class="identifier">rt3</span><span class="special">));</span>
</pre>
<p>
If you like Boost.Range you'll appreciate the third option. You may pass
the result Range directly to the constructor.
</p>
<pre class="programlisting"><span class="identifier">RTree</span> <span class="identifier">rt4</span><span class="special">(</span><span class="identifier">rt1</span> <span class="special">|</span> <span class="identifier">bgi</span><span class="special">::</span><span class="identifier">adaptors</span><span class="special">::</span><span class="identifier">spatial_queried</span><span class="special">(</span><span class="identifier">Box</span><span class="special">(/*...*/)));</span>
</pre>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright &#169; 2011, 2012 Adam Wulkiewicz<br>Copyright &#169; 2008 Federico J. Fernandez<p>
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="creation_and_modification.html"><img src="http://www.boost.org/doc/libs/release/doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../r_tree.html"><img src="http://www.boost.org/doc/libs/release/doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="http://www.boost.org/doc/libs/release/doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="nearest_neighbours_queries.html"><img src="http://www.boost.org/doc/libs/release/doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink