New package: Frechet Distance

Documentation/doc/Documentation/packages.txt

@@ -39,6 +39,7 @@
 \package_listing{Straight_skeleton_2}
 \package_listing{Minkowski_sum_2}
 \package_listing{Polyline_simplification_2}
+\package_listing{Frechet_distance}
 \package_listing{Visibility_2}
 \package_listing{Set_movable_separability_2}
 

Documentation/doc/scripts/generate_how_to_cite.py

@@ -222,6 +222,7 @@ def protect_accentuated_letters(authors):
         .replace("É", r"{\'E}")
         .replace("ä", r"{\"a}")
         .replace("ö", r"{\"o}")
+        .replace("ü", r"{\"u}")
         .replace("ñ", r"{\~n}")
         .replace("ã", r"{\~a}")
         .replace("ë", r"{\"e}")

Filtered_kernel/include/CGAL/Lazy.h

@@ -25,6 +25,7 @@
 #include <CGAL/Origin.h>
 #include <CGAL/Bbox_2.h>
 #include <CGAL/Bbox_3.h>
+#include <CGAL/Bbox.h>
 #include <CGAL/Default.h>
 #include <CGAL/tss.h>
 #include <CGAL/type_traits/is_iterator.h>
@@ -97,6 +98,10 @@ CGAL_LAZY_FORWARD(Bbox_2)
 CGAL_LAZY_FORWARD(Bbox_3)
 #undef CGAL_LAZY_FORWARD
 
+template<class A, class B> Bbox<A,B> const& approx(Bbox<A,B> const& d) { return d; }
+template<class A, class B> Bbox<A,B> const& exact (Bbox<A,B> const& d) { return d; }
+template<class A, class B> int              depth (Bbox<A,B> const&  ) { return 0; }
+
 template<class T>inline std::enable_if_t<std::is_arithmetic<T>::value||std::is_enum<T>::value, T> approx(T d){return d;}
 template<class T>inline std::enable_if_t<std::is_arithmetic<T>::value||std::is_enum<T>::value, T> exact (T d){return d;}
 template<class T>inline std::enable_if_t<std::is_arithmetic<T>::value||std::is_enum<T>::value, int> depth(T){return -1;}

Frechet_distance/doc/Frechet_distance/Concepts/FrechetDistanceTraits.h

@@ -0,0 +1,87 @@
+/*!
+\ingroup PkgFrechetDistanceConcepts
+\cgalConcept
+
+The concept `FrechetDistanceTraits` defines the requirements of the
+first template parameter of the functions `CGAL::is_Frechet_distance_larger()`
+and `CGAL::approximate_Frechet_distance()`.
+
+
+\cgalHasModelsBegin
+\cgalHasModels{CGAL::Frechet_distance_traits_2}
+\cgalHasModels{CGAL::Frechet_distance_traits_3}
+\cgalHasModels{CGAL::Frechet_distance_traits_d}
+\cgalHasModelsEnd
+*/
+
+class FrechetDistanceTraits {
+
+    public:
+/*!  a fixed dimension >= 2 */
+    const int dimension;
+
+/*!  a fixed dimension >= 2 */
+    static constexpr bool is_filtered;
+    /*!  a fixed dimension >= 2 */
+    static constexpr bool  is_floating_point;
+/// \name Types
+/// @{
+
+/*! The kernel type. If this type has a nested type `Has_filtered_predicates_tag`  with `value == true`,
+    it must have a nested type `Exact_kernel`, and a nested type `C2E` with an  `operator()` that converts
+    a point of `Kernel` to a point of `Exact_kernel`. Otherwise, it must have a nested type `FT` for
+    which an overload of `to_double()` exists.
+*/
+using Kernel = unspecified;
+
+/*! The point type of `Kernel` corresponding to `dimension`
+*/
+using Point = unspecified_type;
+
+/*! The number type of the filtered kernel. If
+*/
+using distance_t = Filtered_kernel::FT;
+
+/*! The filtered kernel
+*/
+using Filtered_kernel = unspecified_type;
+
+
+/*! The point type of the filtered kernel corresponding to `dimension`.
+*/
+using Filtered_point = unspecified_type;
+
+/*! A functor of the filtered kernel for filtered points
+*/
+using Construct_bbox = unspecified_type;
+
+/*! A functor of the filtered kernel for two filtered points
+*/
+using Squared_distance = unspecified_type;
+
+
+/*! A functor of the filtered kernel for two filtered points
+*/
+using Difference_of_points = unspecified_type;
+
+
+/*! A functor of the filtered kernel the return type of `Difference_of_points`
+*/
+using Scaled_vector = unspecified_type;
+
+
+/*! A functor of the filtered kernel the return type of `Scaled_vector`
+*/
+using Translated_point = unspecified_type;
+
+/*! The exact kernel
+*/
+using Exact_kernel = unspecified_type;
+
+/*! The point type of the exact kernel corresponding to `dimension`.
+The  point type must have `operator[]` returning a number type which can be used as first template parameter of `Sqrt_extension`.
+*/
+using Exact_point = unspecified_type;
+
+/// @}
+};

Frechet_distance/doc/Frechet_distance/Doxyfile.in

