Triangulation_2 : Document the Triangulation_2_projection_traits_3 class

BGL/test/BGL/test_deprecated_io.cpp

@@ -1,4 +1,5 @@
 #include <CGAL/Installation/internal/disable_deprecation_warnings_and_errors.h>
+
 #include <fstream>
 #include <iostream>
 #include <CGAL/Surface_mesh.h>

GraphicsView/include/CGAL/Buffer_for_vao.h

@@ -15,7 +15,7 @@
 
 #include <CGAL/license/GraphicsView.h>
 
-#include <CGAL/Triangulation_2_projection_traits_3.h>
+#include <CGAL/Projection_traits_3.h>
 #include <CGAL/Triangulation_vertex_base_with_info_2.h>
 #include <CGAL/Triangulation_face_base_with_info_2.h>
 #include <CGAL/Constrained_Delaunay_triangulation_2.h>
@@ -887,7 +887,7 @@ class Buffer_for_vao
     bool is_process;
   };
 
-  typedef CGAL::Triangulation_2_projection_traits_3<CGAL::Exact_predicates_inexact_constructions_kernel> P_traits;
+  typedef CGAL::Projection_traits_3<CGAL::Exact_predicates_inexact_constructions_kernel> P_traits;
   typedef CGAL::Triangulation_vertex_base_with_info_2<Vertex_info, P_traits> Vb;
   typedef CGAL::Triangulation_face_base_with_info_2<Face_info, P_traits>     Fb1;
   typedef CGAL::Constrained_triangulation_face_base_2<P_traits, Fb1>         Fb;

Installation/CHANGES.md

@@ -39,6 +39,8 @@ Release date: December 2021
 -   Added `construct_centroid_2_object()` and `compute_determinant_2_object()` in `Projection_traits_xy_3`, `Projection_traits_xz_3`,
     and`Projection_traits_yz_3` classes.
 
+-   Added documentation for the class `Projection_traits_3`, which enables the use of 2D algorithms on the projections of 3D data onto an arbitrary plane.
+
 ### [Polygon Mesh Processing](https://doc.cgal.org/5.4/Manual/packages.html#PkgPolygonMeshProcessing)
 
 -   Added the function `CGAL::Polygon_mesh_processing::match_faces()`, which, given two polygon meshes,

Kernel_23/doc/Kernel_23/CGAL/Projection_traits_3.h

@@ -0,0 +1,51 @@
+namespace CGAL{
+
+/*!
+\ingroup kernel_classes
+
+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 K must be a model of `Kernel`
+
+\note Internal constructions (projections) are used in the predicate and
+construction functors of this class. If `K` is a model of `Kernel` providing exact
+constructions or if `K` is a `CGAL::Filtered_kernel` (such as for
+`CGAL::Exact_predicates_inexact_constructions_kernel`), this class automatically
+provides exact predicates.
+
+\cgalModels `TriangulationTraits_2`
+\cgalModels `DelaunayTriangulationTraits_2`
+\cgalModels `ConstrainedTriangulationTraits_2`
+\cgalModels `PolygonTraits_2`
+
+\sa `CGAL::Projection_traits_xy_3`
+\sa `CGAL::Projection_traits_xz_3`
+\sa `CGAL::Projection_traits_yz_3`
+*/
+template <class K>
+class Projection_traits_3
+{
+public:
+  /// \name Functors
+  /// The functors provided by this class are those listed in the
+  /// concepts. The functors operate on the 2D projections of their
+  /// arguments. They come with preconditions that projections of the
+  /// arguments are non-degenerate, e.g. a line segment does not project
+  /// on a single point, two points do not project onto the same point, etc.
+
+  /// \name Creation
+  ///@{
+
+  /*!
+   * \brief Constructor
+   *
+   * \param normal a vector orthogonal to the projection plane.
+   */
+  Projection_traits_3(const typename K::Vector_3& normal);
+
+  ///@}
+};
+
+} // end namespace CGAL

Kernel_23/doc/Kernel_23/CGAL/Projection_traits_xy_3.h

@@ -13,12 +13,13 @@ deal with projections on the
 `zx`- and the `zy`-plane,
 respectively.
 
-\cgalHeading{Parameters}
+\tparam K must be a model of `Kernel`.
 
-The template parameter `K` has to
-be instantiated by a model of the `Kernel` concept.
-`Projection_traits_xy_3` uses types
-and predicates defined in `K`.
+\note Internal constructions (projections) are used in the predicate and
+construction functors of this class. If `K` is a model of `Kernel` providing exact
+constructions or if `K` is a `CGAL::Filtered_kernel` (such as for
+`CGAL::Exact_predicates_inexact_constructions_kernel`), this class automatically
+provides exact predicates.
 
 \cgalModels The class is a model of several 2D triangulation traits class concepts,
   except that it does not provide the type and constructors
