libs/geometry/doc/html/geometry/quickstart.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Quick Start</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Geometry">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Geometry">
   9 <link rel="prev" href="design.html" title="Design Rationale">
  10 <link rel="next" href="spatial_indexes.html" title="Spatial Indexes">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="design.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="spatial_indexes.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="geometry.quickstart"></a><a class="link" href="quickstart.html" title="Quick Start">Quick Start</a>
  28 </h2></div></div></div>
  29 <p>
  30       This Quick Start section shows some of the features of Boost.Geometry in the
  31       form of annotated, relatively simple, code snippets.
  32     </p>
  33 <p>
  34       The code below assumes that <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">.</span><span class="identifier">hpp</span></code> is included,
  35       and that <code class="computeroutput"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">geometry</span></code>
  36       is used. Boost.Geometry is header only, so including headerfiles is enough.
  37       There is no linking with any library necessary.
  38     </p>
  39 <p>
  40 </p>
  41 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  42 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">/</span><span class="identifier">geometries</span><span class="special">/</span><span class="identifier">point_xy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  43 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">/</span><span class="identifier">geometries</span><span class="special">/</span><span class="identifier">polygon</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  44
  45 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">geometry</span><span class="special">;</span>
  46 </pre>
  47 <p>
  48     </p>
  49 <h4>
  50 <a name="geometry.quickstart.h0"></a>
  51       <span class="phrase"><a name="geometry.quickstart.cartesian"></a></span><a class="link" href="quickstart.html#geometry.quickstart.cartesian">Cartesian</a>
  52     </h4>
  53 <p>
  54       It is possible to use only a small part of the library. For example: the distance
  55       between two points is a common use case. Boost.Geometry can calculate it from
  56       various types. Using one of its own types:
  57     </p>
  58 <p>
  59 </p>
  60 <pre class="programlisting"><span class="identifier">model</span><span class="special">::</span><span class="identifier">d2</span><span class="special">::</span><span class="identifier">point_xy</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">p1</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="number">1</span><span class="special">),</span> <span class="identifier">p2</span><span class="special">(</span><span class="number">2</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span>
  61 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Distance p1-p2 is: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">distance</span><span class="special">(</span><span class="identifier">p1</span><span class="special">,</span> <span class="identifier">p2</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  62 </pre>
  63 <p>
  64     </p>
  65 <p>
  66       If the right headers are included and the types are bound to a coordinate system,
  67       various other types can be used as points: plain C array's, Boost.Array's,
  68       Boost.Tuple's, Boost.Fusion imported structs, your own classes...
  69     </p>
  70 <p>
  71       Registering and using a C array:
  72     </p>
  73 <p>
  74 </p>
  75 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">/</span><span class="identifier">geometries</span><span class="special">/</span><span class="identifier">adapted</span><span class="special">/</span><span class="identifier">c_array</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  76
  77 <span class="identifier">BOOST_GEOMETRY_REGISTER_C_ARRAY_CS</span><span class="special">(</span><span class="identifier">cs</span><span class="special">::</span><span class="identifier">cartesian</span><span class="special">)</span>
  78 </pre>
  79 <p>
  80     </p>
  81 <p>
  82 </p>
  83 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">a</span><span class="special">[</span><span class="number">2</span><span class="special">]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">1</span><span class="special">};</span>
  84 <span class="keyword">int</span> <span class="identifier">b</span><span class="special">[</span><span class="number">2</span><span class="special">]</span> <span class="special">=</span> <span class="special">{</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">};</span>
  85 <span class="keyword">double</span> <span class="identifier">d</span> <span class="special">=</span> <span class="identifier">distance</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">);</span>
  86 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Distance a-b is: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">d</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
  87 </pre>
  88 <p>
  89     </p>
  90 <p>
  91       Another often used algorithm is point-in-polygon. It is implemented in Boost.Geometry
  92       under the name <code class="computeroutput"><span class="identifier">within</span></code>. We show
  93       its usage here checking a Boost.Tuple (as a point) located within a polygon,
  94       filled with C Array point pairs.
  95     </p>
  96 <p>
  97       But it is first necessary to register a Boost.Tuple, like the C array:
  98     </p>
  99 <p>
 100 </p>
 101 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">geometry</span><span class="special">/</span><span class="identifier">geometries</span><span class="special">/</span><span class="identifier">adapted</span><span class="special">/</span><span class="identifier">boost_tuple</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 102
 103 <span class="identifier">BOOST_GEOMETRY_REGISTER_BOOST_TUPLE_CS</span><span class="special">(</span><span class="identifier">cs</span><span class="special">::</span><span class="identifier">cartesian</span><span class="special">)</span>
 104 </pre>
 105 <p>
 106     </p>
 107 <p>
 108 </p>
 109 <pre class="programlisting"><span class="keyword">double</span> <span class="identifier">points</span><span class="special">[][</span><span class="number">2</span><span class="special">]</span> <span class="special">=</span> <span class="special">{{</span><span class="number">2.0</span><span class="special">,</span> <span class="number">1.3</span><span class="special">},</span> <span class="special">{</span><span class="number">4.1</span><span class="special">,</span> <span class="number">3.0</span><span class="special">},</span> <span class="special">{</span><span class="number">5.3</span><span class="special">,</span> <span class="number">2.6</span><span class="special">},</span> <span class="special">{</span><span class="number">2.9</span><span class="special">,</span> <span class="number">0.7</span><span class="special">},</span> <span class="special">{</span><span class="number">2.0</span><span class="special">,</span> <span class="number">1.3</span><span class="special">}};</span>
 110 <span class="identifier">model</span><span class="special">::</span><span class="identifier">polygon</span><span class="special">&lt;</span><span class="identifier">model</span><span class="special">::</span><span class="identifier">d2</span><span class="special">::</span><span class="identifier">point_xy</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="identifier">poly</span><span class="special">;</span>
 111 <span class="identifier">append</span><span class="special">(</span><span class="identifier">poly</span><span class="special">,</span> <span class="identifier">points</span><span class="special">);</span>
 112 <span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&gt;</span> <span class="identifier">p</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="number">3.7</span><span class="special">,</span> <span class="number">2.0</span><span class="special">);</span>
 113 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Point p is in polygon? "</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">boolalpha</span> <span class="special">&lt;&lt;</span> <span class="identifier">within</span><span class="special">(</span><span class="identifier">p</span><span class="special">,</span> <span class="identifier">poly</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 114 </pre>
 115 <p>
 116     </p>
 117 <p>
 118       We can calculate the area of a polygon:
 119     </p>
 120 <p>
 121 </p>
 122 <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Area: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">area</span><span class="special">(</span><span class="identifier">poly</span><span class="special">)</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 123 </pre>
 124 <p>
 125     </p>
 126 <p>
 127       By the nature of a template library, it is possible to mix point types. We
 128       calculate distance again, now using a C array point and a Boost.Tuple point:
 129     </p>
 130 <p>
 131 </p>
 132 <pre class="programlisting"><span class="keyword">double</span> <span class="identifier">d2</span> <span class="special">=</span> <span class="identifier">distance</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">p</span><span class="special">);</span>
 133 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Distance a-p is: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">d2</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 134 </pre>
 135 <p>
 136     </p>
 137 <p>
 138       The snippets listed above generate the following output:
 139     </p>
 140 <pre class="programlisting">Distance p1-p2 is: 1.41421
 141 Distance a-b is: 2.23607
 142 Point p is in polygon? true
 143 Area: 3.015
 144 Distance a-p is: 2.87924
 145 </pre>
 146 <h4>
 147 <a name="geometry.quickstart.h1"></a>
 148       <span class="phrase"><a name="geometry.quickstart.non_cartesian"></a></span><a class="link" href="quickstart.html#geometry.quickstart.non_cartesian">Non-Cartesian</a>
 149     </h4>
 150 <p>
 151       It is also possible to use non-Cartesian points. For example: points on a sphere.
 152       When then an algorithm such as distance is used the library "inspects"
 153       that it is handling spherical points and calculates the distance over the sphere,
 154       instead of applying the Pythagorean theorem.
 155     </p>
 156 <div class="note"><table border="0" summary="Note">
 157 <tr>
 158 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../doc/src/images/note.png"></td>
 159 <th align="left">Note</th>
 160 </tr>
 161 <tr><td align="left" valign="top"><p>
 162         Boost.Geometry supports a geographical coordinate system, but that is in
 163         an extension and not released in the current Boost release.
 164       </p></td></tr>
 165 </table></div>
 166 <p>
 167       We approximate the Earth as a sphere and calculate the distance between Amsterdam
 168       and Paris:
 169     </p>
 170 <p>
 171 </p>
 172 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">geometry</span><span class="special">::</span><span class="identifier">model</span><span class="special">::</span><span class="identifier">point</span>
 173     <span class="special">&lt;</span>
 174         <span class="keyword">double</span><span class="special">,</span> <span class="number">2</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">cs</span><span class="special">::</span><span class="identifier">spherical_equatorial</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">geometry</span><span class="special">::</span><span class="identifier">degree</span><span class="special">&gt;</span>
 175     <span class="special">&gt;</span> <span class="identifier">spherical_point</span><span class="special">;</span>
 176
 177 <span class="identifier">spherical_point</span> <span class="identifier">amsterdam</span><span class="special">(</span><span class="number">4.90</span><span class="special">,</span> <span class="number">52.37</span><span class="special">);</span>
 178 <span class="identifier">spherical_point</span> <span class="identifier">paris</span><span class="special">(</span><span class="number">2.35</span><span class="special">,</span> <span class="number">48.86</span><span class="special">);</span>
 179
 180 <span class="keyword">double</span> <span class="keyword">const</span> <span class="identifier">earth_radius</span> <span class="special">=</span> <span class="number">3959</span><span class="special">;</span> <span class="comment">// miles</span>
 181 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"Distance in miles: "</span> <span class="special">&lt;&lt;</span> <span class="identifier">distance</span><span class="special">(</span><span class="identifier">amsterdam</span><span class="special">,</span> <span class="identifier">paris</span><span class="special">)</span> <span class="special">*</span> <span class="identifier">earth_radius</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
 182 </pre>
 183 <p>
 184     </p>
 185 <p>
 186       It writes:
 187     </p>
 188 <pre class="programlisting">Distance in miles: 267.02</pre>
 189 <h4>
 190 <a name="geometry.quickstart.h2"></a>
 191       <span class="phrase"><a name="geometry.quickstart.adapted_structs"></a></span><a class="link" href="quickstart.html#geometry.quickstart.adapted_structs">Adapted
 192       structs</a>
 193     </h4>
 194 <p>
 195       Finally an example from a totally different domain: developing window-based
 196       applications, for example using QtWidgets. As soon as Qt classes are registered
 197       in Boost.Geometry we can use them. We can, for example, check if two rectangles
 198       overlap and if so, move the second one to another place:
 199     </p>
 200 <p>
 201 </p>
 202 <pre class="programlisting"><span class="identifier">QRect</span> <span class="identifier">r1</span><span class="special">(</span><span class="number">100</span><span class="special">,</span> <span class="number">200</span><span class="special">,</span> <span class="number">15</span><span class="special">,</span> <span class="number">15</span><span class="special">);</span>
 203 <span class="identifier">QRect</span> <span class="identifier">r2</span><span class="special">(</span><span class="number">110</span><span class="special">,</span> <span class="number">210</span><span class="special">,</span> <span class="number">20</span><span class="special">,</span> <span class="number">20</span><span class="special">);</span>
 204 <span class="keyword">if</span> <span class="special">(</span><span class="identifier">overlaps</span><span class="special">(</span><span class="identifier">r1</span><span class="special">,</span> <span class="identifier">r2</span><span class="special">))</span>
 205 <span class="special">{</span>
 206     <span class="identifier">assign_values</span><span class="special">(</span><span class="identifier">r2</span><span class="special">,</span> <span class="number">200</span><span class="special">,</span> <span class="number">300</span><span class="special">,</span> <span class="number">220</span><span class="special">,</span> <span class="number">320</span><span class="special">);</span>
 207 <span class="special">}</span>
 208 </pre>
 209 <p>
 210     </p>
 211 <h4>
 212 <a name="geometry.quickstart.h3"></a>
 213       <span class="phrase"><a name="geometry.quickstart.more"></a></span><a class="link" href="quickstart.html#geometry.quickstart.more">More</a>
 214     </h4>
 215 <p>
 216       In the reference many more examples can be found.
 217     </p>
 218 </div>
 219 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 220 <td align="left"></td>
 221 <td align="right"><div class="copyright-footer">Copyright &#169; 2009-2014 Barend Gehrels, Bruno Lalande, Mateusz Loskot, Adam
 222       Wulkiewicz, Oracle and/or its affiliates<p>
 223         Distributed under the Boost Software License, Version 1.0. (See accompanying
 224         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>)
 225       </p>
 226 </div></td>
 227 </tr></table>
 228 <hr>
 229 <div class="spirit-nav">
 230 <a accesskey="p" href="design.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="spatial_indexes.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 231 </div>
 232 </body>
 233 </html>