namespace CGAL {
/*!

\mainpage User Manual
\anchor Chapter_Tetrahedral_Remeshing
\anchor userchaptertetrahedralremeshing

\cgalAutoToc
\authors Jane Tournois, Noura Faraj, Jean-Marc Thiery, Tamy Boubekeur

\image html bimba_back.png
\image latex bimba_back.png
<BR>

\section secTetRemeshing Multi-Material Isotropic Tetrahedral Remeshing

This package implements an algorithm for quality tetrahedral remeshing,
introduced by Faraj et al in \cgalCite{faraj2016mvr}.
This practical iterative remeshing algorithm is designed to remesh
multi-material tetrahedral meshes, by iteratively performing a sequence of
elementary operations such as edge splits, edge collapses, edge flips,
and vertex relocations following a Laplacian smoothing.
The algorithm results in high-quality uniform isotropic meshes,
with the desired mesh density,
while preserving the input geometric curve and surface features.

\subsection ssecAlgorithm Remeshing Algorithm

Specific remeshing rules have been designed to satisfy the following criteria.
First, the algorithm preserves the geometric complex topology, including
multi-material surface patches and polyline features. Polyline features
can be defined as intersections between more than two subdomains, or listed by
the user. Second, it has been made possible to remesh only a selection of cells,
instead of remeshing the whole domain, while preserving or remeshing the
interface surfaces between the preserved and the remeshed tetrahedra.

All the local atomic operations that are performed by the algorithm
preserve the input topology of the geometric complex.

The tetrahedral remeshing algorithm improves the quality of dihedral angles,
while targeting the user-defined uniform sizing field and preserving the
topology of the feature complex, as highlighted by \cgalFigureRef{Remesh_liver}.

Experimental evidence shows that a higher number of remeshing iterations
leads to a mesh with a improved fidelity to the sizing criterion,
and higher quality dihedral angles.

\cgalFigureBegin{Remesh_liver, tetrahedral_remeshing_before_after.png}
Tetrahedral mesh, modified by our tetrahedral remeshing method.
(Left) Before remeshing, dihedral angles were in the interval [1.3; 177.8].
(Right) After remeshing and keeping the same density,
dihedral angles are in the interval [12,7; 157.7].
\cgalFigureEnd

\subsection ssecSizing Sizing Field

Tetrahedral isotropic remeshing algorithm is led by a target sizing field,
that can be either uniform, adaptive, or custom.

The sizing field establishes the local target edge length for the remeshed
tetrahedra. Two sizing fields are provided: a uniform and a mesh-adaptive sizing field.
With `CGAL::Uniform_sizing_field`,
all tetrahedra edges are targeted to have equal lengths,
as depicted in Section \ref secTetRemeshing .
With `CGAL::Adaptive_remeshing_sizing_field`,
tetrahedra edge lengths remain locally close to the local size of simplices in the input mesh.

The difference between remeshing with uniform and adaptive
sizing fields is depicted in \cgalFigureRef{uniform_and_adaptive_tet}.

\cgalFigureBegin{uniform_and_adaptive_tet, uniform_and_adaptive_remeshing.png}
Tetrahedral mesh, modified by our tetrahedral remeshing method.
(Left) Before remeshing;
        dihedral angles in the interval [0.1; 179.8],
        33,936 vertices.
(Middle) After remeshing with uniform sizing field,
        targeting the average edge length of input (left) mesh;
        dihedral angles in the interval [9.8; 165.5],
        301,127 vertices.
(Right) After remeshing with adaptive sizing field;
        dihedral angles in the interval [6.8; 166.2],
        38,602 vertices.
\cgalFigureEnd

It is also possible to use a custom sizing function, like for example
the same sizing field as the one used for initial tetrahedral mesh generation
using the \cgal \ref PkgMesh3 package, and consecutive consistent isotropic remeshing,
as shown by \cgalFigureRef{sphere_sizing_field}.
Note that the remeshed version is denser than the one generated by `CGAL::make_mesh_3()`.
This happens because here, the sizing field is used both as a lower and an upper bound for
edge lengths, whereas in mesh generation it is used only as an upper bound
on simplex sizes.

\cgalFigureBegin{sphere_sizing_field, sphere_with_sizing.png}
Tetrahedral mesh, modified by our uniform tetrahedral remeshing method.
(Left) Before remeshing, dihedral angles were in the interval `[0.2; 179.7]`.
(Middle) After remeshing with a uniform target edge length equal to the average edge
 length of the input mesh. Dihedral angles are in the interval `[13.2; 157.3]`.
(Right) After remeshing with the same sizing field as the one used for mesh
generation. Dihedral angles are in the interval `[10.4; 162.3]`.
\cgalFigureEnd


\section secTetRemeshingAPI API

The tetrahedral remeshing algorithm is implemented as a single free function
`CGAL::tetrahedral_isotropic_remeshing()` that
takes only two required parameters: the input triangulation, and the desired edge length
or sizing field,
which drives the remeshing process.

\ref BGLNamedParameters are used to deal with optional parameters.
The page \ref bgl_namedparameters describes their usage.

\section secTetRemeshingExamples Examples

\subsection ssecEx1 Tetrahedral Remeshing Example

The following example shows the simplest use of the tetrahedral remeshing function.
The only required parameter is a given target edge length that drives the remeshing process
towards a high-quality tetrahedral mesh with improved dihedral angles, and a more
uniform mesh, with edge lengths getting closer to the input parameter value.

By default, the cells with a non-zero `Subdomain_index` are
selected for remeshing. The cells with `Subdomain_index` equal to zero
are ignored by the remeshing algorithm.

\cgalExample{Tetrahedral_remeshing/tetrahedral_remeshing_example.cpp }


\subsection ssecEx2 Tetrahedral Remeshing of a Selection

Optional BGL named parameters offer more precise
control on the remeshing process. In this example, a triangulation with two subdomains
(defined by indices stored in cells) is given as input, but only one
(defined by the `Subdomain_index` 2)
of its subdomains is remeshed.

Only the cells with a non-zero `Subdomain_index` will be remeshed.
The named parameter `cell_is_selected_map` can be used to change this
behavior.

\cgalExample{Tetrahedral_remeshing/tetrahedral_remeshing_of_one_subdomain.cpp }


\subsection ssecEx3 Tetrahedral Remeshing With Polyline Features

Optional BGL named parameters offer more precise
control on the remeshing process. In this example, a triangulation
with polyline features that should be preserved - though resampled -
during the remeshing process, is given as input.
Preserving all surfaces exactly could also be achieved by
setting the named parameter `remesh_boundaries` to `false`.

\cgalExample{Tetrahedral_remeshing/tetrahedral_remeshing_with_features.cpp }

It is also possible to define the polyline features as the ones
stored as complex edges in a `Mesh_complex_3_in_triangulation_3`
(e.g., generated by the \ref PkgMesh3 package).

\cgalExample{Tetrahedral_remeshing/mesh_and_remesh_c3t3.cpp }


\subsection ssecEx4 Tetrahedral Remeshing After Mesh Generation

The tetrahedral remeshing algorithm is designed as a postprocessing for
mesh generation algorithms. The API allows to generate a tetrahedral mesh
with the \cgal \ref PkgMesh3 package, and
further improve it with the tetrahedral remeshing algorithm.
This example shows how to use tetrahedral mesh generation and remeshing in sequence,
from a polyhedral domain with features.

\cgalExample{Tetrahedral_remeshing/mesh_and_remesh_polyhedral_domain_with_features.cpp}


\subsection ssecEx4a Tetrahedral Remeshing With Sizing Field

The API enables the user to run tetrahedral remeshing with a custom sizing field,
that is used as a sizing criterion to trigger mesh refinement and decimation.
The following examples show how to use this type of sizing field.

In the first example, we show how to use the same sizing field as the one used as
a meshing criterion for tetrahedral mesh generation using the \cgal \ref PkgMesh3 package.
\cgalExample{Tetrahedral_remeshing/mesh_and_remesh_with_sizing.cpp}

In the second example, we show how to use the provided adaptive sizing field,
`CGAL::Adaptive_remeshing_sizing_field`,
that automatically sets the target edge length to keep a mesh density consistent with
the density of the input mesh.
\cgalExample{Tetrahedral_remeshing/mesh_and_remesh_with_adaptive_sizing.cpp}



\subsection ssecEx5 Tetrahedral Remeshing from Any Tetrahedral Mesh

The following example shows how to read a mesh from a triangulation stored in a
Medit file, perform tetrahedral remeshing, and save the output triangulation.
The input triangulation should follow the validity requirements of a
`CGAL::Triangulation_3` (valid connectivity, positive orientation of the cells, and
coverage of the convex hull of the vertices).

\cgalExample{Tetrahedral_remeshing/tetrahedral_remeshing_from_mesh.cpp}


\section secTetRemeshingHistory Implementation History

This package implements the uniform version of the "Multi-Material Adaptive Volume Remesher"
algorithm for quality tetrahedral remeshing, described by Noura Faraj et al. in \cgalCite{faraj2016mvr}.

A first version of the code was written by Noura Faraj, Jean-Marc Thiery, and Tamy Boubekeur.
Jane Tournois worked on the finalization of the code, the API, and documentation.

It was initially published in CGAL-5.1.

The ability to use a sizing field as variable target edge length was introduced by
Jane Tournois in CGAL-6.0.

*/
} /* namespace CGAL */
