From 685d8b043e5cdbeed2bfc4b7a0022257fd27b0e3 Mon Sep 17 00:00:00 2001 From: Clement Jamin Date: Wed, 18 Oct 2017 11:11:55 +0200 Subject: [PATCH] Document the option to enable a cache + interruptible distance computation --- .../Spatial_searching/CGAL/Fuzzy_iso_box.h | 7 +++++ .../doc/Spatial_searching/CGAL/Fuzzy_sphere.h | 7 +++++ .../doc/Spatial_searching/CGAL/Kd_tree.h | 13 ++++++++- .../Concepts/FuzzyQueryItem.h | 9 +++++++ .../Concepts/GeneralDistance.h | 27 +++++++++++++++++++ .../Spatial_searching/Spatial_searching.txt | 12 +++++++++ 6 files changed, 74 insertions(+), 1 deletion(-) diff --git a/Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_iso_box.h b/Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_iso_box.h index 2366cfa35ba..7312edff28f 100644 --- a/Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_iso_box.h +++ b/Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_iso_box.h @@ -76,6 +76,13 @@ Test whether the fuzzy iso box contains `p`. */ bool contains(Point_d p) const; +/*! +Test whether the fuzzy iso box contains the point whose coordinates are contained in +the range [`begin`, `end`). +*/ +template +bool contains_point_given_as_coordinates(Coord_iterator begin, Coord_iterator end) const; + /*! Test whether the inner box intersects the rectangle associated with a node of a tree. diff --git a/Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_sphere.h b/Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_sphere.h index db3aec07db3..1988463b3d6 100644 --- a/Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_sphere.h +++ b/Spatial_searching/doc/Spatial_searching/CGAL/Fuzzy_sphere.h @@ -78,6 +78,13 @@ less than \f$ r\f$. */ bool contains(const Point_d& p) const; +/*! +Test whether the fuzzy sphere contains the point whose coordinates are contained in +the range [`begin`, `end`). +*/ +template +bool contains_point_given_as_coordinates(Coord_iterator begin, Coord_iterator end) const; + /*! Test whether the inner sphere intersects the rectangle associated with a node of a tree. diff --git a/Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h b/Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h index 3c7a21b94de..0303a7ba84b 100644 --- a/Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h +++ b/Spatial_searching/doc/Spatial_searching/CGAL/Kd_tree.h @@ -14,13 +14,24 @@ It defaults to `Sliding_midpoint`. \tparam UseExtendedNode must be `Tag_true`, if the tree shall be built with extended nodes, and `Tag_false` otherwise. +\tparam EnablePointsCache can be `Tag_true` or `Tag_false`. +Not storing the points coordinates inside the tree usually generates a +lot of cache misses, leading to non-optimal performance. This is the case +for example when indices are stored inside the tree, or when the points +coordinates are stored in a dynamically allocated array. When +`EnablePointsCache` is set to `Tag_true`, the points +coordinates will be cached in an optimal way. This will +increase memory consumption but provide better search performance. +See also the `GeneralDistance` and `FuzzyQueryItem` concepts for +additional requirements when using such a cache. + \sa `CGAL::Kd_tree_node` \sa `CGAL::Search_traits_2` \sa `CGAL::Search_traits_3` \sa `CGAL::Search_traits` */ -template< typename Traits, typename Splitter, typename UseExtendedNode > +template< typename Traits, typename Splitter, typename UseExtendedNode, typename EnablePointsCache > class Kd_tree { public: diff --git a/Spatial_searching/doc/Spatial_searching/Concepts/FuzzyQueryItem.h b/Spatial_searching/doc/Spatial_searching/Concepts/FuzzyQueryItem.h index cc163a57e7e..8ce782c81db 100644 --- a/Spatial_searching/doc/Spatial_searching/Concepts/FuzzyQueryItem.h +++ b/Spatial_searching/doc/Spatial_searching/Concepts/FuzzyQueryItem.h @@ -40,6 +40,15 @@ Test whether the query item contains `p`. */ bool contains(Point_d p) const; +/*! +Optional: must be defined when used with a `Kd_tree` where `EnablePointsCache` +is set to `Tag_true`. +Test whether the query item contains the point whose coordinates are contained in +the range [`begin`, `end`). +*/ +template +bool contains_point_given_as_coordinates(Coord_iterator begin, Coord_iterator end) const; + /*! Test whether the inner approximation of the spatial object intersects a rectangle associated with a node of a tree. diff --git a/Spatial_searching/doc/Spatial_searching/Concepts/GeneralDistance.h b/Spatial_searching/doc/Spatial_searching/Concepts/GeneralDistance.h index d78dd827aee..e1ed793a2a2 100644 --- a/Spatial_searching/doc/Spatial_searching/Concepts/GeneralDistance.h +++ b/Spatial_searching/doc/Spatial_searching/Concepts/GeneralDistance.h @@ -49,6 +49,33 @@ Returns the transformed distance between `q` and `r`. */ FT transformed_distance(Query_item q, Point_d r); +/*! +Optional: must be defined when used with a `Kd_tree` where `EnablePointsCache` +is set to `Tag_true`. + +Returns the transformed distance between `q` and the point whose coordinates +are contained in the range [`begin`, `end`). +*/ +template +FT transformed_distance_from_coordinates( + Query_item q, Coord_iterator begin, Coord_iterator end) const; + +/*! +Optional: in most cases (e.g. Euclidean distance), the distance computation +algorithm knows before its end that the distance will be greater than or equal +to some given value. In this function, the computation can be stopped when the +distance is going to be greater than or equal to `stop_if_geq_to_this`. In this case, +the only requirement of the return value it to be \f$ \geq \f$ `stop_if_geq_to_this`. +Note that points cache does not have to be activated to enable this optimization. + +Returns the transformed distance between `q` and the point whose coordinates +are contained in the range [`begin`, `end`), or any value \f$ \geq \f$ +`stop_if_geq_to_this` if the transformed distance is \f$ \geq \f$ `stop_if_geq_to_this`. +*/ +template +FT interruptible_transformed_distance( + Query_item q, Coord_iterator begin, Coord_iterator end, FT stop_if_geq_to_this) const; + /*! Returns the transformed distance between `q` and the point on the boundary of `r` closest to `q`. diff --git a/Spatial_searching/doc/Spatial_searching/Spatial_searching.txt b/Spatial_searching/doc/Spatial_searching/Spatial_searching.txt index 40ca743f96f..b03f6f0de88 100644 --- a/Spatial_searching/doc/Spatial_searching/Spatial_searching.txt +++ b/Spatial_searching/doc/Spatial_searching/Spatial_searching.txt @@ -498,6 +498,18 @@ instead of the distance itself. For instance for the Euclidean distance, to avoid the expensive computation of square roots, squared distances are used instead of the Euclidean distance itself. +\cgalModifBegin +Not storing the points coordinates inside the tree usually generates a +lot of cache misses, leading to non-optimal performance. This is the case +for example when indices are stored inside the tree, or when the points +coordinates are stored in a dynamically allocated array. In this case, +the `EnablePointsCache` template parameter of the `Kd_tree` class can be +set to `Tag_true`. The points coordinates will then be cached in an optimal +way. This will increase memory consumption but provide better search +performance. See also the `GeneralDistance` and `FuzzyQueryItem` concepts for +additional requirements when using such a cache. +\cgalModif + \section Spatial_searchingImplementationHistory Implementation History The initial implementation of this package was done by Hans Tangelder and