diff --git a/doc/Doxyfile b/doc/Doxyfile new file mode 100644 index 000000000..e32c567ad --- /dev/null +++ b/doc/Doxyfile @@ -0,0 +1,285 @@ +# Doxyfile 1.5.5 + +#--------------------------------------------------------------------------- +# Project related configuration options +#--------------------------------------------------------------------------- +DOXYFILE_ENCODING = UTF-8 +PROJECT_NAME = "Boost.Geometry (aka GGL)" +PROJECT_NUMBER = +OUTPUT_DIRECTORY = ./doxygen_output +CREATE_SUBDIRS = NO +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ABBREVIATE_BRIEF = +ALWAYS_DETAILED_SEC = YES +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = YES +STRIP_FROM_PATH = c:/svn/boost-geometry \ + c:/svn/boost-geometry/libs/geometry/doc/doxygen_input/pages +STRIP_FROM_INC_PATH = +SHORT_NAMES = NO +JAVADOC_AUTOBRIEF = NO +QT_AUTOBRIEF = NO +MULTILINE_CPP_IS_BRIEF = NO +INHERIT_DOCS = YES +SEPARATE_MEMBER_PAGES = NO +TAB_SIZE = 8 +ALIASES = +OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_JAVA = NO +OPTIMIZE_FOR_FORTRAN = NO +OPTIMIZE_OUTPUT_VHDL = NO +BUILTIN_STL_SUPPORT = YES +CPP_CLI_SUPPORT = NO +SIP_SUPPORT = NO +DISTRIBUTE_GROUP_DOC = NO +SUBGROUPING = YES +TYPEDEF_HIDES_STRUCT = NO +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_CLASSES = NO +EXTRACT_LOCAL_METHODS = NO +EXTRACT_ANON_NSPACES = NO +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = NO +HIDE_FRIEND_COMPOUNDS = NO +HIDE_IN_BODY_DOCS = NO +INTERNAL_DOCS = NO +CASE_SENSE_NAMES = NO +HIDE_SCOPE_NAMES = NO +SHOW_INCLUDE_FILES = NO +INLINE_INFO = NO +SORT_MEMBER_DOCS = NO +SORT_BRIEF_DOCS = YES +SORT_GROUP_NAMES = YES +SORT_BY_SCOPE_NAME = YES +GENERATE_TODOLIST = NO +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +SHOW_USED_FILES = NO +SHOW_DIRECTORIES = NO +FILE_VERSION_FILTER = +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = NO +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +INPUT = . .. ../../../boost/geometry/core \ + ../../../boost/geometry/algorithms \ + ../../../boost/geometry/algorithms/detail \ + ../../../boost/geometry/algorithms/overlay \ + ../../../boost/geometry/arithmetic \ + ../../../boost/geometry/geometries/concepts \ + ../../../boost/geometry/geometries/concepts/detail \ + ../../../boost/geometry/geometries \ + ../../../boost/geometry/geometries/adapted \ + ../../../boost/geometry/geometries/register \ + ../../../boost/geometry/iterators \ + ../../../boost/geometry/multi/algorithms \ + ../../../boost/geometry/multi/algorithms/detail \ + ../../../boost/geometry/multi/core \ + ../../../boost/geometry/multi/geometries \ + ../../../boost/geometry/multi/geometries/concepts \ + ../../../boost/geometry/multi/iterators \ + ../../../boost/geometry/policies \ + ../../../boost/geometry/policies/relate \ + ../../../boost/geometry/strategies \ + ../../../boost/geometry/strategies/concepts \ + ../../../boost/geometry/strategies/agnostic \ + ../../../boost/geometry/strategies/cartesian \ + ../../../boost/geometry/strategies/spherical \ + ../../../boost/geometry/strategies/transform \ + ../../../boost/geometry/util \ + ../../../boost/geometry/extensions/io/svg \ + ./doxygen_input/pages +INPUT_ENCODING = UTF-8 +FILE_PATTERNS = *.hpp +RECURSIVE = NO +EXCLUDE = ../../../boost/geometry/util/builder.hpp \ + ../../../boost/geometry/algorithms/parse.hpp \ + ../../../boost/geometry/algorithms/point_on_line.hpp \ + ../../../boost/geometry/strategies/cartesian/cart_intersect.hpp \ + ../../../boost/geometry/util/distance_sort.hpp \ + ./doxygen_extension_examples.hpp +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = +EXAMPLE_PATH = . .. ../example \ + doxygen_input/sourcecode \ + ../../../boost/geometry/geometries \ + ../../../boost/geometry/strategies \ + ../../../boost/geometry/strategies/cartesian \ + ../../../boost/geometry/algorithms +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +IMAGE_PATH = doxygen_input/images +INPUT_FILTER = +FILTER_PATTERNS = +FILTER_SOURCE_FILES = NO +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +INLINE_SOURCES = NO +STRIP_CODE_COMMENTS = YES +REFERENCED_BY_RELATION = NO +REFERENCES_RELATION = NO +REFERENCES_LINK_SOURCE = NO +USE_HTAGS = NO +VERBATIM_HEADERS = NO +#--------------------------------------------------------------------------- +# configuration options related to the alphabetical class index +#--------------------------------------------------------------------------- +COLS_IN_ALPHA_INDEX = 3 +IGNORE_PREFIX = +#--------------------------------------------------------------------------- +# configuration options related to the HTML output +#--------------------------------------------------------------------------- +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = doxygen_input/ggl_doxygen_header.html +HTML_FOOTER = doxygen_input/ggl_doxygen_footer.html +HTML_STYLESHEET = +HTML_ALIGN_MEMBERS = YES +GENERATE_HTMLHELP = NO +GENERATE_DOCSET = NO +DOCSET_FEEDNAME = "Generated documentation, by Doxygen" +DOCSET_BUNDLE_ID = org.doxygen.Project +HTML_DYNAMIC_SECTIONS = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = NO +ENUM_VALUES_PER_LINE = 4 +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = YES +LATEX_BATCHMODE = NO +LATEX_HIDE_INDICES = NO +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +#--------------------------------------------------------------------------- +# configuration options related to the man page output +#--------------------------------------------------------------------------- +GENERATE_MAN = NO +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = NO +#--------------------------------------------------------------------------- +# configuration options related to the XML output +#--------------------------------------------------------------------------- +GENERATE_XML = NO +XML_OUTPUT = xml +XML_SCHEMA = +XML_DTD = +XML_PROGRAMLISTING = YES +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- +GENERATE_AUTOGEN_DEF = NO +#--------------------------------------------------------------------------- +# configuration options related to the Perl module output +#--------------------------------------------------------------------------- +GENERATE_PERLMOD = NO +PERLMOD_LATEX = NO +PERLMOD_PRETTY = YES +PERLMOD_MAKEVAR_PREFIX = +#--------------------------------------------------------------------------- +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +SEARCH_INCLUDES = YES +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = BOOST_CONCEPT_REQUIRES(x)= \ + BOOST_CONCEPT_ASSERT(x) = \ + BOOST_STATIC_ASSERT(x) = \ + DOXYGEN_SHOULD_SKIP_THIS \ + DOXYGEN_NO_DISPATCH \ + DOXYGEN_NO_IMPL \ + DOXYGEN_NO_DETAIL \ + DOXYGEN_NO_CONCEPT_MEMBERS \ + DOXYGEN_NO_TRAITS_SPECIALIZATIONS \ + DOXYGEN_NO_STRATEGY_SPECIALIZATIONS \ + DOXYGEN_NO_SPECIALIZATIONS +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to external references +#--------------------------------------------------------------------------- +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +MSCGEN_PATH = +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +CLASS_GRAPH = YES +COLLABORATION_GRAPH = YES +GROUP_GRAPHS = YES +UML_LOOK = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = YES +INCLUDED_BY_GRAPH = YES +CALL_GRAPH = NO +CALLER_GRAPH = NO +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = YES +DOT_MULTI_TARGETS = NO +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/doc/README.txt b/doc/README.txt new file mode 100644 index 000000000..0cd80e938 --- /dev/null +++ b/doc/README.txt @@ -0,0 +1,37 @@ +Generic Geometry Library (ggl) + +Website: http://geometrylibrary.geodan.nl/ + +Copyright © 1995-2009 Barend Gehrels, Geodan Holding B.V. Amsterdam, the Netherlands. +Copyright © 2008-2009 Bruno Lalande, Paris, France. + +Distributed under 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 + +Introduction + +The Generic Geometry Library (currently in "preview 4") provides a generic +implementation of geometry algorithms, working with user-defined geometries. + +The algorithms include some well-known and often needed algorithms as +point-in-polygon, polygon area, point-to-point distance, point-to-line +distance, line clipping and polygon clipping, convex hulls. It also contains +transformation algorithms, map projections and selection algorithms. + +Besides algorithms the library provides geometry classes which might be used, +but the generic algorithms do not depend on them. + +The library follows existing conventions: + + * conventions from boost + * conventions from the std library + * OGC names and conventions (see the page about OGC) + +This Generic Geometry Library (ggl) is aimed to be proposed to the Boost +Library Collection. + +The library can be downloaded from the Boost Sandbox or as a zipfile, +go to the Download page for more information: + +http://geometrylibrary.geodan.nl/download.html diff --git a/doc/boost.png b/doc/boost.png new file mode 100644 index 000000000..9912755af Binary files /dev/null and b/doc/boost.png differ diff --git a/doc/boostbook.css b/doc/boostbook.css new file mode 100644 index 000000000..81bb80618 --- /dev/null +++ b/doc/boostbook.css @@ -0,0 +1,290 @@ +/* Generated by KompoZer */ +body { + margin: 1em; + font-family: sans-serif; +} +p { + text-align: left; + font-size: 10pt; + line-height: 1.15; +} +p tt.computeroutput { + font-size: 9pt; +} +pre.synopsis { + margin: 1pc 4% 0pc; + padding: 0.5pc; + font-size: 90%; +} +.programlisting, .screen { + margin: 1pc 4% 0pc; + padding: 0.5pc; + font-size: 9pt; + display: block; +} +td .programlisting, td .screen { + margin: 0pc; + padding: 0pc; +} +h1, h2, h3, h4, h5, h6 { + margin: 1em 0em 0.5em; + text-align: left; + font-weight: bold; +} +h1 { +} +h2 { +} +h3 { +} +h4 { +} +h5 { +} +h6 { +} +title, h1.title, h2.title h3.title, h4.title, h5.title, h6.title, .refentrytitle { + font-weight: bold; + margin-bottom: 1pc; +} +h1.title { + font-size: 140%; +} +h2.title { + font-size: 140%; +} +h3.title { + font-size: 130%; +} +h4.title { + font-size: 120%; +} +h5.title { + font-size: 110%; +} +h6.title { + font-size: 100%; +} +.section h1 { + margin: 0em 0em 0.5em; + font-size: 140%; +} +.section h2 { + font-size: 140%; +} +.section h3 { + font-size: 130%; +} +.section h4 { + font-size: 120%; +} +.section h5 { + font-size: 110%; +} +.section h6 { + font-size: 100%; +} +h1 tt.computeroutput { + font-size: 140%; +} +h2 tt.computeroutput { + font-size: 140%; +} +h3 tt.computeroutput { + font-size: 130%; +} +h4 tt.computeroutput { + font-size: 120%; +} +h5 tt.computeroutput { + font-size: 110%; +} +h6 tt.computeroutput { + font-size: 100%; +} +h3.author { + font-size: 100%; +} +li { + font-size: 10pt; + line-height: 1.3; +} +ul { + text-align: left; +} +ol { + text-align: left; +} +a { + text-decoration: none; +} +a:hover { + text-decoration: underline; +} +.spirit-nav { + text-align: right; +} +.spirit-nav a { + color: white; + padding-left: 0.5em; +} +.spirit-nav img { + border-width: 0px; +} +.toc { + margin: 1pc 4% 0pc; + padding: 0.1pc 1pc; + font-size: 80%; + line-height: 1.15; +} +.boost-toc { + padding: 0.5pc; + float: right; +} +.table-title, div.table p.title { + margin-left: 4%; + padding-right: 0.5em; + padding-left: 0.5em; +} +.informaltable table, .table table { + width: 92%; + margin-left: 4%; + margin-right: 4%; +} +div.informaltable table, div.table table { + padding: 4px; +} +div.informaltable table tr td, div.table table tr td { + padding: 0.5em; + text-align: left; + font-size: 9pt; +} +div.informaltable table tr th, div.table table tr th { + border: 1pt solid white; + padding: 0.5em; + font-size: 80%; +} +div.note, div.tip, div.important, div.caution, div.warning, p.blurb { + margin: 1pc 4% 0pc; + padding: 0.5pc; + font-size: 9pt; + line-height: 1.2; + display: block; +} +p.blurb img { + padding: 1pt; +} +div.variablelist dl dt, span.term { + font-weight: bold; + font-size: 10pt; +} +div.variablelist table tbody tr td { + margin: 0em 0em 0.5em; + padding: 0em 2em 0em 0em; + text-align: left; + vertical-align: top; + font-size: 10pt; + line-height: 1; +} +div.variablelist dl dt { + margin-bottom: 0.2em; +} +div.variablelist dl dd { + margin: 0em 0em 0.5em 2em; + font-size: 10pt; +} +div.variablelist table tbody tr td p, div.variablelist dl dd p { + margin: 0em 0em 0.5em; + line-height: 1; +} +span.title { + font-style: italic; +} +span.underline { + text-decoration: underline; +} +span.strikethrough { + text-decoration: line-through; +} +div div.legalnotice p { + text-align: left; +} +@media screen { + a { color: #005a9c; +} + a:visited { color: #9c5a9c; + } + h1 a, h2 a, h3 a, h4 a, h5 a, h6 a, h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover, h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited { text-decoration: none; + color: #000000; + } + .keyword { color: #0000aa; + } + .identifier { color: #000000; + } + .special { color: #707070; + } + .preprocessor { color: #402080; + } + .char { color: teal; + } + .comment { color: #800000; + } + .string { color: teal; + } + .number { color: teal; + } + .white_bkd { background-color: #ffffff; + } + .dk_grey_bkd { background-color: #999999; + } + .copyright { color: #666666; + font-size: small; + } + div div.legalnotice p { color: #666666; + } + pre.synopsis { border: 1px solid #dcdcdc; + } + .programlisting, .screen { border: 1px solid #dcdcdc; + } + td .programlisting, td .screen { border: 0px solid #dcdcdc; + } + div.note, div.tip, div.important, div.caution, div.warning, p.blurb { border: 1px solid #dcdcdc; + } + .toc { border: 1px solid #dcdcdc; + } + div.informaltable table tr td, div.table table tr td { border: 1px solid #dcdcdc; + } + div.informaltable table tr th, div.table table tr th { border: 1px solid #dcdcdc; + background-color: #f0f0f0; + } + span.highlight { color: #00a000; + } +} +@media print { + a { color: black; +} + a:visited { color: black; + } + .spirit-nav { display: none; + } + pre.synopsis { border: 1px solid gray; + } + .programlisting, .screen { border: 1px solid gray; + } + td .programlisting, td .screen { border: 0px solid #dcdcdc; + } + .toc { border: 1px solid gray; + } + .informaltable table, .table table { border: 1px solid gray; + border-collapse: collapse; + } + div.informaltable table tr td, div.table table tr td { border: 1px solid gray; + } + div.informaltable table tr th, div.table table tr th { border: 1px solid gray; + } + span.highlight { font-weight: bold; + } +} +span.inlinemediaobject img { + vertical-align: middle; +} diff --git a/doc/design_notes.txt b/doc/design_notes.txt new file mode 100644 index 000000000..400e2b0c8 --- /dev/null +++ b/doc/design_notes.txt @@ -0,0 +1,168 @@ +Notes for Bruno / documentation + +1) BOX CONCEPT + +concepts/box_traits.hpp +a) static ints min_corner/max_corner to select min/max corner +b) namespace traits let user define: + -> traits::box_point::type LATERON made generic, this is geometry::point_type::type for everything + -> traits::box_access::get and set (LATERON RENAMED TO index_access AND GOT MORE TEMPLATE PARAMETERS) + Note that these concepts are NOT worked out anymore for our geometries + They are empty and should be specialized by the user. The + specialization of the predeclared box is in geometries/box.hpp +c) namespace support to use: + support::box_point::type for the type of the point of the box + support::box_coordinate::type for the coordinate type, double etc. + + LATERON CHANGED TO GET IT CONSISTENT (and removed support prefix): + point_type::type for the type of the point of the box (or any geometry) + coordinate_type::type for the coordinate type, double etc. of any geometry + +4) bget/bset like get/set for point point, but here for box (cannot override, GCC complains, might be with enable_if) + -> lateron renamed to get_indexed/set_indexed to harmonize with segment + +Note on concept compared with point: +- it is smaller because most things are already in point +- the default traits classes are empty, propose to do that in point also +- I decided to not give directly access to the points of the box. Because users might + have a box defined like this: struct box { double left,right,top,bottom; }; they have no point + at all. + However, they still should define a "point type", with meta-functions, that would be the type that fits with the box. + It also defines the coordinate system and dimensions. + + +Furthermore: +-> removed init enumerations and constructors +-> added instead of constructor a "init_inverse" utility LATERON RENAMED TO make_inverse and assign_inverse + + +2) POINT CONCEPT +didn't change the concept but: +-> removed in the source code everything using constructor with two values +-> removed the initialization +-> points should still have a default constructor, there is nothing to do about that. No problem I think +-> added instead of the constructor a "make" object generator set + +changed the concept files a bit: +-> moved usages of our points (coordinate_type etc) to point.hpp + so specialization is now required for custom point + -> THIS INVALIDATES ONE OF THE WELL FORM POINTS! + -> THIS REQUIRES USERS TO ALWAYS DEFINE 5 TRAIT METAFUNCTIONS + -> THEREFORE WE MIGHT ADD A MACRO (OR A FEW MACRO'S) TO REGISTER A CUSTOM POINT + +-> moved folder "concept/adapted" to "geometries/adapted" because, actually, it implements the concepts but it does not + define the concepts + + +SUGGESTIONS / CONSIDERATIONS: +-> I wouldn't be against merging the files coordinate.hpp, dimension.hpp, system.hpp and access.hpp to one file + "point_traits.hpp" (or "point_meta.hpp") to have the point concept defined in one place. + Like with box. + I ALREADY DID THIS. + +-> An idea would be that "*_concept.hpp" is renamed to "*_concept_check.hpp" and "*_traits.hpp" renamed to "*_concept.hpp" + because that last is what actually defines the concept, that first checks the concept. + However, the checker hpp must include the definition hpp, and all sources should check, so like now they include + "*_concept.hpp" and that is OK. + SO THIS SUGGESTION IS REDRAWN (?) + Still find it a bit unclear / confusing where is really the concept defined. In the traits? In the concept? In the dispatch? + +-> I wondered why the get function didn't return a const ref. But I understand. The value inside the geometry + object might be calculated (e.g. a planet, in time). So it has to return the value. + I first did change it but later on reverted it. + SO THIS SUGGESTION IS NOT VALID + + +QUESTIONS: +-> can ConstPoint be baseclass and Point derived such that it only additionally checks write access? + Or, maybe better that Point has a BOOST_CONCEPT_ASSERT from ConstPoint somewhere + IF yes, same for box + PROBABLY NOT + +-> name of a 2 or 3D (or ND) circle: this is nearly impossible. Wikipedia gives "ball" (meaning only the + interior), n-sphere, hypersphere (>3d). n-sphere was mentioned on the list (e.g. by Bruno), there were objections + I combined all and come up with "sphercle" as appropriate :-) + However, didn't commit that, too funny. Probably nsphere is the most appropriate. So that's how it is now... + + Objections to n-sphere are no problem as we still define a typedef "circle" and "sphere" for the 2D, 3D cases + + + +3) CONCEPTS IN GENERAL +We had the get/set functionality. It has proved very useful. +I made a bget/bset to set bounds of a box in a similar way. +THIS IS NOW CHANGED TO get_indexed/set_indexed to set by index of a box/segment/(n-sphere?). + +However, it can and should be slightly more generic. + +How to set the center of the circle? set_center? (later) NO, THIS IS NOW ALSO GET/SET, see below + +We had also the generic "support::coordinate

::type" function (and dimension). It would be useful if the same +function could be used for all geometries. + +So I added one other level of indirection, by using again tag dispatching. I also decided to remove the namespace "support", +because it is functionality even for the end user (e.g. getting the dimension of a geometry). It is generic functionality, +just like "distance". + + +So it is now, sample with coordinate type: + +1) one generic "coordinate_type::type" metafunction (typedef within a struct) +2) forwarding its call (using remove_const) to a core_dispatch::coordinate_type::type metafunction. +(That one should live in namespace core_dispatch. The reason for that is that functionality within "dispatch", such as +distance implementations, often states "coordinate_type::type" and there 1) is wanted, not 2) +3) per geometry the core_dispatch set is specialized, forwarding its call to "traits::coordinate_type" to be able +to specialize user defined geometries +4) the "traits::coordinate_type" meta function will probably call the geometry::coordinate_type type using a typedef, +but that is just how it is implemented. Custom types can also define it as double or so. + +This system is applied for the next meta-functions, for ALL geometries: +- point_type::type (even point has it, defining itself, the rest of course defines the used point) +- coordinate_type::type +- dimension::value +- coordinate_system::type for coordinate system + +This system is also applied for the next meta-functions, for SOME geometries: +access::get and access::set functions to get/set values (only applicable for point and n-sphere) +indexed_access::get and ::set functions to get/set boundary values (applicable for box, maybe sphere, segment) + (for segment the name "bound" was not convenient. There are min_corner/max_corner consts) + +radius_access::get and ::set functions to get/set radius of an n-sphere, I made this templated by dimension also + to enable ellipses to get a radius per dimension. The n-sphere asserts that it is zero. +radius_type::get and ::set to define the type of the radius of an n-sphere (lateron ellipse) + + +Note that this system is convenient, also e.g. for the OGC specifications where "dimension" can be asked to any geometry. Dimension +is just for convenience, it just using + + +4) PLACE OF CONCEPTS FOLDER +core is a new folder, containing things earlier in concepts. I found the name concepts a little inappropriate because it also +contains functions as "get", "set", etc, things to really use. There is now: +/geometry/core +/geometry/concepts +/geometry/dispatch + +It still might be changed a littlebit, adding a "traits" folder would be more consistent. + + +5) DISTANCE RESULT +changed to template, see mail Phil Endecott with suggestions + +6) ALGORITHMS +added generic: +"assign" to assign values, various overloads +"make", idem but returning the geometry +"transform" to transform coordinate systems +"convert" to convert between geometry types, e.g., a BOX (2 corners) -> RING (5 points) +"parse" to assign string-ed values, this was first in projections -> WILL BE EXTENDED +"buffer" is the old "grow" with a value -> FOR FUTURE EXTENSION +"selected" to return if an object is inside or close to a specified point value +changed: +"centroid" has now two versions, one returning centroid +"envelope" idem + + + +7) STRATEGIES +they are now organized per coordinate system diff --git a/doc/development_notes.txt b/doc/development_notes.txt new file mode 100644 index 000000000..6ee51b727 --- /dev/null +++ b/doc/development_notes.txt @@ -0,0 +1,4 @@ +Content of this document has been moved to Wiki: + +http://trac.osgeo.org/ggl/wiki/Developer/Guidelines +http://trac.osgeo.org/ggl/wiki/Developer/UnitTests diff --git a/doc/doxygen_enhance.py b/doc/doxygen_enhance.py new file mode 100755 index 000000000..f256d698b --- /dev/null +++ b/doc/doxygen_enhance.py @@ -0,0 +1,23 @@ +import sys + +args = sys.argv[1:] +if len(args) != 1: + raise SystemExit("Usage: doxygen_enhance ") + + +# 1) set variable for doxygen_contents to be posted +file_in = open(args[0], 'r') +doxygen_contents = file_in.read() + +doxygen_contents = doxygen_contents.replace('Modules', 'Function overview') +doxygen_contents = doxygen_contents.replace('Related Pages', 'Main pages') +doxygen_contents = doxygen_contents.replace('Main Page', 'Introduction') +doxygen_contents = doxygen_contents.replace('

  • Namespaces
    • ', '') + +doxygen_contents = doxygen_contents.replace('

    Modules

    Here is a list of all modules:
      ', '

      Function overview

      Here is a list of all functions:
        ') +doxygen_contents = doxygen_contents.replace('

        Related Pages

        Here is a list of all related documentation pages:
          ', '

          Main pages

          The following pages give backgrounds on Boost.Geometry:
            ') + + +file_out = file (args[0], 'w') +file_out.write(doxygen_contents) +file_out.close() diff --git a/doc/doxygen_input/ggl_doxygen_footer.html b/doc/doxygen_input/ggl_doxygen_footer.html new file mode 100644 index 000000000..e1789091f --- /dev/null +++ b/doc/doxygen_input/ggl_doxygen_footer.html @@ -0,0 +1,22 @@ +
            + + + + + + + +
            +

            December 1, 2009

            +            		 +Copyright © 1995-2009 Barend Gehrels, Geodan, Amsterdam
            +Copyright © 2008-2009 Bruno Lalande, Paris
            +Copyright © 2009 Mateusz Loskot, Cadcorp, London
            +             +
            + +
            +Documentation is generated by Doxygen +
            + + \ No newline at end of file diff --git a/doc/doxygen_input/ggl_doxygen_header.html b/doc/doxygen_input/ggl_doxygen_header.html new file mode 100644 index 000000000..3f42facb1 --- /dev/null +++ b/doc/doxygen_input/ggl_doxygen_header.html @@ -0,0 +1,24 @@ + + + + +Boost.Geometry (aka GGL, Generic Geometry Library) + + + + + + + + + + + +
            +Boost.Geometry +   + + +Boost C++ Libraries + +
            diff --git a/doc/doxygen_input/images/07_graph_route_example_svg.png b/doc/doxygen_input/images/07_graph_route_example_svg.png new file mode 100644 index 000000000..3bf38fa46 Binary files /dev/null and b/doc/doxygen_input/images/07_graph_route_example_svg.png differ diff --git a/doc/doxygen_input/images/07_graph_route_example_text.png b/doc/doxygen_input/images/07_graph_route_example_text.png new file mode 100644 index 000000000..b51e9268d Binary files /dev/null and b/doc/doxygen_input/images/07_graph_route_example_text.png differ diff --git a/doc/doxygen_input/images/centroid_polygon.png b/doc/doxygen_input/images/centroid_polygon.png new file mode 100644 index 000000000..a6426e8f7 Binary files /dev/null and b/doc/doxygen_input/images/centroid_polygon.png differ diff --git a/doc/doxygen_input/images/centroid_ring.png b/doc/doxygen_input/images/centroid_ring.png new file mode 100644 index 000000000..d2d014813 Binary files /dev/null and b/doc/doxygen_input/images/centroid_ring.png differ diff --git a/doc/doxygen_input/images/clip_linestring.png b/doc/doxygen_input/images/clip_linestring.png new file mode 100644 index 000000000..f02d19ed0 Binary files /dev/null and b/doc/doxygen_input/images/clip_linestring.png differ diff --git a/doc/doxygen_input/images/clip_polygon.png b/doc/doxygen_input/images/clip_polygon.png new file mode 100644 index 000000000..e94792e74 Binary files /dev/null and b/doc/doxygen_input/images/clip_polygon.png differ diff --git a/doc/doxygen_input/images/clip_segment_segment.png b/doc/doxygen_input/images/clip_segment_segment.png new file mode 100644 index 000000000..a65b68135 Binary files /dev/null and b/doc/doxygen_input/images/clip_segment_segment.png differ diff --git a/doc/doxygen_input/images/combine_box_box.png b/doc/doxygen_input/images/combine_box_box.png new file mode 100644 index 000000000..807c39504 Binary files /dev/null and b/doc/doxygen_input/images/combine_box_box.png differ diff --git a/doc/doxygen_input/images/combine_box_point.png b/doc/doxygen_input/images/combine_box_point.png new file mode 100644 index 000000000..17b22aa80 Binary files /dev/null and b/doc/doxygen_input/images/combine_box_point.png differ diff --git a/doc/doxygen_input/images/convexhull_polygon_polygon.png b/doc/doxygen_input/images/convexhull_polygon_polygon.png new file mode 100644 index 000000000..e1ae38acc Binary files /dev/null and b/doc/doxygen_input/images/convexhull_polygon_polygon.png differ diff --git a/doc/doxygen_input/images/envelope_polygon.png b/doc/doxygen_input/images/envelope_polygon.png new file mode 100644 index 000000000..404f4d7e7 Binary files /dev/null and b/doc/doxygen_input/images/envelope_polygon.png differ diff --git a/doc/doxygen_input/images/linestring.png b/doc/doxygen_input/images/linestring.png new file mode 100644 index 000000000..5d243eed1 Binary files /dev/null and b/doc/doxygen_input/images/linestring.png differ diff --git a/doc/doxygen_input/images/multi_polygon.png b/doc/doxygen_input/images/multi_polygon.png new file mode 100644 index 000000000..7565ee501 Binary files /dev/null and b/doc/doxygen_input/images/multi_polygon.png differ diff --git a/doc/doxygen_input/images/output_main.png b/doc/doxygen_input/images/output_main.png new file mode 100644 index 000000000..184ba5965 Binary files /dev/null and b/doc/doxygen_input/images/output_main.png differ diff --git a/doc/doxygen_input/images/polygon.png b/doc/doxygen_input/images/polygon.png new file mode 100644 index 000000000..b90f1506c Binary files /dev/null and b/doc/doxygen_input/images/polygon.png differ diff --git a/doc/doxygen_input/images/robust_float.png b/doc/doxygen_input/images/robust_float.png new file mode 100644 index 000000000..c43237c2a Binary files /dev/null and b/doc/doxygen_input/images/robust_float.png differ diff --git a/doc/doxygen_input/images/robust_stars.png b/doc/doxygen_input/images/robust_stars.png new file mode 100644 index 000000000..4278ea56a Binary files /dev/null and b/doc/doxygen_input/images/robust_stars.png differ diff --git a/doc/doxygen_input/images/robust_triangle_box.png b/doc/doxygen_input/images/robust_triangle_box.png new file mode 100644 index 000000000..73ae5744b Binary files /dev/null and b/doc/doxygen_input/images/robust_triangle_box.png differ diff --git a/doc/doxygen_input/images/robust_triangles.png b/doc/doxygen_input/images/robust_triangles.png new file mode 100644 index 000000000..17fc46ef3 Binary files /dev/null and b/doc/doxygen_input/images/robust_triangles.png differ diff --git a/doc/doxygen_input/images/set_a_ac.png b/doc/doxygen_input/images/set_a_ac.png new file mode 100644 index 000000000..2ba18a700 Binary files /dev/null and b/doc/doxygen_input/images/set_a_ac.png differ diff --git a/doc/doxygen_input/images/set_adapt_turns.png b/doc/doxygen_input/images/set_adapt_turns.png new file mode 100644 index 000000000..cfa3375e7 Binary files /dev/null and b/doc/doxygen_input/images/set_adapt_turns.png differ diff --git a/doc/doxygen_input/images/set_int_right_union_left.png b/doc/doxygen_input/images/set_int_right_union_left.png new file mode 100644 index 000000000..9c2bc84f4 Binary files /dev/null and b/doc/doxygen_input/images/set_int_right_union_left.png differ diff --git a/doc/doxygen_input/images/simplify_example.png b/doc/doxygen_input/images/simplify_example.png new file mode 100644 index 000000000..cf5a4a6b2 Binary files /dev/null and b/doc/doxygen_input/images/simplify_example.png differ diff --git a/doc/doxygen_input/images/simplify_linestring.png b/doc/doxygen_input/images/simplify_linestring.png new file mode 100644 index 000000000..51df7a305 Binary files /dev/null and b/doc/doxygen_input/images/simplify_linestring.png differ diff --git a/doc/doxygen_input/images/source/centroid_polygon.svg b/doc/doxygen_input/images/source/centroid_polygon.svg new file mode 100644 index 000000000..15a2a2793 --- /dev/null +++ b/doc/doxygen_input/images/source/centroid_polygon.svg @@ -0,0 +1,107 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/doxygen_input/images/source/centroid_ring.svg b/doc/doxygen_input/images/source/centroid_ring.svg new file mode 100644 index 000000000..fd5e5f5a2 --- /dev/null +++ b/doc/doxygen_input/images/source/centroid_ring.svg @@ -0,0 +1,105 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/doxygen_input/images/source/clip_linestring.svg b/doc/doxygen_input/images/source/clip_linestring.svg new file mode 100644 index 000000000..6378e34c6 --- /dev/null +++ b/doc/doxygen_input/images/source/clip_linestring.svg @@ -0,0 +1,132 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/clip_polygon.svg b/doc/doxygen_input/images/source/clip_polygon.svg new file mode 100644 index 000000000..3437c2aac --- /dev/null +++ b/doc/doxygen_input/images/source/clip_polygon.svg @@ -0,0 +1,115 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/clip_polygon_2.svg b/doc/doxygen_input/images/source/clip_polygon_2.svg new file mode 100644 index 000000000..87c177e73 --- /dev/null +++ b/doc/doxygen_input/images/source/clip_polygon_2.svg @@ -0,0 +1,88 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/combine_box_box.svg b/doc/doxygen_input/images/source/combine_box_box.svg new file mode 100644 index 000000000..14da5a1c9 --- /dev/null +++ b/doc/doxygen_input/images/source/combine_box_box.svg @@ -0,0 +1,114 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/combine_box_point.svg b/doc/doxygen_input/images/source/combine_box_point.svg new file mode 100644 index 000000000..de0a67e2f --- /dev/null +++ b/doc/doxygen_input/images/source/combine_box_point.svg @@ -0,0 +1,111 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/convexhull_polygon_polygon.svg b/doc/doxygen_input/images/source/convexhull_polygon_polygon.svg new file mode 100644 index 000000000..8017f9c1d --- /dev/null +++ b/doc/doxygen_input/images/source/convexhull_polygon_polygon.svg @@ -0,0 +1,100 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/doxygen_input/images/source/envelope_polygon.svg b/doc/doxygen_input/images/source/envelope_polygon.svg new file mode 100644 index 000000000..c7cef36dd --- /dev/null +++ b/doc/doxygen_input/images/source/envelope_polygon.svg @@ -0,0 +1,100 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/doxygen_input/images/source/geometries.svg b/doc/doxygen_input/images/source/geometries.svg new file mode 100644 index 000000000..5eb7ea84a --- /dev/null +++ b/doc/doxygen_input/images/source/geometries.svg @@ -0,0 +1,90 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/intersection_results.svg b/doc/doxygen_input/images/source/intersection_results.svg new file mode 100644 index 000000000..d83e694cb --- /dev/null +++ b/doc/doxygen_input/images/source/intersection_results.svg @@ -0,0 +1,495 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + is_parallel + + + + + + + + + + + + + + + + + + + + + + + + is_intersect + is_disjoint + is_collinear_overlap + is_collinear_connect + + + + + + + + + + + B + B + E + E + I + I + 0 + 0 + + diff --git a/doc/doxygen_input/images/source/intersection_segment_segment.svg b/doc/doxygen_input/images/source/intersection_segment_segment.svg new file mode 100644 index 000000000..1baaaf4d7 --- /dev/null +++ b/doc/doxygen_input/images/source/intersection_segment_segment.svg @@ -0,0 +1,152 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/linestring_example.svg b/doc/doxygen_input/images/source/linestring_example.svg new file mode 100644 index 000000000..f631d4c47 --- /dev/null +++ b/doc/doxygen_input/images/source/linestring_example.svg @@ -0,0 +1,108 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/polygon_example.svg b/doc/doxygen_input/images/source/polygon_example.svg new file mode 100644 index 000000000..2258e557a --- /dev/null +++ b/doc/doxygen_input/images/source/polygon_example.svg @@ -0,0 +1,121 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/polygon_example1.svg b/doc/doxygen_input/images/source/polygon_example1.svg new file mode 100644 index 000000000..8c8ba7599 --- /dev/null +++ b/doc/doxygen_input/images/source/polygon_example1.svg @@ -0,0 +1,111 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/ring.svg b/doc/doxygen_input/images/source/ring.svg new file mode 100644 index 000000000..49c729334 --- /dev/null +++ b/doc/doxygen_input/images/source/ring.svg @@ -0,0 +1,92 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + diff --git a/doc/doxygen_input/images/source/simplify_example.svg b/doc/doxygen_input/images/source/simplify_example.svg new file mode 100644 index 000000000..5cbb7e0fa --- /dev/null +++ b/doc/doxygen_input/images/source/simplify_example.svg @@ -0,0 +1,81 @@ + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/doxygen_input/images/source/simplify_linestring.svg b/doc/doxygen_input/images/source/simplify_linestring.svg new file mode 100644 index 000000000..25cca7e3d --- /dev/null +++ b/doc/doxygen_input/images/source/simplify_linestring.svg @@ -0,0 +1,100 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + diff --git a/doc/doxygen_input/images/source/union_box_box.svg b/doc/doxygen_input/images/source/union_box_box.svg new file mode 100644 index 000000000..b808dcc69 --- /dev/null +++ b/doc/doxygen_input/images/source/union_box_box.svg @@ -0,0 +1,107 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/within_polygon.svg b/doc/doxygen_input/images/source/within_polygon.svg new file mode 100644 index 000000000..770027ea7 --- /dev/null +++ b/doc/doxygen_input/images/source/within_polygon.svg @@ -0,0 +1,125 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/within_polygon_example.svg b/doc/doxygen_input/images/source/within_polygon_example.svg new file mode 100644 index 000000000..0b0ccb311 --- /dev/null +++ b/doc/doxygen_input/images/source/within_polygon_example.svg @@ -0,0 +1,106 @@ + + + + + + + + + image/svg+xml + + + + + + + + + + + diff --git a/doc/doxygen_input/images/source/within_ring.svg b/doc/doxygen_input/images/source/within_ring.svg new file mode 100644 index 000000000..5a66c4776 --- /dev/null +++ b/doc/doxygen_input/images/source/within_ring.svg @@ -0,0 +1,127 @@ + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + diff --git a/doc/doxygen_input/images/speed_comparison.png b/doc/doxygen_input/images/speed_comparison.png new file mode 100644 index 000000000..5e96986f1 Binary files /dev/null and b/doc/doxygen_input/images/speed_comparison.png differ diff --git a/doc/doxygen_input/images/svg_convex_hull_cities.png b/doc/doxygen_input/images/svg_convex_hull_cities.png new file mode 100644 index 000000000..e47d30439 Binary files /dev/null and b/doc/doxygen_input/images/svg_convex_hull_cities.png differ diff --git a/doc/doxygen_input/images/svg_convex_hull_country.png b/doc/doxygen_input/images/svg_convex_hull_country.png new file mode 100644 index 000000000..2d7270a99 Binary files /dev/null and b/doc/doxygen_input/images/svg_convex_hull_country.png differ diff --git a/doc/doxygen_input/images/svg_intersection_countries.png b/doc/doxygen_input/images/svg_intersection_countries.png new file mode 100644 index 000000000..151763039 Binary files /dev/null and b/doc/doxygen_input/images/svg_intersection_countries.png differ diff --git a/doc/doxygen_input/images/svg_intersection_polygon_box.png b/doc/doxygen_input/images/svg_intersection_polygon_box.png new file mode 100644 index 000000000..0d72a86ec Binary files /dev/null and b/doc/doxygen_input/images/svg_intersection_polygon_box.png differ diff --git a/doc/doxygen_input/images/svg_intersection_polygon_ring.png b/doc/doxygen_input/images/svg_intersection_polygon_ring.png new file mode 100644 index 000000000..ca88da421 Binary files /dev/null and b/doc/doxygen_input/images/svg_intersection_polygon_ring.png differ diff --git a/doc/doxygen_input/images/svg_intersection_ring_box.png b/doc/doxygen_input/images/svg_intersection_ring_box.png new file mode 100644 index 000000000..48a3fb3fd Binary files /dev/null and b/doc/doxygen_input/images/svg_intersection_ring_box.png differ diff --git a/doc/doxygen_input/images/svg_intersection_ring_ring.png b/doc/doxygen_input/images/svg_intersection_ring_ring.png new file mode 100644 index 000000000..8d78c15ea Binary files /dev/null and b/doc/doxygen_input/images/svg_intersection_ring_ring.png differ diff --git a/doc/doxygen_input/images/svg_intersection_roads.png b/doc/doxygen_input/images/svg_intersection_roads.png new file mode 100644 index 000000000..cd21586f6 Binary files /dev/null and b/doc/doxygen_input/images/svg_intersection_roads.png differ diff --git a/doc/doxygen_input/images/svg_simplify_country.png b/doc/doxygen_input/images/svg_simplify_country.png new file mode 100644 index 000000000..e49b72cb4 Binary files /dev/null and b/doc/doxygen_input/images/svg_simplify_country.png differ diff --git a/doc/doxygen_input/images/svg_simplify_road.png b/doc/doxygen_input/images/svg_simplify_road.png new file mode 100644 index 000000000..71f326fcd Binary files /dev/null and b/doc/doxygen_input/images/svg_simplify_road.png differ diff --git a/doc/doxygen_input/images/svg_union_polygon_box.png b/doc/doxygen_input/images/svg_union_polygon_box.png new file mode 100644 index 000000000..7910b9fac Binary files /dev/null and b/doc/doxygen_input/images/svg_union_polygon_box.png differ diff --git a/doc/doxygen_input/images/svg_union_polygon_ring.png b/doc/doxygen_input/images/svg_union_polygon_ring.png new file mode 100644 index 000000000..b82eca6cb Binary files /dev/null and b/doc/doxygen_input/images/svg_union_polygon_ring.png differ diff --git a/doc/doxygen_input/images/svg_union_ring_box.png b/doc/doxygen_input/images/svg_union_ring_box.png new file mode 100644 index 000000000..d1b8c7d65 Binary files /dev/null and b/doc/doxygen_input/images/svg_union_ring_box.png differ diff --git a/doc/doxygen_input/images/svg_union_ring_ring.png b/doc/doxygen_input/images/svg_union_ring_ring.png new file mode 100644 index 000000000..1ebb0d934 Binary files /dev/null and b/doc/doxygen_input/images/svg_union_ring_ring.png differ diff --git a/doc/doxygen_input/images/union_box_box.png b/doc/doxygen_input/images/union_box_box.png new file mode 100644 index 000000000..1a3dfa5d0 Binary files /dev/null and b/doc/doxygen_input/images/union_box_box.png differ diff --git a/doc/doxygen_input/images/within_polygon.png b/doc/doxygen_input/images/within_polygon.png new file mode 100644 index 000000000..b5c51e6f6 Binary files /dev/null and b/doc/doxygen_input/images/within_polygon.png differ diff --git a/doc/doxygen_input/images/within_polygon_example.png b/doc/doxygen_input/images/within_polygon_example.png new file mode 100644 index 000000000..c2a3e3fbc Binary files /dev/null and b/doc/doxygen_input/images/within_polygon_example.png differ diff --git a/doc/doxygen_input/images/within_ring.png b/doc/doxygen_input/images/within_ring.png new file mode 100644 index 000000000..b13ebd849 Binary files /dev/null and b/doc/doxygen_input/images/within_ring.png differ diff --git a/doc/doxygen_input/images/x01_qt_example_output.png b/doc/doxygen_input/images/x01_qt_example_output.png new file mode 100644 index 000000000..7a8f64bb4 Binary files /dev/null and b/doc/doxygen_input/images/x01_qt_example_output.png differ diff --git a/doc/doxygen_input/images/x02_numeric_adaptor_example_output.png b/doc/doxygen_input/images/x02_numeric_adaptor_example_output.png new file mode 100644 index 000000000..a07a1997e Binary files /dev/null and b/doc/doxygen_input/images/x02_numeric_adaptor_example_output.png differ diff --git a/doc/doxygen_input/pages/doxygen_a_design_rationale.hpp b/doc/doxygen_input/pages/doxygen_a_design_rationale.hpp new file mode 100644 index 000000000..f2cbe64ab --- /dev/null +++ b/doc/doxygen_input/pages/doxygen_a_design_rationale.hpp @@ -0,0 +1,809 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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_DESIGN_RATIONALE_HPP +#define _DOXYGEN_DESIGN_RATIONALE_HPP + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page design Design rationale + + + + +\section par1 Introduction + +Suppose you need C++ software to calculate the distance between two points. You might define a struct: + +\code +struct mypoint +{ + double x, y; +}; +\endcode + +And a function, containing the algorithm: +\code +double distance(mypoint const& a, mypoint const& b) +{ + double dx = a.x - b.x; + double dy = a.y - b.y; + return sqrt(dx * dx + dy * dy); +} +\endcode + +Quite simple, and it is usable, but not generic. For a library it has to be designed way further. The design above can only be used for 2D points, for the struct \b mypoint (and no other struct), in a Cartesian coordinate system. +A generic library should be able to calculate the distance: +- for any point class or struct, not on just this \b mypoint type +- in more than two dimensions +- for other coordinate systems, e.g. over the earth or on a sphere +- between a point and a line or between other geometry combinations +- in other (e.g. higher) precision than ‘double’ +- avoiding the square root: often we don’t want to calculate the square because it is a relatively expensive function, and for comparing distances it is not necessary + +In this page we will make the design step by step more generic. + + + + +\section par2 Using templates +The distance function can be changed into a template function. This is trivial and allows calculating the distance between other point types than just \b mypoint. We add two template parameters, allowing input of two different point types. + +\code +template +double distance(P1 const& a, P2 const& b) +{ + double dx = a.x - b.x; + double dy = a.y - b.y; + return sqrt(dx * dx + dy * dy); +} +\endcode + +This template version is slightly better, but not much. Consider a C++ class where member variables are protected… Such a class does not allow to access .x and .y directly. So this paragraph is short and we just go on. + + + + +\section par3 Using traits +We need to take a generic approach, to allow any point type as input to the distance function. Instead of accessing .x and .y, we will add a few levels of indirection, using a traits system. +The distance function then becomes: +\code +template +double distance(P1 const& a, P2 const& b) +{ + double dx = get<0>(a) - get<0>(b); + double dy = get<1>(a) - get<1>(b); + return sqrt(dx * dx + dy * dy); +} +\endcode + +This adapted distance function uses a generic get-function, with dimension as a template parameter, to access the coordinates of a point. This get-function forwards to a traits system, defined as following: +\code +namespace traits +{ + template + struct access {}; +} +\endcode + +which is then specialized for our \b mypoint type, implementing a static method called ‘get’: +\code +namespace traits +{ + template <> + struct access + { + static double get(mypoint const& p) + { + return p.x; + } + }; + // same for 1: p.y + ... +} +\endcode + +Calling traits::access::get(a) now returns us our x-coordinate. Nice? It is quite verbose for a function like this, used so often in the library. We can shorten the syntax by adding an extra \b free \b function: +\code +template +inline double get(P const& p) +{ + return traits::access::get(p); +} +\endcode + +This enables us to call get<0>(a), for any point having the traits::access specialization, as shown in the distance algorithm at the start of this paragraph. +So we wanted to enable classes with methods like .x(), and they are supported as long as there is a specialization of the access struct with a static get function returning .x() for dimension 0, and similar for 1 and .y(). + +Alternatively we could implement, in the traits class, the dimension as a template parameter in a member template function: + +\code +template <> +struct access +{ + template + static double get(mypoint const& p) + // either return x/y using an if-clause + // or call a detail-struct specialized + // per dimension +}; +\endcode + +This alternative gives in the end the same functionality. It however is either using an if-clause (which is not compile-time, so not preferred; it is slightly slower), or adding another level of indirection (a sub-structure specialized on dimension). Therefore the form with the dimension as a template parameter of the struct is preferred. + + + + + + +\section par4 Dimension agnosticism +Now we can calculate the distance between points in 2D, points of any structure or class. However, we wanted to have 3D as well. So we have to make it dimension agnostic. +This complicates our distance function. We can use a for-loop to walk through dimensions, but for loops have another performance than the straightforward coordinate addition which was there originally. However, we can make more usage of templates and implement the distance algorithm as following; it is more complex but attractive for template fans: +\code +template +struct pythagoras +{ + static double apply(P1 const& a, P2 const& b) + { + double d = get(a) - get(b); + return d * d + pythagoras::apply(a, b); + } +}; + +template +struct pythagoras +{ + static double apply(P1 const&, P2 const&) + { + return 0; + } +}; +\endcode + +The distance function is calling that pythagoras struct, specifying the number of dimensions: +\code +template +double distance(P1 const& a, P2 const& b) +{ + BOOST_STATIC_ASSERT(( dimension::value == dimension::value )); + + return sqrt(pythagoras::value>::apply(a, b)); +} +\endcode + +The dimension which is referred to is defined using another traits class: +\code +namespace traits +{ + template + struct dimension {}; +} +\endcode + +which has to be specialized again for the struct \b mypoint. Because it only has to publish a value, it can be conveniently derived from the Boost Meta-Programming Library (MPL) class boost::mpl::int_: +\code +namespace traits +{ + template <> + struct dimension + : boost::mpl::int_<2> + {}; +} +\endcode + +Like the free function \b get, the library also contains a metafunction \b dimension. +\code +template +struct dimension : traits::dimension

            +{}; +\endcode + +The extra declaration is convenient to not call the traits namespace. But there is a more important reason why it is useful. This is explained below. +Now we have agnosticism in the number of dimensions. Our more generic distance function now accepts points of three or more dimensions. The compile-time assertion will prevent point \b a having two dimension and point \b b having three dimensions. + + + + + + + +\section par5 Coordinate type +We assumed double above. What if our points are in integer? We can easily add a traits class, and we will do that. However, the distance between two integer coordinates can still be an irrational value. Besides that, a design goal was to avoid square roots. We handle these cases below, in another paragraph. For the moment we keep returning double, but we allow integer coordinates for our point types. +To define the coordinate type, we add another traits class, coordinate_type, which should be specialized by the library user: +\code +namespace traits +{ + template + struct coordinate_type{}; + + // specialization for our mypoint + template <> + struct coordinate_type + { + typedef double type; + }; +} +\endcode + +Like the access function, where we had a free get function, we add a proxy here as well. A longer version is presented later on, the short function would look like this: + +\code +template +struct coordinate_type : traits::coordinate_type

            {}; +\endcode + +We now can modify our distance algorithm again. Because it still returns double, we only modify the Pythagoras computation class. It should return the coordinate type of its input. But... it has two, possibly different, input point types. They might also differ in their coordinate types. Not that that is very likely, but we’re designing a generic library and we should handle those strange cases. +We have to choose one of the coordinate types and of course we select the one with the highest precision. This is not worked out here, it would be too long, and it is not related to geometry. +We just assume that there is a metafunction \b select_most_precise selecting the best type. +So our computation class becomes: +\code +template +struct pythagoras +{ + typedef typename select_most_precise + < + typename coordinate_type::type, + typename coordinate_type::type + >::type computation_type; + + static computation_type apply(P1 const& a, P2 const& b) + { + computation_type d = get(a) - get(b); + return d * d + pythagoras ::apply(a, b); + } +}; +\endcode + + + + + +\section par6 Different geometries +At this point, we’ve designed a dimension agnostic system supporting any point type of any coordinate type. There are still some tweaks but they will be worked out later. +Now we will see how we calculate the distance between a point and a polygon, or between a point and a line-segment. These formulae are more complex, and the influence on design is even larger. +We don’t want to add a function with another name: +\code +template +double distance_point_segment(P const& p, S const& s) +\endcode + +We want to be generic, the distance function has to be called from code not knowing the type of geometry it handles, so it has to be named distance. We also cannot create an overload because that would be ambiguous, having the same template signature. +There are two solutions to avoid this ambiguity: +- tag dispatching +- SFINAE + +We select tag dispatching because it fits into the traits system, and also because SFINAE has several drawbacks, listed in another paragraph. +With tag dispatching the distance algorithm inspects the type of geometry of the input parameters. The distance function is changed into: +\code +template +double distance(G1 const& g1, G2 const& g2) +{ + return dispatch::distance + < + typename tag::type, + typename tag::type, + G1, G2 + >::apply(g1, g2); +} +\endcode + +It is referring to a metafunction called \b tag and forwarding the call to the method \b apply of a dispatch::distance structure. The tag metafunction is another traits class, and should be specialized for per point type, both shown here: +\code +namespace traits +{ + template + struct tag {}; + + // specialization + template <> + struct tag + { + typedef point_tag type; + }; +} +\endcode + +There is again a free metafunction, like we did for \b coordinate_system and \b get: +\code +template +struct tag : traits::tag {}; +\endcode + +Tags (point_tag, segment_tag, etc) are empty structures with the sole purpose to specialize a dispatch class. +The dispatch class for distance, and its specializations, are all defined in a separate namespace and look like the following: + +\code +namespace dispatch { +template < typename Tag1, typename Tag2, typename G1, typename G2 > +struct distance +{}; + +template +struct distance < point_tag, point_tag, P1, P2 > +{ + static double apply(P1 const& a, P2 const& b) + { + // here we call pythagoras + // exactly like we did before + ... + } +}; + +template +struct distance +< + point_tag, segment_tag, P, S +> +{ + static double apply(P const& p, S const& s) + { + // here we refer to another function + // implementing point-segment + // calculations in 2 or 3 + // dimensions... + ... + } +}; +// here we might have many more +// specializations, +// for point-polygon, box-circle, etc. + +} // namespace +\endcode + +So yes, it is possible; the distance algorithm is generic now in the sense that it also supports different geometry types. One drawback: we have to define two dispatch specializations for point - segment and for segment - point separately. That will also be solved, in the paragraph reversibility below. +The example below shows where we are now: different point types, geometry types, dimensions. +\code +point a(1,1); +point b(2,2); +std::cout << distance(a,b) << std::endl; +segment s1(0,0,5,3); +std::cout << distance(a, s1) << std::endl; +rgb red(255, 0, 0); +rbc orange(255, 128, 0); +std::cout << "color distance: " << distance(red, orange) << std::endl; +\endcode + + + + + +\section par7 Kernel revisited + +We described above that we had a traits class coordinate_type, defined in namespace traits, and defined a separate coordinate_type class as well. This was actually not really necessary before, because the only difference was the namespace clause. But now that we have another geometry type, a segment in this case, it is essential. We can call the coordinate_type metafunction for any geometry type, point, segment, polygon, etc, implemented again by tag dispatching: + +\code +template +struct coordinate_type +{ + typedef typename dispatch::coordinate_type + < + typename tag::type, G + >::type type; +}; +\endcode + +Inside the dispatch namespace this metafunction is implemented twice: a generic version and one specialization for points. The specialization for points calls the traits class. The generic version calls the point specialization, as a sort of recursive metafunction definition: + +\code +namespace dispatch +{ + +// Version for any geometry: +template +struct coordinate_type +{ + typedef typename point_type + < + GeometryTag, G + >::type point_type; + + // Call specialization on point-tag + typedef typename coordinate_type < point_tag, point_type >::type type; +}; + +// Specialization for point-type: +template +struct coordinate_type +{ + typedef typename + traits::coordinate_type

            ::type + type; +}; +\endcode + + +So it calls another metafunction point_type. This is not elaborated in here but realize that it is available for all geometry types, and typedefs the point type which makes up the geometry, calling it type. + +The same applies for the metafunction dimension and for the upcoming metafunction coordinate_system. + + + + + +\section par8 Coordinate system +Until here we assumed a Cartesian system. But we know that the Earth is not flat. Calculating a distance between two GPS-points with the system above would result in nonsense. So we again extend our design. We define for each point type a coordinate system type, using the traits system again. Then we make the calculation dependant on that coordinate system. + +Coordinate system is similar to coordinate type, a metafunction, calling a dispatch function to have it for any geometry-type, forwarding to its point specialization, and finally calling a traits class, defining a typedef type with a coordinate system. We don’t show that all here again. We only show the definition of a few coordinate systems: +\code +struct cartesian {}; + +template +struct geographic +{ + typedef DegreeOrRadian units; +}; +\endcode + +So Cartesian is simple; for geographic we can also select if its coordinates are stored in degrees or in radians. + +The distance function will now change: it will select the computation method for the corresponding coordinate system and then call the dispatch struct for distance. We call the computation method specialized for coordinate systems a \b strategy. So the new version of the distance function is: + +\code +template +double distance(G1 const& g1, G2 const& g2) +{ + typedef typename strategy_distance + < + typename coordinate_system::type, + typename coordinate_system::type, + typename point_type::type, + typename point_type::type, + dimension::value + >::type strategy; + + return dispatch::distance + < + typename tag::type, + typename tag::type, + G1, G2, strategy + >::apply(g1, g2, strategy()); +} +\endcode + +The strategy_distance mentioned here is a metafunction with specializations for different coordinate systems. + +\code +template +struct strategy_distance +{ + // undefined; type is not defined +}; + +template +struct strategy_distance +{ + typedef pythagoras type; +}; +\endcode + +So here is our Pythagoras again, now defined as a strategy. The distance dispatch function just calls its apply method. + +So this is an important step: for spherical or geographical coordinate systems, another strategy (computation method) can be implemented. For spherical coordinate systems we have the haversine formula. So the dispatching traits struct is specialized like this: +\code +template +struct strategy_distance +{ + typedef haversine type; +}; + +// struct haversine with apply function +// is omitted here +\endcode + +For geography, we have some alternatives for distance calculation. There is the Andoyer method, fast and precise, and there is the Vincenty method, slower and more precise, and there are some less precise approaches as well. + +Per coordinate system, one strategy is defined as the default strategy. +To be able to use another strategy as well, we modify our design again and add an overload for the distance algorithm, taking a strategy object as a third parameter. + +This new overload distance function also has the advantage that the strategy can be constructed outside the distance function. Because it was constructed inside above, it could not have construction parameters. But for Andoyer or Vincenty, or the haversine formula, it certainly makes sense to have a constructor taking the radius of the earth as a parameter. +So the distance overloaded function is: + +\code +template +double distance(G1 const& g1, G2 const& g2, S const& strategy) +{ + return dispatch::distance + < + typename tag::type, + typename tag::type, + G1, G2, S + >::apply(g1, g2, strategy); +} +\endcode + +The strategy has to have a method \b apply taking two points as arguments (for points). It is not required that it is a static method. A strategy +might define a constructor, where a configuration value is passed and stored as a member variable. In those cases a static +method would be inconvenient. It can be implemented as a normal method (with the const qualifier). + +We do not list all implementations here, Vincenty would cover half a page of mathematics, but you will understand the idea. We can call distance like this: +\code +distance(c1, c2) +\endcode + +where c1,c2 are Cartesian points, or like this: + +\code +distance(g1, g2) +\endcode + +where g1,g2 are Geographic points, calling the default strategy for Geographic points (e.g. Andoyer), and like this: + +\code +distance(g1, g2, vincenty(6275)) +\endcode + +where a strategy is specified explicitly and constructed with a radius. + + + + + + + + + + +\section par9 Point concept +The five traits classes mentioned in the paragraphs above form together the Point Concept. Any point type for which specializations are implemented in the traits namespace should be handled correctly by the library. So the Point concept consists of: +- a specialization for traits::tag +- a specialization for traits::coordinate_system +- a specialization for traits::coordinate_type +- a specialization for traits::dimension +- a specialization for traits::access + +The last one is a class, containing the method \b get and the (optional) method \b set, the first four are metafunctions, either defining \b type or declaring \b value (conform MPL conventions). +So we now have agnosticism for the number of dimensions, agnosticism for coordinate systems, our design can handle any coordinate type, and it can handle different geometry types. +Furthermore we can specify our own strategies, the code will not compile in case of two points with different dimensions (because of the assertion), and it will not compile for two points with different coordinate systems (because there is no specialization). +We still have the distance function returning double. Next paragraph will solve that. + + + +\section par10 Return type +We promised that calling sqrt was not always necessary. So we define a distance result struct that contains the squared value and is convertible to a double value. +This, however, only has to be done for Pythagoras. The spherical distance functions do not take the square root so for them it is not necessary to avoid the expensive square root call; they can just return their distance. +So the distance result struct is dependant on strategy, therefore made a member type of the strategy. The result struct looks like this: +\code +template +struct cartesian_distance +{ + T sq; + explicit cartesian_distance(T const& v) : sq (v) {} + + inline operator T() const + { + return std::sqrt(sq); + } +}; +\endcode + +It also has operators defined to compare itself to other results without taking the square root. + +Each strategy should define its return type, within the strategy class, e.g.: + +\code + typedef cartesian_distance return_type; +\endcode +or: + +\code + typedef double return_type +\endcode + +for Pythagoras and spherical, respectively. + +Again our distance function will be modified, as expected, to reflect the new return type. For the overload with a strategy it is not complex: +\code +template < typename G1, typename G2, typename Strategy > +typename Strategy::return_type distance( G1 const& G1 , G2 const& G2 , S const& strategy) +\endcode + +But for the one without strategy we have to select strategy, coordinate type, etc. It would be spacious to do it in one line so we add a separate metafunction: +\code +template +struct distance_result +{ + typedef typename point_type::type P1; + typedef typename point_type::type P2; + typedef typename strategy_distance + < + typename cs_tag::type, + typename cs_tag::type, + P1, P2 + >::type S; + + typedef typename S::return_type type; +}; +\endcode + +and modify our distance function: +\code +template +inline typename distance_result::type distance(G1 const& g1, G2 const& g2) +{ ... } +\endcode + +Of course also the apply functions in the dispatch specializations will return a result like this. They have a strategy as a template parameter everywhere, making the less verbose version possible. + + + + +\section par11 Reversibility +Our dispatch::distance class was specialized for pairs of geometries, like or . But library users can also call the distance function with a segment and a point, in that order. Actually, there are many geometry types (polygon, box, linestring), how to implement all combinations without duplicating all tag dispatching functions? +The answer is that we automatically reverse the arguments, if appropriate. For distance it is appropriate because distance is a commutative function. +We add a metafunction geometry_id, which has specializations for each geometry type, just derived from boost::mpl::int_, such that it can be ordered. Point is 1, segment is e.g. 2. + +Then we add a metafunction reverse_dispatch: +\code +template +struct reverse_dispatch : detail::reverse_dispatch + < + geometry_id::type::value, + geometry_id::type::value + > +{}; +\endcode + +Because of the order in geometry_id, we can arrange (template) parameters in that order, in specializations. So the detail structure looks like: +\code +namespace detail +{ + template + struct reverse_dispatch : boost::mpl::if_c + < + (Id1 > Id2), + boost::true_type, + boost::false_type + > + {}; +\endcode + +And our distance function will be modified again with some template meta-programming: + +\code +return boost::mpl::if_c + < + boost::geometry::reverse_dispatch ::type::value, + detail::distance_reversed + < + typename tag::type, + typename tag::type, + G1, G2, + // strategy + >, + dispatch::distance + < + typename tag::type, + typename tag::type, + G1, G2, + // strategy + > + > + >::type::apply(g1, g2, s); +\endcode + +Where the detail::distance_reversed is a specific struct, forwarding its call to dispatch::distance, reversing all its template arguments and function arguments. + + +\section par13 Multi-geometries +Consider Hawaii as a multi_polygon: it is a set of islands (polygons), forming together one entity. The shortest distance from a ship to Hawaii is the shortest distance to the closest island. That algorithm also holds for the shortest distance from a point to a multi-line or a multi-point. +So we don't want to implement that functionality three times. Instead we add a metafunction, is_multi, which is always true for a multi-geometry (multi-point, multi-linestring, multi-polygon) and always false for the single versions. + +\code +template +struct is_multi : core_dispatch::is_multi::type> +{}; + + +namespace dispatch +{ + +template +struct is_multi : boost::false_type {}; + +template <> +struct is_multi : boost::true_type {}; + + +template <> +struct is_multi : boost::true_type {}; + + +template <> +struct is_multi : boost::true_type {}; + +} // namespace dispatch +\endcode + + +Now we can specialize on is_multi, so we add two boolean IsMulti's, one for each geometry type, to our distance dispatch struct and make the call to them in the distance function: + +\code +// specialization: +template +struct distance + < + GeometryTag1, GeometryTag2, G1, G2, Strategy, + false, // G1 is_multi == false, so dispatch a 'single' geometry + true // G2 is_multi == true, so dispatch a multi-geometry + > + : detail::distance::distance_single_to_multi +{}; +\endcode + + + + +If that relatively simple change is done, we have to do one thing: implement the single-to-multi distance implementation structure + +\code +template +struct distance_single_to_multi +{ + typedef typename Strategy::return_type return_type; + + static return_type apply(Geometry const& geometry, + MultiGeometry const& multi, + Strategy const& strategy) + { + using namespace boost; + + return_type mindist = make_distance_result( + numeric::bounds::type>::highest()); + + typedef typename range_const_iterator::type iterator; + for(iterator it = begin(multi); it != end(multi); ++it) + { + return_type dist = boost::geometry::distance(geometry, *it); + if (dist < mindist) + { + mindist = dist; + } + } + + return mindist; + } +}; +\endcode + + + +which iterates over a collection of multi-shapes, and returns the shortest distance. Another function can implement the multi-to-multi function. Note that because of reversibility we don't have to implement the multi-to-single version (as long as multi's always have an higher ID than single's). + + + +\section par14 SFINAE +Instead of tag dispatching we alternatively could have chosen for SFINAE, mentioned above. With SFINAE (Substitution Failure Is Not An Error) we add optional parameters to the distance function, which sole use is to make an overload invalid for other geometry types than specified. So like: +\code +template +inline double distance(P1 const& p1, P2 const& p2 + , typename boost::enable_if >::type* = 0 + , typename boost::enable_if >::type* = 0 + ) + { + return impl::distance::point_to_point(p1, p2); + } +\endcode + +There would then be overloads for point-segment, point-polygon, etc. +This SFINAE: +- gives often compiler troubles and headaches: if a user makes an error somewhere, the compiler will not select any of the methods, and/or it will give completely incomprehensible error listings, just because of this SFINAE. +Stated otherwise (pasted from an answer on the list): With SFINAE the real error is hidden behind the phrase "Failed to specialize". The compiler discards all overloads, because of an error somewhere, and you get this error with no clue how to go on. What you get is the error that it is just failing. All overloads are gone, the compiler is not wrong, there is an error somewhere, but the only visible error message which makes sense for the compiler to give is something like "failed to specialize" or "no matching function call". With tag dispatching you get the real error message. That can also be difficult, but the message(s), sometimes a whole list, give at least a clue of what's wrong. In this case: add the banana-tag or add an implementation for banana. The usage of concepts should reduce the length of the list and give a clearer error message. +- So the essence is: compiler errors in code based on tag dispatching are easier to find than compiler errors in code based on SFINAE, because the SFINAE-case is based on discarding overloads and meaningful error messages are discarded as well +- the combination of SFINAE and the BCCL using boost-concept-requires has been quite difficult, or impossible +- does not support partial specializations because it is a function. The tag-dispatching function is of course also not supporting that, but it forwards its call to the dispatch struct where partial specializations (and member template functions) are possible. The SFINAE could do that as well but then: why not just add one tag more and have tag dispatching instead? +- is a trick to deceive the compiler. “As a language behavior it was designed to avoid programs becoming ill-formed” (http://en.wikipedia.org/wiki/Substitution_failure_is_not_an_error), while tag dispatching is based on specialization, a core feature of C++ +- is more verbose (tag dispatching makes the main free function declarations shorter) +- several Boost reviewers appreciated the tag dispatching approach and prefered them over SFINAE + + +*/ + +#endif // _DOXYGEN_DESIGN_RATIONALE_HPP diff --git a/doc/doxygen_input/pages/doxygen_b_sets.hpp b/doc/doxygen_input/pages/doxygen_b_sets.hpp new file mode 100644 index 000000000..f94b13bfe --- /dev/null +++ b/doc/doxygen_input/pages/doxygen_b_sets.hpp @@ -0,0 +1,214 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// 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_SETS_HPP +#define _DOXYGEN_SETS_HPP + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page sets Spatial set-theoretic operations (union, intersection, difference) + + + + +\section sets_par1 Introduction + +The GGL implementation of the algorithms intersection, union, difference and symmetric difference is based on set theory (a.o. http://en.wikipedia.org/wiki/Set_(mathematics)). +This theory is applied for spatial sets. + +Intersection and union are so-called set-theoretic operations. Those operations +work on sets, and geometries (especially +polygons and multi-polygons) can be seen as sets, sets of points. + + +The first section will repeat a small, relevant part of the algebra of sets, also describing the notation used in this page. The next section will extend this algebra of sets for spatial sets (polygons). + +\section sets_par2 Algebra of sets in a spatial context + +- A ∩ B : the intersection of two sets A and B is the set that contains all elements of A that also belong to B (aka AND) +- A ∪ B : the union of two sets A and B is the set that contains all elements that belong to A or B (aka OR) +- Ac : the complement of set A is the set of elements which do not belong to A +- A \ B : the difference of two sets A and B is the set of elements which belong to A but not to B +- A ∆ B : the symmetric difference of two sets A and B is the set of elements which belong to either A or to B, but not to A and B (aka XOR) + +(Source of most definitions: http://en.wikipedia.org/wiki/Algebra_of_sets) + +There are several laws on sets and we will not discuss them all here. The most important for this page are: +- B \ A = Ac ∩ B and, vice versa, A \ B = Bc ∩ A +- A ∆ B = (B \ A) ∪ (A \ B) (http://www.tutorvista.com/content/math/number-theory/sets/operations-sets.php) + + +\section sets_par3 Polygons + + +Polygons are sets of points, and, therefore polygons follow all definitions and laws for sets. For pragmatic reasons and implementations in computer programs, polygons have an orientation, clockwise or counter clockwise. Orientation is not part of most set theory descriptions, but is an important aspect for the appliance of sets to polygon operations. + +If a polygon is (arbitrarily) defined as having its vertices in clockwise direction: +- then its interior lies on the right side of the edges [http://gandraxa.com/draw_orthogonal_polygons.aspx] +- and its exterior lies, therefore, on the left side of the edges + +This definition is important for the spatial interpretation sets. + +- If set A describes the interior of a polygon, then Ac, its complement, describes the exterior of a polygon. +- Stated differently, set A is a polygon, all points belonging to A are inside the polygon. Its complement, Ac, contains all points not belonging to A. +- If A is a polygon with its vertices oriented clockwise, Ac is a polygon with the same vertices, but in reverse order, so counter clockwise. Both sets have their points belonging to them at the right side of their edges + +\image html set_a_ac.png + +The last observation is helpful in calculating the difference and the symmetric difference: +- the difference B \ A is defined above by the law B \ A = Ac ∩ B. + In polygon terms it is therefore the intersection of the "reverse of A" with B. + To calculate it, it is enough to have polygon A input in reverse order, and intersect this with polygon B +- the symmetric difference A ∆ B is defined above by the law (B \ A) ∪ (A \ B), which leads to + (Ac ∩ B) ∪ (Bc ∩ A). + To calculate the symmetric difference, it is enough to have polygon A input in reverse order, + intersect this with polygon B, store the result; then have polygon B input in reverse order, + intersect this with polygon A, add this to the result and this is the symmetric difference. + The combination of both sub-results does not have to be intersected as it is only touching + on vertices and do not have overlaps. + + +\section sets_par4 Implementation of intersection and union +All spatial set-theoretic operations are implemented in shared code. There is hardly any difference in code +between the calculation of an intersection or a union. The only difference is that at each intersection point, +for an intersection the right turn should be taken. For union the left turn should be taken. + +\image html set_int_right_union_left.png + + +This is implemented as such in GGL. The turn to be taken is a variable. + +There is an alternative to calculate union as well: +- the union A ∪ B equals to the complement of the intersection of the complements of the inputs, + (Ac ∩ Bc)c (De Morgan law, + http://en.wikipedia.org/wiki/Algebra_of_sets#Some_additional_laws_for_complements) + +There is an additional difference in the handling of disjoint holes (holes which are not intersected). This is also +implemented in the same generic way (the implementation will still be tweaked a little to have it even more generic). + +For a counter clockwise polygon, the behaviour is the reverse: for intersection take the left path, for union +take the right path. This is a trivial thing to implement, but it still has to be done (as the orientation was introduced +in a later phase in GGL). + + +\section sets_par5 Iterating forward or reverse +As explained above, for a difference, the vertices of the first polygon should be iterated by a forward iterator, but +the vertices of the second polygon should be iterated by a reverse iterator (or vice versa). This (trivial) implementation +still has to be done. It will not be implemented by creating a copy, reversing it, and presenting it as input to the +set operation (as outlined above). That is easy and will work but has a performance penalty. Instead a reversible iterator will used, +extended from Boost.Range iterators, and decorating a Boost.Range iterator at the same time, which can travel forward or backward. + +It is currently named \b reversible_view and usage looks like: + +\code + +template +void walk(Range const & range) +{ + typedef reversible_view view_type; + view_type view(range); + + typename boost::range_const_iterator::type it; + for (it = boost::begin(view); it != boost::end(view); ++it) + { + // do something + } +} + +walk<1>(range); // forward +walk<-1>(range); // backward + +\endcode + + +\section sets_par6 Characteristics of the intersection algorithm +The algorithm is a modern variant of the graph traversal algorithm, after Weiler-Atherton +(http://en.wikipedia.org/wiki/Weiler-Atherton_clipping_algorithm). + +It has the following characteristics (part of these points are deviations from Weiler-Atherton) +- No copy is necessary (the original Weiler-Atherton, and its descendants, insert intersections in (linked) lists, + which require to make first copies of both input geometries). +- All turning points (which are intersection points with side/turn information) are unaware of the context, so we have (and need) no information about + if, before the intersection point, a segment was inside or outside of the other geometry +- It can do intersections, unions, symmetric differences, differences +- It can handle polygons with holes, non-convex polygons, polygons-with-polygons, polygons-with-boxes (clip), rings, multi-polygons +- It can handle one polygon at the time (resolve self-intersections), two polygons (the normal use case), or more polygons (applicable + for intersections and unions) +- It can handle clockwise and counter-clockwise geometries + + +\section sets_par7 Outline of the intersection algorithm +The actual implementation consists of the next phases. + +\b 1 the input geometries are indexed (if necessary). Currently we use monotonic sections for the index. It is done +by the algorithm \b sectionalize. Sections are created is done on the fly, so no preparation is required before (though this would improve +performance - it is possible that there will be an alternative variant where prepared sections or other indexes are part of the input). +For box-polygon this phase is not necessary and skipped. Sectionalizing is done in linear time. + +\b 2, intersection points are calculated. Segments of polygon A are compared with segments of polygon B. Segment intersection is only +done for segments in overlapping sections. Intersection points are not inserted into the original polygon or in a copy. A linked list is therefore not necessary. +This phase is called \b get_intersection_points. This function can currently be used for one or two input geometries, for self-intersection +or for intersection. +Because found intersections are provided with intersection-information, including a reference to their source, it is possible (but currently not +implemented) to have more than two geometry inputs. + +The complexity of getting the intersections is (much) less than quadratic (n*m) because of the monotonic sections. The exact complexity depends on +the number of sections, of how the input polygons look like. In a worst case scenario, there are only two monotonic sections per polygon and both +overlap. The complexity is then quadratic. However, the sectionalize algorithm has a maximum number of segments per section, so for large polygons +there are always more monotonic sections and in those cases they do not overlap by the definition of "monotonic". +For boxes, the complexity is linear time. + +To give another idea of how sections and indexes work: +For a test processing 3918 polygons (but not processing those of which envelopes do not overlap): +- brute force (O(n2)): 11856331 combinations +- monotonic sections: 213732 combinations (55 times less) +- a spatial index: 34877 combinations (1/6 of using monotonic sections) +So there can still be gained some performance by another index. However the current spatial index implementation (in an extension, +not in Formal Review) will still be revisited, so it is currently not used. + +In "normal" cases 84% of the time is spent on finding intersection points. These divisions in %'s refers to the performance test described elsewhere + +One piece of information per intersection points is if it is \b trivial. It is trivial if the intersection is not located at segment end points. + +\b 3, the found intersection points are merged (\b merge_intersection_points), and some intersections can be deleted (e.g. in case of +collinearities). This merge process consists of sorting the intersection points in X (major) and Y (minor) direction, and merging intersections with a common location together. Intersections with common +locations do occur as soon as segments are collinear or meet at their end points. +This phase is skipped if all intersection points are trivial. + +About 6% is spent on merging. + +\b 4, some turns need to be adapted. If segments intersect in their interiors, this is never necessary. However, if segments intersect on their +end points, it is sometimes necessary to change "side" information to "turn" information. This phase is called \b adapt_turns. + +The image below gives one example when adapting turns is necessary. There is side information, both segments have sides \b left and \b right, there +is also \b collinear. +However, for an intersection no turn should be taken at all, so no right turn. For a union, both polygons have to be travelled. +In this case the side information is adapted to turn information, both turns will be \b left. This phase is skipped if all intersection points are trivial. + +\image html set_adapt_turns.png + + +\b 5, the merged intersection points are enriched (\b enrich_intersection_points) with information about a.o. the next intersection point (travel information). + +About 3% is spent on enrichment. + +\b 6, polygons are traversed (\b traverse) using the intersection points, enriched with travel information. The input polygons are traversed and +at all intersection poitns a direction is taken, left for union, right for intersection point (for counter clockwise polygons this is the other way +round). In some cases separate rings are produced. In some cases new holes are formed. + +About 6% is spent on traversal. + +\b 7, the created rings are assembled (\b assemble) into polygon(s) with exterior rings and interior rings. Even if there are no intersection points found, this process can be important to find containment and coverage. + +Timing of this phase is not yet available, as the comparison program work on rings. + + +*/ + +#endif // _DOXYGEN_SETS_HPP diff --git a/doc/doxygen_input/pages/doxygen_c_strategy_rationale.hpp b/doc/doxygen_input/pages/doxygen_c_strategy_rationale.hpp new file mode 100644 index 000000000..e72c83340 --- /dev/null +++ b/doc/doxygen_input/pages/doxygen_c_strategy_rationale.hpp @@ -0,0 +1,79 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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_STRATEGY_RATIONALE_HPP +#define _DOXYGEN_STRATEGY_RATIONALE_HPP + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page strategy Strategy rationale + + +\section strpar1 Purpose of strategies + +A strategy is (Wikipedia, http://en.wikipedia.org/wiki/Strategy_pattern) a software design pattern whereby algorithms can be selected at runtime. According to Wikipedia, it is also known as the Policy pattern. In the C++ template contexts, policies are usually meant as selecting functionality at compile time. so it is reasonable to state that a strategy can also be used at compile-time + +Within GGL the term policy is used (sparsely), but in a broader, or in another context. The term Strategy is used specificly for a computation method targeted to a specific coordinate system + +GGL-Strategies do have the following purposes: + - for each coordinate system, a default strategy is selected by compile time, using the coordinate system tag. This is effectively tag dispatching. + - users can override the default choice by using the overloaded function, which has a strategy as an extra parameter, and take another strategy + - users can override the default choice by using the overloaded function, to use the default strategy, but constructed with specific parameters + - users can override the default choice by using the overloaded function, to use the default strategy (which can be a templated structure), with other template parameters then the default ones + - users can override the default choice by using the overloaded function, to use the default strategy (which can be a templated structure), with other template parameters then the default ones, with the specific purpose as to select another calculation type (e.g. GMP or another big number type) + +All this happens at compile-time. + +For example (this is also explained in the design rationale) the distance functionality. The default distance strategy for point-point is Pythagoras (for cartesian coordinate systems) or Haversine (for spherical) or Andoyer (for geographic). Haversine works on the unit sphere, radius 1. Library users can use the distance function, specifying haversine strategy constructed with a radius of 2. Or they can use the distance function, specifying the more precise Vincenty strategy (for geographic coordinate systems, but that might not even be checked there). Specifying strategies is useful, even if not point-point distance is to be calculated, but e.g. point-polygon distance. In the end it will call the elementary specified functionality. Note that, for this example, the point-segment distance strategy is also "elementary". Note also that it can have an optional template parameter defining the underlying point-point-distance-strategy. + +\section strpar2 Properties of strategies + +Because strategies can be constructed outside the calling function, they can be specified as an optional parameter (implemented as an overloaded function), and not as only a template-parameter. Furthermore, strategies might be used several times, in several function calls. Therefore they are declared as const reference parameter, they should be stateless (besides construction information). + +The strategy needs to access construction information (member variables), its calculation method is therefore usually not a static method but a non-static const method. It can then access member variables, while still being const, non-mutable, stateless, being able to be called across several function calls. +If often has to keep some calculation information (state), so it should (for some algorithms) declare a state_type. In those cases, that state_type is instantiated before first call and specified in each call. +The calculation method is always called \b apply (as convention in GGL) and gets the most elementary information as a parameter: a point, a segment, a range. It depends on the algorithm and, sometimes, on the source geometry passed. That should actually be the case as least as possible +In most cases, there is an additional method \b result which returns the calculated result. That result-method is a also non-static const method, and the state is passed. +Note that the methods might be non-static const, but they might also be static. That is not checked by the concept-checker. + +A strategy for a specific algorithm has a concept. The distance-strategy should follow the distance-strategy-concept. The point-in-polygon strategy should follow the point-in-polygon-strategy-concept. Those concepts are not modelled as traits classes (contrary to the geometries). The reason for this is that it seems not necessary to use legacy classes as concepts, without modification. A wrapper can be built. So the strategies should have a method \b apply and should define some types. + +Which types, and which additional methods (often a method \b result), is dependant on the algorithm / type of strategy. + +Strategies are checked by a strategy-concept-checker. For this checker (and sometimes for checking alone), they should define some types. Because if no types are defined, the methods cannot be checked at compile time... The strategy-concept-checkers are thus implemented per algorithm and they use the Boost Concept Check Library for checking. + +So as explained above, the essence of the design is: +- function determines default-strategy, or is called with specified strategy +- function calls dispatch (dispatching is done on geometry_tag) +- dispatch calls implementation (in namespace detail), which can be shared for different geometry types and for single/multi +- implementation calls strategy (if applicable), with the smallest common (geometric) element applicable for all calculation method, the common denominator + +\section strpar3 Alternative designs + +Some calculations (strategies) might need to take the whole geometry, instead of working on point-per-point or segment-per-segment base. This would bypass the dispatch functionality. Because all strategies would take the whole geometry, it is not necessary to dispatch per geometry type. In fact this dispatching on geometry-type is moved to the strategy_traits class (which are specialized per coordinate system in the current design). So in this alternative design, the strategy traits class specializes on both geometry-tag and coordinate-system-tag, to select the default strategy. +For the default strategy, this move from "dispatch" to another dispatch called "strategy_XXX" (XXX is the algorithm) might make sense. However, if library users would call the overloaded function and specify a strategy, the only thing what would happen is that that specified strategy is called. So, for example: +\code +template +bool within(G1 const& g1, G2 const& g2, S& const strategy) +{ + return strategy.apply(g1, g2); +} +\endcode + +The library user could call just this strategy.apply(..) method directly. If more strategies are provided by the library or its extensions, +it would still make sense: the user can still call \b within and does not have to call the \b apply method of the strategy. + +The convex hull strategy currently works on a whole geometry. However, it is possible that it will be reshaped to work per range (the algorithm +internally works per range), plus a mechanism to pass ranges multiple times (it currently is two-pass). + + +*/ + +#endif // _DOXYGEN_STRATEGY_RATIONALE_HPP diff --git a/doc/doxygen_input/pages/doxygen_d_robustness.hpp b/doc/doxygen_input/pages/doxygen_d_robustness.hpp new file mode 100644 index 000000000..4646ef4c6 --- /dev/null +++ b/doc/doxygen_input/pages/doxygen_d_robustness.hpp @@ -0,0 +1,150 @@ +// Boost.Geometry (aka Boost.Geometry, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// 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_ROBUSTNESS_HPP +#define _DOXYGEN_ROBUSTNESS_HPP + +/--------------------------------------------------------------------------------------------------- + +/*! +\page robustness Boost.Geometry and Robustness + +\section robustness_par1 Introduction + +Floating point coordinates have limited precision. Geometry algorithms have to take this into account. + +If differences between points are very small, it may lead to false result of a mathematical calculation performed on such points, what in turn, may cause algorithm result as inadequate to actual geometric situation. For example, a point which is located left from a segment, but \b very close to it, can be reported on that segment or right from it. Also if differences are a little larger, artifacts can be shown in geometric algorithms. + +See for more backgrounds e.g.: + +- Classroom Examples of Robustness Problems in Geometric Computations +- Robust Predicates and Degeneracy + +Boost.Geometry is aware of these issues and provides several approaches to minimize the problems, or avoid them completely using + +- GMP +- CLN + + +\section robustness_par2 Example + +An example. Consider the elongated triangle and box below. + +\image html robust_triangle_box.png + +The left edge of the triangle has a length of about the precision of the floating point grid. It is not possible to do this intersection correctly, using floating point. No library (using floating point) can do that, by nature of float point numerical representation. It is not possible to express the four different coordinates in the resulting intersected polygon. Theoretically distinct points will be assigned to the very same location. + +Also if the left edge is longer than that, or using double coordinates, those effects will be there. And of course not only in triangles, but any spiky feature in a polygon can result in non representable coordinates or zero-length edges. + +\section robustness_par3 Coordinate types + +All geometry types provided by Boost.Geometry, and types by the user, do have a coordinate type. For example + +\code +boost::geometry::point_xy p1; +boost::geometry::point_xy p2; +boost::geometry::point_xy p3; +\endcode + +describes three points with different coordinate types, +a 32 bits float, +a 64 bits double, +a long double, not standardized by IEEE and is on some machines 96 bits (using a MSVC compiler it is a synonym for a double). + +By default, algorithms select the coordinate type of the input geometries. If there are two input geometries, and they have different coordinate types, the coordinate type with the most precision is selected. This is done by the meta-function \b select_most_precise. + +Boost.Geometry supports also high precision arithmetic types, by adaption. The numeric_adaptor, used for adaption, is not part of Boost.Geometry itself but developed by us and sent (as preview) to the Boost List (as it turned out, that functionality might also be provided by Boost.Math bindings, but the mechanism is the same). Types from the following libraries are supported: + +- GMP (http://gmplib.org) +- CLN (http://www.ginac.de/CLN) + +Note that the libraries themselves are not included in Boost.Geometry, they are completely independant of each other. + +These numeric types can be used as following: +\code +boost::geometry::point_xy p4; +boost::geometry::point_xy p5; +\endcode + +All algorithms using these points will use the \b GMP resp. \b CLN library for calculations. + +\section robustness_par4 Calculation types + +If high precision arithmetic types are used as shown above, coordinates are stored in these points. That is not always necessary. Therefore, Boost.Geometry provides a second approach. It is possible to specify that only the calculation is done in high precision. This is done by specifying a strategy. For example, in area: + +Example: + The code below shows the calculation of the area. Points are stored in double; calculation is done using \b GMP + +\code + { + typedef boost::geometry::point_xy point_type; + boost::geometry::linear_ring ring; + ring.push_back(boost::geometry::make(0.0, 0.0)); + ring.push_back(boost::geometry::make(0.0, 0.0012)); + ring.push_back(boost::geometry::make(1234567.89012345, 0.0)); + ring.push_back(ring.front()); + + typedef boost::numeric_adaptor::gmp_value_type gmp; + + gmp area = boost::geometry::area(ring, boost::geometry::strategy::area::by_triangles()); + std::cout << area << std::endl; + } +\endcode + +Above shows how this is used to use \b GMP or \b CLN for double coordinates. Exactly the same mechanism works (of course) also to do calculation in double, where coordinates are stored in float. + +\section robustness_par5 Strategies + +In the previous section was shown that strategies have an optional template parameter \b CalculationType so enhance precision. However, the design of Boost.Geometry also allows that the user can implement a strategy himself. In that case he can implement the necessary predicates, or use the necessary floating point types, or even go to integer and back. Whatever he prefers. + +\section robustness_par6 Examples + +We show here some things which can occur in challenging domains. + +The image below is drawn in PowerPoint to predict what would happen at an intersection of two triangles using float coordinates in the range 1e-45. + +\image html robust_float.png + +If we perform the intersection using Boost.Geometry, we get the effect that is presented on the pictures below, using float (left) and using double (right). + +\image html robust_triangles.png + +This shows how double can solve issues which might be present in float. However, there are also cases which cannot be solved by double or long double. And there are also cases which give more deviations than just a move of the intersection points. + +We investigated this and created an artificial case. In this case, there are two stars, they are the same but one of them is rotated over an interval of about 1e-44. When those stars are intersected, the current Boost.Geometry implementation using float, double or long double will give some artifacts. + +Those artifacts are caused by taking the wrong paths on points where distances are zero (because they cannot be expressed in the used coordinate systems). + +If using \b GMP or \b CLN, the intersection is correct. + +\image html robust_stars.png + +Note again, these things happen in differences of about 1e-45. We can investigate if they can be reduced or sometimes even solved. However, they belong to the floating point approach, which is not exact. + +For many users, this all is not relevant. Using double they will be able to do all operations without any problems or artefacts. They can occur in real life, where differences are very small, or very large. Those users can use \b GMP to use Boost.Geometry without any problem. + +\section robustness_par7 Future work + +There are several methods to avoid instability and we don't know them all, some of them might be applicable to our algorithms. Therefore is stated that Boost.Geometry is "not checked on 100% robustness". As pointed out in the discussions on the Boost mailing list in spring '09 (a.o. "The dependent concept should explicitely require unlimited precision since the library specifically uses it to *guarantee* robustness. [...] Users should be left with no choice but to pick some external component fulfilling the unlimited precision requirement"), it seems that it is not possible to solve all these issues using any FP number, that it is necessary to use a library as GMP or CLN for this guarantee. + +Therefore we decided to go for supporting high precision numeric types first, and they are currently supported in most algorithms (a.o. area, length, perimeter, distance, centroid, intersection, union). However, we certainly are willing to take other measures as well. + +\section robustness_par8 Summary + +Boost.Geometry approach to support high precision: + +- library users can use points with float, double, or long double coordinates (the default) +- for higher numerical robustness: users can call algorithms using another calculation type (e.g. \b GMP or \b CLN, ...) +- for higher numerical robustness: users can use points with \b GMP or \b CLN coordinates +- users can implement their own implementation and provide this as a strategy, the Boost.Geometry design allows this +- other measures can be implemented, described as future work. + + + +*/ + +#endif // _DOXYGEN_ROBUSTNESS_HPP diff --git a/doc/doxygen_input/pages/doxygen_examples.hpp b/doc/doxygen_input/pages/doxygen_examples.hpp new file mode 100644 index 000000000..d8a893292 --- /dev/null +++ b/doc/doxygen_input/pages/doxygen_examples.hpp @@ -0,0 +1,242 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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_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 07_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 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 x02_numeric_adaptor_example.cpp + +The Numeric Adaptor is recently introduced to the Boost mailing list It is a proxy to high precision +arithmetic libraries such as GMP or CLN. +However, it might be that the same effect can be used using the Boost.Math bindings. + +This example shows how the GGL can be combined with non-numeric value types such as +from the Numeric Adaptor +\image html x02_numeric_adaptor_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 diff --git a/doc/doxygen_input/pages/doxygen_mainpage.hpp b/doc/doxygen_input/pages/doxygen_mainpage.hpp new file mode 100644 index 000000000..b1579b41a --- /dev/null +++ b/doc/doxygen_input/pages/doxygen_mainpage.hpp @@ -0,0 +1,96 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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_MAINPAGE_HPP +#define _DOXYGEN_MAINPAGE_HPP + + +/*! +\mainpage Boost.Geometry + +\section header Boost.Geometry (aka GGL, Generic Geometry Library) + +Copyright © 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands.\n +Copyright © 2008-2009 Bruno Lalande, Paris, France.\n +Copyright © 2009 Mateusz Loskot, Cadcorp, London, UK.\n +Distributed under the Boost Software License, Version 1.0.\n +(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + + +\section intro Introduction +Boost.Geometry, formally accepted by Boost, defines \ref concepts "concepts" for geometries and implements some algorithms on such geometries. Before acceptance by Boost it was known as GGL (Generic Geometry Library) +and this documentation still contains that name on various places. + + +Boost.Geometry contains a dimension-agnostic, coordinate-system-agnostic and scalable kernel, based on concepts, meta-functions and tag- dispatching. +On top of that kernel, algorithms are built: area, length, perimeter, centroid, convex hull, intersection (clipping), within (point in polygon), distance, envelope (bounding box), simplify, transform, convert, and more. The library is also designed to support high precision arithmetic numbers, such as GMP. + +Boost.Geometry contains instantiable geometry classes, but library users can also use their own. Using registration macros or traits classes their geometries can be adapted to fulfil the Boost.Geometry Concepts. + +Boost.Geometry might be used in all domains where geometry plays a role: mapping and GIS, gaming, computer graphics and widgets, robotics, astronomy... The core is designed to be as generic as possible and support those domains. However, for now the development has been mostly GIS-oriented. + +Boost.Geometry supports the extension model, the same way as GIL also applies it. An extension is (mostly) something more specific to domains like mentioned above. + +The library follows existing conventions: +- conventions from boost +- conventions from the std library +- conventions and names from one of the OGC standards on Geometry + +The library can be downloaded from the Boost Sandbox, +go to the \ref download "Download page" for more information. + +A (recently started) Wiki is here: http://trac.osgeo.org/ggl/wiki + +\section quickstart Quick start +It is not possible to show the whole library at a glance. A few very small examples are shown below. + +It should be possible to use a very small part of the library, +for example only the distance between two points. + +\dontinclude doxygen_2.cpp +\skip example_for_main_page() +\skipline int a +\until endl; + +Other often used algorithms are point-in-polygon: +\skipline ring_2d +\until endl; + +or area: +\skip area +\until endl; + +It is possible, by the nature of a template library, to mix the point types declared above: +\skip double d2 +\until endl; + +The pieces above generate this output: +\image html output_main.png + + +It is also possible to use non-Cartesian points. +For example: points on a sphere. When then an algorithm such as distance +is used the library "inspects" that it is handling spherical +points and calculates the distance over the sphere, instead of applying the Pythagorean theorem. + +Finally an example from a totally different domain: developing window-based applications, for example +using QtWidgets. We check if two rectangles overlap and if so, +move the second one to another place: +\skip QRect +\until } + +More examples are on the page \b Examples + + +*/ + + + + + +#endif // _DOXYGEN_MAINPAGE_HPP diff --git a/doc/doxygen_input/pages/doxygen_pages.hpp b/doc/doxygen_input/pages/doxygen_pages.hpp new file mode 100644 index 000000000..cb8ef448b --- /dev/null +++ b/doc/doxygen_input/pages/doxygen_pages.hpp @@ -0,0 +1,431 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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_PAGES_HPP +#define _DOXYGEN_PAGES_HPP + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page compat Relation to Boost and std libraries + +\section boost_compat Boost + +The GGL makes use of the following Boost Libraries: +- Boost Range +- Boost Type Traits (e.g. remove_const) +- Boost Concept Check Library +- Boost Numeric Conversion (cast, bounds) +- Boost MPL +- Boost Static Assert +- Boost Iterator +- Boost Smart Pointer (shared_ptr, in the extensions spatial index and projections) +- Boost uBLAS +- Adapted geometries: + - Boost Array + - Boost Tuple +- IO and parsing + - Boost Tokenizer + - Boost Conversion (lexical cast) + - Boost String Algo +- Testing + - Boost Test + - Boost Timer +- Examples + - Boost Graph Library + + +Many of these are used a lot inside the library. + +The \b Boost.Range library is used everywhere +to declare iterators and to walk through standard containers or custom ranges. + +The \b Boost \b Concept \b Check \b Library is used to check concepts, for geometries as well +as for strategies. + +Tranformations are implemented using \b Boost uBLAS + +\b MPL is used for a.o. reverse dispatching + +Finally, the library can perfectly be used together with the \b Boost \b Graph \b Library, as shown in example 7. + + +\section std_compat std:: library + + +The GGL makes substantial use of the std library, and is designed to be compatible with it. +- provided geometries (linestring, ring, polygon, multi-s) make default use of std::vector (but that is configurable) +- std sorting, unique copies, maps can make use of provided functors in \ref compare "compare". +- internally, there are vector's, deque's, there is sorting, many things are implemented using the std library + +*/ + + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page compiling Compiling + +\section compiling_intro Compiling Boost.Geometry + +Boost.Geometry is a Header Only library. So just including the headerfiles is enough +to use the algorithms. Nothing has to be linked. + +Boost.Geometry is only dependant on (header only) Boost libraries. Download the Boost +Library Collection from www.boost.org, adapt the include path to include Boost. + +\section platforms Platforms + +The library currently compiles successfully on the following platforms: +- MS Visual Studio 2008 (Express Edition) +- MS Visual Studio 2005 (Express Edition) +- gcc version 3.4 +- gcc version 4 (tested are 4.1, 4.2, 4.4) + +For Visual Studio, the examples contains some project files (for 2005). However, because the library + is header only, it will be no problem to integrate it in your own project files. + +The test and example folders contain also Jam-files for bjam / boost-build + +For gcc, the flag -Wno-long-long can be used (surpressing warnings originating from Boost) + +\section convenient_includes Convenient includes + +This section concentrates on how to include GGL. + +The most convenient headerfile including all algorithms and strategies is geometry.hpp: +- \#include It is recommended to include this file. +Alternatively, it is possible to include GGL headerfiles separately. However, this is inconvenient as files might +be renamed or moved occasionaly. + + +An often used headerfile is geometries.hpp: +- \#include This includes all default geometries: point, linestring, + polygon, linear_ring, box. It is not included in the "geometry.hpp" headerfile because + users are allowed to use their own geometries. However, for library users who want to use the provided + geometries it is most useful. + + +For users using only Cartesian points, with floating point coordinates (double), in 2D or 3D, you can use instead: +- \#include This includes all 2D Cartesian geometries: point_2d, linestring_2d, + etc. Using this headerfile the library seems to be a non-template library, so it is convenient for users that + are not so into the template world. + +For users using multi-geometries: +- \#include + +\section advanced_includes Advanced includes + +This section is for users who have their own geometries and want to use algorithms from the Boost.Geometry. + + +If you want to use your own points it makes sense to use the registration macro's: +- \#include macro's for point registration +- \#include macro's for box registration + + +If you are using standard containers containing points and want to handle them as a linestring +- \#include allows you to use things like \c std::vector + and put them as parameters into algorithms. + +If you are using boost tuples and want to handle them as Cartesian points +- \#include + + +\section extension_includes Extensions +The GGL is currently (since 0.5) split into the kernel and several extensions. As this split is relatively new, +there are not yet umbrella-include files, but most things below will do: + +If you want to use the \b geographic coordinate system: +- the tag is already included in the kernel +- \#include for Andoyer distance calculations +- \#include for Vincenty distance calculations + +If you want to use the \b projections: +- \#include +- \#include +- \#include + +If you want to use the \b circle (n-sphere) +- \#include Several headerfiles, there is not yet a common include + + + +\section performance Performance finetuning +The enumeration below is not exhaustive but can contain hints to improve the performance +- For Microsoft, set the define _SECURE_SCL=0 +- For Microsoft, set the define _HAS_ITERATOR_DEBUGGING=0 +- our measurements indicate that MSVC 2005 generates faster code than MSVC 2008 +- Using StlPort results in significant faster code than Microsoft's standard library +- Of course turn on compiler optimizations, compile in release mode + +\section intellisense Intellisense issues +Microsoft Visual Studio (Express) 2005 and 2008 can hang typing in a bracket or angle bracket. +This is not directly related to GGL, but caused by heavy templated libraries such as Boost and GGL. +If this is inconvenient, intellisense can easily be turned off: + +(...) disabling Intellisense in VC++. +There is a file called feacp.dll in <VS8INSTALL>/VC/vcpackages folder. +Renaming this file will disable Intellisense feature. + +Source: http://blogs.msdn.com/yash/archive/2007/09/19/intellisense-issues-in-visual-c-2005.aspx + + +*/ + + + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page performance Performance + +The performance has been tested for some algorithms, concluding that Boost.Geometry is highly comparative +(http://trac.osgeo.org/ggl/wiki/Performance). + +\section performance-notes Performance notes +In the page about compiling the library there are some hints provided which might improve the performance. + +Furthermore it is important to realize that if you're about to do calculations with two geometries, for +example a point-in-polygon or an intersection, it is very useful to first calculate and store all bounding +boxes (envelopes), and then before doing a point-in-polygon check if the point is in the bounding box. Checking if a +point is within a box is of course much faster than visiting all vertices of a polygon. + +The storage of bounding boxes is, on purpose, not done within the library because it would break the possibility +to use standard vectors of points for linestrings or rings. The library might get a traits system in the future +where geometries might tell their boundaries to the algorithms, this however would be an optional system. +*/ + + + + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page DSV DSV (Delimiter Separated Values) +DSV is a text representation of a geometry, explained here: http://en.wikipedia.org/wiki/Delimiter-separated_values . +DSV can represent a point, a linestring, a polygon, or multi versions of those. + +It is currently just a utility in the library, used in samples and tests, to get some textual output +of a geometry. + +*/ + +//--------------------------------------------------------------------------------------------------- + + +/*! +\page OGC OGC (Open Geospatial Consortium) +OGC is the Open Geospatial Consortium, the standardization committee +on Geospatial Interoperability and GIS (Geographical Information Systems). +OGC geometries are used in many environments and databases. + +The Generic Geometry Library uses OGC conventions +for algorithms and for geometry type names. Note that though OGC is concentrating on GIS, +the conventions followed here are 'geometry only', the so-called 'simple features' +(simple in the sense that polygons are not allowed to have self-intersections). + +OGC specifies a library based on inheritance, as opposed to this library, which is a generic template based library +where data classes are separated from the algorithms. +Therefore this library is not an OGC implementation in the strict sense. + +\section Classes +OGC defines the following geometry classes, +which are implemented as concepts (and as geometries) in the Generic Geometry Library: +- \ref boost::geometry::point "point": a point. The point defined here is dimensionally agnostic. +Library users does not have to use this point, they might also use their own points as long as it meets the concepts. +- \ref boost::geometry::linestring "linestring": Sequence of point values with linear interpolation +between points. Note that library users does not have to use this type. Algorithms works on iterators, so +all algorithms also accept iterators on a vector (or other container) of points. +- \ref boost::geometry::linear_ring "linear_ring": Sequence of point values with linear interpolation +between points, which is closed and not self-intersecting +- \ref boost::geometry::polygon "polygon": Plane figure, consisting of an outer ring and zero or more +inner rings. So basically a polygon which might have holes. +Note that this definition is different from several other polygon definitions and libraries, +where polygons are not allowed to have holes. These polygons are comparable to the linear_ring above + +And multi-geometries: +- \ref boost::geometry::multi_point "multi_point": collection of points +- \ref boost::geometry::multi_linestring "multi_linestring": collection of linestrings +- \ref boost::geometry::multi_polygon "multi_polygon": collection of polygons + +The naming of these classes is used in: +- WKT (Well-Known Text) +- KML (Google Maps) +- GML +- many GIS/geometry libraries + +and in many databases: +- Oracle Spatial +- SQL Server 2008 +- PostGreSQL +- MySQL +- MonetDB + +Besides this the Generic Geometry Library provides the following additional classes: +- \ref boost::geometry::box "box": Box, used for selections and for envelopes (bounding boxes) +- \ref boost::geometry::segment "segment": Segment, helper class, used for e.g. intersections + +Finally geometry types can be added as extensions. This is e.g. done with an +"n-sphere" meaning "circle" and "sphere". Circle is convenient for selections. + + +\section Differences +The Generic Geometry Library does not implement the OGC Simple Feature interface exactly and completely. +There are many differences. Below the most important differences are listed. +- In OGC all operations are class methods. The Generic Geometry Library is a template library and defines the algorithms +as generic functions. +- In OGC a point is defined by an x-coordinate value, a y-coordinate value and possibly a z-coordinate value +and a measured value. In the Generic Geometry Library the basic point defines coordinates in a neutral way, +so there is no x, no y. +- In OGC all geometries have additional members, such as SRID (spatial reference system id) or isMeasured. These +properties are not defined in the Generic Geometry Library. Library users can implement them, if necessary, +in derived classes. +- In OGC the envelope returns a geometry, in the Generic Geometry Library it returns a box +- The OGC algorithm asText is named "wkt" +- Union and intersection are currently named "X_inserter" to indicate that they + insert there produced geometries (if any) as an OutputIterator + + +More information on OGC can be found on their website, http://www.opengeospatial.org +and on Wikipedia http://en.wikipedia.org/wiki/Open_Geospatial_Consortium +*/ + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page status Status, previews and formal review + +\section introduction Introduction + +Boost.Geometry is accepted by Boost (http://permalink.gmane.org/gmane.comp.lib.boost.announce/246) +after formal review (http://permalink.gmane.org/gmane.comp.lib.boost.announce/239) + +The first preview was a template 2D geometry library providing its own geometries and algorithms working on +those geometries. Those geometries are still provided but not essential anymore. + +The second preview didn't asume points with .x() and .y() anymore. It provided strategies, +operating on specific point types. So point_xy (cartesian points) were +handled different from point_ll (latlong points). That is still the case (now using a coordinate system meta-function) + +The third preview introducted the point concept, library users could use their own points with the algorithms +provided by the library. + +The fourth preview implemented concepts for all geometries. Besides that tag dispatching was +introduced internally. All algorithms were made generic. + +The Formal Review continued with the design of the fourth preview, made it more consistent +(apply everywhere, all implementation within struct's, structs used as building blocks for +multi-implementations, etc). Things were made more conform Boost standards (template parameters, +no tabs, etc). + +\section changes4 Changes since preview 3 +- there are now typedefs for the more common geometries, such as point_2d or ring_ll_deg +- all geometries are optional, everything is working with concepts +- the convex hull algorithm has been added and can be calculated for linestrings (ranges, point sequences), polygons +- map projections (92 !) have been added, they are converted to C++ template classes from PROJ4 +- transformations have been added, to go from one coordinate system to another +- conversions have been added, to go from one geometry type to another (e.g. BOX to POLYGON) +- edit functionality have been added, to edit coordinate values or to add points +- parsing of latitude longitude coordinate values have been added +- the "selected" algorithm have been added +- many examples have been added +- many tests have been added + +\b Breaking \b changes +Because the library was in preview, and it still is, there are some major changes which might influence library user's +code. Although there are many changes internally, the changes for users should be relatively small: +- all algorithms accepting linestrings are now modified to get the linestring itself. In the previous version + .begin(), end() had to be specified, This is not necessary anymore, because the Boost Range Library is used + internally, and tag dispatching is used to distinguish different geometries +- the "grow" utility is now splitted into buffer (growing a box with a value was in fact a buffer) and a combine. +- there was a generic "get" function with a const ref and a non const ref. This is splitted into "get" and "set" +- there might be more changes, please contact if anything is unclear + +\section changes5 Changes since preview 4 +There are the following changes: +- implementation of spatial set relations (intersection, union) +- implementation of some spatial boolean relations (disjoint, equal, intersects, overlaps) +- move of GIS-specific code to extension/gis +- move of map projections to extensions/gis/projections +- implementation of SVG in extensions/SVG +- review of all code, conform Boost code guidelines, no tabs, template parameters, etc. +- other small changes. + +\b Breaking \b changes +- there is now distinction between functions using an output iterator, and functions + resulting in modifying geometries. Functions using an output iterator are called _inserter, + so convex_hull_inserter inserts points (the hull) into something. +- many headerfiles are moved and/or renamed +- strategies now define a method \b apply, in previous versions this was \b operator() + this only influences your code if you've made strategies yourself +- ... + + +\section changes6 Changes since formal review +- namespace changes +- intersection: fixed Access Violoation which could occur at wrongly oriented input +- intersection: fixed omitting outer polygon if it was equal +- intersection: performance improvement, non quadratic behaviour on monotonic sections +- intersection: now supporting GMP and CLN number types + (there are still some comparisons causing implicit casts to double, which will be removed) +- intersection: support of input consisting of pointer-types +- small other changes (strategies transform and intersection do now have apply instead of operator() and relate) + + +If people are interested in helping with the library, be it by coding, by testing, by commenting or otherwise, they +are very welcome. + +\section history History +Geodan started in 1995 with a Geographic Library, called geolib or also GGL (Geodan Geographic Library). +Since then hundreds of projects have +been done using this geolib, and the geolib have been extended to fit the needs of its users. Geolib +can be used in different environments: in Windows applications, as a DLL (ggl32.dll), in +Web Map Servers (SclMapServer), Web Feature Servers or more specific programs. + +In 2007-2009 the Geometry part has been revised and completely templatized. +From 2008 Bruno Lalande, already a Boost contributor, joined and helped +to make the library more generic and to define clear concepts. +It was later now called Generic Geometry Library (GGL). +From 2009 Mateusz Loskot, an active member of Geospatial Open Source communities, +joined and helped with reviewing code, guidelines, WKB, iterators, and the Wiki and ticket system (http://trac.osgeo.org/ggl) + +The library is now called Boost.Geometry (formerly: Generic Geometry Library, abbreviated to GGL). +Boost.Geometry is Open Source and is accepted by Boost libraries. + + +*/ + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page download Download Boost.Geometry + +The library can be downloaded from Boost SVN. There is anonymous SVN access. + +The command + +svn co https://svn.boost.org/svn/boost/sandbox/geometry geometry + +will download the library to your machine. + +The library can also be downloaded from Geodan SVN. This will be moved to osgeo SVN + +*/ + + + + + +#endif // _DOXYGEN_PAGES_HPP diff --git a/doc/doxygen_input/pages/doxygen_z_article09.hpp b/doc/doxygen_input/pages/doxygen_z_article09.hpp new file mode 100644 index 000000000..e68451c58 --- /dev/null +++ b/doc/doxygen_input/pages/doxygen_z_article09.hpp @@ -0,0 +1,238 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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_ARTICLE2009_HPP +#define _DOXYGEN_ARTICLE2009_HPP + + +//--------------------------------------------------------------------------------------------------- + +/*! +\page art09 A Generic Geometry Library (web-copy of article for BoostCon'09) + + +Authors: +- Barend Gehrels +- Bruno Lalande + +This page is a web-version of the article A Generic Geometry Library, for BoostCon'09. + +Note: this article is written December 2008, it is not updated (besides the namespace). There might be some things out of date. But most things are still as described here, be it that the Geographic stuff is moved to an extension. + +\section art09_abstract Abstract +The Generic Geometry Library (GGL) is a library for geometry and geography. It is based on templates and static polymorphism. It is agnostic in coordinate space, coordinate system, and dimensions. The library is non intrusive and uses concepts for geometries for its algorithms. Developers can either use the provided geometries or define or use their own geometry types and specializations. Essential algorithms such as distance calculations, area calculations, point in polygon calculations are available. A geometry library like described would be a valuable addition to the Boost Library Collection. + +\section art09_intro Introduction +The Boost Library Collection currently still does not have any geometry library. In the past years several discussions and previews have been published on the Boost Mailing Lists. There is certainly interest for a library handling geometry within the Boost community; it would be valuable if geometry algorithms are available for the Boost users. Such algorithms are for instance: the distance between two points, the area of a polygon, or determining if a point is in a polygon. +Geometry is used in many disciplines and there are many approaches possible. Depending on their interest programmers feel other needs. Developers creating games will need other geometries, other algorithms, other dimensions and coordinate representations than developers creating CAD, geographic applications, astronomic or control software for robotics. Besides that, programmers have their personal flavors. + + +It is a major challenge to develop a consistent library containing every aspect of geometry, on which everyone agrees. +This article describes one attempt of a geometry library. The Generic Geometry Library (GGL) developed and restyled in 2008 has been presented, at the time of writing, as a preview three times. With the feedback from the Boost community the library is enhanced and extended, it has been changed a lot and the library is better than it was before. It is still in preview phase and not yet reviewed nor accepted. There are other candidate libraries for geometry as well. This paper describes the characteristics and basic principles of the Generic Geometry Library. +The Generic Geometry Library has been initiated by Geodan. Geodan is a company for Geographic Information Systems. Bruno Lalande, who has contributed to Boost libraries before, joined the team of developers. + +\section art09_concepts Geometry Concepts + +A geometry library should define geometry concepts and should implement algorithms working with those concepts. The library can then handle any geometry type modeled according to the concept. +The task of selecting geometries and giving them proper names can already be a challenge and a subject for much discussion. The Wikipedia list of geometric shapes contains more than 30 different polygons, furthermore a dozen of triangles, rectangles, squares, kites, trapezoids, circles, ellipses, three dimensional shapes as polyhedrons, spheres. The list is probably never ending. +The Generic Geometry Library is not attempting to create concepts for all these shapes. Instead, it models four concepts of basic geometries: +- a point +- a sequence of points (a linestring) +- a point sequence which is closed (a (linear) ring) +- a polygon (an outer ring which can optionally contain inner rings, also called donuts or holes) + +With those four concepts, all two dimensional shapes composed of straight line segments (triangles, rectangular and polygonal, etc.) can be built. How to handle curved geometries in two dimensions is not yet worked out. An equivalent system might be used where segments between three points are marked as curved. +The Generic Geometry Library defines concepts and provides default implementations of these concepts. Besides these predefined types, other types can be handled as well. Any point type that defines the required properties, at compile-time, and thus satisfies the point concept requirements can be used. +The linear ring and the linestring concepts follow Boost Range Library concepts. Ranges are used to iterate through sequences of points. Therefore algorithms as length or area also work on a std::vector of points. The names of these concepts and of the provided geometries are consistent with the naming system of the OGC, described below. The names are also used for tags related to the tag dispatching mechanism, which is used internally to distinguish geometry types. +For convenience three other concepts are defined: +- a box: to be able to select things, for spatial indexing, and to keep track of boundaries of geometries +- an n-sphere: circle or sphere, to be able to select things +- a segment: a part of line bounded by two points, to calculate e.g. distances and intersections + +Besides defining custom types, library users can make specializations of algorithms for their geometry types and in such way implement support for, for example, triangles. This will be worked out below. +The Boost Concept Check Library (BCCL) is used internally to check if the developer’s input follows the concepts expected by the library. + + + +\section art09_dim Dimensions +The Generic Geometry Library is basically agnostic in its dimensions. A point is templatized by the number of dimensions, by coordinate type (integer, float, double, GMP), and by the coordinate system. +Examples: +- point: a point in two dimensions +- point: a point in three dimensions +- polygon< point > >: a spherical polygon, measured in radians + +Although points of any dimensions can be created, most algorithms are currently not prepared to handle all possible dimensions. Most algorithms that are provided handle points in Cartesian, Geographic or Spherical coordinate systems. +A template parameter defining how to handle calculations in algorithms using big number types might be added in the future. + + +\section art09_cs Coordinate systems +A generic library handling geometry should be neutral in its coordinate space. In geography, points can be specified using X and Y (and Z), but also using Latitude and Longitude (and Height). In other disciplines there might be need for other names, for example: red, green and blue (defining colors in a color cube), or right ascension and declination (in astronomy). +The concepts of the Generic Geometry Library use therefore neutral names (get and set) for accessing and modifying coordinates. Example, setting a point to (3,2): +\code +boost::geometry::point a; +boost::geometry::set<0>(a, 3); +boost::geometry::set<1>(a, 2); +\endcode + +Or, alternatively: +\code +boost::geometry::assign(a, 3, 2); +\endcode + +These calls are generic. Library users might also choose to use or define more context targeted methods as a.x() and a.y() for setting and getting coordinates, or non default constructors. This as long as they also provide the specializations needed to enable the library to play with points the way shown above. +The Generic Geometry Library provides a generic transform algorithm which can transform geometries from one coordinate system to another. + + +\section art09_types Types And Strategies + +Algorithms depend on coordinate system. Let’s take, for example, the distance calculation between two points. For points in a Cartesian coordinate space the simple and well known Pythagorean theorem applies. For points in the geographic coordinate system (latitude longitude, also known as latlong, lola or ll) the distance can be calculated using the haversine formula (it is possible to select other formulas as well, which is described below). +The Generic Geometry Library provides a tag dispatching system which selects strategies based on coordinate system. So distances and areas for spherical coordinates are internally calculated differently then distances and areas for Cartesian coordinates. This is, by default, not visible for the library user, it is an automatic tag dispatching system. +The tag dispatching system is also used to distinguish geometry types internally. So the generic distance algorithm can get two points (in any coordinate system) as input, but also a point and a linestring, a point and a polygon, et cetera. + +Example showing different strategies for different coordinate systems: +\code +boost::geometry::point_xy a(1,1), b(3,4); +std::cout << boost::geometry::distance(a, b); + +typedef boost::geometry::point_ll<> LL; +LL A, B; +// initialize lat-long coordinates +// e.g., Amsterdam and Barcelona +// ... +std::cout << boost::geometry::distance(A, B); +\endcode +This example uses two different point types. In the first part the Pythagorean theorem is used to calculate the distance between point a and point b. In the second part the distance along the sphere of earth is used (as the crow flies). Note that the non default constructor shown in the first line is not part of the concept; it is part of the implementation (so part of the example above). +As described, distance is calculated using strategies for different coordinate systems. The distance algorithm selects automatically right specialization belonging to the geometry type, and then it selects the strategy belonging to the coordinate system. This strategy is then used for calculation. +Algorithms in the Generic Geometry Library also have an overload where the strategy can be specified by the library user. This is useful for, for example, calculating distance along the earth (or along any sphere). There are several methods for that calculation, using internally either a fast or a precise algorithm. The library user can select such a strategy or can implement his or her own strategy. For example, to use the exact Vincenty geodetic calculation (provided by the library): +\code +std::cout << distance(A, B, + strategy::distance::vincenty()) + << std::endl; +\endcode +Algorithms as simplification (removing non important points from point sequences such that shape is preserved) use, internally, distance calculations. The same mechanism is used there. Therefore simplification works for Cartesian polygons the same as for polygons with geographical coordinates. It is exactly the same implementation. + + +\section art09_specializations Specializations +Besides strategies, library users have also other options for customization. For example: the Generic Geometry Library itself does not support triangles. Instead it supports polygons (which might contain holes) and linear rings. However, if the library user wants to use triangles directly, he can implement his own type. Let’s work this example out. A triangle can be represented by three coordinate pairs. The library user can make a triangle of his own points (in this case: custom_point), using e.g. a boost::array. +\code +struct triangle : public boost::array +{}; +\endcode +The user then has to indicate that this geometry is handled as a linear ring. He therefore has to provide a specialization of the tag metafunction, defining a type for the tag dispatching mechanism. This should reside in the namespace ggl: +\code +namespace ggl +{ + template <> + struct tag + { + typedef ring_tag type; + }; +} +\endcode +As soon as this is done, the library will automatically select the ring specializations for all triangle algorithms. Because the Generic Geometry Library handles a ring as being a range, the user does not have to provide anything more. The Boost Range library concepts are used internally for all iterations. +So the area of the user’s custom-points-triangle will be calculated correctly, using internally an iterator which walks through the point coordinates. +But wait, for triangle that is not as efficient as possible! No problem, the developer can, if desired, implement a specialization for the area function: +\code +template<> +double area(const triangle& t) +{ + return 0.5 * ( + (t[1].x() - t[0].x()) * (t[2].y() - t[0].y()) + - (t[2].x() - t[0].x()) * (t[1].y() - t[0].y()) + ); +} +\endcode + +Now this specialization will be used to calculate the area of the developer’s triangles, while for other algorithms (centroid, within, intersection, et cetera) the generic ring versions still being used. +The Generic Geometry Library also provides a second way to specialize. Within the dispatch namespace, structs are available for all operations. They can be partially specialized such that, for example, a triangle templatized by point type will be handled correctly by the library. + + +\section art09_conventions Names And Conventions + +All geometry types and algorithms are named following the specifications of the Open Geospatial Consortium (OGC). The naming system of the OGC is carefully thought-out and has been agreed upon by a broad community. Additional algorithms and geometry types are named as much as possible using the same conventions and systematics. +OGC conventions, geometry types and spatial operations are widely used, a.o. in spatial databases, such as PostGreSQL, MySQL, Oracle, and SQL Server. +The OGC defines the following algorithms: +- Basic algorithms: dimension, envelope, as_text, as_binary, is_simple, is_empty +- Query algorithms: equals, disjoint, intersects, touches, crosses, within, contains, overlaps, relate, locate_along, locate_between +- Analysis algorithms: distance, buffer, convex_hull, intersection, union, difference, sym_difference +- Geometry type dependant algorithms: area, length, centroid, point_on_surface + +All algorithms are planned to be implemented. Besides this there are some other algorithms provided or planned: +- Simplify, densify, disperse, spline, triangulate +- Coordinate system conversions: transform + +The last one, transform, transforms geometries from any coordinate system to any other coordinate system. For example from radian to degree, but also from spherical to a 3D X,Y,Z coordinate system, or calling a map projection. +Textual representations of geometries (Well-Known Text or WKT) are also provided by the library, as well as the parsing of them. +The OGC also defines geometry types containing a collection of geometries, which are planned to be supported: +- multi_point +- multi_linestring +- multi_polygon + +The Generic Geometry Library is not OGC compliant in the strict sense. It sometimes deviates from the specifications to enable genericity. It uses Boost Range concepts for the linestring geometry type. The library user can therefore use any standard container or Range compatible type as a linestring (a sequence of points). And the output of intersections is, for example, modeled as an output iterator instead of a multi_polygon or a multi_linestring. + + +\section art09_index Spatial Indexes +In geometry or GIS, spatial indexes can be used to search geometries or to enhance or speed up determination of geometry relationships. In 2008, a student, within the framework of the Google Summer of Code, has worked out a first version of a spatial indexing library which uses the Generic Geometry Library. This will be worked out and extended in the future. +The Priority R-Tree, an R-Tree having optimal performance for any query window, will be available for fast searches within a set of geometries. + + +\section art09_proj Map Projections + +The Generic Geometry Library can be used as a generic library for Geographic Information Systems (GIS). It therefore contains map projections. Map projections are algorithms to map the spherical earth to a flat piece of paper. There are many ways to do this. The USGS has implemented over the years 92 projection algorithms, collected in an often used PROJ4 package, written in C. This package is recently fitted into the Generic Geometry Library by converting it to a set of C++ templates. +The projection collection contains both static as dynamic polymorphism. It is possible to instantiate a projection declaring the wished projection itself, for example: +\code +typedef boost::geometry::point_ll > LL; +typedef boost::geometry::point_xy XY; +projection::merc_ellipsoid prj( + "+ellps=WGS84 +lon_0=11.6E"); + +// Define Amsterdam / Barcelona +LL amsterdam, barcelona; +// Initialize A'dam / B'ona +... +XY ma, mb; // Declare points +// and project (from latlong to XY) +if (prj.forward(amsterdam, ma) + && prj.forward(barcelona, mb)) +{ ... } +\endcode + +This will use static polymorphism. Note that the initialization string is conform PROJ4, but it is also possible to initialize projections with e.g. a std::map. +Static polymorphism is also used if the already mentioned transform algorithm provided by the library is used, a generic algorithm for transforming or projecting geometries: + +\code +// declare type UTM zone 30, Cartesian +// using EPSG 2040 +typedef boost::geometry::point_xy > UTM; + +// Assign Amsterdam / Barcelona in UTM +... + +// call generic transformation +boost::geometry::transform (amsterdam, ma); +boost::geometry::transform (barcelona, mb); +\endcode + +EPSG has defined the accepted standard coding for map projections, worldwide, and an EPSG code can be used as a template parameter in the provided EPSG Cartesian coordinate system. +Besides specific instantiation, any projection can also be instantiated using a factory: + +\code +projection::factory fac; +boost::shared_ptr > prj(fac.create_new(parameters)); +\endcode + +The projection instance can now be any projection, created by the factory according to its parameters (which should contain the name of the projection). The instantiated projection-base-class derived class contains virtual methods for forward and inverse projection, but is still also modeled using template parameters for its point types. + + +\section art09_conclusions Conclusions +The Generic Geometry Library as described and published in preview is an extensive generic template geometry library containing many algorithms. It can be used for simple algorithms such as distance calculation but it can also be used in larger contexts such as GIS or Web Mapping applications. It is an Open Source library following the Boost Software License. The Boost Community would profit from a geometry library as described in this article. + + +*/ + +#endif // _DOXYGEN_ARTICLE2009_HPP diff --git a/doc/doxygen_input/sourcecode/boost.vsprops b/doc/doxygen_input/sourcecode/boost.vsprops new file mode 100644 index 000000000..c1d185173 --- /dev/null +++ b/doc/doxygen_input/sourcecode/boost.vsprops @@ -0,0 +1,20 @@ + + + + + + diff --git a/doc/doxygen_input/sourcecode/doxygen_1.cpp b/doc/doxygen_input/sourcecode/doxygen_1.cpp new file mode 100644 index 000000000..5517a1511 --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_1.cpp @@ -0,0 +1,464 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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) +// +// Doxygen Examples, referred to from the sources + +#include + +#if defined(_MSC_VER) +// We deliberately mix float/double's here so turn off warning +#pragma warning( disable : 4244 ) +#endif // defined(_MSC_VER) + +#include +#include +#include +#include + +#include + + +// All functions below are referred to in the source of the Geometry Library. +// Don't rename them. + +void example_area_polygon() +{ + boost::geometry::polygon > poly; + boost::geometry::read_wkt("POLYGON((0 0,0 7,4 2,2 0,0 0))", poly); + std::cout << "Polygon area is " + << boost::geometry::area(poly) + << " square units" << std::endl; + + // Other coordinate system, spherical or geographic (extension) + boost::geometry::polygon > > sph_poly; + boost::geometry::read_wkt("POLYGON((0 0,0 45,45 0,0 0))", sph_poly); + std::cout << "Area is " + << boost::geometry::area(sph_poly) + << " on unit sphere " << std::endl; +} + +void example_as_wkt_point() +{ + typedef boost::geometry::point_xy P; + P p(5.12, 6.34); + // Points can be streamed like this: + std::cout << boost::geometry::dsv

            (p) << std::endl; + + // or like this: + std::cout << boost::geometry::dsv(p) << std::endl; + + // or (with extension) like this: + std::cout << boost::geometry::wkt(p) << std::endl; +} + +void example_as_wkt_vector() +{ + std::vector > v; + boost::geometry::read_wkt >("linestring(1 1,2 2,3 3,4 4)", std::back_inserter(v)); + + std::cout << boost::geometry::dsv(std::make_pair(v.begin(), v.end())) << std::endl; +} + + +void example_centroid_polygon() +{ + boost::geometry::polygon > poly; + boost::geometry::read_wkt("POLYGON((0 0,0 7,4 2,2 0,0 0))", poly); + // Center of polygon might have different type than points of polygon + boost::geometry::point_xy center; + boost::geometry::centroid(poly, center); + std::cout << "Centroid: " << boost::geometry::dsv(center) << std::endl; +} + + +void example_distance_point_point() +{ + boost::geometry::point_xy p1(1, 1); + boost::geometry::point_xy p2(2, 3); + std::cout << "Distance p1-p2 is " + << boost::geometry::distance(p1, p2) + << " units" << std::endl; + + /* + Extension, other coordinate system: + // Read 2 Dutch cities from WKT texts (in decimal degrees) + boost::geometry::point_ll > a, r; + boost::geometry::read_wkt("POINT(4.89222 52.3731)", a); + boost::geometry::read_wkt("POINT(4.47917 51.9308)", r); + + std::cout << "Distance Amsterdam-Rotterdam is " + << boost::geometry::distance(a, r) / 1000.0 + << " kilometers " << std::endl; + */ +} + +void example_distance_point_point_strategy() +{ + /* + Extension, other coordinate system: + typedef boost::geometry::point_ll > LL; + LL a, r; + boost::geometry::read_wkt("POINT(4.89222 52.3731)", a); + boost::geometry::read_wkt("POINT(4.47917 51.9308)", r); + + std::cout << "Distance Amsterdam-Rotterdam is " + << boost::geometry::distance(a, r, + boost::geometry::strategy::distance::vincenty() ) + / 1000.0 + << " kilometers " << std::endl; + */ +} + +void example_from_wkt_point() +{ + boost::geometry::point_xy point; + boost::geometry::read_wkt("Point(1 2)", point); + std::cout << point.x() << "," << point.y() << std::endl; +} + +void example_from_wkt_output_iterator() +{ + std::vector > v; + boost::geometry::read_wkt >("linestring(1 1,2 2,3 3,4 4)", std::back_inserter(v)); + std::cout << "vector has " << v.size() << " coordinates" << std::endl; +} + +void example_from_wkt_linestring() +{ + boost::geometry::linestring > line; + boost::geometry::read_wkt("linestring(1 1,2 2,3 3,4 4)", line); + std::cout << "linestring has " << line.size() << " coordinates" << std::endl; +} + +void example_from_wkt_polygon() +{ + boost::geometry::polygon > poly; + boost::geometry::read_wkt("POLYGON((0 0,0 1,1 1,1 0,0 0))", poly); + std::cout << "Polygon has " << poly.outer().size() << " coordinates in outer ring" << std::endl; +} + +void example_point_ll_convert() +{ + /* + Extension, other coordinate system: + boost::geometry::point_ll > deg(boost::geometry::latitude<>(33.0), boost::geometry::longitude<>(-118.0)); + boost::geometry::point_ll > rad; + boost::geometry::transform(deg, rad); + + std::cout << "point in radians: " << rad << std::endl; + */ +} + +void example_clip_linestring1() +{ + typedef boost::geometry::point_xy P; + boost::geometry::linestring

            line; + boost::geometry::read_wkt("linestring(1.1 1.1, 2.5 2.1, 3.1 3.1, 4.9 1.1, 3.1 1.9)", line); + boost::geometry::box

            cb(P(1.5, 1.5), P(4.5, 2.5)); + std::cout << "Clipped linestring(s) " << std::endl; + + std::vector > intersection; + boost::geometry::intersection_inserter >(cb, line, std::back_inserter(intersection)); +} + +void example_clip_linestring2() +{ + typedef boost::geometry::point_xy P; + std::vector

            vector_in; + boost::geometry::read_wkt

            ("linestring(1.1 1.1, 2.5 2.1, 3.1 3.1, 4.9 1.1, 3.1 1.9)", + std::back_inserter(vector_in)); + + boost::geometry::box

            cb(P(1.5, 1.5), P(4.5, 2.5)); + typedef std::vector > VV; + VV vector_out; + boost::geometry::intersection_inserter >(cb, vector_in, std::back_inserter(vector_out)); + + std::cout << "Clipped vector(s) " << std::endl; + for (VV::const_iterator it = vector_out.begin(); it != vector_out.end(); it++) + { + std::copy(it->begin(), it->end(), std::ostream_iterator

            (std::cout, " ")); + std::cout << std::endl; + } +} + + + + + +void example_intersection_polygon1() +{ + typedef boost::geometry::point_xy P; + typedef std::vector > PV; + + boost::geometry::box

            cb(P(1.5, 1.5), P(4.5, 2.5)); + boost::geometry::polygon

            poly; + boost::geometry::read_wkt("POLYGON((2 1.3,2.4 1.7,2.8 1.8,3.4 1.2,3.7 1.6,3.4 2,4.1 3,5.3 2.6,5.4 1.2,4.9 0.8,2.9 0.7,2 1.3)" + ",(4 2,4.2 1.4,4.8 1.9,4.4 2.2,4 2))", poly); + + PV v; + boost::geometry::intersection_inserter >(cb, poly, std::back_inserter(v)); + + std::cout << "Clipped polygon(s) " << std::endl; + for (PV::const_iterator it = v.begin(); it != v.end(); it++) + { + std::cout << boost::geometry::dsv(*it) << std::endl; + } +} + +void example_simplify_linestring1() +{ + boost::geometry::linestring > line, simplified; + boost::geometry::read_wkt("linestring(1.1 1.1, 2.5 2.1, 3.1 3.1, 4.9 1.1, 3.1 1.9)", line); + boost::geometry::simplify(line, simplified, 0.5); + std::cout + << " original line: " << boost::geometry::dsv(line) << std::endl + << "simplified line: " << boost::geometry::dsv(simplified) << std::endl; +} + +void example_simplify_linestring2() +{ + typedef boost::geometry::point_xy P; + typedef boost::geometry::linestring

            L; + L line; + + boost::geometry::read_wkt("linestring(1.1 1.1, 2.5 2.1, 3.1 3.1, 4.9 1.1, 3.1 1.9)", line); + + typedef boost::geometry::strategy::distance::projected_point DS; + typedef boost::geometry::strategy::simplify::douglas_peucker simplification; + boost::geometry::simplify_inserter(line, std::ostream_iterator

            (std::cout, "\n"), 0.5, simplification()); +} + + + +void example_within() +{ + boost::geometry::polygon > poly; + boost::geometry::read_wkt("POLYGON((0 0,0 7,4 2,2 0,0 0))", poly); + boost::geometry::point_xy point(3, 3); + std::cout << "Point is " + << (boost::geometry::within(point, poly) ? "IN" : "NOT in") + << " polygon" + << std::endl; +} + +/* +void example_within_strategy() +{ + // TO BE UPDATED/FINISHED + typedef boost::geometry::point_xy P; + typedef boost::geometry::polygon

            POLY; + P p; + std::cout << within(p, poly, strategy::within::cross_count

            ) << std::endl; +} +*/ + +void example_length_linestring() +{ + using namespace boost::geometry; + linestring > line; + read_wkt("linestring(0 0,1 1,4 8,3 2)", line); + std::cout << "linestring length is " + << length(line) + << " units" << std::endl; + + /* + Extension, other coordinate system: + // Linestring in latlong, filled with + // explicit degree-minute-second values + typedef point_ll > LL; + linestring line_ll; + line_ll.push_back(LL( + latitude(dms(52, 22, 23)), + longitude(dms(4, 53, 32)))); + line_ll.push_back(LL( + latitude(dms(51, 55, 51)), + longitude(dms(4, 28, 45)))); + line_ll.push_back(LL( + latitude(dms(52, 4, 48)), + longitude(dms(4, 18, 0)))); + std::cout << "linestring length is " + << length(line_ll) / 1000 + << " kilometers " << std::endl; + */ +} + +void example_length_linestring_iterators1() +{ + boost::geometry::linestring > line; + boost::geometry::read_wkt("linestring(0 0,1 1,4 8,3 2)", line); + std::cout << "linestring length is " + << boost::geometry::length(line) + << " units" << std::endl; +} + +void example_length_linestring_iterators2() +{ + std::vector > line; + boost::geometry::read_wkt >("linestring(0 0,1 1,4 8,3 2)", std::back_inserter(line)); + std::cout << "linestring length is " + << boost::geometry::length(line) + << " units" << std::endl; +} + +void example_length_linestring_iterators3() +{ + /* + Extension, other coordinate system: + using namespace boost::geometry; + typedef point_ll > LL; + std::deque line; + boost::geometry::read_wkt("linestring(0 51,1 51,2 52)", std::back_inserter(line)); + std::cout << "linestring length is " + << 0.001 * boost::geometry::length(line, boost::geometry::strategy::distance::vincenty()) + << " kilometers" << std::endl; + */ +} + + +void example_length_linestring_strategy() +{ + /* + Extension, other coordinate system: + using namespace boost::geometry; + typedef point_ll > LL; + linestring line_ll; + line_ll.push_back(LL(latitude(dms(52, 22, 23)), longitude(dms(4, 53, 32)))); + line_ll.push_back(LL(latitude(dms(51, 55, 51)), longitude(dms(4, 28, 45)))); + line_ll.push_back(LL(latitude(dms(52, 4, 48)), longitude(dms(4, 18, 0)))); + std::cout << "linestring length is " + << length(line_ll, strategy::distance::vincenty() )/(1000) + << " kilometers " << std::endl; + */ +} + + +void example_envelope_linestring() +{ + boost::geometry::linestring > line; + boost::geometry::read_wkt("linestring(0 0,1 1,4 8,3 2)", line); + boost::geometry::box > box; + boost::geometry::envelope(line, box); + + std::cout << "envelope is " << boost::geometry::dsv(box) << std::endl; +} + +void example_envelope_polygon() +{ + /* + Extension, other coordinate system: + using namespace boost::geometry; + typedef point_ll > LL; + + // Wrangel island, 180 meridian crossing island above Siberia. + polygon wrangel; + wrangel.outer().push_back(LL(latitude<>(dms(70, 47, 7)), longitude<>(dms(178, 47, 9)))); + wrangel.outer().push_back(LL(latitude<>(dms(71, 14, 0)), longitude<>(dms(177, 28, 33)))); + wrangel.outer().push_back(LL(latitude<>(dms(71, 34, 24)), longitude<>(dms(179, 44, 37)))); + // Close it + wrangel.outer().push_back(wrangel.outer().front()); + + boost::geometry::box box; + boost::geometry::envelope(wrangel, box); + + dms minlat(box.min_corner().lat()); + dms minlon(box.min_corner().lon()); + + dms maxlat(box.max_corner().lat()); + dms maxlon(box.max_corner().lon()); + + std::cout << wrangel << std::endl; + std::cout << "min: " << minlat.get_dms() << " , " << minlon.get_dms() << std::endl; + std::cout << "max: " << maxlat.get_dms() << " , " << maxlon.get_dms() << std::endl; + */ +} + + +void example_dms() +{ + /* + Extension, other coordinate system: + // Construction with degree/minute/seconds + boost::geometry::dms d1(4, 53, 32.5); + + // Explicit conversion to double. + std::cout << d1.as_value() << std::endl; + + // Conversion to string, with optional strings + std::cout << d1.get_dms(" deg ", " min ", " sec") << std::endl; + + // Combination with latitude/longitude and cardinal directions + { + using namespace boost::geometry; + point_ll > canberra( + latitude<>(dms(35, 18, 27)), + longitude<>(dms(149, 7, 27.9))); + std::cout << canberra << std::endl; + } + */ +} + +void example_point_ll_construct() +{ + /* + Extension, other coordinate system: + using namespace boost::geometry; + typedef point_ll > ll; + + // Constructions in both orders possible + ll juneau( + latitude<>(dms(58, 21, 5)), + longitude<>(dms(134, 30, 42))); + ll wladiwostok( + longitude<>(dms(131, 54)), + latitude<>(dms(43, 8)) + ); + */ +} + + + +int main(void) +{ + example_area_polygon(); + + example_centroid_polygon(); + + example_distance_point_point(); + example_distance_point_point_strategy(); + + example_from_wkt_point(); + example_from_wkt_output_iterator(); + example_from_wkt_linestring(); + example_from_wkt_polygon(); + + example_as_wkt_point(); + + example_clip_linestring1(); + example_clip_linestring2(); + example_intersection_polygon1(); + + example_simplify_linestring1(); + example_simplify_linestring2(); + + example_length_linestring(); + example_length_linestring_iterators1(); + example_length_linestring_iterators2(); + example_length_linestring_iterators3(); + example_length_linestring_strategy(); + + example_envelope_linestring(); + example_envelope_polygon(); + + example_within(); + + example_point_ll_convert(); + example_point_ll_construct(); + example_dms(); + + return 0; +} diff --git a/doc/doxygen_input/sourcecode/doxygen_1.vcproj b/doc/doxygen_input/sourcecode/doxygen_1.vcproj new file mode 100644 index 000000000..72b68d7b6 --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_1.vcproj @@ -0,0 +1,194 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/doxygen_input/sourcecode/doxygen_2.cpp b/doc/doxygen_input/sourcecode/doxygen_2.cpp new file mode 100644 index 000000000..182726583 --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_2.cpp @@ -0,0 +1,156 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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) +// +// Doxygen Examples, for main page + +#include + +#if defined(_MSC_VER) +// We deliberately mix float/double's here so turn off warning +//#pragma warning( disable : 4244 ) +#endif // defined(_MSC_VER) + +#include +#include +#include +#include +#include +#include +#include +#include + + +// Small QRect simulations following http://doc.trolltech.com/4.4/qrect.html +// Todo: once work the traits out further, would be nice if there is a real example of this. +// However for the example it makes no difference, it will work any way. +struct QPoint +{ + int x, y; + // In Qt these are methods but for example below it makes no difference +}; + +struct QRect +{ + int x, y, width, height; + QRect(int _x, int _y, int w, int h) + : x(_x), y(_y), width(w), height(h) + {} + // In Qt these are methods but that will work as well, requires changing traits below +}; + + +// Would be get/set with x(),y(),setX(),setY() +BOOST_GEOMETRY_REGISTER_POINT_2D(QPoint, int, cs::cartesian, x, y) + + +// Register the QT rectangle. The macro(s) does not offer (yet) enough flexibility to do this in one line, +// but the traits classes do their job perfectly. +namespace boost { namespace geometry { namespace traits +{ + +template <> struct tag { typedef box_tag type; }; +template <> struct point_type { typedef QPoint type; }; + +template +struct indexed_access +{ + static inline int get(const QRect& qr) + { + // Would be: x(), y(), width(), height() + return C == min_corner && D == 0 ? qr.x + : C == min_corner && D == 1 ? qr.y + : C == max_corner && D == 0 ? qr.x + qr.width + : C == max_corner && D == 1 ? qr.y + qr.height + : 0; + } + + static inline void set(QRect& qr, const int& value) + { + // Would be: setX, setY, setWidth, setHeight + if (C == min_corner && D == 0) qr.x = value; + else if (C == min_corner && D == 1) qr.y = value; + else if (C == max_corner && D == 0) qr.width = value - qr.x; + else if (C == max_corner && D == 1) qr.height = value - qr.y; + } +}; + + +}}} + + +void example_for_main_page() +{ + using namespace boost::geometry; + + int a[2] = {1,1}; + int b[2] = {2,3}; + double d = distance(a, b); + std::cout << "Distance a-b is:" << d << std::endl; + + ring_2d poly; + double points[][2] = {{2.0, 1.3}, {4.1, 3.0}, {5.3, 2.6}, {2.9, 0.7}, {2.0, 1.3}}; + append(poly, points); + boost::tuple p = boost::make_tuple(3.7, 2.0); + std::cout << "Point p is in polygon? " << (within(p, poly) ? "YES" : "NO") << std::endl; + + std::cout << "Area: " << area(poly) << std::endl; + + double d2 = distance(a, p); + std::cout << "Distance a-p is:" << d2 << std::endl; + + /*** + Now extension + point_ll_deg amsterdam, paris; + parse(amsterdam, "52 22 23 N", "4 53 32 E"); + parse(paris, "48 52 0 N", "2 19 59 E"); + std::cout << "Distance A'dam-Paris: " << distance(amsterdam, paris) / 1000.0 << " kilometers " << std::endl; + ***/ + + QRect r1(100, 200, 15, 15); + QRect r2(110, 210, 20, 20); + if (overlaps(r1, r2)) + { + assign(r2, 200, 300, 220, 320); + } +} + + +void example_for_transform() +{ + using namespace boost::geometry; + + typedef point XYZ; + typedef point > SPH; + XYZ p; + + SPH sph1, sph2; + assign(sph1, 12.5, 41.90, 1.0); + // Go from spherical to Cartesian-3D: + transform(sph1, p); + // Go back from Cartesian 3D to spherical: + transform(p, sph2); + + std::cout << dsv(p) << " <-> " << dsv(sph2) << std::endl; + + typedef point_xy XY; + typedef point_xy PIXEL; + XY xy(50, 50); + strategy::transform::map_transformer map(0, 0, 100, 100, 1024, 768); + PIXEL pix; + transform(xy, pix, map); + std::cout << pix.x() << "," << pix.y() << std::endl; + +} + + +int main(void) +{ + example_for_main_page(); + example_for_transform(); + return 0; +} diff --git a/doc/doxygen_input/sourcecode/doxygen_2.vcproj b/doc/doxygen_input/sourcecode/doxygen_2.vcproj new file mode 100644 index 000000000..78e45ef4e --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_2.vcproj @@ -0,0 +1,182 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/doxygen_input/sourcecode/doxygen_3.cpp b/doc/doxygen_input/sourcecode/doxygen_3.cpp new file mode 100644 index 000000000..144f5a38e --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_3.cpp @@ -0,0 +1,75 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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) +// +// Doxygen Examples, for e.g. email formal review + +#include + +#include +#include +#include +#include + + + +void example_distance() +{ + int a[2] = {1,2}; + int b[2] = {3,4}; + double d = boost::geometry::distance(a, b); + std::cout << d << std::endl; +} + +void example_length1() +{ + std::vector > line; + line.push_back(boost::make_tuple(1, 2, 3)); + line.push_back(boost::make_tuple(4, 5, 6)); + line.push_back(boost::make_tuple(7, 8, 9)); + double length = boost::geometry::length(line); + std::cout << length << std::endl; +} + +void example_length2() +{ + std::vector > line; + line.push_back(boost::make_tuple(1.1, 2.2)); + line.push_back(boost::make_tuple(3.3, 4.4)); + line.push_back(boost::make_tuple(5.5, 6.6)); + std::cout << boost::geometry::length( + std::make_pair(boost::begin(line), boost::end(line) + -1) + ) + << std::endl; +} + +void example_less() +{ + typedef boost::tuple P; + std::vector

            line; + line.push_back(boost::make_tuple(8.1, 1.9)); + line.push_back(boost::make_tuple(4.2, 7.5)); + line.push_back(boost::make_tuple(2.3, 3.6)); + std::sort(line.begin(), line.end(), boost::geometry::less

            ()); + + // Display ordered points + BOOST_FOREACH(P const& p, line) + { + std::cout << boost::geometry::dsv(p) << std::endl; + } +} + + + +int main(void) +{ + example_distance(); + example_length1(); + example_length2(); + example_less(); + return 0; +} diff --git a/doc/doxygen_input/sourcecode/doxygen_3.vcproj b/doc/doxygen_input/sourcecode/doxygen_3.vcproj new file mode 100644 index 000000000..0a326ba5e --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_3.vcproj @@ -0,0 +1,182 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/doxygen_input/sourcecode/doxygen_4.cpp b/doc/doxygen_input/sourcecode/doxygen_4.cpp new file mode 100644 index 000000000..d1b6850b3 --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_4.cpp @@ -0,0 +1,326 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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) +// +// Doxygen Examples, for documentation images + +#include + +#include + +#include + +#include +#include + +#include + + +static const int wkt_countries_count = 1; +std::string wkt_countries[wkt_countries_count] = { + "MULTIPOLYGON(((3.369472 51.37461,3.31712 51.33633,3.338228 51.27769,3.476597 51.23314,3.474252 51.2988,3.553989 51.3246,3.720502 51.27535,3.753336 51.2261,3.887015 51.21203,3.983169 51.25659,4.123883 51.28942,4.222384 51.33163,4.311502 51.38792,4.442835 51.35274,4.38655 51.46297,4.541337 51.4747,4.517883 51.40903,4.67267 51.42075,4.759444 51.48642,4.848564 51.48642,4.771171 51.3973,4.968171 51.3973,5.022111 51.48642,5.099504 51.44186,5.06667 51.36447,5.132337 51.26597,5.20973 51.33163,5.219111 51.22141,5.448946 51.26597,5.514612 51.31991,5.592005 51.27769,5.570898 51.21203,5.711612 51.18858,5.800732 51.16747,5.878123 51.13464,5.800732 51.05724,5.767898 50.93763,5.645946 50.86024,5.678778 50.76174,5.821838 50.76174,6.025336 50.75425,6.403867 50.32674,6.13802 50.1329,5.73455 49.89968,5.816617 49.54663,5.477649 49.49361,4.856486 49.79186,4.877701 50.15532,4.148557 49.97853,4.206795 50.27324,3.694881 50.31094,3.139944 50.79072,2.795442 50.72651,2.546947 51.09281,3.369472 51.37461)))" + //"MULTIPOLYGON(((4.222384 51.33163,4.201276 51.38792,4.13561 51.36447,4.025384 51.40903,4.016003 51.48642,4.091051 51.43013,4.213003 51.42075,4.288051 51.46297,4.234109 51.4958,4.048835 51.52864,3.971442 51.58492,4.058217 51.58492,4.156717 51.58492,4.156717 51.65059,4.255217 51.61776,4.344337 51.63886,4.419384 51.6717,4.574171 51.68342,4.705504 51.70453,4.81573 51.72564,4.750063 51.73736,4.541337 51.71626,4.353717 51.72564,4.255217 51.75847,4.069943 51.83586,3.99255 51.95547,4.180169 52.04459,4.365444 52.18765,4.550717 52.45031,4.67267 52.71298,4.738337 52.94281,4.804003 52.94281,4.881396 52.86542,4.968171 52.89826,5.054944 52.90998,5.111231 52.84431,5.111231 52.77161,5.162826 52.73643,5.228492 52.74582,5.287123 52.74112,5.287123 52.69188,5.233183 52.64497,5.125301 52.61683,5.071361 52.64262,5.015075 52.61214,5.080742 52.49018,5.01742 52.44328,5.080742 52.42921,4.956444 52.35885,5.031492 52.33071,5.120612 52.31898,5.183933 52.30257,5.244909 52.30491,5.341063 52.26739,5.399694 52.23924,5.523993 52.25566,5.566207 52.3096,5.676433 52.36354,5.793696 52.41279,5.861708 52.47611,5.859363 52.53709,5.796041 52.57227,5.849981 52.59806,5.645946 52.60979,5.58966 52.64262,5.592005 52.75989,5.6436 52.80914,5.716303 52.8279,5.645946 52.84431,5.561516 52.82555,5.484123 52.84197,5.413766 52.83025,5.348099 52.87715,5.404385 52.89826,5.40673 52.9991,5.383279 53.07415,5.448946 53.21721,5.580279 53.30398,5.845291 53.36965,5.976624 53.38138,6.140792 53.39076,6.183005 53.32509,6.206459 53.39076,6.370625 53.40248,6.764627 53.47988,6.851399 53.40248,6.928792 53.33682,7.048399 53.28288,7.158627 53.25004,7.179733 53.17265,7.137519 53.12809,7.179733 52.98738,7.048399 52.87715,7.060126 52.62386,6.973351 52.63559,6.698958 52.64732,6.720066 52.56992,6.675507 52.52536,6.7529 52.47142,6.872507 52.42686,6.994459 52.48315,7.060126 52.38465,7.015567 52.29553,7.060126 52.25331,6.884233 52.13136,6.731792 52.09853,6.687233 52.02114,6.80684 52.01176,6.851399 51.94609,6.797459 51.90153,6.666125 51.90153,6.424565 51.83586,6.281507 51.85697,6.140792 51.90153,6.150171 51.83586,5.953171 51.83586,5.953171 51.74909,6.018838 51.70453,6.117339 51.6928,6.107958 51.61776,6.227565 51.51925,6.239291 51.42075,6.194732 51.34336,6.084505 51.25424,6.096231 51.1792,6.173625 51.21203,6.194732 51.14636,5.986005 51.03613,5.943792 51.08069,5.878123 51.03613,5.899231 50.97047,6.030564 50.97047,6.030564 50.9048,6.107958 50.9048,6.096231 50.83913,6.030564 50.82741,6.025336 50.75425,5.821838 50.76174,5.678778 50.76174,5.645946 50.86024,5.767898 50.93763,5.800732 51.05724,5.878123 51.13464,5.800732 51.16747,5.711612 51.18858,5.570898 51.21203,5.592005 51.27769,5.514612 51.31991,5.448946 51.26597,5.219111 51.22141,5.20973 51.33163,5.132337 51.26597,5.06667 51.36447,5.099504 51.44186,5.022111 51.48642,4.968171 51.3973,4.771171 51.3973,4.848564 51.48642,4.759444 51.48642,4.67267 51.42075,4.517883 51.40903,4.541337 51.4747,4.38655 51.46297,4.442835 51.35274,4.311502 51.38792,4.222384 51.33163)),((5.455981 52.55116,5.514612 52.5582,5.573243 52.59103,5.634219 52.59103,5.73272 52.57462,5.791351 52.56758,5.854672 52.52771,5.8406 52.46908,5.756171 52.41279,5.674088 52.39403,5.573243 52.37058,5.540409 52.31664,5.507576 52.26504,5.397349 52.25097,5.294159 52.30725,5.198003 52.33305,5.134682 52.32836,5.153444 52.39403,5.411421 52.49488,5.455981 52.55116)),((4.222384 51.33163,4.123883 51.28942,3.983169 51.25659,3.887015 51.21203,3.753336 51.2261,3.720502 51.27535,3.553989 51.3246,3.474252 51.2988,3.476597 51.23314,3.338228 51.27769,3.31712 51.33633,3.369472 51.37461,3.467216 51.41137,3.600895 51.37854,3.718157 51.34336,3.840109 51.34805,3.924538 51.36447,3.952681 51.41607,4.011312 51.39496,4.072289 51.35509,4.128574 51.32225,4.222384 51.33163)),((3.40155 51.54036,3.500049 51.58258,3.56337 51.59665,3.619656 51.57554,3.659526 51.5216,3.720502 51.51456,3.781478 51.54036,3.887015 51.54271,3.971442 51.52864,4.016003 51.50753,3.999586 51.43717,3.9433 51.46062,3.879979 51.44186,3.854181 51.38792,3.753336 51.39027,3.65249 51.46062,3.556334 51.44421,3.483632 51.48173,3.429692 51.51456,3.40155 51.54036)),((3.973788 51.84524,4.037109 51.81241,4.123883 51.7913,4.196586 51.76081,4.269289 51.71391,4.360754 51.69515,4.313848 51.65293,4.248181 51.65293,4.177824 51.67873,4.119193 51.69984,4.044145 51.71391,4.023039 51.7913,3.933919 51.80537,3.870598 51.77958,3.847145 51.83821,3.973788 51.84524)),((3.793204 51.74674,3.933919 51.73502,3.985514 51.68577,4.076979 51.667,4.116848 51.65293,4.023039 51.62714,3.931574 51.6201,3.865907 51.6459,3.826037 51.6928,3.76037 51.69984,3.692358 51.66935,3.647799 51.70922,3.713466 51.73502,3.793204 51.74674)),((4.806348 53.12574,4.879051 53.175,4.92361 53.13278,4.91423 53.0718,4.86967 53.0249,4.801658 52.99676,4.747718 52.97096,4.72192 53.0249,4.754754 53.0765,4.806348 53.12574)),((5.216766 53.39545,5.507576 53.4447,5.559171 53.43766,5.493505 53.41655,5.460672 53.39545,5.387969 53.3931,5.336373 53.37669,5.240219 53.36027,5.183933 53.33682,5.165171 53.36027,5.216766 53.39545)),((3.596204 51.60134,3.720502 51.60134,3.840109 51.61306,3.877634 51.55443,3.774442 51.56147,3.718157 51.52864,3.645454 51.56147,3.596204 51.60134)),((5.636564 53.46346,5.728029 53.44939,5.852327 53.46112,5.941446 53.45877,5.88985 53.44001,5.800732 53.43063,5.716303 53.43063,5.674088 53.41421,5.622492 53.42828,5.60373 53.45408,5.636564 53.46346)),((5.008039 53.28757,5.050254 53.30398,5.094813 53.31102,5.120612 53.28991,5.001003 53.2688,4.982243 53.24066,4.932992 53.20548,4.862634 53.19845,4.890778 53.22659,4.970516 53.2688,5.008039 53.28757)),((6.138446 53.49395,6.27447 53.50567,6.307303 53.49629,6.236946 53.46815,6.154862 53.46581,6.12672 53.44939,6.100922 53.46581,6.138446 53.49395)),((6.419876 53.54085,6.483197 53.51974,6.42691 53.51506,6.396423 53.53382,6.419876 53.54085)))", +}; + +static const int wkt_cities_count = 1; +std::string wkt_cities[wkt_cities_count] = { + "MULTIPOINT(( -71.03 42.37), (-87.65 41.90), (-95.35 29.97), (-118.40 33.93), (-80.28 25.82), (-73.98 40.77), (-112.02 33.43), ( -77.04 38.85))" +}; + + + +// Read an ASCII file containing WKT's, fill a vector of tuples +// The tuples consist of at least <0> a geometry and <1> an identifying string +template +void read_wkt(std::string const& filename, std::vector& tuples, Box& box) +{ + std::ifstream cpp_file(filename.c_str()); + if (cpp_file.is_open()) + { + while (! cpp_file.eof() ) + { + std::string line; + std::getline(cpp_file, line); + Geometry geometry; + boost::trim(line); + if (! line.empty() && ! boost::starts_with(line, "#")) + { + std::string name; + + // Split at ';', if any + std::string::size_type pos = line.find(";"); + if (pos != std::string::npos) + { + name = line.substr(pos + 1); + line.erase(pos); + + boost::trim(line); + boost::trim(name); + } + + Geometry geometry; + boost::geometry::read_wkt(line, geometry); + + Tuple tuple(geometry, name); + + tuples.push_back(tuple); + boost::geometry::combine(box, boost::geometry::make_envelope(geometry)); + } + } + } +} + + + + +void svg_simplify_road() +{ + static const int n = 1; + std::string wkt[n] = { + "LINESTRING(-122.191 47.9758,-122.181 47.9958,-122.177 48.0022,-122.171 48.0081,-122.174 48.0402,-122.178 48.0718,-122.181 48.1036,-122.183 48.1361,-122.189 48.143,-122.206 48.205,-122.231 48.2515,-122.261 48.2977,-122.291 48.3592,-122.297 48.4234,-122.299 48.5183,-122.324 48.6237,-122.41 48.7339,-122.407 48.7538,-122.4 48.7749,-122.399 48.793,-122.423 48.8044,-122.45 48.8124,-122.481 48.8304,-122.517 48.8718,-122.521 48.8813,-122.523 48.901,-122.527 48.9105,-122.543 48.919,-122.551 48.9305,-122.561 48.9411,-122.585 48.9471,-122.612 48.9669,-122.638 48.9849,-122.661 49.0022)", + //"LINESTRING(-122.191 47.9758,-122.204 47.9372,-122.221 47.9019,-122.242 47.8674,-122.266 47.8312)", + //"LINESTRING(-122.176 47.5801,-122.182 47.5932,-122.185 47.6067,-122.187 47.6202,-122.187 47.6338,-122.187 47.6691,-122.182 47.7052,-122.181 47.7412,-122.192 47.776,-122.2 47.7864,-122.212 47.7945,-122.223 47.8027,-122.232 47.8132,-122.241 47.8168,-122.25 47.821,-122.259 47.8258,-122.266 47.8312)", + //"LINESTRING(-122.193 47.5075,-122.192 47.5108,-122.192 47.5147,-122.192 47.5184,-122.192 47.5224,-122.192 47.5265,-122.192 47.5307,-122.192 47.5327,-122.191 47.5348,-122.19 47.5395,-122.189 47.5443,-122.188 47.549,-122.187 47.5538,-122.185 47.5584,-122.183 47.5609,-122.182 47.563,-122.18 47.5667,-122.179 47.5676,-122.178 47.5711,-122.177 47.5726,-122.177 47.5742,-122.177 47.5762,-122.176 47.5781,-122.176 47.5801)" + }; + + typedef boost::geometry::point_xy point_type; + + std::ofstream svg("simplify_road.svg"); + svg_mapper mapper(svg, 300, 300); + + boost::geometry::linestring original[n], simplified[n]; + + for (int i = 0; i < n; i++) + { + boost::geometry::read_wkt(wkt[i], original[i]); + boost::geometry::simplify(original[i], simplified[i], 0.03); + mapper.add(original[i]); + mapper.add(simplified[i]); + std::cout + << "original: " << boost::size(original[i]) + << " simplified: " << boost::size(simplified[i]) + << std::endl; + } + + + for (int i = 0; i < n; i++) + { + mapper.map(original[i], "opacity:0.8;stroke:rgb(0,0,255);stroke-width:3"); + mapper.map(simplified[i], "opacity:0.8;stroke:rgb(0,255,0);stroke-width:2"); + } + +} + + +void svg_simplify_country() +{ + + typedef boost::geometry::point_xy point_type; + + std::ofstream svg("simplify_country.svg"); + svg_mapper mapper(svg, 300, 300); + + boost::geometry::multi_polygon > original[wkt_countries_count] + , simplified[wkt_countries_count]; + + for (int i = 0; i < wkt_countries_count; i++) + { + boost::geometry::read_wkt(wkt_countries[i], original[i]); + boost::geometry::simplify(original[i], simplified[i], 0.1); + mapper.add(original[i]); + mapper.add(simplified[i]); + std::cout + << "original: " << boost::geometry::num_points(original[i]) + << " simplified: " << boost::geometry::num_points(simplified[i]) + << std::endl; + } + + + for (int i = 0; i < wkt_countries_count; i++) + { + mapper.map(original[i], "opacity:0.8;fill:none;stroke:rgb(0,0,255);stroke-width:3"); + mapper.map(simplified[i], "opacity:0.8;fill:none;stroke:rgb(0,255,0);stroke-width:2"); + } +} + +void svg_convex_hull_country() +{ + + typedef boost::geometry::point_xy point_type; + + std::ofstream svg("convex_hull_country.svg"); + svg_mapper mapper(svg, 300, 300); + + boost::geometry::multi_polygon > original[wkt_countries_count]; + boost::geometry::linear_ring hull[wkt_countries_count]; + + for (int i = 0; i < wkt_countries_count; i++) + { + boost::geometry::read_wkt(wkt_countries[i], original[i]); + boost::geometry::convex_hull_inserter(original[i], std::back_inserter(hull[i])); + mapper.add(original[i]); + mapper.add(hull[i]); + std::cout + << "original: " << boost::geometry::num_points(original[i]) + << " hull: " << boost::geometry::num_points(hull[i]) + << std::endl; + } + + + for (int i = 0; i < wkt_countries_count; i++) + { + mapper.map(original[i], "opacity:0.8;fill:rgb(255,255,0);stroke:rgb(0,0,0);stroke-width:3"); + mapper.map(hull[i], "opacity:0.8;fill:none;stroke:rgb(255,0,0);stroke-width:3"); + } + +} + + +void svg_convex_hull_cities() +{ + + typedef boost::geometry::point_xy point_type; + + std::ofstream svg("convex_hull_cities.svg"); + svg_mapper mapper(svg, 300, 300); + + boost::geometry::multi_point original[wkt_cities_count]; + + boost::geometry::linear_ring hull[wkt_cities_count]; + + for (int i = 0; i < wkt_cities_count; i++) + { + boost::geometry::read_wkt(wkt_cities[i], original[i]); + boost::geometry::convex_hull_inserter(original[i], std::back_inserter(hull[i])); + mapper.add(original[i]); + mapper.add(hull[i]); + std::cout + << "original: " << boost::geometry::num_points(original[i]) + << " hull: " << boost::geometry::num_points(hull[i]) + << std::endl; + } + + + for (int i = 0; i < wkt_cities_count; i++) + { + mapper.map(original[i], "fill:rgb(255,255,0);stroke:rgb(0,0,100);stroke-width:1", 3); + mapper.map(hull[i], "opacity:0.8;fill:none;stroke:rgb(255,0,0);stroke-width:3"); + } +} + +void svg_intersection_roads() +{ + // Read the road network + typedef boost::geometry::point_xy point_type; + typedef boost::geometry::linestring line_type; + + typedef boost::tuple road_type; + + boost::geometry::box bbox; + boost::geometry::assign_inverse(bbox); + + std::vector roads; + read_wkt("../../../example/data/roads.wkt", roads, bbox); + + // intersect + boost::geometry::box clip; + std::vector intersected; + + boost::geometry::assign(clip, -100, 25, -90, 50); + for (size_t i = 0; i < roads.size(); i++) + { + boost::geometry::intersection_inserter(clip, roads[i].get<0>(), std::back_inserter(intersected)); + } + + // create map + std::ofstream svg("intersection_roads.svg"); + svg_mapper mapper(svg, 500, 500); + + mapper.add(bbox); + + for (size_t i = 0; i < roads.size(); i++) + { + mapper.map(roads[i].get<0>(), "stroke:rgb(0,0,255);stroke-width:3"); + } + + for (size_t i = 0; i < intersected.size(); i++) + { + mapper.map(intersected[i], "stroke:rgb(0,255,0);stroke-width:2"); + } + + for (size_t i = 0; i < intersected.size(); i++) + { + mapper.map(clip, "fill:none;stroke:rgb(128,128,128);stroke-width:2"); + } +} + + +void svg_intersection_countries() +{ + // Read the road network + typedef boost::geometry::point_xy point_type; + typedef boost::geometry::polygon poly_type; + typedef boost::geometry::multi_polygon mp_type; + + typedef boost::tuple country_type; + + boost::geometry::box bbox; + boost::geometry::assign_inverse(bbox); + + std::vector countries; + read_wkt("../../../example/data/world.wkt", countries, bbox); + + // intersect + boost::geometry::box clip; + std::vector intersected; + + boost::geometry::assign(clip, -100, -50, 100, 50); + for (size_t i = 0; i < countries.size(); i++) + { + mp_type const& mp = countries[i].get<0>(); + for (size_t j = 0; j < mp.size(); j++) + { + boost::geometry::intersection_inserter(clip, mp[j], std::back_inserter(intersected)); + } + } + + // create map + std::ofstream svg("intersection_countries.svg"); + svg_mapper mapper(svg, 800, 800); + + mapper.add(bbox); + + for (size_t i = 0; i < countries.size(); i++) + { + mapper.map(countries[i].get<0>().front(), "fill:rgb(0,0,255);stroke-width:1"); + } + + for (size_t i = 0; i < intersected.size(); i++) + { + mapper.map(intersected[i], "fill:rgb(0,255,0);stroke-width:1"); + } + + for (size_t i = 0; i < intersected.size(); i++) + { + mapper.map(clip, "fill:none;stroke:rgb(128,128,128);stroke-width:2"); + } +} + + + + + +int main(void) +{ + svg_intersection_roads(); + svg_intersection_countries(); + svg_simplify_road(); + svg_simplify_country(); + svg_convex_hull_country(); + svg_convex_hull_cities(); + return 0; +} diff --git a/doc/doxygen_input/sourcecode/doxygen_4.vcproj b/doc/doxygen_input/sourcecode/doxygen_4.vcproj new file mode 100644 index 000000000..d65ca80c1 --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_4.vcproj @@ -0,0 +1,182 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/doxygen_input/sourcecode/doxygen_5.cpp b/doc/doxygen_input/sourcecode/doxygen_5.cpp new file mode 100644 index 000000000..873451cd2 --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_5.cpp @@ -0,0 +1,136 @@ +// Boost.Geometry (aka GGL, Generic Geometry Library) +// +// Copyright Barend Gehrels 2007-2009, Geodan, Amsterdam, the Netherlands +// Copyright Bruno Lalande 2008, 2009 +// 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) +// +// Doxygen Examples, for Geometry Concepts + +#include +#include +#include +#include + + + +struct legacy_point1 +{ + double x, y; +}; + +// adapt legacy_point1 +namespace boost { namespace geometry { namespace traits +{ + template <> struct tag { typedef point_tag type; }; + template <> struct coordinate_type { typedef double type; }; + template <> struct coordinate_system { typedef cs::cartesian type; }; + template <> struct dimension: boost::mpl::int_<2> {}; + template <> struct access + { + static double get(legacy_point1 const& p) { return p.x; } + static void set(legacy_point1& p, double const& value) { p.x = value; } + }; + template <> struct access + { + static double get(legacy_point1 const& p) { return p.y; } + static void set(legacy_point1& p, double const& value) { p.y = value; } + }; +}}} // namespace boost::geometry::traits +// end adaptation + +namespace example_legacy_point1 +{ + // The first way to check a concept at compile time: checking if the input is parameter + // or return type is OK. + template + BOOST_CONCEPT_REQUIRES(((boost::geometry::concept::Point

            )), (void)) + test1(P& p) + { + } + + // The second way to check a concept at compile time: checking if the provided type, + // inside the function, if OK + template + void test2(P& p) + { + BOOST_CONCEPT_ASSERT((boost::geometry::concept::Point

            )); + } + + + void example() + { + legacy_point1 p; + test1(p); + test2(p); + } +} + +// leave comment below for (strange behaviour of) doxygen +class legacy_point2 +{ +public : + double x() const; + double y() const; +}; + +// adapt legacy_point2 +BOOST_GEOMETRY_REGISTER_POINT_2D_CONST(legacy_point2, double, boost::geometry::cs::cartesian, x(), y() ) +// end adaptation + + +double legacy_point2::x() const { return 0; } +double legacy_point2::y() const { return 0; } + +namespace example_legacy_point2 +{ + // test it using boost concept requires + + template + BOOST_CONCEPT_REQUIRES(((boost::geometry::concept::ConstPoint

            )), (double)) + test3(P& p) + { + return boost::geometry::get<0>(p); + } + + void example() + { + legacy_point2 p; + test3(p); + } +} + + +template +struct custom_linestring1 : std::deque

            +{ + int id; +}; + +// adapt custom_linestring1 +namespace boost { namespace geometry { namespace traits +{ + template + struct tag< custom_linestring1

            > { typedef linestring_tag type; }; +}}} // namespace boost::geometry::traits +// end adaptation + +namespace example_custom_linestring1 +{ + void example() + { + typedef custom_linestring1 L; + BOOST_CONCEPT_ASSERT((boost::geometry::concept::Linestring)); + + } +} + +int main(void) +{ + example_legacy_point1::example(); + example_legacy_point2::example(); + example_custom_linestring1::example(); + + return 0; +} diff --git a/doc/doxygen_input/sourcecode/doxygen_5.vcproj b/doc/doxygen_input/sourcecode/doxygen_5.vcproj new file mode 100644 index 000000000..23505e8c9 --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_5.vcproj @@ -0,0 +1,182 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/doxygen_input/sourcecode/doxygen_examples.sln b/doc/doxygen_input/sourcecode/doxygen_examples.sln new file mode 100644 index 000000000..d7fd0b326 --- /dev/null +++ b/doc/doxygen_input/sourcecode/doxygen_examples.sln @@ -0,0 +1,43 @@ +Microsoft Visual Studio Solution File, Format Version 9.00 +# Visual C++ Express 2005 +Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "doxygen_1", "doxygen_1.vcproj", "{861F130D-2849-4B50-B240-049DBD9D3F18}" +EndProject +Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "doxygen_2", "doxygen_2.vcproj", "{6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}" +EndProject +Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "doxygen_3", "doxygen_3.vcproj", "{45D4139F-BC5B-4D48-BAB8-9901C53ECCC9}" +EndProject +Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "doxygen_4", "doxygen_4.vcproj", "{CBEDAEC7-EC87-4F91-9C45-F9505A052A44}" +EndProject +Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "doxygen_5", "doxygen_5.vcproj", "{0CDE9E15-C937-4D05-B9BF-A2D96B8EAD33}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|Win32 = Debug|Win32 + Release|Win32 = Release|Win32 + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {861F130D-2849-4B50-B240-049DBD9D3F18}.Debug|Win32.ActiveCfg = Debug|Win32 + {861F130D-2849-4B50-B240-049DBD9D3F18}.Debug|Win32.Build.0 = Debug|Win32 + {861F130D-2849-4B50-B240-049DBD9D3F18}.Release|Win32.ActiveCfg = Release|Win32 + {861F130D-2849-4B50-B240-049DBD9D3F18}.Release|Win32.Build.0 = Release|Win32 + {6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}.Debug|Win32.ActiveCfg = Debug|Win32 + {6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}.Debug|Win32.Build.0 = Debug|Win32 + {6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}.Release|Win32.ActiveCfg = Release|Win32 + {6CF6A521-57E0-4DA4-9D17-ED5D29E4208C}.Release|Win32.Build.0 = Release|Win32 + {45D4139F-BC5B-4D48-BAB8-9901C53ECCC9}.Debug|Win32.ActiveCfg = Debug|Win32 + {45D4139F-BC5B-4D48-BAB8-9901C53ECCC9}.Debug|Win32.Build.0 = Debug|Win32 + {45D4139F-BC5B-4D48-BAB8-9901C53ECCC9}.Release|Win32.ActiveCfg = Release|Win32 + {45D4139F-BC5B-4D48-BAB8-9901C53ECCC9}.Release|Win32.Build.0 = Release|Win32 + {CBEDAEC7-EC87-4F91-9C45-F9505A052A44}.Debug|Win32.ActiveCfg = Debug|Win32 + {CBEDAEC7-EC87-4F91-9C45-F9505A052A44}.Debug|Win32.Build.0 = Debug|Win32 + {CBEDAEC7-EC87-4F91-9C45-F9505A052A44}.Release|Win32.ActiveCfg = Release|Win32 + {CBEDAEC7-EC87-4F91-9C45-F9505A052A44}.Release|Win32.Build.0 = Release|Win32 + {0CDE9E15-C937-4D05-B9BF-A2D96B8EAD33}.Debug|Win32.ActiveCfg = Debug|Win32 + {0CDE9E15-C937-4D05-B9BF-A2D96B8EAD33}.Debug|Win32.Build.0 = Debug|Win32 + {0CDE9E15-C937-4D05-B9BF-A2D96B8EAD33}.Release|Win32.ActiveCfg = Release|Win32 + {0CDE9E15-C937-4D05-B9BF-A2D96B8EAD33}.Release|Win32.Build.0 = Release|Win32 + EndGlobalSection + GlobalSection(SolutionProperties) = preSolution + HideSolutionNode = FALSE + EndGlobalSection +EndGlobal diff --git a/doc/extensions/gis/projections/doxygen_modules.hpp b/doc/extensions/gis/projections/doxygen_modules.hpp new file mode 100644 index 000000000..1280e650a --- /dev/null +++ b/doc/extensions/gis/projections/doxygen_modules.hpp @@ -0,0 +1,82 @@ + +/*! +\defgroup projections projections: Projections +\brief Projections are algorithms to transform earth coordinates (latlong coordinates, sphere coordinates, +coordinates in latitude longitude) to a cartesian system. Algorithms here are converted from PROJ4 (http://trac.osgeo.org/proj) + +\details Almost all projection sources are converted from PROJ4, from C to a C++ template structure. +PROJ4 is originally written by Gerald Evenden (then of the USGS). + +Projections can be used in combination with the Generic Geometry Library. +Because it does not use the Generic Geometry Library, +it might also be used as a standalone map projection library. +\par Projection parameters +(This list is adapted from the PROJ4 documentation.) +- \b proj is required for selection of the cartographic transformation +function and where name is an acronym for the desired projection. +- \b R specifies that the projection should be computed as a spherical Earth +with radius R. +- \b ellps The \b ellps option allows selection of standard, predefined +ellipsoid figures. For spherical only projections, the major axis is used as the +radius. +- \b a specifies an elliptical Earth’s major axis a. +- \b es defines the elliptical Earth’s squared eccentricity. Optionally, + either \b b, \b e, \b rf or \b f may be used where \b b, \b e and \b f are respective minor axis, + eccentricity and flattening and \b rf = 1/f +- \b R_A must be used with elliptical Earth parameters. It determines that spherical +computations be used with the radius of a sphere that has a surface area +equivalent to the selected ellipsoid. +- \b R_V can be used in a similar manner for sphere radius of an ellipse with equivalent volume. +- \b R_a must be used with elliptical Earth parameters. Spherical radius of the +arithmetic mean of the major and minor axis is used. +- \b R_g and \b R_h can be used for equivalent geometric and harmonic means of major and minor axis. +- \b R_lat_a must be used with elliptical Earth parameters. Spherical radius +of the arithmetic mean of the principle radii of the ellipsoid at latitude is used. +- \b R_lat_g can be used for equivalent geometric mean of the principle radii. +- \b x_0 false easting; added to x value of the cartesian coordinate. Used in +grid systems to avoid negative grid coordinates. +- \b y_0 false northing; added to y value of the cartesian coordinate. See x_0. +- \b lon_0 central meridian. Along with lat_0, normally determines the +geographic origin of the projection. +- \b lat_0 central parallel. See lon_0. +- \b units selects conversion of cartesian values to units specified by name. +When used, other + metric parameters must be in meters. +- \b geoc data geographic coordinates are to be treated as geocentric when this +option specified. +- \b over inhibit reduction of input longitude values to a range within ±180 of the central meridian. + +\note +- Note that many projections have also their own parameters, additionally to the list above +- Note also that some of the parameters above are required for some projections, others are always optionally + +\par Original copyright of PROJ4: +- Permission is hereby granted, free of charge, to any person obtaining a +copy of this software and associated documentation files (the "Software"), +to deal in the Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, sublicense, +and/or sell copies of the Software, and to permit persons to whom the +Software is furnished to do so, subject to the following conditions: +- The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. +- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL +THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. +*/ + + +/*! +\defgroup projection projection: Projection struct's, classes +\brief Projection struct's, classes + +\details +*/ + + +/* +- +init=file:key names a file containing cartographic control parameters associated +with the keyword key. +*/ diff --git a/doc/ggl.png b/doc/ggl.png new file mode 100644 index 000000000..0ef978a2f Binary files /dev/null and b/doc/ggl.png differ diff --git a/doc/ggl.svg b/doc/ggl.svg new file mode 100644 index 000000000..a4d6bbb3d --- /dev/null +++ b/doc/ggl.svg @@ -0,0 +1,150 @@ + + + + + + + + + + + image/svg+xml + + Generic Geometry Library Logo + + + Steven M. Ottens + + + + + logo + library + + + Big version of Generic Geometry Library logo graphics + + + Steven M. Ottens, Barend Gerhles + + + + + Mateusz Loskot + + + en-US + + + + + + + + + + + + + + + + + + + GenericGeometryLibrary + + diff --git a/doc/make_documentation.bat b/doc/make_documentation.bat new file mode 100644 index 000000000..a72a7ad2c --- /dev/null +++ b/doc/make_documentation.bat @@ -0,0 +1,9 @@ +@echo off + +doxygen + +cd doxygen_output\html + +for %%f in (*.html) do ..\..\doxygen_enhance.py %%f + +cd ..\.. diff --git a/doc/overlay/de9im_polygons.ppt b/doc/overlay/de9im_polygons.ppt new file mode 100644 index 000000000..44500c9fb Binary files /dev/null and b/doc/overlay/de9im_polygons.ppt differ diff --git a/doc/overlay/de9im_segments.ppt b/doc/overlay/de9im_segments.ppt new file mode 100644 index 000000000..5dee5a954 Binary files /dev/null and b/doc/overlay/de9im_segments.ppt differ diff --git a/doc/overlay/intersection.ppt b/doc/overlay/intersection.ppt new file mode 100644 index 000000000..bcd7049aa Binary files /dev/null and b/doc/overlay/intersection.ppt differ diff --git a/doc/overlay/overlay.ppt b/doc/overlay/overlay.ppt new file mode 100644 index 000000000..dd1e93df9 Binary files /dev/null and b/doc/overlay/overlay.ppt differ diff --git a/doc/overlay/overlay_spatial_set_operations.ppt b/doc/overlay/overlay_spatial_set_operations.ppt new file mode 100644 index 000000000..10f2bfb7e Binary files /dev/null and b/doc/overlay/overlay_spatial_set_operations.ppt differ diff --git a/doc/proposed_boost.png b/doc/proposed_boost.png new file mode 100644 index 000000000..9912755af Binary files /dev/null and b/doc/proposed_boost.png differ diff --git a/doc/quickbook/Jamfile.v2 b/doc/quickbook/Jamfile.v2 new file mode 100644 index 000000000..f543b0d1e --- /dev/null +++ b/doc/quickbook/Jamfile.v2 @@ -0,0 +1,36 @@ +# doc/quickbook/Jamfile.v2 builds Quickbook documentation for Geometry library +# +# Copyright (c) 2009 Mateusz Loskot +# 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) +# +# TODO: when moved to boot --mloskot +#project boost/libs/geometry/doc ; +import boostbook : boostbook ; +using quickbook ; + +path-constant images_location : html ; + +boostbook quickbook + : + geometry.qbk + : + # TODO: These paths assume Boost.Geometry lives in Boost tree + boost.root=../../../.. + boost.libraries=../../../libraries.htm + # TODO Use local path ../../../../doc/html/boostbook.css or similar + # but temporarily link to online CSS - hmm, does not work, using private + # copy of CSS is in quickbook/html/boostbook.css + # html.stylesheet=http://www.boost.org/doc/libs/1_41_0/doc/html/boostbook.css + html.stylesheet=http://mateusz.loskot.net/tmp/ggl/boostbook.css + # TODO: Tweak these parameters + chunk.section.depth=4 + chunk.first.sections=1 + toc.section.depth=2 + toc.max.depth=2 + generate.section.toc.level=4 + html:admon.graphics.path=images/ + pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/libs/geometry/doc/html + pdf:img.src.path=$(images_location)/ + ; diff --git a/doc/quickbook/algorithm_area.qbk b/doc/quickbook/algorithm_area.qbk new file mode 100644 index 000000000..95195f2fd --- /dev/null +++ b/doc/quickbook/algorithm_area.qbk @@ -0,0 +1,89 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section area] + +['TODO: type and function names to be inter-linked --mloskot] + +[heading Description] + +Calculate area of a geometry. + +The area algorithm calculates the surface area of all geometries having a surface, namely +box, polygon, ring, multipolygon. The units are the square of the units used for the points +defining the surface. If subject geometry is defined in meters, then area is calculated +in square meters. + +The area calculation can be done in all three common coordinate systems, Cartesian, Spherical +and Geographic as well. + +[heading Synopsis] + + namespace boost { namespace geometry { + + template + typename area_result::type area(Geometry const &geometry) + + template + Strategy::return_type area(Geometry const &geometry, Strategy const &strategy) + + template + typename area_result::type area(Geometry const &geometry) + }} + +[table Template Parameters + [[Parameter] [Requirement] [Description]] + [[`Geometry`] [Models of one of geometry __concepts__] []] + [[`Strategy`] [Models of AreaStrategy] []] +] + +[table Parameters + [[Parameter] [Requirement] [Description]] + [[`geometry`] [Shall form a valid geometry] + [Polygon should be closed and according to specified orientation (clockwise or counter-clockwise)]] + [[`strategy`] [['TODO]] + [Specifies algorithm of area calculation, especially useful for spherical areas where number + of approaches are possible]] +] + +[table Expression Semantics + [[Expression] [Return Type] [Description]] + [[__area__(geometry);] [`area_result::type`] + [Calculates area of polygon, ring, box using default area strategy provided for __wiki_cs_cartesian__ and __wiki_cs_spherical__]] + [[__area__(geometry,strategy);] [`Strategy::return_type`] + [Calculates area of polygon, ring, box using specified area strategy]] +] + +[heading Complexity] + +[table + [[Notation] [Name] [Notes]] + [[`O(n)`] [__wiki_complex_linear__] []] +] + +Benchmark example: calculation of `2776 * 1000` areas done in 0.11 seconds (see [@http://trac.osgeo.org/ggl/wiki/Performance Performance] earticle on the Wiki). + +[heading Header] + + #include + +[heading Example] + + using namespace boost::geometry; + polygon > poly; + read_wkt("POLYGON((0 0,0 7,4 2,2 0,0 0))", poly); + std::cout << "Polygon area is " << area(poly) << " square units" << std::endl; + + // Other coordinate system, spherical or geographic (extension) + polygon > > sph_poly; + read_wkt("POLYGON((0 0,0 45,45 0,0 0))", sph_poly); + std::cout << "Area is " << area(sph_poly) << " on unit sphere " << std::endl; + +[endsect] [/ end of section area] \ No newline at end of file diff --git a/doc/quickbook/algorithm_distance.qbk b/doc/quickbook/algorithm_distance.qbk new file mode 100644 index 000000000..5b43dbd73 --- /dev/null +++ b/doc/quickbook/algorithm_distance.qbk @@ -0,0 +1,32 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:distance distance (?)] +['TODO: distance algorithm...] + +[heading Description] +['TODO: this is distance algorithm...] + +[heading Synopsis] +['TODO: distance parameters...] + +[heading Complexity] +['TODO: distance complexity...] + +[heading Header] +['TODO: are public headers...] + +[heading Example] +['TODO: distance example...] + +[heading Notes] +['TODO: distance notes...] + +[endsect] [/ end of section distance] \ No newline at end of file diff --git a/doc/quickbook/algorithms.qbk b/doc/quickbook/algorithms.qbk new file mode 100644 index 000000000..fc3af67af --- /dev/null +++ b/doc/quickbook/algorithms.qbk @@ -0,0 +1,16 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section Algorithms] + +[include algorithm_area.qbk] +[include algorithm_distance.qbk] + +[endsect] [/ end of section Algorithms] diff --git a/doc/quickbook/arithmetic.qbk b/doc/quickbook/arithmetic.qbk new file mode 100644 index 000000000..833440f67 --- /dev/null +++ b/doc/quickbook/arithmetic.qbk @@ -0,0 +1,233 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section Arithmetic] + +__boost_geometry__ provides a set of arithmetic operations defined for point geometries. + +[section add_point] + +[heading Description] + +Adds one point to another. + +[heading Synopsis] + + namespace boost { namespace geometry { + + template + void add_point(Point1 &p1, Point2 const &p2); + }} + +[table Parameters + [[Parameter] [Requirement] [Description]] + [[`p1`, `p2`] [Models of __concept_point__] + [First point used as operation input and output. Second point usedas input]] +] + +[table Expression Semantics + [[Expression] [Return Type] [Description]] + [[__add_point__(p1, p2);] [`void`] + [Coordinates of `p2` are added to corresponding coordinates of `p1`. The `p2` is not modified]] +] + +[heading Header] + + #include + +[heading Example] + + #include + #include + #include + #include + + int main() + { + using namespace boost::geometry; + point_xy p1(1, 3); + point_xy p2(2, 4); + + add_point(p1, p2); + + std::cout << "p1 = " << dsv(p1) << std::endl; + } + +[endsect] [/ end of section add_point] + +[section add_value] + +[heading Description] + +Adds a value to each coordinate of a point. + +[heading Synopsis] + + namespace boost { namespace geometry { + + template + void add_value(Point &p, typename detail::param::type value) + }} + +[heading Header] + + #include + +[heading Example] + + int foo(); + +[endsect] [/ end of section add_value] + +[section divide_point] + +[heading Description] + +Divides a point by another. + +[heading Synopsis] + + namespace boost { namespace geometry { + + template + void divide_point(Point1 &p1, Point2 const &p2); + }} + +[heading Header] + + #include + +[heading Example] + + int foo(); + +[endsect] [/ end of section divide_point] + +[section divide_value] + +[heading Description] + +Divides each coordinate of a point by a value. + +[heading Synopsis] + + namespace boost { namespace geometry { + + template + void divide_value(Point &p, typename detail::param< Point>::type value); + }} + +[heading Header] + + #include + +[heading Example] + + int foo(); + +[endsect] [/ end of section divide_value] + +[section multiply_point] + +[heading Description] + +Multiplies a point by another. + +[heading Synopsis] + + namespace boost { namespace geometry { + + template + void multiply_point(Point1 &p1, Point2 const &p2); + }} + +[heading Header] + + #include + +[heading Example] + + int foo(); + +[endsect] [/ end of section multiply_point] + +[section multiply_value] + +[heading Description] + +Multiplies each coordinate of a point by a value. + +[heading Synopsis] + + namespace boost { namespace geometry { + + template + void multiply_value(Point &p, typename detail::param::type value); + }} + +[heading Header] + + #include + +[heading Example] + + int foo(); + +[endsect] [/ end of section multiply_value] + +[section subtract_point] + +[heading Description] + +Subtracts a point to another. + +[heading Synopsis] + + namespace boost { namespace geometry { + + template + void subtract_point(Point1 &p1, Point2 const &p2) + }} + +[heading Header] + + #include + +[heading Example] + + int foo(); + +[endsect] [/ end of section subtract_point] + +[section subtract_value] + +[heading Description] + +Subtracts a value to each coordinate of a point. + +[heading Synopsis] + + namespace boost { namespace geometry { + + template + void subtract_value(Point &p, typename detail::param::type value) + }} + +[heading Header] + + #include + +[heading Example] + + int foo(); + +[endsect] [/ end of section subtract_value] + +[endsect] [/ end of section Arithmetic] \ No newline at end of file diff --git a/doc/quickbook/boolean.qbk b/doc/quickbook/boolean.qbk new file mode 100644 index 000000000..4d99a23dd --- /dev/null +++ b/doc/quickbook/boolean.qbk @@ -0,0 +1,249 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:boolean Spatial Boolean Operations] + +The __boost_geometry__ implementation of the algorithms like intersection, union, difference and +symmetric difference is based on principles of __wiki_set_theory__, where a set is formed by +spatial object, a geometry or collection of geometries. + +Intersection and union are so-called set-theoretic operations. Those operations work on sets, +and geometries (especially polygons and multipolygons) can be seen as sets, sets of points. + +The first section will repeat a small, relevant part of the algebra of sets, also describing the +notation used in this page. The next section will extend this algebra of sets for spatial sets +(polygons). + +[section:algebra Algebra of Sets in Spatial Context] + +The following section explaines meaning of __wiki_set_algebra__ in context of spatial operations. + +* A __set_intersect__ B : intersection of two sets A and B is the set that contains all + elements of A that also belong to B, also known as AND. +* A __set_union__ B : union of two sets A and B is the set that contains all elements + that belong to A or B, also known as OR. +* A__set_complement__ : complement of set A is the set of elements which do not belong to A +* A __set_difference__ B : difference of two sets A and B is the set of elements which + belong to A but not to B +* A __set_symdifference__ B : symmetric difference of two sets A and B is the set of + elements which belong to either A or to B, but not to A and B, also known as XOR. + +There are several laws on sets and we will not discuss them all here. The most important for this +page are: + +* B __set_difference__ A = A__set_complement__ __set_intersect__ B and, vice versa, A __set_difference__ B = B__set_complement__ __set_intersect__ A +* A __set_symdifference__ B = (B __set_difference__ A) __set_union__ (A __set_difference__ B) + +[heading References] + +* __wiki_set_theory__ in Wikipedia +* __wiki_set_algebra__ in Wikipedia +* [@http://www.tutorvista.com/content/math/number-theory/sets/operations-sets.php Operations on Sets,Union of sets,Intersection of sets] at TutorVista.com + +[endsect] [/ end of section Algebra] + +[section:polygons Polygons] + +Polygons are sets of points, and, therefore polygons follow all definitions and laws for sets. +For pragmatic reasons and implementations in computer programs, polygons have an orientation, +clockwise or counter clockwise. Orientation is not part of most set theory descriptions, but is an +important aspect for the appliance of sets to polygon operations. + +If a polygon is (arbitrarily) defined as having its vertices in clockwise direction: + +* then its interior lies on the right side of the edges (see [@http://gandraxa.com/draw_orthogonal_polygons.aspx Draw Orthogonal Polygons]) +* and its exterior lies, therefore, on the left side of the edges + +This definition is important for the spatial interpretation sets. + +* If set A describes the interior of a polygon, then A__set_complement__, its complement, + describes the exterior of a polygon. +* Stated differently, set A is a polygon, all points belonging to A are inside the polygon. + Its complement, A__set_complement__, contains all points not belonging to A. +* If A is a polygon with its vertices oriented clockwise, A__set_complement__ is a polygon + with the same vertices, but in reverse order, so counter clockwise. Both sets have their points belonging to them at the right side of their edges + +__img_set_a_ac__ + +The last observation is helpful in calculating the difference and the symmetric difference: + +* the difference B __set_difference__ A is defined above by the + law B __set_difference__ A = A__set_complement__ __set_intersect__ B. In polygon terms it is + therefore the intersection of the "reverse of A" with B. To calculate it, it is enough to have + polygon A input in reverse order, and intersect this with polygon B +* the symmetric difference A __set_symdifference__ B is defined above by the law + (B __set_difference__ A) __set_union__ (A __set_difference__ B), which leads to + (A__set_complement__ __set_intersect__ B) __set_union__ (B__set_complement__ __set_intersect__ A). + To calculate the symmetric difference, it is enough to have polygon A input in reverse order, intersect this with polygon B, store the result; then have polygon B input in reverse order, + intersect this with polygon A, add this to the result and this is the symmetric difference. + The combination of both sub-results does not have to be intersected as it is only touching on + vertices and do not have overlaps. + +[endsect] [/ end of section Polygons] + +[section:implementation Implementation of Intersection and Union] + +All spatial set-theoretic operations are implemented in shared code. There is hardly any difference +in code between the calculation of an intersection or a union. The only difference is that at each +intersection point, for an intersection the right turn should be taken. For union the left turn +should be taken. + +__img_set_int_right_union_left__ + +This is implemented as such in __boost_geometry__. The turn to be taken is a variable. + +There is an alternative to calculate union as well: + +* the union A __set_union__ B equals to the complement of the intersection of the complements + of the inputs, (A__set_complement__ __set_intersect__ B__set_complement__)__set_complement__ + (see __wiki_demorgan_laws__ and __wiki_set_law_complements__) + +There is an additional difference in the handling of disjoint holes (holes which are not intersected). This is also implemented in the same generic way (the implementation will still be tweaked a +little to have it even more generic). + +For a counter clockwise polygon, the behaviour is the reverse: for intersection take the left path, +for union take the right path. This is a trivial thing to implement, but it still has to be done +(as the orientation was introduced in a later phase in __boost_geometry__). + +[endsect] [/ end of section Implementation] + +[section:iterating Iterating Forward or Reverse] + +['TODO: Does this section belong to boolean operations at all? --mloskot] + +As explained above, for a difference, the vertices of the first polygon should be iterated by a +forward iterator, but the vertices of the second polygon should be iterated by a reverse iterator +(or vice versa). This (trivial) implementation still has to be done. It will not be implemented +by creating a copy, reversing it, and presenting it as input to the set operation (as outlined above). + +That is easy and will work but has a performance penalty. Instead a reversible iterator will used, +extended from __boost_range__ iterators, and decorating a Boost.Range iterator at the same time, +which can travel forward or backward. + +It is currently named `reversible_view` and usage looks like: + + template + void walk(Range const & range) + { + typedef reversible_view view_type; + view_type view(range); + + typename boost::range_const_iterator::type it; + for (it = boost::begin(view); it != boost::end(view); ++it) + { + // do something + } + } + + walk<1>(range); // forward + walk<-1>(range); // backward + +[endsect] [/ end of section Iterating] + +[section:intersection Characteristics of the Intersection Algorithm] + +The algorithm is a modern variant of the graph traversal algorithm, after __wiki_weiler_atherton__. + +It has the following characteristics (part of these points are deviations from __wiki_weiler_atherton__) + +* No copy is necessary (the original Weiler-Atherton, and its descendants, insert intersections in + (linked) lists, which require to make first copies of both input geometries). +* All turning points (which are intersection points with side/turn information) are unaware of + the context, so we have (and need) no information about if, before the intersection point, + a segment was inside or outside of the other geometry +* It can do intersections, unions, symmetric differences, differences +* It can handle polygons with holes, non-convex polygons, polygons-with-polygons, + polygons-with-boxes (clip), rings, multi-polygons +* It can handle one polygon at the time (resolve self-intersections), two polygons (the normal + use case), or more polygons (applicable for intersections and unions) +* It can handle clockwise and counter-clockwise geometries + +[heading Outline of the Intersection Algorithm] + +The actual implementation consists of the next phases. + +1. The input geometries are indexed (if necessary). Currently we use monotonic sections for the +index. It is done by the algorithm sectionalize. Sections are created is done on the fly, +so no preparation is required before (though this would improve performance - it is possible that +there will be an alternative variant where prepared sections or other indexes are part of the input). +For box-polygon this phase is not necessary and skipped. Sectionalizing is done in linear time. + +2. Intersection points are calculated. Segments of polygon A are compared with segments of polygon B. +Segment intersection is only done for segments in overlapping sections. Intersection points are not +inserted into the original polygon or in a copy. A linked list is therefore not necessary. This phase +is called get_intersection_points. This function can currently be used for one or two input geometries, +for self-intersection or for intersection. Because found intersections are provided with intersection +information, including a reference to their source, it is possible (but currently not implemented) +to have more than two geometry inputs. + +The complexity of getting the intersections is (much) less than quadratic (n*m) because of the +monotonic sections. The exact complexity depends on the number of sections, of how the input polygons +look like. In a worst case scenario, there are only two monotonic sections per polygon and both +overlap. The complexity is then quadratic. However, the sectionalize algorithm has a maximum number of +segments per section, so for large polygons there are always more monotonic sections and in those cases +they do not overlap by the definition of "monotonic". For boxes, the complexity is linear time. + +To give another idea of how sections and indexes work: For a test processing 3918 polygons (but not +processing those of which envelopes do not overlap): + +* brute force (O(n2)): 11856331 combinations +* monotonic sections: 213732 combinations (55 times less) +* a spatial index: 34877 combinations (1/6 of using monotonic sections) So there can still be gained + some performance by another index. However the current spatial index implementation (in an extension, + not in Formal Review) will still be revisited, so it is currently not used. + +In "normal" cases 84% of the time is spent on finding intersection points. These divisions in 's +refers to the performance test described elsewhere + +One piece of information per intersection points is if it is trivial. It is trivial if the intersection +is not located at segment end points. + +3. The found intersection points are merged (merge_intersection_points), and some intersections +can be deleted (e.g. in case of collinearities). This merge process consists of sorting +the intersection points in X (major) and Y (minor) direction, and merging intersections +with a common location together. Intersections with common locations do occur as soon as segments +are collinear or meet at their end points. This phase is skipped if all intersection points +are trivial. + +About 6% is spent on merging. + +4. Some turns need to be adapted. If segments intersect in their interiors, this is never necessary. +However, if segments intersect on their end points, it is sometimes necessary to change "side" +information to "turn" information. This phase is called adapt_turns. + +The image below gives one example when adapting turns is necessary. There is side information, both +segments have sides left and right, there is also collinear. However, for an intersection no turn +should be taken at all, so no right turn. For a union, both polygons have to be travelled. In this +case the side information is adapted to turn information, both turns will be left. This phase is +skipped if all intersection points are trivial. + +__img_set_adapt_turns__ + +5. The merged intersection points are enriched (enrich_intersection_points) with information +about a.o. the next intersection point (travel information). + +About 3% is spent on enrichment. + +6. Polygons are traversed (traverse) using the intersection points, enriched with travel information. +The input polygons are traversed and at all intersection poitns a direction is taken, left for union, +right for intersection point (for counter clockwise polygons this is the other way round). +In some cases separate rings are produced. In some cases new holes are formed. + +About 6% is spent on traversal. + +7. The created rings are assembled (assemble) into polygon(s) with exterior rings and interior rings. +Even if there are no intersection points found, this process can be important to find containment +and coverage. + +['Timing of this phase is not yet available, as the comparison program work on rings.] + +[endsect] [/ end of section Intersection ] + +[endsect] [/ end of section Boolean] \ No newline at end of file diff --git a/doc/quickbook/cs.qbk b/doc/quickbook/cs.qbk new file mode 100644 index 000000000..2ac45d6e8 --- /dev/null +++ b/doc/quickbook/cs.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:cs Coordinate Systems (?)] +['TODO: long story about coordinate systems...] + +['TODO: end of long story about coordinate systems...] +[endsect] [/ end of section Coordinate Systems] diff --git a/doc/quickbook/design.qbk b/doc/quickbook/design.qbk new file mode 100644 index 000000000..5cc4e413f --- /dev/null +++ b/doc/quickbook/design.qbk @@ -0,0 +1,22 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section:design Design] + +[include design/introduction.qbk] +[include design/templates.qbk] +[include design/traits.qbk] +[include design/dimension.qbk] +[include design/coordinate_type.qbk] +[include design/geometry_type.qbk] +[include design/coordinate_system.qbk] +[include design/concepts.qbk] + +[endsect] diff --git a/doc/quickbook/design_deprecated/concepts.qbk b/doc/quickbook/design_deprecated/concepts.qbk new file mode 100644 index 000000000..0f33897e0 --- /dev/null +++ b/doc/quickbook/design_deprecated/concepts.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section Concepts] + +/TODO/ Basics of point concept + +[endsect] diff --git a/doc/quickbook/design_deprecated/coordinate_system.qbk b/doc/quickbook/design_deprecated/coordinate_system.qbk new file mode 100644 index 000000000..05c5574a7 --- /dev/null +++ b/doc/quickbook/design_deprecated/coordinate_system.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section Coordinate system] + +/TODO/ + +[endsect] diff --git a/doc/quickbook/design_deprecated/coordinate_type.qbk b/doc/quickbook/design_deprecated/coordinate_type.qbk new file mode 100644 index 000000000..7a8893146 --- /dev/null +++ b/doc/quickbook/design_deprecated/coordinate_type.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section Coordinate type] + +/TODO/ + +[endsect] diff --git a/doc/quickbook/design_deprecated/dimension.qbk b/doc/quickbook/design_deprecated/dimension.qbk new file mode 100644 index 000000000..a84ca8232 --- /dev/null +++ b/doc/quickbook/design_deprecated/dimension.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section Dimension] + +/TODO/ + +[endsect] diff --git a/doc/quickbook/design_deprecated/geometry_type.qbk b/doc/quickbook/design_deprecated/geometry_type.qbk new file mode 100644 index 000000000..e7e5745d3 --- /dev/null +++ b/doc/quickbook/design_deprecated/geometry_type.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section Geometry type] + +/TODO/ + +[endsect] diff --git a/doc/quickbook/design_deprecated/introduction.qbk b/doc/quickbook/design_deprecated/introduction.qbk new file mode 100644 index 000000000..8845c4157 --- /dev/null +++ b/doc/quickbook/design_deprecated/introduction.qbk @@ -0,0 +1,45 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section Introduction] + +Suppose you need to write C++ program to calculate distance between two points. +You might define a type of point: + + struct mypoint + { + double x, y; + }; + +and function that defines algorithm calculating distance between two points: + + double distance(mypoint const& a, mypoint const& b) + { + double dx = a.x - b.x; + double dy = a.y - b.y; + return sqrt(dx * dx + dy * dy); + } + +Quite simple, and it is usable, but not generic. For a library it has to be +designed way further. The design above can only be used for 2D points, +for the type `struct mypoint` (and no other type), in a Cartesian coordinate system. + +A generic library should be able to calculate the distance: + +* for any type of point, not on just this `struct mypoint` +* in more than two dimensions +* for other coordinate systems, e.g. over the Earth or on a sphere +* between a point and a line or between other geometry combinations +* in higher precision than `double` +* avoiding the square root: often we don’t want to do that because it is a relatively expensive function, and for comparing distances it is not necessary. + +In this page we will make the design step by step more generic. + +[endsect] diff --git a/doc/quickbook/design_deprecated/templates.qbk b/doc/quickbook/design_deprecated/templates.qbk new file mode 100644 index 000000000..ac8048cb5 --- /dev/null +++ b/doc/quickbook/design_deprecated/templates.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section:templates Using templates] + +/TODO/ + +[endsect] diff --git a/doc/quickbook/design_deprecated/traits.qbk b/doc/quickbook/design_deprecated/traits.qbk new file mode 100644 index 000000000..36ea12c25 --- /dev/null +++ b/doc/quickbook/design_deprecated/traits.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section:traits Using traits] + +/TODO/ + +[endsect] diff --git a/doc/quickbook/design_rationale.qbk b/doc/quickbook/design_rationale.qbk new file mode 100644 index 000000000..ecdfc189f --- /dev/null +++ b/doc/quickbook/design_rationale.qbk @@ -0,0 +1,758 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:design Design Rationale] + +Suppose you need a C++ program to calculate the distance between two points. +You might define a struct: + + struct mypoint + { + double x, y; + }; + +and a function, containing the algorithm: + + double distance(mypoint const& a, mypoint const& b) + { + double dx = a.x - b.x; + double dy = a.y - b.y; + return sqrt(dx * dx + dy * dy); + } + +Quite simple, and it is usable, but not generic. For a library it has to be designed way further. +The design above can only be used for 2D points, for the struct mypoint (and no other struct), +in a __wiki_cs_cartesian__. A generic library should be able to calculate the distance: + +* for any point class or struct, not on just this mypoint type +* in more than two dimensions +* for other coordinate systems, e.g. over the earth or on a sphere +* between a point and a line or between other geometry combinations +* in higher precision than ‘double’ +* avoiding the square root: often we don’t want to do that because it is a relatively expensive + function, and for comparing distances it is not necessary + +In this and following sections we will make the design step by step more generic. + +[section:templates Using Templates] + +The distance function can be changed into a template function. This is trivial and allows +calculating the distance between other point types than just mypoint. We add two template +parameters, allowing input of two different point types. + + template + double distance(P1 const& a, P2 const& b) + { + double dx = a.x - b.x; + double dy = a.y - b.y; + return std::sqrt(dx * dx + dy * dy); + } + +This template version is slightly better, but not much. + +Consider a C++ class where member variables are protected... +Such a class does not allow to access `x` and `y` members directly. So, this paragraph is short +and we just move on. + +[endsect] [/ end of section Templates] + +[section:traits Using Traits] + +We need to take a generic approach and allow any point type as input to the distance function. +Instead of accessing `x` and `y` members, we will add a few levels of indirection, using a +traits system. The function then becomes: + + template + double distance(P1 const& a, P2 const& b) + { + double dx = get<0>(a) - get<0>(b); + double dy = get<1>(a) - get<1>(b); + return std::sqrt(dx * dx + dy * dy); + } + +This adapted distance function uses a generic get function, with dimension as a template parameter, +to access the coordinates of a point. This get forwards to the traits system, defined as following: + + namespace traits + { + template + struct access {}; + } + +which is then specialized for our mypoint type, implementing a static method called `get`: + + namespace traits + { + template <> + struct access + { + static double get(mypoint const& p) + { + return p.x; + } + }; + // same for 1: p.y + ... + } + +Calling `traits::access::get(a)` now returns us our `x` coordinate. Nice, isn't it? +It is too verbose for a function like this, used so often in the library. We can shorten the syntax +by adding an extra free function: + + template + inline double get(P const& p) + { + return traits::access::get(p); + } + +This enables us to call `get<0>(a)`, for any point having the traits::access specialization, +as shown in the distance algorithm at the start of this paragraph. So we wanted to enable classes +with methods like `x()`, and they are supported as long as there is a specialization of the access +`struct` with a static `get` function returning `x()` for dimension 0, and similar for 1 and `y()`. + +Alternatively we could implement, in the traits class, the dimension as a template parameter in +a member template function: + + template <> + struct access + { + template + static double get(mypoint const& p) + // either return x/y using an if-clause + // or call a detail-struct specialized + // per dimension + }; + +This alternative gives in the end the same functionality, either using an `if` statement (wihch +may be slower), or adding another level of indirection. + +[endsect] [/ end of section Traits] + +[section:dimension Dimension Agnosticism] + +Now we can calculate the distance between points in 2D, points of any structure or class. +However, we wanted to have 3D as well. So we have to make it dimension agnostic. This complicates +our distance function. We can use a `for` loop to walk through dimensions, but for loops have +another performance than the straightforward coordinate addition which was there originally. +However, we can make more usage of templates and make the distance algorithm as following, +more complex but attractive for template fans: + + template + struct pythagoras + { + static double apply(P1 const& a, P2 const& b) + { + double d = get(a) - get(b); + return d * d + pythagoras::apply(a, b); + } + }; + + template + struct pythagoras + { + static double apply(P1 const&, P2 const&) + { + return 0; + } + }; + +The distance function is calling that pythagoras structure, specifying the number of dimensions: + + template + double distance(P1 const& a, P2 const& b) + { + BOOST_STATIC_ASSERT(( dimension::value == dimension::value )); + + return sqrt(pythagoras::value>::apply(a, b)); + } + +The dimension which is referred to is defined using another traits class: + + namespace traits + { + template + struct dimension {}; + } + +which has to be specialized again for the `struct mypoint`. + +Because it only has to publish a value, we conveniently derive it from the __boost_mpl__ `class boost::mpl::int_`: + +namespace traits +{ + template <> + struct dimension + : boost::mpl::int_<2> + {}; +} + +Like the free get function, the library also contains a dimension meta-function. + + template + struct dimension : traits::dimension

            + {}; + +Below is explained why the extra declaration is useful. Now we have agnosticism in the number of +dimensions. Our more generic distance function now accepts points of three or more dimensions. +The compile-time assertion will prevent point a having two dimension and point b having +three dimensions. + +[endsect] [/ end of section Dimension] + +[section:coordinate Coordinate Type] + +We assumed double above. What if our points are in integer? + +We can easily add a traits class, and we will do that. However, the distance between two integer +coordinates can still be a fractionized value. Besides that, a design goal was to avoid square +roots. We handle these cases below, in another paragraph. For the moment we keep returning double, +but we allow integer coordinates for our point types. To define the coordinate type, we add +another traits class, `coordinate_type`, which should be specialized by the library user: + + namespace traits + { + template + struct coordinate_type{}; + + // specialization for our mypoint + template <> + struct coordinate_type + { + typedef double type; + }; + } + +Like the access function, where we had a free get function, we add a proxy here as well. +A longer version is presented later on, the short function would look like this: + + template + struct coordinate_type : traits::coordinate_type

            {}; + +We now can modify our distance algorithm again. Because it still returns double, we only +modify the Pythagoras computation class. It should return the coordinate type of its input. +But, it has two input, possibly different, point types. They might also differ in their +coordinate types. Not that that is very likely, but we’re designing a generic library and we +should handle those strange cases. We have to choose one of the coordinate types and of course +we select the one with the highest precision. This is not worked out here, it would be too long, +and it is not related to geometry. We just assume that there is a meta-function `select_most_precise` +selecting the best type. + +So our computation class becomes: + + template + struct pythagoras + { + typedef typename select_most_precise + < + typename coordinate_type::type, + typename coordinate_type::type + >::type computation_type; + + static computation_type apply(P1 const& a, P2 const& b) + { + computation_type d = get(a) - get(b); + return d * d + pythagoras ::apply(a, b); + } + }; + +[endsect] [/ end of section Coordinate Type] + +[section:geometries Different Geometries] + +We’ve designed a dimension agnostic system supporting any point type of any coordinate type. +There are still some tweaks but they will be worked out later. Now we will see how we calculate +the distance between a point and a polygon, or between a point and a line-segment. These formulae +are more complex, and the influence on design is even larger. We don’t want to add a function +with another name: + + template + double distance_point_segment(P const& p, S const& s) + +We want to be generic, the distance function has to be called from code not knowing the type +of geometry it handles, so it has to be named distance. We also cannot create an overload because +that would be ambiguous, having the same template signature. There are two solutions: + +[/TODO: link --mloskot] +* tag dispatching +* __wiki_sfinae__ + +We select tag dispatching because it fits into the traits system, and also because __wiki_sfinae__ +has several drawbacks, listed in another paragraph. With tag dispatching the distance algorithm +inspects the type of geometry of the input parameters. The distance function will be changed +into this: + + template + double distance(G1 const& g1, G2 const& g2) + { + return dispatch::distance + < + typename tag::type, + typename tag::type, + G1, G2 + >::apply(g1, g2); + } + +It is referring to the tag meta-function and forwarding the call to the apply method of +a `dispatch::distance` structure. The tag meta-function is another traits class, and should +be specialized for per point type, both shown here: + + namespace traits + { + template + struct tag {}; + + // specialization + template <> + struct tag + { + typedef point_tag type; + }; + } + +Free meta-function, like coordinate_system and get: + + template + struct tag : traits::tag {}; + +Tags (`point_tag`, `segment_tag`, etc) are empty structures with the purpose to specialize a +dispatch struct. The dispatch struct for distance, and its specializations, are all defined +in a separate namespace and look like the following: + + namespace dispatch { + template < typename Tag1, typename Tag2, typename G1, typename G2 > + struct distance + {}; + + template + struct distance < point_tag, point_tag, P1, P2 > + { + static double apply(P1 const& a, P2 const& b) + { + // here we call pythagoras + // exactly like we did before + ... + } + }; + + template + struct distance + < + point_tag, segment_tag, P, S + > + { + static double apply(P const& p, S const& s) + { + // here we refer to another function + // implementing point-segment + // calculations in 2 or 3 + // dimensions... + ... + } + }; + + // here we might have many more + // specializations, + // for point-polygon, box-circle, etc. + + } // namespace + +So yes, it is possible; the distance algorithm is generic now in the sense that it also +supports different geometry types. One drawback: we have to define two dispatch specializations +for point - segment and for segment - point separately. That will also be solved, in the paragraph +reversibility below. The example below shows where we are now: different point types, +geometry types, dimensions. + + point a(1,1); + point b(2,2); + std::cout << distance(a,b) << std::endl; + segment s1(0,0,5,3); + std::cout << distance(a, s1) << std::endl; + rgb red(255, 0, 0); + rbc orange(255, 128, 0); + std::cout << "color distance: " << distance(red, orange) << std::endl; + +[endsect] [/ end of section Different Geometries] + +[section:kernel Kernel Revisited] + +We described above that we had a traits class `coordinate_type`, defined in namespace traits, +and defined a separate `coordinate_type` class as well. This was actually not really necessary +before, because the only difference was the namespace clause. But now that we have another +geometry type, a segment in this case, it is essential. We can call the `coordinate_type` +meta-function for any geometry type, point, segment, polygon, etc, implemented again by tag dispatching: + + template + struct coordinate_type + { + typedef typename dispatch::coordinate_type + < + typename tag::type, G + >::type type; + }; + +Inside the dispatch namespace this meta-function is implemented twice: a generic version and +one specialization for points. The specialization for points calls the traits class. +The generic version calls the point specialization, as a sort of recursive meta-function definition: + + namespace dispatch + { + + // Version for any geometry: + template + struct coordinate_type + { + typedef typename point_type + < + GeometryTag, G + >::type point_type; + + // Call specialization on point-tag + typedef typename coordinate_type < point_tag, point_type >::type type; + }; + + // Specialization for point-type: + template + struct coordinate_type + { + typedef typename + traits::coordinate_type

            ::type + type; + }; + } + +So it calls another meta-function point_type. This is not elaborated in here but realize that it +is available for all geometry types, and typedefs the point type which makes up the geometry, +calling it type. + +The same applies for the meta-function dimension and for the upcoming meta-function coordinate system. + +[endsect] [/ end of section Kernel] + +[section:cs Coordinate System] + +Until here we assumed a Cartesian system. But we know that the Earth is not flat. +Calculating a distance between two GPS-points with the system above would result in nonsense. +So we again extend our design. We define for each point type a coordinate system type +using the traits system again. Then we make the calculation dependant on that coordinate system. + +Coordinate system is similar to coordinate type, a meta-function, calling a dispatch function +to have it for any geometry-type, forwarding to its point specialization, and finally calling +a traits class, defining a typedef type with a coordinate system. We don’t show that all here again. +We only show the definition of a few coordinate systems: + + struct cartesian {}; + + template + struct geographic + { + typedef DegreeOrRadian units; + }; + +So Cartesian is simple, for geographic we can also select if its coordinates are stored in degrees +or in radians. + +The distance function will now change: it will select the computation method for the corresponding +coordinate system and then call the dispatch struct for distance. We call the computation method +specialized for coordinate systems a strategy. So the new version of the distance function is: + + template + double distance(G1 const& g1, G2 const& g2) + { + typedef typename strategy_distance + < + typename coordinate_system::type, + typename coordinate_system::type, + typename point_type::type, + typename point_type::type, + dimension::value + >::type strategy; + + return dispatch::distance + < + typename tag::type, + typename tag::type, + G1, G2, strategy + >::apply(g1, g2, strategy()); + } + +The strategy_distance mentioned here is a struct with specializations for different coordinate +systems. + + template + struct strategy_distance + { + typedef void type; + }; + + template + struct strategy_distance + { + typedef pythagoras type; + }; + +So, here is our Pythagoras again, now defined as a strategy. The distance dispatch function just +calls its apply method. + +So this is an important step: for spherical or geographical coordinate systems, another +strategy (computation method) can be implemented. For spherical coordinate systems +have the haversine formula. So the dispatching traits struct is specialized like this + + template + struct strategy_distance + { + typedef haversine type; + }; + + // struct haversine with apply function + // is omitted here + +For geography, we have some alternatives for distance calculation. There is the Andoyer method, +fast and precise, and there is the Vincenty method, slower and more precise, and there are some +less precise approaches as well. + +Per coordinate system, one strategy is defined as the default strategy. To be able to use +another strategy as well, we modify our design again and add an overload for the distance +algorithm, taking a strategy object as a third parameter. + +This new overload distance function also has the advantage that the strategy can be constructed +outside the distance function. Because it was constructed inside above, it could not have +construction parameters. But for Andoyer or Vincenty, or the haversine formula, it certainly +makes sense to have a constructor taking the radius of the earth as a parameter. + +So, the distance overloaded function is: + + template + double distance(G1 const& g1, G2 const& g2, S const& strategy) + { + return dispatch::distance + < + typename tag::type, + typename tag::type, + G1, G2, S + >::apply(g1, g2, strategy); + } + +The strategy has to have a method apply taking two points as arguments (for points). It is not +required that it is a static method. A strategy might define a constructor, where a configuration +value is passed and stored as a member variable. In those cases a static method would be +inconvenient. It can be implemented as a normal method (with the const qualifier). + +We do not list all implementations here, Vincenty would cover half a page of mathematics, +but you will understand the idea. We can call distance like this: + + distance(c1, c2) + +where `c1` and `c2` are Cartesian points, or like this: + + distance(g1, g2) + +where `g1` and `g2` are Geographic points, calling the default strategy for Geographic +points (e.g. Andoyer), and like this: + + distance(g1, g2, vincenty(6275)) + +where a strategy is specified explicitly and constructed with a radius. + +[endsect] [/ end of section Coordinate System] + +[section Point Concept] +['TODO: What to do with this section? We have concepts already --mloskot] +[endsect] [/ end of section ] + +[section Return Type] + +We promised that calling `std::sqrt` was not always necessary. So we define a distance result `struct` +that contains the squared value and is convertible to a double value. This, however, only has to +be done for Pythagoras. The spherical distance functions do not take the square root so for them +it is not necessary to avoid the expensive square root call; they can just return their distance. + +So the distance result struct is dependant on strategy, therefore made a member type of +the strategy. The result struct looks like this: + + template + struct cartesian_distance + { + T sq; + explicit cartesian_distance(T const& v) : sq (v) {} + + inline operator T() const + { + return std::sqrt(sq); + } + }; + +It also has operators defined to compare itself to other results without taking the square root. + +Each strategy should define its return type, within the strategy class, for example: + + typedef cartesian_distance return_type; + +or: + + typedef double return_type + +for Pythagoras and spherical, respectively. + +Again our distance function will be modified, as expected, to reflect the new return type. +For the overload with a strategy it is not complex: + + template < typename G1, typename G2, typename Strategy > + typename Strategy::return_type distance( G1 const& G1 , G2 const& G2 , S const& strategy) + +But for the one without strategy we have to select strategy, coordinate type, etc. +It would be spacious to do it in one line so we add a separate meta-function: + + template + struct distance_result + { + typedef typename point_type::type P1; + typedef typename point_type::type P2; + typedef typename strategy_distance + < + typename cs_tag::type, + typename cs_tag::type, + P1, P2 + >::type S; + + typedef typename S::return_type type; + }; + +and modify our distance function: + + template + inline typename distance_result::type distance(G1 const& g1, G2 const& g2) + { + // ... + } + +Of course also the apply functions in the dispatch specializations will return a result like this. +They have a strategy as a template parameter everywhere, making the less verbose version possible. + +[endsect] [/ end of section Return Type] + +[section Reversibility] + +Our `dispatch::distance` class was specialized for <`point_tag`, `segment_tag`>. +Library users can also call the distance function with a segment and a point, in that order. +Actually, there are many geometry types (polygon, box, linestring), how to implement all those +without duplicating all tag dispatching functions? The answer is that we automatically +reverse the arguments, if appropriate. For distance it is appropriate because distance is a +commutative function. We add a meta-function geometry_id, which has specializations for each +geometry type, just derived from `boost::mpl::int_`, such that it can be ordered. Point is 1, +segment is e.g. 2. + +Then we add a meta-function reverse_dispatch: + + template + struct reverse_dispatch : detail::reverse_dispatch + < + geometry_id::type::value, + geometry_id::type::value + > + {}; + +Because of the order in geometry_id, we can arrange (template) parameters in that order, +in specializations. So the detail structure looks like: + + namespace detail + { + template + struct reverse_dispatch : boost::mpl::if_c + < + (Id1 > Id2), + boost::true_type, + boost::false_type + > + {}; + } + +and our distance function will be modified again with some template meta-programming: We get + + return boost::mpl::if_c + < + boost::geometry::reverse_dispatch ::type::value, + dispatch::distance_reversed + < + typename tag::type, + typename tag::type, + G1, G2, + // strategy + >, + dispatch::distance + < + typename tag::type, + typename tag::type, + G1, G2, + // strategy + > + >::type::apply(g1, g2, s); + +Where the `dispatch::distance_reversed` is a specific struct, forwarding its call to +`dispatch::distance`, reversing all its template arguments and function arguments. + +[endsect] [/ end of section Reversibility] + +[section Multi] +['TODO: What to do with this section? --mloskot] +[endsect] [/ end of section Multi] + +[section SFINAE] + +[/TODO: explain a bit more and link --mloskot] + +Instead of tag dispatching we alternatively could have chosen for __wiki_sfinae__, mentioned above. +With __wiki_sfinae__ we add optional parameters to the function, which sole use is to make an +overload invalid for other geometry types than specified. So, for example: + + template + inline double distance(P1 const& p1, P2 const& p2, + typename boost::enable_if >::type* = 0, + typename boost::enable_if >::type* = 0) + { + return impl::distance::point_to_point(p1, p2); + } + +There would then be overloads for point-segment, point-polygon, etc. This __wiki_sfinae__: + +* gives often compiler troubles and headaches: if a user makes an error somewhere, the compiler +will not select any of the methods, and/or it will give completely incomprehensible error listings, +just because of this __wiki_sfinae__. Stated otherwise (pasted from an answer on the list): +With __wiki_sfinae__ the real error is hidden behind the phrase "Failed to specialize". +The compiler discards all overloads, because of an error somewhere, and you get this error with +clue how to go on. What you get is the error that it is just failing. All overloads are gone, +the compiler is not wrong, there is an error somewhere, but the only visible error message which +makes sense for the compiler to give is something like "failed to specialize" or "no matching +function call". With tag dispatching you get the real error message. That can also be difficult, +but the message(s), sometimes a whole list, give at least a clue of what's wrong. In this case: +add the banana-tag or add an implementation for banana. The usage of concepts should reduce the +length of the list and give a clearer error message. + +* So the essence is: compiler errors in code based on tag dispatching are easier to find than +compiler errors in code based on SFINAE, because the SFINAE-case is based on discarding overloads +and meaningful error messages are discarded as well + +* the combination of __wiki_sfinae__ and the BCCL using boost-concept-requires has been quite difficult, or impossible + +* does not support partial specializations because it is a function. The tag-dispatching function +is of course also not supporting that, but it forwards its call to the dispatch struct where +partial specializations (and member template functions) are possible. The SFINAE could do that as +well but then: why not just add one tag more and have tag dispatching instead? + +* is a trick to deceive the compiler. "As a language behavior it was designed to avoid programs becoming ill-formed" (http://en.wikipedia.org/wiki/Substitution_failure_is_not_an_error), +while tag dispatching is based on specialization, a core feature of C++ + +* is more verbose (tag dispatching makes the main free function declarations shorter) + +* several Boost reviewers appreciated the tag dispatching approach and prefered them over SFINAE + +[endsect] [/ end of section Multi] + + +[endsect] [/ end of section Design Rationale] \ No newline at end of file diff --git a/doc/quickbook/extensions.qbk b/doc/quickbook/extensions.qbk new file mode 100644 index 000000000..a7ff8165c --- /dev/null +++ b/doc/quickbook/extensions.qbk @@ -0,0 +1,50 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section Extensions (?)] +['TODO: long story about extensions here...] + +[section:io I/O] +['TODO: input/output extensions here...] + +[section DSV] +[endsect] [/ end of DSV] + +[section SVG] +[endsect] [/ end of SVG] + +['TODO: end of input/output extensions here...] +[endsect] [/ end of I/O] + +[section:spatialindex Spatial Index] +['TODO: spatial indexes here...] + +[section:rtree R-tree] +['TODO: r-tree index here...] +[endsect] [/ end of R-tree] + +['TODO: end of spatial indexes here...] +[endsect] [/ end of Spatial Index] + +[section GIS] + +[section:io I/O] +['TODO: gis specific input/output here...] +[endsect] [/ end of I/O] + +[section Projections] +['TODO: projections here...] +[endsect] [/ end of Projections] + +['TODO: end of long GIS story here...] +[endsect] [/ end of GIS] + +['TODO: end of long story about extensions here...] +[endsect] [/ end of section Extensions] diff --git a/doc/quickbook/geometries.qbk b/doc/quickbook/geometries.qbk new file mode 100644 index 000000000..b869633bd --- /dev/null +++ b/doc/quickbook/geometries.qbk @@ -0,0 +1,36 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section Geometries] + +Boost Geometry can be used with the geometry types provided by the library, as well as with +custom geometry types which can be registered for Boost Geometry using traits or dedicated +registration macros. + +This section refers to the geometry types provided by the library wich are ready to use +and do not require to be adapted or registered for the library. + +[/ section Geometry Concepts] +[include geometry_concepts.qbk] +[/ end of section Geometry Concepts] + +[/ section Geometry Types] +[include geometry_types.qbk] +[/ end of section Geometry Types] + +[section:adaption Adaption and Registration (?)] +['TODO: adapting user-defined geometry types...] +[endsect] [/ end of section Adaption and Registration] + +[heading Headers] + + #include + +[endsect] [/ end of section Geometries] diff --git a/doc/quickbook/geometry.qbk b/doc/quickbook/geometry.qbk new file mode 100644 index 000000000..ae7299724 --- /dev/null +++ b/doc/quickbook/geometry.qbk @@ -0,0 +1,119 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[article Geometry + [quickbook 1.4] + [version 1.0] + [authors [Gehrels, Barend], [Lalande, Bruno], [Loskot, Mateusz]] + [copyright 2010 Barend Gehrels, Bruno Lalande, Mateusz Loskot] + [purpose Documentation of Boost.Geometry library] + [license + Distributed under 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]) + ] + [id geometry] + [dirname /home/mloskot/dev/ggl/_svn/trunk] + [category geometry] +] + +[/ External link macros ///////////////////////////////////////////////////////] + +[def __ggl__ [@http://trac.osgeo.org/ggl/ Generic Geometry Library]] +[def __ogc__ [@http://www.opengeospatial.org/ OGC]] +[def __cln__ [@http://www.ginac.de/CLN/ CLN]] +[def __gmp__ [@http://gmplib.org/ GMP]] +[def __stl__ [@http://www.sgi.com/tech/stl/ STL]] +[def __stlport__ [@http://stlport.sourceforge.net/ STLPort]] +[def __gcc__ [@http://gcc.gnu.org/ GNU C++]] +[def __msvc__ [@http://msdn.microsoft.com/en-us/visualc/ Microsoft Visual C++]] +[def __msvs__ [@http://msdn.microsoft.com/en-us/vstudio/ Microsoft Visual Studio]] +[def __msvs_express__ [@http://msdn.microsoft.com/express/ Microsoft Visual Studio Express]] +[def __geodan__ [@http://www.geodan.com/ Geodan]] +[def __mloskot__ [@http://mateusz.loskot.net/ Mateusz Loskot]] + +[/ Boost general] +[def __boost__ [@http://www.boost.org/ Boost]] +[def __boost_cpp_lib__ [@http://www.boost.org/ Boost C++ Libraries]] +[def __boost_gs__ [@http://www.boost.org/doc/libs/release/more/getting_started/index.html Boost Getting Started]] +[def __boost_gtp__ [@http://www.boost.org/community/generic_programming.html Generic Programming Techniques]] +[def __boost_bb__ [@http://www.boost.org/doc/tools/build/index.html Boost Build]] +[/ Boost libraries] +[def __boost_array__ [@http://www.boost.org/libs/array/ Boost Array]] +[def __boost_graph__ [@http://www.boost.org/libs/graph/ Boost Graph Library (BGL)]] +[def __boost_concept__ [@http://www.boost.org/libs/concept_check/ Boost Concept Check Library (BCCL)]] +[def __boost_conversion__ [@http://www.boost.org/libs/conversion/ Boost Conversion]] +[def __boost_geometry__ [@http://trac.osgeo.org/ggl/ Boost Geometry]] +[def __boost_gil__ [@http://www.boost.org/libs/gil/ Boost GIL]] +[def __boost_iterator__ [@http://www.boost.org/libs/iterator/ Boost Iterator]] +[def __boost_mpl__ [@http://www.boost.org/libs/gil/ Boost Metaprogramming Library (MPL)]] +[def __boost_numericadaptor__ [@http://svn.boost.org/svn/boost/sandbox/numeric_adaptor/ Boost Numeric Adaptor]] +[def __boost_numericconv__ [@http://www.boost.org/libs/numeric/conversion/ Boost Numeric Conversion]] +[def __boost_range__ [@http://www.boost.org/libs/range/ Boost Range]] +[def __boost_smart_ptr__ [@http://www.boost.org/libs/smart_ptr/ Boost Smart Pointers]] +[def __boost_staticassert__ [@http://www.boost.org/libs/static_assert/ Boost Static Assert]] +[def __boost_stringalgo__ [@http://www.boost.org/libs/algorithm/string/ Boost String Algorithms]] +[def __boost_test__ [@http://www.boost.org/libs/test/ Boost Test]] +[def __boost_timer__ [@http://www.boost.org/libs/timer/ Boost Timer]] +[def __boost_traits__ [@http://www.boost.org/libs/type_traits/ Boost TypeTraits]] +[def __boost_tokenizer__ [@http://www.boost.org/libs/tokenizer/ Boost Tokenizer]] +[def __boost_tuple__ [@http://www.boost.org/libs/tuple/ Boost Tuple]] +[def __boost_ublas__ [@http://www.boost.org/libs/numeric/ublas/ Boost uBLAS]] + +[/ Wikipedia] +[def __wiki_cs_cartesian__ [@http://en.wikipedia.org/wiki/Cartesian_coordinate_system Cartesian coordinate system]] +[def __wiki_cs_spherical__ [@http://en.wikipedia.org/wiki/Spherical_coordinate_system Spherical coordinate system]] +[def __wiki_cs_geographic__ [@http://en.wikipedia.org/wiki/Geographic_coordinate_system Geographic coordinate system]] +[def __wiki_demorgan_laws__ [@http://en.wikipedia.org/wiki/De_Morgan%27s_laws De Morgan's laws]] +[def __wiki_set_algebra__ [@http://en.wikipedia.org/wiki/Algebra_of_sets Algebra of Sets]] +[def __wiki_set_law_complements__ [@http://en.wikipedia.org/wiki/Algebra_of_sets#Some_additional_laws_for_complements Laws for Complements]] +[def __wiki_set_theory__ [@http://en.wikipedia.org/wiki/Set_(mathematics) Set Theory]] +[def __wiki_sfinae__ [@http://en.wikipedia.org/wiki/Substitution_failure_is_not_an_error SFINAE]] +[def __wiki_std__ [@http://en.wikipedia.org/wiki/C%2B%2B_Standard_Library C++ Standard Library]] +[def __wiki_weiler_atherton__ [@http://en.wikipedia.org/wiki/Weiler-Atherton_clipping_algorithm Weiler-Atherton clipping algorithm]] +[def __wiki_complex_linear__ [@http://en.wikipedia.org/wiki/Linear_time#Linear_time Linear time]] + +[/ Images macros //////////////////////////////////////////////////////////////] +[def __img_quickstart_output__ [$./images/quickstart_output.png]] +[def __img_set_a_ac__ [$./images/set_a_ac.png]] +[def __img_set_adapt_turns__ [$./images/set_adapt_turns.png]] +[def __img_set_int_right_union_left__ [$./images/set_int_right_union_left.png]] + +[/ Internal link macros ///////////////////////////////////////////////////////] +[/ Concepts and models] +[def __concepts__ [link geometry.reference.geometries.concepts concepts]] +[def __concept_point__ [link geometry.reference.geometries.concepts.point Point]] +[def __concept_constpoint__ [link geometry.reference.geometries.concepts.constpoint ConstPoint]] +[def __model_point__ [link geometry.reference.geometries.types.points.point point]] +[def __model_point_xy__ [link geometry.reference.geometries.types.points.point_xy point_xy]] +[/ Arithmetic] +[def __area__ [link geometry.reference.algorithms.area area]] +[def __distance__ [link geometry.reference.algorithms.distance distance]] +[def __add_point__ [link geometry.reference.arithmetic.add_point add_point]] + +[/ Character and entities macrods /////////////////////////////////////////////] + +[def __set_complement__ c] +[def __set_difference__ \\] +[def __set_symdifference__ ∆] [/ ∆] +[def __set_intersect__ ∩] [/ ∩] +[def __set_union__ ∪] [/ ∪] + +[/ Content starts here ////////////////////////////////////////////////////////] + +This is the documentation of the newest version of __ggl__ (current Subversion trunk). + +[include introduction.qbk] +[include tutorial.qbk] +[include overview.qbk] +[include reference.qbk] +[include extensions.qbk] +[include misc.qbk] +[include references.qbk] \ No newline at end of file diff --git a/doc/quickbook/geometry_concepts.qbk b/doc/quickbook/geometry_concepts.qbk new file mode 100644 index 000000000..27964ddcf --- /dev/null +++ b/doc/quickbook/geometry_concepts.qbk @@ -0,0 +1,232 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:concepts Geometry Concepts] + +[:['["A concept is a set of requirements consisting of valid expressions, +associated types, invariants, and complexity guarantees]] + +-- David Abrahams, __boost_gtp__ +] + +Boost Geometry is a generic library. Instead of providing a collection of concrete and +final definitions of types and algorithms, the library rather lets users to generate +them based on parameters specified during templates specialization. + +Boost Geometry uses concepts as a technique for describing requirements on types and +combinations of types. This mechanism allows precise specification of requirements on +template parameters which can be used to instantiate concrete types. It means that +a geometry type, in order to be usable with Boost Geometr algorithms, has to model +specific concepts which corresponds to a role that particular type is dedicated to play. + +Boost Geometry uses __boost_concept__ to define checking classes, specify and verify +concept requirements. The mechanism of concepts uses standard C++ and introduce no +run-time overhead as it is compile-time technique. + +Boost Geometry algorithms necessarily impose restrictions on the types that they take, +so they heavily rely on concepts. It means that all algorithms can work with the provided +geometries as well as user-defined and custom geometries as long as all geometry types +model required concepts. + +[/ TODO: declaring? shouldn't be using?] +By declaring registration macros or by specializating type traits it is possible to adapt +user-defined or even legacy geometry types to fulfil requirements of Boost Geometry as +defined by concepts. + +In practice, it means that Boost Geometry potentially can handle geometry types in +variety of forms and definitions, like: + +* predefined geometry types provided by the library +* user-defined type for point geometry +* tuples as point geometry types +* sequences of elments of fundamental types as coordinates +* sequences of elments of user-defined point types +* various legacy geometries + +For definition of point geometry, number of choices are possible: + +* user-defined class +* C array of coordiantes +* __boost_tuple__ or `std::pair` [/ TODO: confirm if std::pair is usable] + +Boost Geometry uses __boost_range__ library to access various sequences in unified manner +and thus it is capable to iterate over elements of: + +* C array +* C++ standard sequences: `std::vector`, `std::deque`, `std::array` +* a range specified by a pair of iterators +* __boost_array__ + +Boost Geometry specifies concepts for the following single geometries: + +* point +* line segment +* linestring (line, polyline) +* ring (linearring) +* box +* polygon + +Concepts are also provided for homogeneous aggregate geometries: + +* multipoint +* multilinestring +* multipolygon + +The aggregate geometry types are considered as ranges of points, linestrings and polygons, +respectively. + +[/Explanation of the terms included only next to the Point concept below to + help to diest concepts presentation full definitions at + http://www.sgi.com/tech/stl/doc_introduction.html] +[section Point] + +[/Description - A summary of the concept's purpose.] +[heading Description] + +A Point is a 0-dimensional entity that has a location on a plane or in space. + +[/Notation - defines meaning of variables and identifiers used in definitions, + valid expressions and expression semantics.] +[variablelist Notation + [[`G`] [A type that is a model of `Point`]] + [[`D`] [An integral constant specifying number of dimensions of coordinate space]] + [[`K`] [An integral constant specifying nth-dimension of `D`-dimensional coordinate space]] + [[`p`] [Object of type `G`]] + [[`v`] [An arbitrary (?) numeric value ['TODO: arbitrary value? --mloskot] ]] +] + +[/Refinement - A list of other concepts that this concept refines.] +[heading Refinement of] + +none + +[/Associated Types - named types related to the modeling type, participate valid + expressions, value of constraint variable, parameter.] +[/heading Associated Types] +[heading Associated types] + +[table + [[Type] [Expression] [Description]] + [[Geometry tag] + [`boost::geometry::traits::tag::type`] + [Identifier of a point geometry type]] + [[Coordinate type] + [`boost::geometry::traits::coordinate_type::type`] + [Type of values of coordinates]] + [[Dimmension value] + [`boost::geometry::traits::dimension::value`] + [Value indicating number of coordinate dimensions (2, 3, ...)]] + [[Coordinate access type] + [`boost::geometry::traits::access`] + [Type implementing read and write access to point coordinates]] + [[Coordinate system type] + [`boost::geometry::traits::coordinate_system::type`] + [Definition of coordinate system, for instance cartesian or spherical, etc.]] +] + +[heading Valid Expressions] + +[table + [[Expression] [Return Type] [Type Requirements]] + [[`p.get()`] [`boost::geometry::traits::coordinate_type::type`][]] + [[`p.set(v)`] [][`p` is mutable, `v` is convertible to `boost::geometry::traits::coordinate_type::type`]] +] + +[heading Expression Semantics] + +The semantics of an expression are defined only where they differ from, or are not defined in +DefaultConstructible, CopyConstructible, Assignable. + +[table + [[Expression] [Semantics]] + [[`p.get()`] []] + [[`p.set(v)`] []] +] + +[/Model - A list of examples of types that are models of this concept.] +[heading Models] + +* __model_point__ +* __model_point_xy__ + +[/Header - A definition, link to the source code where concept is defined.] +[heading Header] + #include + +[endsect] [/ end of section Concept Point] + +[section ConstPoint] + +[heading Description] + +A Point is a 0-dimensional entity that has a location on a plane or in space, +but does not apply write access to its coordinates. + +[variablelist Notation + [[`G`] [A type that is a model of `Point`]] + [[`D`] [An integral constant]] + [[`K`] [An integral constant specifying nth-dimension of `D`-dimensional coordinate space]] + [[`p`] [Object of type `G`]] + [[`v`] [An arbitrary (?) numeric value ['TODO: arbitrary value? --mloskot] ]] +] + +[heading Refinement of] + +__concept_point__ + +[heading Associated types] + +[table + [[Type] [Expression] [Description]] + [[Geometry tag] + [`boost::geometry::traits::tag::type`] + [Identifier of a point geometry type]] + [[Coordinate type] + [`boost::geometry::traits::coordinate_type::type`] + [Type of values of coordinates]] + [[Dimmension value] + [`boost::geometry::traits::dimension::value`] + [Value indicating number of coordinate dimensions (2, 3, ...)]] + [[Coordinate access type] + [`boost::geometry::traits::access`] + [Type implementing read-only access to point coordinates]] + [[Coordinate system type] + [`boost::geometry::traits::coordinate_system::type`] + [Definition of coordinate system, for instance cartesian or spherical, etc.]] +] + +[heading Valid Expressions] + +[table + [[Expression] [Return Type] [Type Requirements]] + [[`p.get()`] [`boost::geometry::traits::coordinate_type::type`][`p` is immutable]] +] + +[heading Expression Semantics] + +The semantics of an expression are defined only where they differ from, or are not defined +in Point. + +[table + [[Expression] [Semantics]] + [[`p.get()`] []] +] + +[heading Models] + +['TODO] + +[heading Header] + + #include + +[endsect] [/ end of section Concept ConstPoint] + +[endsect] [/ end of section Concepts] diff --git a/doc/quickbook/geometry_types.qbk b/doc/quickbook/geometry_types.qbk new file mode 100644 index 000000000..8be790bb8 --- /dev/null +++ b/doc/quickbook/geometry_types.qbk @@ -0,0 +1,209 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:types Geometry Types] + +Boost.Geometry provides a collection of geometry models as class templates and their +specializations. + +[section Points] + +[section point] + +__model_point__ is a data type for 0-dimensional mathematical object, point, specified in +n-dimensional Euclidean space using n coordinates defined in a neutral way. ['TODO: What does the "neutral way" mean? --mloskot] + +[h4 Header] + + #include + +[h4 Synopsis] + + namespace boost { namespace geometry { + + template + class point + { + point(); + point(T const& v0, T const& v1 = 0, T const& v2 = 0); + + template + T const& get() const; + + template + void set(T value); + }; + }} + +[h4 Template Parameters] + +[table + [[Parameter] [Requirement] [Description]] + [[T] [] [Type of numeric coordinates. For example `double`, `float`, `int`, a type of + arbitrary-precision arithmetic provided by __boost_numericadaptor__]] + [[D] [`0 < D`] [Value of number of coordinate space dimensions. For example `2` for two-dimensional plane]] + [[C] [] [Type of coordinate system. For example `boost::geometry::cs::cartesian`]] + [[K] [`0 < K < D`] [Value identifying coordiante nth-dimension of D dimensions.]] +] + +[h4 Model of] + +__concept_point__ + +[h4 Description] + + point(); + +[*Effects:] Constructs an object of the class point, no initialization of coordinate values occurs. + + point(T const& v0, T const& v1 = 0, T const& v2 = 0); + +[*Effects:] Constructs an object of the class point with initialization of all three coordinate values. + + template + T const& get() const; + +[*Requires:] Value `K` is less-than value `D` specified as the class template parameter. + +[*Effects:] Returns value of K-th coordinate of the point object. + + template + void set(T value); + +[*Requires:] Value `K` is less-than value `D` specified as the class template parameter. + +[*Effects:] Sets value of K-th coordinate in the point object. + +[h4 Example] + + // create point object + point p; + // set coordinate values + p.set<0>(1.0); + p.set<1>(2.0); + // query coordinates + double r = p.get<0>(); + double i = p.get<1>(); + +[endsect] [/ end of section point] + +[section point_xy] + +__model_point_xy__ is a data type for 0-dimensional mathematical object, point, specified in +two-dimensional Euclidean space using two coordinates, `x` and `y`. + +[h4 Header] + + #include + +[h4 Synopsis] + + namespace boost { namespace geometry { + + template + class point_xy + { + point_xy(); + point_xy(T const& x, T const& y); + + T const& get<0>() const; + T const& get<1>() const; + + void set<0>(T value); + void set<1>(T value); + + T const& x() const + T const& y() const; + + void x(T const& v); + void y(T const& v); + }; + }} + +[h4 Template Parameters] + +[table + [[Parameter] [Requirement] [Description]] + [[T] [] [Type of numeric coordinates. For example `double`, `float`, `int`, a type of + arbitrary-precision arithmetic provided by __boost_numericadaptor__]] + [[C] [] [Type of coordinate system. For example `boost::geometry::cs::cartesian`]] +] + +[h4 Model of] + +__concept_point__ + +[h4 Description] + + point_xy(); + +[*Effects:] Constructs an object of the class point_xy, no initialization of coordinate values occurs. + + point_xy(T const& x, T const& y); + +[*Effects:] Constructs an object of the class point_xy with initialization of both coordinate values. + + T const& get<0>() const; + +[*Effects:] Returns value, of the first coordinate of the point object, namely of the `x` coordinate. + + T const& get<1>() const; + +[*Effects:] Returns value, of the second coordinate of the point object, namely of the `y` coordinate. + + void set<0>(T value); + +[*Effects:] Sets value, of the first coordinate of the point object, namely of the `x` coordinate. + + void set<1>(T value); + +[*Effects:] Sets value, of the second coordinate of the point object, namely of the `y` coordinate. + + T const& x() const; + +[*Effects:] Returns value, of the first coordinate of the point object, namely of the `x` +coordinate. Named accessor provided for convenience, uses `get<0>()`. + + T const& y() const; + +[*Effects:] Returns value, of the second coordinate of the point object, namely of the `y` +coordinate. Named accessor provided for convenience, uses `get<1>()`. + + void x(T const& v); + +[*Effects:] Sets value, of the first coordinate of the point object, namely of the `x` coordinate. +Named accessor provided for convenience, uses `set<0>()`. + + void y(T const& v); + +[*Effects:] Sets value, of the second coordinate of the point object, namely of the `y` coordinate. +Named accessor provided for convenience, uses `set<1>()`. + +[h4 Example] + + // create object with initialized coordinates + point_xy p(5, 7); + // query coordinates + int x = p.get<0>(); + int y = p.get<1>(); + +[endsect] [/ end of section point_xy] + +[endsect] [/ end of section Points] + +[section Lines] +['TODO: built-in line types...] +[endsect] + +[section Polygons] +['TODO: built-in polygon types...] +[endsect] + +[endsect] [/ end of section Geometry Types] diff --git a/doc/quickbook/html/boostbook.css b/doc/quickbook/html/boostbook.css new file mode 100644 index 000000000..0a72f7814 --- /dev/null +++ b/doc/quickbook/html/boostbook.css @@ -0,0 +1,598 @@ +/*============================================================================= + Copyright (c) 2004 Joel de Guzman + http://spirit.sourceforge.net/ + + Distributed under the Boost Software License, Version 1.0. (See accompany- + ing file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) +=============================================================================*/ + +/*============================================================================= + Body defaults +=============================================================================*/ + + body + { + margin: 1em; + font-family: sans-serif; + } + +/*============================================================================= + Paragraphs +=============================================================================*/ + + p + { + text-align: left; + font-size: 10pt; + line-height: 1.15; + } + +/*============================================================================= + Program listings +=============================================================================*/ + + /* Code on paragraphs */ + p tt.computeroutput + { + font-size: 9pt; + } + + pre.synopsis + { + font-size: 90%; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + .programlisting, + .screen + { + font-size: 9pt; + display: block; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + /* Program listings in tables don't get borders */ + td .programlisting, + td .screen + { + margin: 0pc 0pc 0pc 0pc; + padding: 0pc 0pc 0pc 0pc; + } + +/*============================================================================= + Headings +=============================================================================*/ + + h1, h2, h3, h4, h5, h6 + { + text-align: left; + margin: 1em 0em 0.5em 0em; + font-weight: bold; + } + + h1 { font: 140% } + h2 { font: bold 140% } + h3 { font: bold 130% } + h4 { font: bold 120% } + h5 { font: italic 110% } + h6 { font: italic 100% } + + /* Top page titles */ + title, + h1.title, + h2.title + h3.title, + h4.title, + h5.title, + h6.title, + .refentrytitle + { + font-weight: bold; + margin-bottom: 1pc; + } + + h1.title { font-size: 140% } + h2.title { font-size: 140% } + h3.title { font-size: 130% } + h4.title { font-size: 120% } + h5.title { font-size: 110% } + h6.title { font-size: 100% } + + .section h1 + { + margin: 0em 0em 0.5em 0em; + font-size: 140%; + } + + .section h2 { font-size: 140% } + .section h3 { font-size: 130% } + .section h4 { font-size: 120% } + .section h5 { font-size: 110% } + .section h6 { font-size: 100% } + + /* Code on titles */ + h1 tt.computeroutput { font-size: 140% } + h2 tt.computeroutput { font-size: 140% } + h3 tt.computeroutput { font-size: 130% } + h4 tt.computeroutput { font-size: 130% } + h5 tt.computeroutput { font-size: 130% } + h6 tt.computeroutput { font-size: 130% } + + +/*============================================================================= + Author +=============================================================================*/ + + h3.author + { + font-size: 100% + } + +/*============================================================================= + Lists +=============================================================================*/ + + li + { + font-size: 10pt; + line-height: 1.3; + } + + /* Unordered lists */ + ul + { + text-align: left; + } + + /* Ordered lists */ + ol + { + text-align: left; + } + +/*============================================================================= + Links +=============================================================================*/ + + a + { + text-decoration: none; /* no underline */ + } + + a:hover + { + text-decoration: underline; + } + +/*============================================================================= + Spirit style navigation +=============================================================================*/ + + .spirit-nav + { + text-align: right; + } + + .spirit-nav a + { + color: white; + padding-left: 0.5em; + } + + .spirit-nav img + { + border-width: 0px; + } + +/*============================================================================= + Copyright footer +=============================================================================*/ + .copyright-footer + { + text-align: right; + font-size: 70%; + } + + .copyright-footer p + { + text-align: right; + font-size: 80%; + } + +/*============================================================================= + Table of contents +=============================================================================*/ + + .toc + { + margin: 1pc 4% 0pc 4%; + padding: 0.1pc 1pc 0.1pc 1pc; + font-size: 80%; + line-height: 1.15; + } + + .boost-toc + { + float: right; + padding: 0.5pc; + } + + /* Code on toc */ + .toc .computeroutput { font-size: 120% } + +/*============================================================================= + Tables +=============================================================================*/ + + .table-title, + div.table p.title + { + margin-left: 4%; + padding-right: 0.5em; + padding-left: 0.5em; + } + + .informaltable table, + .table table + { + width: 92%; + margin-left: 4%; + margin-right: 4%; + } + + div.informaltable table, + div.table table + { + padding: 4px; + } + + /* Table Cells */ + div.informaltable table tr td, + div.table table tr td + { + padding: 0.5em; + text-align: left; + font-size: 9pt; + } + + div.informaltable table tr th, + div.table table tr th + { + padding: 0.5em 0.5em 0.5em 0.5em; + border: 1pt solid white; + font-size: 80%; + } + + table.simplelist + { + width: auto !important; + margin: 0em !important; + padding: 0em !important; + border: none !important; + } + table.simplelist td + { + margin: 0em !important; + padding: 0em !important; + text-align: left !important; + font-size: 9pt !important; + border: none !important; + } + +/*============================================================================= + Blurbs +=============================================================================*/ + + div.note, + div.tip, + div.important, + div.caution, + div.warning, + p.blurb + { + font-size: 9pt; /* A little bit smaller than the main text */ + line-height: 1.2; + display: block; + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; + } + + p.blurb img + { + padding: 1pt; + } + +/*============================================================================= + Variable Lists +=============================================================================*/ + + div.variablelist + { + margin: 1em 0; + } + + /* Make the terms in definition lists bold */ + div.variablelist dl dt, + span.term + { + font-weight: bold; + font-size: 10pt; + } + + div.variablelist table tbody tr td + { + text-align: left; + vertical-align: top; + padding: 0em 2em 0em 0em; + font-size: 10pt; + margin: 0em 0em 0.5em 0em; + line-height: 1; + } + + div.variablelist dl dt + { + margin-bottom: 0.2em; + } + + div.variablelist dl dd + { + margin: 0em 0em 0.5em 2em; + font-size: 10pt; + } + + div.variablelist table tbody tr td p, + div.variablelist dl dd p + { + margin: 0em 0em 0.5em 0em; + line-height: 1; + } + +/*============================================================================= + Misc +=============================================================================*/ + + /* Title of books and articles in bibliographies */ + span.title + { + font-style: italic; + } + + span.underline + { + text-decoration: underline; + } + + span.strikethrough + { + text-decoration: line-through; + } + + /* Copyright, Legal Notice */ + div div.legalnotice p + { + text-align: left + } + +/*============================================================================= + Colors +=============================================================================*/ + + @media screen + { + body { + background-color: #FFFFFF; + color: #000000; + } + + /* Links */ + a + { + color: #005a9c; + } + + a:visited + { + color: #9c5a9c; + } + + h1 a, h2 a, h3 a, h4 a, h5 a, h6 a, + h1 a:hover, h2 a:hover, h3 a:hover, h4 a:hover, h5 a:hover, h6 a:hover, + h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited + { + text-decoration: none; /* no underline */ + color: #000000; + } + + /* Syntax Highlighting */ + .keyword { color: #0000AA; } + .identifier { color: #000000; } + .special { color: #707070; } + .preprocessor { color: #402080; } + .char { color: teal; } + .comment { color: #800000; } + .string { color: teal; } + .number { color: teal; } + .white_bkd { background-color: #FFFFFF; } + .dk_grey_bkd { background-color: #999999; } + + /* Copyright, Legal Notice */ + .copyright + { + color: #666666; + font-size: small; + } + + div div.legalnotice p + { + color: #666666; + } + + /* Program listing */ + pre.synopsis + { + border: 1px solid #DCDCDC; + } + + .programlisting, + .screen + { + border: 1px solid #DCDCDC; + } + + td .programlisting, + td .screen + { + border: 0px solid #DCDCDC; + } + + /* Blurbs */ + div.note, + div.tip, + div.important, + div.caution, + div.warning, + p.blurb + { + border: 1px solid #DCDCDC; + } + + /* Table of contents */ + .toc + { + border: 1px solid #DCDCDC; + } + + /* Tables */ + div.informaltable table tr td, + div.table table tr td + { + border: 1px solid #DCDCDC; + } + + div.informaltable table tr th, + div.table table tr th + { + background-color: #F0F0F0; + border: 1px solid #DCDCDC; + } + + .copyright-footer + { + color: #8F8F8F; + } + + /* Misc */ + span.highlight + { + color: #00A000; + } + } + + @media print + { + /* Links */ + a + { + color: black; + } + + a:visited + { + color: black; + } + + .spirit-nav + { + display: none; + } + + /* Program listing */ + pre.synopsis + { + border: 1px solid gray; + } + + .programlisting, + .screen + { + border: 1px solid gray; + } + + td .programlisting, + td .screen + { + border: 0px solid #DCDCDC; + } + + /* Table of contents */ + .toc + { + border: 1px solid gray; + } + + .informaltable table, + .table table + { + border: 1px solid gray; + border-collapse: collapse; + } + + /* Tables */ + div.informaltable table tr td, + div.table table tr td + { + border: 1px solid gray; + } + + div.informaltable table tr th, + div.table table tr th + { + border: 1px solid gray; + } + + table.simplelist tr td + { + border: none !important; + } + + /* Misc */ + span.highlight + { + font-weight: bold; + } + } + +/*============================================================================= + Images +=============================================================================*/ + + span.inlinemediaobject img + { + vertical-align: middle; + } + +/*============================================================================== + Super and Subscript: style so that line spacing isn't effected, see + http://www.adobe.com/cfusion/communityengine/index.cfm?event=showdetails&productId=1&postId=5341 +==============================================================================*/ + +sup, +sub { + height: 0; + line-height: 1; + vertical-align: baseline; + _vertical-align: bottom; + position: relative; + +} + +sup { + bottom: 1ex; +} + +sub { + top: .5ex; +} + diff --git a/doc/quickbook/html/images/quickstart_output.png b/doc/quickbook/html/images/quickstart_output.png new file mode 100644 index 000000000..184ba5965 Binary files /dev/null and b/doc/quickbook/html/images/quickstart_output.png differ diff --git a/doc/quickbook/html/images/set_a_ac.png b/doc/quickbook/html/images/set_a_ac.png new file mode 100644 index 000000000..2ba18a700 Binary files /dev/null and b/doc/quickbook/html/images/set_a_ac.png differ diff --git a/doc/quickbook/html/images/set_adapt_turns.png b/doc/quickbook/html/images/set_adapt_turns.png new file mode 100644 index 000000000..cfa3375e7 Binary files /dev/null and b/doc/quickbook/html/images/set_adapt_turns.png differ diff --git a/doc/quickbook/html/images/set_int_right_union_left.png b/doc/quickbook/html/images/set_int_right_union_left.png new file mode 100644 index 000000000..9c2bc84f4 Binary files /dev/null and b/doc/quickbook/html/images/set_int_right_union_left.png differ diff --git a/doc/quickbook/introduction.qbk b/doc/quickbook/introduction.qbk new file mode 100644 index 000000000..5ef122821 --- /dev/null +++ b/doc/quickbook/introduction.qbk @@ -0,0 +1,52 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section Introduction] + +The __boost_geometry__ (aka Generic Geometry Library, GGL), part of collection of +the Boost C++ Libraries, defines concepts, primitives and algorithms for solving +computational geometry problems. + +The __boost_geometry__ contains a dimension-agnostic, coordinate-system-agnostic +and scalable kernel, based on concepts, meta-functions and tag- dispatching. +On top of that kernel, algorithms are built: area, length, perimeter, centroid, +convex hull, intersection (clipping), within (point in polygon), distance, +envelope (bounding box), simplify, transform, convert, and more. +The library is also designed to support high precision arithmetic numbers, +such as __gmp__. + +The Boost Geometry contains instantiable geometry classes, but library users can +also use their own. Using registration macros or traits classes their geometries +can be adapted to fulfil the Boost Geometry concepts. + +The Boost Geometry might be used in all domains where geometry plays a role: +mapping and GIS, game development, computer graphics and widgets, robotics, +astronomy and more. The core is designed to be as generic as possible and support +those domains. However, for now the development has been mostly GIS-oriented. + +The Boost Geometry supports the extension model, the same way as __boost_gil__ +also applies it. An extension is (mostly) something more specific to +like mentioned above. + +The library follows existing conventions: + +* conventions from boost +* conventions from the std library +* conventions and names from one of the __ogc__ standards on geometry + +This Generic Geometry Library (Boost Geometry) is now being reviewed by +the Boost Community + +The library can be downloaded from the Boost Sandbox, go to the download page +for more information. + +The Boost Geometry bug tracker and Wiki are available at http://trac.osgeo.org/ggl/ + +[endsect] \ No newline at end of file diff --git a/doc/quickbook/iterators.qbk b/doc/quickbook/iterators.qbk new file mode 100644 index 000000000..0d8c50309 --- /dev/null +++ b/doc/quickbook/iterators.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section Iterators (?)] +['TODO: long story about iterators...] + +['TODO: end of long story about iterators...] +[endsect] [/ end of section Iterators] diff --git a/doc/quickbook/misc.qbk b/doc/quickbook/misc.qbk new file mode 100644 index 000000000..3d082086f --- /dev/null +++ b/doc/quickbook/misc.qbk @@ -0,0 +1,172 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:misc Miscellaneous] +['TODO: long misc stories here...] + +[section:release Release Notes (?)] [/TODO: current status] +['TODO: about giving birth here...] +[endsect] [/ end of Release Notes] + +[section Compilation] + +__boost_geometry__ is a headers-only library. Users only need to include the library +headers in their programs in order to be able to access definitions and algorithms +provided by the __boost_geometry__ library. No linking against any binaries is required. + +__boost_geometry__ is only dependant on headers-only __boost__ libraries. +It does not introduce indirect dependencies on any binary libraries. + +In order to be able to use __boost_geometry__, the only thing users need to do is to +install __boost_cpp_lib__ and specify location to include directories, so `include` +directives of this scheme will work: + + #include + +[heading Supported Compilers] + +__boost_geometry__ library has been successfully tested with the following compilers: + +* __msvc__ (including Express Edition) + * 9.0 (__msvs__ 2008) + * 8.0 (__msvs__ 2005) +* __gcc__ + * 4.x (confirmed versoins 4.1, 4.2, 4.4) + * 3.4 + +For __msvs__, the examples contains some project files (for 2005). However, because the library +is header only, it will be no problem to integrate it in your own project files. + +__boost_geometry__ uses __boost_bb__, a text-based system for developing and testing software, to +configure, build and execute unit tests and example programs. The build configuration is provided +as a collection of `Jamfile.v2` files. + +For __gcc__ , flag `-Wno-long-long` can be used to surpress some warnings originating from Boost. + +[heading Basic Includes] + +This section concentrates on how to include __boost_geometry__ headers efficiently. + +['TODO: link header names to files? --mloskot] + +The most convenient headerfile including all algorithms and strategies is `geometry.hpp`: + + #include + +This is the main header of the __boost_geometry__ library and it is recommended to include this file. + +Alternatively, it is possible to include __boost_geometry__ header files separately. However, +this may be inconvenient as header files might be renamed or moved occasionaly in future. + +Another often used header is `geometries.hpp`: + + #include + +This includes definitions of all provided geometry tyoes: __model_point__, linestring, polygon, +linear_ring, box. The `geometries.hpp` is not included in the `geometry.hpp` headerfile because +users should be given the liberty to use their own geometries and not the provided ones. +However, for the __boost_geometry__ users who want to use the provided geometries it is +useful to include it. + +For users using only Cartesian points, with floating point coordinates (of C++ type `double`), +in 2D or 3D, you can use instead: + + #include + +This includes all 2D Cartesian geometries: point_2d, linestring_2d, etc. +Using this header file, the library seems to be a non-template library, so it is convenient +for users who do not feel strong with using and specializing C++ templates on their own. + +For users using multi-geometries: + + #include + +[heading Advanced Includes] + +This section is for users who have their own geometries and want to use algorithms from +the __boost_geometry__ library. + +If you want to use your own points it makes sense to use the registration macro's: + + #include + +Defines preprocessor macros for point geometry types registration. + + #include + +Defines preprocessor macros for box geometry type registration. + +If you are using standard containers containing points and want to handle them as a linestring. + + #include + +Allows you to use things like `std::vector` and put them as parameters into algorithms. + +If you are using boost tuples and want to handle them as Cartesian points + + #include + +[heading Extensions] + +['TODO: Do we want this sub-section here? or moving completely to the Extensions node? --mloskot] + +[section Hints] + +[heading Performance] + +The enumeration below is not exhaustive but can contain hints to improve the performance: + +* For Microsoft __msvc__, set define `_SECURE_SCL=0` for preprocessor. +* For Microsoft __msvc__, set define `_HAS_ITERATOR_DEBUGGING=0` for preprocessor. +* Our measurements indicate that Visual C++ 8.0 generates faster code than Visual C++ 9.0 +* Use of __stlport__, a very popular open-source implementation of the STL, may result in + significantly faster code than use of the C++ standard library provided by __msvc__ compiler. +* Turn on compiler optimizations, compile in release mode. + +[endsect] [/ end of Hints] + +[section:issues Known Problems] + +[heading Problems with Intellisense] + +Both versions of __msvs__, 2005 and 2008 (including Express Edition) can hang trying to resolve +symbols and give [@http://en.wikipedia.org/wiki/IntelliSense IntelliSense] suggestions while +typing in a bracket or angle bracket. +This is not directly related to __boost_geometry__, but is caused by problems with handling by this +IDE large C++ code base with intensively used templates, such as Boost and __boost_geometry__. +If this is inconvenient, IntelliSense can easily be turned off: + +[:['["(...)disabling IntelliSense in VC++. There is a file called `feacp.dll` in +`/VC/vcpackages` folder. Renaming this file will disable Intellisense feature.]] + +-- [@http://blogs.msdn.com/yash/archive/2007/09/19/intellisense-issues-in-visual-c-2005.aspx Intellisense issues in Visual C++ 2005] +] + +[endsect] [/ end of Problems] + +[endsect] [/ end of Compilation] + +[section Performance (?)] +['TODO: how fast we are here...] +[endsect] [/ end of Performance] + +[section:users Who uses Boost.Geometry (?)] +['TODO: users here...] +[endsect] [/ end of Who Uses] + +[section:future Future Work (?)] [/TODO: Roadmap? --mloskot] +['TODO: roadmap here...] +[endsect] [/ end of ] + +[section Acknowledgments (?)] +['TODO: who is who here...] +[endsect] [/ end of Acknowledgments] + +[endsect] [/ end of Miscellaneous] diff --git a/doc/quickbook/overview.qbk b/doc/quickbook/overview.qbk new file mode 100644 index 000000000..908084f1a --- /dev/null +++ b/doc/quickbook/overview.qbk @@ -0,0 +1,21 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:overview Overview] + +[include design_rationale.qbk] +[include strategy_rationale.qbk] +[include boolean.qbk] + +[section Robustness (?)] +['TODO: how robust we are here...] +[endsect] + +[endsect] [/ end of section Library Overview] diff --git a/doc/quickbook/quickstart.qbk b/doc/quickbook/quickstart.qbk new file mode 100644 index 000000000..5cc3fb786 --- /dev/null +++ b/doc/quickbook/quickstart.qbk @@ -0,0 +1,63 @@ +[/============================================================================== + Copyright (c) 1995-2009 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2009 Bruno Lalande, Paris, France. + Copyright (c) 2009 Mateusz Loskot (mateusz@loskot.net) + + 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) +===============================================================================/] + +[section:quickstart Quick Start] + +It is not possible to present all features of the whole library at a glance. +However, a few very small examples are shown below. + +It should be possible to use a very small part of the library, for example +only the distance between two points. + + int a[2] = {1,1}; + int b[2] = {2,3}; + double d = distance(a, b); + std::cout << "Distance a-b is:" << d << std::endl; + +Other often used algorithms are point-in-polygon: + + ring_2d poly; + double points[][2] = {{2.0, 1.3}, {4.1, 3.0}, {5.3, 2.6}, {2.9, 0.7}, {2.0, 1.3}}; + append(poly, points); + boost::tuple p = boost::make_tuple(3.7, 2.0); + std::cout << "Point p is in polygon? " << (within(p, poly) ? "YES" : "NO") << std::endl; + +or area: + + std::cout << "Area: " << area(poly) << std::endl; + +It is possible, by the nature of a template library, to mix the point types declared above: + + double d2 = distance(a, p); + std::cout << "Distance a-p is:" << d2 << std::endl; + +The pieces above generate this output: + +__img_quickstart_output__ + +It is also possible to use non-Cartesian points. For example: points on a sphere. +When then an algorithm such as distance is used the library "inspects" that it +is handling spherical points and calculates the distance over the sphere, +instead of applying the Pythagorean theorem. + +Finally an example from a totally different domain: developing window-based applications, +for example using QtWidgets. We check if two rectangles overlap and if so, move the second +one to another place: + + QRect r1(100, 200, 15, 15); + QRect r2(110, 210, 20, 20); + if (overlaps(r1, r2)) + { + assign(r2, 200, 300, 220, 320); + } + +More examples are on the page Examples + +[endsect] diff --git a/doc/quickbook/reference.qbk b/doc/quickbook/reference.qbk new file mode 100644 index 000000000..b93570f8e --- /dev/null +++ b/doc/quickbook/reference.qbk @@ -0,0 +1,23 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section Reference] +['TODO: full reference starts here...] + +[include geometries.qbk] +[include cs.qbk] +[include algorithms.qbk] +[include arithmetic.qbk] +[include strategies.qbk] +[include iterators.qbk] +[include utilities.qbk] + +['TODO: end of full reference...] +[endsect] [/ end of section Reference] \ No newline at end of file diff --git a/doc/quickbook/references.qbk b/doc/quickbook/references.qbk new file mode 100644 index 000000000..d66ac4cba --- /dev/null +++ b/doc/quickbook/references.qbk @@ -0,0 +1,86 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section References] + +The following section lists references and relations between __boost_geometry__ and other +software libraries as well as various specifications and documents discussing subjects directly +related to the matter of the library implementation. + +[section:std C++ Standard Library] + +The __boost_geometry__ makes substantial use of the __wiki_std__ and is designed to be +compatible with it. Quick list of uses of the `std` namespace elements: + +* provided geometries (linestring, ring, polygon, multi-s) make default use of `std::vector`, + but that is configurable. +* std sorting, unique copies, maps can make use of provided functors in compare. +* internally, there are vector's, deque's, there is sorting, many things are implemented + using the std library + +[endsect] [/ end of C++Std] + +[section Boost C++ Libraries] + +The __boost_geometry__ makes use of the following __boost_cpp_lib__: + +* __boost_range__ +* __boost_traits__ (e.g. remove_const) +* __boost_concept__ +* __boost_numericconv__ (cast, bounds) +* __boost_mpl__ +* __boost_staticassert__ +* __boost_iterator__ +* __boost_smart_ptr__ (shared_ptr, in the extensions spatial index and projections) +* __boost_ublas__ +* Adapted geometries: + * __boost_array__ + * __boost_tuple__ +* IO and parsing + * __boost_tokenizer__ + * __boost_conversion__ (lexical cast) + * __boost_stringalgo__ +* Testing + * __boost_test__ + * __boost_timer__ +* Examples + * __boost_graph__ + +Many of these are used a lot inside the library. + +The __boost_range__ library is used everywhere to declare iterators and to walk through standard +containers or custom ranges. + +The __boost_concept__ is used to check concepts, for geometries as well as for strategies. + +Tranformations are implemented using __boost_ublas__ + +The __boost_mpl__ is used for a.o. reverse dispatching + +Finally, the library can perfectly be used together with the __boost_graph__, as shown in example 7. + +[endsect] [/ end of Boost] + +[section:other Other Libraries] + +__boost_geometry__ is designed to support use of arbitrary-precision arithmetic data types +and algorithms provided by third-party libraries like __gmp__ and __cln__. + +['TODO: to be extended --mloskot] + +['TODO: do we discuss only what libraries Boost Geometry core can use or extensions too? --mloskot] + +[endsect] [/ end of Other Libraries] + +[section:opengis Standards of the Open Geospatial Consortium (?)] [/TODO: matrix on Wiki] +['TODO: about ogc here...] +[endsect] [/ end of OGC] + +[endsect] [/ end of References] \ No newline at end of file diff --git a/doc/quickbook/strategies.qbk b/doc/quickbook/strategies.qbk new file mode 100644 index 000000000..93680b68f --- /dev/null +++ b/doc/quickbook/strategies.qbk @@ -0,0 +1,17 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:strategies Strategies (?)] + +[heading Headers] + + #include + +[endsect] [/ end of section Strategies] diff --git a/doc/quickbook/strategy_rationale.qbk b/doc/quickbook/strategy_rationale.qbk new file mode 100644 index 000000000..4de8aa331 --- /dev/null +++ b/doc/quickbook/strategy_rationale.qbk @@ -0,0 +1,148 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section:strategy Strategy Rationale] + +[@http://en.wikipedia.org/wiki/Strategy_pattern Strategy] is a [@http://en.wikipedia.org/wiki/Design_pattern_(computer_science) software design pattern] used to +achieve algorithms slection at runtime. An idiomatic variation of the Strategy pattern specific +to C++ programming language is known as Policy pattern with related technique of [@http://en.wikipedia.org/wiki/Policy-based_design Policy-based design]. Thus, in the C++ template +contexts, policy is usually meant as selection of algorithms at compile time. + +['TODO: the two sentences below need to be clarified, what is "another context", etc. --mloskot] + +__boost_geometry__ uses (sparsely) the term policy in a broader, or in another, context. The term +Strategy is used specificly for a computation method targeted to a specific coordinate system. + +In __boost_geometry__ strategies do have the following purposes: + +* for each coordinate system, a default strategy is selected by compile time, using the coordinate + system tag. This is effectively tag dispatching. +* users can override the default choice by using the overloaded function, which has a strategy + as an extra parameter, and take another strategy +* users can override the default choice by using the overloaded function, to use the default + strategy, but constructed with specific parameters +* users can override the default choice by using the overloaded function, to use the default + strategy (which can be a templated structure), with other template parameters then the default ones +* users can override the default choice by using the overloaded function, to use the default + strategy, which can be a class template, with other template parameters then the default ones, + with the specific purpose as to select another calculation type (e.g. __gmp__ or another + arbitrary precision number type) + +All these decisions and choices listed above occur at compile-time. + +Let's discuss a short example to explaining how strategies work in __boost_geometry__. +Note, it is also explained in the design rationale section. + +Considering calculation of distance in three common coordinate systems, for each of the coordinate +systems a default strategy implementing distance calculation has been assigned: + +* __wiki_cs_cartesian__ uses Pythagoras as default strategy for point-point distance calculations +* __wiki_cs_spherical__ uses Haversine strategy a default +* __wiki_cs_geographic__ uses Andoyer. + +The Haversine works on the unit sphere, radius `1`. Library users can use the distance function, +specifying haversine strategy constructed with a radius of `2`. Or, for example, they can +use the distance function, specifying the more precise Vincenty strategy +(for __wiki_cs_geographic__, but that might not even be checked there). + +Specifying strategies is useful, even if not point-point distance is to be calculated, for +example, point-polygon distance. In the end, it will call the elementary specified functionality. +Note, that for this example, the point-segment distance strategy is also considered as "elementary". +Note also, that it can have an optional template parameter defining the underlying +point-point-distance-strategy. + +[section:properties Properties of Strategies] + +Strategies can be constructed outside a calling function, thus they can be specified as an +optional parameter (implemented as an overloaded function), and not only as a template parameter. +Furthermore, strategies can be reused number of times, in subsequent function calls. +Therefore strategies as function parameter are declared as reference to `const` and they +should be stateless, except that they can be provided with some initialization details +during construction. + +The strategy needs to access construction information (member variables), its calculation method +is therefore usually not a `static` method but a non-static `const` method. It can then access +member variables, while still being `const`, non-mutable, stateless and read-only object, and +being able to be called across several function calls. + +['TODO: The next 2-3 paragraphs might need some refactoring, to rephrase what is said in + clearer and simple manner --mloskot] + +For some algorithms, strategies may need to store some intermediate results of calculation +(a state). For this purpose, strategies should declare a `state_type`. An instance of the `state_type` +is created before first call is performed and specified in each call. + +The calculation method is always called apply (as convention in __boost_geometry__) and gets the +most elementary information as a parameter: a point, a segment, a range. It depends on the +algorithm and, sometimes, on the source geometry passed. That should actually be the case as +least as possisble. +In most cases, there is an additional method result which returns the calculated result. +That result-method is a also non-static const method, and the state is passed. Note that the +methods might be non-static const, but they might also be static. That is not checked by the +concept-checker. + +A strategy for a specific algorithm has a concept. The distance-strategy should follow the +distance-strategy-concept. The point-in-polygon strategy should follow the +point-in-polygon-strategy-concept. Those concepts are not modelled as traits classes (contrary +to the geometries). The reason for this is that it seems not necessary to use legacy classes +as concepts, without modification. A wrapper can be built. So the strategies should have a method +apply and should define some types. + +Which types, and which additional methods (often a method result), is dependant on the algorithm +and type of strategy. + +Strategies are checked by a strategy-concept-checker. For this checker (and sometimes for +checking alone), they should define some types. Because if no types are defined, the +cannot be checked at compile time... The strategy-concept-checkers are thus implemented per +algorithm and they use the __boost_concept__ for concepts checking. + +According to what was explained above, the essentials of the design are: + +* function determines default-strategy, or is called with specified strategy +* function calls dispatch (dispatching is done on geometry tag) +* dispatch calls implementation (in namespace detail), which can be shared for different geometry + types, for single as well as for aggregate geometries (multi-geometries) +* implementation calls strategy (if applicable), with the smallest common (geometric) + element applicable for all calculation method, the common denominator. + +[endsect] [/ end of section Properties of Strategies] + +[section:alternative Alternative Design] + +Some calculations (strategies) might need to take the whole geometry, instead of working on +point-per-point or segment-per-segment base. This would bypass the dispatch functionality. +Because all strategies would take the whole geometry, it is not necessary to dispatch per +geometry type. In fact this dispatching on geometry-type is moved to the strategy_traits class +(which are specialized per coordinate system in the current design). So in this alternative design, +the strategy traits class specializes on both geometry-tag and coordinate-system-tag, to select +the default strategy. For the default strategy, this move from "dispatch" to another dispatch +called `strategy_XXX` (XXX is the algorithm) might make sense. However, if library users would +call the overloaded function and specify a strategy, the only thing what would happen is that +that specified strategy is called. + +For example: + + template + bool within(G1 const& g1, G2 const& g2, S& const strategy) + { + return strategy.apply(g1, g2); + } + +The library user could call just this `strategy.apply()` method directly. If more strategies are +provided by the library or its extensions, it would still make sense: the user can still call +within and does not have to call the apply method of the strategy. + +The convex hull strategy currently works on a whole geometry. However, it is possible that it will +be reshaped to work per range (the algorithm internally works per range), plus a mechanism to +pass ranges multiple times (it currently is two-pass). + +[endsect] [/ end of section Alternative Design] + +[endsect] [/ end of section Strategies] diff --git a/doc/quickbook/toc.qbk b/doc/quickbook/toc.qbk new file mode 100644 index 000000000..b6c243567 --- /dev/null +++ b/doc/quickbook/toc.qbk @@ -0,0 +1,182 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[article Geometry + [quickbook 1.4] + [version 1.0] + [copyright 2009 Barend Gehrels, Bruno Lalande, Mateusz Loskot] + [authors [Gehrels, Barend], [Lalande, Bruno], [Loskot, Mateusz]] + [purpose Documentation of Boost.Geometry library] + [license + Distributed under 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]) + ] +] + +[/ Links macros ///////////////////////////////////////////////////////////////] + +[def __ggl__ [@http://trac.osgeo.org/ggl/ Generic Geometry Library]] +[def __ggl_short__ [@http://trac.osgeo.org/ggl/ GGL]] +[def __stl__ [@http://www.sgi.com/tech/stl/ STL]] +[def __boost__ [@http://www.boost.org/ Boost]] +[def __boost_gil__ [@boost:/libs/gil/index.html Boost.GIL]] +[def __gnu_gmp__ [@http://gmplib.org/ GMP]] +[def __ogc__ [@http://www.opengeospatial.org/ OGC]] + +[/ Sections macros ////////////////////////////////////////////////////////////] + + [/ TODO] + +[/ Images macros //////////////////////////////////////////////////////////////] + +[def __img_quickstart_output__ [$./images/quickstart_output.png]] + +[/ Content starts here ////////////////////////////////////////////////////////] + +This is the documentation of the newest version of __ggl__ (current Subversion trunk). + +[/ TODO: This is proposal of G] + +[section Introduction] +[endsect] + +[section Tutorial] +[section Quick Start] +[endsect] +[section Examples] +[endsect] +[endsect] [/ end of section Examples] + +[section Library Overview] +[section Design Rationale] +[endsect] +[section Strategy Rationale] +[endsect] +[section Spatial set-theoretic operations] +[endsect] +[section Robustness] +[endsect] +[endsect] [/ end of section Library Overview] + +[section Reference] + +[section Geometries] +[section Concepts] +[endsect] [/ end of section Concepts] +[section Provided Geometries] [/TOOD better name? --mloskot] +[endsect] [/ end of section Provided Geometries] +[section Adaption and Registration] +[endsect] [/ end of section Adaption and Registration] +[endsect] [/ end of section Geometries] + +[section Coordinate Systems] +[endsect] [/ end of section Coordinate Systems] + +[section Algorithms] + +[section area] +[section Formal description] [/TOOD Theory as better name? --mloskot] +[endsect] +[section Parameters] +[endsect] +[section Complexity] +[endsect] +[section Example] +[endsect] +[section Notes] +[endsect] +[endsect] [/ end of section area] + +[section distance] +[section Formal description] [/TOOD Theory as better name? --mloskot] +[endsect] +[section Parameters] +[endsect] +[section Complexity] +[endsect] +[section Example] +[endsect] +[section Notes] +[endsect] +[endsect] [/ end of section disance] + +[endsect] [/ end of section Algorithms] + +[section Strategies and Policies] +[endsect] [/ end of Strategies and Policies] + +[section Iterators] +[endsect] [/ end of Iterators] + +[section Utilities] +[endsect] [/ end of Utilities] + +[endsect] [/ end of section Reference] + +[section Extensions] + +[section I/O] +[section DSV] +[endsect] [/ end of DSV] +[section SVG] +[endsect] [/ end of SVG] +[endsect] [/ end of I/O] + +[section Spatial Index] +[section R-tree] +[endsect] [/ end of R-tree] +[endsect] [/ end of Spatial Index] + +[section GIS] +[section I/O] +[endsect] [/ end of I/O] +[section Projections] +[endsect] [/ end of Projections] +[endsect] [/ end of GIS] + +[endsect] [/ end of section Extensions] + +[section Miscellaneous] + +[section Release Notes] [/TODO: current status] +[endsect] [/ end of ] + +[section Compilation] [/TOOD Was proposed as relations --mloskot] +[section Supported Compilers] +[endsect] [/ end of ] +[section Hints] +[endsect] [/ end of ] +[section Known Problems] [/TODO: Was proposed as issues --mloskot] +[endsect] [/ end of ] +[endsect] [/ end of Compilation] + +[section Relations] +[section Boost C++ Libraries] +[endsect] [/ end of Boost] +[section C++ Standard Library] +[endsect] [/ end of C++Std] +[section OGC] [/TODO: matrix on Wiki] +[endsect] [/ end of OGC] +[endsect] [/ end of Affiliations] + +[section Performance] +[endsect] [/ end of Performance] + +[section Who uses Boost.Geometry] +[endsect] [/ end of Who Uses] + +[section Future Work] [/TODO: Roadmap? --mloskot] +[endsect] [/ end of ] + +[section Acknowledgments] +[endsect] [/ end of Acknowledgments] + +[endsect] [/ end of Miscellaneous] diff --git a/doc/quickbook/tutorial.qbk b/doc/quickbook/tutorial.qbk new file mode 100644 index 000000000..11a4156b3 --- /dev/null +++ b/doc/quickbook/tutorial.qbk @@ -0,0 +1,25 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section Tutorial] +['TODO: tutorial-like materials here...] + +[include quickstart.qbk] + +[section Examples] + +[/TODO include example1.qbk] +[/TODO include example2.qbk] +[/TODO include ...] + +[endsect] + +['TODO: end of tutorial-like materials here...] +[endsect] [/ end of section Tutorial] \ No newline at end of file diff --git a/doc/quickbook/utilities.qbk b/doc/quickbook/utilities.qbk new file mode 100644 index 000000000..dce9a3ae4 --- /dev/null +++ b/doc/quickbook/utilities.qbk @@ -0,0 +1,15 @@ +[/============================================================================== + Copyright (c) 1995-2010 Barend Gehrels, Geodan, Amsterdam, the Netherlands. + Copyright (c) 2008-2010 Bruno Lalande, Paris, France. + Copyright (c) 2009-2010 Mateusz Loskot (mateusz@loskot.net), London, UK + + 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) +===============================================================================/] + +[section Utilities (?)] +['TODO: long story about utilities...] + +['TODO: end of long story about utilities...] +[endsect] [/ end of section Coordinate Systems] diff --git a/doc/roadmap.doc b/doc/roadmap.doc new file mode 100644 index 000000000..ad059bbdc Binary files /dev/null and b/doc/roadmap.doc differ diff --git a/doc/status.txt b/doc/status.txt new file mode 100644 index 000000000..61963bcfc --- /dev/null +++ b/doc/status.txt @@ -0,0 +1,65 @@ +TODO FOR PREVIEW4 + +* documentation + +* JAM's + -update + + + +---------------------------- + + + +* from_wkt + - harmonize with parse? MAYBE NEXT VERSION, NOT NOW +* parse: + - make default parser calling atod / lexical_cast for convenience/consistency with dms parser MAYBE NEXT VERSION, NOT NOW + + +* projections: + - param check without char LATER + - there are warnings on "this->" in MSVC LATER + - add "ellipse" structs -> can be shared by projections and by geographic distances LATER + - map for init LATER + + + +maybe + +* cartesian_tag etc -> cs::cartesian_tag or tag::cartesian_tag (?) +* OGC + - start_point + - end_point + +* assign/append + - add latitude<>/long<> / dms<> ? they were in point_ll. Now in "util/graticule.hpp" + -> PROBABLY DO THIS BY MAKING A FUNCTION AND ADDING dms_result -> more generic + - what about box? You might wish a method assigning a corner to a box, not yet there. LATER + + + +* make traits access consistent (DIM,TYPE) with index_access and radius_access + the call are now, for access/index_access/radius_access + return traits::access

            ::template get(p); + return traits::indexed_access::get(b); + return traits::radius_access::get(s); + the first is different and might be changed to: + return traits::access::get(p); + + Has no influence on the rest of the library, only the traits class(es) + + +* exceptions more consistent / separate headers?, derive from boost? + +* bounding box trait? + + +* convex_hull: + - multi*, LATER + + +EXAMPLES + +? X0x_GMP with GNU MP + diff --git a/doc/status.xls b/doc/status.xls new file mode 100644 index 000000000..e784ef88a Binary files /dev/null and b/doc/status.xls differ diff --git a/doc/testcases/get_turn_info.ppt b/doc/testcases/get_turn_info.ppt new file mode 100644 index 000000000..06b08b68c Binary files /dev/null and b/doc/testcases/get_turn_info.ppt differ diff --git a/doc/testcases/get_turn_info.xls b/doc/testcases/get_turn_info.xls new file mode 100644 index 000000000..facd118e4 Binary files /dev/null and b/doc/testcases/get_turn_info.xls differ diff --git a/doc/testcases/multi_overlay_cases.ppt b/doc/testcases/multi_overlay_cases.ppt new file mode 100644 index 000000000..909d0b9e2 Binary files /dev/null and b/doc/testcases/multi_overlay_cases.ppt differ diff --git a/doc/testcases/overlay_cases.ppt b/doc/testcases/overlay_cases.ppt new file mode 100644 index 000000000..1e7b7251c Binary files /dev/null and b/doc/testcases/overlay_cases.ppt differ diff --git a/doc/testcases/strategy_segment_intersection_obsolete.ppt b/doc/testcases/strategy_segment_intersection_obsolete.ppt new file mode 100644 index 000000000..76681a5e1 Binary files /dev/null and b/doc/testcases/strategy_segment_intersection_obsolete.ppt differ