| // Boost.Geometry (aka GGL, Generic Geometry Library) |
| // |
| // Copyright (c) 2007-2011 Barend Gehrels, Amsterdam, the Netherlands. |
| // Copyright (c) 2008-2011 Bruno Lalande, Paris, France. |
| // Use, modification and distribution is subject to the Boost Software License, |
| // Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at |
| // http://www.boost.org/LICENSE_1_0.txt) |
| |
| #ifndef _DOXYGEN_EXAMPLES_HPP |
| #define _DOXYGEN_EXAMPLES_HPP |
| |
| |
| /*! |
| |
| |
| \example 01_point_example.cpp |
| In most cases the documentation gives small examples of how to use the algorithms or classes. |
| The point example is a slightly larger example giving an idea of how to use different |
| algorithms from the library, related to points. It shows |
| - the usage of include files |
| - how to declare points, using different coordinate types |
| - how to construct points, specifying coordinates, initializing to zero or to infinite |
| - how to compare points to each other |
| - how points can be streamed as OGC text |
| - calculating the distance from point to point |
| |
| |
| */ |
| |
| |
| //--------------------------------------------------------------------------------------------------- |
| |
| /*! |
| \example 02_linestring_example.cpp |
| The linestring example shows how linestrings can be declared and used and shows some more algorithms. |
| One of the important concepts of the Generic Geometry Library is that it is totally built upon the standard |
| library, using the standard containers such as std::vector. |
| |
| A linestring is, as explained elsewhere in this documentation, not much more than a vector of points. |
| Most algorithms run on linestrings, but can also run on any iterator pair. And all algorithms |
| on std::vector can be used on geometry::linestring. |
| |
| The sample shows this, shows some algorithms: |
| - geometry::envelope |
| - geometry::length |
| - geometry::distance |
| - geometry::simplify |
| - geometry::for_each |
| - geometry::intersection |
| |
| This documentation illustrates the simplify algorithm and the intersection algorithm with some pictures. |
| |
| The simplify algorithm simplifies a linestring. Simplification means that the less important points |
| are removed from the line and that the points that are most important for the shape of a line are |
| kept. Simplification is done using the well known Douglas Peucker algorithm. The library user can |
| specify the distance or tolerance, which indicates how much the linestring should be simplified. |
| |
| The image below shows the original and simplified linestring: |
| \image html simplify_linestring.png |
| The blue line is the original linestring; the red line is the simplified line which has one point less. |
| In geographical applications simplification can reduce a linestring to its basic form containing only |
| 10% of its original points. |
| |
| The intersection algorithm intersects two geometries which each other, delivering a third geometry. |
| In the case of the example a linestring is intersected with a box. Intersection with a box is often |
| called a clip. The image below illustrates the intersection. |
| \image html clip_linestring.png |
| The yellow line is intersected with the blue box. |
| The intersection result, painted in red, contains three linestrings. |
| */ |
| |
| //--------------------------------------------------------------------------------------------------- |
| |
| /*! |
| \example 03_polygon_example.cpp |
| The polygon example shows some examples of what can be done with polygons in the Generic Geometry Library: |
| * the outer ring and the inner rings |
| * how to calculate the area of a polygon |
| * how to get the centroid, and how to get an often more interesting label point |
| * how to correct the polygon such that it is clockwise and closed |
| * within: the well-known point in polygon algorithm |
| * how to use polygons which use another container, or which use different containers for points and for inner rings |
| * how polygons can be intersected, or clipped, using a clipping box |
| |
| The illustrations below show the usage of the within algorithm and the intersection algorithm. |
| |
| The within algorithm results in true if a point lies completly within a polygon. If it lies exactly |
| on a border it is not considered as within and if it is inside a hole it is also not within the |
| polygon. This is illustrated below, where only the point in the middle is within the polygon. |
| |
| \image html within_polygon.png |
| |
| The clipping algorithm, called intersection, is illustrated below: |
| |
| \image html clip_polygon.png |
| |
| The yellow polygon, containing a hole, is clipped with the blue rectangle, resulting in a |
| multi_polygon of three polygons, drawn in red. The hole is vanished. |
| |
| include polygon_example.cpp |
| */ |
| |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example 06_a_transformation_example.cpp |
| This sample demonstrates the usage of transformations in the Generic Geometry Library. |
| Behind the screens this is done using with the uBLAS matrix/vector library. |
| |
| \example 06_b_transformation_example.cpp |
| |
| */ |
| |
| //--------------------------------------------------------------------------------------------------- |
| |
| /*! |
| \example 07_a_graph_route_example.cpp |
| The graph route example shows how GGL can be combined with Boost.Graph. The sample does the following things: |
| - it reads roads (included in the distribution, stored on disk in the form of a text file containing geometries and names) |
| - it reads cities |
| - it creates a graph from the roads |
| - it connects each city to the nearest vertex in the graph |
| - it calculates the shortest route between each pair of cities |
| - it outputs the distance over the road, and also of the air |
| - it creates an SVG image with the roads, the cities, and the first calculated route |
| |
| Note that this example is useful, but it is only an example. It could be built in many different ways. |
| For example: |
| - the roads/cities could be read from a database using SOCI, or from a shapefile using shapelib |
| - it could support oneway roads and roads on different levels (disconnected bridges) |
| - it currently uses tuples but that could be anything |
| - etc |
| |
| The SVG looks like: |
| \image html 07_graph_route_example_svg.png |
| |
| The output screen looks like: |
| \image html 07_graph_route_example_text.png |
| |
| \example 07_b_graph_route_example.cpp |
| |
| |
| */ |
| |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example c01_custom_point_example.cpp |
| This sample demonstrates that custom points can be made as well. This sample contains many points, derived |
| from boost::tuple, created from scratch, read only points, legacy points, etc. |
| */ |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example c02_custom_box_example.cpp |
| Besides custom points, custom boxes are possible as shown in this example. |
| */ |
| |
| //--------------------------------------------------------------------------------------------------- |
| /* |
| \example c03_custom_linestring_example.cpp |
| GPS tracks are shown in this example: a custom linestring with GPS points |
| */ |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example c04_a_custom_triangle_example.cpp |
| The \b custom triangle \b example goes even further and implements a custom ring, where the area calculation |
| algorithm is optimized for a triangle |
| */ |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example c04_b_custom_triangle_example.cpp |
| This second custom triangle example shows an alternative implementation for a custom shape, showing a |
| partial specialization for the area calculation. |
| */ |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example c05_custom_point_pointer_example.cpp |
| This example shows how GGL can be used to adapt a pointer-to-a-point, used e.g. in a linestring |
| */ |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example c06_custom_polygon_example.cpp |
| Showing a custom polygon (asked on the list during Formal Review) |
| */ |
| |
| |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example x01_qt_example.cpp |
| This sample demonstrates that by usage of concepts, external geometries can be handled |
| by GGL, just calling by a one-line registration macro. In this case for the Qt Widget Library. |
| |
| The example, code shown below, results in this window-output: |
| \image html x01_qt_example_output.png |
| */ |
| |
| |
| |
| |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example x03_a_soci_example.cpp |
| First example showing how to get spatial data from a database using SOCI and put them into GGL |
| */ |
| |
| |
| //--------------------------------------------------------------------------------------------------- |
| /*! |
| \example x03_b_soci_example.cpp |
| Second example showing how to get polygons from a database using SOCI and put them into GGL, using WKT. |
| */ |
| |
| |
| //--------------------------------------------------------------------------------------------------- |
| /* |
| \example x03_c_soci_example.cpp |
| Example showing how to get polygons from PostGIS using SOCI and use them in GGL through WKB |
| */ |
| |
| |
| //--------------------------------------------------------------------------------------------------- |
| /* |
| \example x03_d_soci_example.cpp |
| Example showing how to get polygons from PostGIS using SOCI and use them in GGL through WKB |
| |
| */ |
| |
| #endif // _DOXYGEN_EXAMPLES_HPP |