diff --git a/Weights/doc/Weights/PackageDescription.txt b/Weights/doc/Weights/PackageDescription.txt index c645803daf1..e68abe5afb6 100644 --- a/Weights/doc/Weights/PackageDescription.txt +++ b/Weights/doc/Weights/PackageDescription.txt @@ -96,7 +96,7 @@ being the power parameter. Here, `q` is a query point and the points `p0`, `p1`, and `p2` are ordered. -This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Flattening) +This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Coplanarity) while alternative formulations are explained in \ref Weights_Implementation. \cgalFigureBegin{three_point_family_weight, three_point_family.svg} @@ -133,7 +133,7 @@ with notations shown in the figure below. Here, `q` is a query point and the points `p0`, `p1`, and `p2` are ordered. -This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Flattening) +This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Coplanarity) while alternative formulations are explained in \ref Weights_Implementation. \cgalFigureBegin{wachspress_weight, wachspress.svg} @@ -198,7 +198,7 @@ The \f$\pm\f$ sign is a sign of the weight that depends on the configuration. Here, `q` is a query point and the points `p0`, `p1`, and `p2` are ordered. -This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Flattening) +This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Coplanarity) while alternative formulations are explained in \ref Weights_Implementation. \cgalFigureBegin{mean_value_weight, mean_value.svg} @@ -262,7 +262,7 @@ with notations shown in the figure below. Here, `q` is a query point and the points `p0`, `p1`, and `p2` are ordered. -This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Flattening) +This weight supports only planar configurations (see more in section about \ref Weights_Implementation_Coplanarity) while alternative formulations are explained in \ref Weights_Implementation. \cgalFigureBegin{discrete_harmonic_weight, discrete_harmonic.svg} diff --git a/Weights/doc/Weights/Weights.txt b/Weights/doc/Weights/Weights.txt index 3e968a7967c..104d2b22adb 100644 --- a/Weights/doc/Weights/Weights.txt +++ b/Weights/doc/Weights/Weights.txt @@ -93,40 +93,25 @@ The parameter `traits` with a traits class can be omitted for all functions and if it can be deduced from the input point type. Several weights in this package have different implementations. One reason to have it is -explained in section about \ref Weights_Implementation_Flattening. Another reason is that +explained in section about \ref Weights_Implementation_Coplanarity. Another reason is that in different communities the same weights are named and computed differently. If one searches for these weights, one needs to know all their alternative names, which is tiresome. We provide the most common names and implementations of these weights. -\subsection Weights_Implementation_Flattening Coplanarity - -\cgalFigureBegin{flattening, flattening.svg} - The non-planar configuration (top) is flattened to the planar configuration (bottom). -\cgalFigureEnd +\subsection Weights_Implementation_Coplanarity Coplanarity When computing weights for a query point \f$q\f$ with respect to its neighbors \f$p_0\f$, \f$p_1\f$, and \f$p_2\f$, the local configuration is a quadrilateral [\f$p_0\f$, \f$p_1\f$, \f$p_2\f$, \f$q\f$] or two connected triangles [\f$q\f$, \f$p_0\f$, \f$p_1\f$] and [\f$q\f$, \f$p_1\f$, \f$p_2\f$]. When working in 3D, these triangles are not necessarily coplanar, in other words, they do not belong to the same common plane. -When they are not coplanar, they can be made coplanar through the process called *flattening* (see the Figure above), -however the latter introduces a distortion because the weights are computed with respect to the -flattened configuration rather than to the original non-flat configuration. Certain weights in this package support only coplanar configurations, while other weights support both. The weights, which support non-coplanar configurations, provide the corresponding overloads with 3D points, while other weights accept only 2D point types. For example, \ref PkgWeightsRefCotangentWeights "cotangent weights" -support both flat and non-flat configurations, while \ref PkgWeightsRefDiscreteHarmonicWeights "discrete harmonic weights" -support only flat configurations. - -If you still want to compute the coplanar weights, such as discrete harmonic weights, in 3D, -you can either provide your own way to flatten the 3D configuration or you can use one of the projection -traits available in CGAL as the last parameter to the weight function (see \ref Weights_Examples_ProjectionTraits -for example, where the common plane is a horizontal plane). If the two triangles are not exactly coplanar, -this projection traits will introduce an error, but this error is proportional to how much these triangles -differ from the common plane. If the non-coplanarity difference between them is due to noise or inexact computations, -it won't affect much the final computation result. +support both coplanar and non-coplanar configurations, while \ref PkgWeightsRefDiscreteHarmonicWeights "discrete harmonic weights" +support only coplanar configurations. \subsection Weights_Implementation_Boundaries Boundaries @@ -179,22 +164,10 @@ The used type of barycentric weights is `Wachspress_weights_2`. \cgalExample{Weights/coordinates_multiple_queries.cpp} -\subsection Weights_Examples_ProjectionTraits Computing 2D Weights in 3D - -If you have a 2D polygon in 3D plane that is not an XY plane, you can still compute -the 2D weights, however you need to provide a special projection traits class. -The common plane that is used in this example is projectable to the XY plane. We first -compute `Mean_value_weights_2` for a 3D polygon in this plane. We then also show how to use -the projection traits to compute the \ref PkgWeightsRefWachspressWeights "2D Wachspress weight" -for 3D points, which are not strictly coplanar. - -\cgalExample{Weights/projection_traits.cpp} - - \subsection Weights_Examples_CustomTraits Weights with Custom Traits -As you could see from the previous example, it is possible to provide your own traits -class with basic geometric objects, constructions, and predicates required by the algorithm. +As you could see from the reference manual, it is possible to provide your own traits class +with basic geometric objects, constructions, and predicates to the weight functions. All weights in this \cgal component are models of the `AnalyticWeightTraits_2` and `AnalyticWeightTraits_3` concepts. However, many weights do not require all objects from these concepts. This example shows that the inverse distance weight, for instance, requires only the squared distance object which is specified diff --git a/Weights/doc/Weights/examples.txt b/Weights/doc/Weights/examples.txt index 68e7049f4c9..1e374b4c1f1 100644 --- a/Weights/doc/Weights/examples.txt +++ b/Weights/doc/Weights/examples.txt @@ -3,7 +3,6 @@ \example Weights/coordinates_one_query.cpp \example Weights/coordinates_multiple_queries.cpp \example Weights/weighted_laplacian.cpp -\example Weights/projection_traits.cpp \example Weights/custom_traits.cpp \example Weights/convergence.cpp */ diff --git a/Weights/include/CGAL/Weights/internal/utils.h b/Weights/include/CGAL/Weights/internal/utils.h index 5da0a0d80a9..c0e3f52f81c 100644 --- a/Weights/include/CGAL/Weights/internal/utils.h +++ b/Weights/include/CGAL/Weights/internal/utils.h @@ -432,6 +432,61 @@ namespace internal { return Point_2(x, y); } + // Flattening. + + // \cgalFigureBegin{flattening, flattening.svg} + // The non-planar configuration (top) is flattened to the planar configuration (bottom). + // \cgalFigureEnd + + // When computing weights for a query point \f$q\f$ with respect to its neighbors + // \f$p_0\f$, \f$p_1\f$, and \f$p_2\f$, the local configuration is a quadrilateral + // [\f$p_0\f$, \f$p_1\f$, \f$p_2\f$, \f$q\f$] or two connected triangles [\f$q\f$, \f$p_0\f$, \f$p_1\f$] + // and [\f$q\f$, \f$p_1\f$, \f$p_2\f$]. When working in 3D, these triangles are not + // necessarily coplanar, in other words, they do not belong to the same common plane. + // When they are not coplanar, they can be made coplanar through the process called *flattening* (see the Figure above), + // however the latter introduces a distortion because the weights are computed with respect to the + // flattened configuration rather than to the original non-flat configuration. + + // \subsection Weights_Examples_ProjectionTraits Computing 2D Weights in 3D + + // If you have a 2D polygon in 3D plane that is not an XY plane, you can still compute + // the 2D weights, however you need to provide a special projection traits class. + // The common plane that is used in this example is projectable to the XY plane. We first + // compute `Mean_value_weights_2` for a 3D polygon in this plane. We then also show how to use + // the projection traits to compute the \ref PkgWeightsRefWachspressWeights "2D Wachspress weight" + // for 3D points, which are not strictly coplanar. + + // \cgalExample{Weights/projection_traits.cpp} + + // Example of flattening: + + // 3D configuration. + // const Point_3 p0(0, 1, 1); + // const Point_3 p1(2, 0, 1); + // const Point_3 p2(7, 1, 1); + // const Point_3 q0(3, 1, 1); + + // Choose a type of the weight: + // e.g. 0 - Wachspress (WP) weight. + // const FT wp = FT(0); + + // Compute WP weights for q1, which is not on the plane [p0, p1, p2]. + + // Point_3 q1(3, 1, 2); + // std::cout << "3D wachspress (WP, q1): "; + // std::cout << CGAL::Weights::three_point_family_weight(p0, p1, p2, q1, wp) << std::endl; + + // Converge q1 towards q0 that is we flatten the configuration. + // We also compare the result with the authalic weight. + + // std::cout << "Converge q1 to q0: " << std::endl; + // for (FT x = FT(0); x <= FT(1); x += step) { + // std::cout << "3D wachspress/authalic: "; + // q1 = Point_3(3, 1, FT(2) - x); + // std::cout << CGAL::Weights::three_point_family_weight(p0, p1, p2, q1, wp) << "/"; + // std::cout << CGAL::Weights::authalic_weight(p0, p1, p2, q1) << std::endl; + // } + // Flattens an arbitrary quad into a planar quad. template void flatten( diff --git a/Weights/include/CGAL/Weights/three_point_family_weights.h b/Weights/include/CGAL/Weights/three_point_family_weights.h index 47aaa63bfe0..29a03965c4b 100644 --- a/Weights/include/CGAL/Weights/three_point_family_weights.h +++ b/Weights/include/CGAL/Weights/three_point_family_weights.h @@ -130,35 +130,6 @@ namespace Weights { namespace internal { - // Example of flattening: - - // 3D configuration. - // const Point_3 p0(0, 1, 1); - // const Point_3 p1(2, 0, 1); - // const Point_3 p2(7, 1, 1); - // const Point_3 q0(3, 1, 1); - - // Choose a type of the weight: - // e.g. 0 - Wachspress (WP) weight. - // const FT wp = FT(0); - - // Compute WP weights for q1, which is not on the plane [p0, p1, p2]. - - // Point_3 q1(3, 1, 2); - // std::cout << "3D wachspress (WP, q1): "; - // std::cout << CGAL::Weights::three_point_family_weight(p0, p1, p2, q1, wp) << std::endl; - - // Converge q1 towards q0 that is we flatten the configuration. - // We also compare the result with the authalic weight. - - // std::cout << "Converge q1 to q0: " << std::endl; - // for (FT x = FT(0); x <= FT(1); x += step) { - // std::cout << "3D wachspress/authalic: "; - // q1 = Point_3(3, 1, FT(2) - x); - // std::cout << CGAL::Weights::three_point_family_weight(p0, p1, p2, q1, wp) << "/"; - // std::cout << CGAL::Weights::authalic_weight(p0, p1, p2, q1) << std::endl; - // } - template typename GeomTraits::FT three_point_family_weight( const typename GeomTraits::Point_3& t,