Patate Lib  0.5
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Pages
User Manual
Authors
Simon Boyé, Gautier Ciaudo, Gael Guennebaud, Pascal Barla

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 [6]. 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 [1].

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.

About this manual

This user manual is best read in order. The tutorial introduces some key concepts and the VGMesh 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.

Library overview

Here is a quick overview of the main elements of Vitelotte. For a more in-depth introduction, see the tutorial.

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 class is an extension that incorporates higher-level diffusion curve constraints.

The FemSolver 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 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. 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:

// include everything but OpenGL classes.
#include <Patate/vitelotte.h>
// include OpenGL-based rendering classes, see renderer documentation.
#include <Patate/vitelotte_gl.h>

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.

Tools overview

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

  • The mvg toolkit (mvgtk). Permits to do high level operations on DCMesh. Example:

    # 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

    See mvgtk's documentation for a complete explanation of this command.

  • mvg_viewer is a simple OpenGL viewer. It can display both 2D images and 3D meshes.
  • mvg_editor 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.