updated documentation (converted shot and camera...)

docs/Doxygen/attributes.dxy

@@ -10,69 +10,22 @@ Conceptually the difference is that with the term component VCGLib indicates tho
 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 v.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 an example:
-\code
-/* apps/sample/trimesh_attribute/trimesh_attribute.cpp */
 
-#include<vcg/simplex/vertex/base.h>
+\dontinclude trimesh_attribute.cpp
-#include<vcg/simplex/vertex/component.h>
+\skip include
-#include<vcg/simplex/face/base.h>
+\until main
-#include<vcg/simplex/face/component.h>
+\until }
-#include<vcg/complex/trimesh/base.h>
-#include<vcg/complex/trimesh/allocate.h>
 
-class MyFace;
+You also have functions to check if a given attribute exists, retrieve an handle for it and eventually deleting it (using the handle or by name).
-class MyVertex;
+Do not get mix up the scope of the handle with the memory allocation of the attribute. If you do not delete an attribute explicitly, it will be allocated until the mesh itself is destroyed, even if you do not have handles to it.
-class MyEdge;   // dummy prototype never used
-class MyVertex  : public vcg::VertexSimp2< MyVertex, MyEdge, MyFace, vcg::vertex::Coord3f,vcg::vertex::Normal3f>{};
-class MyFace    : public vcg::FaceSimp2< MyVertex, MyEdge, MyFace, vcg::face::VertexRef, vcg::face::Normal3f> {};
 
-class MyMesh : public vcg::tri::TriMesh< std::vector<MyVertex>, std::vector<MyFace> > {};   
+\until }
 
-float Irradiance(MyMesh::VertexType v){ 
+The same can be done for the faces, just replace the occurences of PerVertex with PerFace.
-	// .....
+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.
-	return 1.0;
-}
-
-int main()
-{
-  MyMesh m;
-  //...here m is filled
-  
-  // add a per-vertex attribute with type float named "Irradiance"
-  MyMesh::PerVertexAttributeHandle<float> ih = vcg::tri::Allocator<MyMesh>::AddPerVertexAttribute<float>  (m,std::string("Irradiance"));
-
-  // add a per-vertex attribute with type float named "Radiosity"   
-  vcg::tri::Allocator<MyMesh>::AddPerVertexAttribute<float> (m,std::string("Radiosity"));
- 
-  // add a per-vertex attribute with type bool and no name specified
-  MyMesh::PerVertexAttributeHandle<bool> blocked_h = vcg::tri::Allocator<MyMesh>::AddPerVertexAttribute<bool> (m); 
-  
-  MyMesh::VertexIterator vi; int i = 0;
-  for(vi   = m.vert.begin(); vi != m.vert.end(); ++vi,++i){
-   ih[vi]  = Irradiance(*vi);  // [] operator takes a iterator
-   ih[*vi] = Irradiance(*vi);  // or a MyMesh::VertexType object
-   ih[&*vi]= Irradiance(*vi);  // or a pointer to it
-   ih[i]   = Irradiance(*vi);  // or an integer index
-  }
-    
-  // Once created with AddPerVertexAttribute, an handle to the attribute can be obtained as follows
-  MyMesh::PerVertexAttributeHandle<float> rh = vcg::tri::Allocator<MyMesh>::GetPerVertexAttribute<float>(m,"Radiosity");  
-
-  // you can query if an attribute is present or not
-  bool hasRadiosity = vcg::tri::HasPerVertexAttribute(m,"Radiosity");  
-
-  // you can delete an attibute by name
-  vcg::tri::Allocator<MyMesh>::DeletePerVertexAttribute<float>(m,"Radiosity");
-
-  // you can delete an attibute by handle
-  vcg::tri::Allocator<MyMesh>::DeletePerVertexAttribute<bool>(m,blocked_h);
-}
-\endcode
-The same can be done for the faces, just replace the occurences of PerVertex with PerFace. 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.
 
 Note:
 
-Do not get mix up the scope of the handle with the memory allocation of the attribute. If you do not delete an attribute explicitly, it will be allocated until the mesh itself is destroyed, even if you do not have handles to it.
 
 C++ type of a mesh and reflection
 ---------------------------------

docs/Doxygen/doxyfile

@@ -32,7 +32,7 @@ PROJECT_NAME           = "VCG Library"
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 0.1
+PROJECT_NUMBER         = 
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description 
 # for a project that appears at the top of each page and should give viewer 
@@ -45,7 +45,7 @@ PROJECT_BRIEF          =
 # exceed 55 pixels and the maximum width should not exceed 200 pixels. 
 # Doxygen will copy the logo to the output directory.
 
-PROJECT_LOGO           = 
+PROJECT_LOGO           = /Users/cignoni/Documents/devel/vcglib/docs/Doxygen/img/vcglogo.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 
@@ -386,7 +386,7 @@ EXTRACT_STATIC         = NO
 # defined locally in source files will be included in the documentation. 
 # If set to NO only classes defined in header files are included.
 
-EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_CLASSES  = NO
 
 # This flag is only useful for Objective-C code. When set to YES local 
 # methods, which are defined in the implementation section but not in 
@@ -666,7 +666,9 @@ WARN_LOGFILE           =
 # with spaces.
 
 INPUT                  = . \
-                         ../../vcg/complex/algorithms/update
+                         ../../vcg/complex/algorithms/update \
+                         ../../apps/sample/trimesh_base \
+                         ../../apps/sample/trimesh_attribute
 
 # 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 
@@ -731,7 +733,7 @@ EXCLUDE_SYMBOLS        =
 # directories that contain example code fragments that are included (see 
 # the \include command).
 
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           = ../../apps/sample/trimesh_base
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the 
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
@@ -795,7 +797,7 @@ FILTER_SOURCE_PATTERNS =
 # Note: To get rid of all source code in the generated output, make sure also 
 # VERBATIM_HEADERS is set to NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body 
 # of functions and classes directly in the documentation.
@@ -849,7 +851,7 @@ VERBATIM_HEADERS       = NO
 # of all compounds will be generated. Enable this if the project 
 # contains a lot of classes, structs, unions or interfaces.
 
-ALPHABETICAL_INDEX     = NO
+ALPHABETICAL_INDEX     = YES
 
 # If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then 
 # the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns 

docs/Doxygen/examples.dxy

@@ -1,2 +1,13 @@
-/** \page Examples
+/**
-\*
+\page examples
+
+There are a number of very simple and short examples meant to document the various features of the library.
+
+trimesh_base.cpp
+
+trimesh_attribute.cpp
+
+trimesh_normal.cpp
+
+
+*/

docs/Doxygen/groups.dxy

@@ -1,18 +1,49 @@
 
 
 /** \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...
*/
+This module contains all the basic types for representing spatial entities like points (vcg::Point3) box3, line planes etc.
-
/** \defgroup math Math
This module contains the documentation for the types and the functions used for representing and managing mathematical entities.
+This module contains the documentation for the types and the functions used for...
 */
-
/** \defgroup simplex Simplexes
The moudule containing the various simplicial complexes
+
-*/
//@{
+/** \defgroup math Math
-/** \defgroup vertex Vertexes
Vertex of edge, triangular and tetrahedral meshes
This module contains the documentation for the types and the functions used for representing and managing vertexes of meshes.
+This module contains the documentation for the types and the functions used for representing and managing mathematical entities.
 */
-/** \defgroup face Faces 
Face of a triangular or a tetrahedral mesh
+
-*/

/** \defgroup tetra Tetrahedra 
Tetrahedral element of a tetrahedral complex.
+/** \defgroup simplex Simplexes
-*/

//@}

/** \defgroup complex Complexes 
The moudule containing the various simplicial complexes
+The module containing the various simplicial complexes
-*/

//@{

/** \defgroup edgemesh Edge Meshes (i.e. PolyLines)
This module contains the documentation for the types and the functions used for representing and managing generic polylines, or in other words \b edge\b meshes.
 */
-
/** \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 tetramesh Tetrahedral Meshes
This module contains the documentation for the types and the functions used for representing and managing generic tetrahedral of meshes.
+/** \defgroup vertex Vertexes
-*/

//@}
+Vertex of edge, triangular and tetrahedral meshes
+This module contains the documentation for the types and the functions used for representing and managing vertexes of meshes.
+*/
+/** \defgroup face Faces 
+Face of a triangular or a tetrahedral mesh
+*/
+
+//@}
+
+/** \defgroup complex Complexes 
+The module containing the various simplicial complexes
+*/
+
+//@{
+
+/** \defgroup edgemesh Edge Meshes (i.e. PolyLines)
+This module contains the documentation for the types and the functions used for representing and managing generic polylines, or in other words \b edge\b meshes.
+*/
+
+/** \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 tetramesh Tetrahedral Meshes
+This module contains the documentation for the types and the functions used for representing and managing generic tetrahedral of meshes.
+*/
+
+//@}
+
+/** \defgroup code_sample Code Examples
+This module contains a number of small examples to explain the library features
+*/
+

docs/Doxygen/index.dxy

@@ -3,65 +3,49 @@ 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. 
 
-The library, composed by more than 50k lines of code, 
+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 was built to manage triangular meshes, so most of the classes
+The VCG library is tailored to mostly manage triangular meshes:
-and algorithms it contains are related to such object. This is especially true
+The library is fairly large and offers many state of the art functionalities for processing meshes, like:
-for the things that are in the "mesh" folder of the tree. This document
+- high quality simplfication,
-basically explains how the concept of mesh is implemented, i.e. what the "type"
+- efficient spatial query structures (uniform grids, hashed grids, kdtree, ...) ,
-of a mesh is and how it can be obtained, how the connectivity  of the mesh is
+- advanced smoothing and fairing algorithms,
-stored and how it is used to visit the mesh. This part of the library is self
+- computation of curvature,
-contained, only standard libraries are included, as STL (which are intensively
+- optimization of texture coordinates,
-used all over the code).
+- Hausdorff distance computation,
+- Geodesic paths
+- mesh repairing capabilities and many many other.
+- isosurface extraction and advancing front meshing algorithms
+- subdivision surfaces
 