@@ -0,0 +1,3 @@
+@INCLUDE = ${CGAL_DOC_PACKAGE_DEFAULTS}
+
+PROJECT_NAME = "CGAL ${CGAL_DOC_VERSION} - dD Polyline Distance"

Frechet_distance/doc/Frechet_distance/Frechet_distance.txt

@@ -0,0 +1,84 @@
+namespace CGAL {
+/*!
+
+\mainpage User Manual
+\anchor Chapter_dD_Frechet_distance
+
+\cgalAutoToc
+\authors André Nusser, Marvin Künnemann, and Karl Bringmann
+
+
+<center>
+<img src="FrechetTeaser.png" style="max-width:30%;"/>
+</center>
+
+This package provides functions for computing the Fréchet distance of polylines in any dimension under the Euclidean metric.
+
+\section secFrechetDistanceIntroduction Introdution
+
+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.
+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.
+
+
+<!--
+\cgalFigureBegin{figRefId,pdist-pkg-small.png}
+Here you can put the caption
+\cgalFigureEnd
+-->
+
+The Fréchet distance is a metric. This implies that two polylines have distance zero if and only if they are equal (after removing redundant vertices).
+
+\section secFrechetDistanceAPI API
+
+The package provides one function to approximate the Fréchet distance and one function to decide whether the Fréchet distance is at most a given value.
+
+The function `approximate_Frechet_distance()` computes an approximation of the Fréchet distance between two polylines, up to a given approximation error. It returns an interval that contains the true distance.
+The function `is_Frechet_distance_larger()` decides if the Fréchet distance
+between two polylines is larger than a given bound.
+
+Both functions have as template parameter a traits class defining the dimension and the point type.
+The traits classes have as template parameter a kernel. This may be a kernel such as `Simple_cartesian`
+with a floating point number type, or a filtered kernel such as `Exact_predicates_inexact_constructions_kernel`.
+In both cases the result is guaranteed to be correct.
+
+
+\section secFrechetDistanceImplementation Implementation
+
+Internally all computations are done using interval arithmetic. In case of filter failures
+the algorithm switches to the usage of square root extensions.
+
+The algorithms in this package are an adaption of the implementation of a <a href="https://doi.org/10.4230/LIPIcs.SoCG.2019.17">SoCG</a>/<a href="https://doi.org/10.20382/jocg.v12i1a4">JoCG</a> paper. In particular, the implementation can decide non-difficult cases very fast while for difficult cases it still has the quadratic running time guarantee of the classical Fréchet distance algorithm by Alt and Godau. This is achieved by using fast filtering methods and a divide and conquer algorithm with pruning rules on the free-space diagram.
+
+
+\section secFrechetDistanceExamples Examples
+
+In the examples we use different kernels to illustrate that the functions
+work as well for inexact or exact kernels.
+
+\subsection subsecFrechetDistanceFirstExample Decision for 2D Polylines
+
+The following example shows how we can use `is_Frechet_distance_larger()` to decide whether the Fréchet distance between two polylines in the Euclidean plane is at most a given value.
+
+\cgalExample{Frechet_distance/Frechet_distance_2.cpp}
+
+\subsection subsecFrechetDistanceSecondExample Distance Computation for 3D Polylines
+
+The following example shows how we can compute the Fréchet distance up to a given precision on two polylines in 3-dimensional Euclidean space using `approximate_Frechet_distance()`.
+
+\cgalExample{Frechet_distance/Frechet_distance_3.cpp}
+
+
+\subsection subsecFrechetDistanceImageCredits  Image Credits
+
+The teaser image is a visualization of two data points from the <a href="https://archive.ics.uci.edu/dataset/175/character+trajectories">Character Trajectories</a> data set.
+
+\subsection subsecFrechetDistanceImplementation  Implementation History
+
+An initial version using floating point arithmetic was developed by the authors
+while working at the Max Planck Institute for Informatics in Saarbrücken, Germany.
+André Nusser, together with Sebastien Loriot and Andreas Fabri, introduced
+the usage of interval arithmetic and square root extensions to alleviate issues stemming from rounding errors and hence ensuring correctness of the computation.
+
+*/
+} /* namespace CGAL */

Frechet_distance/doc/Frechet_distance/PackageDescription.txt

@@ -0,0 +1,44 @@
+/// \defgroup PkgFrechetDistanceRef dD Frechet Distance Reference
+/// \defgroup PkgFrechetDistanceConcepts Concepts
+/// \ingroup PkgFrechetDistanceRef
+/// \defgroup PkgFrechetDistanceFunctions Functions
+/// You can add some text here if you want a description at the group level
+/// \ingroup PkgFrechetDistanceRef
+
+
+/*!
+\addtogroup PkgFrechetDistanceRef
+
+\cgalPkgDescriptionBegin{dD Frechet Distance,PkgFrechetDistance}
+\cgalPkgPicture{pdist-pkg-small.png}
+
+\cgalPkgSummaryBegin
+\cgalPkgAuthors{André Nusser, Marvin Künnemann, and Karl Bringmann}
+\cgalPkgDesc{This package provides functions for computing the Fréchet distance of polylines in any dimension under the Euclidean metric.}
+\cgalPkgManuals{Chapter_dD_Frechet_distance,PkgFrechetDistanceRef}
+\cgalPkgSummaryEnd
+
+\cgalPkgShortInfoBegin
+\cgalPkgSince{6.1}
+\cgalPkgBib{cgal:nkb-fd}
+\cgalPkgLicense{\ref licensesGPL "GPL"}
+\cgalPkgShortInfoEnd
+
+\cgalPkgDescriptionEnd
+
+This package provides functions for computing the Fréchet distance of polylines in any dimension under the Euclidean metric.
+
+\cgalClassifedRefPages
+
+\cgalCRPSection{Concepts}
+- `FrechetDistanceTraits`
+
+\cgalCRPSection{Classes}
+- `CGAL::Frechet_distance_traits_2`
+- `CGAL::Frechet_distance_traits_3`
+- `CGAL::Frechet_distance_traits_d`
+
+\cgalCRPSection{Functions}
+- `CGAL::approximate_Frechet_distance()`
+- `CGAL::is_Frechet_distance_larger()`
+*/

Frechet_distance/doc/Frechet_distance/dependencies

@@ -0,0 +1,6 @@
+Manual
+Kernel_23
+STL_Extension
+Algebraic_foundations
+Circulator
+Stream_support

Frechet_distance/doc/Frechet_distance/examples.txt

@@ -0,0 +1,4 @@
+/*!
+\example Frechet_distance/Frechet_distance_2.cpp
+\example Frechet_distance/Frechet_distance_3.cpp
+*/

Frechet_distance/examples/Frechet_distance/CMakeLists.txt

@@ -0,0 +1,22 @@
+# Created by the script cgal_create_cmake_script
+# This is the CMake script for compiling a CGAL application.
+
+cmake_minimum_required(VERSION 3.1...3.14)
+project( Frechet_distance_Examples )
+
+find_package(CGAL REQUIRED QUIET OPTIONAL_COMPONENTS Core )
+
+
+find_package(Eigen3 3.1.0 QUIET) #(requires 3.1.0 or greater)
+include(CGAL_Eigen3_support)
+
+create_single_source_cgal_program( "Frechet_distance_2.cpp" )
+create_single_source_cgal_program( "Frechet_distance_3.cpp" )
+create_single_source_cgal_program( "Has_filtered_predicates.cpp" )
+
+if(TARGET CGAL::Eigen3_support)
+create_single_source_cgal_program( "Frechet_distance_d.cpp" )
+target_link_libraries(Frechet_distance_d PUBLIC CGAL::Eigen3_support)
+target_link_libraries(Frechet_distance_2 PUBLIC CGAL::Eigen3_support)
+target_link_libraries(Frechet_distance_3 PUBLIC CGAL::Eigen3_support)
+endif()

Frechet_distance/examples/Frechet_distance/Frechet_distance_2.cpp

@@ -0,0 +1,17 @@
+#include <CGAL/Frechet_distance.h>
+#include <CGAL/Frechet_distance_traits_2.h>
+#include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
+
+#include <ostream>
+
+using Kernel = CGAL::Exact_predicates_inexact_constructions_kernel;
+using Traits = CGAL::Frechet_distance_traits_2<Kernel>;
+using Point = Traits::Point;
+
+int main(int argc, char* argv[])
+{
+    std::vector<Point> A, B;
+    bool res = CGAL::is_Frechet_distance_larger<Traits>(A, B, 0.001);
+    std::cout << std::boolalpha << res << std::endl;
+    return 0;
+}

Frechet_distance/examples/Frechet_distance/Frechet_distance_3.cpp

@@ -0,0 +1,17 @@
+#include <CGAL/Frechet_distance.h>
+#include <CGAL/Frechet_distance_traits_3.h>
+#include <CGAL/Simple_cartesian.h>
+
+#include <ostream>
+
+using Kernel = CGAL::Simple_cartesian<double>;
+using Traits = CGAL::Frechet_distance_traits_3<Kernel>;
+using Point = Traits::Point;
+
+int main(int argc, char* argv[])
+{
+    std::vector<Point> A, B;
+    std::pair<double, double> res = CGAL::approximate_Frechet_distance<Traits>(A, B, 0.000001);
+    std::cout << "The Frechet distance between the polylines is between " <<  res.first << " and " << res.second << std::endl;
+    return 0;
+}

Frechet_distance/examples/Frechet_distance/Frechet_distance_d.cpp

@@ -0,0 +1,17 @@
+#include <CGAL/Frechet_distance.h>
+#include <CGAL/Frechet_distance_traits_d.h>
+#include <CGAL/Epick_d.h>
+
+#include <iostream>
+#include <vector>
+
+using Kernel = CGAL::Epick_d<CGAL::Dimension_tag<4>>;
+using Traits = CGAL::Frechet_distance_traits_d<Kernel>;
+using Point = Traits::Point;
+
+int main(int argc, char* argv[])
+{
+    std::vector<Point> A, B;
+    bool res = CGAL::is_Frechet_distance_larger<Traits>(A, B, 0.001);
+    return 0;
+}