ceph/src/boost/libs/geometry/doc/quickstart.qbk

   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]