+Documentation
+-------
 
+Start from the following pages for basic concepts and needs.
 - \subpage install "Installing the VCG Library"
 - \subpage basic_concepts "Basic Concepts"
 - \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"
+- \subpage examples "Short Examples showing various features of the lib"
 
+Notable Applications
+------- 
+A number of applications have been developed using the vcglib:
+- <a href="http://meshlab.sourceforge.net">MeshLab</a>: the renowed open source mesh processing is based on this library.
+- \subpage metro "Metro, the tool for measuring differences between meshes"
 
-
+Contacts
-Point3 as an example of the style
+-------
---------
+For any info about licensing the (portion of the library) please contact us:<br>
-We won't going through all of the files and classes of the library to show how
+<b> Paolo Cignoni (p.cignoni@isti.cnr.it) </b><br>
-it is built. You will find most of the information in the code as comments, and
+<b> Fabio Ganovelli (f.ganovelli@isti.cnr.it) </b><br>
-when understood the implementation flavor, you won't even need the comments.
+<a href="http://vcg.isti.cnr.it">Visual Computing Lab</a> of the Italian National Research Council Institute ISTI
-
-The definition of class Point3 looks like this:
-
-\code
-
- template <class T> class Point3  {
-    public:
-        Point3() { }
-        ~Point3()   { }
-
-    private:
-       T _v[3];
-//    ....
-//    ....
-    public:
-      T & X(){return v[0];}
-      T & Y(){return v[1];}
-      T & Z(){return v[2];}
-
-//     ...... operators
-   };
-\endcode
-
-
-You  will find that most of (if not all of) the classes have some template
-parameters. In this case it is used to say which type is used as coordinate
-(most of the times it will be float or double, but it can be any type
-implementing the operator used in the bodies of Point3 operators). Another
-common characteristic is the access method to the data (in this case v[3]),
-which are always defined as private member.
 
 */

docs/Doxygen/main_concept.dxy

@@ -1,27 +1,27 @@
 /** \page basic_concepts
-
 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:
 \code
  class MyMesh : public vcg::tri::TriMesh< std::vector<MyVertex>, std::vector<MyFace> >  {}
 \endcode
-where `vcg::TriMesh` is the base type for a triangle mesh and it is templated on:
+where vcg::TriMesh is the base type for a triangle mesh and it is templated on:
 - the type of STL random access container containing the vertices
--- 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
--- 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 :
 \code
-#include <vcg/complex/complex.h>   
+#include <vcg/simplex/vertex/base.h>
+#include <vcg/simplex/vertex/component.h>
 
 class MyVertex;
 class MyFace;
@@ -35,17 +35,23 @@ class MyVertex0 : public vcg::Vertex<MyUsedTypes, vcg::vertex::Coord3d, vcg::ver
 class MyVertex1 : public vcg::Vertex<MyUsedTypes, vcg::vertex::Coord3d, vcg::vertex::Normal3f,vcg::vertex::Color4b> {};
 class MyVertex2 : public vcg::Vertex<MyUsedTypes > {};
 \endcode
-
+vcg::Vertex is the VCG base class for a vertex.
-`vcg::Vertex` is the VCG base class for a vertex.
+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
-
-`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
 \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).
+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
-#include <vcg/complex/complex.h>   
+#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/trimesh/base.h>
 
 class MyVertex;
 class MyFace;
@@ -63,16 +69,17 @@ int main()
   MyMesh m;
   return 0;
 }
-\endcode
-One more comment: `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
 
+\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
 --------------------
 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.
 
 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 `try::Append` utility class:
+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>
 
@@ -80,15 +87,18 @@ 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.
+
+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
+-----------
 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.
 
 How to process a mesh
----------------------
+-------------
 The algorithms that do something on a mesh are generally written as static member functions of a class templated 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
-/** vcg/complex/trimesh/update/normal.h */
 ...
 template <class ComputeMeshType>
 class UpdateNormals{
@@ -108,7 +118,15 @@ 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 show how to compute the value of the normal and the mean and gaussian curvature per vertex:
 \code
-#include <vcg/complex/complex.h>   
+
+#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/trimesh/base.h>
 #include <vcg/complex/trimesh/update/normals.h>     //class UpdateNormals
 #include <vcg/complex/trimesh/update/curvature.h>   //class UpdateCurvature
 
@@ -135,7 +153,7 @@ int main()
   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 algorithm 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.
+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 algorithm 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.*/
 

docs/Doxygen/shot.dxy

@@ -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.
+
+- \bIntrinsic (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 "../img/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 "../img/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 "../img/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 "../img/shot-Distort1.jpg"
+where
+\image html "../img/shot-Distort2.jpg"
+and
+\image html "../img/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.
+*/