Merge remote-tracking branch 'refs/remotes/lrineau/Triangulation_3-CDT_3-lrineau' into pr/lrineau/8186

Constrained_triangulation_3/doc/Constrained_triangulation_3/Concepts/ConformingConstrainedDelaunayTriangulationTraits_3.h

@@ -17,82 +17,68 @@ parameter `Triangulation_3` in the function template
 */
 class ConformingConstrainedDelaunayTriangulationTraits_3 {
 public:
-  /// \name Types
-  /// @{
-
-  /*!
-  * The number type
-  */
-  using FT = unspecified_type;
-
-  /*!
-  * The vector type
-  */
-  using Vector_3 = unspecified_type;
-
-  /// @}
 
   /// \name Operations
   /// The following functions give access to the predicate and construction objects:
   /// @{
 
   /*!
-   * returns a function object model of `Angle_3`
+   * returns a function object model of `Kernel::Angle_3`
    */
   unspecified_type angle_3_object();
 
   /*!
-   * returns a function object model of `CompareAngle_3
+   * returns a function object model of `Kernel::CompareAngle_3`
    */
   unspecified_type compare_angle_3_object();
 
   /*!
-   * returns a function object model of `ComputeScalarProduct_3`
+   * returns a function object model of `Kernel::ComputeScalarProduct_3`
    */
   unspecified_type compute_scalar_product_3_object();
 
   /*!
-   * returns a function object model of `ComputeSquaredLength_3`
+   * returns a function object model of `Kernel::ComputeSquaredLength_3`
    */
   unspecified_type compute_squared_length_3_object();
 
   /*!
-   * returns a function object model of `ConstructCrossProductVector_3`
+   * returns a function object model of `Kernel::ConstructCrossProductVector_3`
    */
   unspecified_type construct_cross_product_vector_3_object();
 
   /*!
-   * returns a function object model of `ConstructMidpoint_3`
+   * returns a function object model of `Kernel::ConstructMidpoint_3`
    */
   unspecified_type construct_midpoint_3_object();
 
   /*!
-   * returns a function object model of `ConstructVector_3`
+   * returns a function object model of `Kernel::ConstructVector_3`
    */
   unspecified_type construct_vector_3_object();
 
   /*!
-   * returns a function object model of `ConstructScaledVector_3`
+   * returns a function object model of `Kernel::ConstructScaledVector_3`
    */
   unspecified_type construct_scaled_vector_3_object();
 
   /*!
-   * returns a function object model of `ConstructSumOfVectors_3`
+   * returns a function object model of `Kernel::ConstructSumOfVectors_3`
    */
   unspecified_type construct_sum_of_vectors_3_object();
 
   /*!
-   * returns a function object model of `ConstructTranslatedPoint_3`
+   * returns a function object model of `Kernel::ConstructTranslatedPoint_3`
    */
   unspecified_type construct_translated_point_3_object();
 
   /*!
-   * returns a function object model of `ConstructVertex_3`
+   * returns a function object model of `Kernel::ConstructVertex_3`
    */
   unspecified_type construct_vertex_3_object();
 
   /*!
-   * returns a predicate object model of `IsDegenerate_3`
+   * returns a predicate object model of `Kernel::IsDegenerate_3`
    */
   unspecified_type is_degenerate_3_object();
 

Constrained_triangulation_3/doc/Constrained_triangulation_3/Concepts/ConformingConstrainedDelaunayTriangulationVertexBase_3.h

@@ -4,7 +4,8 @@
 
 The concept `ConformingConstrainedDelaunayTriangulationVertexBase_3` refines the concept
 `TriangulationVertexBase_3` and is the base vertex class for
-the `CGAL::make_conforming_constrained_Delaunay_triangulation_3()` function template.
+the triangulation returned by
+`CGAL::make_conforming_constrained_Delaunay_triangulation_3()` function template.
 
 \cgalRefines{TriangulationVertexBase_3, BaseWithTimeStamp}
 

Constrained_triangulation_3/doc/Constrained_triangulation_3/Constrained_triangulation_3.txt

@@ -24,7 +24,7 @@ the algorithm builds a constrained Delaunay triangulation conforming to this PLC
 The constrained triangulation does not always exist, and it may be necessary
 to add Steiner vertices to the PLC to make it tetrahedralizable.
 
-The problem is described by Cohen-Steiner et al \cgalCite{cgal:cohen2002conforming},
+The problem is described by Cohen-Steiner et al. \cgalCite{cgal:cohen2002conforming},
 and by Si \cgalCite{cgal:si2008cdt3}.
 
 
@@ -35,21 +35,25 @@ In this section, we define the main concepts that have to be understood to use t
 \subsection CT_3_PLC Piecewise Linear Complex
 
 A _Piecewise Linear Complex_ (PLC) is the 3-dimensional generalization of a
-planar straight-line graph. It is a finite set of vertices, edges, and polygons (facets)
+planar straight-line graph. It is a finite set of vertices, edges, and polygons (faces)
 that satisfies the following properties:
 
-- The vertices and edges in the PLC form a simplicial complex: every edge in the PLC has
+- The vertices and edges in the PLC form a simplicial complex: two edges may intersect
-  both its endpoints (vertices) in the PLC, and the relative interior of any edge in the
+  only at a common vertex.
-  PLC does not intersect any vertex or any other edge in the PLC.
+- For each polygon (face) in the PLC, its boundary is a union of edges in the PLC.
-- For each polygon (facet) in the PLC, its boundary is a union of edges in the PLC.
+- If two polygons (faces) in the PLC intersect, their intersection is a union of edges and vertices
-- If two polygons in the PLC intersect, their intersection is a union of edges and vertices
   in the PLC. In particular, the interiors of two polygons cannot intersect.
 
-The polygons (facets) can be non-convex, have holes, and as many boundary segments as needed.
+The polygons (faces) can be non-convex, have holes, and arbitrarily many boundary segments.
 
-\cgalFigureBegin{plc_fig, plc.png}
+\cgalFigureAnchor{CT_3_plc_fig}
+<center>
+<img src="plc.png" style="max-width:60%;"/>
+</center>
+\cgalFigureCaptionBegin{CT_3_plc_fig}
 A Piecewise Linear Complex, made of planar faces, connected by edges and vertices.
-\cgalFigureEnd
+\cgalFigureCaptionEnd
+
 
 \subsection CT_3_CDT Conforming Delaunay Triangulation
 
@@ -70,11 +74,16 @@ of polygons that are coplanar with the segment.
 In 3D, constrained triangulations do not always exist. It can be shown using the
 example of the Sch&ouml;nhardt polyhedra \cgalCite{schonhardt1928zerlegung},
 \cgalCite{b-ip-48a}, that requires the addition of
-Steiner vertices to be tetrahedralizable (see Figure \cgalFigureRef{schonhardt_fig}).
+Steiner vertices to be tetrahedralizable (see Figure \cgalFigureRef{CT_3_schonhardt_fig}).
 
-\cgalFigureBegin{schonhardt_fig, schonhardt.png}
+\cgalFigureAnchor{CT_3_schonhardt_fig}
+<center>
+<img src="schonhardt.png" style="max-width:40%;"/>
+</center>
+\cgalFigureCaptionBegin{CT_3_schonhardt_fig}
 A Sch&ouml;nhardt polyhedron.
-\cgalFigureEnd
+\cgalFigureCaptionEnd
+
 
 Shewchuk \cgalCite{cgal:shewchuk1998condition} showed that for any PLC,
 there exists another PLC that is a refined version of the original one,
@@ -88,15 +97,18 @@ Hang Si \cgalCite{si2005meshing}, \cgalCite{si2015tetgen}.
 Steiner vertices are added on input edges and input facets
 of the PLC to make it tetrahedralizable.
 
-Figure \cgalFigureRef{plc2cdt_fig} shows an example of a conforming constrained
+Figure \cgalFigureRef{CT_3_plc2cdt_fig} shows an example of a conforming constrained
 Delaunay triangulation constructed from a PLC.
 
-
+\cgalFigureAnchor{CT_3_plc2cdt_fig}
-\cgalFigureBegin{plc2cdt_fig, plc_to_cdt.png}
+<center>
+<img src="plc_to_cdt.png" style="max-width:90%;"/>
+</center>
+\cgalFigureCaptionBegin{CT_3_plc2cdt_fig}
 Left : PLC (360 vertices);
 Middle : CCDT (2452 vertices);
 Right : the same CCDT seen with cutplane.
-\cgalFigureEnd
+\cgalFigureCaptionEnd
 
 
 \section CT_3_api API
@@ -144,7 +156,8 @@ The following example demonstrates how to detect surface patches separated by sh
 and use this surface segmentation in the tetrahedrization process.
 
 When this parameter is used, the 3D triangulation constrained faces indices (available with
-`face_constraint_index()` in `Conforming_constrained_Delaunay_triangulation_cell_data_3`)
+\link Conforming_constrained_Delaunay_triangulation_cell_data_3::face_constraint_index() `face_constraint_index()`\endlink
+in `Conforming_constrained_Delaunay_triangulation_cell_data_3`)
 are set to the corresponding patch ids from this map.
 When it is not used, the face indices are set to different indices for each input facet.
 

