[Boost-commit] svn:boost r68574 - in trunk/boost/geometry: algorithms core strategies/agnostic strategies/cartesian strategies/spherical

Subject: [Boost-commit] svn:boost r68574 - in trunk/boost/geometry: algorithms core strategies/agnostic strategies/cartesian strategies/spherical
From: barend.gehrels_at_[hidden]
Date: 2011-01-30 16:48:25

Author: barendgehrels
Date: 2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
New Revision: 68574
URL: http://svn.boost.org/trac/boost/changeset/68574

Log:
Doc update
Renamed macro to throw/don't throw BOOST_GEOMETRY_CENTROID_NO_THROW

Text files modified: 
   trunk/boost/geometry/algorithms/area.hpp                                       |     1                                         
   trunk/boost/geometry/algorithms/centroid.hpp                                   |    85 +++++++++++++++++++++++++++------------ 
   trunk/boost/geometry/algorithms/within.hpp                                     |    17 +++++--                                 
   trunk/boost/geometry/core/closure.hpp                                          |    32 +++++++++++++-                          
   trunk/boost/geometry/core/exception.hpp                                        |    10 ++-                                     
   trunk/boost/geometry/core/point_order.hpp                                      |    56 +++++++++++++++++++-------              
   trunk/boost/geometry/strategies/agnostic/point_in_poly_winding.hpp             |     5 ++                                      
   trunk/boost/geometry/strategies/cartesian/area_surveyor.hpp                    |     2                                         
   trunk/boost/geometry/strategies/cartesian/centroid_bashein_detmer.hpp          |     6 ++                                      
   trunk/boost/geometry/strategies/cartesian/distance_projected_point.hpp         |     2                                         
   trunk/boost/geometry/strategies/cartesian/distance_pythagoras.hpp              |     2                                         
   trunk/boost/geometry/strategies/cartesian/point_in_poly_crossings_multiply.hpp |     4 +                                       
   trunk/boost/geometry/strategies/cartesian/point_in_poly_franklin.hpp           |     5 +                                       
   trunk/boost/geometry/strategies/spherical/area_huiller.hpp                     |     2                                         
   trunk/boost/geometry/strategies/spherical/distance_cross_track.hpp             |     2                                         
   trunk/boost/geometry/strategies/spherical/distance_haversine.hpp               |     2                                         
   16 files changed, 171 insertions(+), 62 deletions(-)

Modified: trunk/boost/geometry/algorithms/area.hpp
==============================================================================
--- trunk/boost/geometry/algorithms/area.hpp	(original)
+++ trunk/boost/geometry/algorithms/area.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -259,7 +259,6 @@
 [heading Available Strategies]
 \* [link geometry.reference.strategies.strategy_area_surveyor Surveyor (cartesian)]
 \* [link geometry.reference.strategies.strategy_area_huiller Huiller (spherical)]
-
 }
  */
 template <typename Geometry, typename Strategy>

Modified: trunk/boost/geometry/algorithms/centroid.hpp
==============================================================================
--- trunk/boost/geometry/algorithms/centroid.hpp	(original)
+++ trunk/boost/geometry/algorithms/centroid.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -38,6 +38,20 @@
 {
 
 
+#if ! defined(BOOST_GEOMETRY_CENTROID_NO_THROW)
+
+/*!
+\brief Centroid Exception
+\ingroup centroid
+\details The centroid_exception is thrown if the free centroid function is called with
+    geometries for which the centroid cannot be calculated. For example: a linestring
+    without points, a polygon without points, an empty multi-geometry.
+\qbk{
+[heading See also]
+\* [link geometry.reference.algorithms.centroid the centroid function]
+}
+
+ */
 class centroid_exception : public geometry::exception
 {
 public:
@@ -50,6 +64,8 @@
     }
 };
 
