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,38 @@
+/*!
+\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:
+/*!  2 or 3 */
+    const int dimension;
+
+/// \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;
+
+/// @}
+};

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;
+}

Frechet_distance/include/CGAL/Frechet_distance.h

@@ -0,0 +1,87 @@
+// Copyright (c) 2024 Max-Planck-Institute Saarbruecken (Germany), GeometryFactory (France)
+// All rights reserved.
+//
+// This file is part of CGAL (www.cgal.org).
+//
+// $URL$
+// $Id$
+// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-Commercial
+//
+// Author(s)     : André Nusser <[email protected]>
+//                 Marvin Künnemann <[email protected]>
+//                 Karl Bringmann <[email protected]>
+//                 Andreas Fabri
+// =============================================================================
+
+#ifndef CGAL_FRECHET_DISTANCE_H
+#define CGAL_FRECHET_DISTANCE_H
+
+#include <CGAL/license/Frechet_distance.h>
+#include <CGAL/basic.h>
+#include <CGAL/Frechet_distance/internal/Frechet_distance.h>
+
+#include <iterator>
+
+namespace CGAL
+{
+
+/**
+ * \ingroup PkgFrechetDistanceFunctions
+ * decides if the Frechet distance between two polylines is larger than a given distance.
+ *
+ * \param polyline1 the first polyline defined by the sequence of consecutive points
+ * \param polyline2 the second polyline defined by the sequence of consecutive points
+ * \param distance the decision distance
+ * \param traits the geometric traits object
+ *
+ * \tparam Traits a model of `FrechetDistanceTraits`
+ * \tparam PointRange  a model of the concept `RandomAccessContainer`
+ * with `Traits::Point` as value type.
+ */
+template < class Traits, class PointRange>
+bool is_Frechet_distance_larger(const PointRange& polyline1,
+                              const PointRange& polyline2,
+                              const double distance,
+                              const Traits& traits = Traits())
+{
+    Protect_FPU_rounding<true> p;
+    auto icurve1 = Frechet_distance_::internal::toCurve(polyline1, traits);
+    auto icurve2 = Frechet_distance_::internal::toCurve(polyline2, traits);
+    auto idistance = Frechet_distance_::internal::toDistance(distance);
+
+    return ! Frechet_distance_::internal::lessThan(icurve1, icurve2, idistance, traits);
+}
+
+/**
+ * \ingroup PkgFrechetDistanceFunctions
+ * approximates the Fréchet distance between two polylines up to an additive error
+ * of `precision`.
+ *
+ * \param polyline1 the first polyline defined by the sequence of consecutive points
+ * \param polyline2 the second polyline defined by the sequence of consecutive points
+ * \param precision the precision of the approximation
+ *  \param traits the geometric traits object
+ *
+ * \tparam Traits a model of `FrechetDistanceTraits`
+ * \tparam PointRange  a model of the concept `RandomAccessContainer`
+ * with `Traits::Point` as value type.
+ *
+ * @return an interval enclosing the exact result, the difference between the upper and
+ * the lower bound being less than `precision`.
+ */
+template <class Traits,class PointRange>
+std::pair<double,double> approximate_Frechet_distance(const PointRange& polyline1,
+                                                      const PointRange& polyline2,
+                                                      const double precision,
+                                                      const Traits& traits = Traits())
+{
+    Protect_FPU_rounding<true> p;
+    auto icurve1 = Frechet_distance_::internal::toCurve(polyline1, traits);
+    auto icurve2 = Frechet_distance_::internal::toCurve(polyline2, traits);
+
+    return Frechet_distance_::internal::calcDistance<Traits>(icurve1, icurve2, precision);
+}
+
+}  // end of namespace CGAL
+
+#endif  // CGAL_FRECHET_DISTANCE_H