From 232c38cee1ba1fb58fb88c62ed5f1c598f28860f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Thu, 20 Apr 2017 12:54:39 +0200 Subject: [PATCH] Removed documentation of degenerate cases of power_side_of_oriented_* predicates See Issue https://github.com/CGAL/cgal/issues/2067 --- .../include/CGAL/Cartesian/function_objects.h | 10 +++ .../CGAL/Homogeneous/function_objects.h | 39 +++++++++-- .../Concepts/FunctionObjectConcepts.h | 65 ++----------------- .../include/CGAL/Kernel/function_objects.h | 15 +++++ 4 files changed, 64 insertions(+), 65 deletions(-) diff --git a/Cartesian_kernel/include/CGAL/Cartesian/function_objects.h b/Cartesian_kernel/include/CGAL/Cartesian/function_objects.h index dbdcc49fddd..c23d442fa63 100644 --- a/Cartesian_kernel/include/CGAL/Cartesian/function_objects.h +++ b/Cartesian_kernel/include/CGAL/Cartesian/function_objects.h @@ -4143,6 +4143,16 @@ namespace CartesianKernelFunctors { t.x(), t.y(), t.weight()); } + // The methods below are currently undocumented because the definition of + // orientation is unclear for 2 and 1 point configurations in a 2D space. + + // One should be (very) careful with the order of vertices when using them, + // as swapping points will change the result and one must therefore have a + // precise idea of what is the positive orientation in the full space. + // For example, these functions are (currently) used safely in the regular + // triangulations classes because we always call them on vertices of + // triangulation cells, which are always positively oriented. + Oriented_side operator()(const Weighted_point_2& p, const Weighted_point_2& q, const Weighted_point_2& t) const diff --git a/Homogeneous_kernel/include/CGAL/Homogeneous/function_objects.h b/Homogeneous_kernel/include/CGAL/Homogeneous/function_objects.h index 62e081bd8c0..b3dc18a7bb4 100644 --- a/Homogeneous_kernel/include/CGAL/Homogeneous/function_objects.h +++ b/Homogeneous_kernel/include/CGAL/Homogeneous/function_objects.h @@ -4450,33 +4450,48 @@ namespace HomogeneousKernelFunctors { t.hx(), t.hy(), t.hz(), t.hw(), t.weight()); } + // The methods below are currently undocumented because the definition of + // orientation is unclear for 3, 2, and 1 point configurations in a 3D space. + + // One should be (very) careful with the order of vertices when using them, + // as swapping points will change the result and one must therefore have a + // precise idea of what is the positive orientation in the full space. + // For example, these functions are (currently) used safely in the regular + // triangulations classes because we always call them on vertices of + // triangulation cells, which are always positively oriented. + Oriented_side operator() ( const Weighted_point_3 & p, const Weighted_point_3 & q, const Weighted_point_3 & r, const Weighted_point_3 & s) const { - return power_side_of_oriented_power_sphereH3( + //CGAL_kernel_precondition( coplanar(p, q, r, s) ); + //CGAL_kernel_precondition( !collinear(p, q, r) ); + return power_side_of_oriented_power_sphereH3( p.hx(), p.hy(), p.hz(), p.weight(), q.hx(), q.hy(), q.hz(), q.weight(), r.hx(), r.hy(), r.hz(), r.weight(), s.hx(), s.hy(), s.hz(), s.weight()); - } + } Oriented_side operator() ( const Weighted_point_3 & p, const Weighted_point_3 & q, const Weighted_point_3 & r) const { - return power_side_of_oriented_power_sphereH3( + //CGAL_kernel_precondition( collinear(p, q, r) ); + //CGAL_kernel_precondition( p.point() != q.point() ); + return power_side_of_oriented_power_sphereH3( p.x(), p.y(), p.z(), p.weight(), q.x(), q.y(), q.z(), q.weight(), r.x(), r.y(), r.z(), r.weight()); - } + } Oriented_side operator() ( const Weighted_point_3 & p, const Weighted_point_3 & q) const - { - return power_side_of_oriented_power_sphereH3(p.weight(),q.weight()); - } + { + //CGAL_kernel_precondition( p.point() == r.point() ); + return power_side_of_oriented_power_sphereH3(p.weight(),q.weight()); + } }; #endif @@ -4501,6 +4516,16 @@ namespace HomogeneousKernelFunctors { t.hx(), t.hy(), t.hw(), t.weight()); } + // The methods below are currently undocumented because the definition of + // orientation is unclear for 2 and 1 point configurations in a 2D space. + + // One should be (very) careful with the order of vertices when using them, + // as swapping points will change the result and one must therefore have a + // precise idea of what is the positive orientation in the full space. + // For example, these functions are (currently) used safely in the regular + // triangulations classes because we always call them on vertices of + // triangulation cells, which are always positively oriented. + Oriented_side operator()(const Weighted_point_2& p, const Weighted_point_2& q, const Weighted_point_2& t) const diff --git a/Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h b/Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h index 17a8d076381..c5ba6d1acdd 100644 --- a/Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h +++ b/Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h @@ -9212,7 +9212,8 @@ public: \sa `ComputePowerProduct_2` for the definition of power distance. */ - class PowerSideOfOrientedPowerCircle_2 { +class PowerSideOfOrientedPowerCircle_2 +{ public: /// \name Operations @@ -9230,29 +9231,13 @@ public: \pre the bare points corresponding to `p`, `q`, `r` are not collinear. */ - Oriented_side operator() ( const Kernel::Weighted_point_2& p, - const Kernel::Weighted_point_2& q, - const Kernel::Weighted_point_2& r, - const Kernel::Weighted_point_2& s); - -/*! - degenerate power test for collinear points `p`, `q`, `r`. - \pre `p` and `q` have different bare points. -*/ - Oriented_side operator() ( const Kernel::Weighted_point_2& p, - const Kernel::Weighted_point_2& q, - const Kernel::Weighted_point_2& r); -/*! -degenerate power test for weighted points -`p` and `q` whose corresponding bare points are identical. -\pre `p` and `q` have equal bare points. -*/ -Oriented_side operator() ( const Kernel::Weighted_point_2& p, - const Kernel::Weighted_point_2& q); - + Oriented_side operator()(const Kernel::Weighted_point_2& p, + const Kernel::Weighted_point_2& q, + const Kernel::Weighted_point_2& r, + const Kernel::Weighted_point_2& s); /// @} - }; +}; /*! \ingroup PkgKernel23ConceptsFunctionObjects @@ -9298,42 +9283,6 @@ public: const Kernel::Weighted_point_3& r, const Kernel::Weighted_point_3& s, const Kernel::Weighted_point_3& t) const; - - /*! - Analogous to the previous method, for coplanar points, - with the power circle \f$ {z(p,q,r)}^{(w)}\f$. - - \pre `p, q, r, s` are coplanar and `p, q, r` are not collinear. - */ - Oriented_side operator()( const Kernel::Weighted_point_3& p, - const Kernel::Weighted_point_3& q, - const Kernel::Weighted_point_3& r, - const Kernel::Weighted_point_3& t) const; - - /*! - which is the same for collinear points, where \f$ {z(p,q)}^{(w)}\f$ is the - power segment of `p` and `q`. - - \pre `p, q, r` are collinear, and `p` and `q` have different bare points. - - If all points have a weight equal to 0, then - `power_side_of_oriented_power_sphere_3(p,q,t)` yields an answer consistent with - what the kernel predicate `s(p,q).has_on(t)` would give, where `s(p,q)` - denotes the segment with endpoints `p` and `q`. - */ - Oriented_side operator()( const Kernel::Weighted_point_3& p, - const Kernel::Weighted_point_3& q, - const Kernel::Weighted_point_3& t) const; - - /*! - which is the same for equal points, that is when `p` and `q` - have equal coordinates, and returns the comparison of the weights - (`ON_POSITIVE_SIDE` when `q` is heavier than `p`). - - \pre `p` and `q` have equal bare points. - */ - Oriented_side operator()( const Kernel::Weighted_point_3& p, - const Kernel::Weighted_point_3& q) const; /// @} }; diff --git a/Kernel_23/include/CGAL/Kernel/function_objects.h b/Kernel_23/include/CGAL/Kernel/function_objects.h index 7cb2ed5326a..342314ffb36 100644 --- a/Kernel_23/include/CGAL/Kernel/function_objects.h +++ b/Kernel_23/include/CGAL/Kernel/function_objects.h @@ -452,11 +452,23 @@ namespace CommonKernelFunctors { t.x(), t.y(), t.z(), t.weight()); } + // The methods below are currently undocumented because the definition of + // orientation is unclear for 3, 2, and 1 point configurations in a 3D space. + + // One should be (very) careful with the order of vertices when using them, + // as swapping points will change the result and one must therefore have a + // precise idea of what is the positive orientation in the full space. + // For example, these functions are (currently) used safely in the regular + // triangulations classes because we always call them on vertices of + // triangulation cells, which are always positively oriented. + Oriented_side operator()(const Weighted_point_3 & p, const Weighted_point_3 & q, const Weighted_point_3 & r, const Weighted_point_3 & s) const { + //CGAL_kernel_precondition( coplanar(p, q, r, s) ); + //CGAL_kernel_precondition( !collinear(p, q, r) ); return power_side_of_oriented_power_sphereC3(p.x(), p.y(), p.z(), p.weight(), q.x(), q.y(), q.z(), q.weight(), r.x(), r.y(), r.z(), r.weight(), @@ -467,6 +479,8 @@ namespace CommonKernelFunctors { const Weighted_point_3 & q, const Weighted_point_3 & r) const { + //CGAL_kernel_precondition( collinear(p, q, r) ); + //CGAL_kernel_precondition( p.point() != q.point() ); return power_side_of_oriented_power_sphereC3(p.x(), p.y(), p.z(), p.weight(), q.x(), q.y(), q.z(), q.weight(), r.x(), r.y(), r.z(), r.weight()); @@ -475,6 +489,7 @@ namespace CommonKernelFunctors { Oriented_side operator()(const Weighted_point_3 & p, const Weighted_point_3 & q) const { + //CGAL_kernel_precondition( p.point() == r.point() ); return power_side_of_oriented_power_sphereC3(p.weight(),q.weight()); } };