Commit 98d6ea82 authored by Simon Boyé's avatar Simon Boyé

Vitelotte: Some documentation.

parent aa4e9590
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page vitelotte_example_common_page Vitelotte example utils
The <tt>common</tt> directory under the <tt>example/vitelotte</tt> directory contains pieces of code used by several examples. The most notable one is VGMeshWithCurves which shows how to extend the VGMesh class in order to add high level informations about diffusion curves.
This directory contains:
- VGMeshWithCurves, an extension of VGMesh that contains higher level informations. VGMeshWithCurvesReader and VGMeshWithCurvesWritet allow to read and write <tt>.mvg</tt> files extended to support curve constraints and point constraints. These classes are used by all other examples.
- VGNodeRenderer is a class that allow to render a wireframe version of the mesh where constrained edges are bold and doubled if they represent a value discontinuity, and also display nodes per edges. It can be used to have a better understanding of the connectivity of a mesh, making it a useful debugging tool. This class rely on GLLineRenderer and GLPointRenderer and is used by examples doing rendering.
- OrthographicCamera is a simple orthographic camera used by the viewer examples.
- <tt>plotObj.h</tt> contains a simple function that convert a 2D mvg file in a 3D plot. Used by the <tt>plot</tt> command of mvgtk and useful for debugging.
- <tt>textFormatter.h</tt> contains a simple function to break paragraph into multiple lines. Used by mvgtk for help display.
- <tt>shaders.cpp</tt> contains the shaders required by the various OpenGL classes in this directory. It is an automatically generated file that regroup the content of the <tt>shaders</tt> directory in a single .cpp.
*/
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page vitelotte_example_editor_page MVG Editor example
\todo vitelotte_example_editor_page
*/
\ No newline at end of file
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page vitelotte_example_gl_viewer_page GL Viewer example
\todo vitelotte_example_gl_viewer_page
*/
\ No newline at end of file
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page vitelotte_example_mvgtk_page The MVG Toolkit example
\section vitelotte_example_mvgtk_introduction_sec Introduction
The MVG Toolkit, aka. <tt>mvgtk</tt> is more than a simple example, it is a command-line interface to the Vitelotte library. It is designed to allow to do common operation on mvg files without writing C++ code.
There is a typical use of <tt>mvgtk</tt>:
\code
$ mvgtk -v my_file.mvg conv fv finalize solve out out.mvg
Load mvg "my_file.mvg"...
Set attributes to 271...
Finalize...
Solve...
Biharmonic quadratic diffusion.
Output "out.mvg"...
\endcode
Mvgtk first takes a list of global options, in this case <tt>-v</tt> that enable the verbose mode (mvgtk does not print anything without it, unless there is an error). Then you must specify the input file. Note that beside mvg files, mvgtk can load .obj files that will be treated as mvg with no attributes. The rest of the command line is a sequence of command (with options) that are executed in order on the mesh. Most commands modify the mesh for the subsequent operations. There is what the above line is doing:
1. <tt>conv fv</tt> (convert) set the mesh attributes to represent FV elements. In practice, just call \c VGMesh::setAttributes(VGMesh::FV_FLAGS).
2. <tt>finalize</tt> finalize the mesh (see \ref vitelotte_user_manual_vgmesh). Just call <tt>VGMesh::finalize()</tt> as you may guess.
3. <tt>solve</tt> solve the diffusion. The code of this command is a little bit more involved as it as to create the right solver class depending on the mesh attributes, call the right sequence of methods on it and do some error handling.
4. <tt>out out.mvg</tt> output the resulting mesh in the file <tt>out.mvg</tt>. This is the only command of the line that does not modify the mesh. Note that it is possible to use this command several time, for instance to output intermediate results.
The complete list of commands and options can always be found by calling <tt>mvgtk --help</tt>.
\section vitelotte_example_mvgtk_options_sec Global options
- <tt>-h</tt>, <tt>--help</tt>: print help and exit.
- <tt>-v</tt>, <tt>--verbose</tt>: verbose mode.
\section vitelotte_example_mvgtk_commands_sec Commands
\subsection vitelotte_example_mvgtk_check_command_sub Check command
The <tt>check</tt> command does some sanity check on the mesh. Problems found are printed on the standard output. Subsequent commands are only executed if no error was found.
This command takes no parameter, but output more detailed diagnostic in case of error in verbose mode.
Note that this command may not check exhaustively for all possible inconsistencies in the mesh, so the fact this command succeed is no guarantee that subsequent commands will.
\subsection vitelotte_example_mvgtk_compact_command_sub Compact command
The <tt>compact</tt> command remove all unused nodes in the mesh (nodes not referenced by an element), making it more compact. This command takes no options.
The implementation of this command is straightforward:
\include vitelotte/mvgtk/compactCommand.cpp
\subsection vitelotte_example_mvgtk_convert_command_sub Convert command
The <tt>convert ATTR</tt> (or <tt>conv</tt>) command allow to change the attributes set of the mesh, thus effectively converting the mesh to a new kind of element. The mandatory parameter ATTR describe the new set of attributes. It must be one of the following:
- <tt>none</tt>: removes all attributes.
- <tt>linear</tt>: set attributes to represent linear elements. See \ref VGMesh::LINEAR_FLAGS.
- <tt>quadratic</tt>: set attributes to represent quadratic elements. See \ref VGMesh::QUADRATIC_FLAGS.
- <tt>morley</tt>: set attributes to represent morley elements. See \ref VGMesh::MORLEY_FLAGS.
- <tt>fv</tt>: set attributes to represent FV elements. See \ref VGMesh::FV_FLAGS.
If you use <tt>convert</tt> to remove attributes from the mesh, it may be worth to call <tt>compact</tt> afterward to remove no longer used nodes as this is not done automatically.
\include vitelotte/mvgtk/convertCommand.cpp
\subsection vitelotte_example_mvgtk_c2n_command_sub Curves-to-nodes command
The <tt>curves-to-nodes</tt> (or <tt>c2n</tt>) command set nodes constraints according to curves and point constraints (those are high level constraints defined in the \ref vitelotte_example_vg_mesh_with_curves_page). This command first remove all node. Note that the resulting mesh will only have constrained nodes set, so you probably want to call <tt>finalize</tt> afterward.
\include vitelotte/mvgtk/curvesToNodesCommand.cpp
\subsection vitelotte_example_mvgtk_finalize_command_sub Finalize command
The <tt>finalize</tt> command finalize the mesh. See \ref vitelotte_user_manual_fem_solver for a detailed explanation of the finalization mechanism.
The code is as simple as it can be:
\include vitelotte/mvgtk/finalizeCommand.cpp
\subsection vitelotte_example_mvgtk_output_command_sub Output command
The <tt>output FILENAME</tt> (or <tt>out</tt>) command output the mesh in FILENAME using the MVG file format.
\include vitelotte/mvgtk/outputCommand.cpp
\subsection vitelotte_example_mvgtk_plot_command_sub Plot command
The <tt>plot COEFF SUBDIV FILENAME</tt> command output the mesh in FILENAME in the obj file format. The \c x and \c y vertices coordinates are not modified and the \c z coordinate is the value of the coefficient COEFF. The SUBDIV parameter allow to control the level of subdivision each element.
Note that elements subdivision depends on the current mesh attributes. If the mesh represent FV element, the plot will show FV element (which produces discontinuities at their boundaries). You can use <tt>convert</tt> before calling <tt>plot</tt> to change the elements used.
\include vitelotte/mvgtk/plotCommand.cpp
\subsection vitelotte_example_mvgtk_simplify_command_sub Simplify command
\subsection vitelotte_example_mvgtk_solve_command_sub Solve command
*/
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page vitelotte_example_plot_obj_page OBJ Plotter example
\todo vitelotte_example_plot_obj_page
*/
\ No newline at end of file
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page vitelotte_example_vg_mesh_with_curves_page VGMeshWithCurves example
\todo vitelotte_example_vg_mesh_with_curves_page
*/
\ No newline at end of file
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page vitelotte_example_vg_mesh_with_curves_reader_page VGMeshWithCurvesReader example
\todo vitelotte_example_vg_mesh_with_curves_reader_page
*/
\ No newline at end of file
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page vitelotte_example_vg_mesh_with_curves_writer_page VGMeshWithCurvesWriter example
\todo vitelotte_example_vg_mesh_with_curves_writer_page
*/
\ No newline at end of file
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page vitelotte_example_vg_node_renderer_page NodeRenderer example
\todo vitelotte_example_vg_node_renderer_page
*/
\ No newline at end of file
namespace Vitelotte
{
/*!
\page vitelotte_user_manual_page User Manual
\authors Simon Boyé, Gautier Ciaudo, Gael Guennebaud, Pascal Barla
\section vitelotte_user_manual_intro Introduction
- Problematic: complex vector gradients. Mesh-based vector graphics introduction and advantages.
- Problem with the content generation -> diffusion methods
- Overview of the typical use of Vitelotte: get a mesh, set constraint, solve and render.
- A word about mvgtk that will be used to illustrate the following ?
\section vitelotte_user_manual_vgmesh VGMesh
- What is the VGMesh class, its relationship with surface_mesh, what are nodes (probably require a few images).
- Template parameters, dimensions and coefficients.
- Attributes and their meaning.
- An example where we set all nodes manually ? With I/O ?
- Refinement: coming soon !
\section vitelotte_user_manual_fem_solver FEM solver
- Diffusion equations and control.
- Fem solver introduction, presentations of the supported element.
- Setting up the mesh by hand, requirements and limitations.
- Setting up the mesh using finalize, limitations.
- Using the solver.
\section vitelotte_user_manual_rendering Rendering
- Rendering overview.
- Rendering customization.
\section vitelotte_user_manual_mvg MVG file format
- Description of the .mvg file format. Maybe move it to a dedicated page.
*/
}
......@@ -27,4 +27,20 @@
<div class="clear"></div>
\section patate_overview_sec_vitelotte Vitelotte
\htmlonly
<div class="dessin"><img src="images/vitelotte.png" border="0px" width="180" height="200" alt=""/></div>
\endhtmlonly
<i> Simon Boyé, Gautier Ciaudo, Gael Guennebaud, Pascal Barla </i>
This module provides tool to manipulate mesh-based vector graphics with arbitrary connectivity. It includes a generic mesh representation, a diffusion solver to generate colors from a sparse set of constraint, an OpenGL renderer and input/output through the mvg file format.
This module also include a command-line tool called mvgtk that gives access to most of the library functionalities.
<span style="padding-right: 20px;">\ref vitelotte_user_manual_page "User Manual"</span><span style="padding-right: 20px;">\ref vitelotte_example_page "Examples"</span><span style="padding-right: 20px;">\ref Vitelotte "References"</span>
<div class="clear"></div>
*/
#!/usr/bin/python3
from sys import argv, stderr
from os.path import dirname, realpath, normpath, join, isdir, exists
from jinja2 import Environment, FileSystemLoader
def simplify(string):
return string.replace(' ', '_').lower()
script_dir = dirname(realpath(__file__))
env = Environment(loader=FileSystemLoader(join(script_dir, "templates")))
tmpl = env.get_template("doc.tmpl")
if len(argv) != 4:
print("Usage: {} MODULE NAME TITLE".format(argv[0]))
exit(1)
module = argv[1]
name = argv[2]
title = argv[3]
base_name = "{}_{}".format(simplify(module), simplify(name))
out_dir = normpath(join(script_dir, '..', 'Patate', module))
if not isdir(out_dir):
print("\"{}\" is not a directory.".format(out_dir))
exit(1)
out_filename = "{}.mdoc".format(base_name).lower()
out_path = join(out_dir, out_filename)
if exists(out_path):
print("\"{}\" already exists.".format(out_path))
exit(1)
params = {
'pagename' : "{}_page".format(base_name),
'pagetitle': title
}
with open(out_path, "w") as out:
out.write(tmpl.render(params))
/*
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.
*/
/*!
\page {{ pagename }} {{ pagetitle }}
\todo {{ pagename }}
*/
......@@ -32,6 +32,25 @@
<tab type="user" visible="yes" url="@ref grenaille_example_pcl_page" title="PCL Wrapper for surface curvature"/>
</tab>
</tab>
<tab type="usergroup" url="vitelotte_user_manual_page.html" title="Vitelotte">
<tab type="usergroup" url="vitelotte_user_manual_page.html" title="User Manual">
<tab type="user" visible="yes" url="@ref vitelotte_user_manual_intro" title="Introduction"/>
</tab>
<tab type="usergroup" url="@ref vitelotte_example_page" title="Examples">
<tab type="usergroup" url="@ref vitelotte_example_common_page" title="Common utilities">
<tab type="user" visible="yes" url="@ref vitelotte_example_vg_mesh_with_curves_page" title="VGMeshWithCurves"/>
<tab type="user" visible="yes" url="@ref vitelotte_example_vg_mesh_with_curves_reader_page" title="VGMeshWithCurvesReader"/>
<tab type="user" visible="yes" url="@ref vitelotte_example_vg_mesh_with_curves_writer_page" title="VGMeshWithCurvesWriter"/>
<tab type="user" visible="yes" url="@ref vitelotte_example_vg_node_renderer_page" title="VGNodeRenderer"/>
<tab type="user" visible="yes" url="@ref vitelotte_example_plot_obj_page" title="OBJ Plotter"/>
</tab>
<tab type="user" visible="yes" url="@ref vitelotte_example_mvgtk_page" title="MVG Toolkit"/>
<tab type="user" visible="yes" url="@ref vitelotte_example_gl_viewer_page" title="MVG OpenGL Viewer"/>
<tab type="user" visible="yes" url="@ref vitelotte_example_editor_page" title="MVG Editor"/>
</tab>
</tab>
</tab>
<tab type="pages" visible="no" title="" intro=""/>
<tab type="modules" visible="no" title="" intro=""/>
......
......@@ -4,7 +4,11 @@
bool CompactCommand::execute(Mesh& mesh, const GlobalOptions* opts)
{
if(opts && opts->verbose) std::cout << "Compact...\n";
// Mark unused nodes as deleted
mesh.deleteUnusedNodes();
// If verbose mode is on, print a summary of what is removed
if(opts && opts->verbose)
{
int nv = mesh.verticesSize() - mesh.nVertices();
......@@ -16,6 +20,9 @@ bool CompactCommand::execute(Mesh& mesh, const GlobalOptions* opts)
if(nf) std::cout << "Removing " << nf << " faces.\n";
if(nn) std::cout << "Removing " << nn << " nodes.\n";
}
// Call garbage collection that effectively removes deleted elements and
// compact internal arrays.
mesh.garbageCollection();
return true;
}
......
......@@ -26,7 +26,9 @@ bool ConvertCommand::parseArgs(int argc, char** argv, int& argi)
bool ConvertCommand::execute(Mesh& mesh, const GlobalOptions* opts)
{
if(opts && opts->verbose) std::cout << "Set attributes to " << m_attributes << "...\n";
mesh.setAttributes(m_attributes);
return true;
}
......@@ -39,6 +41,6 @@ const char* ConvertCommand::cmdOptions()
const char* ConvertCommand::cmdDesc()
{
return "Set mesh attribute to ATTRIBUTE_DESC. accepted values are linear, "
"quadratic, morley and fv.";
return "Set mesh attribute to ATTRIBUTE_DESC. Accepted values are none, "
"linear, quadratic, morley and fv.";
}
......@@ -4,7 +4,9 @@
bool CurvesToNodesCommand::execute(Mesh& mesh, const GlobalOptions* opts)
{
if(opts && opts->verbose) std::cout << "Set nodes from curves...\n";
mesh.setNodesFromCurves();
return true;
}
......
......@@ -4,7 +4,9 @@
bool FinalizeCommand::execute(Mesh& mesh, const GlobalOptions* opts)
{
if(opts && opts->verbose) std::cout << "Finalize...\n";
mesh.finalize();
return true;
}
......
......@@ -41,6 +41,9 @@ bool MvgtkCommand::parseArgs(int /*argc*/, char** /*argv*/, int& /*argi*/)
}
// ////////////////////////////////////////////////////////////////////////////
bool OutputCommand::parseArgs(int argc, char** argv, int& argi)
{
if(argi < argc) {
......
......@@ -64,7 +64,7 @@ const char* PlotCommand::cmdDesc()
{
return "Output a plot of a 2D input mesh as a .obj file. 2D coordinates "
"are mapped to x and y axis, and the COEFFth coefficient is mapped "
"to z. SUBDIV indicates how refine will be the output. A value of "
"to z. SUBDIV indicates how refined will be the output. A value of "
"1 produces one triangle per element, higher values produce "
"tesselated elements.";
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment