]>
Commit | Line | Data |
---|---|---|
1 | [/============================================================================ | |
2 | Boost.Geometry (aka GGL, Generic Geometry Library) | |
3 | ||
4 | Copyright (c) 2009-2012 Barend Gehrels, Amsterdam, the Netherlands. | |
5 | Copyright (c) 2009-2012 Mateusz Loskot, London, UK. | |
6 | Copyright (c) 2009-2012 Bruno Lalande, Paris, France. | |
7 | ||
8 | Use, modification and distribution is subject to the Boost Software License, | |
9 | Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at | |
10 | http://www.boost.org/LICENSE_1_0.txt) | |
11 | =============================================================================/] | |
12 | ||
13 | [section:quickstart Quick Start] | |
14 | ||
15 | This Quick Start section shows some of the features of __boost_geometry__ | |
16 | in the form of annotated, relatively simple, code snippets. | |
17 | ||
18 | The code below assumes that `boost/geometry.hpp` is included, and that `namespace | |
19 | boost::geometry` is used. __boost_geometry__ is header only, so including | |
20 | headerfiles is enough. There is no linking with any library necessary. | |
21 | ||
22 | [quickstart_include] | |
23 | ||
24 | [h3 Cartesian] | |
25 | ||
26 | It is possible to use only a small part of the library. For example: the | |
27 | distance between two points is a common use case. __boost_geometry__ can calculate | |
28 | it from various types. Using one of its own types: | |
29 | ||
30 | [quickstart_distance] | |
31 | ||
32 | If the right headers are included and the types are bound to a coordinate | |
33 | system, various other types can be used as points: plain C array's, __boost_array__'s, | |
34 | __boost_tuple__'s, __boost_fusion__ imported structs, your own classes... | |
35 | ||
36 | Registering and using a C array: | |
37 | [quickstart_register_c_array] | |
38 | [quickstart_distance_c_array] | |
39 | ||
40 | Another often used algorithm is point-in-polygon. It is implemented in __boost_geometry__ | |
41 | under the name `within`. We show its usage here checking a __boost_tuple__ (as a point) | |
42 | located within a polygon, filled with C Array point pairs. | |
43 | ||
44 | But it is first necessary to register a __boost_tuple__, like the C array: | |
45 | [quickstart_register_boost_tuple] | |
46 | [quickstart_point_in_polygon] | |
47 | ||
48 | We can calculate the area of a polygon: | |
49 | [quickstart_area] | |
50 | ||
51 | By the nature of a template library, it is possible to mix point types. | |
52 | We calculate distance again, now using a C array point and a __boost_tuple__ point: | |
53 | [quickstart_distance_mixed] | |
54 | ||
55 | The snippets listed above generate the following output: | |
56 | ||
57 | [pre | |
58 | Distance p1-p2 is: 1.41421 | |
59 | Distance a-b is: 2.23607 | |
60 | Point p is in polygon? true | |
61 | Area: 3.015 | |
62 | Distance a-p is: 2.87924 | |
63 | ] | |
64 | ||
65 | ||
66 | [h3 Non-Cartesian] | |
67 | ||
68 | It is also possible to use non-Cartesian points. For example: points on a sphere. | |
69 | When then an algorithm such as distance is used the library "inspects" that it | |
70 | is handling spherical points and calculates the distance over the sphere, | |
71 | instead of applying the Pythagorean theorem. | |
72 | ||
73 | [note __boost_geometry__ supports a geographical coordinate system, but that is | |
74 | in an extension and not released in the current Boost release.] | |
75 | ||
76 | We approximate the Earth as a sphere and calculate the distance between Amsterdam | |
77 | and Paris: | |
78 | [quick_start_spherical] | |
79 | ||
80 | It writes: [pre Distance in miles: 267.02] | |
81 | ||
82 | [h3 Adapted structs] | |
83 | ||
84 | Finally an example from a totally different domain: developing window-based | |
85 | applications, for example using QtWidgets. As soon as Qt classes are registered | |
86 | in __boost_geometry__ we can use them. We can, for example, check if two | |
87 | rectangles overlap and if so, move the second one to another place: | |
88 | ||
89 | [quickstart_qt] | |
90 | ||
91 | ||
92 | [h3 More] | |
93 | In the reference many more examples can be found. | |
94 | ||
95 | [endsect] |