diff --git a/include/boost/geometry/extensions/index/distance_predicates.hpp b/include/boost/geometry/extensions/index/distance_predicates.hpp index ddd58c9b5..1df5c6b03 100644 --- a/include/boost/geometry/extensions/index/distance_predicates.hpp +++ b/include/boost/geometry/extensions/index/distance_predicates.hpp @@ -100,18 +100,56 @@ struct relation< far > // relations generators +/*! +Generate a nearest query Point and Value's Indexable relationship while calculating +distances. This function may be used to define that knn query should calculate distances +as smallest as possible between query Point and Indexable's points. In other words it +should be the distance to the nearest Indexable's point. This function may be also used +to define distances bounds which indicates that Indexable's nearest point should be +closer or further than value v. This is default relation. + +\tparam T Type of wrapped object. This may be a Point for PointRelation or some Value for + MinRelation or MaxRelation + +\param v Point or bound value. +*/ template detail::near near(T const& v) { return detail::near(v); } +/*! +Generate a nearest query Point and Value's Indexable relationship while calculating +distances. This function may be used to define that knn query should calculate distances +between query Point and Indexable's centroid. This function may be also used +to define distances bounds which indicates that Indexable's centroid should be +closer or further than value v. + +\tparam T Type of wrapped object. This may be a Point for PointRelation or some Value for + MinRelation or MaxRelation + +\param v Point or bound value. +*/ template detail::centroid centroid(T const& v) { return detail::centroid(v); } +/*! +Generate a nearest query Point and Value's Indexable relationship while calculating +distances. This function may be used to define that knn query should calculate distances +as biggest as possible between query Point and Indexable's points. In other words it +should be the distance to the furthest Indexable's point. This function may be also used +to define distances bounds which indicates that Indexable's furthest point should be +closer or further than value v. + +\tparam T Type of wrapped object. This may be a Point for PointRelation or some Value for + MinRelation or MaxRelation + +\param v Point or bound value. +*/ template detail::far far(T const& v) { @@ -197,6 +235,17 @@ struct bounded // distance predicates generators +/*! +Generate a distance predicate. This defines distances bounds which are used by knn query. +This function indicates that there is no distance bounds and Values should be returned +if distances between Point and Indexable are the smallest. Distance calculation is defined +by PointRelation. This is default nearest predicate. + +\tparam PointRelation PointRelation type. + +\param pr The point relation. This may be generated by bgi::near(Point), + bgi::centroid(Point) or bgi::far(Point). +*/ template inline detail::unbounded unbounded(PointRelation const& pr) @@ -204,6 +253,21 @@ unbounded(PointRelation const& pr) return detail::unbounded(pr); } +/*! +Generate a distance predicate. This defines distances bounds which are used by knn query. +This function indicates that Values should be returned only if distances between Point and +Indexable are greater or equal to some min_distance passed in MinRelation. Check for closest Value is +defined by PointRelation. So it is possible e.g. to return Values with centroids closest to some +Point but only if nearest points are further than some distance. + +\tparam PointRelation PointRelation type. +\tparam MinRelation MinRelation type. + +\param pr The point relation. This may be generated by bgi::near(Point), + bgi::centroid(Point) or bgi::far(Point). +\param minr The minimum bound relation. This may be generated by bgi::near(min_distance), + bgi::centroid(min_distance) or bgi::far(min_distance). +*/ template inline detail::min_bounded min_bounded(PointRelation const& pr, MinRelation const& minr) @@ -211,6 +275,21 @@ min_bounded(PointRelation const& pr, MinRelation const& minr) return detail::min_bounded(pr, minr); } +/*! +Generate a distance predicate. This defines distances bounds which are used by knn query. +This function indicates that Values should be returned only if distances between Point and +Indexable are lesser or equal to some max_distance passed in MaxRelation. Check for closest Value is +defined by PointRelation. So it is possible e.g. to return Values with centroids closest to some +Point but only if nearest points are closer than some distance. + +\tparam PointRelation PointRelation type. +\tparam MaxRelation MaxRelation type. + +\param pr The point relation. This may be generated by bgi::near(Point), + bgi::centroid(Point) or bgi::far(Point). +\param maxr The maximum bound relation. This may be generated by bgi::near(max_distance), + bgi::centroid(max_distance) or bgi::far(max_distance). +*/ template inline detail::max_bounded max_bounded(PointRelation const& pr, MaxRelation const& maxr) @@ -218,6 +297,25 @@ max_bounded(PointRelation const& pr, MaxRelation const& maxr) return detail::max_bounded(pr, maxr); } +/*! +Generate a distance predicate. This defines distances bounds which are used by knn query. +This function indicates that Values should be returned only if distances between Point and +Indexable are greater or equal to some min_distance passed in MinRelation and lesser or equal to +some max_distance passed in MaxRelation. Check for closest Value is defined by PointRelation. +So it is possible e.g. to return Values with centroids closest to some Point but only if nearest +points are further than some distance and closer than some other distance. + +\tparam PointRelation PointRelation type. +\tparam MinRelation MinRelation type. +\tparam MaxRelation MaxRelation type. + +\param pr The point relation. This may be generated by bgi::near(Point), + bgi::centroid(Point) or bgi::far(Point). +\param minr The minimum bound relation. This may be generated by bgi::near(min_distance), + bgi::centroid(min_distance) or bgi::far(min_distance). +\param maxr The maximum bound relation. This may be generated by bgi::near(max_distance), + bgi::centroid(max_distance) or bgi::far(max_distance). +*/ template inline detail::bounded bounded(PointRelation const& pr, MinRelation const& minr, MaxRelation const& maxr) diff --git a/include/boost/geometry/extensions/index/predicates.hpp b/include/boost/geometry/extensions/index/predicates.hpp index 63358a94f..57b0d088d 100644 --- a/include/boost/geometry/extensions/index/predicates.hpp +++ b/include/boost/geometry/extensions/index/predicates.hpp @@ -120,83 +120,202 @@ struct not_within // generators +/*! +Generate empty predicate. +*/ inline detail::empty empty() { return detail::empty(); } +/*! +Generate value predicate. A wrapper around user-defined functor +describing if Value should be returned by spatial query. + +\tparam ValuePredicate Functor type. + +\param vpred The functor. +*/ template inline detail::value value(ValuePredicate const& vpred) { return detail::value(vpred); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::covered_by(Indexable, Geometry) +returns true. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::covered_by covered_by(Geometry const& g) { return detail::covered_by(g); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::disjoint(Indexable, Geometry) +returns true. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::disjoint disjoint(Geometry const& g) { return detail::disjoint(g); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::intersects(Indexable, Geometry) +returns true. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::intersects intersects(Geometry const& g) { return detail::intersects(g); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::overlaps(Indexable, Geometry) +returns true. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::overlaps overlaps(Geometry const& g) { return detail::overlaps(g); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::touches(Indexable, Geometry) +returns true. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ //template //inline detail::touches touches(Geometry const& g) //{ // return detail::touches(g); //} +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::within(Indexable, Geometry) +returns true. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::within within(Geometry const& g) { return detail::within(g); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::covered_by(Indexable, Geometry) +returns false. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::not_covered_by not_covered_by(Geometry const& g) { return detail::not_covered_by(g); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::disjoint(Indexable, Geometry) +returns false. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::not_disjoint not_disjoint(Geometry const& g) { return detail::not_disjoint(g); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::intersects(Indexable, Geometry) +returns false. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::not_intersects not_intersects(Geometry const& g) { return detail::not_intersects(g); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::overlaps(Indexable, Geometry) +returns false. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::not_overlaps not_overlaps(Geometry const& g) { return detail::not_overlaps(g); } +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::touches(Indexable, Geometry) +returns false. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ //template //inline detail::not_touches not_touches(Geometry const& g) //{ // return detail::not_touches(g); //} +/*! +Generate a predicate defining Value and Geometry relationship. +Value will be returned by the query if bg::within(Indexable, Geometry) +returns false. + +\tparam Geometry The Geometry type. + +\param g The Geometry object. +*/ template inline detail::not_within not_within(Geometry const& g) {