Boost logo

Boost-Commit :

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)]
 }
 
 */


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk