manolas
/
vcglib
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Still improving documentation

This commit is contained in:
Paolo Cignoni 2012-10-25 07:20:06 +00:00
parent 5adb83c8c9
commit b50b1e88c3
4 changed files with 78 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
apps/sample/trimesh_base/trimesh_base.cpp
View File

@ -30,20 +30,11 @@ This file contain a minimal example of the library, showing how to load a mesh a
*/ */
#include<vcg/complex/complex.h> #include<vcg/complex/complex.h>
// input output
#include<wrap/io_trimesh/import_off.h> #include<wrap/io_trimesh/import_off.h>
// topology computation
#include<vcg/complex/algorithms/update/topology.h> #include<vcg/complex/algorithms/update/topology.h>
// normals
#include<vcg/complex/algorithms/update/normal.h> #include<vcg/complex/algorithms/update/normal.h>
class MyVertex; class MyEdge; class MyFace;
class MyEdge;
class MyFace;
class MyVertex;
struct MyUsedTypes : public vcg::UsedTypes<vcg::Use<MyVertex> ::AsVertexType, struct MyUsedTypes : public vcg::UsedTypes<vcg::Use<MyVertex> ::AsVertexType,
vcg::Use<MyEdge> ::AsEdgeType, vcg::Use<MyEdge> ::AsEdgeType,
vcg::Use<MyFace> ::AsFaceType>{}; vcg::Use<MyFace> ::AsFaceType>{};
@ -51,8 +42,15 @@ struct MyUsedTypes : public vcg::UsedTypes< vcg::Use<MyVertex> ::AsVertexType,
class MyVertex : public vcg::Vertex< MyUsedTypes, vcg::vertex::Coord3f, vcg::vertex::Normal3f, vcg::vertex::BitFlags >{}; class MyVertex : public vcg::Vertex< MyUsedTypes, vcg::vertex::Coord3f, vcg::vertex::Normal3f, vcg::vertex::BitFlags >{};
class MyFace : public vcg::Face< MyUsedTypes, vcg::face::FFAdj, vcg::face::VertexRef, vcg::face::BitFlags > {}; class MyFace : public vcg::Face< MyUsedTypes, vcg::face::FFAdj, vcg::face::VertexRef, vcg::face::BitFlags > {};
class MyEdge : public vcg::Edge< MyUsedTypes> {}; class MyEdge : public vcg::Edge< MyUsedTypes> {};
class MyMesh : public vcg::tri::TriMesh< std::vector<MyVertex>, std::vector<MyFace> , std::vector<MyEdge> > {}; class MyMesh : public vcg::tri::TriMesh< std::vector<MyVertex>, std::vector<MyFace> , std::vector<MyEdge> > {};
class MyVertex0 : public vcg::Vertex< MyUsedTypes, vcg::vertex::Coord3f, vcg::vertex::BitFlags >{};
class MyVertex1 : public vcg::Vertex< MyUsedTypes, vcg::vertex::Coord3f, vcg::vertex::Normal3f, vcg::vertex::BitFlags >{};
class MyVertex2 : public vcg::Vertex< MyUsedTypes, vcg::vertex::Coord3f, vcg::vertex::Color4b, vcg::vertex::CurvatureDirf,
vcg::vertex::Qualityf, vcg::vertex::Normal3f, vcg::vertex::BitFlags >{};
int main( int argc, char **argv ) int main( int argc, char **argv )
{ {
if(argc<2) if(argc<2)
@ -60,7 +58,7 @@ int main( int argc, char **argv )
printf("Usage trimesh_base <meshfilename.obj>\n"); printf("Usage trimesh_base <meshfilename.obj>\n");
return -1; return -1;
} }
/*! we simply /*!
*/ */
MyMesh m; MyMesh m;

14
docs/Doxygen/allocation.dxy
View File

@ -74,4 +74,18 @@ m.vert.size() == m.vn
m.face.size() == m.fn m.face.size() == m.fn
\endcode \endcode
Note that if there are no deleted elements in your mesh, the compactor functions returns immediately. Note that if there are no deleted elements in your mesh, the compactor functions returns immediately.
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:
\code
#include<vcg/complex/trimesh/append.h>
MyMesh ml,mr;
...
tri::Append<MyMesh>::Mesh(ml,mr);
\endcode
This is equivalent to append the content of mr onto ml. If you want simple copy just clear ml before calling the above function.
*/ */

14
docs/Doxygen/doxyfile
View File

@ -665,16 +665,20 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories # directories like "/usr/src/myproject". Separate the files or directories
# with spaces. # with spaces.
INPUT = . \ INPUT = \
../../vcg/complex/allocate.h \
../../vcg/complex/algorithms/update \ ../../vcg/complex/algorithms/update \
../../vcg/complex/algorithms/inertia.h \
../../vcg/complex/algorithms/point_sampling.h \
../../vcg/complex/algorithms/clean.h \
../../vcg/complex/algorithms/refine.h \
../../apps/sample/trimesh_base \ ../../apps/sample/trimesh_base \
../../apps/sample/trimesh_attribute \ ../../apps/sample/trimesh_attribute \
../../apps/sample/trimesh_smooth \ ../../apps/sample/trimesh_smooth \
../../apps/sample/trimesh_refine \ ../../apps/sample/trimesh_refine \
../../vcg/complex/allocate.h \ ../../apps/sample/trimesh_inertia \
../../vcg/complex/algorithms/inertia.h \ ../../apps/sample/point_sampling \
../../vcg/complex/algorithms/clean.h \ .
../../apps/sample/trimesh_inertia
# This tag can be used to specify the character encoding of the source files # This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is

