1 // Boost.Geometry Index
3 // Spatial index distance predicates, calculators and checkers used in nearest neighbor query
5 // Copyright (c) 2011-2013 Adam Wulkiewicz, Lodz, Poland.
7 // Use, modification and distribution is subject to the Boost Software License,
8 // Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
9 // http://www.boost.org/LICENSE_1_0.txt)
11 #ifndef BOOST_GEOMETRY_INDEX_DISTANCE_PREDICATES_HPP
12 #define BOOST_GEOMETRY_INDEX_DISTANCE_PREDICATES_HPP
14 #include <boost/geometry/index/detail/distance_predicates.hpp>
17 \defgroup nearest_relations Nearest relations (boost::geometry::index::)
20 namespace boost { namespace geometry { namespace index {
22 // relations generators
24 #ifdef BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL
27 \brief Generate to_nearest() relationship.
29 Generate a nearest query Point and Value's Indexable relationship while calculating
30 distances. This function may be used to define that knn query should calculate distances
31 as smallest as possible between query Point and Indexable's points. In other words it
32 should be the distance to the nearest Indexable's point. This function may be also used
33 to define distances bounds which indicates that Indexable's nearest point should be
34 closer or further than value v. This is default relation.
36 \ingroup nearest_relations
38 \tparam T Type of wrapped object. This may be a Point for PointRelation or CoordinateType for
39 MinRelation or MaxRelation
41 \param v Point or distance value.
44 detail::to_nearest<T> to_nearest(T const& v)
46 return detail::to_nearest<T>(v);
50 \brief Generate to_centroid() relationship.
52 Generate a nearest query Point and Value's Indexable relationship while calculating
53 distances. This function may be used to define that knn query should calculate distances
54 between query Point and Indexable's centroid. This function may be also used
55 to define distances bounds which indicates that Indexable's centroid should be
56 closer or further than value v.
58 \ingroup nearest_relations
60 \tparam T Type of wrapped object. This may be a Point for PointRelation or some CoordinateType for
61 MinRelation or MaxRelation
63 \param v Point or distance value.
66 detail::to_centroid<T> to_centroid(T const& v)
68 return detail::to_centroid<T>(v);
72 \brief Generate to_furthest() relationship.
74 Generate a nearest query Point and Value's Indexable relationship while calculating
75 distances. This function may be used to define that knn query should calculate distances
76 as biggest as possible between query Point and Indexable's points. In other words it
77 should be the distance to the furthest Indexable's point. This function may be also used
78 to define distances bounds which indicates that Indexable's furthest point should be
79 closer or further than value v.
81 \ingroup nearest_relations
83 \tparam T Type of wrapped object. This may be a Point for PointRelation or some CoordinateType for
84 MinRelation or MaxRelation
86 \param v Point or distance value.
89 detail::to_furthest<T> to_furthest(T const& v)
91 return detail::to_furthest<T>(v);
94 #endif // BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL
96 // distance predicates generators
99 \brief Generate unbounded() distance predicate.
101 Generate a distance predicate. This defines distances bounds which are used by knn query.
102 This function indicates that there is no distance bounds and Values should be returned
103 if distances between Point and Indexable are the smallest. Distance calculation is defined
104 by PointRelation. This is default nearest predicate.
106 \ingroup distance_predicates
108 \tparam PointRelation PointRelation type.
110 \param pr The point relation. This may be generated by \c index::to_nearest(),
111 \c index::to_centroid() or \c index::to_furthest() with \c Point passed as a parameter.
113 //template <typename PointRelation>
114 //inline detail::unbounded<PointRelation>
115 //unbounded(PointRelation const& pr)
117 // return detail::unbounded<PointRelation>(pr);
121 \brief Generate min_bounded() distance predicate.
123 Generate a distance predicate. This defines distances bounds which are used by knn query.
124 This function indicates that Values should be returned only if distances between Point and
125 Indexable are greater or equal to some min_distance passed in MinRelation. Check for closest Value is
126 defined by PointRelation. So it is possible e.g. to return Values with centroids closest to some
127 Point but only if nearest points are further than some distance.
129 \ingroup distance_predicates
131 \tparam PointRelation PointRelation type.
132 \tparam MinRelation MinRelation type.
134 \param pr The point relation. This may be generated by \c to_nearest(),
135 \c to_centroid() or \c to_furthest() with \c Point passed as a parameter.
136 \param minr The minimum bound relation. This may be generated by \c to_nearest(),
137 \c to_centroid() or \c to_furthest() with distance value passed as a parameter.
139 //template <typename PointRelation, typename MinRelation>
140 //inline detail::min_bounded<PointRelation, MinRelation>
141 //min_bounded(PointRelation const& pr, MinRelation const& minr)
143 // return detail::min_bounded<PointRelation, MinRelation>(pr, minr);
147 \brief Generate max_bounded() distance predicate.
149 Generate a distance predicate. This defines distances bounds which are used by knn query.
150 This function indicates that Values should be returned only if distances between Point and
151 Indexable are lesser or equal to some max_distance passed in MaxRelation. Check for closest Value is
152 defined by PointRelation. So it is possible e.g. to return Values with centroids closest to some
153 Point but only if nearest points are closer than some distance.
155 \ingroup distance_predicates
157 \tparam PointRelation PointRelation type.
158 \tparam MaxRelation MaxRelation type.
160 \param pr The point relation. This may be generated by \c to_nearest(),
161 \c to_centroid() or \c to_furthest() with \c Point passed as a parameter.
162 \param maxr The maximum bound relation. This may be generated by \c to_nearest(),
163 \c to_centroid() or \c to_furthest() with distance value passed as a parameter.
165 //template <typename PointRelation, typename MaxRelation>
166 //inline detail::max_bounded<PointRelation, MaxRelation>
167 //max_bounded(PointRelation const& pr, MaxRelation const& maxr)
169 // return detail::max_bounded<PointRelation, MaxRelation>(pr, maxr);
173 \brief Generate bounded() distance predicate.
175 Generate a distance predicate. This defines distances bounds which are used by knn query.
176 This function indicates that Values should be returned only if distances between Point and
177 Indexable are greater or equal to some min_distance passed in MinRelation and lesser or equal to
178 some max_distance passed in MaxRelation. Check for closest Value is defined by PointRelation.
179 So it is possible e.g. to return Values with centroids closest to some Point but only if nearest
180 points are further than some distance and closer than some other distance.
182 \ingroup distance_predicates
184 \tparam PointRelation PointRelation type.
185 \tparam MinRelation MinRelation type.
186 \tparam MaxRelation MaxRelation type.
188 \param pr The point relation. This may be generated by \c to_nearest(),
189 \c to_centroid() or \c to_furthest() with \c Point passed as a parameter.
190 \param minr The minimum bound relation. This may be generated by \c to_nearest(),
191 \c to_centroid() or \c to_furthest() with distance value passed as a parameter.
192 \param maxr The maximum bound relation. This may be generated by \c to_nearest(),
193 \c to_centroid() or \c to_furthest() with distance value passed as a parameter.
195 //template <typename PointRelation, typename MinRelation, typename MaxRelation>
196 //inline detail::bounded<PointRelation, MinRelation, MaxRelation>
197 //bounded(PointRelation const& pr, MinRelation const& minr, MaxRelation const& maxr)
199 // return detail::bounded<PointRelation, MinRelation, MaxRelation>(pr, minr, maxr);
202 }}} // namespace boost::geometry::index
204 #endif // BOOST_GEOMETRY_INDEX_DISTANCE_PREDICATES_HPP