namespace Vitelotte
{
/*!
  \page vitelotte_user_manual_page User Manual

  \authors Simon Boyé, Gautier Ciaudo, Gael Guennebaud, Pascal Barla

  \section vitelotte_user_manual_intro Introduction

  The Vitelotte module provides tools to smoothly interpolate a set of constraints on a mesh. Its primary intent is to provide an efficient solver to create [diffusion curves images](@ref vitelotte_user_manual_diffusion_images_page) \cite Orzan:2008:DiffusionCurves. It includes a FEM-based diffusion solver that is able to do harmonic and biharmonic interpolation on triangular meshes with either linear or quadratic color interpolation over each face \cite Boye:2012:VectorialSolver.

  \image html vitelotte/vitelotte_overview.svg "Vitelotte takes a mesh with constraints along a curve as input (left) and produce a mesh with colors interpolated over each face (right)."

  The diffusion approach offers several advantages compared to methods currently used to produce smooth arbitrary color gradients, like Gradient Meshes. Diffusion curves do not enforce a regular topology, which permits to represent similar gradients with less control points. This leads to easier to manipulate and more lightweight images. However, diffusion curves require to solve a costly equation to produce the final image.

  Vitelotte represents images as arbitrary meshes with color interpolation over each face. This representation is easy to rasterize and scale independent, which makes it perfect to store the result of the diffusion. In facts, as our solver uses the finite element method, it also takes a mesh as input that encode the constraints and the structure of the final image.

  This approach has several advantages:

  - **Scale independence**: important features, like discontinuities, are represented exactly with curved edges while color functions are smooth at any scale.
  - **Efficient rendering**: modern GPU excel at rendering polygons, which enable very fast rendering. Vitelotte contains an OpenGL 4 renderer that supports all the features of our meshes (curved edges, singularities, ...).
  - **Arbitrary dimensions**: our solver can work on surfaces of any dimension. So, you can just use a planar 2D mesh but also diffuse color on 3D surface meshes.
  - **Memory tradeoff**: the result of the diffusion can be a bit heavy with dense meshes. If data size matters, you may wish to store the mesh and the constraint and recompute the diffusion when required, which permits to trade CPU time for memory.

  Note that you are not constrained to diffuse colors with Vitelotte. You can also interpolate normals, displacement vectors or anything else that can be represented as a vectors.


  \section vitelotte_user_manual_about About this manual

  This user manual is best read in order. The tutorial introduces some key concepts and the [VGMesh](@ref vitelotte_user_manual_vg_mesh_page) page details the VGMesh class, which is central to Vitelotte. The rest of the manual does not need to be read in order, but requires a good understanding of VGMesh.


  \section vitelotte_user_manual_overview_library Library overview

  Here is a quick overview of the main elements of Vitelotte. For a more in-depth introduction, see [the tutorial](@ref vitelotte_user_manual_tutorial_page).

  At the heart of Vitelotte is the VGMesh class. It is a mesh representation that contains per-face attributes used for color interpolation. It has been designed to be easily extensible and can support various color interpolation schemes. It can also represent a mesh with some color constraints to use as solver input. The [DCMesh](@ref vitelotte_user_manual_dc_mesh_page) class is an extension that incorporates higher-level diffusion curve constraints.

  The [FemSolver](@ref vitelotte_user_manual_fem_solver_page) class implements a diffusion solver. It can do harmonic or biharmonic color diffusion over a VGMesh with unknown colors. It supports different kinds of elements, enabling either linear or quadratic color interpolation over the final image.

  The [VGMeshRenderer](@ref vitelotte_user_manual_rendering_page) permits to render a VGMesh with linear or quadratic color interpolation, providing basic OpenGL routines to speed-up implementation.

  MVGReader and MVGWriter work together to save and load a VGMesh in the [MVG file format](@ref vitelotte_user_manual_mvg_file_format_page). It allows users to save meshes at any processing step (i.e., before or after a solve), which can be useful for debugging purposes.

  There are several header to include Vitelotte:
  \code
  // include everything but OpenGL classes.
  #include <Patate/vitelotte.h>

  // include OpenGL-based rendering classes, see renderer documentation.
  #include <Patate/vitelotte_gl.h>
  \endcode

  There is currently no easy way to manipulate the topology of a VGMesh, except the low-level mesh manipulation methods that do not preserve constraints. Don't worry, it is planned for the next release which should come very soon.


  \section vitelotte_user_manual_overview_tools Tools overview

  Vitelotte also comes with a small set of tools that offer a high-level interface to the library:

  - The [mvg toolkit](@ref vitelotte_example_mvgtk_page) (`mvgtk`). Permits to do high level operations on DCMesh. Example:
    \code{.sh}
    # poring.mvg is a mvg with diffusion curves and point gradient constraints.
    # Available from the examples/Vitelotte/samples directory.
    # This command generates an image with quadratic interpolation using
    # a biharmonic diffusion.
    mvgtk -v poring.mvg conv fv c2n finalize solve out out.mvg
    \endcode

    See [mvgtk's documentation](@ref vitelotte_example_mvgtk_page) for a complete explanation of this command.

  - [mvg_viewer](@ref vitelotte_example_mvg_viewer_page) is a simple OpenGL viewer. It can display both 2D images and 3D meshes.
  - [mvg_editor](@ref vitelotte_example_mvg_editor_page) is a simple editor for mvg files. Its main purpose is to allow users to experiment with the representation rather than being a user-friendly tool, so expect some rough edges.

 */
 }
