]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 |