From 857f494340af00a2ee3a45b070f1fc096097b12c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mael=20Rouxel-Labb=C3=A9?= Date: Tue, 23 Mar 2021 10:56:21 +0100 Subject: [PATCH] Minor ref manual improvements --- .../CGAL/Delaunay_triangulation_on_sphere_2.h | 17 +++++++++++--- ...elaunay_triangulation_on_sphere_traits_2.h | 2 +- .../CGAL/Triangulation_on_sphere_2.h | 22 ++++++++++++------- .../DelaunayTriangulationOnSphereTraits_2.h | 11 +++++++--- .../Concepts/TriangulationOnSphereTraits_2.h | 3 ++- 5 files changed, 39 insertions(+), 16 deletions(-) diff --git a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_on_sphere_2.h b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_on_sphere_2.h index 60e5eee44bf..adc9ee7b65b 100644 --- a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_on_sphere_2.h +++ b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_on_sphere_2.h @@ -66,7 +66,7 @@ public: introduces an empty triangulation, sets the center and radius of the sphere to `c` and `r` respectively, and inserts the point range `[first; beyond[`. - \tparam PointOnSphereIterator must be a model of `InputIterator` with value type `Point_on_sphere_2`. + \tparam PointOnSphereIterator must be a model of `InputIterator` with value type `Point_on_sphere_2` or `Point_3`. */ template Delaunay_triangulation_on_sphere_2(PointOnSphereIterator first, PointOnSphereIterator beyond, @@ -78,7 +78,7 @@ public: \warning It is the user's responsability to ensure that the center and radius are set as intended in `gt`. - \tparam PointOnSphereIterator must be a model of `InputIterator` with value type `Point_on_sphere_2`. + \tparam PointOnSphereIterator must be a model of `InputIterator` with value type `Point_on_sphere_2` or `Point_3`. */ template Delaunay_triangulation_on_sphere_2(PointOnSphereIterator first, PointOnSphereIterator beyond, @@ -183,6 +183,9 @@ public: /// Two different embeddings are possible: a "straight" embedding, using line segments living /// in Euclidean 3D sphere, and a "curved" embedding, using arc segments on the sphere. /// + /// Note that the following operations are constructions, which should be kept in mind in the choice + /// of the underlying kernel. + /// /// @{ // Straight @@ -210,22 +213,30 @@ public: // Curved /*! - returns the intersection of the dual of the face `f` and the sphere + returns the intersection of the dual of the face `f` and the sphere. + + \pre `dimension() == 2` and `f` is a solid face. */ Point dual_on_sphere(const Face_handle f) const; /*! returns the arc of great circle with endpoints the circumcenters of the faces incident to the edge `e`. + + \pre `dimension() == 2` and `e` is not a ghost edge. */ Arc_on_sphere_2 dual_on_sphere(const Edge& e) const; /*! returns the arc of great circle with endpoints the circumcenters of the faces incident to the edge `*ec`. + + \pre `dimension() == 2` and `*ec` is not a ghost edge. */ Arc_on_sphere_2 dual_on_sphere(const Edge_circulator ec) const; /*! returns the arc of great circle with endpoints the circumcenters of the faces incident to the edge `*ei`. + + \pre `dimension() == 2` and `*ei` is not a ghost edge. */ Arc_on_sphere_2 dual_on_sphere(const All_edges_iterator ei) const; diff --git a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_on_sphere_traits_2.h b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_on_sphere_traits_2.h index 657703daf94..2cbc69936b0 100644 --- a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_on_sphere_traits_2.h +++ b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Delaunay_triangulation_on_sphere_traits_2.h @@ -25,7 +25,7 @@ using the relation above to ensure that a point being inserted is either marked and thus not inserted, or guaranteed to not be hidden upon insertion. \tparam LK a linear kernel type; it must be a model of `Kernel`. -\tparam SK a spherical kernel type; it must be a model of `SphericalKernel`. +\tparam SK a spherical kernel type; it must be a model of `SphericalKernel` refining `LK`. \cgalModels `DelaunayTriangulationOnSphereTraits_2` diff --git a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Triangulation_on_sphere_2.h b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Triangulation_on_sphere_2.h index 37b0b18a9cc..8000e773254 100644 --- a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Triangulation_on_sphere_2.h +++ b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/CGAL/Triangulation_on_sphere_2.h @@ -31,7 +31,7 @@ are not ghost faces solid faces, and edges of such faces solid edge \sa `CGAL::Delaunay_triangulation_on_sphere_2` */ -template< typename Traits, typename TDS > +template class Triangulation_on_sphere_2 : public Triangulation_cw_ccw_2 { @@ -65,11 +65,6 @@ public: */ typedef Traits::Point_on_sphere_2 Point; - /*! - An arc of a great circle, used to represent a curved segment (Voronoi or Delaunay edge). - */ - typedef Traits::Arc_on_sphere_2 Arc_on_sphere_2; - /*! The 3D point type. */ @@ -85,6 +80,11 @@ public: */ typedef Traits::Triangle_3 Triangle_3; + /*! + An arc of a great circle, used to represent a curved segment (Voronoi or Delaunay edge). + */ + typedef Traits::Arc_on_sphere_2 Arc_on_sphere_2; + public: /*! The vertex type. @@ -258,12 +258,16 @@ public: /*! returns `true` if `f` is a ghost face, and `false` otherwise. + + \pre `dimension() == 2` */ bool is_ghost(const Face_handle f) const; /*! returns `true` if `e` is a ghost edge, that is if both its incident faces are ghost faces, and `false` otherwise. + + \pre `dimension() == 2` */ bool is_ghost(const Edge& e) const; @@ -517,6 +521,8 @@ public: /*! Starts at an arbitrary face incident to the vertex `v`. + + Note that this may contain ghost faces. */ Face_circulator incident_faces(Vertex_handle v) const; @@ -545,7 +551,7 @@ public: If `true` is returned, the edge with vertices `va` and `vb` is the edge `e=(fr,i)` where `fr` is a handle to the face incident to `e` and on the right side of `e` oriented from `va` to `vb`. */ - bool is_edge(Vertex_handle va, Vertex_handle vb, Face_handle& fr, int & i); + bool is_edge(Vertex_handle va, Vertex_handle vb, Face_handle& fr, int& i); /*! returns `true` if there exists a face (ghost or solid) having `v1`, `v2` and `v3` as vertices. @@ -556,7 +562,7 @@ public: returns `true` if there exists a face (ghost or solid) having `v1`, `v2` and `v3` as vertices. If `true` is returned, `fr` is a handle to the face with `v1`, `v2` and `v3` as vertices. */ - bool is_face(Vertex_handle v1, Vertex_handle v2, Vertex_handle v3, Face_handle &fr); + bool is_face(Vertex_handle v1, Vertex_handle v2, Vertex_handle v3, Face_handle& fr); /// @} diff --git a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/Concepts/DelaunayTriangulationOnSphereTraits_2.h b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/Concepts/DelaunayTriangulationOnSphereTraits_2.h index 3053d5d8789..ca03f9c3c1f 100644 --- a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/Concepts/DelaunayTriangulationOnSphereTraits_2.h +++ b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/Concepts/DelaunayTriangulationOnSphereTraits_2.h @@ -7,8 +7,9 @@ The concept `DelaunayTriangulationOnSphereTraits_2` describes the set of requirements to be fulfilled by any class used to instantiate the first template parameter of the class `CGAL::Delaunay_triangulation_on_sphere_2`. -This concept provides the types of the geometric primitives used in the -triangulation and the function object types for the required predicates on those primitives. + +To the requirements listed within the concept `TriangulationOnSphereTraits_2`, +this concept adds types and functors requirements related to build the dual on the sphere. \cgalHasModel `CGAL::Delaunay_triangulation_on_sphere_traits_2` \cgalHasModel `CGAL::Projection_on_sphere_traits_3` @@ -25,7 +26,11 @@ public: /// `Point_on_sphere_2 operator()(Point_on_sphere_2 p, Point_on_sphere_2 q, Point_on_sphere_2 r)` /// /// which returns the intersection of the dual of the face defined by the three points `p`, `q`, and `r`, - /// and the sphere. + /// and the sphere, on the positive side of the plane defined by `p`, `q`, and `r`. The dual of the face + /// is the line orthogonal to the face, passing through the center of the smallest circumscribing sphere + /// of the face. + /// + /// \pre the center of the sphere is on the negative side of the plane defined by `p`, `q`, and `r`. /// /// \note This type is only required for the computation of dual objects (Voronoi vertices and edges) /// and a dummy type can be used otherwise. diff --git a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/Concepts/TriangulationOnSphereTraits_2.h b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/Concepts/TriangulationOnSphereTraits_2.h index a15ace91a3c..631398d0221 100644 --- a/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/Concepts/TriangulationOnSphereTraits_2.h +++ b/Triangulation_on_sphere_2/doc/Triangulation_on_sphere_2/Concepts/TriangulationOnSphereTraits_2.h @@ -122,9 +122,10 @@ public: /// when traversing the great circle counterclockwise seen from the side of the plane /// of the great circle pointed by its positive normal vectors. /// - /// In this definition, we say that a normal vector \f$ (a,b,c)\f$ is positive if + /// In this definition, we say that a normal vector \f$ (a,b,c)\f$ is positive if /// \f$ (a,b,c)>(0,0,0)\f$ (i.e.\ \f$ (a>0) || (a==0) \&\& (b>0) || (a==0)\&\&(b==0)\&\&(c>0)\f$). /// + /// \pre `p` and `q` are not diametrically opposed. typedef unspecified_type Construct_arc_on_sphere_2; /// Construction object. Must provide the operator: