API proposal for 3D mesh smoothing

Documentation/doc/Documentation/packages.txt

@@ -101,6 +101,7 @@
 \package_listing{Tetrahedral_remeshing}
 \package_listing{Periodic_3_mesh_3}
 \package_listing{Alpha_wrap_3}
+\package_listing{Mesh_smoothing_3}
 
 \cgalPackageSection{PartReconstruction,Shape Reconstruction}
 

Documentation/doc/scripts/generate_how_to_cite.py

@@ -237,6 +237,7 @@ def protect_accentuated_letters(authors):
         .replace("%", "")
         .replace("đ", r"{\-d}")
         .replace("ï", r"{\"i}")
+        .replace("ç", r"{\,c}")
     )
     try:
         res.encode("ascii")

Installation/include/CGAL/license/Mesh_smoothing_3.h

@@ -0,0 +1,54 @@
+// Copyright (c) 2016  GeometryFactory SARL (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) : Andreas Fabri
+//
+// Warning: this file is generated, see include/CGAL/license/README.md
+
+#ifndef CGAL_LICENSE_MESH_SMOOTHING_3_H
+#define CGAL_LICENSE_MESH_SMOOTHING_3_H
+
+#include <CGAL/config.h>
+#include <CGAL/license.h>
+
+#ifdef CGAL_MESH_SMOOTHING_3_COMMERCIAL_LICENSE
+
+#  if CGAL_MESH_SMOOTHING_3_COMMERCIAL_LICENSE < CGAL_RELEASE_DATE
+
+#    if defined(CGAL_LICENSE_WARNING)
+
+       CGAL_pragma_warning("Your commercial license for CGAL does not cover "
+                           "this release of the 3D Mesh Smoothing package.")
+#    endif
+
+#    ifdef CGAL_LICENSE_ERROR
+#      error "Your commercial license for CGAL does not cover this release \
+              of the 3D Mesh Smoothing package. \
+              You get this error, as you defined CGAL_LICENSE_ERROR."
+#    endif // CGAL_LICENSE_ERROR
+
+#  endif // CGAL_MESH_SMOOTHING_3_COMMERCIAL_LICENSE < CGAL_RELEASE_DATE
+
+#else // no CGAL_MESH_SMOOTHING_3_COMMERCIAL_LICENSE
+
+#  if defined(CGAL_LICENSE_WARNING)
+     CGAL_pragma_warning("\nThe macro CGAL_MESH_SMOOTHING_3_COMMERCIAL_LICENSE is not defined."
+                          "\nYou use the CGAL 3D Mesh Smoothing package under "
+                          "the terms of the GPLv3+.")
+#  endif // CGAL_LICENSE_WARNING
+
+#  ifdef CGAL_LICENSE_ERROR
+#    error "The macro CGAL_MESH_SMOOTHING_3_COMMERCIAL_LICENSE is not defined.\
+            You use the CGAL 3D Mesh Smoothing package under the terms of \
+            the GPLv3+. You get this error, as you defined CGAL_LICENSE_ERROR."
+#  endif // CGAL_LICENSE_ERROR
+
+#endif // no CGAL_MESH_SMOOTHING_3_COMMERCIAL_LICENSE
+
+#endif // CGAL_LICENSE_MESH_SMOOTHING_3_H

Installation/include/CGAL/license/gpl_package_list.txt

@@ -35,6 +35,7 @@ Kinetic_surface_reconstruction Kinetic Surface Reconstruction
 Matrix_search Monotone and Sorted Matrix Search
 Mesh_2 2D Conforming Triangulations and Meshes
 Mesh_3 3D Mesh Generation
+Mesh_smoothing_3 3D Mesh Smoothing
 Minkowski_sum_2 2D Minkowski Sums
 Minkowski_sum_3 3D Minkowski Sum of Polyhedra
 Nef_2 2D Boolean Operations on Nef Polygons

Mesh_smoothing_3/doc/Mesh_smoothing_3/Concepts/MeshDataStructure.h

@@ -0,0 +1,80 @@
+/*!
+\ingroup pkgMeshSmoothing3Concepts
+\cgalConcept
+
+The concept `MeshDataStructure` describes the way the tetrahedral mesh will be accessed and modified.
+
+\sa `CGAL::Mesh_smoothing_3::Mesh_smoother`
+
+*/
+class MeshDataStructure {
+public:
+
+/// \name Types
+/// @{
+
+/*!
+Descriptor used to access a cell (tetrahedron) information
+*/
+using Cell_descriptor = unspecified_type;
+
+
+/*!
+Descriptor used to access a vertex information
+*/
+using Vertex_descriptor = unspecified_type;
+
+
+/*!
+Point type.
+*/
+using Point_3 = unspecified_type;
+
+/// @}
+
+/// \name Operations
+/// The following functions are used to access and modify the mesh data:
+/// @{
+
+/*!
+std::size_t is optional but will avoid warnings.
+*/
+std::size_t nb_cells() const;
+
+/*!
+
+*/
+std::size_t nb_vertices() const;
+
+/*!
+Access the coordinates of a vertex.
+*/
+Point_3 vertex_coordinates(Vertex_descriptor vertex) const;
+
+/*!
+Change the coordinates of a vertex.
+*/
+void set_vertex_coordinates(Vertex_descriptor vertex, Point_3 coord);
+
+/*!
+Provide an iterable range over the Cell_descriptors of the mesh
+*/
+unspecified_type cell_range() const;
+
+/*!
+Access the 4 vertices of a cell.
+Returns container behaving like std::array<Vertex_descriptor, 4>
+*/
+unspecified_type cell_vertices(Cell_descriptor cell) const;
+
+/*!
+Optimal shape of the given cell.
+Returns container behaving like std::array<Point_3, 4>
+*/
+unspecified_type cell_reference_shape(Cell_descriptor cell) const;
+
+/// @}
+
+
+
+}; /* end MeshDataStructure */

Mesh_smoothing_3/doc/Mesh_smoothing_3/Concepts/PolylinesDataStructure.h

@@ -0,0 +1,63 @@
+/*!
+\ingroup pkgMeshSmoothing3Concepts
+\cgalConcept
+
+The concept `PolylinesDataStructure` describes the way the curves on the mesh will be accessed.
+
+\sa `CGAL::Mesh_smoothing_3::Mesh_smoother`
+\sa `MeshDataStructure`
+\sa `SurfaceDataStructure`
+
+*/
+class PolylinesDataStructure {
+public:
+
+/// \name Types
+/// @{
+
+/*!
+Descriptor used to access a edge information
+*/
+using Edge_descriptor = unspecified_type;
+
+/*!
+Index associated with an edge to identify the curve it belongs to. This is used to query the curve information from the user.
+*/
+using Curve_index = unspecified_type;
+
+/*!
+Descriptor used to access a vertex information. Should be compatible with the one used in MeshDataStructure.
+*/
+using Vertex_descriptor = unspecified_type;
+
+
+/// @}
+
+/// \name Operations
+/// The following functions are used to access surface data:
+/// @{
+
+/*!
+std::size_t is optional but will avoid warnings.
+*/
+std::size_t nb_edges() const;
+
+/*!
+Provides an iterable range over the Edge_descriptor of the mesh
+*/
+unspecified_type edge_range() const;
+
+/*!
+Returns an identifier (curve id, segment id, ...) related to an edge.
+*/
+Curve_index curve_id(Edge_descriptor edge) const;
+
+/*!
+Return the ith vertex of an edge (max 2).
+*/
+Vertex_descriptor edge_vertex(Edge_descriptor edge, unsigned i) const;
+
+/// @}
+
+
+}; /* end PolylinesDataStructure */

Mesh_smoothing_3/doc/Mesh_smoothing_3/Concepts/SurfaceDataStructure.h

@@ -0,0 +1,68 @@
+/*!
+\ingroup pkgMeshSmoothing3Concepts
+\cgalConcept
+
+The concept `SurfaceDataStructure` describes the way the surface mesh will be accessed.
+
+\sa `CGAL::Mesh_smoothing_3::Mesh_smoother`
+\sa `MeshDataStructure`
+
+*/
+class SurfaceDataStructure {
+public:
+
+/// \name Types
+/// @{
+
+/*!
+Descriptor used to access face information
+*/
+using Face_descriptor = unspecified_type;
+
+
+/*!
+Vector type.
+*/
+using Normal_3 = unspecified_type;
+
+/*!
+Index associated with a surface patch to identify the patch it belongs to. This is used to query the patch information from the user.
+*/
+using Surface_patch_index = unspecified_type;
+
+/// @}
+
+/// \name Operations
+/// The following functions are used to access surface data:
+/// @{
+
+/*!
+std::size_t is optional but will avoid warnings.
+*/
+std::size_t nb_faces() const;
+
+/*!
+Provides an iterable range over the Face_descriptor of the mesh
+*/
+unspecified_type face_range() const;
+
+/*!
+Returns the number of vertices of a face. std::size_t is optional but will avoid warnings.
+*/
+std::size_t nb_face_vertices(Face_descriptor face) const;
+
+/*!
+Returns an identifier (patch id, face id, ...) related to a face.
+*/
+Surface_patch_index patch_id(Face_descriptor face) const;
+
+/*!
+Provides an iterable range of Vertex_descriptor as defined in `MeshDataStructure` to iterate over the vertices of a face.
+*/
+unspecified_type face_vertices(Face_descriptor face) const;
+
+/// @}
+
+
+
+}; /* end SurfaceDataStructure */

