diff --git a/doc/Jamfile b/doc/Jamfile index 69f0cb26f3..ace7111ba9 100644 --- a/doc/Jamfile +++ b/doc/Jamfile @@ -24,6 +24,7 @@ testing.make-test run-pyd : : $(here) src/docutils/tools/doxygen_xml2qbk//doxygen_xml2qbk + doxy/Doxyfile "--release-build --doxygen-xml2qbk" src/docutils/tools/doxygen_xml2qbk//doxygen_xml2qbk : diff --git a/doc/concept/point.qbk b/doc/concept/point.qbk index bade8fd35b..3a59653e85 100644 --- a/doc/concept/point.qbk +++ b/doc/concept/point.qbk @@ -68,7 +68,7 @@ struct access, Index> { * [link geometry.reference.adapted.boost_fusion Boost.Fusion] * [link geometry.reference.adapted.boost_polygon Boost.Polygon] * [link geometry.reference.adapted.boost_tuple Boost.Tuple] -* other point types, adapted e.g. using one of the [link geometry.reference.adapted registration macro's] +* other point types, adapted e.g. using one of the [link geometry.reference.adapted.register registration macro's] [endsect] diff --git a/doc/debug_clean_doc.sh b/doc/debug_clean_doc.sh new file mode 100755 index 0000000000..cb2b3fbf40 --- /dev/null +++ b/doc/debug_clean_doc.sh @@ -0,0 +1,22 @@ +# =========================================================================== +# Copyright (c) 2024-2024 Barend Gehrels, 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) +# ============================================================================ + +# Removes all generated output + +b2 clean + +rm -f index/generated/*.qbk +rm -f generated/*.qbk +rm -f generated/*.xml +rm -Rf html/geometry +rm -Rf doxy/doxygen_output/xml +rm -Rf doxy/doxygen_output/html_by_doxygen +rm -Rf index/xml +rm -Rf index/html_by_doxygen + +git ls-files --others diff --git a/doc/debug_make_doc.sh b/doc/debug_make_doc.sh new file mode 100755 index 0000000000..f5661bff95 --- /dev/null +++ b/doc/debug_make_doc.sh @@ -0,0 +1,153 @@ +# =========================================================================== +# Copyright (c) 2024-2024 Barend Gehrels, 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) +# ============================================================================ + +# Makes the documentation without calling b2, to be able to do it in steps +# and debug the individual steps. +# +# The following software must be in your path: +# - doxygen +# - xsltproc +# - python3 +# - doxygen_xml2qbk (provided by Boost.Geometry) +# - quickbook (should be made, it is referred to in a relative path) +# +# Execute the script from .../boost/libs/geometry/doc + +echo "=== Generating documentation for Boost.Geometry" + +base=`pwd` +boost_root=`realpath ${base}/../../..` + +# Set the DocBook (and dtd and boost dtd, less relevant) versions. + +# 1.75.2 is the one setup within Boost for ages. +# It reports as debug message: "Computing chunks..." +# But it currently gives the error message +# "The called template 'id.attribute' was not found." +# For all libraries (not only Boost.Geometry) + +# 1.79.1 works and gives correct documentation +# It does not output any extra debug message + +# 1.79.2 (with namespaces, on mac) gives empty content for sub-toc pages for Boost.Geometry +# It reports as debug message: "Note: namesp. add : added namespace before processing Geometry" +# 1.79.2 ("nons", no namespace) works and gives correct documentation +# It can be downloaded from https://www.linuxfromscratch.org/blfs/view/stable/pst/docbook-xsl.html + +# Set the values with 4.2 / 1.75.2 - used by setup_boostbook.sh +docbook_dtd_version=4.2 +docbook_xsl_version=1.75.2 +docbook_dtd=${boost_root}/tools/boostbook/docbook-dtd-${docbook_dtd_version} +docbook_xsl=${boost_root}/tools/boostbook/docbook-xsl-${docbook_xsl_version} + +# OVERRIDE the values with 4.5 / 1.79.1 - used by boostorg/release-tools/blob/develop/build_docs +docbook_dtd_version=4.5 +docbook_xsl_version=1.79.1 +docbook_dtd=~/data/docbook/docbook-dtd-${docbook_dtd_version} +docbook_xsl=~/data/docbook/docbook-xsl-${docbook_xsl_version} + +# UNCOMMENT the values with 4.5 / 1.79.2 - for future usage, note the "nons", which is essential +# docbook_xsl_version=1.79.2 +# docbook_xsl=~/data/docbook/docbook-xsl-nons-${docbook_xsl_version} + +# Set other values of dtd, css, style sheets +boostbook_dtd=${boost_root}/tools/boostbook/dtd + +file_css=${boost_root}/doc/src/boostbook.css + +xsl_docbook=${boost_root}/tools/boostbook/xsl/docbook.xsl +xsl_html=${boost_root}/tools/boostbook/xsl/html.xsl + +# Set the folder where to generate boostbook/docbook and some filenames +folder_generated=generated +file_boostbook=${folder_generated}/geometry.boostbook.xml +file_docbook=${folder_generated}/geometry.docbook.xml + +# === step 1 === + +echo "=== Running Doxygen" +cd doxy +doxygen Doxyfile +cd .. + +# === step 2 === +# Note that doxygen_xml2qbk should be in your path! + +echo "=== From Doxygen XML to QuickBook" +python3 make_qbk.py --skip_doxygen + +# === step 3 === + +echo "=== From QuickBook to BoostBook" +${boost_root}/dist/bin/quickbook -I"${boost_root}" -I"." -D"enable_index" \ + --output-file=${file_boostbook} geometry.qbk + +# === step 4 === + +# To avoid using b2 and user-config.jam, the catalog has to be written locally +filename_catalog=${folder_generated}/catalog.xml +echo "=== Write ${filename_catalog} for xstlproc with ${docbook_xsl}" + +cat <${filename_catalog} + + + + + + + +EOF + +# It is necessary to publish its location in an environment variable +export XML_CATALOG_FILES=${filename_catalog} + +# Set parameters shared for Boostbook -> Docbook -> HTML +params="--xinclude" +params="${params} --stringparam boost.defaults Boost" + +# Set boost.root (here, it should be relative, and go one above boost root itself) +params="${params} --stringparam boost.root ../../../.." + +echo "=== From BoostBook to DocBook" +xsltproc ${params} --path ${folder_generated} -o ${file_docbook} ${xsl_docbook} ${file_boostbook} + +# === step 5 === + +# These parameters define behaviour for DocBook. +# See also https://www.sagehill.net/docbookxsl/TOCcontrol.html +# The parameters values should correspond with the values in Jamfile. + +# Their values are currently valid for docbook-xsl-1.75.2 (the version included in Boost). +# However, the sections.xsl file currently included boost do not work for 1.75.2 +# If this is encountered, remove the part "" + +# Their values are currently also valid for version 1.79.1 +# But for version 1.79.2 is used, the chunking is broken. + +chunk_section_depth=4 +chunk_first_sections=1 +toc_section_depth=3 +toc_max_depth=2 +generate_section_toc_level=4 + +params="${params} --stringparam chunk.section.depth ${chunk_section_depth}" +params="${params} --stringparam chunk.first.sections ${chunk_first_sections}" +params="${params} --stringparam toc.max.depth ${toc_max_depth}" +params="${params} --stringparam toc.section.depth ${toc_section_depth}" +params="${params} --stringparam generate.section.toc.level ${generate_section_toc_level}" + +echo "=== From DocBook to html" +xsltproc ${params} --path ${folder_generated} -o "html/" ${xsl_html} ${file_docbook} + +echo "=== Resulting html, generated with:" +cat html/index.html| grep -w -e generator + +echo "=== Resulting contents of generated 'adapted.html', there should be sections" +cat html/geometry/reference/adapted.html | grep section + diff --git a/doc/doxy/Doxyfile b/doc/doxy/Doxyfile index d3e40f4bf1..094b31aded 100644 --- a/doc/doxy/Doxyfile +++ b/doc/doxy/Doxyfile @@ -5,19 +5,19 @@ #--------------------------------------------------------------------------- DOXYFILE_ENCODING = UTF-8 PROJECT_NAME = "Boost.Geometry (aka GGL)" -PROJECT_NUMBER = +PROJECT_NUMBER = OUTPUT_DIRECTORY = ./doxygen_output CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES -ABBREVIATE_BRIEF = +ABBREVIATE_BRIEF = ALWAYS_DETAILED_SEC = YES INLINE_INHERITED_MEMB = NO FULL_PATH_NAMES = YES STRIP_FROM_PATH = c:/_svn/boost/trunk/boost/geometry \ c:/_svn/boost/trunk/libs/geometry/doc/doxygen_input/pages -STRIP_FROM_INC_PATH = +STRIP_FROM_INC_PATH = SHORT_NAMES = NO JAVADOC_AUTOBRIEF = NO QT_AUTOBRIEF = NO @@ -26,7 +26,7 @@ INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 8 -# The aliases are shortcuts for Doxygen documentation. +# The aliases are shortcuts for Doxygen documentation. # Within Boost.Geometry they are used in the top section, so for both # Doxygen documentation and QuickBook documentation. # They avoid repetations and make the documentation more structured. @@ -39,6 +39,8 @@ TAB_SIZE = 8 # \return* for various return cases ALIASES = qbk{1}="\xmlonly \1 \endxmlonly" \ qbk{2}="\xmlonly \2 \endxmlonly" \ + wkt="WKT" \ + well_known_text="Well-Known Text" \ brief_calc{1}="Calculates the \1 of a geometry" \ brief_calc2{1}="Calculate the \1 of two geometries" \ brief_calc2{2}="Calculate the \1 \2 two geometries" \ @@ -101,9 +103,10 @@ ALIASES = qbk{1}="\xmlonly \1 \endxmlonly" \ details_calc2{1}="The free function \1 calculates the \1 of two geometries" \ details_check12{2}="The free function \1 checks if the first geometry \2 the second geometry" \ details_macro{2}="The macro \1 registers a \2 such that it is recognized by Boost.Geometry and that Boost.Geometry functionality can used with the specified type." \ - details_macro_const="The const version registers only read access to the fields, the point type is therefore read-only" \ - details_macro_getset="The get/set version registers get and set methods separately and can be used for classes with protected member variables and get/set methods to change coordinates" \ + details_macro_const="The const version registers only read access to the fields, the point type is therefore read-only." \ + details_macro_getset="The get/set version registers get and set methods separately and can be used for classes with protected member variables and get/set methods to change coordinates." \ details_macro_templated{2}="The type must have one template parameter, which should be a \2 type, and should not be specified. Boost.Geometry takes care of inserting the template parameter. Hence all types of this templated \1 are registered, regardless of their point type." \ + details_macro_lola="For geographic coordinate systems, be sure to specify first longitude and then latitude, to be able to use the strategies included in the library." \ details_default_strategy="It uses the default strategy, based on the coordinate system of the geometry." \ details_strategy_reasons="Reasons to specify a strategy include: use another coordinate system for calculations; construct the strategy beforehand (e.g. with the radius of the Earth); select a strategy when there are more than one available for a calculation." \ details_return{1}="This version with the return_ prefix returns the \1, and a template parameter must therefore be specified in the call." \ @@ -124,6 +127,8 @@ ALIASES = qbk{1}="\xmlonly \1 \endxmlonly" \ macro_x="first (usually x)" \ macro_y="second (usually y)" \ macro_z="third (usually z)" \ + macro_x_lon="first (usually x, or longitude)" \ + macro_y_lat="second (usually y, or latitude)" \ p_l_or_c="Point, LineString or Polygon" OPTIMIZE_OUTPUT_FOR_C = NO OPTIMIZE_OUTPUT_JAVA = NO @@ -161,10 +166,10 @@ GENERATE_TODOLIST = NO GENERATE_TESTLIST = YES GENERATE_BUGLIST = YES GENERATE_DEPRECATEDLIST= YES -ENABLED_SECTIONS = +ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = NO -FILE_VERSION_FILTER = +FILE_VERSION_FILTER = #--------------------------------------------------------------------------- # configuration options related to warning and progress messages #--------------------------------------------------------------------------- @@ -174,7 +179,7 @@ WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = NO WARN_FORMAT = "$file:$line: $text" -WARN_LOGFILE = +WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- @@ -227,7 +232,6 @@ INPUT = . .. ../../../../boost/geometry/core \ ../../../../boost/geometry/strategy/spherical \ ../../../../boost/geometry/util \ ../../../../boost/geometry/views \ - ./doxygen_input/pages \ ./doxygen_input/groups INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.hpp @@ -239,19 +243,19 @@ EXCLUDE = ../../../../boost/geometry/util/builder.hpp \ ../../../../boost/geometry/util/distance_sort.hpp \ ./doxygen_extension_examples.hpp EXCLUDE_SYMLINKS = NO -EXCLUDE_PATTERNS = -EXCLUDE_SYMBOLS = +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = EXAMPLE_PATH = . .. ../../example ../../example/with_external_libs \ doxygen_input/sourcecode \ ../../../../boost/geometry/geometries \ ../../../../boost/geometry/strategies \ ../../../../boost/geometry/strategies/cartesian \ ../../../../boost/geometry/algorithms -EXAMPLE_PATTERNS = +EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO IMAGE_PATH = doxygen_input/images -INPUT_FILTER = -FILTER_PATTERNS = +INPUT_FILTER = +FILTER_PATTERNS = FILTER_SOURCE_FILES = NO #--------------------------------------------------------------------------- # configuration options related to source browsing @@ -268,23 +272,25 @@ VERBATIM_HEADERS = NO # configuration options related to the alphabetical class index #--------------------------------------------------------------------------- COLS_IN_ALPHA_INDEX = 3 -IGNORE_PREFIX = +IGNORE_PREFIX = #--------------------------------------------------------------------------- # configuration options related to the HTML output +# This is only for debug purposes. For the final documentation, XML output is +# converted to QuickBook and then to BoostBook and DocBook and html #--------------------------------------------------------------------------- GENERATE_HTML = YES HTML_OUTPUT = html_by_doxygen HTML_FILE_EXTENSION = .html HTML_HEADER = doxygen_input/ggl_doxygen_header.html HTML_FOOTER = doxygen_input/ggl_doxygen_footer.html -HTML_STYLESHEET = +HTML_STYLESHEET = 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 = +CHM_FILE = +HHC_LOCATION = GENERATE_CHI = NO BINARY_TOC = NO TOC_EXPAND = NO @@ -311,14 +317,14 @@ GENERATE_PERLMOD = NO #--------------------------------------------------------------------------- -# Configuration options related to the preprocessor +# Configuration options related to the preprocessor #--------------------------------------------------------------------------- ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES SEARCH_INCLUDES = YES -INCLUDE_PATH = -INCLUDE_FILE_PATTERNS = +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = PREDEFINED = BOOST_CONCEPT_REQUIRES(x) \ BOOST_CONCEPT_ASSERT(x) \ BOOST_STATIC_ASSERT(x) \ @@ -331,12 +337,12 @@ PREDEFINED = BOOST_CONCEPT_REQUIRES(x) \ DOXYGEN_NO_STRATEGY_SPECIALIZATIONS \ DOXYGEN_NO_SPECIALIZATIONS \ DOXYGEN_INVOKED -EXPAND_AS_DEFINED = +EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- -# Configuration::additions related to the search engine +# Configuration::additions related to the search engine #--------------------------------------------------------------------------- SEARCHENGINE = NO diff --git a/doc/doxy/doxygen_enhance.py b/doc/doxy/doxygen_enhance.py deleted file mode 100755 index af892be98a..0000000000 --- a/doc/doxy/doxygen_enhance.py +++ /dev/null @@ -1,33 +0,0 @@ -#! /usr/bin/env python -# -*- coding: utf-8 -*- -# =========================================================================== -# Copyright (c) 2010 Barend Gehrels, 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)9 -# ============================================================================ - -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/doxy/doxygen_input/pages/doxygen_b_sets.hpp b/doc/doxy/doxygen_input/pages/doxygen_b_sets.hpp deleted file mode 100644 index 1e353a69d0..0000000000 --- a/doc/doxy/doxygen_input/pages/doxygen_b_sets.hpp +++ /dev/null @@ -1,214 +0,0 @@ -// Boost.Geometry (aka GGL, Generic Geometry Library) -// -// Copyright (c) 2007-2012 Barend Gehrels, 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/doxy/doxygen_input/pages/doxygen_c_strategy_rationale.hpp b/doc/doxy/doxygen_input/pages/doxygen_c_strategy_rationale.hpp deleted file mode 100644 index 4fafd31682..0000000000 --- a/doc/doxy/doxygen_input/pages/doxygen_c_strategy_rationale.hpp +++ /dev/null @@ -1,79 +0,0 @@ -// Boost.Geometry (aka GGL, Generic Geometry Library) -// -// Copyright (c) 2007-2012 Barend Gehrels, Amsterdam, the Netherlands. -// Copyright (c) 2008-2012 Bruno Lalande, Paris, France. -// 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/doxy/doxygen_input/pages/doxygen_d_robustness.hpp b/doc/doxy/doxygen_input/pages/doxygen_d_robustness.hpp deleted file mode 100644 index 45d38ae39e..0000000000 --- a/doc/doxy/doxygen_input/pages/doxygen_d_robustness.hpp +++ /dev/null @@ -1,137 +0,0 @@ -// Boost.Geometry (aka Boost.Geometry, Generic Geometry Library) -// -// Copyright (c) 2007-2012 Barend Gehrels, 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. For example from Boost.Multiprecision. - -\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 - { - using point_type = bg::model::point ; - boost::geometry::model::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()); - - using mp = boost::multiprecision::cpp_bin_float_100; - - auto area = boost::geometry::area(ring, boost::geometry::strategies::area::cartesian()); - std::cout << area << std::endl; - } -\endcode - -Above shows how this is used to use Boost.Multiprecision with 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/doxy/doxygen_input/pages/doxygen_examples.hpp b/doc/doxy/doxygen_input/pages/doxygen_examples.hpp deleted file mode 100644 index d7349b197f..0000000000 --- a/doc/doxy/doxygen_input/pages/doxygen_examples.hpp +++ /dev/null @@ -1,235 +0,0 @@ -// Boost.Geometry (aka GGL, Generic Geometry Library) -// -// Copyright (c) 2007-2012 Barend Gehrels, Amsterdam, the Netherlands. -// Copyright (c) 2008-2012 Bruno Lalande, Paris, France. -// 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_a_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 06_b_transformation_example.cpp - -*/ - -//--------------------------------------------------------------------------------------------------- - -/*! -\example 07_a_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 07_b_graph_route_example.cpp - - -*/ - - -//--------------------------------------------------------------------------------------------------- - /*! -\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 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/doxy/doxygen_input/pages/doxygen_mainpage.hpp b/doc/doxy/doxygen_input/pages/doxygen_mainpage.hpp deleted file mode 100644 index e144964000..0000000000 --- a/doc/doxy/doxygen_input/pages/doxygen_mainpage.hpp +++ /dev/null @@ -1,105 +0,0 @@ -// Boost.Geometry (aka GGL, Generic Geometry Library) -// -// Copyright (c) 2007-2012 Barend Gehrels, Amsterdam, the Netherlands. -// Copyright (c) 2008-2012 Bruno Lalande, Paris, France. -// 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 - - -// -> introduction.qbk -// -> quickstart.qbk - -/*! -\mainpage Boost.Geometry - -\section header Boost.Geometry (aka GGL, Generic Geometry Library) - - -Copyright © 1995-2012 Barend Gehrels, Geodan, Amsterdam, the Netherlands.\n -Copyright © 2008-2012 Bruno Lalande, Paris, France.\n -Copyright © 2010-2012 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 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/doxy/doxygen_input/pages/doxygen_pages.hpp b/doc/doxy/doxygen_input/pages/doxygen_pages.hpp deleted file mode 100644 index 7369d3eb63..0000000000 --- a/doc/doxy/doxygen_input/pages/doxygen_pages.hpp +++ /dev/null @@ -1,433 +0,0 @@ -// Boost.Geometry (aka GGL, Generic Geometry Library) -// -// Copyright (c) 2007-2012 Barend Gehrels, Amsterdam, the Netherlands. -// Copyright (c) 2008-2012 Bruno Lalande, Paris, France. -// 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 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. - -\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 - - - - -\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. - -*/ - -// BSG 24-12-2010: re-added to silence Doxygen warnings: -/*! -\page WKT WKT (Well-Known Text) -WKT is a textual representation of a geometry, explained here: http://en.wikipedia.org/wiki/Well-known_text -WKT 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::model::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::model::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::model::ring "linear_ring": Sequence of point values with linear interpolation -between points, which is closed and not self-intersecting -- \ref boost::geometry::model::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::model::multi_point "multi_point": collection of points -- \ref boost::geometry::model::multi_linestring "multi_linestring": collection of linestrings -- \ref boost::geometry::model::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::model::box "box": Box, used for selections and for envelopes (bounding boxes) -- \ref boost::geometry::model::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 expand. -- 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/doxy/doxygen_input/pages/doxygen_z_article09.hpp b/doc/doxy/doxygen_input/pages/doxygen_z_article09.hpp deleted file mode 100644 index ba39248328..0000000000 --- a/doc/doxy/doxygen_input/pages/doxygen_z_article09.hpp +++ /dev/null @@ -1,238 +0,0 @@ -// Boost.Geometry (aka GGL, Generic Geometry Library) -// -// Copyright (c) 2007-2012 Barend Gehrels, Amsterdam, the Netherlands. -// Copyright (c) 2008-2012 Bruno Lalande, Paris, France. -// 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/doxy/make_documentation.bat b/doc/doxy/make_documentation.bat deleted file mode 100644 index bdb6d8feb1..0000000000 --- a/doc/doxy/make_documentation.bat +++ /dev/null @@ -1,17 +0,0 @@ -:: =========================================================================== -:: Copyright (c) 2010 Barend Gehrels, 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)9 -:: ============================================================================ - -@echo off - -doxygen - -cd doxygen_output\html - -for %%f in (*.html) do ..\..\doxygen_enhance.py %%f - -cd ..\.. diff --git a/doc/geometry.qbk b/doc/geometry.qbk index 4976464372..a48aa66226 100644 --- a/doc/geometry.qbk +++ b/doc/geometry.qbk @@ -14,7 +14,7 @@ [library Geometry [quickbook 1.5] [authors [Gehrels, Barend], [Lalande, Bruno], [Loskot, Mateusz], [Wulkiewicz, Adam], [Karavelas, Menelaos], [Fisikopoulos, Vissarion]] - [copyright 2009-2021 Barend Gehrels, Bruno Lalande, Mateusz Loskot, Adam Wulkiewicz, Oracle and/or its affiliates] + [copyright 2009-2024 Barend Gehrels, Bruno Lalande, Mateusz Loskot, Adam Wulkiewicz, Oracle and/or its affiliates] [purpose Documentation of Boost.Geometry library] [license Distributed under the Boost Software License, Version 1.0. diff --git a/doc/html/index.html b/doc/html/index.html index 646695a202..d1e399c5a3 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -3,9 +3,10 @@ Chapter 1. Geometry - + + @@ -40,8 +41,8 @@

            Vissarion Fisikopoulos

            -

            Copyright © 2009-2022 Barend Gehrels, - Bruno Lalande, Mateusz Loskot, Adam Wulkiewicz, Oracle and/or its affiliates

            +

            Copyright © 2009-2024 Barend Gehrels, Bruno Lalande, Mateusz Loskot, Adam + Wulkiewicz, Oracle and/or its affiliates

            Distributed under the Boost Software License, Version 1.0. (See accompanying @@ -51,7 +52,7 @@

            Table of Contents

            -
            +
            Introduction
            Compilation
            Design Rationale
            @@ -102,12 +103,12 @@

            - Contributions + Contributions

            Boost.Geometry contains contributions by:

            -
              +
              • Akira Takahashi (adaption of Boost.Fusion)
                • @@ -148,10 +149,7 @@

            -
            - - -

            Last revised: December 01, 2022 at 10:37:09 GMT

            +
            Next
            diff --git a/doc/index/Doxyfile b/doc/index/Doxyfile index 0113fe0735..1e7f43c073 100644 --- a/doc/index/Doxyfile +++ b/doc/index/Doxyfile @@ -173,6 +173,8 @@ COLS_IN_ALPHA_INDEX = 5 IGNORE_PREFIX = #--------------------------------------------------------------------------- # configuration options related to the HTML output +# This is only for debug purposes. For the final documentation, XML output is +# converted to QuickBook and then to BoostBook and DocBook and html #--------------------------------------------------------------------------- GENERATE_HTML = YES HTML_OUTPUT = html_by_doxygen diff --git a/doc/index/make_qbk.py b/doc/index/make_qbk.py index cb99c495df..1dc73c455c 100755 --- a/doc/index/make_qbk.py +++ b/doc/index/make_qbk.py @@ -10,7 +10,7 @@ # # 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)9 +# http://www.boost.org/LICENSE_1_0.txt) # ============================================================================ import os, sys, shutil diff --git a/doc/introduction.qbk b/doc/introduction.qbk index 1762a169d8..b8399201c2 100644 --- a/doc/introduction.qbk +++ b/doc/introduction.qbk @@ -59,8 +59,7 @@ __boost_geometry__ was accepted by Boost at November 28, 2009 ([@http://permalink.gmane.org/gmane.comp.lib.boost.announce/246 review report]). There is a __boost_geometry__ [@http://lists.boost.org/mailman/listinfo.cgi/geometry -mailing list]. The mailing list and its messages are also accessible from -[@http://boost-geometry.203548.n3.nabble.com/ Nabble] as Boost Geometry. Also on +mailing list]. Also on the [@http://lists.boost.org/mailman/listinfo.cgi/boost Boost Developers list] and on the [@http://lists.boost.org/mailman/listinfo.cgi/boost-users Boost Users list] __boost_geometry__ is discussed. diff --git a/doc/make_qbk.py b/doc/make_qbk.py index 610bcee423..780773a9a8 100755 --- a/doc/make_qbk.py +++ b/doc/make_qbk.py @@ -44,7 +44,12 @@ cmd = cmd + " --output_member_variables false" cmd = cmd + " > generated/%s.qbk" +def print_verbose(s): + if "--verbose" in sys.argv: + print("`make_qbk.py` -- " + s) + def run_command(command): + print_verbose("Running %s" % command) if os.system(command) != 0: raise Exception("Error running %s" % command) @@ -55,6 +60,7 @@ def remove_all_files(dir_relpath): shutil.rmtree(dir_abspath, ignore_errors=True) def call_doxygen(): + print_verbose("Calling doxygen...") os.chdir("doxy") remove_all_files("doxygen_output/xml/") run_command(doxygen_cmd) @@ -86,14 +92,13 @@ def strategy_to_quickbook(section): ns = section[:p] strategy = section[p+2:] run_command(cmd % ("classboost_1_1geometry_1_1strategy_1_1" - + ns.replace("_", "__") + "_1_1" + strategy.replace("_", "__"), + + ns.replace("_", "__") + "_1_1" + strategy.replace("_", "__"), ns + "_" + strategy)) - + def cs_to_quickbook(section): run_command(cmd % ("structboost_1_1geometry_1_1cs_1_1" + section.replace("_", "__"), section)) - -call_doxygen() +# MAIN PROGRAM algorithms = ["append", "assign", "make", "clear" , "area", "azimuth", "buffer", "centroid", "closest_points", "convert" @@ -110,7 +115,7 @@ def cs_to_quickbook(section): access_functions = ["get", "set", "exterior_ring", "interior_rings" , "num_points", "num_interior_rings", "num_geometries"] - + coordinate_systems = ["cartesian", "geographic", "polar", "spherical", "spherical_equatorial"] core = ["closure", "coordinate_system", "coordinate_type", "cs_tag" @@ -153,18 +158,20 @@ def cs_to_quickbook(section): , "transform::translate_transformer", "transform::matrix_transformer" , "within::winding", "within::franklin", "within::crossings_multiply" ] - + views = ["box_view", "segment_view" , "closeable_view", "reversible_view", "identity_view"] +if "--skip_doxygen" not in sys.argv: + call_doxygen() for i in algorithms: group_to_quickbook(i) - + for i in access_functions: group_to_quickbook(i) - + for i in coordinate_systems: cs_to_quickbook(i) @@ -179,7 +186,7 @@ def cs_to_quickbook(section): for i in models: model_to_quickbook(i) - + for i in srs: srs_class_to_quickbook(i) @@ -188,7 +195,6 @@ def cs_to_quickbook(section): for i in views: struct_to_quickbook(i) - model_to_quickbook2("d2_1_1point__xy", "point_xy") model_to_quickbook2("d3_1_1point__xyz", "point_xyz") @@ -205,9 +211,10 @@ def cs_to_quickbook(section): class_to_quickbook2("de9im_1_1mask", "de9im_mask") class_to_quickbook2("de9im_1_1static__mask", "de9im_static_mask") -os.chdir("index") -exec(compile(open("make_qbk.py", "rb").read(), "make_qbk.py", 'exec')) -os.chdir("..") +if "--skip_index" not in sys.argv: + os.chdir("index") + exec(compile(open("make_qbk.py", "rb").read(), "make_qbk.py", 'exec')) + os.chdir("..") # Clean up generated intermediate files if "--release-build" in sys.argv: @@ -217,5 +224,5 @@ def cs_to_quickbook(section): remove_all_files("index/html_by_doxygen/") # Use either bjam or b2 or ../../../b2 (the last should be done on Release branch) -if "--release-build" not in sys.argv: +if "--release-build" not in sys.argv and "--skip_doxygen" not in sys.argv: run_command("b2") diff --git a/doc/quickref.xml b/doc/quickref.xml index f17cef9153..5fe37f0525 100644 --- a/doc/quickref.xml +++ b/doc/quickref.xml @@ -437,7 +437,7 @@ length - line_interpolate + Line Interpolate line_interpolate @@ -599,7 +599,7 @@ - Line interpolate point + Line Interpolate strategy::line_interpolate::cartesian strategy::line_interpolate::geographic @@ -723,7 +723,7 @@ read_wkt wkt - to_wkt + to_wkt from_wkt @@ -862,7 +862,7 @@ overlaps(Geometry const &) within(Geometry const &) satisfies(UnaryPredicate const &) - nearest(Geometry const &, unsigned) + nearest(Geometry const &, unsigned)