add vcglib

2025-11-03 17:46:44 +08:00
1 parent 6f6c0c8eb7
commit af8100f851
@@ -0,0 +1,37 @@
+# Contributor License Agreement
+The following terms are used throughout this agreement:
+
+* **You** - the person or legal entity including its affiliates asked to accept this agreement. An affiliate is any entity that controls or is controlled by the legal entity, or is under common control with it.
+* **VCLab** - the legal representative of the **Visual Computing Lab of the ISTI-CNR** (Istituto di Scienza e Tecnologie dell’Informazione “A. Faedo” an Institute of CNR, the National Research Council of Italy).
+* **Project** - is an umbrella term that refers to any and all the open source projects managed by the VCLab, including, but not limited to, `MeshLab` and the `vcglib`.
+* **Contribution** - any type of work that is submitted to a Project, including any modifications or additions to existing work.
+* **Submitted** - conveyed to a Project via a pull request, commit, issue, or any form of electronic, written, or verbal communication with GitHub, contributors or maintainers.
+
+## 1. Grant of Copyright License.
+Subject to the terms and conditions of this agreement, You grant to the Projects’ maintainers and to VCLab a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute Your contributions and such derivative works. Except for this license, You reserve all rights, title, and interest in your contributions. You agree that your perpetual licensing grant will be applied to all Your contributions to VCLab's Projects during the validity (two years) of this agreement.
+
+## 2. Grant of Patent License.
+Subject to the terms and conditions of this agreement, You grant to the Projects’ maintainers and to VCLab a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer your contributions, where such license applies only to those patent claims licensable by you that are necessarily infringed by your contribution or by combination of your contribution with the project to which this contribution was submitted.
+
+If any entity institutes patent litigation - including cross-claim or counterclaim in a lawsuit - against You alleging that your contribution or any project it was submitted to constitutes or is responsible for direct or contributory patent infringement, then any patent licenses granted to that entity under this agreement shall terminate as of the date such litigation is filed.
+
+## 3. Source of Contribution.
+Your contribution is either your original creation, based upon previous work that, to the best of your knowledge, is covered under an appropriate open source license and you have the right under that license to submit that work with modifications, whether created in whole or in part by you, or you have clearly identified the source of the contribution and any license or other restriction (like related patents, trademarks, and license agreements) of which you are personally aware.
+
+### 4. Personal Details
+ | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   |  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   |
+ :---:|:---:
+**Full real world First and Last name** |  **github user name**
+ &nbsp; |   &nbsp;
+**Email**  | **Physical home/office address**  
+&nbsp;|&nbsp;
+**Date of birth**  | **Place of birth**
+&nbsp; | &nbsp;
+
+
+Signature
+
+---
+Date
+
+---
@@ -0,0 +1,219 @@
+/** \page adjacency
+Adjacency
+=========
+VCG Lib does not have a unique, hard-coded, way to encode the adjacencies among triangles and edges. 
+It all depends on which attributes are stored with the simplices and how they are used. 
+In the previous examples the definition of face has always included the attribute vcg::face::VertexRef, 
+which stores 3 pointers to MyVertex accessible with the member function V() (implementing a plain Indexed Data Structure). 
+Almost all of the algorithms currently implemented in vcglib assume that vcg::face::VertexRef is present. 
+So, if your type MyFace does not include the attribute vcg::face::VertexRef, the definition will be correct, 
+but almost no algorithm will work.
+
+There are other adjacency relations that can be useful to navigate a mesh, 
+for example to collect the one-ring neighborhood of a vertex. vcgib has two main adjacency relations face-face and vertex-face
+which are explained in the following, along with the attributes they use.
+
+
+FF Adjacency
+============
+The face-to-face adjacency, stored in the attribute for the faces vcg::face::FFAdj ,
+encodes the adjacency between faces through edges. 
+The image below shows two triangle faces with the convention adopted for indexing vertexes and edges.
+
+The vertexes are numbered from 0 to 2 in CCW direction and the edge i = 0..2 is the edge
+whose extremes are i and (i+1) mod 3. Therefor, in the below example, the common edge between faces f0 and f1 
+is the edge 1 of the face f1 and the edge 0 of the face f0.
+
+vcg::face::FFAdj stores, for the i-th edge of the face f:
+
+- `FFp(i)`: a pointer to the face sharing the i-th edge of f. If that edge is a border than points to the face f itself
+- `FFi(i)`: the index of edge that corresponds to i-th edge of f in the pointed face
+
+\image html "FF_Adj.png" "Indexing of vertexes and edges"
+
+So for the above example, assuming that `f0` and `f1` are the two pointers to faces, the following relations hold:
+
+    f1->FFp(1) == f0
+    f1->FFi(1) == 0
+
+    f0->FFp(0) == f1
+    f0->FFi(0) == 1
+
+Note that to be precise we should say that `FFp(i)` points to **a** adjacent face, not to **the** adjacent face. 
+The reason is that, in case of non-manifoldness, there could be more than two faces on the same edge, and this 
+is seamlessly supported by VCG Lib. In the picture below is shown an example with 4 faces incident to the same edge.
+
+
+\image html "FF_nonmanifold.png" "Non manifold edge"
+
+In this case the FF adjacencies are arranged to form a circular list (not necessarily sorted with the angle around the edge). 
+This is done by the VCG Lib function that update these values ( vcg::tri::UpdateTopology::FaceFace (MeshType & m)).
+In this way VCG Lib provides a way to check if a mesh is manifold on a specific edge because the FF adjacency relation is mutual, i.e. the face f0 points to the face f1 which points to the face f0, if and only if the mesh is manifold over the corresponding edge.
+
+    bool IsManifold(MyFace *f,int e) { return (f0 == f0->FFp(0)->FFp(f0->FFi(0)))}
+
+
+Pos
+---
+The Pos is the VCG Lib implementation of the Cell-Tuple{ref}. Here we give a as short as possible definition, 
+trading formalisms for space. A Pos in a triangle mesh is a triple made of a vertex: pos = (v,e,f) , 
+such that v is an extreme of e and e belong to the face f . The figure shows few pos in a triangle mesh as small triangles 
+"pointing" to a vertex, "leaning" against an edge and inside a face. For example c0=(v,e0,f).
+
+A very nice property is that given a pos c, there is only another neighbor pos c' that can be obtained from c changing only one of the elements of the triple.
+
+We call the operation of passing from a pos to one of its neighbors Flip and write FlipV, FlipE and FlipF to indicate that the flipped element is the vertex, the edge or the face respectively.
+
+For example consider c1: there is only another pos which is the same as c0 except for the vertex component of the triple, and it is c2. For brevity, we write c2 = FlipV(c1).
+
+In the left of the table some other examples are shown just to make this point clear.
+
+\image html "pos_example.png" "Pos Example"
+
+    c2 = FlipV(c1)
+    c0 = FlipE(c1)
+    c3 = FlipF(c0)
+
+    CCW around v
+    c4 = FlipE(FlipF(c0))
+    c5 = FlipE(FlipF(c4))
+    Bounce
+    c6 = FlipE(FlipF(c5))
+    CW around v
+    c3 = FlipE(FlipF(c6))
+    c1 = FlipE(FlipF(c3))
+    Bounce
+    c0 = FlipE(FlipF(c1))
+
+Note that concatenating two flips: FlipF and FlipE we obtain a transition from a pos to the next in counterclockwise or in clockwise sense, depending if the starting pos is on the CCW edge of the face with respect to the vertex or not. Also note that, thanks to how FF adjacency is defined, when a pos is on the border, it bounces back. This pair of flip are widely used in the VCG Lib to run over the one ring neighborhood of manifold vertices.
+
+The following code snippet shows how to use the pos to iterate around a vertex:
+
+    sf/apps/sample/trimesh_pos_demo/trimesh_pos_demo.cpp
+
+    #include <vcg/simplex/face/pos.h> // include the definition of pos
+
+    ...includes to define your mesh type
+
+    class MyVertex: ...
+    class MyFace: public vcg::FaceSimp2<MyVertex,MyEdge,MyFace, vcg::face::VertexRef, vcg::face::FFAdj>{};
+
+    void OneRingNeighborhood( MyFace * f)
+    {
+      MyVertex * v = f->V(0);
+      MyFace* start = f;
+      vcg::face::Pos<MyFace> p(f,0,v);// constructor that takes face, edge and vertex
+      do
+      {
+        p.FlipF();
+        p.FlipE();
+      }while(p.f!=start);
+    }
+
+Two important notes:
+
+We arbitrarily picked f->V(0) as pivot vertex. In general one may want to start knowing the vertex. This is done by including the attribute vcg::vertex::VFAdj which basically associates to each vertex pointer to one of the faces incident on it. See the VF Adjacency for details.
+This implementation does not work if the vertex is on the border. Just try with the example: from the pos c4 it would find c5,c6,c3 which is in the same face as c4. Of course this does not happen if you use the pos itself as a guard and not just the face. However, even in this case, you would obtain the sequence of pos: c5,c6,c3,c1,c0,c4 corresponding to the faces f2,f2,f1,f0,f0,f1 which probably is not what you want. VCG Lib provides a variation of pos that solves this problem
+
+Jumping Pos
+-----------
+The Jumping Pos works exactly like the Pos, only it does not bounce when it encounters the border. Instead, it jump around the vertex as if the to border faces sharing the vertex (faces f0 and f2 in the image) were adjacent.
+\code
+sf/apps/sample/trimesh_pos_demo/trimesh_pos_demo.cpp
+
+    #include <vcg/simplex/face/jumping_pos.h> // include the definition of jumping pos
+
+    //...includes to define your mesh type
+
+    //class MyVertex: ...
+    class MyFace: public vcg::FaceSimp2<MyVertex,MyEdge,MyFace, vcg::face::VertexRef,vcg::face::FFAdj>{};
+
+    void OneRingNeighborhoodJP( MyFace * f)
+    {
+      MyVertex * v = f->V(0);
+      MyFace* start = f;
+      vcg::face::JumpingPos<MyFace> p(f,0,v);// constructor that takes face, edge and vertex
+      do
+      {
+        p.NextFE();
+      }while(p.f!=start);
+    }
+\endcode
+VF Adjacency
+------------
+
+VCG Lib implements vertex-to-face adjacency, i.e. given a vertex v we can retrieve all the faces incident to v.
+Let v_star =(f0,f1,f2,...,fk) be the set faces incident to v arranged in a sequence (with no preferred criteria).
+VCG Lib allows to retrieve v_star in optimal time ( O( star_v) ) by using the following attributes:
+
+- vcg::vertex::VFAdj which is a vertex attribute containing a pointer to f0
+- vcg::face::VFAdj which is a face attribute containing a pointer to the next face in the list v_star for each of its 3 vertices
+
+These two attributes are not only a pointers, they also contain an index referring the index of the vertex in the pointed face 
+in the same style as the vcg::face::FFAdj does. The picture below shows a practical example:
+Similarly to the *Face-Face* adjacency you need to initialize it using vcg::tri::UpdateTopology::VertexFace(MeshType & m).
+\image html "VertexStar.png" "Example of vertex-face adjacency"
+
+    v.VFp() == f2
+    v.VFi() == 0
+
+    f2->VFp(0) == f3
+    f2->VFi(0) == 1
+    f3->VFp(1) == f1
+    f3->VFi(1) == 2
+    f1->VFp(2) == f0
+    f1->VFi(2) == 2
+    f0->VFp(2) == NULL
+    f0->VFi(2) == -1
+
+VFIterator
+----------
+
+VFIterator is a simple iterator to run over the faces in the one-ring neighborhood of a vertex using the VF Adjacency (it is just like Pos for the FF Adjacency) The following code snippet shows how to use the VFIterator:
+\code
+sf/apps/sample/trimesh_pos_demo/trimesh_vfiter_demo.cpp
+
+#include <vcg/simplex/face/pos.h> // include the definition of  VFIterator
+
+//...includes to define your mesh type
+
+class MyVertex: public vcg::VertexSimp2<MyVertex,MyEdge,MyFace, vcg::vertex::VFAdj /*,... other attributes*/ >{};
+class MyFace: public vcg::FaceSimp2<MyVertex,MyEdge,MyFace, vcg::face::VertexRef,vcg::face::VFAd>{};
+
+void OneRingNeighborhoodVF( MyVertex * v)
+{
+  vcg::face::VFIterator<MyFace> vfi(v); //initialize the iterator tohe first face
+  for(;!vfi.End();++vfi)
+  {
+    MyFace* f = vfi.F();
+    // ...do something with face f
+  }
+}
+\endcode
+Stars and Rings
+---------------
+We have a few handy functions to recover the set of faces/vertices incident on vertex:
+
+- \ref vcg::face::VFOrderedStarFF
+- \ref vcg::face::VVStarVF
+- \ref vcg::face::VFStarVF
+- \ref vcg::face::VFExtendedStarVF
+- \ref vcg::face::EFStarFF
+
+Few facts on FF adjacency and VF adjacency
+------------------------------------------
+
+Here we make a series of simple statements just to avoid confusion and try to help up choosing the adjacencies the best fit your needs.
+
+If the mesh is manifold, the one-ring neighborhood of a vertex computed by using Pos ( needs FF adjacency) is the same as the one computed by using VFIterator (needs VF adjacency). The order in which the faces are visited can be CW or CCW if using Pos, unspecified by using VIterator
+If the mesh is non-manifold, Pos may not find all the faces of the one-ring neighborhood of he vertex, VFIterator always does
+
+Boundary relations and adjacency
+--------------------------------
+In many algorithms you need to simply the boundary/border condition of a face, e.g. to know if a given face f has one or more adjacent faces on a specified edge e. Using FF adjacency this can be done simply by using the face::IsBorder(f,e) static function that simply checks if the pointer stored in face f on the edge e points to f itself. If you are navigating the mesh using a Pos, you have a Pos member function IsBorder() that reports the boundary condition of the current pos. Similarly, for testing manifoldness of specific places over a mesh, there is a face::IsManifold(f,e) static function and a IsManifold(e) function member of the pos class.
+
+If you are not using FF adjacency evaluating the boundary conditions could be not very efficient, so vcg library provides a technique to cook the current boundary conditions of the mesh into vertex and face flags. Use the members of the UpdateFlags static class to compute flags that reflects the current mesh status and the access these flags using the IsB(e) member function of the face class. Remember that flags based boundary information can become invalid if you change the mesh topology. On the other hand consider that many non-mesh-modifying algorithms do not require explicit FF adjacency but just boundary information (typical examples: most mesh smoothing and curvature computation algorithms).
+
+Please note that the boundary flags are set true also for non manifold conditions.
+
+*/
@@ -0,0 +1,78 @@
+/** \page allocation Allocating and Deleting mesh elements
+Creating elements
+=================
+To create a simple single triangle mesh or to add elements to an existing mesh you should use the AddVertices and AddFaces functions, elements are added at the end of the mesh. These functions returns a pointer to the first allocated element.
+
+Adding element to a vector can cause reallocation, and therefore invalidation of any pointer that points to the mesh elements. These fucntion manage safely re-allocation and updating of pointers for all the pointers stored internally in the mesh (e.g. if you add some vertices and that causes a reallocation of the vertex vector, the pointers from faces to vertices will be automatically updated by the Allocator functions.
+You should never directly reallocate or resize the vertex or face vectors.
+
+\dontinclude trimesh_allocate.cpp
+\skip MyMesh
+\until fi->V(2)=ivp[2];
+
+look to platonic.h for more examples.
+
+Alternatively you can add single vertex and faces in a more compact way as follows:
+
+\dontinclude trimesh_allocate.cpp
+\skip Alternative
+\until AddFace(
+
+
+If you keep internally some pointers to the mesh elements adding elements can invalidate them. In that case you should pass to the vcg::tri::Allocator functions a PointerUpdater to be used to update your private pointers.
+
+\dontinclude trimesh_allocate.cpp
+\skip dangerous
+\until NeedUpdate
+
+Destroying Elements
+-------------------
+
+The library adopts a <em>Lazy Deletion Strategy</em> i.e. the elements in the vector that are deleted are only \b flagged as deleted, but they are still there.
+
+Note that the basic deletion functions are very low level ones. They simply mark as deleted the corresponding entries without affecting the rest of the structures. So for example if you delete a vertex with these structures without checking that all the faces incident on it have been removed you could create a non consistent situation.
+Similarly, but less dangerously, when you delete a face its vertices are left around so at the end you can have unreferenced floating vertices.
+Again you should never, ever try to delete vertexes by yourself by directly flagging deleted, but you must call the Allocator utility function.
+The following snippet of code shows how to delete a few faces from an icosahedron.
+\dontinclude trimesh_allocate.cpp
+\skip Icosahedron
+\until face[3]
+After such a deletion the vector of the faces still contains 20 elements (number of faces of an icosahedron) but the \c m.FN() function correctly reports 18 faces.
+Therefore if your algorithm performs deletions it happens that the size of a container could be different from the number of valid element of your meshes:
+\code
+m.vert.size() != m.VN()
+m.face.size() != m.FN()
+\endcode
+
+Therefore when you scan the containers of vertices and faces you could encounter deleted elements so you should take care with a simple !IsD() check:
+\dontinclude trimesh_allocate.cpp
+\skip loop
+\until  }
+\until }
+In some situations, particularly when you have to loop many many times over the element of the mesh without deleting/creating anything, it can be practical and convenient to get rid of deleted elements by explicitly calling the two garbage collecting functions:
+\dontinclude trimesh_allocate.cpp
+\skip CompactFaceVector
+\until  CompactVertexVector
+After calling these function it is safe to not check the IsD() state of every element and always holds that:
+\code
+m.vert.size() == m.VN()
+m.face.size() == m.FN()
+\endcode
+\note If there are no deleted elements in your mesh, the compactor functions returns immediately (it just test that the container size match the number of the elements) so it is safe to call it before lenghty operations.
+\note If you are messing around with deleted elements it is rather dangerous to loop over mesh elements using \c FN() or \c VN() as end guards in the for; the following code snipped is \b WRONG:
+\dontinclude trimesh_allocate.cpp
+\skip WRONG
+\until  }
+\until }
+
+
+How to copy a mesh
+------------
+Given the intricate nature of the mesh itself it is severely forbidden any attempt of copying meshes as simple object. To copy a mesh you have to use the Append utility class:
+\dontinclude trimesh_allocate.cpp
+\skip m2
+\until Append
+
+In the vcg::tri::Append utility class there are also functions for copying only a subset of the second mesh (the selected one) or to append the second mesh to the first one.
+
+*/
@@ -0,0 +1,39 @@
+/** \page attributes
+User-Defined Attributes
+=======================
+VCG Lib also provides a simple mechanism to associate user-defined typed 'attributes' to the simplicies and to the mesh.
+
+Note that both 'attributes' and 'components' are basically accessory data that are bound to a simplex. In short, components are statically defined member data, while attributes are run-time defined, handle accessed, data.
+
+Conceptually the difference is that with the term component VCGLib indicates those basic values that are considered to 'define' the simplex (its position, its normal, its connectivity information), while an user defined attribute is an accessory data that is useful for some specific algorithms, like "the average direction from which a vertex is visible".
+
+Practically the difference is that every optional component has its non optional counterpart and is accessed through a member function of the simplex, so that when you write your algorithm you use vi->N() to access the normal both it is has been declared as optional or not, while the attributes are accessed by a handle which is returned at the creation of the attribute.
+
+The following code snippet shows how to add an attribute:
+ \snippet trimesh_attribute.cpp Adding an attribute
+
+Once you have the handle retrieving and using the attributes is rather simple by mean of the [] operator:
+
+\snippet trimesh_attribute.cpp Using an attribute
+
+You also have functions to check if a given attribute exists, to retrieve an handle for it and for, eventually, deleting it (using the handle or by name).
+Remember that the scope of a handle does not interfere with the memory allocation of the attribute. If you do not delete an attribute explicitly, it will stay allocated until the mesh itself is destroyed, even if you do not have any more handles to it.
+
+\snippet trimesh_attribute.cpp Deleting an attribute
+
+The same can be done for edges, faces and for the mesh itself, just replace the occurences of PerVertex with PerFace, PerEdge and PerMesh.
+Note that if you call add an attribute without specifying a name and you lose the handle, you will not be able to get your handle back.
+For attributes specified as per-mesh the access is done in a slightly different way. 
+\snippet trimesh_attribute.cpp Per Mesh attribute
+
+
+
+C++ type of a mesh and reflection
+---------------------------------
+
+VCG Lib provides a set of functions to implement reflection, i.e. to investigate the type of a mesh at runtime. These functions follow the format Has[attribute](mesh) and return a boolean stating if that particular attribute is present or not.
+
+
+You may wonder why those functions are not statically typed and why they needs the mesh object, i.e. why can't you just write ComputeMeshType::HasPerVertexNormal()? The reason is that VCG Lib reflection takes into account optional components, therefore HasPerVertexNormal(m) will return true if the type of the vertex contains the attribute as permanent (e.g. vcg::vertex::Normal3f) OR if it contains the attribute as optional (e.g. vcg::vertex::Normal3fOcf) AND it is enabled, i.e. the relative Enable function has been called.
+
+*/
@@ -0,0 +1,124 @@
+/** \page basic_concepts Basic Concepts
+How to define the type of a mesh
+=========================
+The VCG Lib may encode a mesh in several ways, the most common of which is a vector of vertices and vector of triangles (i.e. triangles for triangle meshes, tetrahedra for tetrahedral meshes). The following line is an example of the definition of a VCG type of mesh:
+
+\dontinclude trimesh_base.cpp
+\skip MyMesh
+\until MyMesh
+
+
+where vcg::tri::TriMesh is the base type for a triangle mesh and it is templated on:
+- the type of container containing the vertices (usually a std::vector
+ - which in turn is templated on your vertex type
+- the type of STL random access container containing the faces
+ - which in turn is templated on your face type
+
+In other words, to define a type of mesh you need only to derive from vcg::tri::TriMesh and to provide the type of containers of the elements you want to use to encode the mesh. In this second example we also passed a std::vector of type MyEdge, which, as we will see shortly, is the type of our edge. Note that there is no predefined order to follow for passing the template parameters to TriMesh.
+\dontinclude trimesh_base.cpp
+\skip complex.h
+\until complex.h
+\skip class
+\until MyMesh
+
+The face, the edge and the vertex type are the crucial bits to understand in order to be able to take the best from VCG Lib. A vertex, an edge, a face and a tetrahedron are just an user defined (possibly empty) collection of attributes. For example you will probably expect MyVertex to contain the (x,y,z) position of the vertex, but what about the surface normal at the vertex?.. and the color? VCG Lib gives you a pretty elegant way to define whichever attributes you want to store in each vertex, face, or edge. For example, the following example shows three valid definitions of MyVertex of increasing complexity :
+
+\dontinclude trimesh_base.cpp
+\skip MyVertex0
+\until Qualityf
+
+\c vcg::Vertex is the VCG base class for a vertex.
+\c vcg::UsedTypes declares which are the types involved in the definition of the mesh. It is a mapping between the names of your entity types (MyVertex,MyEdge,MyFace... and the role they play in the mesh definition). The mapping is established passing the template parameters with the syntax
+It can be annoying when you see it but it is useful that every entity involved knows the type of the others and this is the way VCG Lib does it. As you can see the three definitions of MyVertex0,1,2 differ for the remaining template parameters (the components). These specify which values will be stored with the vertex type:
+- MyVertex0 is a type storing coordinates as a triple of doubles and normal as a triple of floats,
+- MyVertex1 also store a color value specified as 4 bytes
+- MyVertex2 store a long list of different components.
+
+Many other components are implemented in the library for the simplexes, the complete list can be found
+in the \ref VertexComponentGroup, \ref EdgeComponentGroup and \ref FaceComponentGroup pages. You can place any combination of them as
+a template parameters of your vertex/edge/face type (note that order is rather unimportant).
+Now we have all it takes for a working definition of MyMesh type:
+
+\dontinclude trimesh_base.cpp
+\skip complex.h
+\until complex.h
+\skip class
+\until MyMesh
+\skip main
+\until }
+\until }
+\until }
+
+
+One more comment: \c vcg::face::VertexRef is an attribute that stores 3 pointers to the type of vertex, so implementing the Indexed Data structure. This is an example of why the type MyFace needs to know the type MyVertex
+
+How to create a mesh
+--------------------
+Once you declared your mesh type, you may want to instance an object and to fill it with vertices and triangles. The typical approach is just to open some file like in the above example. It may cross your mind that you could just make some push_back on the vertexes and faces container (data member vert and face of class vcg::tri::Trimesh). In fact this is the wrong way since there can be side effects by adding an element to a container. We describe this issue and the correct way of adding mesh element in the \ref allocation page.
+
+The flags of the mesh elements
+-----------
+Usually to each element of the mesh we associate a small bit vector containing useful single-bit information about vertices and faces. For example the deletion of vertex simply mark a the Deletion bit in this vector (more details on the various deletion/allocation issues in the \ref allocation page. More details on the various kind of flags that can be associated are in the \ref flags page.
+
+How to process a mesh
+-------------
+The algorithms that do something on a mesh are generally written as a static member functions of a templated class on the mesh type. For example the code snipped below is part of the class UpdateNormals, which contains the several algorithms to compute the value of the normal
+
+\code
+...
+template <class ComputeMeshType>
+class UpdateNormals{
+...
+// Calculates the face normal (if stored in the current face type)
+static void PerFace(ComputeMeshType &m)
+
+// Calculates the vertex normal. Without exploiting or touching face normals
+// The normal of a vertex v is the weighted average of the normals of the faces incident on v.
+static void PerVertex(ComputeMeshType &m)
+
+// Calculates both vertex and face normals.
+// The normal of a vertex v is the weighted average of the normals of the faces incident on v.
+static void PerVertexPerFace(ComputeMeshType &m)
+...
+};
+\endcode
+This class is part of a kernel of classes with name UpdateValue that compute the value of the vertex or face attributes and that can be found altogether in the folder vcg/complex/trimesh/update. For example, the following example shows how to compute the value of the normal and the mean and gaussian curvature per vertex:
+\code
+
+#include <vector>
+
+#include <vcg/simplex/vertex/base.h>
+#include <vcg/simplex/vertex/component.h>
+#include <vcg/simplex/face/base.h>
+#include <vcg/simplex/face/component.h>
+
+#include <vcg/complex/base.h>
+#include <vcg/complex/algorithms/update/normal.h>    //class UpdateNormals
+#include <vcg/complex/algorithms/update/curvature.h> //class UpdateCurvature
+
+class MyVertex;
+class MyFace;
+class MyUsedTypes: public vcg::UsedTypes< vcg::Use<MyVertex>::AsVertexType>,
+                                          vcg::Use<MyFace>::AsFaceType>
+
+class MyVertex: public vcg::Vertex<MyUsedTypes, vcg::vertex::BitFlags,vcg::vertex::Coord3d, vcg::vertex::Normal3f,vcg::vertex::Curvaturef>{};
+class MyFace: public vcg::Face<MyUsedTypes, vcg::face::BitFlags,vcg::face::VertexRef>{};
+class MyMesh: public vcg::tri::TriMesh< std::vector<MyVertex>, std::vector<MyFace> > {};
+
+int main()
+{
+  MyMesh m;
+  // fill the mesh
+  ...
+  // compute the normal per-vertex -> update the value of v.N() for all v (vcg::vertex::Normal3f)
+  vcg::tri::UpdateNormals<MyMesh>::PerVertexPerFace(m);
+
+  // compute the curvature per-vertex -> update the value of v.H() and v.K() (vcg::vertex::Curvaturef)
+  vcg::tri::UpdateCurvature<MyMesh>::MeanAndGaussian(m);
+
+  return 0;
+}
+\endcode
+
+Other than algorithms that update values of the mesh attributes, VCG Lib provides algorithms to create a mesh from another source, for example from point sets (by means of the Ball Pivoting approach) or as isosurfaces from a volumetric dataset (by means of Marching Cubes algorithm). Those algorithms can be found in vcg/complex/trimesh/create/.
+Finally, you can find algorithms for refinement (midpoint, Loop, Butterfly...), for smoothing, for closing holes and other that are not currently classified under any specific heading and that you can find under /vcg/complex/trimesh.*/
@@ -0,0 +1,45 @@
+/** \page fileformat File Formats
+File Formats
+============
+VCGLib provides importer and exporter for several file formats
+- import: PLY, STL, OFF, OBJ, 3DS, COLLADA, PTX, V3D, PTS, APTS, XYZ, GTS, TRI, ASC, X3D, X3DV, VRML, ALN
+- export: PLY, STL, OFF, OBJ, 3DS, COLLADA, VRML, DXF, GTS, U3D, IDTF, X3D
+
+The following code snippet show how to use the PLY importer and exporter:
+\code
+#include <wrap/io_trimesh/import.h>
+// definition of type MyMesh
+MyMesh m;
+
+vcg::tri::io::ImporterPLY<MyMesh>::Open(m,"namefile_to_open.ply");
+// ....
+vcg::tri::io::ExporterPLY<MyMesh>::Save(m,"namefile_to_save.ply");
+\endcode
+
+The previous one is the minimal required interface for all the importers and exporters. Additionally two other parameters can be specified: *mask* and *callback*. The callback is used for providing a feedback during the usually length importing/exporting process. The mask is used to better specify/understand what is loaded/saved.
+
+Saving Mask and Reading Mask
+----------------------------
+Generally all file formats save at least vertex positions and basic connectivity information, but beyond that you may want to choose which other data are stored with the file. To this aim, VCGLib provides a class `vcg::tri::io::Mask` which is essentially a collection of bit names that are used to specify which components you want to write to the file (e.g. stuff like `vcg::tri::io::Mask::IOM_VERTCOLOR`).
+
+When __saving__ this mask is used in a READ ONLY mode (they are just constants) to specify what component you want to save. For example, if you have stored in your mesh normals per vertex (for rendering purposes) but you consider saving them in ply format just a waste of space, you should specify an appropriate mask with the `Mask::IOM_VERTNORMAL` bit cleared. Obviously not all the formats are able to save all the possible data. For example STL format cannot save texture coords or per vertex color. So to know what you are able to save in a given XXX format there is the function `ExporterXXX::GetExportMaskCapability()` that gives you a bitmask with all the capability of that file format.
+
+When __loading__ this mask is used in a WRITE ONLY mode to report to the user what fields have been loaded from the file into the mesh (e.g. the initial value of the mask is ignored). In many cases it could be useful to know what data is present into a file to prepare the mesh (e.g. to enable optional components), for this purpose all the importer have also a `ImporterXXX::LoadMask(filename,mask)` that fill the mask only without effectively loading a mesh. Note that for some mesh formats understanding what is contained into a file means parsing the whole file.
+
+Error Reporting
+---------------
+The mesh I/O functions returns ZERO on success and an error code different from zero in case of failure or critical conditions. Use the `static const char *ErrorMsg(int error)` function to get a human understandable description of the error code and static bool `ErrorCritical(int err)` to know if a given error is a critical one or just a warning. For example in the OBJ format the absence of the accompanying material description file, is considered non critical (you are able to get the correct geometry even if you miss material info).
+
+VMI dump file
+-------------
+VMI is an acronym for Vcglib Mesh Image and it is not a proper file format but a simple dump of the `vcg::TriMesh` on a file. Not being a file format means that:
+there is no specification
+it is bound to the current version of the VCGLib with no backward compatibility
+a VMI can be very useful for debug purpose, because it saves:
+* all the components
+* all the temporary components (currently only of Optional Component Fast type)
+* all the vertex, face or mesh attributes you have in your mesh file
+So if, for example, your algorithm crashes at the n-th step, you can save intermediate results of your computation with VMI and reload it.
+Note that in order to load a VMI the mesh passed as template to `vcg::tri::ImporterVMI<MeshType>(..)` must be of the same type as the mesh passed to `vcg::tri::ExporterVMI<MeshType>(..)` otherwise the loader returns FALSE.
+
+*/
@@ -0,0 +1,56 @@
+/** \page flags Bit Flags
+
+For each simplex of the mesh we have a component called \c BitFlags that store a fixed size vector of 32 bits that are used for a variety of needs.
+Related classes to manage these flags: <br>
+- \ref vcg::tri::UpdateFlags (defined in flag.h)
+- \ref vcg::tri::UpdateSelection (defined in selection.h)
+
+Delete Bit
+----------
+\code
+IsD(),
+ClearD(); // deprecated
+SetD()    // deprecated
+\endcode
+This bit flag is the most used one; see \ref allocation page for more detail on its use.
+\warning you should \b never directly nvoke \c SetD() or \c ClearD(), but you should use the function described in the vcg::tri::Allocator.
+
+Border Bit
+----------
+\code
+IsB(),
+ClearB(),
+SetB()
+\endcode
+To store the fact that a vertex or a face is on the boundary. These bits are not computed by default.
+They can be computed with or without the topology (obviously if you FF topology the computation of these bit is faster). <br>
+The rationale of these bits is that there are a lot of algorithms that need only boundary information for correctly working
+so computing it once is sufficient without needing to burden everything with the whole FF topology structure.
+
+
+Selection bit
+-------------
+IsS(), ClearS(), SetS()
+
+Visiting bit
+------------
+
+IsV(), ClearV(), SetV() Useful bit for any algorithm. You should not rely on the state of this bit or store anything persistent here. Any algorithm can clear it and use it for its own local purposes. use tri::UpdateFlags<YourMeshClass>::VertexClearV(yourMesh) to clear all bits.
+
+User bits
+---------
+
+If you want to allocate some private bits among the one stored with your mesh elements you can do it by mean of the NewBitFlag() function that returns a mask that can be used for setting, clearing and testing elements against that particular bit. The following example allocate three new bits for each face and clear them.
+
+int e0bit = MyFace::NewBitFlag();
+int e1bit = MyFace::NewBitFlag();
+int e2bit = MyFace::NewBitFlag();
+int ebit[3] = {e0bit,e1bit,e2bit};
+
+for(MyMesh::FaceIterator fi=m.face.begin();fi!=m.face.end();++fi)
+	for(int i=0;i<3;++i)
+		(*fi).ClearUserBit(ebit[i]);
+The task of clearing a given bit of all the faces (vertexes) of a mesh can be done with
+tri::UpdateFlags<YourMeshClass>::FaceClear(yourMesh,e0bit|e1bit|e2bit);
+to clear all bits.
+*/
@@ -0,0 +1,36 @@
+
+
+/** \defgroup space Space
+This module contains all the basic types for representing spatial entities like points (vcg::Point3) box3, line planes etc.
+This module contains the documentation for the types and the functions used for...
+*/
+
+/** \defgroup math Math
+This module contains the documentation for the types and the functions used for representing and managing mathematical entities.
+*/
+
+/** \defgroup VertexComponentGroup Vertex Components
+\brief Components that you can use to compose your Vertex type
+*/
+
+/** \defgroup EdgeComponentGroup Edge Components
+\brief Components that you can use to compose your Edge type
+*/
+
+/** \defgroup FaceComponentGroup Face Components
+\brief Components that you can use to compose your Face type
+*/
+
+/** \defgroup trimesh Triangular Meshes
+This module contains the documentation for the types and the functions used for representing and managing generic \b triangular \b meshes.
+*/
+
+/** \defgroup code_sample Code Examples
+\brief This module contains a number of small examples to explain the library features
+
+All the examples here listed are located in the folder `vcglib/apps/sample`. 
+To compile each sample, please use the corresponding `qmake`  `*.pro` project files. 
+
+
+*/
+
@@ -0,0 +1,311 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="744.09448819"
+   height="1052.3622047"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.1 r9760"
+   sodipodi:docname="vcglogo.svg">
+  <defs
+     id="defs4" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.6448421"
+     inkscape:cx="995.39411"
+     inkscape:cy="396.26054"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="true"
+     inkscape:window-width="1870"
+     inkscape:window-height="1156"
+     inkscape:window-x="50"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1">
+    <inkscape:grid
+       type="xygrid"
+       id="grid2987" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <rect
+       style="fill:none;stroke:none;stroke-width:1.99999975999999990;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+       id="rect3853"
+       width="460"
+       height="265"
+       x="90"
+       y="587.36218"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-ydpi="200.35001" />
+    <text
+       sodipodi:linespacing="125%"
+       id="text3040"
+       y="839.36218"
+       x="100"
+       style="font-size:61.15526199000001384px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#006080;fill-opacity:1;stroke:#003040;font-family:Century Gothic;-inkscape-font-specification:Century Gothic;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       xml:space="preserve"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-ydpi="200.35001"><tspan
+         y="839.36218"
+         x="100"
+         id="tspan3042"
+         sodipodi:role="line">L  I  B  R  A  R  Y </tspan></text>
+    <path
+       style="fill:#006080;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;fill-opacity:1;stroke-opacity:1"
+       inkscape:transform-center-x="-1.0790028"
+       inkscape:transform-center-y="-5.3460821"
+       d="m 210,607.36218 -105,180.00001 210,0 z"
+       id="path3044"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cccc"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-ydpi="200.35001" />
+    <path
+       sodipodi:nodetypes="cccc"
+       inkscape:connector-curvature="0"
+       id="path3046"
+       d="m 430,607.36218 -105,180 210,0 z"
+       inkscape:transform-center-y="-5.3460821"
+       inkscape:transform-center-x="-1.0790028"
+       style="fill:#006080;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;fill-opacity:1;stroke-opacity:1"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-ydpi="200.35001" />
+    <path
+       style="fill:#006080;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;fill-opacity:1;stroke-opacity:1"
+       inkscape:transform-center-x="-1.0790028"
+       inkscape:transform-center-y="5.3460821"
+       d="m 320,781.36218 -105,-180 210,0 z"
+       id="path3048"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cccc"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-ydpi="200.35001" />
+    <text
+       xml:space="preserve"
+       style="font-size:108px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:#003040;font-family:Century Gothic;-inkscape-font-specification:Century Gothic;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       x="172.11035"
+       y="769.17273"
+       id="text3050"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-ydpi="200.35001"><tspan
+         sodipodi:role="line"
+         id="tspan3052"
+         x="172.11035"
+         y="769.17273">V</tspan></text>
+    <text
+       sodipodi:linespacing="125%"
+       id="text3054"
+       y="769.17273"
+       x="379.77051"
+       style="font-size:108px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:#003040;font-family:Century Gothic;-inkscape-font-specification:Century Gothic;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       xml:space="preserve"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-ydpi="200.35001"><tspan
+         y="769.17273"
+         x="379.77051"
+         id="tspan3056"
+         sodipodi:role="line">G </tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:108px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:#003040;font-family:Century Gothic;-inkscape-font-specification:Century Gothic;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       x="273.19824"
+       y="700.36218"
+       id="text3058"
+       sodipodi:linespacing="125%"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-ydpi="200.35001"><tspan
+         sodipodi:role="line"
+         id="tspan3060"
+         x="273.19824"
+         y="700.36218">C </tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
+       x="367.91953"
+       y="778.65179"
+       id="text3830"
+       sodipodi:linespacing="125%"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-ydpi="200.35001"><tspan
+         sodipodi:role="line"
+         id="tspan3832"
+         x="367.91953"
+         y="778.65179"> </tspan></text>
+    <rect
+       inkscape:export-ydpi="200.35001"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       y="147.72942"
+       x="121.37207"
+       height="265"
+       width="460"
+       id="rect3858"
+       style="fill:none;stroke:none" />
+    <path
+       inkscape:connector-curvature="0"
+       id="path3887"
+       style="font-size:61.15526199px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       d="m 136.71719,355.80398 4.41942,0 0,39.6852 16.87145,0 0,4.2402 -21.29087,0 0,-43.9254" />
+    <path
+       inkscape:connector-curvature="0"
+       id="path3889"
+       style="font-size:61.15526199px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       d="m 198.32036,355.80398 4.38956,0 0,43.9254 -4.38956,0 0,-43.9254" />
+    <path
+       inkscape:connector-curvature="0"
+       id="path3891"
+       style="font-size:61.15526199px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       d="m 246.96387,355.80398 8.65968,0 c 3.48376,0 6.1613,0.418 8.0326,1.2541 1.87127,0.8163 3.34441,2.0804 4.41943,3.7924 1.09487,1.712 1.64232,3.6132 1.64235,5.7034 -3e-5,1.9509 -0.4778,3.7327 -1.43333,5.3451 -0.95557,1.5926 -2.35904,2.8866 -4.21039,3.8819 2.28931,0.7764 4.05111,1.6922 5.28539,2.7472 1.23422,1.0352 2.18977,2.2994 2.86665,3.7924 0.69673,1.4731 1.0451,3.0757 1.04513,4.8076 -3e-5,3.5236 -1.294,6.5097 -3.88192,8.9583 -2.56807,2.4287 -6.02198,3.643 -10.36176,3.643 l -12.06383,0 0,-43.9254 m 4.29998,4.2999 0,14.0645 2.50832,0 c 3.04581,10e-5 5.28538,-0.2786 6.71872,-0.8361 1.43331,-0.5772 2.56802,-1.4731 3.40415,-2.6874 0.83608,-1.2343 1.25414,-2.5979 1.25416,-4.091 -2e-5,-2.0106 -0.70673,-3.5833 -2.12013,-4.718 -1.39353,-1.1546 -3.62315,-1.7319 -6.68885,-1.732 l -5.07637,0 m 0,18.484 0,16.8416 5.4347,0 c 3.20506,0 5.55412,-0.3086 7.04719,-0.9257 1.49302,-0.6371 2.68746,-1.6225 3.58331,-2.9563 0.91571,-1.3337 1.37358,-2.777 1.37361,-4.3298 -3e-5,-1.9509 -0.63706,-3.653 -1.91111,-5.1062 -1.27409,-1.4532 -3.02593,-2.4486 -5.25553,-2.9861 -1.49306,-0.3583 -4.09096,-0.5375 -7.79371,-0.5375 l -2.47846,0" />
+    <path
+       inkscape:connector-curvature="0"
+       id="path3893"
+       style="font-size:61.15526199px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       d="m 316.12188,355.80398 8.74926,0 c 4.87727,0 8.18188,0.1991 9.91384,0.5972 2.60783,0.5972 4.72796,1.8813 6.36039,3.852 1.63236,1.951 2.44856,4.3598 2.4486,7.2264 -4e-5,2.3889 -0.5674,4.4891 -1.70208,6.3007 -1.11484,1.8115 -2.71738,3.1851 -4.80762,4.1208 -2.09029,0.9157 -4.97684,1.3835 -8.65968,1.4034 l 15.79646,20.4249 -5.4347,0 -15.76659,-20.4249 -2.50832,0 0,20.4249 -4.38956,0 0,-43.9254 m 4.38956,4.2999 0,14.9305 7.55482,0.06 c 2.92636,10e-5 5.0863,-0.2786 6.47983,-0.8361 1.4134,-0.5573 2.5083,-1.4432 3.28471,-2.6576 0.79626,-1.2342 1.19441,-2.6078 1.19444,-4.1208 -3e-5,-1.4731 -0.39818,-2.8069 -1.19444,-4.0014 -0.79632,-1.2143 -1.84145,-2.0803 -3.1354,-2.5979 -1.294,-0.5175 -3.44399,-0.7763 -6.44997,-0.7764 l -7.73399,0" />
+    <path
+       inkscape:connector-curvature="0"
+       id="path3895"
+       style="font-size:61.15526199px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       d="m 404.89854,355.80398 20.48462,43.9254 -4.71803,0 -6.89789,-14.4527 -18.93185,0 -6.86802,14.4527 -4.8972,0 20.75337,-43.9254 1.075,0 m -0.5375,9.3166 -7.55483,15.9159 15.02007,0 -7.46524,-15.9159" />
+    <path
+       inkscape:connector-curvature="0"
+       id="path3897"
+       style="font-size:61.15526199px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       d="m 466.38225,355.80398 8.74926,0 c 4.87728,0 8.18189,0.1991 9.91385,0.5972 2.60783,0.5972 4.72795,1.8813 6.36038,3.852 1.63237,1.951 2.44857,4.3598 2.4486,7.2264 -3e-5,2.3889 -0.56739,4.4891 -1.70207,6.3007 -1.11484,1.8115 -2.71738,3.1851 -4.80762,4.1208 -2.09029,0.9157 -4.97685,1.3835 -8.65968,1.4034 l 15.79645,20.4249 -5.43469,0 -15.7666,-20.4249 -2.50832,0 0,20.4249 -4.38956,0 0,-43.9254 m 4.38956,4.2999 0,14.9305 7.55483,0.06 c 2.92635,10e-5 5.08629,-0.2786 6.47983,-0.8361 1.41339,-0.5573 2.50829,-1.4432 3.2847,-2.6576 0.79627,-1.2342 1.19441,-2.6078 1.19444,-4.1208 -3e-5,-1.4731 -0.39817,-2.8069 -1.19444,-4.0014 -0.79631,-1.2143 -1.84145,-2.0803 -3.1354,-2.5979 -1.294,-0.5175 -3.44398,-0.7763 -6.44997,-0.7764 l -7.73399,0" />
+    <path
+       inkscape:connector-curvature="0"
+       id="path3899"
+       style="font-size:61.15526199px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       d="m 533.74861,355.80398 5.07637,0 11.22772,18.0957 11.04856,-18.0957 5.07636,0 -13.91521,22.9332 0,20.9922 -4.32984,0 0,-20.9922 -14.18396,-22.9332" />
+    <path
+       inkscape:export-ydpi="200.35001"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       sodipodi:nodetypes="cccc"
+       inkscape:connector-curvature="0"
+       id="path3864"
+       d="m 241.37207,167.72938 -105,180 210,0 z"
+       inkscape:transform-center-y="-5.3460821"
+       inkscape:transform-center-x="-1.0790028"
+       style="fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <path
+       inkscape:export-ydpi="200.35001"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       style="fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       inkscape:transform-center-x="-1.0790028"
+       inkscape:transform-center-y="-5.3460821"
+       d="m 461.37207,167.72938 -105,180 210,0 z"
+       id="path3866"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cccc" />
+    <path
+       inkscape:export-ydpi="200.35001"
+       inkscape:export-xdpi="200.35001"
+       inkscape:export-filename="/Users/cignoni/devel/vcglib/docs/Doxygen/img/text3830.png"
+       sodipodi:nodetypes="cccc"
+       inkscape:connector-curvature="0"
+       id="path3868"
+       d="m 351.37207,341.72938 -105,-180 210,0 z"
+       inkscape:transform-center-y="5.3460821"
+       inkscape:transform-center-x="-1.0790028"
+       style="fill:#006080;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
+    <g
+       style="font-size:108px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       id="text3870"
+       transform="translate(-28.85742,-922.82222)">
+      <path
+         d="m 235.87305,1174.7899 8.4375,0 25.68164,59.959 26.15625,-59.959 8.4375,0 -33.75,77.5723 -1.6875,0 -33.27539,-77.5723"
+         id="path3915"
+         inkscape:connector-curvature="0" />
+    </g>
+    <g
+       style="font-size:108px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       id="text3874"
+       transform="translate(-28.85742,-922.82222)">
+      <path
+         d="m 524.26953,1187.8153 -6.01172,5.6953 c -4.32429,-4.2538 -9.07038,-7.4706 -14.23828,-9.6504 -5.13287,-2.2147 -10.14263,-3.3222 -15.0293,-3.3222 -6.08207,0 -11.88285,1.4942 -17.40234,4.4824 -5.4844,2.9883 -9.7383,7.0489 -12.76172,12.1816 -3.02345,5.0977 -4.53517,10.4942 -4.53515,16.1895 -2e-5,5.836 1.56443,11.3906 4.69335,16.664 3.12889,5.2383 7.4531,9.3692 12.97266,12.3926 5.5195,2.9883 11.56636,4.4824 18.14063,4.4824 7.98041,0 14.7304,-2.25 20.25,-6.75 5.51945,-4.4999 8.78898,-10.3359 9.80859,-17.5078 l -24.73242,0 0,-7.4883 33.43359,0 c -0.0704,11.9884 -3.63876,21.5157 -10.70508,28.5821 -7.03132,7.0312 -16.45318,10.5469 -28.26562,10.5469 -14.34379,0 -25.69924,-4.8868 -34.06641,-14.6602 -6.4336,-7.5234 -9.65039,-16.2246 -9.65039,-26.1035 0,-7.3476 1.8457,-14.1855 5.53711,-20.5137 3.69139,-6.328 8.75389,-11.2675 15.1875,-14.8183 6.43356,-3.5859 13.7109,-5.3789 21.83203,-5.379 6.57417,10e-5 12.76166,1.1954 18.5625,3.586 5.80071,2.3555 11.46086,6.1524 16.98047,11.3906"
+         id="path3909"
+         inkscape:connector-curvature="0" />
+    </g>
+    <g
+       style="font-size:108px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#ffffff;fill-opacity:1;stroke:#003040;stroke-width:2;stroke-miterlimit:4;stroke-opacity:1;font-family:Century Gothic;-inkscape-font-specification:Century Gothic"
+       id="text3878"
+       transform="translate(-28.85742,-922.82222)">
+      <path
+         d="m 415.11328,1120.3759 -6.11719,4.6933 c -3.37507,-4.3945 -7.43561,-7.7167 -12.18164,-9.9668 -4.71099,-2.2851 -9.89653,-3.4276 -15.55664,-3.4277 -6.18754,10e-5 -11.918,1.4942 -17.1914,4.4824 -5.27347,2.9532 -9.36917,6.9434 -12.28711,11.9707 -2.88283,4.9922 -4.32424,10.6172 -4.32422,16.875 -2e-5,9.4571 3.23436,17.3496 9.70312,23.6777 6.50388,6.3282 14.69528,9.4922 24.57422,9.4922 10.86322,0 19.95111,-4.2539 27.26367,-12.7617 l 6.11719,4.6406 c -3.86726,4.9219 -8.70124,8.7364 -14.50195,11.4434 -5.76569,2.6719 -12.21685,4.0078 -19.35352,4.0078 -13.57034,0 -24.27541,-4.5176 -32.11523,-13.5527 -6.57423,-7.6289 -9.86134,-16.8398 -9.86133,-27.6328 -10e-6,-11.3555 3.97265,-20.9004 11.91797,-28.6348 7.98044,-7.7695 17.96481,-11.6542 29.95312,-11.6543 7.24214,10e-5 13.78119,1.4415 19.61719,4.3242 5.83587,2.8477 10.61711,6.8556 14.34375,12.0235"
+         id="path3912"
+         inkscape:connector-curvature="0" />
+    </g>
+    <text
+       inkscape:export-ydpi="200.35001"
+       inkscape:export-xdpi="200.35001"
+       sodipodi:linespacing="125%"
+       id="text3882"
+       y="339.0191"
+       x="399.2916"
+       style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
+       xml:space="preserve"><tspan
+         y="339.0191"
+         x="399.2916"
+         id="tspan3884"
+         sodipodi:role="line"> </tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
+       x="780"
+       y="252.36218"
+       id="text3917"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3919"
+         x="780"
+         y="252.36218">&lt;--This is as path (no font!)</tspan></text>
+    <text
+       sodipodi:linespacing="125%"
+       id="text3921"
+       y="712.36218"
+       x="760"
+       style="font-size:18px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
+       xml:space="preserve"><tspan
+         y="712.36218"
+         x="760"
+         id="tspan3923"
+         sodipodi:role="line">&lt;--This is as text (need the Century Gothic font!)</tspan></text>
+  </g>
+</svg>
@@ -0,0 +1,60 @@
+/** \mainpage The VCG Library
+The Visualization and Computer Graphics Library (VCG for short) is
+a open source portable C++ templated library for manipulation, processing
+and displaying with OpenGL of triangle and tetrahedral meshes.
+
+VCG Lib uses a git repository hosted by github at http://github.com/cnr-isti-vclab/vcglib/
+
+The library, composed by more than 100k lines of code,
+is released under the GPL license, and it is the base of most of the
+software tools of the <b>Visual Computing Lab</b> of the Italian National Research Council Institute ISTI
+(http://vcg.isti.cnr.it), like metro and MeshLab.
+
+
+The VCG library is tailored to mostly manage triangular meshes:
+The library is fairly large and offers many state of the art functionalities for processing meshes, like:
+- high quality quadric-error edge-collapse based simplification,
+- efficient spatial query structures (uniform grids, hashed grids, kdtree, ...) ,
+- advanced smoothing and fairing algorithms,
+- computation of curvature,
+- optimization of texture coordinates,
+- Hausdorff distance computation,
+- Geodesic paths,
+- mesh repairing capabilities,
+- isosurface extraction and advancing front meshing algorithms,
+- Poisson Disk sampling and other tools to sample point distributions over meshes,
+- subdivision surfaces,
+
+Documentation
+-------
+
+Start from the following pages for basic concepts and examples.
+- \subpage install "Installing the VCG Library"
+- \subpage basic_concepts "Basic Concepts"
+- \subpage optional_component "Optional Component"
+- \subpage flags "Bit Flags on mesh elements"
+- \subpage adjacency "Adjacency and Topology"
+- \subpage allocation "Creating and destroying elements"
+- \subpage attributes "Adding user defined attributes to mesh elements"
+- \subpage fileformat "Loading and saving meshes"
+- \subpage shot "Camera and shot abstraction for managing views"
+- \ref code_sample "Short Examples showing various features of the library"
+
+Notable Applications
+-------
+A number of applications have been developed using the vcglib:
+- <a href="http://www.meshlab.net">MeshLab</a>: the renowned open source mesh processing is based on this library.
+- \subpage metro "Metro, the tool for measuring differences between meshes"
+- The first high quality  <a href="http://dl.acm.org/citation.cfm?id=940008"> out-of-core mesh simplifier </a> that was used by the Stanford Digital Michelangelo project to process their huge 3D scanned models.
+
+Contacts
+-------
+
+For any info about licensing (portion of) the library please contact us:<br>
+<b> Paolo Cignoni (p.cignoni@isti.cnr.it) </b><br>
+<b> Fabio Ganovelli (f.ganovelli@isti.cnr.it) </b><br>
+<a href="http://vcg.isti.cnr.it">Visual Computing Lab</a> of the Italian National Research Council - ISTI
+
+In case of \b bugs please report them <a href="https://github.com/cnr-isti-vclab/vcglib/issues"> here</a>.
+
+*/
@@ -0,0 +1,30 @@
+/** \page install
+
+Installation and folder structure
+================
+
+VCG Lib uses a git repository hosted by github. 
+The main project page of the library is http://github.com/cnr-isti-vclab/vcglib/
+
+The stable version of the library are available under the release page 
+https://github.com/cnr-isti-vclab/vcglib/releases
+
+To get the development version of library clone the 'devel' branch of the library :
+
+     git clone -b devel https://github.com/cnr-isti-vclab/vcglib.git   
+
+
+Folder Structure
+================
+VCGLib is mostly made of header files (and its core part it's only header files) with no external dependencies.
+Just download the tarball from here and uncompress it in a folder, e.g. named vcg, inside you compiler "include" directory.
+Afterwards, you have to just include the files you need as shown in the apps/sample examples.
+
+Inside vcg folder you will find 5 sub-folders:
+
+- `vcg`: this is the core of the library, where all the algorithms and data structures are defined. This part is pure, quite heavily templated, C++ code with STL support for common data structures and algorithms. You will not find a single include from here to anything else than standard libraries. Note that core part is made of header files (.h files) only.
+- `wrap`: here you will find the wrapping of VCG concepts towards specific needs/contexts/libraries. For example you will find all the code to import/export meshes from the hard disk in many formats, or the routines for rendering triangle meshes with OpenGL, supports for common GUI tools like a trackball, and so on..
+- `apps`: this folder contains the command line applications developed with the VCG Lib. Many (much more) examples can be found in MeshLab. The apps/sample directory contains a sub-collection of very basic apps. A good starting point for beginners!
+- `docs`: documentation lives here (including this tutorial)
+- `eigenlib` a copy of the latest stable version of the eigen library for linear algebra ( http://http://eigen.tuxfamily.org/ ). VCGlib relies on eigen for all the advanced matrix  processing.
+*/
@@ -0,0 +1,29 @@
+/** \page metro
+Metro: Measuring error on simplified surfaces
+=============================================
+Metro is a tool designed to evaluate the difference between two triangular meshes. Metro adopts an approximated approach based on surface sampling and point-to-surface distance computation. The tool has been widely used in the surface simplification research community (more than 800 citations according to google scholar ).
+Three different surface sampling methods are implemented:
+- _Montecarlo sampling_ (pick k random samples in the interior of each face)
+- _Subdivision sampling_ (recursively subdivide each face along the longest edge and choose the sample in the center of each cell)
+- _Similar Triangles sampling_ (subdivide each face t in k polygons similar to t and sample the face in correspondence with the vertices of these polygons, internal to t)
+
+For efficiently finding the closest point over a mesh from a sample point three different spatial indexing structures sampling methods were implemented:
+- Static Uniform Grid
+- Hashed Uniform Grid
+- Axis Aligned Bounding Box Hierarchy
+
+In most cases, given the sampling pattern of Metro, that makes a very large number of spatially coherent queries very near to the indexed surface, Uniform Grids are faster than hierarchies. Hierarchical structures perform better when the query points are far from the indexed surface; in this case UG would require a larger traversal overhead (many cells would be traversed to find a non-empty cell).
+The tool support the following file formats: off, ply and stl.
+
+Papers
+------
+_P. Cignoni, C. Rocchini and R. Scopigno_<BR>
+__Metro: measuring error on simplified surfaces__<br>
+Computer Graphics Forum, Blackwell Publishers, vol. 17(2), June 1998, pp 167-174<br> 
+<a href="http://vcg.isti.cnr.it/publications/papers/metro.pdf">PDF</a>
+
+__Abstract__
+
+This paper presents a new tool, Metro, designed to compensate for a deficiency in many simplification methods proposed in literature. Metro allows to compare the difference between a pair of surfaces (e.g. a triangulated mesh and its simplified representation) by adopting a surface sampling approach. It has been designed as a highly general tool, and it does no assumption on the particular approach used to build the simplified representation. It returns both numerical results (meshes areas and volumes, maximum and mean error, etc.) and visual results, by coloring the input surface according to the approximation error.
+
+*/
@@ -0,0 +1 @@
+␍/**␍Main namespace.␍It contain all the other namespaces and  ␍*/␍namespace vcg {}␍␍/**␍Everything about triangular meshes lie in this namespace␍*/␍namespace vcg::tri {}␍␍/**␍Everything about tetrahedral meshes lie in this namespace␍*/␍namespace vcg::tetra {}␍␍/**␍Global algorithms and classes working on generic faces are defined in this namespace.␍Typical example are the topological surgery functions (like vcg::face::Detach and vcg::face::IsBorder) and the class vcg::face::Pos ␍for defining \e positions over a mesh. Note that for sake of brevity the main face class is defined outside this namespace.␍*/␍namespace vcg::face {}␍␍/**␍Wrapper for symbols and structs defind in the old ply library␍*/␍namespace vcg::ply {} ␍␍/**␍For all the functions and classes used to read and write meshes␍*/␍namespace vcg::tri::io {}␍␍/**␍For all the functions and classes used to read and write Tetrahedral Meshes␍*/␍namespace vcg::tetra::io {}␍␍/**␍For all the generic math functions and classes.␍*/␍namespace vcg::math {}␍
@@ -0,0 +1,49 @@
+/** \page optional_component
+Optional Component
+===
+There are many cases where some vertex or face attributes (like for example the Face-Face adjacency) are not necessary all the time.
+VCG Lib gives you a way to specify optional components, i.e. attributes that are not statically stored within the simplex but can be
+dynamically allocated only when you need them. Their use is totally transparent with respect to the standard, statically allocated components.
+
+To 'define' optional component you need to do two things:
+- to use a special type of container (derived from std::vector) in the mesh definition
+- to specify the right type of component in the simplex definition
+
+An optional component can be used only when it is 'enabled', e.g. when the memory for it has been allocated.
+An optional component can be enable by calling the function Enable.
+VCG Lib handles optional components with two alternative mechanisms: the first is called 'Ocf' (for Optional Component Fast)
+which uses one pointer for each simplex but it makes accessing optional attribute almost as fast as non-optional ones;
+the second is called 'Occ' (for Optional Component Compact) which only requires a little extra space for each mesh
+(unrelated to its size in terms of number of simplicies) but which can result in a slower access.
+In the following, only their use is discussed. The implementation detail can be found here.
+
+Optional Component Fast
+---
+The following definition of MyMesh specifies that a few components of the vertex and face types are optional.
+Note that  the special attribute vcg::vertex::InfoOcf and vcg::face::InfoOcf are the first attribute of vertex and face types and that we
+use the vcg::vertex::vector_ocf and vcg::face::vector_ocf as containers;
+
+\dontinclude trimesh_optional.cpp
+\skip MyVertexOcf
+\until MyMeshOcf
+
+
+Before accessing the data contained in the optional component you must enable that attribute by calling EnableXXX() corresponding function;
+afterwards the space for the component will be allocated and accessible until you call again DisableXXXX().
+
+\dontinclude trimesh_optional.cpp
+\skip cmof
+\until cmof
+\skip HasFFAdjacency
+\until true
+
+Trying to access the value of a unallocated component before enabling or after disabling the corresponding component
+will throw an assertion.
+
+\dontinclude trimesh_optional.cpp
+\skip EnableNormal
+\until UpdateNormal
+
+
+\sa trimesh_optional.cpp
+*/
@@ -0,0 +1,78 @@
+/**
+\page shot
+
+Viewing and manipulation
+------------------------
+In this section, all that concerns the definition of a view and the manipulation of a mesh will be explained.
+
+Shot and camera
+--------------
+This section presents the structure of the shot and camera of the library.
+After an overview of the camera model used, all the components of the shot class are listed and described.
+Then, a set of examples of the most important operations (projection and un-projection) and of the interactions between shots and between a shot and the trackball are presented. Finally, simple examples of a shot are visually shown, in order to help with the implementations of eventual wrapped to and from other shot-camera formats.
+
+<b>The camera model</b>
+
+In generale, the camera parameters can be divided in two groups:
+- \b Extrinsic (or external) parameters: these are the parameters associated to the position in the space of the camera.
+
+- \b Intrinsic (or internal) parameters: these values are related to the peculiar characteristics of the camera, like the focal length (the zoom) or the distortion introduced by the lenses.
+
+If these group of values are put in a proper camera model, it is possible to transform any point in the space in the corresponding point on the image plane of the camera (and viceversa).
+
+\image html "shot-Camera_model.png" An example scheme of a perspective camera model
+
+
+In fact, given a simple perspective camera model like the one shown in figure, extrinsic parameters can be used to transform a point from its world coordinates {xw,yw,zw} to the camera 3D coordinate system {x,y,z}):
+\image html "shot-Projection.png"
+In this case the extrinsic parameters are a 3 X 3 rotation matrix R and a translation vector T, which define the orientation and position of the camera. In order to transform the 3D camera coordinate in 2D image plane coordinates (Xu,Yu) it's necessary to know the measure of the distance between the point of view and the image plane (OO1 in figure): this value, indicated with f, is usually known as the focal length. The relation between the camera and image coordinates of the point can be expressed as follows:
+\image html "shot-Focal.jpg"
+
+Another aspect of the structure of a camera that can be characterized is the distortion introduced by the lenses: if we suppose that the distortion is radial (performed along the radial direction respect to the center of distortion) we can calculate the undistorted image coordinates
+
+\image html "shot-Distort1.jpg"
+where
+\image html "shot-Distort2.jpg"
+and
+\image html "shot-Distort3.jpg"
+
+In conclusion, a quite accurate model of a camera can be described by:
+- A 3x3 rotation matrix and a translation vector for extrinsic parameters
+- The values of focal, center of distortion and one or more distortion coefficients for intrinsic parameters
+
+While this set of parameters provides everything to transform any 3D point in its corresponding point in the image plane, this could be not enough in peculiar applications. If an accurate estimation of the real position of the camera respect to the object is needed, some more data about the camera model are needed: in particular, the sensor physical size together with the resolution in pixel of the acquired image. If these a-priori data are known, a unique set of camera parameters is associated to any shot.
+
+<b>The VCG Shot</b>
+
+The implementation of a Shot in the VCG library can be found in vcg\math\shot.h
+
+The shot is composed by two elements:
+
+- the \b Extrinsics parameters, which are stored in the class Shot (in the type ReferenceFrame) that contains viewpoint and view direction.
+The Extrinsics parameters are kept as a rotation matrix "rot" and a translation vector "tra"
+NOTE: the translation matrix "tra" corresponds to -viewpoint while the rotation matrix "rot"
+corresponds to the axis of the reference frame by row, i.e.<br>
+rot[0][0 1 2] == X axis<br>
+rot[1][0 1 2] == Y axis<br>
+rot[2][0 1 2] == Z axis<br>
+It follows that the matrix made with the upper left 3x3 equal to rot and the 4th column equal to tra and (0,0,0,1) in the bottom row transform a point from world coordinates to the reference frame of the shot.
+- the \b Instrinsics parameters, which are stored as a Camera type (check vcg/math/camera) and that
+determines how a point in the frame of the camera is projected in the 2D projection plane. This information was kept indendent of the extrinsic parameters because more than one shot can share the same intrinsic parameters set.
+
+The attributes of a Camera, which is define in vcg\math\shot.h, are:
+\code
+//------ camera intrinsics
+ScalarType	FocalMm;		/// Focal Distance: the distance between focal center and image plane. Expressed in mm
+Point2<int>	ViewportPx;		/// Dimension of the Image Plane (in pixels)
+Point2< S>	PixelSizeMm;		/// Dimension in mm of a single pixel
+Point2< S>	CenterPx;		/// Position of the projection of the focal center on the image plane. Expressed in pixels
+Point2< S>	DistorCenterPx;		/// Position of the radial distortion center on the image plane in pixels
+S			k[4];		/// 1st & 2nd order radial lens distortion coefficient (only the first 2 terms are used)
+//------------------------
+\endcode
+While the extrinsic parameters usually change between the shots, some (sometimes all) of the intrinsics are strongly related to the camera model used. In particular, some values are usually known before camera calibration: viewportPx and CenterPx. Moreover, if an accurate calibration is needed, it is necessary to fill the PixelSizeMm value.
+
+This can be inferred from the camera datasheet (it can be calculated by dividing the sensor width and height, in mm, by the resolution of the image) or, in some cases, from the EXIF of the image (in the CANON models, it is the inverse of FocalPlane X-resolution and FocalPlane Y-resolution, scaled from inches to mm if necessary). If a correct PixelSizeMm is not set, the values of the camera parameters can be different from the real ones, even though the image is perfectly aligned to a 3D model.
+
+Also the focal distance can be inferred from EXIF, but its value is indicative. If a calibrated camera is used, then all the intrinsic parameters should be known in advance.
+*/
@@ -0,0 +1,111 @@
+/**
+\page "VCG Library Coding Guide"
+VCG Library Coding Guide
+=========================
+
+Naming Rules
+------------
+
+<B><I>Class names </I></B> with first letter Uppercase and internal
+uppercase to separate compound words.\n
+
+<B><I>Function members</I></B> of classes follow the same rule.
+
+Example:
+
+\code
+   Point3f
+   {
+   public:
+   ScalarType &amp;V(const int i);
+   }
+\endcode
+
+<B><I>Public Variable members</I></B> has the first letter
+lowercase and internal uppercase to separate compound words.
+
+Example:
+
+<pre></pre>
+
+<B><I>Private Variable members</I></B> has an underscore as first char and
+the first letter lowercase and internal uppercase to separate compound
+words.
+
+Example:
+
+<pre>
+   Point3f
+   {
+   private:
+   ScalarType _v[3];
+   }
+</pre>
+
+<B><I>Class Template Arguments</I></B> all capitalized and with names
+remembering where they have been defined.<br>
+Class TypeDefs used for templated Class arguments or for shortness are just like Class Names,
+but ending with &ldquo;Type&rdquo;, &ldquo;Iterator&rdquo;,  &ldquo;Pointer&rdquo;, or &ldquo;Container&rdquo;.
+
+Example:
+<pre>
+   typedef typename VertexType::CoordType CoordType;
+   typedef typename VertContainer::iterator VertexIterator;
+
+</pre>
+
+<H2 >Header Files</H2>
+Header filenames and folders always fully lower case. Compound names
+are separated by '_'.
+
+Example:
+
+    #include<vcg/space/point3.h>;
+
+Each include file must begin with the standard legal
+disclamier/license intestation and report in the first line of history
+the $LOG$ cvs string.
+
+The following automatically generated history can be, from time to
+time, compressed and shortened to save space.
+
+Each file of the library has to include all the files that it
+requires. A include file should rely on the files included by its own
+include files. Example: in vcg/space/box3.h:
+
+
+     #include<vcg/math/base.h>; // not necessary because included by point3.h
+     #include<vcg/space/point3.h>;
+
+
+In Class definitions place all the prototypes all together before
+the inline or templated implementations.
+
+<H2 >Editing Rules</H2>
+
+Tabs are equivalent to two spaces.
+
+There are no strict rules for the placement of '{' or indenting.
+
+<H2 >Constructors and casting</H2>
+
+All basic classes (point3, box3 ecc) must have null
+constructors. Non null constructors can be added in debug
+versions.
+
+Implicit casting is disallowed. Write a member Import function for
+casting from different integral types and a static.<br>
+Construct to build an object from different a integral type.
+
+Example:
+
+<pre>
+   Point3f pf(1.0f,0.0f,0.0f);
+   Point3d pd=Point3f::Construct(pf);
+   pf.Import(pd);
+</pre>
+
+<H2 >Comment and documenting</H2>
+All the classes, algorithms and functions <B>MUST</B> be documented using Doxygen. Please add a short intro before each class explaining design choices and for non trivial classes give some short usage example. For complex classes try to group  similar members under categories. Non trivial algorithms should refer the paper/book where they are explained.
+ Namespaces and files should be also documented trying to explain how the file/namespace partitioning works.
+*/
@@ -0,0 +1,17 @@
+<!-- HTML footer for doxygen 1.9.6-->
+<!-- start footer part -->
+<!--BEGIN GENERATE_TREEVIEW-->
+<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
+  <ul>
+    $navpath
+    <li class="footer">$generatedby <a href="https://www.doxygen.org/index.html">doxygen</a> $doxygenversion on $datetime</li>
+  </ul>
+</div>
+<!--END GENERATE_TREEVIEW-->
+<!--BEGIN !GENERATE_TREEVIEW-->
+<hr class="footer"/><address class="footer"><small>
+$generatedby&#160;<a href="https://www.doxygen.org/index.html">doxygen</a> $doxygenversion on $datetime
+</small></address>
+<!--END !GENERATE_TREEVIEW-->
+</body>
+</html>
@@ -0,0 +1,74 @@
+<!-- HTML header for doxygen 1.9.6-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
+<head>
+<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+<meta http-equiv="X-UA-Compatible" content="IE=11"/>
+<meta name="generator" content="Doxygen $doxygenversion"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
+<!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+<link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<script type="text/javascript">var page_layout=1;</script>
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+<script type="text/javascript" src="$relpath^jquery.js"></script>
+<script type="text/javascript" src="$relpath^dynsections.js"></script>
+$treeview
+$search
+$mathjax
+$darkmode
+<link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
+$extrastylesheet
+</head>
+<body>
+<!--BEGIN DISABLE_INDEX-->
+  <!--BEGIN FULL_SIDEBAR-->
+<div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
+  <!--END FULL_SIDEBAR-->
+<!--END DISABLE_INDEX-->
+
+<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+
+<!--BEGIN TITLEAREA-->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">
+ <tbody>
+ <tr id="projectrow">
+  <!--BEGIN PROJECT_LOGO-->
+  <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"/></td>
+  <!--END PROJECT_LOGO-->
+  <!--BEGIN PROJECT_NAME-->
+  <td id="projectalign">
+   <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
+   </div>
+   <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
+  </td>
+  <!--END PROJECT_NAME-->
+  <!--BEGIN !PROJECT_NAME-->
+   <!--BEGIN PROJECT_BRIEF-->
+    <td>
+    <div id="projectbrief">$projectbrief</div>
+    </td>
+   <!--END PROJECT_BRIEF-->
+  <!--END !PROJECT_NAME-->
+  <!--BEGIN DISABLE_INDEX-->
+   <!--BEGIN SEARCHENGINE-->
+     <!--BEGIN !FULL_SIDEBAR-->
+    <td>$searchbox</td>
+     <!--END !FULL_SIDEBAR-->
+   <!--END SEARCHENGINE-->
+  <!--END DISABLE_INDEX-->
+ </tr>
+  <!--BEGIN SEARCHENGINE-->
+   <!--BEGIN FULL_SIDEBAR-->
+   <tr><td colspan="2">$searchbox</td></tr>
+   <!--END FULL_SIDEBAR-->
+  <!--END SEARCHENGINE-->
+ </tbody>
+</table>
+</div>
+<!--END TITLEAREA-->
+<!-- end header part -->
@@ -0,0 +1,130 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 
+<HTML> <HEAD>   
+<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252">
+<TITLE></TITLE>     
+    
+<STYLE>     <!--        
+        @page { size: 21.59cm 27.94cm; margin: 2cm }    
+        body { background-color: #FFFFFF }
+        body { margin-left:8%; margin-right:8%; }
+        pre { font-family: monospace; }
+        P { text-indent: 0em; margin-bottom: 0.21cm }       
+        H1.old { margin-bottom: 0.21cm }        
+        H1.old { font-family: "Arial", sans-serif; font-size: 16pt }
+
+    H2.old { margin-bottom: 0.21cm }        
+    H2.old { font-family: "Arial", sans-serif; font-size: 14pt; font-style: italic } 
+    P.old { text-indent: 1.01cm; margin-bottom: 0cm; }      
+-->     </STYLE> 
+</HEAD> 
+<BODY LANG="en-US" DIR="LTR"> 
+<H1 >VCG Library Coding Guide</H1>
+<H2 >Naming Rules</H2> 
+<P><B><I>Class names</I></B> with first letter Uppercase and internal
+uppercase to separate compound words.</P>  
+
+<P><B><I>Function members</I></B> of classes follow the same rule.</P> 
+
+<P>Example:</P> 
+
+<pre>
+   Point3f
+   {
+   public: 
+   ScalarType &amp;V(const int i);
+   }
+</pre>
+
+<P><B><I>Public Variable members</I></B> has the first letter
+lowercase and internal uppercase to separate compound words.</P> 
+
+<P>Example:</P> 
+
+<pre></pre>
+
+<P><B><I>Private Variable members</I></B> has an underscore as first char and
+the first letter lowercase and internal uppercase to separate compound
+words.</P> 
+
+<P>Example:</P> 
+
+<pre>
+   Point3f
+   {
+   private:
+   ScalarType _v[3];
+   }
+</pre>
+
+<P><B><I>Class Template Arguments</I></B> all capitalized and with names
+remembering where they have been defined.<br>
+Class TypeDefs used for templated Class arguments or for shortness are just like Class Names,
+but ending with &ldquo;Type&rdquo;, &ldquo;Iterator&rdquo;,  &ldquo;Pointer&rdquo;, or &ldquo;Container&rdquo;.</P> 
+
+<P>Example:</P>
+<pre>
+   typedef typename VertexType::CoordType CoordType;
+   typedef typename VertContainer::iterator VertexIterator;
+ 
+</pre>
+
+<H2 >Header Files</H2> 
+<P>Header filenames and folders always fully lower case. Compound names
+are separated by '_'.</P> 
+
+<P>Example:</P> 
+
+<pre>
+   #include&lt;vcg/space/point3.h&gt;
+</pre>
+
+<P>Each include file must begin with the standard legal
+disclamier/license intestation and report in the first line of history
+the $LOG$ cvs string.</P> 
+
+<P>The following automatically generated history can be, from time to
+time, compressed and shortened to save space.</P> 
+
+<P>Each file of the library has to include all the files that it
+requires. A include file should rely on the files included by its own
+include files. Example: in vcg/space/box3.h:</P>
+
+<pre>
+   #include&lt;vcg/math/base.h&gt; // not necessary because included by point3.h
+
+   #include&lt;vcg/space/point3.h&gt;  
+</pre>
+
+<P>In Class definitions place all the prototypes all together before
+the inline or templated implementations.</P> 
+
+<H2 >Editing Rules</H2> 
+
+<P>Tabs are equivalent to two spaces.</P> 
+
+<P>There are no strict rules for the placement of '{' or indenting.</P> 
+
+<H2 >Constructors and casting</H2> 
+
+<P>All basic classes (point3, box3 ecc) must have null
+constructors. Non null constructors can be added in debug
+versions.</P> 
+
+<P>Implicit casting is disallowed. Write a member Import function for
+casting from different integral types and a static.<br>
+Construct to build an object from different a integral type.</P>
+
+<P>Example:</P> 
+
+<pre>
+   Point3f pf(1.0f,0.0f,0.0f);
+   Point3d pd=Point3f::Construct(pf);
+   pf.Import(pd);
+</pre>
+
+<H2 >Comment and documenting</H2> 
+<P>All the classes, algorithms and functions <B>MUST</B> be documented using Doxygen. Please add a short intro before each class explaining design choices and for non trivial classes give some short usage example. For complex classes try to group  similar members under categories. Non trivial algorithms should refer the paper/book where they are explained.</p> 
+<P> Namespaces and files should be also documented trying to explain how the file/namespace partitioning works.
+</P>
+</BODY>
+</HTML>
				`@@ -0,0 +1 @@`
				␍/*␍Main namespace.␍It contain all the other namespaces and ␍/␍namespace vcg {}␍␍/*␍Everything about triangular meshes lie in this namespace␍/␍namespace vcg::tri {}␍␍/*␍Everything about tetrahedral meshes lie in this namespace␍/␍namespace vcg::tetra {}␍␍/*␍Global algorithms and classes working on generic faces are defined in this namespace.␍Typical example are the topological surgery functions (like vcg::face::Detach and vcg::face::IsBorder) and the class vcg::face::Pos ␍for defining \e positions over a mesh. Note that for sake of brevity the main face class is defined outside this namespace.␍/␍namespace vcg::face {}␍␍/*␍Wrapper for symbols and structs defind in the old ply library␍/␍namespace vcg::ply {} ␍␍/*␍For all the functions and classes used to read and write meshes␍/␍namespace vcg::tri::io {}␍␍/*␍For all the functions and classes used to read and write Tetrahedral Meshes␍/␍namespace vcg::tetra::io {}␍␍/*␍For all the generic math functions and classes.␍/␍namespace vcg::math {}␍