Mesh_smoothing_3/doc/Mesh_smoothing_3/Doxyfile.in

@@ -0,0 +1,10 @@
+@INCLUDE = ${CGAL_DOC_PACKAGE_DEFAULTS}
+
+PROJECT_NAME = "CGAL ${CGAL_DOC_VERSION} - 3D Mesh Smoothing"
+
+# custom options for this package
+HIDE_UNDOC_MEMBERS         =  true
+HIDE_UNDOC_CLASSES         =  true
+
+EXCLUDE += \
+  include/CGAL/Mesh_smoothing_3/Mesh_smoothing_3.h \

Mesh_smoothing_3/doc/Mesh_smoothing_3/Mesh_smoothing_3.txt

@@ -0,0 +1,77 @@
+namespace CGAL {
+
+/*!
+
+\mainpage User Manual
+
+\anchor Chapter_3D_Mesh_smoothing
+
+\cgalAutoToc
+
+\author François Protais
+
+\section secMeshSmoothing3 Volume Mesh Smoothing and Geometric Fitting
+
+This package implements an optimization algorithm for improving the quality of
+volumetric meshes and fitting them to geometric targets. It can be used to improve an already valid mesh, untangle
+an invalid mesh, or deform a mesh so that its boundary follows a prescribed
+geometry.
+
+The algorithm only modifies vertex coordinates. It does not insert or remove
+vertices, change cell connectivity, or alter the combinatorial structure of the
+input mesh. Consequently, cell indices, material labels, adjacency relations,
+and other data attached to the mesh are preserved throughout the
+optimization.
+
+\subsection ssecMeshSmoothingAlgorithm Smoothing and Fitting Algorithm
+
+The algorithm optimizes vertex positions according to an element-quality
+energy. It currently uses a conformal energy (MIPS3D) that improves 
+the dihedral angles of the cells. Interior vertices are moved
+to improve the volume mesh, while boundary vertices can additionally be
+attracted towards a target geometry.
+
+The energy possesses a barrier term preventing element inversion. 
+For an initially valid mesh, all accepted optimization steps preserve element orientation, 
+providing a validity guarantee while the element quality is improved. 
+The use of a penalization approach allows the optimizer to start from an invalid meshes, 
+and recover a valid configuration by untangling inverted elements.
+
+Geometric targets can be specified at several dimensions:
+
+- surface targets constrain boundary polygons to locally estimated tangent
+  planes;
+- curve targets constrain selected mesh edges to target tangent directions;
+- point targets attract individual vertices to prescribed positions.
+
+Surface patches and curves may be assigned different identifiers, allowing
+different parts of the mesh to use different target geometries. Constraints
+are soft and weighted by default, so geometric fidelity can be balanced
+against element quality. Vertices, or individual coordinate dimensions, can
+also be locked when hard constraints are required. Combining surface, curve,
+and point targets allows smooth regions, sharp curves, corners, and user
+handles to be treated within the same optimization.
+
+By recovering the tangent planes of the target geometry, the smoother
+can recover curvature discontinuities enabling automatic feature recovery/preservation.
+
+\section secMeshSmoothing3API API
+
+The main function of the package is `CGAL::boundary_aware_mesh_smoothing()`, 
+which takes a `CGAL::Mesh_complex_3_in_triangulation_3` as input and updates its vertex coordinates to improve element quality and fit to geometric targets.
+
+\section secMeshSmoothing3Examples Examples
+
+\subsection ssecMeshSmoothingC3t3 Direct Smoothing of a C3t3
+
+The following example demonstrates the direct use of the smoother on a
+`CGAL::Mesh_complex_3_in_triangulation_3`. A multi-domain `C3t3` is generated
+from a labeled image and deformed to create an initial input. The
+`boundary_aware_mesh_smoothing` is then called on the generated `C3t3`.
+
+\cgalExample{Mesh_smoothing_3/c3t3_smooth.cpp}
+
+
+
+*/
+} /* namespace CGAL */