From be4cb4d9a8e032cdc29c9be7a14b166898b49fa6 Mon Sep 17 00:00:00 2001 From: Adam Wulkiewicz Date: Thu, 23 Aug 2012 00:51:24 +0000 Subject: [PATCH] r-tree methods description expanded, default translator description added [SVN r80150] --- .../geometry/extensions/index/rtree/rtree.hpp | 86 ++++++++++++++++--- .../extensions/index/translator/def.hpp | 13 +++ 2 files changed, 88 insertions(+), 11 deletions(-) diff --git a/include/boost/geometry/extensions/index/rtree/rtree.hpp b/include/boost/geometry/extensions/index/rtree/rtree.hpp index 6bc99b767..77021eadb 100644 --- a/include/boost/geometry/extensions/index/rtree/rtree.hpp +++ b/include/boost/geometry/extensions/index/rtree/rtree.hpp @@ -47,11 +47,22 @@ namespace boost { namespace geometry { namespace index { /*! -The R-tree spatial index. +The R-tree spatial index. This is self-balancing spatial index capable to store various types +of Values and balancing algorithms. \tparam Value The type of objects stored in the container. -\tparam Parameters Compile-time parameters. -\tparam Translator The type of the translator. +\tparam Parameters Compile-time parameters. The user must pass a type defining the Parameters which will + be used in rtree creation process. This type is used e.g. to specify balancing algorithm + with compile-time parameters like min and max number of elements in node. + Predefined Algorithms/Parameters are: + bgi::linear, + bgi::quadratic, + bgi::rstar. +\tparam Translator The type of the translator which translates from Value to Indexable. This translation is done each time + the r-tree wants to know Value's Indexable. Default translator can translate all types adapted to Point + or Box concepts (which are Indexables). It also handles std::pair, pointers, smart pointers, + and iterators. E.g. If std::pair is stored, the default translator translates from + std::pair const& to Box const&. \tparam Allocator The allocator. */ template < @@ -339,8 +350,16 @@ public: /*! Find values meeting spatial predicates, e.g. intersecting some box. - \param pred The spatial predicates. - \param out_it The output iterator of the result range. E.g. a back_insert_iterator. + \param pred The spatial predicates. May be a Geometry (in this case default + predicate - intersects is used) or generated by bgi::covered_by(geometry), + bgi::disjoint(geometry), bgi::intersects(geometry), bgi::overlaps(geometry), + bgi::within(geometry), !bgi::covered_by(geometry), !bgi::disjoint(geometry), + !bgi::intersects(geometry), !bgi::overlaps(geometry), !bgi::within(geometry) + or bgi::value(func). Those predicates may be passed together in std::pair + or boost::tuple. + + \param out_it The output iterator of the result range. E.g. an iterator generated by + std::back_inserter(container) \return The number of values found. */ @@ -358,7 +377,16 @@ public: /*! Find one value meeting distances predicates, e.g. nearest to some point. - \param dpred The distances predicates. + \param dpred The distances predicates. May be a Point. This is default case where Value which + nearest point is closest to Point is returned. May be a PointRelation which define + how distance to Value is calculated. This may be generated by bgi::near(Point), + bgi::centroid(Point) or bgi::far(Point). DistancesPredicates may also define distances + bounds. E.g. that some distance must be between min_distance and max_distance. This may + be generated by bgi::unbounded(PointRelation) - default case, bgi::min_bounded(PointRelation, MinRelation), + bgi::max_bounded(PointRelation, MaxRelation), bgi::bounded(PointRelation, MinRelation, MaxRelation). + MinRelation and MaxRelation describes bounds and may be generated by bgi::near(dist_bound), + bgi::centroid(dist_bound) or bgi::far(dist_bound). + \param v The reference to the object which will contain the result. \return The number of values found. @@ -373,8 +401,22 @@ public: Find one value meeting distances predicates and spatial predicates, e.g. nearest to some point and intersecting some box. - \param dpred The distances predicates. - \param pred The spatial predicates. + \param dpred The distances predicates. May be a Point. This is default case where Value which + nearest point is closest to Point is returned. May be a PointRelation which define + how distance to Value is calculated. This may be generated by bgi::near(Point), + bgi::centroid(Point) or bgi::far(Point). DistancesPredicates may also define distances + bounds. E.g. that some distance must be between min_distance and max_distance. This may + be generated by bgi::unbounded(PointRelation) - default case, bgi::min_bounded(PointRelation, MinRelation), + bgi::max_bounded(PointRelation, MaxRelation), bgi::bounded(PointRelation, MinRelation, MaxRelation). + MinRelation and MaxRelation describes bounds and may be generated by bgi::near(dist_bound), + bgi::centroid(dist_bound) or bgi::far(dist_bound). + \param pred The spatial predicates. May be a Geometry (in this case default + predicate - intersects is used) or generated by bgi::covered_by(geometry), + bgi::disjoint(geometry), bgi::intersects(geometry), bgi::overlaps(geometry), + bgi::within(geometry), !bgi::covered_by(geometry), !bgi::disjoint(geometry), + !bgi::intersects(geometry), !bgi::overlaps(geometry), !bgi::within(geometry) + or bgi::value(func). Those predicates may be passed together in std::pair + or boost::tuple. \param v The reference to the object which will contain the result. \return The number of values found. @@ -388,7 +430,15 @@ public: /*! Find k values meeting distances predicates, e.g. k nearest values to some point. - \param dpred The distance predicate. + \param dpred The distances predicates. May be a Point. This is default case where Value which + nearest point is closest to Point is returned. May be a PointRelation which define + how distance to Value is calculated. This may be generated by bgi::near(Point), + bgi::centroid(Point) or bgi::far(Point). DistancesPredicates may also define distances + bounds. E.g. that some distance must be between min_distance and max_distance. This may + be generated by bgi::unbounded(PointRelation) - default case, bgi::min_bounded(PointRelation, MinRelation), + bgi::max_bounded(PointRelation, MaxRelation), bgi::bounded(PointRelation, MinRelation, MaxRelation). + MinRelation and MaxRelation describes bounds and may be generated by bgi::near(dist_bound), + bgi::centroid(dist_bound) or bgi::far(dist_bound). \param k The max number of values. \param out_it The output iterator of the result range. E.g. a back_insert_iterator. @@ -404,9 +454,23 @@ public: Find k values meeting distances predicates and spatial predicates, e.g. k nearest values to some point and intersecting some box. - \param dpred The distances predicates. + \param dpred The distances predicates. May be a Point. This is default case where Value which + nearest point is closest to Point is returned. May be a PointRelation which define + how distance to Value is calculated. This may be generated by bgi::near(Point), + bgi::centroid(Point) or bgi::far(Point). DistancesPredicates may also define distances + bounds. E.g. that some distance must be between min_distance and max_distance. This may + be generated by bgi::unbounded(PointRelation) - default case, bgi::min_bounded(PointRelation, MinRelation), + bgi::max_bounded(PointRelation, MaxRelation), bgi::bounded(PointRelation, MinRelation, MaxRelation). + MinRelation and MaxRelation describes bounds and may be generated by bgi::near(dist_bound), + bgi::centroid(dist_bound) or bgi::far(dist_bound). \param k The max number of values. - \param pred The spatial predicates. + \param pred The spatial predicates. May be a Geometry (in this case default + predicate - intersects is used) or generated by bgi::covered_by(geometry), + bgi::disjoint(geometry), bgi::intersects(geometry), bgi::overlaps(geometry), + bgi::within(geometry), !bgi::covered_by(geometry), !bgi::disjoint(geometry), + !bgi::intersects(geometry), !bgi::overlaps(geometry), !bgi::within(geometry) + or bgi::value(func). Those predicates may be passed together in std::pair + or boost::tuple. \param out_it The output iterator of the result range. E.g. a back_insert_iterator. \return The number of values found. diff --git a/include/boost/geometry/extensions/index/translator/def.hpp b/include/boost/geometry/extensions/index/translator/def.hpp index 673b7cf60..c20fff09c 100644 --- a/include/boost/geometry/extensions/index/translator/def.hpp +++ b/include/boost/geometry/extensions/index/translator/def.hpp @@ -71,6 +71,12 @@ struct def } // namespace dispatch +/*! +The default translator. It translates Value object to Indexable object. This is done in +operator() which takes const reference to Value and returns const reference to Indexable. + +\tparam Value The Value type which the translator translates to Indexable. +*/ template struct def : public dispatch::def @@ -82,6 +88,13 @@ struct def { }; +/*! +The default translator. It translates Value object to Indexable object. Since this is +a specialization for pointers to Values operator() takes const ptr to Value and returns +const reference to Indexable. + +\tparam Value The Value type which the translator translates to Indexable. +*/ template struct def {