Constrained_triangulation_3/doc/Constrained_triangulation_3/PackageDescription.txt

@@ -40,13 +40,6 @@ to add Steiner points to the PLC to make it tetrahedralizable.
 \cgalPkgDescriptionEnd
 
 \cgalClassifedRefPages
-`CGAL::make_conforming_constrained_Delaunay_triangulation_3()` is the main function to create
-a conforming constrained Delaunay triangulation in 3D, an instance of the class template
-`CGAL::Conforming_constrained_Delaunay_triangulation_3`.
-
-\cgalCRPSection{Functions Templates}
-
-- `CGAL::make_conforming_constrained_Delaunay_triangulation_3()`
 
 \cgalCRPSection{Concepts}
 
@@ -54,7 +47,13 @@ a conforming constrained Delaunay triangulation in 3D, an instance of the class
 - `ConformingConstrainedDelaunayTriangulationVertexBase_3`
 - `ConformingConstrainedDelaunayTriangulationCellBase_3`
 
-\cgalCRPSubsection{Class Templates}
+\cgalCRPSection{Functions}
+
+- `CGAL::make_conforming_constrained_Delaunay_triangulation_3()`: the main function to create
+a conforming constrained Delaunay triangulation in 3D, an instance of the class template
+`CGAL::Conforming_constrained_Delaunay_triangulation_3`.
+
+\cgalCRPSubsection{Classes}
 
 - `CGAL::Conforming_constrained_Delaunay_triangulation_3<Traits, Triangulation>`
 - `CGAL::Conforming_constrained_Delaunay_triangulation_vertex_base_3<Traits, Vertex_base>`

