mirror of https://github.com/CGAL/cgal
additional pass on the user manual
In particular, @sloriot, I have added the subsection _Representation of Piecewise Linear Complexes_, to talk about face IDs, among other things.
This commit is contained in:
Laurent Rineau
parent
97d0ece4c8
commit
2db51dbc85
|
|
@ -12,70 +12,72 @@ namespace CGAL {
|
|||
\image latex vase_cdt.png
|
||||
<BR>
|
||||
|
||||
\section CT_3_CCDT_3 Conforming Delaunay Triangulations in 3D
|
||||
\section CT_3_CCDT_3 Constrained Triangulations in 3D
|
||||
|
||||
3D triangulations are a way to partition space, which is useful in many applications.
|
||||
Sometimes, we want specific faces to appear in the output, for example, to preserve sharp features.
|
||||
3D triangulations partition space and are useful in many applications. In some cases, it is
|
||||
important to ensure that specific faces, such as sharp features, are preserved in the output.
|
||||
When a triangulation exactly respects these constraints, it is called a _constrained_ triangulation.
|
||||
In some cases, it is possible to honor the geometry of the constraints but not their combinatorics;
|
||||
additional points must be inserted—this is called a _conforming_ triangulation.
|
||||
However, it is sometimes only possible to preserve the geometry of the constraints, 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 that constructs conforming triangulations of
|
||||
3D polygonal constraints. In particular, it requires that these piecewise linear constraints
|
||||
are part of a _Piecewise Linear Complex_ (PLC). The type of produced triangulations is
|
||||
`Triangulation_3`, described in the chapter \ref PkgTriangulation3.
|
||||
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_ (PLC). The resulting triangulations are of type `Triangulation_3`,
|
||||
as described in the chapter \ref PkgTriangulation3.
|
||||
|
||||
The problem is described by Cohen-Steiner et al. \cgalCite{cgal:cohen2002conforming},
|
||||
and by Si \cgalCite{cgal:si2008cdt3}.
|
||||
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's work \cgalCite{cgal:si2008cdt3} presents an algorithm for computing conforming constrained
|
||||
Delaunay triangulations in 3D.
|
||||
|
||||
\section CT_3_definitions Definitions
|
||||
|
||||
In this section, we define the main concepts that have to be understood to use this package.
|
||||
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_ (PLC) is the 3-dimensional generalization of a
|
||||
planar straight-line graph. It is a finite set of vertices, edges, and polygons (faces)
|
||||
that satisfies the following properties:
|
||||
A _Piecewise Linear Complex_ (PLC) is the three-dimensional generalization of a
|
||||
planar straight-line graph. It consists of a finite set of vertices, edges, and polygons (faces)
|
||||
that satisfy the following properties:
|
||||
|
||||
- The vertices and edges in the PLC form a simplicial complex: two edges may intersect
|
||||
only at a common vertex.
|
||||
- For each polygon in the PLC, its boundary is a union of edges in the PLC.
|
||||
- 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 vertices and edges of the PLC form a simplicial complex: two edges may intersect only at a
|
||||
shared vertex.
|
||||
- The boundary of each polygon in the PLC is a union of edges from the PLC.
|
||||
- If two polygons in the PLC intersect, their intersection is a union of edges and vertices from the
|
||||
PLC. In particular, the interiors of two polygons cannot overlap.
|
||||
|
||||
The polygons can be non-convex, have holes, and arbitrarily many boundary segments.
|
||||
Polygons in a PLC may be non-convex, may have holes, and may have arbitrarily many boundary segments.
|
||||
|
||||
\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.
|
||||
A Piecewise Linear Complex composed of planar faces connected by edges and vertices.
|
||||
\cgalFigureCaptionEnd
|
||||
|
||||
|
||||
\subsection CT_3_CDT Conforming Constrained Delaunay Triangulation
|
||||
|
||||
The goal of the algorithms developed in this package is to compute a constrained Delaunay
|
||||
mesh containing a given set of polygonal constraints in 3D as sub-complex.
|
||||
mesh 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
|
||||
of the triangulation contains no vertex in its interior (see package \ref PkgTriangulation3
|
||||
in the triangulation contains no vertex in its interior (see package \ref PkgTriangulation3
|
||||
for more details on Delaunay triangulations).
|
||||
|
||||
A _constrained Delaunay triangulation_ of a PLC is a constrained triangulation which is as much
|
||||
Delaunay as possible, given that some facets 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 of the interior of the simplex \f$s\f$. Two points are _visible_
|
||||
if the open line segment joining them does not intersect any polygon of the PLC, with the exception
|
||||
of polygons that are coplanar with the segment.
|
||||
A _constrained Delaunay triangulation_ of a PLC is a constrained triangulation that is as close as
|
||||
possible to being Delaunay, given that some facets 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 polygon of the PLC, except for 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önhardt polyhedron \cgalCite{schonhardt1928zerlegung},
|
||||
\cgalCite{b-ip-48a}, that requires the addition of
|
||||
Steiner vertices to be tetrahedralizable (see \cgalFigureRef{CT_3_schonhardt_fig}).
|
||||
In 3D, constrained triangulations do not always exist. This can be demonstrated using the example of
|
||||
Schönhardt polyhedra \cgalCite{schonhardt1928zerlegung}, \cgalCite{b-ip-48a}, which require the
|
||||
addition of Steiner vertices to become tetrahedralizable (see \cgalFigureRef{CT_3_schonhardt_fig}).
|
||||
|
||||
\cgalFigureAnchor{CT_3_schonhardt_fig}
|
||||
<center>
|
||||
|
|
@ -86,19 +88,16 @@ A Schönhardt polyhedron.
|
|||
\cgalFigureCaptionEnd
|
||||
|
||||
|
||||
Shewchuk \cgalCite{cgal:shewchuk1998condition} showed that for any PLC,
|
||||
there exists another PLC that is a refined version of the original one,
|
||||
and admits a constrained Delaunay triangulation.
|
||||
The refined PLC is obtained by adding Steiner vertices on the input edges and polygons,
|
||||
and the constrained triangulation built on this PLC is called
|
||||
a _conforming constrained Delaunay triangulation_.
|
||||
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 polygons. The constrained triangulation
|
||||
built on this refined PLC is known as a _conforming constrained Delaunay triangulation_.
|
||||
|
||||
The algorithm implemented in this package is based on the work of
|
||||
Hang Si \cgalCite{si2005meshing}, \cgalCite{si2015tetgen}.
|
||||
Steiner vertices are added on input edges and input polygons
|
||||
of the PLC to make it tetrahedralizable.
|
||||
The algorithm implemented in this package is based on the work of Hang Si \cgalCite{si2005meshing},
|
||||
\cgalCite{si2015tetgen}. Steiner vertices are inserted on the input edges and polygons of the PLC to
|
||||
ensure it can be tetrahedralized.
|
||||
|
||||
\cgalFigureRef{CT_3_plc2cdt_fig} shows an example of a conforming constrained
|
||||
\cgalFigureRef{CT_3_plc2cdt_fig} illustrates an example of a conforming constrained
|
||||
Delaunay triangulation constructed from a PLC.
|
||||
|
||||
\cgalFigureAnchor{CT_3_plc2cdt_fig}
|
||||
|
|
@ -114,53 +113,83 @@ Right: the same CCDT seen with cutplane.
|
|||
|
||||
\section CT_3_api 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.
|
||||
|
||||
Since any polyhedron is a PLC, any model of `FaceListGraph`—such as `CGAL::Surface_mesh<P>`—can be
|
||||
used to represent a PLC. In this case, the polygons of the PLC correspond to the faces of the
|
||||
surface mesh, and the edges of the PLC correspond to the edges of the surface mesh. However, PLCs
|
||||
represented in this way are restricted to be manifold, and their polygons cannot have holes.
|
||||
|
||||
PLCs can also be represented as polygon soups: a collection of vertices and a set of polygons, where
|
||||
each polygon is defined by an ordered list of vertices. For a polygon soup to represent a valid PLC,
|
||||
its polygons must satisfy the properties outlined in the previous section. This approach allows for
|
||||
the representation of non-manifold geometries, but note that polygons in a polygon soup cannot have
|
||||
holes.
|
||||
|
||||
To represent a PLC with polygons that have holes, this package allows the use of a property map that
|
||||
associates a _patch_ identifier with each polygon of the face graph or polygon soup. Polygons
|
||||
sharing the same patch identifier are considered part of the same _surface patch_, which may include
|
||||
holes. If these patches are planar and satisfy the properties of a PLC, they can be used to build a
|
||||
conforming constrained Delaunay triangulation. When a face patch property map is provided:
|
||||
- the vertices of the PLC are the vertices of the surface mesh or polygon soup,
|
||||
- the edges of the PLC are the edges of the surface mesh or polygon soup _that are on the border
|
||||
of patches_,
|
||||
- the polygons (facets) of the PLC are the patches defined as above.
|
||||
|
||||
\subsection CT_3_api_classes Classes
|
||||
|
||||
This package provides one main class `CGAL::Conforming_constrained_Delaunay_triangulation_3`
|
||||
that represents a 3D conforming constrained Delaunay triangulation.
|
||||
The class is templated by the geometric traits class and the underlying triangulation class.
|
||||
The other classes that are provided are secondary classes that define the
|
||||
vertex and cell types and metadata that constitute the triangulation.
|
||||
This package provides a primary class, `CGAL::Conforming_constrained_Delaunay_triangulation_3`,
|
||||
which represents a 3D conforming constrained Delaunay triangulation. This class is templated on 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.
|
||||
|
||||
\subsection CT_3_api_functions Functions
|
||||
|
||||
Some helper constructor functions, like `CGAL::make_conforming_constrained_Delaunay_triangulation_3()`,
|
||||
are provided to create a `CGAL::Conforming_constrained_Delaunay_triangulation_3` object.
|
||||
Several helper constructor functions are provided, such as \link
|
||||
PkgConstrainedTriangulation3FunctionsPolygonSoupOrMesh
|
||||
`CGAL::make_conforming_constrained_Delaunay_triangulation_3()`\endlink, to facilitate the creation
|
||||
of a `CGAL::Conforming_constrained_Delaunay_triangulation_3` object from various types of input
|
||||
data.
|
||||
|
||||
\section CT_3_examples Examples
|
||||
|
||||
\subsection CT_3_example_ccdt Build a Conforming Constrained Delaunay Triangulation
|
||||
|
||||
The following example demonstrates how to use the helper constructor function
|
||||
`CGAL::make_conforming_constrained_Delaunay_triangulation_3()` to create a
|
||||
conforming constrained Delaunay triangulation from a given PLC.
|
||||
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 piecewise linear complex (PLC).
|
||||
|
||||
\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
|
||||
|
||||
It is also possible to create a conforming constrained Delaunay triangulation
|
||||
from a polygon soup, i.e., a set of polygons for which the connectivity is not known a priori.
|
||||
This example demonstrates how to build such a triangulation.
|
||||
You can also construct a conforming constrained Delaunay triangulation from a polygon soup—that is,
|
||||
a collection of polygons where the connectivity information is not explicitly provided. The
|
||||
following example demonstrates how to build such a triangulation from a polygon soup input.
|
||||
|
||||
\cgalExample{Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3_from_soup.cpp }
|
||||
|
||||
|
||||
\subsection CT_3_example_ccdt_fpmap Build a Conforming Constrained Delaunay Triangulation with Known Face Patches
|
||||
|
||||
When the user knows a priori the set of patch ids that he wants to attach to faces, this information
|
||||
can be used and kept valid through the construction of the conforming constrained
|
||||
Delaunay triangulation.
|
||||
If the user already knows the set of patch IDs to associate with each face, this information can be
|
||||
provided and preserved throughout the construction of the conforming constrained Delaunay
|
||||
triangulation.
|
||||
|
||||
The following example demonstrates how to detect surface patches separated by sharp edges
|
||||
and use this surface segmentation in the tetrahedrization process.
|
||||
The following example demonstrates how to detect surface patches separated by sharp edges and use
|
||||
this segmentation during the tetrahedralization process.
|
||||
|
||||
When this parameter is used, the 3D triangulation constrained faces indices (available with
|
||||
`CGAL::Conforming_constrained_Delaunay_triangulation_cell_data_3::face_constraint_index() `
|
||||
)
|
||||
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 polygon.
|
||||
When this parameter is specified, the face constraint indices in the 3D triangulation (accessible
|
||||
via `CGAL::Conforming_constrained_Delaunay_triangulation_cell_data_3::face_constraint_index()`) are
|
||||
set to the corresponding patch IDs from the property map. If this parameter is not provided, each
|
||||
input polygon is assigned a unique face index.
|
||||
|
||||
\cgalExample{Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3_fpmap.cpp}
|
||||
|
||||
|
|
@ -177,8 +206,9 @@ Right: The corresponding conforming constrained Delaunay triangulation using the
|
|||
|
||||
\subsection CT_3_examples_preprocessing Preprocessing the Input Mesh for Conforming Constrained Delaunay Triangulations
|
||||
|
||||
The input mesh must be a valid triangulated surface mesh, i.e., it must not have self-intersections.
|
||||
Numerous preprocessing functions are available in the \ref PkgPolygonMeshProcessing package _to enforce these preconditions_.
|
||||
The input mesh must be a valid surface mesh, i.e., it must not have self-intersections. Numerous
|
||||
preprocessing functions are available in the \ref PkgPolygonMeshProcessing package _to enforce these
|
||||
preconditions_.
|
||||
|
||||
\subsubsection CT_3_example_ccdt_autorefinement Autorefinement of the Input Mesh
|
||||
|
||||
|
|
@ -190,35 +220,35 @@ when it is self-intersecting.
|
|||
|
||||
\subsubsection CT_3_example_self_intersecting_non_triangles Non-Triangulated Self-Intersecting Input Mesh
|
||||
|
||||
The following example shows how to build a conforming constrained Delaunay triangulation from
|
||||
an input mesh that is not triangulated, and (possibly) self-intersecting.
|
||||
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.
|
||||
|
||||
The function `CGAL::Polygon_mesh_processing::does_self_intersect()` is used to check for self-intersections,
|
||||
but this function can be used only on triangulated meshes. It is therefore necessary to triangulate
|
||||
the input mesh before checking for self-intersections, using the function
|
||||
`CGAL::Polygon_mesh_processing::triangulate_faces()`.
|
||||
The function `CGAL::Polygon_mesh_processing::does_self_intersect()` can be used to detect self-intersections,
|
||||
but it requires the input mesh to be triangulated. Therefore, the input mesh must first be triangulated
|
||||
using `CGAL::Polygon_mesh_processing::triangulate_faces()` before performing the self-intersection check.
|
||||
|
||||
The triangulated version of the mesh is then kept in case of self-intersections,
|
||||
to use the `CGAL::Polygon_mesh_processing::autorefine()` function to remove the self-intersections.
|
||||
If self-intersections are found, the triangulated mesh is converted into a triangle soup, which can then be
|
||||
processed with `CGAL::Polygon_mesh_processing::autorefine_triangle_soup()` to remove the self-intersections.
|
||||
|
||||
\cgalExample{Constrained_triangulation_3/ccdt_3_preprocessing.cpp }
|
||||
|
||||
|
||||
\subsection CT_3_example_remesh Remeshing a Conforming Constrained Delaunay Triangulation
|
||||
|
||||
Once the triangulation is built, it is possible to remesh it using the
|
||||
`CGAL::tetrahedral_isotropic_remeshing()` function from the \ref PkgTetrahedralRemeshing package
|
||||
to improve the quality of the mesh or adapt it to a given sizing field.
|
||||
After constructing the triangulation, you can improve its quality or adapt it to a specific sizing
|
||||
field by applying the `CGAL::tetrahedral_isotropic_remeshing()` function from the \ref
|
||||
PkgTetrahedralRemeshing package.
|
||||
|
||||
The following example shows how to remesh a conforming constrained Delaunay triangulation.
|
||||
The following example demonstrates how to remesh a conforming constrained Delaunay triangulation.
|
||||
|
||||
\cgalExample{Constrained_triangulation_3/remesh_constrained_Delaunay_triangulation_3.cpp }
|
||||
|
||||
|
||||
\section CT_3_design Implementation History
|
||||
|
||||
The first version of this package was implemented by Laurent Rineau, and published in 2025 in CGAL 6.1. It is based on the theoretical foundation provided by Hang Si's work on meshing algorithms
|
||||
\cgalCite{si2005meshing}, \cgalCite{si2015tetgen}.
|
||||
The initial version of this package was implemented by Laurent Rineau and released in
|
||||
\cgal 6.1 (2025). Its design and algorithms are grounded in the theoretical work of
|
||||
Hang Si on meshing algorithms \cgalCite{si2005meshing}, \cgalCite{si2015tetgen}.
|
||||
|
||||
*/
|
||||
} /* namespace CGAL */
|
||||
|
|
|
|||
|
|
@ -7,6 +7,7 @@ Property_map
|
|||
SMDS_3
|
||||
STL_Extension
|
||||
Stream_support
|
||||
Surface_mesh
|
||||
TDS_3
|
||||
Tetrahedral_remeshing
|
||||
Triangulation_3
|
||||
|
|
|
|||
Loading…
Reference in New Issue