+#endif
+
 
 #ifndef DOXYGEN_NO_DETAIL
 namespace detail { namespace centroid
@@ -133,7 +149,7 @@
     }
     else if (n <= 0)
     {
-#if defined(CENTROID_WITH_CATCH)
+#if ! defined(BOOST_GEOMETRY_CENTROID_NO_THROW)
         throw centroid_exception();
 #endif
         return false;
@@ -203,33 +219,36 @@
     static inline void apply(Linestring const& line, Point& centroid,
             Strategy const& strategy)
     {
-        // First version, should
-        // - be moved to a strategy
-        // - be made dim-agnostic
-
-        typedef typename point_type<Linestring>::type point_type;
-        typedef typename boost::range_iterator<Linestring const>::type point_iterator_type;
-        typedef segment_returning_iterator<point_iterator_type, point_type> segment_iterator;
-
-        double length = double();
-        std::pair<double, double> average_sum;
-
-        segment_iterator it(boost::begin(line), boost::end(line));
-        segment_iterator end(boost::end(line));
-        while (it != end)
+        if (range_ok(line, centroid))
         {
-            double const d = geometry::distance(it->first, it->second);
-            length += d;
+            // First version, should
+            // - be moved to a strategy
+            // - be made dim-agnostic
+
+            typedef typename point_type<Linestring>::type point_type;
+            typedef typename boost::range_iterator<Linestring const>::type point_iterator_type;
+            typedef segment_returning_iterator<point_iterator_type, point_type> segment_iterator;
+
+            double length = double();
+            std::pair<double, double> average_sum;
+
+            segment_iterator it(boost::begin(line), boost::end(line));
+            segment_iterator end(boost::end(line));
+            while (it != end)
+            {
+                double const d = geometry::distance(it->first, it->second);
+                length += d;
+
+                double const mx = (get<0>(it->first) + get<0>(it->second)) / 2;
+                double const my = (get<1>(it->first) + get<1>(it->second)) / 2;
+                average_sum.first += d * mx;
+                average_sum.second += d * my;
+                ++it;
+            }
 
-            double const mx = (get<0>(it->first) + get<0>(it->second)) / 2;
-            double const my = (get<1>(it->first) + get<1>(it->second)) / 2;
-            average_sum.first += d * mx;
-            average_sum.second += d * my;
-            ++it;
+            set<0>(centroid, average_sum.first / length );
+            set<1>(centroid, average_sum.second / length );
         }
-
-        set<0>(centroid, average_sum.first / length );
-        set<1>(centroid, average_sum.second / length );
     }
 };
 
