songsenand
/
cgal
mirror of https://github.com/CGAL/cgal
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 2025-05-22 15:23:23 +02:00
parent 97d0ece4c8
commit 2db51dbc85
2 changed files with 116 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
Constrained_triangulation_3/doc/Constrained_triangulation_3/Constrained_triangulation_3.txt
View File

@ -12,70 +12,72 @@ namespace CGAL {
\image latex vase_cdt.png \image latex vase_cdt.png
<BR> <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. 3D triangulations partition space and are useful in many applications. In some cases, it is
Sometimes, we want specific faces to appear in the output, for example, to preserve sharp features. 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. 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; However, it is sometimes only possible to preserve the geometry of the constraints, not their exact
additional points must be inserted—this is called a _conforming_ triangulation. 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 This package implements an algorithm for constructing conforming triangulations of 3D polygonal
3D polygonal constraints. In particular, it requires that these piecewise linear constraints constraints. Specifically, it requires that these piecewise linear constraints are provided as a
are part of a _Piecewise Linear Complex_&nbsp;(PLC). The type of produced triangulations is _Piecewise Linear Complex_&nbsp;(PLC). The resulting triangulations are of type `Triangulation_3`,
`Triangulation_3`, described in the chapter \ref PkgTriangulation3. as described in the chapter \ref PkgTriangulation3.
The problem is described by Cohen-Steiner et al. \cgalCite{cgal:cohen2002conforming}, The article by Cohen-Steiner et al. \cgalCite{cgal:cohen2002conforming} discusses the problem of
and by Si \cgalCite{cgal:si2008cdt3}. 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 \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 \subsection CT_3_PLC Piecewise Linear Complex
A _Piecewise Linear Complex_ (PLC) is the 3-dimensional generalization of a A _Piecewise Linear Complex_ (PLC) is the three-dimensional generalization of a
planar straight-line graph. It is a finite set of vertices, edges, and polygons (faces) planar straight-line graph. It consists of a finite set of vertices, edges, and polygons (faces)
that satisfies the following properties: that satisfy the following properties:
- The vertices and edges in the PLC form a simplicial complex: two edges may intersect - The vertices and edges of the PLC form a simplicial complex: two edges may intersect only at a
only at a common vertex. shared vertex.
- For each polygon in the PLC, its boundary is a union of edges in the PLC. - 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 - If two polygons in the PLC intersect, their intersection is a union of edges and vertices from the
in the PLC. In particular, the interiors of two polygons cannot intersect. 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} \cgalFigureAnchor{CT_3_plc_fig}
<center> <center>
<img src="plc.png" style="max-width:60%;"/> <img src="plc.png" style="max-width:60%;"/>
</center> </center>
\cgalFigureCaptionBegin{CT_3_plc_fig} \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 \cgalFigureCaptionEnd
\subsection CT_3_CDT Conforming Constrained Delaunay Triangulation \subsection CT_3_CDT Conforming Constrained Delaunay Triangulation
The goal of the algorithms developed in this package is to compute a constrained Delaunay 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 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). for more details on Delaunay triangulations).
A _constrained Delaunay triangulation_ of a PLC is a constrained triangulation which is as much A _constrained Delaunay triangulation_ of a PLC is a constrained triangulation that is as close as
Delaunay as possible, given that some facets are marked as _constrained_. More precisely, a 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, triangulation is _constrained Delaunay_ if, for any simplex \f$s\f$ of the triangulation, the
the interior of its circumscribing sphere contains no vertex of the triangulation that is interior of its circumscribing sphere contains no vertex of the triangulation that is _visible_ from
_visible_ from any point of the interior of the simplex \f$s\f$. Two points are _visible_ any point in the interior of the simplex \f$s\f$. Two points are _visible_ if the open line segment
if the open line segment joining them does not intersect any polygon of the PLC, with the exception joining them does not intersect any polygon of the PLC, except for polygons that are coplanar with
of polygons that are coplanar with the segment. the segment.
In 3D, constrained triangulations do not always exist. It can be shown using the In 3D, constrained triangulations do not always exist. This can be demonstrated using the example of
example of the Sch&ouml;nhardt polyhedron \cgalCite{schonhardt1928zerlegung}, Sch&ouml;nhardt polyhedra \cgalCite{schonhardt1928zerlegung}, \cgalCite{b-ip-48a}, which require the
\cgalCite{b-ip-48a}, that requires the addition of addition of Steiner vertices to become tetrahedralizable (see \cgalFigureRef{CT_3_schonhardt_fig}).
Steiner vertices to be tetrahedralizable (see \cgalFigureRef{CT_3_schonhardt_fig}).
\cgalFigureAnchor{CT_3_schonhardt_fig} \cgalFigureAnchor{CT_3_schonhardt_fig}
<center> <center>
@ -86,19 +88,16 @@ A Sch&ouml;nhardt polyhedron.
\cgalFigureCaptionEnd \cgalFigureCaptionEnd
Shewchuk \cgalCite{cgal:shewchuk1998condition} showed that for any PLC, Shewchuk \cgalCite{cgal:shewchuk1998condition} demonstrated that for any PLC, there exists a refined
there exists another PLC that is a refined version of the original one, version of the original PLC that admits a constrained Delaunay triangulation. This refinement is
and admits a constrained Delaunay triangulation. achieved by adding Steiner vertices to the input edges and polygons. The constrained triangulation
The refined PLC is obtained by adding Steiner vertices on the input edges and polygons, built on this refined PLC is known as a _conforming constrained Delaunay triangulation_.
and the constrained triangulation built on this PLC is called
a _conforming constrained Delaunay triangulation_.
The algorithm implemented in this package is based on the work of The algorithm implemented in this package is based on the work of Hang Si \cgalCite{si2005meshing},
Hang Si \cgalCite{si2005meshing}, \cgalCite{si2015tetgen}. \cgalCite{si2015tetgen}. Steiner vertices are inserted on the input edges and polygons of the PLC to
Steiner vertices are added on input edges and input polygons ensure it can be tetrahedralized.
of the PLC to make it tetrahedralizable.
\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. Delaunay triangulation constructed from a PLC.
\cgalFigureAnchor{CT_3_plc2cdt_fig} \cgalFigureAnchor{CT_3_plc2cdt_fig}
@ -114,53 +113,83 @@ Right: the same CCDT seen with cutplane.
\section CT_3_api Software Design \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 \subsection CT_3_api_classes Classes
This package provides one main class `CGAL::Conforming_constrained_Delaunay_triangulation_3` This package provides a primary class, `CGAL::Conforming_constrained_Delaunay_triangulation_3`,
that represents a 3D conforming constrained Delaunay triangulation. which represents a 3D conforming constrained Delaunay triangulation. This class is templated on a
The class is templated by the geometric traits class and the underlying triangulation class. geometric traits class and an underlying triangulation class, allowing for flexibility and
The other classes that are provided are secondary classes that define the customization.
vertex and cell types and metadata that constitute the triangulation.
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 \subsection CT_3_api_functions Functions
Some helper constructor functions, like `CGAL::make_conforming_constrained_Delaunay_triangulation_3()`, Several helper constructor functions are provided, such as \link
are provided to create a `CGAL::Conforming_constrained_Delaunay_triangulation_3` object. 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 \section CT_3_examples Examples
\subsection CT_3_example_ccdt Build a Conforming Constrained Delaunay Triangulation \subsection CT_3_example_ccdt Build a Conforming Constrained Delaunay Triangulation
The following example demonstrates how to use the helper constructor function The following example illustrates how to use the helper function
`CGAL::make_conforming_constrained_Delaunay_triangulation_3()` to create a `CGAL::make_conforming_constrained_Delaunay_triangulation_3()` to construct a conforming constrained
conforming constrained Delaunay triangulation from a given PLC. Delaunay triangulation from a given piecewise linear complex (PLC).
\cgalExample{Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3.cpp } \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 \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 You can also construct a conforming constrained Delaunay triangulation from a polygon soup—that is,
from a polygon soup, i.e., a set of polygons for which the connectivity is not known a priori. a collection of polygons where the connectivity information is not explicitly provided. The
This example demonstrates how to build such a triangulation. 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 } \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 \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 If the user already knows the set of patch IDs to associate with each face, this information can be
can be used and kept valid through the construction of the conforming constrained provided and preserved throughout the construction of the conforming constrained Delaunay
Delaunay triangulation. triangulation.
The following example demonstrates how to detect surface patches separated by sharp edges The following example demonstrates how to detect surface patches separated by sharp edges and use
and use this surface segmentation in the tetrahedrization process. this segmentation during the tetrahedralization process.
When this parameter is used, the 3D triangulation constrained faces indices (available with When this parameter is specified, the face constraint indices in the 3D triangulation (accessible
`CGAL::Conforming_constrained_Delaunay_triangulation_cell_data_3::face_constraint_index() ` 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
are set to the corresponding patch ids from this map. input polygon is assigned a unique face index.
When it is not used, the face indices are set to different indices for each input polygon.
\cgalExample{Constrained_triangulation_3/conforming_constrained_Delaunay_triangulation_3_fpmap.cpp} \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 \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. The input mesh must be a valid surface mesh, i.e., it must not have self-intersections. Numerous
Numerous preprocessing functions are available in the \ref PkgPolygonMeshProcessing package _to enforce these preconditions_. preprocessing functions are available in the \ref PkgPolygonMeshProcessing package _to enforce these
preconditions_.
\subsubsection CT_3_example_ccdt_autorefinement Autorefinement of the Input Mesh \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 \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 The following example demonstrates how to construct a conforming constrained Delaunay triangulation from
an input mesh that is not triangulated, and (possibly) self-intersecting. 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, The function `CGAL::Polygon_mesh_processing::does_self_intersect()` can be used to detect self-intersections,
but this function can be used only on triangulated meshes. It is therefore necessary to triangulate but it requires the input mesh to be triangulated. Therefore, the input mesh must first be triangulated
the input mesh before checking for self-intersections, using the function using `CGAL::Polygon_mesh_processing::triangulate_faces()` before performing the self-intersection check.
`CGAL::Polygon_mesh_processing::triangulate_faces()`.
The triangulated version of the mesh is then kept in case of self-intersections, If self-intersections are found, the triangulated mesh is converted into a triangle soup, which can then be
to use the `CGAL::Polygon_mesh_processing::autorefine()` function to remove the self-intersections. processed with `CGAL::Polygon_mesh_processing::autorefine_triangle_soup()` to remove the self-intersections.
\cgalExample{Constrained_triangulation_3/ccdt_3_preprocessing.cpp } \cgalExample{Constrained_triangulation_3/ccdt_3_preprocessing.cpp }
\subsection CT_3_example_remesh Remeshing a Conforming Constrained Delaunay Triangulation \subsection CT_3_example_remesh Remeshing a Conforming Constrained Delaunay Triangulation
Once the triangulation is built, it is possible to remesh it using the After constructing the triangulation, you can improve its quality or adapt it to a specific sizing
`CGAL::tetrahedral_isotropic_remeshing()` function from the \ref PkgTetrahedralRemeshing package field by applying the `CGAL::tetrahedral_isotropic_remeshing()` function from the \ref
to improve the quality of the mesh or adapt it to a given sizing field. 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 } \cgalExample{Constrained_triangulation_3/remesh_constrained_Delaunay_triangulation_3.cpp }
\section CT_3_design Implementation History \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 The initial version of this package was implemented by Laurent Rineau and released in
\cgalCite{si2005meshing}, \cgalCite{si2015tetgen}. \cgal&nbsp;6.1&nbsp;(2025). Its design and algorithms are grounded in the theoretical work of
Hang&nbsp;Si on meshing algorithms&nbsp;\cgalCite{si2005meshing},&nbsp;\cgalCite{si2015tetgen}.
*/ */
} /* namespace CGAL */ } /* namespace CGAL */

1
Constrained_triangulation_3/doc/Constrained_triangulation_3/dependencies
View File

@ -7,6 +7,7 @@ Property_map
SMDS_3 SMDS_3
STL_Extension STL_Extension
Stream_support Stream_support
Surface_mesh
TDS_3 TDS_3
Tetrahedral_remeshing Tetrahedral_remeshing
Triangulation_3 Triangulation_3