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 236