]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | // Boost.Geometry (aka GGL, Generic Geometry Library) |
2 | // | |
3 | // Copyright (c) 2007-2012 Barend Gehrels, Amsterdam, the Netherlands. | |
4 | // Copyright (c) 2008-2012 Bruno Lalande, Paris, France. | |
5 | // Use, modification and distribution is subject to the Boost Software License, | |
6 | // Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at | |
7 | // http://www.boost.org/LICENSE_1_0.txt) | |
8 | ||
9 | #ifndef _DOXYGEN_EXAMPLES_HPP | |
10 | #define _DOXYGEN_EXAMPLES_HPP | |
11 | ||
12 | ||
13 | /*! | |
14 | ||
15 | ||
16 | \example 01_point_example.cpp | |
17 | In most cases the documentation gives small examples of how to use the algorithms or classes. | |
18 | The point example is a slightly larger example giving an idea of how to use different | |
19 | algorithms from the library, related to points. It shows | |
20 | - the usage of include files | |
21 | - how to declare points, using different coordinate types | |
22 | - how to construct points, specifying coordinates, initializing to zero or to infinite | |
23 | - how to compare points to each other | |
24 | - how points can be streamed as OGC text | |
25 | - calculating the distance from point to point | |
26 | ||
27 | ||
28 | */ | |
29 | ||
30 | ||
31 | //--------------------------------------------------------------------------------------------------- | |
32 | ||
33 | /*! | |
34 | \example 02_linestring_example.cpp | |
35 | The linestring example shows how linestrings can be declared and used and shows some more algorithms. | |
36 | One of the important concepts of the Generic Geometry Library is that it is totally built upon the standard | |
37 | library, using the standard containers such as std::vector. | |
38 | ||
39 | A linestring is, as explained elsewhere in this documentation, not much more than a vector of points. | |
40 | Most algorithms run on linestrings, but can also run on any iterator pair. And all algorithms | |
41 | on std::vector can be used on geometry::linestring. | |
42 | ||
43 | The sample shows this, shows some algorithms: | |
44 | - geometry::envelope | |
45 | - geometry::length | |
46 | - geometry::distance | |
47 | - geometry::simplify | |
48 | - geometry::for_each | |
49 | - geometry::intersection | |
50 | ||
51 | This documentation illustrates the simplify algorithm and the intersection algorithm with some pictures. | |
52 | ||
53 | The simplify algorithm simplifies a linestring. Simplification means that the less important points | |
54 | are removed from the line and that the points that are most important for the shape of a line are | |
55 | kept. Simplification is done using the well known Douglas Peucker algorithm. The library user can | |
56 | specify the distance or tolerance, which indicates how much the linestring should be simplified. | |
57 | ||
58 | The image below shows the original and simplified linestring: | |
59 | \image html simplify_linestring.png | |
60 | The blue line is the original linestring; the red line is the simplified line which has one point less. | |
61 | In geographical applications simplification can reduce a linestring to its basic form containing only | |
62 | 10% of its original points. | |
63 | ||
64 | The intersection algorithm intersects two geometries which each other, delivering a third geometry. | |
65 | In the case of the example a linestring is intersected with a box. Intersection with a box is often | |
66 | called a clip. The image below illustrates the intersection. | |
67 | \image html clip_linestring.png | |
68 | The yellow line is intersected with the blue box. | |
69 | The intersection result, painted in red, contains three linestrings. | |
70 | */ | |
71 | ||
72 | //--------------------------------------------------------------------------------------------------- | |
73 | ||
74 | /*! | |
75 | \example 03_polygon_example.cpp | |
76 | The polygon example shows some examples of what can be done with polygons in the Generic Geometry Library: | |
77 | * the outer ring and the inner rings | |
78 | * how to calculate the area of a polygon | |
79 | * how to get the centroid, and how to get an often more interesting label point | |
80 | * how to correct the polygon such that it is clockwise and closed | |
81 | * within: the well-known point in polygon algorithm | |
82 | * how to use polygons which use another container, or which use different containers for points and for inner rings | |
83 | * how polygons can be intersected, or clipped, using a clipping box | |
84 | ||
85 | The illustrations below show the usage of the within algorithm and the intersection algorithm. | |
86 | ||
87 | The within algorithm results in true if a point lies completly within a polygon. If it lies exactly | |
88 | on a border it is not considered as within and if it is inside a hole it is also not within the | |
89 | polygon. This is illustrated below, where only the point in the middle is within the polygon. | |
90 | ||
91 | \image html within_polygon.png | |
92 | ||
93 | The clipping algorithm, called intersection, is illustrated below: | |
94 | ||
95 | \image html clip_polygon.png | |
96 | ||
97 | The yellow polygon, containing a hole, is clipped with the blue rectangle, resulting in a | |
98 | multi_polygon of three polygons, drawn in red. The hole is vanished. | |
99 | ||
100 | include polygon_example.cpp | |
101 | */ | |
102 | ||
103 | ||
104 | //--------------------------------------------------------------------------------------------------- | |
105 | /*! | |
106 | \example 06_a_transformation_example.cpp | |
107 | This sample demonstrates the usage of transformations in the Generic Geometry Library. | |
108 | Behind the screens this is done using with the uBLAS matrix/vector library. | |
109 | ||
110 | \example 06_b_transformation_example.cpp | |
111 | ||
112 | */ | |
113 | ||
114 | //--------------------------------------------------------------------------------------------------- | |
115 | ||
116 | /*! | |
117 | \example 07_a_graph_route_example.cpp | |
118 | The graph route example shows how GGL can be combined with Boost.Graph. The sample does the following things: | |
119 | - it reads roads (included in the distribution, stored on disk in the form of a text file containing geometries and names) | |
120 | - it reads cities | |
121 | - it creates a graph from the roads | |
122 | - it connects each city to the nearest vertex in the graph | |
123 | - it calculates the shortest route between each pair of cities | |
124 | - it outputs the distance over the road, and also of the air | |
125 | - it creates an SVG image with the roads, the cities, and the first calculated route | |
126 | ||
127 | Note that this example is useful, but it is only an example. It could be built in many different ways. | |
128 | For example: | |
129 | - the roads/cities could be read from a database using SOCI, or from a shapefile using shapelib | |
130 | - it could support oneway roads and roads on different levels (disconnected bridges) | |
131 | - it currently uses tuples but that could be anything | |
132 | - etc | |
133 | ||
134 | The SVG looks like: | |
135 | \image html 07_graph_route_example_svg.png | |
136 | ||
137 | The output screen looks like: | |
138 | \image html 07_graph_route_example_text.png | |
139 | ||
140 | \example 07_b_graph_route_example.cpp | |
141 | ||
142 | ||
143 | */ | |
144 | ||
145 | ||
146 | //--------------------------------------------------------------------------------------------------- | |
147 | /*! | |
148 | \example c01_custom_point_example.cpp | |
149 | This sample demonstrates that custom points can be made as well. This sample contains many points, derived | |
150 | from boost::tuple, created from scratch, read only points, legacy points, etc. | |
151 | */ | |
152 | ||
153 | //--------------------------------------------------------------------------------------------------- | |
154 | /*! | |
155 | \example c02_custom_box_example.cpp | |
156 | Besides custom points, custom boxes are possible as shown in this example. | |
157 | */ | |
158 | ||
159 | //--------------------------------------------------------------------------------------------------- | |
160 | /* | |
161 | \example c03_custom_linestring_example.cpp | |
162 | GPS tracks are shown in this example: a custom linestring with GPS points | |
163 | */ | |
164 | ||
165 | //--------------------------------------------------------------------------------------------------- | |
166 | /*! | |
167 | \example c04_a_custom_triangle_example.cpp | |
168 | The \b custom triangle \b example goes even further and implements a custom ring, where the area calculation | |
169 | algorithm is optimized for a triangle | |
170 | */ | |
171 | ||
172 | //--------------------------------------------------------------------------------------------------- | |
173 | /*! | |
174 | \example c04_b_custom_triangle_example.cpp | |
175 | This second custom triangle example shows an alternative implementation for a custom shape, showing a | |
176 | partial specialization for the area calculation. | |
177 | */ | |
178 | ||
179 | //--------------------------------------------------------------------------------------------------- | |
180 | /*! | |
181 | \example c05_custom_point_pointer_example.cpp | |
182 | This example shows how GGL can be used to adapt a pointer-to-a-point, used e.g. in a linestring | |
183 | */ | |
184 | ||
185 | //--------------------------------------------------------------------------------------------------- | |
186 | /*! | |
187 | \example c06_custom_polygon_example.cpp | |
188 | Showing a custom polygon (asked on the list during Formal Review) | |
189 | */ | |
190 | ||
191 | ||
192 | ||
193 | //--------------------------------------------------------------------------------------------------- | |
194 | /*! | |
195 | \example x01_qt_example.cpp | |
196 | This sample demonstrates that by usage of concepts, external geometries can be handled | |
197 | by GGL, just calling by a one-line registration macro. In this case for the Qt Widget Library. | |
198 | ||
199 | The example, code shown below, results in this window-output: | |
200 | \image html x01_qt_example_output.png | |
201 | */ | |
202 | ||
203 | ||
204 | ||
205 | ||
206 | ||
207 | //--------------------------------------------------------------------------------------------------- | |
208 | /*! | |
209 | \example x03_a_soci_example.cpp | |
210 | First example showing how to get spatial data from a database using SOCI and put them into GGL | |
211 | */ | |
212 | ||
213 | ||
214 | //--------------------------------------------------------------------------------------------------- | |
215 | /*! | |
216 | \example x03_b_soci_example.cpp | |
217 | Second example showing how to get polygons from a database using SOCI and put them into GGL, using WKT. | |
218 | */ | |
219 | ||
220 | ||
221 | //--------------------------------------------------------------------------------------------------- | |
222 | /* | |
223 | \example x03_c_soci_example.cpp | |
224 | Example showing how to get polygons from PostGIS using SOCI and use them in GGL through WKB | |
225 | */ | |
226 | ||
227 | ||
228 | //--------------------------------------------------------------------------------------------------- | |
229 | /* | |
230 | \example x03_d_soci_example.cpp | |
231 | Example showing how to get polygons from PostGIS using SOCI and use them in GGL through WKB | |
232 | ||
233 | */ | |
234 | ||
235 | #endif // _DOXYGEN_EXAMPLES_HPP |