From c50619822ac1fc1e74827e5e652bf3435e7476a8 Mon Sep 17 00:00:00 2001 From: Andreas Fabri Date: Tue, 18 Jun 2024 09:22:29 +0100 Subject: [PATCH] User Manual, rename tags, add example --- .../Concepts/FrechetDistanceTraits.h | 2 +- .../doc/Frechet_distance/Frechet_distance.txt | 57 ++++++++++++++----- .../Frechet_distance/PackageDescription.txt | 16 +++--- .../Frechet_distance/Frechet_distance_3.cpp | 17 ++++++ .../include/CGAL/Frechet_distance.h | 4 +- .../CGAL/Frechet_distance/internal/curve.h | 2 +- .../CGAL/Frechet_distance/internal/filter.h | 2 +- .../Frechet_distance/internal/frechet_light.h | 2 +- .../internal/frechet_light_types.h | 12 ++-- .../internal/geometry_basics.h | 8 +-- .../internal/high_level_predicates.h | 2 +- .../include/CGAL/Frechet_distance_traits_2.h | 2 +- .../include/CGAL/Frechet_distance_traits_3.h | 2 +- .../include/CGAL/Frechet_distance_traits_d.h | 2 +- 14 files changed, 88 insertions(+), 42 deletions(-) create mode 100644 Frechet_distance/examples/Frechet_distance/Frechet_distance_3.cpp diff --git a/Frechet_distance/doc/Frechet_distance/Concepts/FrechetDistanceTraits.h b/Frechet_distance/doc/Frechet_distance/Concepts/FrechetDistanceTraits.h index b9fedba545c..681e9259353 100644 --- a/Frechet_distance/doc/Frechet_distance/Concepts/FrechetDistanceTraits.h +++ b/Frechet_distance/doc/Frechet_distance/Concepts/FrechetDistanceTraits.h @@ -1,5 +1,5 @@ /*! -\ingroup PkgPolylineDistanceConcepts +\ingroup PkgFrechetDistanceConcepts \cgalConcept The concept `FrechetDistanceTraits` defines the requirements ... diff --git a/Frechet_distance/doc/Frechet_distance/Frechet_distance.txt b/Frechet_distance/doc/Frechet_distance/Frechet_distance.txt index 9b7f960b3c9..328d48313af 100644 --- a/Frechet_distance/doc/Frechet_distance/Frechet_distance.txt +++ b/Frechet_distance/doc/Frechet_distance/Frechet_distance.txt @@ -5,32 +5,61 @@ namespace CGAL { \anchor Chapter_dD_Frechet_distance \cgalAutoToc -\author André Nusser, Marvin Künnemann, and Karl Bringmann +\authors André Nusser, Marvin Künnemann, and Karl Bringmann -This chapter describes the ... -\section secPolylineDistanceDefinitions Definitions +
+ +
-Section on definitions here ... +This chapter provides functions for computing the Fréchet distance of polylines in any dimension under Euclidean metric. -\section secPolylineDistanceExamples Examples +\section secFrechetDistanceIntroduction Introdution -\subsection subsecPolylineDistanceFirstExample First Example - -The following example shows ... - -\cgalExample{Frechet_distance/Frechet_distance_2.cpp} +The Fréchet distance ..... \cgalFigureBegin{figRefId,pdist-pkg-small.png} Here you can put the caption \cgalFigureEnd +\section secFrechetDistanceAPI API -\subsection subsecPolylineDistanceImplementation Implementation History +The function `continuous_Frechet_distance()` computes an approximation of the Fréchet distance between two polylines, +up to a given approximation error. It returns an interval. +The function `continuous_Frechet_distance_less_than()` decides if the Fréchet distance +between two polylines is smaller than a given bound. -An intial version using floating point arithmetic was developed by the authors. -André Nusser, together with Sebastien Loriot and Andreas Fabri introduced -interval arithmetic and square root extensions to achieve a certified result. +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. 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. + +\section secFrechetDistanceExamples Examples + +\subsection subsecFrechetDistanceFirstExample Decision for 2D Polylines + +The following example shows ... + +\cgalExample{Frechet_distance/Frechet_distance_2.cpp} + +subsection subsecFrechetDistanceSecondExample Distance Computation for 3D Polylines + +The following example shows ... + +\cgalExample{Frechet_distance/Frechet_distance_3.cpp} + + +\subsection subsecFrechetDistanceImplementation Implementation History + +An intial version using floating point arithmetic was developed by the authors +while working at the Max-Planck Institute of Computer Science in Saarbrücken. +André Nusser, together with Sebastien Loriot and Andreas Fabri, introduced +the usage of interval arithmetic and square root extensions to achieve a certified result. */ } /* namespace CGAL */ diff --git a/Frechet_distance/doc/Frechet_distance/PackageDescription.txt b/Frechet_distance/doc/Frechet_distance/PackageDescription.txt index f6946c7ec76..ad6e378bb29 100644 --- a/Frechet_distance/doc/Frechet_distance/PackageDescription.txt +++ b/Frechet_distance/doc/Frechet_distance/PackageDescription.txt @@ -1,21 +1,21 @@ -/// \defgroup PkgPolylineDistanceRef dD Polyline Distance Reference -/// \defgroup PkgPolylineDistanceConcepts Concepts -/// \ingroup PkgPolylineDistanceRef -/// \defgroup PkgPolylineDistanceFunctions Functions +/// \defgroup PkgFrechetDistanceRef dD Polyline 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 PkgPolylineDistanceRef +/// \ingroup PkgFrechetDistanceRef /*! -\addtogroup PkgPolylineDistanceRef +\addtogroup PkgFrechetDistanceRef -\cgalPkgDescriptionBegin{dD Polyline Distance,PkgPolylineDistance} +\cgalPkgDescriptionBegin{dD Polyline Distance,PkgFrechetDistance} \cgalPkgPicture{pdist-pkg-small.png} \cgalPkgSummaryBegin \cgalPkgAuthors{André Nusser, Marvin Künnemann, and Karl Bringmann} \cgalPkgDesc{The package provides ... } -\cgalPkgManuals{Chapter_dD_Frechet_distance,PkgPolylineDistanceRef} +\cgalPkgManuals{Chapter_dD_Frechet_distance,PkgFrechetDistanceRef} \cgalPkgSummaryEnd \cgalPkgShortInfoBegin diff --git a/Frechet_distance/examples/Frechet_distance/Frechet_distance_3.cpp b/Frechet_distance/examples/Frechet_distance/Frechet_distance_3.cpp new file mode 100644 index 00000000000..ccf8e58ab13 --- /dev/null +++ b/Frechet_distance/examples/Frechet_distance/Frechet_distance_3.cpp @@ -0,0 +1,17 @@ +#include +#include +#include + +#include + +using Kernel = CGAL::Simple_cartesian; +using Point = Traits::Point; + +int main(int argc, char* argv[]) +{ + std::vector A, B; + std::pair res = CGAL::continuous_Frechet_distance(A, B, 0.000001); + std::cout << "The Frechet distance between the curves is between " << res.first << " and " << res.second << std::endl; + return 0; +} diff --git a/Frechet_distance/include/CGAL/Frechet_distance.h b/Frechet_distance/include/CGAL/Frechet_distance.h index a15e12122d2..0683cd7fc3e 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance.h +++ b/Frechet_distance/include/CGAL/Frechet_distance.h @@ -35,7 +35,7 @@ namespace CGAL { /** - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * decides if the Frechet distance between two polylines given as a range of * points is less than a given distance. * \param curve1 the first curve defined @@ -63,7 +63,7 @@ bool continuous_Frechet_distance_less_than(const PointRange& curve1, } /** - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * approximates the Fréchet distance between `curve1` and `curve2` up to an additive error * of `precision` between two polylines given as a range of points. * diff --git a/Frechet_distance/include/CGAL/Frechet_distance/internal/curve.h b/Frechet_distance/include/CGAL/Frechet_distance/internal/curve.h index 6a9bb6d8435..cfde7c4017b 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance/internal/curve.h +++ b/Frechet_distance/include/CGAL/Frechet_distance/internal/curve.h @@ -55,7 +55,7 @@ double length_of_diagonal(const Bbox_3& bb) // TODO: Clean up Curve /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a trajectory. Additionally to the points given in the * input file, we also store the length of any prefix of the trajectory. */ diff --git a/Frechet_distance/include/CGAL/Frechet_distance/internal/filter.h b/Frechet_distance/include/CGAL/Frechet_distance/internal/filter.h index 3987db0e55d..8f761537c8d 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance/internal/filter.h +++ b/Frechet_distance/include/CGAL/Frechet_distance/internal/filter.h @@ -36,7 +36,7 @@ namespace internal { // decisions /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ template diff --git a/Frechet_distance/include/CGAL/Frechet_distance/internal/frechet_light.h b/Frechet_distance/include/CGAL/Frechet_distance/internal/frechet_light.h index 5a6e5bf6848..b0dd2a424b3 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance/internal/frechet_light.h +++ b/Frechet_distance/include/CGAL/Frechet_distance/internal/frechet_light.h @@ -43,7 +43,7 @@ namespace internal { /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ template diff --git a/Frechet_distance/include/CGAL/Frechet_distance/internal/frechet_light_types.h b/Frechet_distance/include/CGAL/Frechet_distance/internal/frechet_light_types.h index 0a9ad9c0f5d..f1fd3e1407b 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance/internal/frechet_light_types.h +++ b/Frechet_distance/include/CGAL/Frechet_distance/internal/frechet_light_types.h @@ -39,7 +39,7 @@ namespace internal { // /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ template @@ -66,7 +66,7 @@ using Boxes = std::vector>; // /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ template @@ -105,7 +105,7 @@ struct Inputs { // /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ @@ -120,7 +120,7 @@ struct Outputs { // /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ template @@ -185,7 +185,7 @@ using QSimpleID = ID>; // /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ @@ -200,7 +200,7 @@ struct QSimpleOutputs { // /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ template diff --git a/Frechet_distance/include/CGAL/Frechet_distance/internal/geometry_basics.h b/Frechet_distance/include/CGAL/Frechet_distance/internal/geometry_basics.h index 2ba88a00bb2..c8ce011e7da 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance/internal/geometry_basics.h +++ b/Frechet_distance/include/CGAL/Frechet_distance/internal/geometry_basics.h @@ -48,7 +48,7 @@ namespace internal { /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a value in the interval `[0,1]`.... */ template @@ -287,7 +287,7 @@ BFDirection toBFDirection(Direction direction); // TODO: does CGAL have any replacement for this or do we want our custom type // here? /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ @@ -325,7 +325,7 @@ template std::ostream& operator<<(std::ostream& out, const Interval& interval); /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * Data Types for FrechetLight: * * CPoint is integral part + rational [0,1] number given as sqrt_extension @@ -461,7 +461,7 @@ using CPositions = std::vector>; using CurveID = std::size_t; /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * A class representing a */ template diff --git a/Frechet_distance/include/CGAL/Frechet_distance/internal/high_level_predicates.h b/Frechet_distance/include/CGAL/Frechet_distance/internal/high_level_predicates.h index 5042b317c08..ee02b4c2def 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance/internal/high_level_predicates.h +++ b/Frechet_distance/include/CGAL/Frechet_distance/internal/high_level_predicates.h @@ -136,7 +136,7 @@ namespace HLPred { /*! - * \ingroup PkgPolylineDistanceFunctions + * \ingroup PkgFrechetDistanceFunctions * computes */ template diff --git a/Frechet_distance/include/CGAL/Frechet_distance_traits_2.h b/Frechet_distance/include/CGAL/Frechet_distance_traits_2.h index f242c9a3181..78430711ebe 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance_traits_2.h +++ b/Frechet_distance/include/CGAL/Frechet_distance_traits_2.h @@ -35,7 +35,7 @@ namespace CGAL { /*! - * \ingroup PkgPolylineDistanceRef + * \ingroup PkgFrechetDistanceRef * This class ... * \cgalModels{FrechetDistanceTraits} * \tparam GT geometric traits class diff --git a/Frechet_distance/include/CGAL/Frechet_distance_traits_3.h b/Frechet_distance/include/CGAL/Frechet_distance_traits_3.h index fa5a5600098..ffae351b8a6 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance_traits_3.h +++ b/Frechet_distance/include/CGAL/Frechet_distance_traits_3.h @@ -39,7 +39,7 @@ namespace CGAL { /*! - * \ingroup PkgPolylineDistanceRef + * \ingroup PkgFrechetDistanceRef * This class ... * \cgalModels{FrechetDistanceTraits} * \tparam GT geometric traits class diff --git a/Frechet_distance/include/CGAL/Frechet_distance_traits_d.h b/Frechet_distance/include/CGAL/Frechet_distance_traits_d.h index 25f4262adde..6899b884c5e 100644 --- a/Frechet_distance/include/CGAL/Frechet_distance_traits_d.h +++ b/Frechet_distance/include/CGAL/Frechet_distance_traits_d.h @@ -37,7 +37,7 @@ namespace CGAL { /*! - * \ingroup PkgPolylineDistanceRef + * \ingroup PkgFrechetDistanceRef * This class ... * \cgalModels{FrechetDistanceTraits} * \tparam GT geometric traits class