diff --git a/Frechet_distance/doc/Frechet_distance/Concepts/FrechetDistanceTraits.h b/Frechet_distance/doc/Frechet_distance/Concepts/FrechetDistanceTraits.h index 141cdd72368..6d1d2ae2cc8 100644 --- a/Frechet_distance/doc/Frechet_distance/Concepts/FrechetDistanceTraits.h +++ b/Frechet_distance/doc/Frechet_distance/Concepts/FrechetDistanceTraits.h @@ -4,7 +4,7 @@ The concept `FrechetDistanceTraits` defines the requirements of the first template parameter of the functions `CGAL::is_Frechet_distance_larger()` -and `CGAL::approximate_Frechet_distance()`. +and `CGAL::bounded_error_Frechet_distance()`. \cgalHasModelsBegin diff --git a/Frechet_distance/doc/Frechet_distance/Frechet_distance.txt b/Frechet_distance/doc/Frechet_distance/Frechet_distance.txt index 573cb786abf..a4bcd1d8107 100644 --- a/Frechet_distance/doc/Frechet_distance/Frechet_distance.txt +++ b/Frechet_distance/doc/Frechet_distance/Frechet_distance.txt @@ -14,10 +14,10 @@ namespace CGAL { This package provides functions for computing the Fréchet distance of polylines in any dimension under the Euclidean metric. -\section secFrechetDistanceIntroduction Introdution +\section secFrechetDistanceIntroduction Introduction The Fréchet distance is a classical dissimilarity measure between polylines. -Its advantages over other measures is that it both considers the polylines as continuous objects and takes into account the ordering of the points. +Its advantages over other measures are that it both considers the polylines as continuous objects and takes into account the ordering of the points. Intuitively, the Fréchet distance is commonly explained as follows: Imagine a human walking on one polyline while a dog walks on the other polyline, they are connected by a leash, and they are only allowed to walk forward. The Fréchet distance is the shortest leash length that allows the human and the dog to jointly walk from start to end on their respective trajectories. @@ -45,11 +45,10 @@ The traits classes have as template parameter a kernel, model of the concept `Ke In case the static constant `Has_filtered_predicates` of the kernel is `true`, the functions combine interval arithmetic with a fallback to exact computing in case comparisons of intervals are uncertain. This means for `Simple_cartesian` that there are no guarantees, for -`Simple_cartesian` that all computation is done with exact rationals, +`Simple_cartesian` that all computations are performed with exact rationals, and for kernels such as `Exact_predicates_inexact_constructions_kernel`, `Exact_predicates_exact_constructions_kernel`, `Exact_predicates_exact_constructions_kernel_with_sqrt`, -as well as `Epick_d` and `Epeck_d`, the computation is filtered and hence fast and at -the same time guaranteed to be correct. +as well as `Epick_d` and `Epeck_d`, the computation is filtered and hence both fast and guaranteed to be correct. \section secFrechetDistanceImplementation Implementation @@ -92,6 +91,14 @@ polylines in 4-dimensional Euclidean space using `bounded_error_Frechet_distance \cgalExample{Frechet_distance/Frechet_distance_d.cpp} +\subsection subsecFrechetDistanceDSExample Searching Close Curves + +The following example shows how to store many curves in a data structure and to find all curves +closed than a distance bound for a query curve. + +\cgalExample{Frechet_distance/Frechet_DS_3.cpp} + + \subsection subsecFrechetDistanceImageCredits Image Credits The teaser image is a visualization of two data points from the Character Trajectories data set. diff --git a/Frechet_distance/doc/Frechet_distance/examples.txt b/Frechet_distance/doc/Frechet_distance/examples.txt index 67f840658c7..01941adf3d5 100644 --- a/Frechet_distance/doc/Frechet_distance/examples.txt +++ b/Frechet_distance/doc/Frechet_distance/examples.txt @@ -2,4 +2,5 @@ \example Frechet_distance/Frechet_distance_2.cpp \example Frechet_distance/Frechet_distance_3.cpp \example Frechet_distance/Frechet_distance_d.cpp +\example Frechet_distance/Frechet_DS_3.cpp */ \ No newline at end of file diff --git a/Frechet_distance/include/CGAL/Frechet_distance.h b/Frechet_distance/include/CGAL/Frechet_distance.h index 678c0e54d61..5869f4297fe 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance.h +++ b/Frechet_distance/include/CGAL/Frechet_distance.h @@ -87,20 +87,21 @@ namespace internal * \ingroup PkgFrechetDistanceFunctions * determines if the Frechet distance between two polylines is larger than a given distance bound. * - * \tparam Traits a model of `FrechetDistanceTraits` - * \tparam PointRange a model of the concept `RandomAccessContainer` with `Traits::Point_d` as value type + * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is a `Point_d` * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * - * \param polyline1 the first polyline defined by a sequence of consecutive points - * \param polyline2 the second polyline defined by a sequence of consecutive points + * \param polyline1 the first polyline, defined by a sequence of consecutive points + * \param polyline2 the second polyline, defined by a sequence of consecutive points * \param distance_bound the distance to compare against - * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: + * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" containing the one listed below: * * \cgalNamedParamsBegin * \cgalParamNBegin{geom_traits} * \cgalParamDescription{an instance of a geometric traits class} * \cgalParamType{a model of `FrechetDistanceTraits`} - * \cgalParamDefault{`Frechet_distance_traits_2`, `Frechet_distance_traits_3`, or`Frechet_distance_traits_d`, depending on the dimension of the point type.} + * \cgalParamDefault{`Frechet_distance_traits_2`, `Frechet_distance_traits_3`, or `Frechet_distance_traits_d`, depending on the dimension of the point type + * deduced from the point type, using `Kernel_traits`.} + * \cgalParamExtra{The input point type (the range's value type) must be equal to the traits' `Point_d` type. * \cgalParamNEnd * \cgalNamedParamsEnd * @@ -144,27 +145,28 @@ bool is_Frechet_distance_larger(const PointRange& polyline1, * returns an estimate of the Fréchet distance between the two polylines that is at most `error_bound` * away from the actual Fréchet distance between the two polylines. * - * \tparam Traits a model of `FrechetDistanceTraits` - * \tparam PointRange a model of the concept `RandomAccessContainer` with `Traits::Point_d` as value type. + * \tparam PointRange a model of the concept `RandomAccessContainer` whose value type is a `Point_d`. * \tparam NamedParameters a sequence of \ref bgl_namedparameters "Named Parameters" * - * \param polyline1 the first polyline defined by a sequence of consecutive points - * \param polyline2 the second polyline defined by a sequence of consecutive points + * \param polyline1 the first polyline, defined by a sequence of consecutive points + * \param polyline2 the second polyline, defined by a sequence of consecutive points * \param error_bound a maximum bound by which the Fréchet distance estimate is allowed to deviate from the actual Fréchet distance - * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below: + * \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" containing the one listed below: * * \cgalNamedParamsBegin * \cgalParamNBegin{geom_traits} * \cgalParamDescription{an instance of a geometric traits class} * \cgalParamType{a model of `FrechetDistanceTraits`} - * \cgalParamDefault{`Frechet_distance_traits_2`, `Frechet_distance_traits_3`, or`Frechet_distance_traits_d`, depending on the dimension of the point type.} + * \cgalParamDefault{`Frechet_distance_traits_2`, `Frechet_distance_traits_3`, or `Frechet_distance_traits_d`, depending on the dimension of the point type + * deduced from the point type, using `Kernel_traits`.} + * \cgalParamExtra{The input point type (the range's value type) must be equal to the traits' `Point_d` type. * \cgalParamNEnd * \cgalNamedParamsEnd * * \pre the polylines must not be empty * - * @return an interval enclosing the exact result, the difference between the upper and - * the lower bound being less than `error_bound`. + * @return an interval enclosing the exact Fréchet distance, the difference between the upper and + * the lower bound being smaller than `error_bound`. */ template std::pair bounded_error_Frechet_distance(const PointRange& polyline1, diff --git a/Frechet_distance/include/CGAL/Frechet_distance/Neighbor_search.h b/Frechet_distance/include/CGAL/Frechet_distance/Neighbor_search.h index 4f6fc781268..10c85499420 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance/Neighbor_search.h +++ b/Frechet_distance/include/CGAL/Frechet_distance/Neighbor_search.h @@ -28,7 +28,7 @@ namespace CGAL { namespace Frechet_distance { /*! - * A data structure to store curves with a function that enables to find those curves which are close to a query curve. + * A data structure to store curves with a function that enables to find those curves which are closer than a distance bound to a query curve. * * \tparam Traits a model of `FrechetDistanceTraits` * \tparam PointRange a model of the concept `RandomAccessContainer` with `Traits::Point_d` as value type. @@ -45,7 +45,13 @@ class Neighbor_search using PolylineIDs = std::vector; public: +#ifndef DOXYGEN_RUNNING Neighbor_search() = default; +#endif + +#ifdef DOXYGEN_RUNNING +using Point = Traits::Point_d; +#endif /*! inserts curves */ @@ -72,7 +78,12 @@ void Neighbor_search::insert( } template -auto Neighbor_search::get_close_curves( +#ifdef DOXYGEN_RUNNING +std::vector +#else +auto +#endif +Neighbor_search::get_close_curves( const Polyline& curve, double distance) -> PolylineIDs { auto result = kd_tree.search(curve, distance); diff --git a/Frechet_distance/include/CGAL/Frechet_distance_traits_2.h b/Frechet_distance/include/CGAL/Frechet_distance_traits_2.h index 8b49c376e16..4b4adfabf9f 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance_traits_2.h +++ b/Frechet_distance/include/CGAL/Frechet_distance_traits_2.h @@ -49,6 +49,10 @@ public: Construct_cartesian_const_iterator_d construct_cartesian_const_iterator_d_object() const { return Construct_cartesian_const_iterator_d(); } + + Compare_squared_distance_d construct_compare_squared_distance_d_object() const { + return Compare_squared_distance_d(); + } }; } // end of namespace CGAL diff --git a/Frechet_distance/include/CGAL/Frechet_distance_traits_3.h b/Frechet_distance/include/CGAL/Frechet_distance_traits_3.h index f7679ffa3df..7b54bbca0e9 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance_traits_3.h +++ b/Frechet_distance/include/CGAL/Frechet_distance_traits_3.h @@ -49,6 +49,10 @@ public: Construct_cartesian_const_iterator_d construct_cartesian_const_iterator_d_object() const { return Construct_cartesian_const_iterator_d(); } + + Compare_squared_distance_d construct_compare_squared_distance_d_object() const { + return Compare_squared_distance_d(); + } }; } // end of namespace CGAL diff --git a/Kernel_23/doc/Kernel_23/CGAL/Bbox_2.h b/Kernel_23/doc/Kernel_23/CGAL/Bbox_2.h index 600314c0330..4cb3c144a96 100644 --- a/Kernel_23/doc/Kernel_23/CGAL/Bbox_2.h +++ b/Kernel_23/doc/Kernel_23/CGAL/Bbox_2.h @@ -20,7 +20,7 @@ public: /// @{ /*! -introduces an \em empty bounding box with lower left +constructs an \em empty bounding box with lower left corner point at \f$ (\infty, \infty) \f$ and with upper right corner point at \f$ (-\infty, -\infty) \f$, \f$ \infty \f$ being @@ -28,7 +28,7 @@ and with upper right corner point at */ Bbox_2(); /*! -introduces a bounding box `b` with lower left corner at +constructs a bounding box `b` with lower left corner at `(xmin, ymin)` and with upper right corner at `(xmax, ymax)`. */ diff --git a/Kernel_23/doc/Kernel_23/CGAL/Bbox_3.h b/Kernel_23/doc/Kernel_23/CGAL/Bbox_3.h index 734f79bc76e..fb0de9bc83e 100644 --- a/Kernel_23/doc/Kernel_23/CGAL/Bbox_3.h +++ b/Kernel_23/doc/Kernel_23/CGAL/Bbox_3.h @@ -20,7 +20,7 @@ public: /// @{ /*! -introduces an \em empty bounding box with lower left +constructs an \em empty bounding box with lower left corner point at \f$ (\infty, \infty, \infty) \f$ and with upper right corner point at \f$ (-\infty, -\infty, -\infty) \f$, \f$ \infty \f$ being @@ -29,7 +29,7 @@ and with upper right corner point at Bbox_3(); /*! -introduces a bounding box `b` with lexicographically +constructs a bounding box `b` with lexicographically smallest corner point at `(xmin, ymin, zmin)` and lexicographically largest corner point at `(xmax, ymax, zmax)`. diff --git a/Kernel_d/doc/Kernel_d/CGAL/Bbox_d.h b/Kernel_d/doc/Kernel_d/CGAL/Bbox_d.h index 48fc24932ce..5d7c3843a63 100644 --- a/Kernel_d/doc/Kernel_d/CGAL/Bbox_d.h +++ b/Kernel_d/doc/Kernel_d/CGAL/Bbox_d.h @@ -4,8 +4,9 @@ namespace CGAL { /*! \ingroup PkgKernelDKernelObjs -An object `b` of the class `Bbox_d` is a bounding -box in the d-dimensional Euclidean plane \f$ \E^d\f$. This class is templated with a dimension tag. +An object `b` of the class `Bbox_d` is a bounding box in the d-dimensional Euclidean space \f$ \E^d\f$. + +\tparam DimensionTag must be an instance of `CGAL::Dimension_tag`. \cgalModels{Hashable} @@ -18,11 +19,19 @@ template class Bbox_d { public: + +/// \name Types +/// @{ +/// An iterator for enumerating the %Cartesian coordinates of the point with the lexicographically +//// smallest coordinates followed by those of the point with the lexicographically largest coordinates. +typedef unspecified_type Cartesian_const_iterator; +/// @} + /// \name Creation /// @{ /*! -introduces an \em empty bounding box with lower left +constructs an \em empty bounding box with lower left corner coordinates at \f$ \infty \f$ and with upper right corner coordinates at \f$ -\infty \f$, \f$ \infty \f$ being @@ -31,21 +40,21 @@ and with upper right corner coordinates at Bbox_d(); /*! -introduces a d-dimensional bounding box from a 2d bounding box. +constructs a d-dimensional bounding box from a 2D bounding box. \pre the dimension must be 2D */ Bbox_d(const Bbox_2& b); /*! -introduces a d-dimensional bounding box from a range. +constructs a d-dimensional bounding box from a range of coordinates \pre the range must have the size of the dimension. -\tparam I an iterator model of `InputIterator` with value type double +\tparam InputIterator an input iterator with value type `double` */ -template -Bbox_d(int d, I b, I e); +template +Bbox_d(int d, InputIterator b, InputIterator e); /*! -introduces a d-dimensional bounding box from a 3d bounding box. +constructs a d-dimensional bounding box from a 3D bounding box. \pre the dimension must be 3D */ Bbox_d(const Bbox_3& b); @@ -56,7 +65,7 @@ Bbox_d(const Bbox_3& b); /// @{ /*! -ests for equality. +tests for equality. */ bool operator==(const Bbox_d &c) const; @@ -72,15 +81,26 @@ int dimension() const; /*! -returns an iterator for the %Cartesian coordinates of the lower left and the upper right corner. +returns the `i`-th %Cartesian coordinate of the "lower left" corner. +*/ +double min(int i) const; + + +/*! +returns the `i`-th %Cartesian coordinate of the "upper right" corner. +*/ +double max(int i) const; + +/*! +returns an iterator for the %Cartesian coordinates of the "lower left" and the "upper right" corner. */ Cartesian_const_iterator cartesian_begin() const; /*! -returns the past-the-end iterator for the %Cartesian coordinates of the lower left and the upper right corner. +returns the past-the-end iterator for the %Cartesian coordinates of the "lower left" and the "upper right" corner. */ -Cartesian_const_iterator cartesian_begin() const; +Cartesian_const_iterator cartesian_end() const; /*! returns a bounding box of `b` and `c`. @@ -117,7 +137,7 @@ intersection is non-empty. \relates Bbox_d */ template -bool do_overlap(const Bbox_d &bb1, const Bbox_d &bb2); +bool do_overlap(const Bbox_d &bb1, const Bbox_d &bb2); /// @}