#### /Src/Dependencies/Boost/libs/geometry/doc/doxy/doxygen_input/pages/doxygen_pages.hpp

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