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_PAGES_HPP 10 #define _DOXYGEN_PAGES_HPP 11 12 13 //--------------------------------------------------------------------------------------------------- 14 15 /*! 16 \page compat Relation to Boost and std libraries 17 18 \section boost_compat Boost 19 20 The GGL makes use of the following Boost Libraries: 21 - Boost Range 22 - Boost Type Traits (e.g. remove_const) 23 - Boost Concept Check Library 24 - Boost Numeric Conversion (cast, bounds) 25 - Boost MPL 26 - Boost Static Assert 27 - Boost Iterator 28 - Boost Smart Pointer (shared_ptr, in the extensions spatial index and projections) 29 - Boost uBLAS 30 - Adapted geometries: 31 - Boost Array 32 - Boost Tuple 33 - IO and parsing 34 - Boost Tokenizer 35 - Boost Conversion (lexical cast) 36 - Boost String Algo 37 - Testing 38 - Boost Test 39 - Boost Timer 40 - Examples 41 - Boost Graph Library 42 43 44 Many of these are used a lot inside the library. 45 46 The \b Boost.Range library is used everywhere 47 to declare iterators and to walk through standard containers or custom ranges. 48 49 The \b Boost \b Concept \b Check \b Library is used to check concepts, for geometries as well 50 as for strategies. 51 52 Tranformations are implemented using \b Boost uBLAS 53 54 \b MPL is used for a.o. reverse dispatching 55 56 Finally, the library can perfectly be used together with the \b Boost \b Graph \b Library, as shown in example 7. 57 58 59 \section std_compat std:: library 60 61 62 The GGL makes substantial use of the std library, and is designed to be compatible with it. 63 - provided geometries (linestring, ring, polygon, multi-s) make default use of std::vector (but that is configurable) 64 - std sorting, unique copies, maps can make use of provided functors in compare "compare". 65 - internally, there are vector's, deque's, there is sorting, many things are implemented using the std library 66 67 */ 68 69 70 71 //--------------------------------------------------------------------------------------------------- 72 73 /*! 74 \page compiling Compiling 75 76 \section compiling_intro Compiling Boost.Geometry 77 78 Boost.Geometry is a Header Only library. So just including the headerfiles is enough 79 to use the algorithms. Nothing has to be linked. 80 81 Boost.Geometry is only dependant on (header only) Boost libraries. Download the Boost 82 Library Collection from www.boost.org, adapt the include path to include Boost. 83 84 \section platforms Platforms 85 86 The library currently compiles successfully on the following platforms: 87 - MS Visual Studio 2008 (Express Edition) 88 - MS Visual Studio 2005 (Express Edition) 89 - gcc version 3.4 90 - gcc version 4 (tested are 4.1, 4.2, 4.4) 91 92 For Visual Studio, the examples contains some project files (for 2005). However, because the library 93 is header only, it will be no problem to integrate it in your own project files. 94 95 The test and example folders contain also Jam-files for bjam / boost-build 96 97 For gcc, the flag -Wno-long-long can be used (surpressing warnings originating from Boost) 98 99 \section convenient_includes Convenient includes 100 101 This section concentrates on how to include GGL. 102 103 The most convenient headerfile including all algorithms and strategies is geometry.hpp: 104 - \#include <boost/geometry/geometry.hpp> It is recommended to include this file. 105 Alternatively, it is possible to include GGL headerfiles separately. However, this is inconvenient as files might 106 be renamed or moved occasionaly. 107 108 109 An often used headerfile is geometries.hpp: 110 - \#include <boost/geometry/geometries/geometries.hpp> This includes all default geometries: point, linestring, 111 polygon, linear_ring, box. It is not included in the "geometry.hpp" headerfile because 112 users are allowed to use their own geometries. However, for library users who want to use the provided 113 geometries it is most useful. 114 115 116 For users using only Cartesian points, with floating point coordinates (double), in 2D or 3D, you can use instead: 117 - \#include <boost/geometry/geometries/cartesian2d.hpp> This includes all 2D Cartesian geometries: point_2d, linestring_2d, 118 etc. Using this headerfile the library seems to be a non-template library, so it is convenient for users that 119 are not so into the template world. 120 121 \section advanced_includes Advanced includes 122 123 This section is for users who have their own geometries and want to use algorithms from the Boost.Geometry. 124 125 126 If you want to use your own points it makes sense to use the registration macro's: 127 - \#include <boost/geometry/geometries/register/point.hpp> macro's for point registration 128 - \#include <boost/geometry/geometries/register/box.hpp> macro's for box registration 129 130 131 132 133 \section extension_includes Extensions 134 The GGL is currently (since 0.5) split into the kernel and several extensions. As this split is relatively new, 135 there are not yet umbrella-include files, but most things below will do: 136 137 If you want to use the \b geographic coordinate system: 138 - the tag is already included in the kernel 139 - \#include <boost/geometry/extensions/gis/geographic/strategies/andoyer.hpp> for Andoyer distance calculations 140 - \#include <boost/geometry/extensions/gis/geographic/strategies/vincenty.hpp> for Vincenty distance calculations 141 142 If you want to use the \b projections: 143 - \#include <boost/geometry/extensions/gis/projections/parameters.hpp> 144 - \#include <boost/geometry/extensions/gis/projections/projection.hpp> 145 - \#include <boost/geometry/extensions/gis/projections/factory.hpp> 146 147 If you want to use the \b circle (n-sphere) 148 - \#include <boost/geometry/extensions/nsphere/...> <i>Several headerfiles, there is not yet a common include</i> 149 150 151 152 \section performance Performance finetuning 153 The enumeration below is not exhaustive but can contain hints to improve the performance 154 - For Microsoft, set the define _SECURE_SCL=0 155 - For Microsoft, set the define _HAS_ITERATOR_DEBUGGING=0 156 - our measurements indicate that MSVC 2005 generates faster code than MSVC 2008 157 - Using StlPort results in significant faster code than Microsoft's standard library 158 - Of course turn on compiler optimizations, compile in release mode 159 160 \section intellisense Intellisense issues 161 Microsoft Visual Studio (Express) 2005 and 2008 can hang typing in a bracket or angle bracket. 162 This is not directly related to GGL, but caused by heavy templated libraries such as Boost and GGL. 163 If this is inconvenient, intellisense can easily be turned off: 164 165 <i>(...) disabling Intellisense in VC++. 166 There is a file called feacp.dll in <VS8INSTALL>/VC/vcpackages folder. 167 Renaming this file will disable Intellisense feature.</i> 168 169 Source: http://blogs.msdn.com/yash/archive/2007/09/19/intellisense-issues-in-visual-c-2005.aspx 170 171 172 */ 173 174 175 176 177 //--------------------------------------------------------------------------------------------------- 178 179 /*! 180 \page performance Performance 181 182 The performance has been tested for some algorithms, concluding that Boost.Geometry is highly comparative 183 (http://trac.osgeo.org/ggl/wiki/Performance). 184 185 \section performance-notes Performance notes 186 In the page about compiling the library there are some hints provided which might improve the performance. 187 188 Furthermore it is important to realize that if you're about to do calculations with two geometries, for 189 example a point-in-polygon or an intersection, it is very useful to first calculate and store all bounding 190 boxes (envelopes), and then before doing a point-in-polygon check if the point is in the bounding box. Checking if a 191 point is within a box is of course much faster than visiting all vertices of a polygon. 192 193 The storage of bounding boxes is, on purpose, not done within the library because it would break the possibility 194 to use standard vectors of points for linestrings or rings. The library might get a traits system in the future 195 where geometries might tell their boundaries to the algorithms, this however would be an optional system. 196 */ 197 198 199 200 201 202 //--------------------------------------------------------------------------------------------------- 203 204 /*! 205 \page DSV DSV (Delimiter Separated Values) 206 DSV is a text representation of a geometry, explained here: http://en.wikipedia.org/wiki/Delimiter-separated_values . 207 DSV can represent a point, a linestring, a polygon, or multi versions of those. 208 209 It is currently just a utility in the library, used in samples and tests, to get some textual output 210 of a geometry. 211 212 */ 213 214 // BSG 24-12-2010: re-added to silence Doxygen warnings: 215 /*! 216 \page WKT WKT (Well-Known Text) 217 WKT is a textual representation of a geometry, explained here: http://en.wikipedia.org/wiki/Well-known_text 218 WKT can represent a point, a linestring, a polygon, or multi versions of those. 219 220 It is currently just a utility in the library, used in samples and tests, to get some textual output 221 of a geometry. 222 223 */ 224 225 //--------------------------------------------------------------------------------------------------- 226 227 228 /*! 229 \page OGC OGC (Open Geospatial Consortium) 230 OGC is the Open Geospatial Consortium, the standardization committee 231 on Geospatial Interoperability and GIS (Geographical Information Systems). 232 OGC geometries are used in many environments and databases. 233 234 The Generic Geometry Library uses OGC conventions 235 for algorithms and for geometry type names. Note that though OGC is concentrating on GIS, 236 the conventions followed here are 'geometry only', the so-called 'simple features' 237 (simple in the sense that polygons are not allowed to have self-intersections). 238 239 OGC specifies a library based on inheritance, as opposed to this library, which is a generic template based library 240 where data classes are separated from the algorithms. 241 Therefore this library is not an OGC implementation in the strict sense. 242 243 \section Classes 244 OGC defines the following geometry classes, 245 which are implemented as concepts (and as geometries) in the Generic Geometry Library: 246 - \ref boost::geometry::model::point "point": a point. The point defined here is dimensionally agnostic. 247 Library users does not have to use this point, they might also use their own points as long as it meets the concepts. 248 - \ref boost::geometry::model::linestring "linestring": Sequence of point values with linear interpolation 249 between points. Note that library users does not have to use this type. Algorithms works on iterators, so 250 all algorithms also accept iterators on a vector (or other container) of points. 251 - \ref boost::geometry::model::ring "linear_ring": Sequence of point values with linear interpolation 252 between points, which is closed and not self-intersecting 253 - \ref boost::geometry::model::polygon "polygon": Plane figure, consisting of an outer ring and zero or more 254 inner rings. So basically a polygon which might have holes. 255 <em>Note that this definition is different from several other polygon definitions and libraries, 256 where polygons are not allowed to have holes. These polygons are comparable to the linear_ring above</em> 257 258 And multi-geometries: 259 - \ref boost::geometry::model::multi_point "multi_point": collection of points 260 - \ref boost::geometry::model::multi_linestring "multi_linestring": collection of linestrings 261 - \ref boost::geometry::model::multi_polygon "multi_polygon": collection of polygons 262 263 The naming of these classes is used in: 264 - WKT (Well-Known Text) 265 - KML (Google Maps) 266 - GML 267 - many GIS/geometry libraries 268 269 and in many databases: 270 - Oracle Spatial 271 - SQL Server 2008 272 - PostGreSQL 273 - MySQL 274 - MonetDB 275 276 Besides this the Generic Geometry Library provides the following additional classes: 277 - \ref boost::geometry::model::box "box": Box, used for selections and for envelopes (bounding boxes) 278 - \ref boost::geometry::model::segment "segment": Segment, helper class, used for e.g. intersections 279 280 Finally geometry types can be added as extensions. This is e.g. done with an 281 "n-sphere" meaning "circle" and "sphere". Circle is convenient for selections. 282 283 284 \section Differences 285 The Generic Geometry Library does not implement the OGC Simple Feature interface exactly and completely. 286 There are many differences. Below the most important differences are listed. 287 - In OGC all operations are class methods. The Generic Geometry Library is a template library and defines the algorithms 288 as generic functions. 289 - In OGC a point is defined by an x-coordinate value, a y-coordinate value and possibly a z-coordinate value 290 and a measured value. In the Generic Geometry Library the basic point defines coordinates in a neutral way, 291 so there is no x, no y. 292 - In OGC all geometries have additional members, such as SRID (spatial reference system id) or isMeasured. These 293 properties are not defined in the Generic Geometry Library. Library users can implement them, if necessary, 294 in derived classes. 295 - In OGC the envelope returns a geometry, in the Generic Geometry Library it returns a box 296 - The OGC algorithm asText is named "wkt" 297 - Union and intersection are currently named "X_inserter" to indicate that they 298 insert there produced geometries (if any) as an OutputIterator 299 300 301 More information on OGC can be found on their website, http://www.opengeospatial.org 302 and on Wikipedia http://en.wikipedia.org/wiki/Open_Geospatial_Consortium 303 */ 304 305 306 //--------------------------------------------------------------------------------------------------- 307 308 /*! 309 \page status Status, previews and formal review 310 311 \section introduction Introduction 312 313 Boost.Geometry is accepted by Boost (http://permalink.gmane.org/gmane.comp.lib.boost.announce/246) 314 after formal review (http://permalink.gmane.org/gmane.comp.lib.boost.announce/239) 315 316 The first preview was a template 2D geometry library providing its own geometries and algorithms working on 317 those geometries. Those geometries are still provided but not essential anymore. 318 319 The second preview didn't asume points with .x() and .y() anymore. It provided strategies, 320 operating on specific point types. So point_xy (cartesian points) were 321 handled different from point_ll (latlong points). That is still the case (now using a coordinate system meta-function) 322 323 The third preview introducted the point concept, library users could use their own points with the algorithms 324 provided by the library. 325 326 The fourth preview implemented concepts for all geometries. Besides that tag dispatching was 327 introduced internally. All algorithms were made generic. 328 329 The Formal Review continued with the design of the fourth preview, made it more consistent 330 (apply everywhere, all implementation within struct's, structs used as building blocks for 331 multi-implementations, etc). Things were made more conform Boost standards (template parameters, 332 no tabs, etc). 333 334 \section changes4 Changes since preview 3 335 - there are now typedefs for the more common geometries, such as point_2d or ring_ll_deg 336 - all geometries are optional, everything is working with concepts 337 - the convex hull algorithm has been added and can be calculated for linestrings (ranges, point sequences), polygons 338 - map projections (92 !) have been added, they are converted to C++ template classes from PROJ4 339 - transformations have been added, to go from one coordinate system to another 340 - conversions have been added, to go from one geometry type to another (e.g. BOX to POLYGON) 341 - edit functionality have been added, to edit coordinate values or to add points 342 - parsing of latitude longitude coordinate values have been added 343 - the "selected" algorithm have been added 344 - many examples have been added 345 - many tests have been added 346 347 \b Breaking \b changes 348 Because the library was in preview, and it still is, there are some major changes which might influence library user's 349 code. Although there are many changes internally, the changes for users should be relatively small: 350 - all algorithms accepting linestrings are now modified to get the linestring itself. In the previous version 351 .begin(), end() had to be specified, This is not necessary anymore, because the Boost Range Library is used 352 internally, and tag dispatching is used to distinguish different geometries 353 - the "grow" utility is now splitted into buffer (growing a box with a value was in fact a buffer) and a expand. 354 - there was a generic "get" function with a const ref and a non const ref. This is splitted into "get" and "set" 355 - there might be more changes, please contact if anything is unclear 356 357 \section changes5 Changes since preview 4 358 There are the following changes: 359 - implementation of spatial set relations (intersection, union) 360 - implementation of some spatial boolean relations (disjoint, equal, intersects, overlaps) 361 - move of GIS-specific code to extension/gis 362 - move of map projections to extensions/gis/projections 363 - implementation of SVG in extensions/SVG 364 - review of all code, conform Boost code guidelines, no tabs, template parameters, etc. 365 - other small changes. 366 367 \b Breaking \b changes 368 - there is now distinction between functions using an output iterator, and functions 369 resulting in modifying geometries. Functions using an output iterator are called _inserter, 370 so convex_hull_inserter inserts points (the hull) into something. 371 - many headerfiles are moved and/or renamed 372 - strategies now define a method \b apply, in previous versions this was \b operator() 373 <i>this only influences your code if you've made strategies yourself</i> 374 - ... 375 376 377 \section changes6 Changes since formal review 378 - namespace changes 379 - intersection: fixed Access Violoation which could occur at wrongly oriented input 380 - intersection: fixed omitting outer polygon if it was equal 381 - intersection: performance improvement, non quadratic behaviour on monotonic sections 382 - intersection: now supporting GMP and CLN number types 383 (there are still some comparisons causing implicit casts to double, which will be removed) 384 - intersection: support of input consisting of pointer-types 385 - small other changes (strategies transform and intersection do now have apply instead of operator() and relate) 386 387 388 If people are interested in helping with the library, be it by coding, by testing, by commenting or otherwise, they 389 are very welcome. 390 391 \section history History 392 Geodan started in 1995 with a Geographic Library, called geolib or also GGL (Geodan Geographic Library). 393 Since then hundreds of projects have 394 been done using this geolib, and the geolib have been extended to fit the needs of its users. Geolib 395 can be used in different environments: in Windows applications, as a DLL (ggl32.dll), in 396 Web Map Servers (SclMapServer), Web Feature Servers or more specific programs. 397 398 In 2007-2009 the Geometry part has been revised and completely templatized. 399 From 2008 Bruno Lalande, already a Boost contributor, joined and helped 400 to make the library more generic and to define clear concepts. 401 It was later now called Generic Geometry Library (GGL). 402 From 2009 Mateusz Loskot, an active member of Geospatial Open Source communities, 403 joined and helped with reviewing code, guidelines, WKB, iterators, and the Wiki and ticket system (http://trac.osgeo.org/ggl) 404 405 The library is now called Boost.Geometry (formerly: Generic Geometry Library, abbreviated to GGL). 406 Boost.Geometry is Open Source and is accepted by Boost libraries. 407 408 409 */ 410 411 412 //--------------------------------------------------------------------------------------------------- 413 414 /*! 415 \page download Download Boost.Geometry 416 417 The library can be downloaded from Boost SVN. There is anonymous SVN access. 418 419 The command 420 421 <tt>svn co https://svn.boost.org/svn/boost/sandbox/geometry geometry</tt> 422 423 will download the library to your machine. 424 425 The library can also be downloaded from Geodan SVN. <i>This will be moved to osgeo SVN</i> 426 427 */ 428 429 430 431 432 433 #endif // _DOXYGEN_PAGES_HPP 434