@@ -349,7 +368,7 @@
 /*!
 \brief \brief_calc{centroid} \brief_strategy
 \ingroup centroid
-\details \details_calc{centroid,geometric center (or: center of mass)}
+\details \details_calc{centroid,geometric center (or: center of mass)}. \details_strategy_reasons
 \tparam Geometry \tparam_geometry
 \tparam Point \tparam_point
 \tparam Strategy \tparam_strategy{Centroid}
@@ -359,6 +378,12 @@
 
 \qbk{distinguish,with strategy}
 \qbk{[include ref/algorithms/centroid.qbk]}
+
+\qbk{
+[heading Available Strategies]
+\* [link geometry.reference.strategies.strategy_centroid_bashein_detmer Bashein Detmer (cartesian)]
+}
+
 */
 template<typename Geometry, typename Point, typename Strategy>
 inline void centroid(Geometry const& geometry, Point& c,
@@ -434,7 +459,7 @@
 /*!
 \brief \brief_calc{centroid} \brief_strategy
 \ingroup centroid
-\details \details_calc{centroid,geometric center (or: center of mass)}. \details_make{centroid}.
+\details \details_calc{centroid,geometric center (or: center of mass)}. \details_make{centroid}. \details_strategy_reasons
 \tparam Point \tparam_point
 \tparam Geometry \tparam_geometry
 \tparam Strategy \tparam_strategy{centroid}
@@ -444,6 +469,12 @@
 
 \qbk{distinguish,with strategy}
 \qbk{[include ref/algorithms/centroid.qbk]}
+
+\qbk{
+[heading Available Strategies]
+\* [link geometry.reference.strategies.strategy_centroid_bashein_detmer Bashein Detmer (cartesian)]
+}
+
  */
 template<typename Point, typename Geometry, typename Strategy>
 inline Point make_centroid(Geometry const& geometry, Strategy const& strategy)

Modified: trunk/boost/geometry/algorithms/within.hpp
==============================================================================
--- trunk/boost/geometry/algorithms/within.hpp	(original)
+++ trunk/boost/geometry/algorithms/within.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -155,7 +155,7 @@
     static inline int apply(Point const& point, Ring const& ring,
             Strategy const& strategy)
     {
-        if (boost::size(ring) 
+        if (boost::size(ring)
                 < core_detail::closure::minimum_ring_size<Closure>::value)
         {
             return -1;
@@ -326,8 +326,9 @@
 
 
 /*!
-\brief \brief_check12{completely inside}
+\brief \brief_check12{is completely inside}
 \ingroup within
+\details \details_check12{within, is completely inside}.
 \tparam Geometry1 \tparam_geometry
 \tparam Geometry2 \tparam_geometry
 \param geometry1 \param_geometry
@@ -368,9 +369,9 @@
 }
 
 /*!
-\brief Within, examine if a geometry is within another geometry,
-    using a specified strategy
+\brief \brief_check12{is completely inside} \brief_strategy
 \ingroup within
+\details \details_check12{within, is completely inside}, \brief_strategy. \details_strategy_reasons
 \tparam Geometry1 \tparam_geometry
 \tparam Geometry2 \tparam_geometry
 \param geometry1 \param_geometry
@@ -382,7 +383,13 @@
     else false
 
 \qbk{distinguish,with strategy}
- */
+\qbk{
+[heading Available Strategies]
+\* [link geometry.reference.strategies.strategy_within_winding Winding (coordinate system agnostic)]
+\* [link geometry.reference.strategies.strategy_within_franklin Franklin (cartesian)]
+\* [link geometry.reference.strategies.strategy_within_crossings_multiply Crossings Multiply (cartesian)]
+}
+*/
 template<typename Geometry1, typename Geometry2, typename Strategy>
 inline bool within(Geometry1 const& geometry1, Geometry2 const& geometry2,
         Strategy const& strategy)

Modified: trunk/boost/geometry/core/closure.hpp
==============================================================================
--- trunk/boost/geometry/core/closure.hpp	(original)
+++ trunk/boost/geometry/core/closure.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -22,7 +22,27 @@
 {
 
 
-enum closure_selector { open = 0, closed = 1, closure_undertermined = -1 };
+/*!
+\brief Enumerates options for defining if polygons are open or closed
+\ingroup enum
+\details The enumeration closure_selector describes options for if a polygon is
+    open or closed. In a closed polygon the very first point (per ring) should be
+    equal to the very last point.
+    The specific closing property of a polygon type is defined by the closure metafunction.
+    The closure metafunction defines a value, which is one of the values enumerated
+    in the closure_selector
+
+\qbk{
+[heading See also]
+[link geometry.reference.core.closure The closure metafunction]
+}
+*/
+enum closure_selector
+{
+    open = 0,
+    closed = 1,
+    closure_undertermined = -1
+};
 
 namespace traits
 {
@@ -123,8 +143,14 @@
 
 
 /*!
-    \brief Meta-function which defines closure of any geometry
-    \ingroup core
+\brief Meta-function which defines closure of a geometry type
+\ingroup core
+\details
+
+\qbk{
+[heading See also]
+[link geometry.reference.enumerations.order_selector The order_selector enumeration]
+}
 */
 template <typename Geometry>
 struct closure

Modified: trunk/boost/geometry/core/exception.hpp
==============================================================================
--- trunk/boost/geometry/core/exception.hpp	(original)
+++ trunk/boost/geometry/core/exception.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -15,12 +15,14 @@
 {
 
 /*!
-\brief Base exception class for GGL
+\brief Base exception class for Boost.Geometry algorithms
 \ingroup core
+\details This class is never thrown. All exceptions thrown in Boost.Geometry
+    are derived from exception, so it might be convenient to catch it.
 */
-struct exception : public std::exception
-{
-};
+class exception : public std::exception
+{};
+
 
 }} // namespace boost::geometry
 

Modified: trunk/boost/geometry/core/point_order.hpp
==============================================================================
--- trunk/boost/geometry/core/point_order.hpp	(original)
+++ trunk/boost/geometry/core/point_order.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -20,21 +20,40 @@
 namespace boost { namespace geometry
 {
 
-
-enum order_selector { clockwise = 1, counterclockwise = 2, order_undetermined = 0 };
+/*!
+\brief Enumerates options for the order of points within polygons
+\ingroup enum
+\details The enumeration order_selector describes options for the order of points
+    within a polygon. Polygons can be ordered either clockwise or counterclockwise.
+    The specific order of a polygon type is defined by the point_order metafunction.
+    The point_order metafunction defines a value, which is one of the values enumerated
+    in the order_selector
+
+\qbk{
+[heading See also]
+[link geometry.reference.core.point_order The point_order metafunction]
+}
+*/
+enum order_selector
+{
+    /// Points are ordered clockwise
+    clockwise = 1,
+    /// Points are ordered counter clockwise
+    counterclockwise = 2,
+    /// Points might be stored in any order, the algorithm will find out (not yet supported)
+    order_undetermined = 0
+};
 
 namespace traits
 {
 
 /*!
-    \brief Traits class indicating the order of contained points within a
-        ring or (multi)polygon, clockwise, counter clockwise or not known.
-    \ingroup traits
-    \par Geometries:
-        - ring
-    \tparam G geometry
+\brief Traits class indicating the order of contained points within a
+    ring or (multi)polygon, clockwise, counter clockwise or not known.
+\ingroup traits
+\tparam Ring ring
 */
-template <typename G>
+template <typename Ring>
 struct point_order
 {
     static const order_selector value = clockwise;
@@ -74,20 +93,20 @@
 };
 
 template <typename Point>
-struct point_order<point_tag, Point> 
+struct point_order<point_tag, Point>
     : public detail::point_order::clockwise {};
 
 template <typename Segment>
-struct point_order<segment_tag, Segment> 
+struct point_order<segment_tag, Segment>
     : public detail::point_order::clockwise {};
 
 
 template <typename Box>
-struct point_order<box_tag, Box> 
+struct point_order<box_tag, Box>
     : public detail::point_order::clockwise {};
 
 template <typename LineString>
-struct point_order<linestring_tag, LineString>  
+struct point_order<linestring_tag, LineString>
     : public detail::point_order::clockwise {};
 
 
@@ -113,12 +132,19 @@
 
 
 /*!
-    \brief Meta-function which defines point order of any geometry
-    \ingroup core
+\brief Metafunction which defines point order of a geometry type
+\ingroup core
+\details
+
+\qbk{
+[heading See also]
+[link geometry.reference.enumerations.closure_selector The closure_selector enumeration]
+}
 */
 template <typename Geometry>
 struct point_order
 {
+    /// metafunction implementation
     static const order_selector value = core_dispatch::point_order
         <
             typename tag<Geometry>::type,

Modified: trunk/boost/geometry/strategies/agnostic/point_in_poly_winding.hpp
==============================================================================
--- trunk/boost/geometry/strategies/agnostic/point_in_poly_winding.hpp	(original)
+++ trunk/boost/geometry/strategies/agnostic/point_in_poly_winding.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -36,6 +36,11 @@
 \note The implementation is inspired by terralib http://www.terralib.org (LGPL)
 \note but totally revised afterwards, especially for cases on segments
 \note Only dependant on "side", -> agnostic, suitable for spherical/latlong
+
+\qbk{
+[heading See also]
+[link geometry.reference.algorithms.within.within_3_with_strategy within (with strategy)]
+}
  */
 template
 <

Modified: trunk/boost/geometry/strategies/cartesian/area_surveyor.hpp
==============================================================================
--- trunk/boost/geometry/strategies/cartesian/area_surveyor.hpp	(original)
+++ trunk/boost/geometry/strategies/cartesian/area_surveyor.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -32,7 +32,7 @@
 
 \qbk{
 [heading See also]
-[link geometry.reference.algorithms.area.area_2_with_strategy area]
+[link geometry.reference.algorithms.area.area_2_with_strategy area (with strategy)]
 }
 
 */

Modified: trunk/boost/geometry/strategies/cartesian/centroid_bashein_detmer.hpp
==============================================================================
--- trunk/boost/geometry/strategies/cartesian/centroid_bashein_detmer.hpp	(original)
+++ trunk/boost/geometry/strategies/cartesian/centroid_bashein_detmer.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -95,6 +95,12 @@
         , mdsys.sdo_dim_array(mdsys.sdo_dim_element('x',0,10,.00000005)
         ,mdsys.sdo_dim_element('y',0,10,.00000005)))
         from dual
+
+\qbk{
+[heading See also]
+[link geometry.reference.algorithms.centroid.centroid_3_with_strategy centroid (with strategy)]
+}
+
  */
 template
 <

Modified: trunk/boost/geometry/strategies/cartesian/distance_projected_point.hpp
==============================================================================
--- trunk/boost/geometry/strategies/cartesian/distance_projected_point.hpp	(original)
+++ trunk/boost/geometry/strategies/cartesian/distance_projected_point.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -58,7 +58,7 @@
 
 \qbk{
 [heading See also]
-[link geometry.reference.algorithms.distance.distance_3_with_strategy distance]
+[link geometry.reference.algorithms.distance.distance_3_with_strategy distance (with strategy)]
 }
 
 */

Modified: trunk/boost/geometry/strategies/cartesian/distance_pythagoras.hpp
==============================================================================
--- trunk/boost/geometry/strategies/cartesian/distance_pythagoras.hpp	(original)
+++ trunk/boost/geometry/strategies/cartesian/distance_pythagoras.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -119,7 +119,7 @@
 [heading Notes]
 [note Can be used for points with two\, three or more dimensions]
 [heading See also]
-[link geometry.reference.algorithms.distance.distance_3_with_strategy distance]
+[link geometry.reference.algorithms.distance.distance_3_with_strategy distance (with strategy)]
 }
 
 */

Modified: trunk/boost/geometry/strategies/cartesian/point_in_poly_crossings_multiply.hpp
==============================================================================
--- trunk/boost/geometry/strategies/cartesian/point_in_poly_crossings_multiply.hpp	(original)
+++ trunk/boost/geometry/strategies/cartesian/point_in_poly_crossings_multiply.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -27,6 +27,10 @@
 \tparam CalculationType \tparam_calculation
 \see http://tog.acm.org/resources/GraphicsGems/gemsiv/ptpoly_haines/ptinpoly.c
 \note Does NOT work correctly for point ON border
+\qbk{
+[heading See also]
+[link geometry.reference.algorithms.within.within_3_with_strategy within (with strategy)]
+}
  */
 
 template

Modified: trunk/boost/geometry/strategies/cartesian/point_in_poly_franklin.hpp
==============================================================================
--- trunk/boost/geometry/strategies/cartesian/point_in_poly_franklin.hpp	(original)
+++ trunk/boost/geometry/strategies/cartesian/point_in_poly_franklin.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -32,7 +32,10 @@
 \return true if point is in ring, works for closed rings in both directions
 \note Does NOT work correctly for point ON border
 
-
+\qbk{
+[heading See also]
+[link geometry.reference.algorithms.within.within_3_with_strategy within (with strategy)]
+}
  */
 
 template

Modified: trunk/boost/geometry/strategies/spherical/area_huiller.hpp
==============================================================================
--- trunk/boost/geometry/strategies/spherical/area_huiller.hpp	(original)
+++ trunk/boost/geometry/strategies/spherical/area_huiller.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -53,7 +53,7 @@
 
 
 [heading See also]
-[link geometry.reference.algorithms.area.area_2_with_strategy area]
+[link geometry.reference.algorithms.area.area_2_with_strategy area (with strategy)]
 }
 
 */

Modified: trunk/boost/geometry/strategies/spherical/distance_cross_track.hpp
==============================================================================
--- trunk/boost/geometry/strategies/spherical/distance_cross_track.hpp	(original)
+++ trunk/boost/geometry/strategies/spherical/distance_cross_track.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -49,7 +49,7 @@
 
 \qbk{
 [heading See also]
-[link geometry.reference.algorithms.distance.distance_3_with_strategy distance]
+[link geometry.reference.algorithms.distance.distance_3_with_strategy distance (with strategy)]
 }
 
 */

Modified: trunk/boost/geometry/strategies/spherical/distance_haversine.hpp
==============================================================================
--- trunk/boost/geometry/strategies/spherical/distance_haversine.hpp	(original)
+++ trunk/boost/geometry/strategies/spherical/distance_haversine.hpp	2011-01-30 16:48:22 EST (Sun, 30 Jan 2011)
@@ -112,7 +112,7 @@
 
 \qbk{
 [heading See also]
-[link geometry.reference.algorithms.distance.distance_3_with_strategy distance]
+[link geometry.reference.algorithms.distance.distance_3_with_strategy distance (with strategy)]
 }
 
 */