108
docs/Doxygen/main_concept.dxy
View File

@ -3,96 +3,60 @@ How to define a mesh type
===== =====
The VCG Lib may encode a mesh in several ways, the most common of which is a set of vertices and set 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: The VCG Lib may encode a mesh in several ways, the most common of which is a set of vertices and set 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:
\code
class MyMesh : public vcg::tri::TriMesh< std::vector<MyVertex>, std::vector<MyFace> > {} \dontinclude trimesh_base.cpp
\endcode \skip MyMesh
where vcg::TriMesh is the base type for a triangle mesh and it is templated on: \until MyMesh
- the type of STL random access container containing the vertices
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 - which in turn is templated on your vertex type
- the type of STL random access container containing the faces - the type of STL random access container containing the faces
- which in turn is templated on your face type - which in turn is templated on your face type
Another valid example is:
\code
class MyMesh : public vcg::tri::TriMesh< std::vector<MyFace> ,std::vector<MyVertex>,std::vector<MyEdge> > {}
\endcode
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. 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.
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 attribute. 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 : \dontinclude trimesh_base.cpp
\code \skip complex.h
#include <vcg/simplex/vertex/base.h> \until complex.h
#include <vcg/simplex/vertex/component.h> \skip class
\until MyMesh
class MyVertex; 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 attribute. 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 :
class MyFace;
class MyEdge;
class MyUsedTypes: public vcg::UsedTypes< vcg::Use<MyVertex>::AsVertexType, \dontinclude trimesh_base.cpp
vcg::Use<MyEdge>::AsEdgeType, \skip MyVertex0
vcg::Use<MyFace>::AsFaceType> {}; \until Qualityf
class MyVertex0 : public vcg::Vertex<MyUsedTypes, vcg::vertex::Coord3d, vcg::vertex::Normal3f> {}; \c vcg::Vertex is the VCG base class for a vertex.
class MyVertex1 : public vcg::Vertex<MyUsedTypes, vcg::vertex::Coord3d, vcg::vertex::Normal3f,vcg::vertex::Color4b> {}; \c vcg::UsedTypes declares which are the types invoved 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
class MyVertex2 : public vcg::Vertex<MyUsedTypes > {}; 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:
\endcode - MyVertex0 is a type storing coordinates as a triple of doubles and normal as a triple of floats,
vcg::Vertex is the VCG base class for a vertex. - MyVertex1 also store a color value specified as 4 bytes
vcg::UsedTypes declares which are the types invoved 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 - MyVertex2 store a long list of different components.
\code
vcg::Use<[name of your type] >::As[Vertex | Edge | Face | HEdge | Wedge]Type>
\endcode
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 MyVertex differ for the remaining template parameters. 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 and MyVertex2 does not store any value, it is just an empty class. vcg::Coord3d, vcg::Normal3f, vcg::Color4b and many others are implemented in VCG, their complete list can be found *here*. You can place any combination of them as a template parameters of your vertex (your entity) type (order is unimportant).
Now we have all it takes for a working definition of MyMesh type:
\code Many other compenents are implemented in VCG, their complete list can be found *here*. You can place any combination of them as a template parameters of your vertex (your entity) type (order is unimportant). Now we have all it takes for a working definition of MyMesh type:
#include <vector>
#include <vcg/simplex/vertex/base.h> \dontinclude trimesh_base.cpp
#include <vcg/simplex/vertex/component.h> \skip complex.h
#include <vcg/simplex/face/base.h> \until complex.h
#include <vcg/simplex/face/component.h> \skip class
\until MyMesh
#include <vcg/complex/trimesh/base.h> \skip main
\until }
class MyVertex; \until }
class MyFace; \until }
class MyUsedTypes: public vcg::UsedTypes< vcg::Use<MyVertex>::AsVertexType>,
vcg::Use<MyFace>::AsFaceType>
class MyVertex : public vcg::Vertex<MyUsedTypes, vcg::vertex::Coord3d, vcg::vertex::Normal3f> {}; 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
class MyFace : public vcg::Face<MyUsedTypes, vcg::face::VertexRef> {};
class MyMesh : public vcg::tri::TriMesh< std::vector<MyVertex>, std::vector<MyFace> > {};
int main()
{
MyMesh m;
return 0;
}
\endcode
One more comment: vcg::VertexRef is an attribute that stores 3 pointers to the type of vertex, so implementing the Idexed Data structure. This is an example of why the type MyFace needs to know the type MyVertex
How to create a mesh 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. 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 element to a container. We describe this issue and the correct way of adding mesh element in the Allocation page. 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 element to a container. We describe this issue and the correct way of adding mesh element in the \ref allocation page.
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:
\code
#include<vcg/complex/trimesh/append.h>
MyMesh ml,mr;
...
tri::Append<MyMesh>::Mesh(ml,mr);
\endcode
This is equivalent to append the content of mr onto ml. If you want simple copy just clear ml before calling the above function.
The flags of the mesh elements 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 thsi vector (more details on the various deletion/allocation issues in the Allocation page. More details on the various kind of flags that can be associated are in the Flags page. 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 thsi 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 How to process a mesh
------------- -------------