@@ -33,6 +34,7 @@ and predicates defined in `K`.
 \cgalModels `AnalyticWeightTraits_2`
 \cgalModels `BarycentricTraits_2`
 
+\sa `CGAL::Projection_traits_3`
 */
 template< typename K >
 class Projection_traits_xy_3 {

Kernel_23/doc/Kernel_23/Concepts/FunctionObjectConcepts.h

@@ -8898,7 +8898,7 @@ class LessXYZ_3 {
 
   /*!
     returns true iff the \f$ x\f$-coordinate of `p` is smaller than the
-    \f$ x\f$-coordinate of `q` or if the are the same and
+    \f$ x\f$-coordinate of `q` or if they are the same and
     the \f$ y\f$-coordinate of `p` is smaller than the \f$ y\f$-coordinate of `q`, or,
     if both \f$ x\f$- and \f$ y\f$- coordinate are identical and
     the \f$ z\f$-coordinate of `p` is smaller than the \f$ z\f$-coordinate of `q`.
@@ -8928,7 +8928,7 @@ class LessXY_2 {
 
   /*!
     returns true iff the \f$ x\f$-coordinate of `p` is smaller than the
-    \f$ x\f$-coordinate of `q` or if the are the same and
+    \f$ x\f$-coordinate of `q` or if they are the same and
     the \f$ y\f$-coordinate of `p` is smaller than the \f$ y\f$-coordinate of `q`.
   */
   bool operator()(const Kernel::Point_2&p,
@@ -8957,7 +8957,7 @@ class LessXY_3 {
 
   /*!
     returns true iff the \f$ x\f$-coordinate of `p` is smaller than the
-    \f$ x\f$-coordinate of `q` or if the are the same and
+    \f$ x\f$-coordinate of `q` or if they are the same and
     the \f$ y\f$-coordinate of `p` is smaller than the \f$ y\f$-coordinate of `q`.
   */
   bool operator()(const Kernel::Point_3&p,
@@ -9040,7 +9040,7 @@ class LessYX_2 {
 
   /*!
     returns true iff the \f$ y\f$-coordinate of `p` is smaller than the
-    \f$ y\f$-coordinate of `q` or if the are the same and
+    \f$ y\f$-coordinate of `q` or if they are the same and
     the \f$ x\f$-coordinate of `p` is smaller than the \f$ x\f$-coordinate of `q`.
   */
   bool operator()(const Kernel::Point_2&p,

Kernel_23/doc/Kernel_23/Doxyfile.in

@@ -2,3 +2,4 @@
 
 PROJECT_NAME = "CGAL ${CGAL_DOC_VERSION} - 2D and 3D Linear Geometry Kernel"
 EXAMPLE_PATH              +=  ${CGAL_Filtered_kernel_EXAMPLE_DIR}
+EXAMPLE_PATH              +=  ${CGAL_Triangulation_2_EXAMPLE_DIR}

Kernel_23/doc/Kernel_23/PackageDescription.txt

@@ -71,6 +71,7 @@
 - `CGAL::Simple_cartesian<FieldNumberType>`
 - `CGAL::Simple_homogeneous<RingNumberType>`
 - `CGAL::Projection_traits_xy_3<K>`
+- `CGAL::Projection_traits_3<K>`
 
 \cgalCRPSection{Predefined Kernels}
 

Kernel_23/doc/Kernel_23/examples.txt

@@ -13,4 +13,5 @@
 \example Kernel_23/points_and_segment.cpp
 \example Kernel_23/surprising.cpp
 \example Kernel_23/exact.cpp
+\example Triangulation_2/triangulation_projection_traits.cpp
 */

Triangulation_2/include/CGAL/Triangulation_2/internal/Triangulation_2_filtered_projection_traits_3.h → Kernel_23/include/CGAL/Kernel_23/internal/Filtered_projection_traits_3.h

@@ -5,42 +5,39 @@
 //
 // $URL$
 // $Id$
-// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-Commercial
+// SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-Commercial
 //
 //
 // Author(s)     : Laurent Rineau
 
 
-#ifndef CGAL_INTERNAL_TRIANGULATION_2_FILTERED_PROJECTION_TRAITS_3_H
-#define CGAL_INTERNAL_TRIANGULATION_2_FILTERED_PROJECTION_TRAITS_3_H
+#ifndef CGAL_INTERNAL_FILTERED_PROJECTION_TRAITS_3_H
+#define CGAL_INTERNAL_FILTERED_PROJECTION_TRAITS_3_H
 
-#include <CGAL/license/Triangulation_2.h>
-
-
-#include <CGAL/Triangulation_2/internal/Triangulation_2_projection_traits_base_3.h>
+#include <CGAL/Kernel_23/internal/Projection_traits_base_3.h>
 #include <CGAL/Filtered_predicate_with_state.h>
 
 namespace CGAL {
 
 template < class Filtered_kernel >
-class Triangulation_2_filtered_projection_traits_3
-  : public Triangulation_2_projection_traits_base_3<Filtered_kernel>
+class Filtered_projection_traits_3
+  : public Projection_traits_base_3<Filtered_kernel>
 {
   typedef Filtered_kernel K;
-  typedef Triangulation_2_filtered_projection_traits_3<K> Self;
-  typedef Triangulation_2_projection_traits_base_3<K> Base;
+  typedef Filtered_projection_traits_3<K> Self;
+  typedef Projection_traits_base_3<K> Base;
 
   typedef typename K::Exact_kernel Exact_kernel;
   typedef typename K::Approximate_kernel Approximate_kernel;
   typedef typename K::C2E C2E;
   typedef typename K::C2F C2F;
 
 public:
-  typedef Triangulation_2_projection_traits_base_3<Exact_kernel> Exact_traits;
-  typedef Triangulation_2_projection_traits_base_3<Approximate_kernel> Filtering_traits;
+  typedef Projection_traits_base_3<Exact_kernel> Exact_traits;
+  typedef Projection_traits_base_3<Approximate_kernel> Filtering_traits;
 
 public:
-  explicit Triangulation_2_filtered_projection_traits_3(const typename K::Vector_3& n)
+  explicit Filtered_projection_traits_3(const typename K::Vector_3& n)
     : Base(n)
   {
   }
@@ -73,9 +70,9 @@ class Triangulation_2_filtered_projection_traits_3
   CGAL_TRIANGULATION_2_PROJ_TRAITS_FILTER_PRED(Compare_y_2,
                                                compare_y_2_object,
                                                base2)
-}; // end class Triangulation_2_projection_traits_base_3<Filtered_kernel>
+}; // end class Projection_traits_base_3<Filtered_kernel>
 
 } // end namespace CGAL
 
 
-#endif // CGAL_INTERNAL_TRIANGULATION_2_FILTERED_PROJECTION_TRAITS_3_H
+#endif // CGAL_INTERNAL_FILTERED_PROJECTION_TRAITS_3_H

Kernel_23/include/CGAL/Kernel_23/internal/Projection_traits_3.h

@@ -833,6 +833,8 @@ class Power_side_of_oriented_power_circle_projected_3
   }
 };
 
+// This is for projection traits along a specific canonical plane (xy, yz, xz)
+// The generic class for an arbitrary normal is CGAL::Projection_traits_3<K> (not in `internal`)
 template < class R, int dim >
 class Projection_traits_3 {
 public:

Triangulation_2/include/CGAL/Triangulation_2/internal/Triangulation_2_projection_traits_base_3.h → Kernel_23/include/CGAL/Kernel_23/internal/Projection_traits_base_3.h

@@ -5,17 +5,14 @@
 //
 // $URL$
 // $Id$
-// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-Commercial
+// SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-Commercial
 //
 //
 // Author(s)     : Laurent Rineau
 
 
-#ifndef CGAL_INTERNAL_TRIANGULATION_2_PROJECTION_TRAITS_BASE_3_H
-#define CGAL_INTERNAL_TRIANGULATION_2_PROJECTION_TRAITS_BASE_3_H
-
-#include <CGAL/license/Triangulation_2.h>
-
+#ifndef CGAL_INTERNAL_PROJECTION_TRAITS_BASE_3_H
+#define CGAL_INTERNAL_PROJECTION_TRAITS_BASE_3_H
 
 #include <CGAL/Profile_timer.h>
 #include <CGAL/intersections.h>
@@ -379,17 +376,17 @@ class Less_xy_along_axis
 
 
 template < class Kernel >
-class Triangulation_2_projection_traits_base_3
+class Projection_traits_base_3
 {
-  typedef Triangulation_2_projection_traits_base_3<Kernel> Self;
+  typedef Projection_traits_base_3<Kernel> Self;
 
   typename Kernel::Vector_3 n, b1, b2;
 
 public:
   typedef typename Kernel::Vector_3 Vector_3;
 
 
-  explicit Triangulation_2_projection_traits_base_3(const Vector_3& n_)
+  explicit Projection_traits_base_3(const Vector_3& n_)
     : n(n_)
   {
     typedef typename Kernel::FT FT;
@@ -589,8 +586,8 @@ class Triangulation_2_projection_traits_base_3
     return Projection_to_plan(plane_point, *this);
   }
 
-}; // end class Triangulation_2_projection_traits_base_3<Kernel>
+}; // end class Projection_traits_base_3<Kernel>
 
 } // end namespace CGAL
 
-#endif // CGAL_INTERNAL_TRIANGULATION_2_PROJECTION_TRAITS_BASE_3_H
+#endif // CGAL_INTERNAL_PROJECTION_TRAITS_BASE_3_H

Kernel_23/include/CGAL/Projection_traits_3.h

@@ -0,0 +1,47 @@
+// Copyright (c) 2009  GeometryFactory (France)
+// All rights reserved.
+//
+// This file is part of CGAL (www.cgal.org).
+//
+// $URL$
+// $Id$
+// SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-Commercial
+//
+//
+// Author(s)     : Laurent Rineau
+
+
+#ifndef CGAL_PROJECTION_TRAITS_3_H
+#define CGAL_PROJECTION_TRAITS_3_H
+
+#include <CGAL/Kernel_23/internal/Filtered_projection_traits_3.h>
+
+namespace CGAL {
+
+// This declaration is needed to break the cyclic dependency.
+template < class Filtered_kernel >
+class Filtered_projection_traits_3;
+
+template <class Kernel, bool Has_filtered_predicates=Kernel::Has_filtered_predicates>
+class Projection_traits_3
+  : public Projection_traits_base_3<Kernel>
+{
+public:
+  explicit Projection_traits_3(const typename Kernel::Vector_3& n_)
+    : Projection_traits_base_3<Kernel>(n_)
+  {}
+};
+
+template <class Kernel>
+class Projection_traits_3<Kernel, true>
+  : public Filtered_projection_traits_3<Kernel>
+{
+public:
+  explicit Projection_traits_3(const typename Kernel::Vector_3& n_)
+    : Filtered_projection_traits_3<Kernel>(n_)
+  {}
+};
+
+} // namespace CGAL
+
+#endif // CGAL_PROJECTION_TRAITS_3_H

Linear_cell_complex/demo/Linear_cell_complex/typedefs.h

@@ -14,7 +14,7 @@
 
 #include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
 
-#include <CGAL/Triangulation_2_projection_traits_3.h>
+#include <CGAL/Projection_traits_3.h>
 #include <CGAL/Triangulation_vertex_base_with_info_2.h>
 #include <CGAL/Triangulation_face_base_with_info_2.h>
 #include <CGAL/Constrained_Delaunay_triangulation_2.h>
@@ -178,7 +178,7 @@ struct Face_info {
   bool is_process;
 };
 
-typedef CGAL::Triangulation_2_projection_traits_3<CGAL::Exact_predicates_inexact_constructions_kernel> P_traits;
+typedef CGAL::Projection_traits_3<CGAL::Exact_predicates_inexact_constructions_kernel> P_traits;
 typedef CGAL::Triangulation_vertex_base_with_info_2<Vertex_info, P_traits> Vb;
 
 typedef CGAL::Triangulation_face_base_with_info_2<Face_info,P_traits> Fb1;

Linear_cell_complex/examples/Linear_cell_complex/basic_viewer.h

@@ -22,7 +22,7 @@
 #include <QGLBuffer>
 #include <QOpenGLShaderProgram>
 
-#include <CGAL/Triangulation_2_projection_traits_3.h>
+#include <CGAL/Projection_traits_3.h>
 #include <CGAL/Triangulation_vertex_base_with_info_2.h>
 #include <CGAL/Triangulation_face_base_with_info_2.h>
 #include <CGAL/Constrained_Delaunay_triangulation_2.h>
@@ -211,7 +211,7 @@ class Basic_viewer : public CGAL::QGLViewer, public QOpenGLFunctions
     bool is_process;
   };
 
-  typedef CGAL::Triangulation_2_projection_traits_3<CGAL::Exact_predicates_inexact_constructions_kernel> P_traits;
+  typedef CGAL::Projection_traits_3<CGAL::Exact_predicates_inexact_constructions_kernel> P_traits;
   typedef CGAL::Triangulation_vertex_base_with_info_2<Vertex_info, P_traits> Vb;
 
   typedef CGAL::Triangulation_face_base_with_info_2<Face_info, P_traits> Fb1;

Mesh_2/test/Mesh_2/test_mesh_projection_traits.cpp

@@ -3,12 +3,12 @@
 #include <CGAL/Delaunay_mesher_2.h>
 #include <CGAL/Delaunay_mesh_face_base_2.h>
 #include <CGAL/Delaunay_mesh_size_criteria_2.h>
-#include <CGAL/Triangulation_2_projection_traits_3.h>
+#include <CGAL/Projection_traits_3.h>
 
 #include <iostream>
 
 typedef CGAL::Exact_predicates_inexact_constructions_kernel K1;
-typedef CGAL::Triangulation_2_projection_traits_3<K1> K;
+typedef CGAL::Projection_traits_3<K1> K;
 typedef CGAL::Triangulation_vertex_base_2<K> Vb;
 typedef CGAL::Delaunay_mesh_face_base_2<K> Fb;
 typedef CGAL::Triangulation_data_structure_2<Vb, Fb> Tds;