Boost.Geometry doc updates

[SVN r76963]

doc/concept/multi_polygon.qbk

@@ -23,6 +23,19 @@ The MultiPolygon Concept is defined as following:
 * It must behave like a Boost.Range Random Access Range
 * The type defined by the metafunction `range_value<...>::type` must fulfill 
 	the [link geometry.reference.concepts.concept_polygon Polygon Concept]
+    
+[heading Rules]
+
+Besides the Concepts, which are checks on compile-time, there are  
+rules that valid MultiPolygons must fulfill. See the
+[link geometry.reference.concepts.concept_polygon Polygon Concept] for more information
+on the rules a polygon (and also a multi polygon) must fulfill.
+
+Additionally:
+
+* Individual polygons making up a multi-polygon may not intersect each other,
+    but tangencies are allowed.
+* One polygon might be located within the interior ring of another polygon.
 
 [heading Available Models]	
 * [link geometry.reference.models.model_multi_polygon model::multi_polygon]

doc/concept/polygon.qbk

@@ -15,7 +15,7 @@
 [heading Description]
 [concept Polygon..polygon]
 
-A polygon is ['A polygon is a planar surface defined by one exterior boundary and zero or more interior boundaries.] 
+A polygon is ['A polygon is a planar surface defined by one exterior boundary and zero or more interior boundaries] 
 ([@http://portal.opengeospatial.org/files/?artifact_id=25355 opengeospatial]).
 
 So the definition of a Boost.Geometry polygon differs a bit from e.g. Wiki, where a polygon does not have holes. A
@@ -34,6 +34,36 @@ The Polygon Concept is defined as following:
 * there must be a specialization of `traits::exterior_ring` with two functions named `get`, returning the exterior ring, one being const, the other being non const
 * there must be a specialization of `traits::interior_rings` with two functions named `get`, returning the interior rings, one being const, the other being non const
 
+[heading Rules]
+
+Besides the Concepts, which are checks on compile-time, there are some other 
+rules that valid polygons must fulfill. This follows the opengeospatial rules (see link 
+above).
+
+* Polygons are simple geometric objects (See also [@http://en.wikipedia.org/wiki/Simple_polygon wiki]
+    but holes are allowed in __boost_geometry__ polygons).
+* If the polygons underlying `ring_type` is defined as clockwise, the exterior
+    ring must have the clockwise orientation, and any interior ring must be 
+    counter clockwise. If the `ring_type` is defined counter clockwise, it is 
+    vice versa.
+* If the polygons underlying `ring_type` is defined as closed, all rings must be
+    closed: the first point must be spatially equal to the last point.
+* The interior is a connected point set.
+* There should be no self intersections, but self tangencies (between 
+    exterior/interior rings) are allowed (as long as the interior is a connected
+    point set.
+* There should be no cut lines, spikes or punctures.
+* The interior rings should be located within the exterior ring. Interior rings
+    may not be located within each other.
+
+The algorithms such as intersection, area, centroid, union, etc. do not check 
+validity. There will be an algorithm is_valid which checks for 
+validity against these rules, at runtime, and which can be called (by the library
+user) before.
+
+If the input is invalid, the output might be invalid too. For example: if a polygon
+which should be closed is not closed, the area will be incorrect.
+
 [heading Available Models]	
 * [link geometry.reference.models.model_polygon polygon]
 * a Boost.Polygon polygon_with_holes_data (requires `#include boost/geometry/geometries/adapted/boost_polygon/polygon.hpp>`)

doc/concept/ring.qbk

@@ -28,6 +28,13 @@ The Ring Concept is defined as following:
 * there might be a specialization of `traits::point_order` defining the order or orientation of its points, `clockwise` or `counterclockwise`
 * there might be a specialization of `traits::closure` defining the closure, `open` or `closed`
 
+[heading Rules]
+
+Besides the Concepts, which are checks on compile-time, there are
+rules that valid rings must fulfill. See the
+[link geometry.reference.concepts.concept_polygon Polygon Concept] for more information
+on the rules a polygon (and also a ring) must fulfill.
+
 [heading Available Models]	
 * [link geometry.reference.models.model_ring ring]
 * a Boost.Polygon polygon_data (requires `#include boost/geometry/geometries/adapted/boost_polygon/ring.hpp>`)

doc/doxy/doxygen_input/groups/groups.hpp

@@ -23,6 +23,7 @@
 \defgroup convex_hull convex hull: calculate the convex hull of a geometry
 \defgroup core core: meta-functions for geometry types
 \defgroup correct correct: correct geometries
+\defgroup covered_by covered_by: detect if a geometry is inside or on the border of another geometry, a.o. point-in-polygon (border included)
 \defgroup cs coordinate systems
 \defgroup difference difference: difference of two geometries
 \defgroup disjoint disjoint: detect if geometries are not spatially related

doc/introduction.qbk

@@ -39,25 +39,32 @@ The library follows existing conventions:
 * conventions from the std library
 * conventions and names from one of the __ogc__ standards on geometry
 
-The library was released with Boost 1.47.0 and from that point on it is oficially part of the Boost C++ Libraries.
+The library was released with Boost 1.47.0 and from that point on it is 
+officially part of the Boost C++ Libraries.
 
-Latest stable version of the source code is included in the [@http://www.boost.org/users/download/ Boost packaged releases].
-It can also be downloaded from the current [@http://svn.boost.org/svn/boost/branches/release Boost release branch]
+Latest stable version of the source code is included in the 
+[@http://www.boost.org/users/download/ Boost packaged releases].
+It can also be downloaded from the current 
+[@http://svn.boost.org/svn/boost/branches/release Boost release branch]
 in the Boost Subversion repository.
 
-The library development upstream is available from the [@http://svn.boost.org/svn/boost/trunk Boost trunk] in the Boost Subversion repository.
+The library development upstream is available from the 
+[@http://svn.boost.org/svn/boost/trunk Boost trunk] in the Boost Subversion 
+repository.
 
-Note that the library [*extensions] are not distributed in the official Boost releases, but  only available
-in the [@http://svn.boost.org/svn/boost/trunk/boost/geometry/extensions/ Boost trunk] 
+Note that the library [*extensions] are not distributed in the official Boost 
+releases, but  only available
+in the [@http://svn.boost.org/svn/boost/trunk/boost/geometry/extensions/ Boost 
+trunk] 
 and that they are subject to change.
 
 __boost_geometry__ was accepted by Boost at November 28, 2009
 ([@http://permalink.gmane.org/gmane.comp.lib.boost.announce/246 review report]).
 
-There are two mailing lists
-where __boost_geometry__ is discussed: the boost developers list, and also the 
-[@http://lists.osgeo.org/mailman/listinfo/ggl GGL mailing list] at osgeo, at which, at the moment of writing, more than 70 people
-are subscribed. The mailing list is also accessible from  
-[@http://boost-geometry.203548.n3.nabble.com/ Nabble] as Boost Geometry.
+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. On 
+the Boost Developers list and on the Boost Users list are also sometimes 
+messages about __boost_geometry__.
 
 [endsect]

doc/make_qbk.py

@@ -68,7 +68,7 @@ def cs_to_quickbook(section):
 call_doxygen()
 
 algorithms = ["append", "assign", "make", "clear"
-    , "area", "buffer", "centroid", "convert", "correct"
+    , "area", "buffer", "centroid", "convert", "correct", "covered_by"
     , "convex_hull", "difference", "disjoint", "distance" 
     , "envelope", "equals", "expand", "for_each", "intersection", "intersects" 
     , "length", "num_geometries", "num_interior_rings", "num_points" 

doc/quickref.xml

@@ -319,6 +319,7 @@
     </simplelist>
     <bridgehead renderas="sect3">Predicates</bridgehead>
     <simplelist type="vert" columns="1">
+     <member><link linkend="geometry.reference.algorithms.covered_by">covered_by</link></member>
      <member><link linkend="geometry.reference.algorithms.disjoint">disjoint</link></member>
      <member><link linkend="geometry.reference.algorithms.equals">equals</link></member>
      <member><link linkend="geometry.reference.algorithms.intersects">intersects</link></member>

doc/readme.txt

@@ -30,3 +30,15 @@ reference: generated documentation QBK files (by doxygen_xml2qbk)
 	because it is used in the final URL and we want to have "reference" in it]
 src: examples used in documentation and tools (doxygen_xml2qbk)
 
+Per new algorithm (e.g. foo), one should add:
+1) in file boost/geometry/algorithms/foo.hpp, include a "\ingroup foo" in the doxygen comments
+2) in file doc/doxy/doxygen_input/groups/groups.hpp, define the group "foo"
+3) in file doc/make_qbk.py, include the algorithm "foo"
+4) in file doc/reference.qbk, include the foo.qbk ([include generated/foo.qbk])
+5) in file doc/quickref.xml, include a section on foo conform other sections
+6) in file doc/src/docutils/tools/support_status/support_status.cpp include the algorithm (3 places) (optionally)
+7) in file doc/reference/foo.qbk (to be created), include the support status and write other text, and include examples (optionally)
+8) in file doc/imports.qbk, include the example foo.cpp (if any)
+9) create file doc/src/examples/algorithm/foo.cpp (optional)
+
+

doc/reference.qbk

@@ -84,6 +84,10 @@
 [include generated/convex_hull.qbk]
 [include generated/correct.qbk]
 
+[section:covered_by covered_by]
+[include generated/covered_by.qbk]
+[endsect]
+
 [include generated/difference.qbk]
 [include generated/disjoint.qbk]
 

doc/reference/algorithms/convert.qbk

@@ -10,8 +10,8 @@
   http://www.boost.org/LICENSE_1_0.txt)
 =============================================================================/]
 
-[tip convert is not defined within OGC or ISO]
-[tip convert is modelled as source -> target 
+[note convert is not defined within OGC or ISO]
+[note convert is modelled as source -> target 
     (where assign is modelled as target := source)]
 
 [include generated/convert_status.qbk]

doc/reference/algorithms/covered_by.qbk

@@ -0,0 +1,32 @@
+[/============================================================================
+  Boost.Geometry (aka GGL, Generic Geometry Library)
+
+  Copyright (c) 2009-2012 Barend Gehrels, Amsterdam, the Netherlands.
+  Copyright (c) 2009-2012 Mateusz Loskot, London, UK.
+  Copyright (c) 2009-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)
+=============================================================================/]
+
+[include generated/covered_by_status.qbk]
+[note In this status matrix above: columns are types of first parameter
+  and rows are types of second parameter. So a point can be checked to be 
+  covered by a polygon, but not vice versa.
+]
+
+[note convert is not defined within OGC or ISO. However, both PostGIS
+  and Oracle contain an algorithm with the same name and the same functionality.
+  See the [@http://www.postgis.org/docs/ST_CoveredBy.html PostGIS documentation]. 
+]
+
+[heading Complexity]
+Linear
+
+[heading See also]
+* [link geometry.reference.algorithms.within within]
+
+[note The difference with the `within` algorithm is that this algorithm checks the
+  border by default
+]

doc/reference/algorithms/difference.qbk

@@ -8,7 +8,9 @@
   http://www.boost.org/LICENSE_1_0.txt)
 =============================================================================/]
 
-[include reference/algorithms/overlay_behavior.qbk]
+[include reference/algorithms/difference_behavior.qbk]
+
+[include reference/algorithms/geometry_rules.qbk]
 
 [heading Example]
 [difference] [difference_output]

doc/reference/algorithms/difference_behavior.qbk

@@ -12,6 +12,8 @@
 [table
 [[Case] [Behavior] ]
 [[__2dim__][All combinations of: box, ring, polygon, multi_polygon]]
+[[__1dim__ / __2dim__][A combinations of a (multi) linestring with a (multi) polygon
+    results in a collection of linestrings]]
 [[__other__][__nyiversion__]]
 [[__sph__][__nyiversion__]]
 [[Three dimensional][__nyiversion__]]

doc/reference/algorithms/difference_inserter.qbk

@@ -8,7 +8,9 @@
   http://www.boost.org/LICENSE_1_0.txt)
 =============================================================================/]
 
-[include reference/algorithms/overlay_behavior.qbk]
+[include reference/algorithms/difference_behavior.qbk]
+
+[include reference/algorithms/geometry_rules.qbk]
 
 [heading Example]
 [difference_inserter] [difference_inserter_output]

doc/reference/algorithms/geometry_rules.qbk

@@ -0,0 +1,12 @@
+[/============================================================================
+  Boost.Geometry (aka GGL, Generic Geometry Library)
+
+  Copyright (c) 2011-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)
+=============================================================================/]
+
+[note Check the [link geometry.reference.concepts.concept_polygon Polygon Concept]
+    for the rules that polygon input for this algorithm should fulfill]

doc/reference/algorithms/intersection.qbk

@@ -15,9 +15,11 @@
 [[Case] [Behavior] ]
 [[[qbk_out __point__]][Calculates intersection points of input geometries]]
 [[[qbk_out __linestring__]][Calculates intersection linestrings of input geometries (NYI)]]
-[[[qbk_out __polygon__]][Calculates intersection polygons input (multi)polygons and/or boxes]]
+[[[qbk_out __polygon__]][Calculates intersection polygons of input (multi)polygons and/or boxes]]
 ]
 
+[include reference/algorithms/geometry_rules.qbk]
+
 [heading Example]
 [intersection]
 [intersection_output]

doc/reference/algorithms/sym_difference.qbk

@@ -10,13 +10,9 @@
   http://www.boost.org/LICENSE_1_0.txt)
 =============================================================================/]
 
-[heading Behavior]
-[table
-[[Case] [Behavior] ]
-[[__2dim__][All combinations of: box, ring, polygon, multi_polygon]]
-[[__other__][Not supported]]
+[include reference/algorithms/difference_behavior.qbk]
 
-]
+[include reference/algorithms/geometry_rules.qbk]
 
 [heading Example]
 [sym_difference]

doc/reference/algorithms/union.qbk

@@ -13,8 +13,11 @@
 [heading Behavior]
 [table
 [[Case] [Behavior] ]
+[[[qbk_out __polygon__]][Calculates union polygons of input (multi)polygons and/or boxes]]
 ]
 
+[include reference/algorithms/geometry_rules.qbk]
+
 [heading Example]
 [union]
 [union_output]

doc/reference/algorithms/within.qbk

@@ -11,7 +11,10 @@
 =============================================================================/]
 
 [include generated/within_status.qbk]
-
+[note In this status matrix above: columns are types of first parameter
+  and rows are types of second parameter. So a point can be checked to be 
+  within a polygon, but not vice versa.]
+  
 [heading Notes]
 If a point is located exactly on the border of a geometry, the result depends on the strategy.
 The default strategy ([link geometry.reference.strategies.strategy_within_winding Winding (coordinate system agnostic)]) 
@@ -23,3 +26,5 @@ The default strategy returns still true if a point is completely within the reve
 [heading Complexity]
 Linear
 
+[heading See also]
+* [link geometry.reference.algorithms.covered_by covered_by]

include/boost/geometry/algorithms/covered_by.hpp

@@ -108,14 +108,14 @@ struct covered_by<Point, Polygon, point_tag, polygon_tag>
 \details \details_check12{covered_by, is inside or on border}.
 \tparam Geometry1 \tparam_geometry
 \tparam Geometry2 \tparam_geometry
-\param geometry1 \param_geometry
-\param geometry2 \param_geometry
-\param geometry1 geometry which might be covered_by the second geometry
-\param geometry2 geometry which might contain the first geometry
-\return true if geometry1 is completely contained covered_by geometry2,
+\param geometry1 \param_geometry which might be inside or on the border of the second geometry
+\param geometry2 \param_geometry which might cover the first geometry
+\return true if geometry1 is inside of or on the border of geometry2,
     else false
 \note The default strategy is used for covered_by detection
 
+\qbk{[include reference/algorithms/covered_by.qbk]}
+
  */
 template<typename Geometry1, typename Geometry2>
 inline bool covered_by(Geometry1 const& geometry1, Geometry2 const& geometry2)
@@ -158,15 +158,14 @@ inline bool covered_by(Geometry1 const& geometry1, Geometry2 const& geometry2)
 \details \details_check12{covered_by, is inside or on border}, \brief_strategy. \details_strategy_reasons
 \tparam Geometry1 \tparam_geometry
 \tparam Geometry2 \tparam_geometry
-\param geometry1 \param_geometry
-\param geometry2 \param_geometry
-\param geometry1 \param_geometry geometry which might be covered_by the second geometry
-\param geometry2 \param_geometry which might contain the first geometry
+\param geometry1 \param_geometry which might be inside or on the border of the second geometry
+\param geometry2 \param_geometry which might cover the first geometry
 \param strategy strategy to be used
 \return true if geometry1 is inside of or on the border of geometry2,
     else false
 
 \qbk{distinguish,with strategy}
+\qbk{[include reference/algorithms/covered_by.qbk]}
 
 */
 template<typename Geometry1, typename Geometry2, typename Strategy>

include/boost/geometry/algorithms/within.hpp

@@ -241,10 +241,8 @@ struct within<Point, Polygon, point_tag, polygon_tag>
 \details \details_check12{within, is completely inside}.
 \tparam Geometry1 \tparam_geometry
 \tparam Geometry2 \tparam_geometry
-\param geometry1 \param_geometry
-\param geometry2 \param_geometry
-\param geometry1 geometry which might be within the second geometry
-\param geometry2 geometry which might contain the first geometry
+\param geometry1 \param_geometry which might be within the second geometry
+\param geometry2 \param_geometry which might contain the first geometry
 \return true if geometry1 is completely contained within geometry2,
     else false
 \note The default strategy is used for within detection
@@ -299,9 +297,7 @@ inline bool within(Geometry1 const& geometry1, Geometry2 const& geometry2)
 \details \details_check12{within, is completely inside}, \brief_strategy. \details_strategy_reasons
 \tparam Geometry1 \tparam_geometry
 \tparam Geometry2 \tparam_geometry
-\param geometry1 \param_geometry
-\param geometry2 \param_geometry
-\param geometry1 \param_geometry geometry which might be within the second geometry
+\param geometry1 \param_geometry which might be within the second geometry
 \param geometry2 \param_geometry which might contain the first geometry
 \param strategy strategy to be used
 \return true if geometry1 is completely contained within geometry2,

test/algorithms/difference.cpp

@@ -74,9 +74,6 @@ void test_areal_linear()
     test_one_lp<LineString, LineString, Polygon>("case13", "LINESTRING(3 2,4 4,2 3)", poly_9, 0, 0, 0.0);
     test_one_lp<LineString, LineString, Polygon>("case14", "LINESTRING(5 6,4 4,6 5)", poly_9, 1, 3, 2.0 * sqrt(5.0));
 
-    //return;
-    // The rest compiles but is NOT yet correct
-
     test_one_lp<LineString, LineString, Polygon>("case15", "LINESTRING(0 2,1 2,1 3,0 3)", poly_9, 2, 4, 2.0);
     test_one_lp<LineString, LineString, Polygon>("case16", "LINESTRING(2 2,1 2,1 3,2 3)", poly_9, 0, 0, 0.0);
 

test/algorithms/test_difference.hpp

@@ -294,7 +294,8 @@ void test_one_lp(std::string const& caseid,
 
     BOOST_CHECK_CLOSE(length, expected_length, 0.001);
 
-    difference_output(caseid, g1, g2, pieces);
+    std::string lp = "lp_";
+    difference_output(lp + caseid, g1, g2, pieces);
 }