geometry/index/distance_predicates.hpp

0001 // Boost.Geometry Index
0002 //
0003 // Spatial index distance predicates, calculators and checkers used in nearest neighbor query
0004 //
0005 // Copyright (c) 2011-2022 Adam Wulkiewicz, Lodz, Poland.
0006 //
0007 // Use, modification and distribution is subject to the Boost Software License,
0008 // Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
0009 // http://www.boost.org/LICENSE_1_0.txt)
0010
0011 #ifndef BOOST_GEOMETRY_INDEX_DISTANCE_PREDICATES_HPP
0012 #define BOOST_GEOMETRY_INDEX_DISTANCE_PREDICATES_HPP
0013
0014 #ifdef BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL
0015 #ifndef BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL_PREDICATES
0016 #define BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL_PREDICATES
0017 #endif
0018 #endif
0019
0020 #include <boost/geometry/index/detail/distance_predicates.hpp>
0021
0022 /*!
0023 \defgroup nearest_relations Nearest relations (boost::geometry::index::)
0024 */
0025
0026 namespace boost { namespace geometry { namespace index {
0027
0028 // relations generators
0029
0030 #ifdef BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL_PREDICATES
0031
0032 /*!
0033 \brief Generate to_nearest() relationship.
0034
0035 Generate a nearest query Point and Value's Indexable relationship while calculating
0036 distances. This function may be used to define that knn query should calculate distances
0037 as smallest as possible between query Point and Indexable's points. In other words it
0038 should be the distance to the nearest Indexable's point. This function may be also used
0039 to define distances bounds which indicates that Indexable's nearest point should be
0040 closer or further than value v. This is default relation.
0041
0042 \ingroup nearest_relations
0043
0044 \tparam T   Type of wrapped object. This may be a Point for PointRelation or CoordinateType for
0045             MinRelation or MaxRelation
0046
0047 \param v    Point or distance value.
0048 */
0049 template <typename T>
0050 detail::to_nearest<T> to_nearest(T const& v)
0051 {
0052     return detail::to_nearest<T>(v);
0053 }
0054
0055 /*!
0056 \brief Generate to_centroid() relationship.
0057
0058 Generate a nearest query Point and Value's Indexable relationship while calculating
0059 distances. This function may be used to define that knn query should calculate distances
0060 between query Point and Indexable's centroid. This function may be also used
0061 to define distances bounds which indicates that Indexable's centroid should be
0062 closer or further than value v.
0063
0064 \ingroup nearest_relations
0065
0066 \tparam T   Type of wrapped object. This may be a Point for PointRelation or some CoordinateType for
0067             MinRelation or MaxRelation
0068
0069 \param v    Point or distance value.
0070 */
0071 template <typename T>
0072 detail::to_centroid<T> to_centroid(T const& v)
0073 {
0074     return detail::to_centroid<T>(v);
0075 }
0076
0077 /*!
0078 \brief Generate to_furthest() relationship.
0079
0080 Generate a nearest query Point and Value's Indexable relationship while calculating
0081 distances. This function may be used to define that knn query should calculate distances
0082 as biggest as possible between query Point and Indexable's points. In other words it
0083 should be the distance to the furthest Indexable's point. This function may be also used
0084 to define distances bounds which indicates that Indexable's furthest point should be
0085 closer or further than value v.
0086
0087 \ingroup nearest_relations
0088
0089 \tparam T   Type of wrapped object. This may be a Point for PointRelation or some CoordinateType for
0090             MinRelation or MaxRelation
0091
0092 \param v    Point or distance value.
0093 */
0094 template <typename T>
0095 detail::to_furthest<T> to_furthest(T const& v)
0096 {
0097     return detail::to_furthest<T>(v);
0098 }
0099
0100 #endif // BOOST_GEOMETRY_INDEX_DETAIL_EXPERIMENTAL_PREDICATES
0101
0102 // distance predicates generators
0103
0104 /*!
0105 \brief Generate unbounded() distance predicate.
0106
0107 Generate a distance predicate. This defines distances bounds which are used by knn query.
0108 This function indicates that there is no distance bounds and Values should be returned
0109 if distances between Point and Indexable are the smallest. Distance calculation is defined
0110 by PointRelation. This is default nearest predicate.
0111
0112 \ingroup distance_predicates
0113
0114 \tparam PointRelation   PointRelation type.
0115
0116 \param pr               The point relation. This may be generated by \c index::to_nearest(),
0117                         \c index::to_centroid() or \c index::to_furthest() with \c Point passed as a parameter.
0118 */
0119 //template <typename PointRelation>
0120 //inline detail::unbounded<PointRelation>
0121 //unbounded(PointRelation const& pr)
0122 //{
0123 //    return detail::unbounded<PointRelation>(pr);
0124 //}
0125
0126 /*!
0127 \brief Generate min_bounded() distance predicate.
0128
0129 Generate a distance predicate. This defines distances bounds which are used by knn query.
0130 This function indicates that Values should be returned only if distances between Point and
0131 Indexable are greater or equal to some min_distance passed in MinRelation. Check for closest Value is
0132 defined by PointRelation. So it is possible e.g. to return Values with centroids closest to some
0133 Point but only if nearest points are further than some distance.
0134
0135 \ingroup distance_predicates
0136
0137 \tparam PointRelation   PointRelation type.
0138 \tparam MinRelation     MinRelation type.
0139
0140 \param pr               The point relation. This may be generated by \c to_nearest(),
0141                         \c to_centroid() or \c to_furthest() with \c Point passed as a parameter.
0142 \param minr             The minimum bound relation. This may be generated by \c to_nearest(),
0143                         \c to_centroid() or \c to_furthest() with distance value passed as a parameter.
0144 */
0145 //template <typename PointRelation, typename MinRelation>
0146 //inline detail::min_bounded<PointRelation, MinRelation>
0147 //min_bounded(PointRelation const& pr, MinRelation const& minr)
0148 //{
0149 //    return detail::min_bounded<PointRelation, MinRelation>(pr, minr);
0150 //}
0151
0152 /*!
0153 \brief Generate max_bounded() distance predicate.
0154
0155 Generate a distance predicate. This defines distances bounds which are used by knn query.
0156 This function indicates that Values should be returned only if distances between Point and
0157 Indexable are lesser or equal to some max_distance passed in MaxRelation. Check for closest Value is
0158 defined by PointRelation. So it is possible e.g. to return Values with centroids closest to some
0159 Point but only if nearest points are closer than some distance.
0160
0161 \ingroup distance_predicates
0162
0163 \tparam PointRelation   PointRelation type.
0164 \tparam MaxRelation     MaxRelation type.
0165
0166 \param pr               The point relation. This may be generated by \c to_nearest(),
0167                         \c to_centroid() or \c to_furthest() with \c Point passed as a parameter.
0168 \param maxr             The maximum bound relation. This may be generated by \c to_nearest(),
0169                         \c to_centroid() or \c to_furthest() with distance value passed as a parameter.
0170 */
0171 //template <typename PointRelation, typename MaxRelation>
0172 //inline detail::max_bounded<PointRelation, MaxRelation>
0173 //max_bounded(PointRelation const& pr, MaxRelation const& maxr)
0174 //{
0175 //    return detail::max_bounded<PointRelation, MaxRelation>(pr, maxr);
0176 //}
0177
0178 /*!
0179 \brief Generate bounded() distance predicate.
0180
0181 Generate a distance predicate. This defines distances bounds which are used by knn query.
0182 This function indicates that Values should be returned only if distances between Point and
0183 Indexable are greater or equal to some min_distance passed in MinRelation and lesser or equal to
0184 some max_distance passed in MaxRelation. Check for closest Value is defined by PointRelation.
0185 So it is possible e.g. to return Values with centroids closest to some Point but only if nearest
0186 points are further than some distance and closer than some other distance.
0187
0188 \ingroup distance_predicates
0189
0190 \tparam PointRelation   PointRelation type.
0191 \tparam MinRelation     MinRelation type.
0192 \tparam MaxRelation     MaxRelation type.
0193
0194 \param pr               The point relation. This may be generated by \c to_nearest(),
0195                         \c to_centroid() or \c to_furthest() with \c Point passed as a parameter.
0196 \param minr             The minimum bound relation. This may be generated by \c to_nearest(),
0197                         \c to_centroid() or \c to_furthest() with distance value passed as a parameter.
0198 \param maxr             The maximum bound relation. This may be generated by \c to_nearest(),
0199                         \c to_centroid() or \c to_furthest() with distance value passed as a parameter.
0200 */
0201 //template <typename PointRelation, typename MinRelation, typename MaxRelation>
0202 //inline detail::bounded<PointRelation, MinRelation, MaxRelation>
0203 //bounded(PointRelation const& pr, MinRelation const& minr, MaxRelation const& maxr)
0204 //{
0205 //    return detail::bounded<PointRelation, MinRelation, MaxRelation>(pr, minr, maxr);
0206 //}
0207
0208 }}} // namespace boost::geometry::index
0209
0210 #endif // BOOST_GEOMETRY_INDEX_DISTANCE_PREDICATES_HPP