Constrained_triangulation_3/doc/Constrained_triangulation_3/doc_fragments/CDT_3_description_of_input.dox-frag

@@ -1,6 +1,7 @@
   The input data (polygon mesh or polygon soup) represents the polygonal constraints enforced
   during the triangulation process.
 
+
   By default, each face of the input is considered a polygonal constraint for the triangulation. The
   named parameter `face_patch_map` can be used to describe larger polygonal constraints, possibly with holes. If
   used, this parameter must be a property map that associates each face of the input with a patch
@@ -8,5 +9,6 @@
   surface patches (defined as the union of the input faces with a given patch identifier) is expected to be a polygon or a
   polygon with holes, with coplanar vertices (or nearly coplanar up to the precision of the number type used).
 
-  The generated triangulation will conform to the faces of the input or to the surface patches
+
+  The generated triangulation will conform to the faces of the input, or to the surface patches
   described by the `face_patch_map` property map if provided.

Constrained_triangulation_3/include/CGAL/Conforming_constrained_Delaunay_triangulation_3.h

@@ -552,6 +552,7 @@ private:
   CDT_3_impl cdt_impl = {};
 
   using Is_constrained = typename CDT_3_impl::Is_constrained;
+
 public:
   /** \name Constructors
   @{
@@ -956,9 +957,10 @@ public:
   /// \name Accessors for Constrained Facets
   /// @{
   /*!
-   * \brief returns if a facet is constrained.
+   * \brief returns whether a facet is constrained or not.
    * \param f is a facet of the triangulation, of type
-   *        \link TriangulationDataStructure_3::Facet `Triangulation::Facet`, as defined by its triangulation data structure \endlink.
+   *        \link TriangulationDataStructure_3::Facet `Triangulation::Facet`\endlink,
+   *        as defined by its triangulation data structure.
    */
   bool is_facet_constrained(typename Triangulation::Facet f) const {
     return cdt_impl.is_facet_constrained(f);

Constrained_triangulation_3/include/CGAL/Conforming_constrained_Delaunay_triangulation_cell_base_3.h

@@ -30,7 +30,7 @@ namespace CGAL {
  *
  * @tparam Traits The geometric traits class, which must be a model of `ConformingConstrainedDelaunayTriangulationTraits_3`.
  *         It should be the same as the geometric traits class of the triangulation.
- * @tparam Cell_base The base class for the cell, which must be a model of `TriangulationCellBase_3`.
+ * @tparam CellBase The base class for the cell, which must be a model of `TriangulationCellBase_3`.
  *
  * @cgalModels{ConformingConstrainedDelaunayTriangulationCellBase_3, SimplicialMeshCellBase_3, RemeshingCellBase_3}
  *
@@ -38,11 +38,11 @@ namespace CGAL {
  *
  * \sa `CGAL::Conforming_constrained_Delaunay_triangulation_vertex_base_3`
  */
-template <typename Traits, typename Cell_base = Triangulation_cell_base_3<Traits> >
+template <typename Traits, typename CellBase = Triangulation_cell_base_3<Traits> >
 class Conforming_constrained_Delaunay_triangulation_cell_base_3
-  : public Base_with_time_stamp<Cell_base>
+  : public Base_with_time_stamp<CellBase>
 {
-  using Base = Base_with_time_stamp<Cell_base>;
+  using Base = Base_with_time_stamp<CellBase>;
   Conforming_constrained_Delaunay_triangulation_cell_data_3 ccdt_3_data_;
 
   CDT_3_signed_index subdomain_index_ = -1;
@@ -51,7 +51,7 @@ public:
   // To get correct cell type in TDS
   template < class TDS3 >
   struct Rebind_TDS {
-    typedef typename Cell_base::template Rebind_TDS<TDS3>::Other Cb3;
+    typedef typename CellBase::template Rebind_TDS<TDS3>::Other Cb3;
     typedef Conforming_constrained_Delaunay_triangulation_cell_base_3 <Traits, Cb3> Other;
   };
 

Constrained_triangulation_3/include/CGAL/Conforming_constrained_Delaunay_triangulation_cell_data_3.h

@@ -67,16 +67,16 @@ class Conforming_constrained_Delaunay_triangulation_cell_data_3 {
     return cdt.tds().faces().iterator_to(*ptr);
   }
 public:
-  /// @brief Returns if the i-th facet of the cell is constrained.
+  /// @brief returns whether the i-th facet of the cell is constrained or not.
   bool is_facet_constrained(int i) const { return face_id[unsigned(i)] >= 0; }
 
-  /// @brief Returns the index of the constraint that constrains the
+  /// @brief returns the index of the constraint that constrains the
   /// i-th facet of the cell.
   /// @pre `is_facet_constrained(i)`
   CDT_3_signed_index face_constraint_index(int i) const {
     return face_id[unsigned(i)];
   }
-  /// @brief Set the index of the constraint that constrains the i-th facet of the cell.
+  /// @brief sets the index of the constraint that constrains the i-th facet of the cell.
   void set_face_constraint_index(int i, CDT_3_signed_index index) {
     face_id[unsigned(i)] = index;
   }

Constrained_triangulation_3/include/CGAL/Conforming_constrained_Delaunay_triangulation_vertex_base_3.h

@@ -29,16 +29,17 @@ namespace CGAL {
  * This class is derived from the `Triangulation_vertex_base_3` class and provides additional functionality
  * required by `make_conforming_constrained_Delaunay_triangulation_3()`.
  *
- * @tparam Traits The geometric traits class, model of `DelaunayTriangulationTraits_3`.
+ * @tparam Traits The geometric traits class, model of `ConformingConstrainedDelaunayTriangulationTraits_3`.
  *         It must be the same as the geometric traits class of the triangulation.
- * @tparam Vertex_base The base class for the vertex. It must be a model of `TriangulationVertexBase_3`.
+ * @tparam VertexBase The base class for the vertex. It must be a model of `TriangulationVertexBase_3`.
  *
  * @cgalModels{ConformingConstrainedDelaunayTriangulationVertexBase_3}
  *
  * \sa `CGAL::Conforming_constrained_Delaunay_triangulation_cell_base_3`
  */
-template < typename Traits, typename Vertex_base = Triangulation_vertex_base_3<Traits> >
+template < typename Traits, typename VertexBase = Triangulation_vertex_base_3<Traits> >
-class Conforming_constrained_Delaunay_triangulation_vertex_base_3 : public Base_with_time_stamp<Vertex_base>
+class Conforming_constrained_Delaunay_triangulation_vertex_base_3
+  : public Base_with_time_stamp<VertexBase>
 {
   Conforming_constrained_Delaunay_triangulation_vertex_data_3 ccdt_3_data_;
   bool cache_validity_ = false;
@@ -51,12 +52,12 @@ public:
   // To get correct vertex type in TDS
   template <class TDS3> struct Rebind_TDS
   {
-    using Vb3 = typename Vertex_base::template Rebind_TDS<TDS3>::Other;
+    using Vb3 = typename VertexBase::template Rebind_TDS<TDS3>::Other;
     using Other = Conforming_constrained_Delaunay_triangulation_vertex_base_3<Traits, Vb3>;
   };
 
   // constructors, inherited from the base class
-  using Base = Base_with_time_stamp<Vertex_base>;
+  using Base = Base_with_time_stamp<VertexBase>;
   using Base::Base;
 
   // model of SimplicialMeshVertexBase_3
@@ -108,7 +109,7 @@ public:
   const Conforming_constrained_Delaunay_triangulation_vertex_data_3& ccdt_3_data() const { return ccdt_3_data_; }
 
   static std::string io_signature() {
-    return Get_io_signature<Vertex_base>()();
+    return Get_io_signature<VertexBase>()();
   }
 };
 

Constrained_triangulation_3/include/CGAL/make_conforming_constrained_Delaunay_triangulation_3.h

@@ -29,7 +29,7 @@ namespace CGAL {
   Free Functions for Creating Conforming Constrained Delaunay Triangulations  {#PkgConstrainedTriangulation3Functions}
   ==========================================================================
 
-  Each of the following functions create a 3D conforming constrained Delaunay triangulation
+  The following functions create a 3D conforming constrained Delaunay triangulation
   from either a polygon soup or a polygon mesh.
 
   Input Data        {#make_conforming_constrained_Delaunay_triangulation_3_input_data}
@@ -40,7 +40,7 @@ namespace CGAL {
   Template Parameters        {#make_conforming_constrained_Delaunay_triangulation_3_template_parameters}
   -------------------
 
-  For both function templates, the template arguments can be deduced from the function arguments or defaulted.
+  For both function templates, the template arguments can be deduced from the function arguments, or defaulted.
 
   - The first template argument `Triangulation` defaults to `CGAL::Default`, and in that case the
     triangulation type is deduced from the input type and the named parameters (see below).
@@ -94,8 +94,8 @@ namespace CGAL {
  *    \cgalParamDescription{a property map associating a patch identifier to each face of `mesh`}
  *    \cgalParamType{a class model of `ReadWritePropertyMap` with `boost::graph_traits<PolygonMesh>::%face_descriptor`
  *                   as key type and with any value type that is a *regular* type (model of `Regular`)}
- *   \cgalParamExtra{If this parameter is omitted, each face of the mesh is considered a separate patch.}
+ *   \cgalParamExtra{If this parameter is omitted, each face of the mesh is considered a separate patch.
- *   \cgalParamExtra{Otherwise, faces with the same patch identifier are considered part of the same surface patch.}
+ *                   Otherwise, faces with the same patch identifier are considered part of the same surface patch.}
  *   \cgalParamNEnd
  *
  *   \cgalParamNBegin{geom_traits}
@@ -108,7 +108,8 @@ namespace CGAL {
  * \return a 3D constrained Delaunay triangulation conforming to the faces of the polygon mesh, of a type
  *   described in the section \ref make_conforming_constrained_Delaunay_triangulation_3_returned_type above.
  *
- * \pre `mesh` must not have self-intersections:
+ * \pre `mesh` must not have self-intersections.
+ *      For triangulated surfaces, it can be checked using the function
  *      \link CGAL::Polygon_mesh_processing::does_self_intersect
  *      `CGAL::Polygon_mesh_processing::does_self_intersect(mesh, np) == false`
  *      \endlink

Kernel_23/doc/Kernel_23/CGAL/Projection_traits_3.h

@@ -7,7 +7,7 @@ The class `Projection_traits_3` works similarly to the `Projection_traits_xy_3`,
 `Projection_traits_xz_3`, and `Projection_traits_yz_3` traits classes, enabling
 the use of 2D algorithms on the projections of 3D data onto an arbitrary plane.
 
-\tparam Geom_traits must be a model of `ProjectionTraitsGeometricTraits_3`
+\tparam GeomTraits must be a model of `ProjectionTraitsGeometricTraits_3`
 
 \note Internal constructions (projections) are used in the predicate and
 construction functors of this class. If `K` is a model of `Kernel` providing exact
@@ -21,7 +21,7 @@ provides exact predicates.
 \sa `CGAL::Projection_traits_xz_3`
 \sa `CGAL::Projection_traits_yz_3`
 */
-template <class Geom_traits>
+template <class GeomTraits>
 class Projection_traits_3
 {
 public:
@@ -40,7 +40,7 @@ public:
    *
    * \param normal a vector orthogonal to the projection plane.
    */
-  Projection_traits_3(const typename Geom_traits::Vector_3& normal);
+  Projection_traits_3(const typename GeomTraits::Vector_3& normal);
 
   ///@}
 };

Kernel_23/doc/Kernel_23/Concepts/ProjectionTraitsGeometricTraits_3.h

@@ -19,7 +19,7 @@ public:
 /// \name Types
 /// @{
 
-  /*! Number type */
+  /*! Number type model of `FieldNumberType`*/
   typedef unspecified_type FT;
 
   /*! 2D point type */

STL_Extension/include/CGAL/Base_with_time_stamp.h

@@ -20,11 +20,11 @@ namespace CGAL {
 ///
 /// This class is a base class that can be used to add a time stamp to any class.
 /// \cgalModels{BaseWithTimeStamp}
-template <typename B_w_ts_base>
+template <typename BaseWithTSBase>
-class Base_with_time_stamp : public B_w_ts_base {
+class Base_with_time_stamp : public BaseWithTSBase {
   std::size_t time_stamp_ = std::size_t(-2);
 public:
-  using B_w_ts_base::B_w_ts_base;
+  using BaseWithTSBase::BaseWithTSBase;
 
   using Has_timestamp = CGAL::Tag_true;
 
@@ -37,7 +37,7 @@ public:
 
   template < class TDS >
   struct Rebind_TDS {
-    typedef typename B_w_ts_base::template Rebind_TDS<TDS>::Other Base2;
+    typedef typename BaseWithTSBase::template Rebind_TDS<TDS>::Other Base2;
     typedef Base_with_time_stamp<Base2> Other;
   };
 };