namespace CGAL {
/*!

\mainpage User Manual
\anchor Chapter_CT_3
\anchor userchapterct3

\cgalAutoToc
\author Laurent Rineau and Jane Tournois

\cgalFigureAnchor{CT_3_pyramid_fig}
<img src="cdt_title_pyramid.png" style="max-width:60%;min-width=20%"/>
<BR>

\section CT_3_CCDT_3 Constrained Triangulations in 3D

3D triangulations partition space and are useful in many applications. In some cases, it is
important to ensure that specific faces, such as those representing the sharp features of an object, appear in the output.
When a triangulation exactly respects these constraints, it is called a _constrained_ triangulation.
However, it is sometimes only possible to preserve the geometry of the constraints, but not their exact
combinatorics. In such cases, additional points, called _Steiner_ _points_, must be inserted. This process
results in a _conforming_ triangulation.

This package implements an algorithm for constructing conforming triangulations of 3D polygonal
constraints. Specifically, it requires that these piecewise linear constraints are provided as a
_piecewise linear complex_&nbsp;(PLC). The resulting triangulations are of type `Triangulation_3`,
as described in the chapter \ref PkgTriangulation3.

The article by Cohen-Steiner et al. \cgalCite{cgal:cohen2002conforming} discusses the problem of
constructing conforming Delaunay triangulations and proposes an algorithm to address it.
Si et al.'s work \cgalCite{si2005meshing}, \cgalCite{cgal:si2008cdt3}, \cgalCite{si2015tetgen},
 presents an algorithm for computing conforming constrained
Delaunay triangulations in 3D.

\section CT_3_definitions Definitions

This section introduces the key concepts necessary to understand and use this package effectively.

\subsection CT_3_PLC Piecewise Linear Complex

A _piecewise linear complex_&nbsp;(PLC) is the three-dimensional generalization of a
planar straight-line graph. It consists of a finite set of vertices, edges, and polygonal faces
that satisfy the following properties:

- The vertices and edges of the PLC form a simplicial complex: two edges may intersect only at a
  shared vertex.
- The boundary of each polygonal face in the PLC is an ordered list of vertices from the PLC, forming
  one closed loop.
- Each polygonal face must be a simple polygon, i.e., its edges don't intersect,
  except consecutive edges, which intersect at their common vertex.
- Each polygonal face must be planar, meaning all its vertices lie on the same plane.
- Each polygonal face may be non-convex.
- Each polygonal face may have one or more holes, each of them also represented by an ordered list of vertices
  from the PLC, forming a closed loop.
- Polygonal holes may be non-convex.
- If two polygonal faces in the PLC intersect, their intersection is a union of edges and vertices from the
  PLC. In particular, the interiors of two polygonal faces cannot overlap.


\cgalFigureAnchor{CT_3_plc_fig}
<center>
<img src="plc.png" style="max-width:60%;"/>
</center>
\cgalFigureCaptionBegin{CT_3_plc_fig}
A piecewise linear complex, composed of planar faces connected by edges and vertices.
\cgalFigureCaptionEnd


\subsection CT_3_CDT Conforming Constrained Delaunay Triangulation

The algorithms developed in this package are designed to compute a constrained Delaunay
triangulation that contains a given set of polygonal constraints in 3D as a subcomplex.

A triangulation is a _Delaunay triangulation_ if the circumscribing sphere of any simplex
in the triangulation contains no vertex in its interior (see chapter \ref PkgTriangulation3
for more details on Delaunay triangulations).

A _constrained Delaunay triangulation_ of a PLC is a constrained triangulation that is as close as
possible to being Delaunay, given that some faces are marked as _constrained_. More precisely, a
triangulation is _constrained Delaunay_ if, for any simplex \f$s\f$ of the triangulation, the
interior of its circumscribing sphere contains no vertex of the triangulation that is _visible_ from
any point in the interior of the simplex \f$s\f$. Two points are _visible_ if the open line segment
joining them does not intersect any polygonal face of the PLC, except for polygonal faces that are coplanar with
the segment.

In 3D, constrained triangulations do not always exist. This can be demonstrated using the example of
Sch&ouml;nhardt polyhedra \cgalCite{s-udzvd-28} (see \cgalFigureRef{CT_3_schonhardt_fig}),
\cgalCite{b-ip-48a}. Shewchuk \cgalCite{cgal:shewchuk1998condition} demonstrated that for any PLC,
there exists a refined
version of the original PLC that admits a constrained Delaunay triangulation. This refinement is
achieved by adding Steiner vertices to the input edges and polygonal faces. The constrained triangulation
built on this refined PLC is known as a _conforming constrained Delaunay triangulation_ (CCDT for
short). \cgalFigureRef{CT_3_plc2cdt_fig} illustrates an example of a conforming constrained
Delaunay triangulation constructed from a PLC.


\cgalFigureAnchor{CT_3_schonhardt_fig}
<center>
<img src="schonhardt.png" style="max-width:25%;"/>
</center>
\cgalFigureCaptionBegin{CT_3_schonhardt_fig}
A Sch&ouml;nhardt polyhedron.
\cgalFigureCaptionEnd


\cgalFigureAnchor{CT_3_plc2cdt_fig}
<center>
<img src="plc_to_cdt.png" style="max-width:70%;"/>
</center>
\cgalFigureCaptionBegin{CT_3_plc2cdt_fig}
Left: PLC (360 vertices);
Right: CCDT (2452 vertices).
\cgalFigureCaptionEnd

The algorithm implemented in this package is based on the work of Hang Si et al., who developed particular
algorithms for constructing conforming constrained Delaunay triangulations from PLCs.
The corresponding implementation is designed to handle points whose coordinates
are floating-point numbers.
\cgalCite{si2005meshing}, \cgalCite{cgal:si2008cdt3}, \cgalCite{si2015tetgen}.


\section CT_3_design Software Design

\subsection CT_3_representation_of_PLCs Representation of Piecewise Linear Complexes

There is no universal or canonical way to represent all possible PLCs in \cgal.

Any polyhedral surface is a PLC, so any model of `FaceListGraph`, such as `CGAL::Surface_mesh`, can be
used to represent such a PLC.
In this representation, the geometric structure of the PLC is directly mapped to the elements
of the `CGAL::Surface_mesh`:
- vertices of the PLC geometrically correspond to vertices of the surface mesh,
- edges of the PLC correspond to edges of the surface mesh,
- and polygonal faces of the PLC correspond to faces of the surface mesh,
covering the surface of a geometric object.
However, PLCs represented in this way are limited to being
manifold (that is, each edge belongs to exactly two faces), and their faces cannot have holes.

A PLC can also be represented as a polygon soup: a collection of vertices and a set of polygons, where
each polygon is defined by an ordered list of vertices, without explicit connectivity information between
polygons. For a polygon soup to represent a valid PLC, its polygons must satisfy the
polygonal faces properties described
in the previous section. This approach allows for the representation of non-manifold geometries; however,
polygons in a polygon soup cannot have holes.

This package also provides a way to group polygonal faces into distinct surface patches using a property map,
named `plc_face_id`.
Each polygon can be assigned a _patch_ identifier, allowing multiple polygonal faces to form a continuous surface patch,
which may include holes. Some necessary conditions must be satisfied for these patches to be
used in the conforming constrained Delaunay triangulation construction:
- Each patch must be planar, meaning all polygonal faces in the patch lie on the same plane;
- The polygonal faces of the patch must not intersect except at their shared edges.

When this property map is provided, the input PLC is interpreted in terms of its polygonal faces,
edges and vertices as follows:
- Each polygonal face of the PLC is defined as the union of input polygons sharing the same patch identifier;
- The edges of the PLC are those from the surface mesh or polygon soup that satisfy one of the following conditions:
-- they are adjacent to only one polygonal face;
-- they are adjacent to two polygonal faces with different patch identifiers;
-- they are adjacent to more than two polygonal faces with differing patch identifiers, indicating non-manifold features of the PLC.
- The vertices of the PLC are the ones lying on the boundaries of surface patches in the original surface mesh or polygon soup.

\subsection CT_3_api API

This package provides a primary class, `CGAL::Conforming_constrained_Delaunay_triangulation_3`.
This class is templated by a
geometric traits class and an underlying triangulation class, allowing for flexibility and
customization.

In addition to the main class, the package includes several auxiliary classes that define the types
of vertices, cells, and associated metadata used within the triangulation. These supporting classes
enable users to extend or adapt the triangulation data structure to their specific needs.

Two overloads of the constructor function \link
PkgConstrainedTriangulation3FunctionsPolygonSoupOrMesh
`CGAL::make_conforming_constrained_Delaunay_triangulation_3()`\endlink are provided to facilitate the creation
of a `CGAL::Conforming_constrained_Delaunay_triangulation_3` object from either a surface mesh or a polygon soup.

\subsection CT_3_geomtraits Traits and Kernel Choice

The requirements for geometric objects and operations are specified by the traits class concept
`ConformingConstrainedDelaunayTriangulationTraits_3`. Any CGAL kernel is a model of this concept.
However, because this package builds upon the 3D Triangulation package, it inherits the requirement
that the traits class must provide exact predicates.

A key aspect of this algorithm is the creation of new points, known as Steiner points, which are
inserted on the segments and polygons forming the input PLC polygonal faces.
If a traits class with inexact constructions
is used, it cannot be guaranteed that these points will lie exactly on the intended segments or polygons.
As a result, the output will only approximate the input, with the accuracy limited by the rounding
of the computed Steiner points.

Furthermore, when using inexact constructions, the algorithm may fail if the input PLC contains
non-adjacent simplices that are too close to each other. In such cases, the triangulation process
will emit an error if the distance between simplices falls below an internally computed threshold.
An error message describing the involved simplices will be displayed on the standard output.
If the issue is caused by poorly shaped triangles, functions such as
`CGAL::Polygon_mesh_processing::remove_almost_degenerate_faces()` may help resolve the problem.

\section CT_3_examples Examples

\subsection CT_3_example_ccdt Build a Conforming Constrained Delaunay Triangulation

The following example illustrates how to use the helper function
`CGAL::make_conforming_constrained_Delaunay_triangulation_3()` to construct a conforming constrained
Delaunay triangulation from a given PLC.

The triangulation is saved in the MEDIT file format, using the
\link PkgCDT3IOFunctions `CGAL::IO::write_MEDIT()` \endlink function.

\cgalExample{Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3.cpp }


\subsection CT_3_example_ccdt_soup Build a Conforming Constrained Delaunay Triangulation from a Polygon Soup

You can also construct a conforming constrained Delaunay triangulation from a polygon soup.
The following example demonstrates how to create such a triangulation from a collection of polygons
without explicit connectivity information.

\cgalExample{Constrained_triangulation_3/ccdt_3_from_soup.cpp }


\subsection CT_3_example_ccdt_fimap Build a Conforming Constrained Delaunay Triangulation with Known Polygon Identifiers

If the user already knows the set of polygonal face identifiers to associate with each PLC face, this information can be
provided and preserved throughout the construction of the conforming constrained Delaunay
triangulation.

The following example demonstrates how to detect planar surface patches and remesh them as coarsely
as possible using
\link CGAL::Polygon_mesh_processing::remesh_planar_patches(const TriangleMeshIn&,PolygonMeshOut&,const NamedParametersIn&,const NamedParametersOut&) `CGAL::Polygon_mesh_processing::remesh_planar_patches()` \endlink
from the \ref PkgPolygonMeshProcessing package.
The resulting patches and segmentation are then used to build a conforming constrained Delaunay triangulation.

When the named parameter `plc_face_id` is specified, each constrained facet in the 3D triangulation
is assigned to the corresponding input PLC face, as identified by the provided property map.
If this parameter is not specified, each input polygonal face is assigned a unique face index.

Figure \cgalFigureRef{CT_3_ccdt_examples_fig} shows the benefit of using the `plc_face_id` property map.
On the last line of the figure, the input PLC is enriched with a segmentation of the planar faces,
provided via the `plc_face_id` property map. In the resulting conforming constrained Delaunay triangulation,
only the boundary edges of the PLC faces are constrained, while the other edges never get inserted as
edges of the 3D triangulation.

Without the `plc_face_id` property map, all edges of the PLC faces are constrained,
each PLC face is considered as a constraint,
possibly resulting in a 3D triangulation with surfaces that are more refined than necessary.

\cgalExample{Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3_fimap.cpp}

\cgalFigureRef{CT_3_ccdt_examples_fig} shows the input and output of this triangulation construction example.


\subsection CT_3_example_ccdt_region_growing_fimap Build a Conforming Constrained Delaunay Triangulation with Detected Polygon Identifiers

If the user does not know the set of polygonal face identifiers to associate with each PLC face, this information can be
automatically detected using the
\link CGAL::Polygon_mesh_processing::region_growing_of_planes_on_faces(const PolygonMesh& mesh,RegionMap region_map,const NamedParameters& np) `CGAL::Polygon_mesh_processing::region_growing_of_planes_on_faces()`\endlink
function from the \ref PkgPolygonMeshProcessing package.

The following example demonstrates how to detect planar surface patches and build a conforming
constrained Delaunay triangulation using the detected segmentation. The named parameter `plc_face_id`
is used to associate each facet of the triangulation with the corresponding input PLC face.

\cgalExample{Constrained_triangulation_3/ccdt_3_fimap_region_growing.cpp}


\subsection CT_3_examples_preprocessing Preprocessing the Input for Conforming Constrained Delaunay Triangulations

Given a PLC, the algorithms in this package can construct a conforming constrained Delaunay triangulation, provided
the input surface can be represented as a valid surface mesh or a collection of surface meshes,
and does not contain self-intersections.
Several preprocessing functions are available in the \ref PkgPolygonMeshProcessing package to help ensure these
preconditions are met.

The following example demonstrates how to construct a conforming constrained Delaunay triangulation from
an input mesh that is not triangulated and may contain self-intersections,
using autorefinement.

\cgalExample{Constrained_triangulation_3/ccdt_3_after_autorefinement.cpp }

The function
\link CGAL::Polygon_mesh_processing::does_self_intersect(const FaceRange&, const TriangleMesh&, const NamedParameters&) `CGAL::Polygon_mesh_processing::does_self_intersect()` \endlink
is used to detect self-intersections,
but it requires the input mesh to be triangulated. Therefore, the input mesh must first be triangulated
using
\link CGAL::Polygon_mesh_processing::triangulate_faces(FaceRange,PolygonMesh&,const NamedParameters&) `CGAL::Polygon_mesh_processing::triangulate_faces()`\endlink
before performing the self-intersection check.

If self-intersections are found, the triangulated mesh is converted into a triangle soup, which is then
processed with
\link CGAL::Polygon_mesh_processing::autorefine_triangle_soup(PointRange&,TriangleRange&,const NamedParameters&) `CGAL::Polygon_mesh_processing::autorefine_triangle_soup()`\endlink
to resolve the self-intersections.


\subsection CT_3_example_remesh Remeshing a Conforming Constrained Delaunay Triangulation

After constructing the triangulation, you can improve its quality or adapt it to a specific sizing
field by applying the
\link CGAL::tetrahedral_isotropic_remeshing(CGAL::Triangulation_3<Traits, TDS, SLDS>&, const SizingFunction&, const NamedParameters&) `CGAL::tetrahedral_isotropic_remeshing()`\endlink
 function from the \ref PkgTetrahedralRemeshing package.

The following example demonstrates how to remesh a conforming constrained Delaunay triangulation.

\cgalExample{Constrained_triangulation_3/remesh_constrained_Delaunay_triangulation_3.cpp }


\subsection CT_3_examples_figure Figures

The following table of figures (\cgalFigureRef{CT_3_ccdt_examples_fig}) illustrates some results of the examples provided in this package.
The left column shows the input PLC, while the right column displays the resulting conforming
constrained Delaunay triangulation.

From top to bottom, the lines show different input PLC, from the same input triangulated surface and,
for each of them, the resulting conforming constrained Delaunay triangulation.
The input data are:
<ul>
<li> the input PLC with no preprocessing;
<li> the input PLC with a segmentation of the surface patches done with `CGAL::Polygon_mesh_processing::region_growing_of_planes_on_faces()` as done in example \ref CT_3_example_ccdt_region_growing_fimap;</li>
<li> the input PLC, remeshed and not triangulated, with a segmentation of the surface patches, done with `CGAL::Polygon_mesh_processing::remesh_planar_patches()` as in example \ref CT_3_example_ccdt_fimap;</li>
<li> the input PLC, isotropically remeshed, with a segmentation of the surface patches, done with `CGAL::Polygon_mesh_processing::region_growing_of_planes_on_faces()` as in example \ref CT_3_example_ccdt_region_growing_fimap.</li>
</ul>

On the fourth line, the input PLC is remeshed using `CGAL::Polygon_mesh_processing::isotropic_remeshing()`.
The resulting conforming constrained Delaunay triangulation contains fewer vertices than the input
remeshed and segmented input PLC. This reduction occurs because only the boundary edges of the PLC faces
are marked as constraints in the triangulation;
interior edges that do not lie on the boundaries of surface patches (as defined by `plc_face_id`) are ignored.
As a result, these non-boundary edges are omitted from the triangulation, leading to a coarser triangulation.

\cgalFigureAnchor{CT_3_ccdt_examples_fig}
<center>
<img src="ccdt_examples.png" style="max-width:50%;"/>
</center>
\cgalFigureCaptionBegin{CT_3_ccdt_examples_fig}
A collection of conforming constrained Delaunay triangulations built from different inputs.
The left column shows the input PLC, while the right column displays the resulting 3D triangulation.<br>
\cgalFigureCaptionEnd


\section CT_3_history Implementation History

The initial version of this package was implemented by Laurent Rineau and released in
\cgal&nbsp;6.1&nbsp;(2025). Jane Tournois contributed to the documentation and helped improve the API.
The package design and algorithms are grounded in the theoretical work of
Hang&nbsp;Si et al. on meshing algorithms&nbsp;\cgalCite{si2005meshing},&nbsp;\cgalCite{si2015tetgen}.

*/
} /* namespace CGAL */
