 
/** \page skeletonType Skeleton (DATA_SKELETON)

\section skeletonStructure Skeleton Structure

\image html type_skeleton_thumb.png

A \ref SkeletonT "skeleton" represents a hierarchical tree structure of \ref JointT "joints". The joints can be
accessed through the skeleton. Therefore the skeleton class provides an \ref SkeletonT::Iterator "iterator" over its joints.
Additional ways to access joints from the skeleton are defined in the \ref JointAccess "Joint Access Section".\n
The \ref JointT "joint class" does not directly store information about the position and orientation of the joint, since
this is dependent on the current pose. The joint class can be used to traverse from a joint to its neighbors in
the tree structure and to set the selection state of a joint. Each joint is equipped with a unique id which is guaranteed
to lie in a range between \f$[0,\cdots, (n-1)]\f$, where \f$ n \f$ is the number of joints. So when a joint is deleted
from the skeleton the ids may change.

\section skeletonPoses Poses and Animations

\image html poses.png

A skeleton consists of a set of different poses. Initially a skeleton has only one attached pose. The so called reference pose.
This pose defines the original position and orientation of each joint in the skeleton. For each animation defined on the skeleton
poses store the position of joints in each frame of the animation. So for every frame of the animation we have an associated pose.
\n \n
The \ref SkeletonT::referencePose "referencePose()" can directly be accessed from the skeleton. In order to access 
specific poses from the animation we first have to get a handle for that pose. These handles are called \ref AnimationHandle "AnimationHandles"
and they store the index of an animation and index of a frame (or pose). All functions needed to access animations and poses
from a skeleton are defined in the \ref AnimationAccess "Animation Section".

\section transformations Joint Transformations

\image html transform.png

A \ref PoseT "pose" of the skeleton defines the skeleton configuration for one frame in the animation. Thus if we want to change
the position of joints this is only meaningful when a pose is given. The \ref PoseT "Pose class" can then be used to alter the
transformation of joints. Basically there are two \f$ 4 \times 4 \f$ matrices for every joint which store its alignment.\n \n

For every joint \f$ J_i \f$ in the skeleton we define a matrix \f$ G_i \f$ to prescribe the global position and orientation of
the joint. Hence, \f$ G_i \f$ is also referred to as the global matrix: \n

\f[
 G_i = \left[  \begin{array}{cccc}
                  &   &   & p_x\\
                  & r &   & p_y\\
                  &   &   & p_z\\
                0 & 0 & 0 &   1\\
              \end{array} \right] \f] \n \n

where \f$ r \in R^{3 \times 3} \f$ is a rotation matrix and \f$ p = (p_x,p_y,p_z)^\top \f$ denotes the global joint
position. The global matrix can also be seen as a transformation for the change of a basis. The global matrix
transforms points from the local coordinate frame of the joint to global Cartesian coordinates.\n \n

The representation of joints using global matrices is sufficient to represent the geometry of a skeleton, but for
computational efficiency we add another representation. We also express the position and orientation of a
joint relative to its parent joint. This local representation of the joints is also stored in matrices, yielding
a local matrix \f$ L_i \f$ for every joint \f$ J_i \f$:\n

\f[ L_i = G_p^{-1} \cdot G_i \f] \n

The functions to access and alter the transformations are defined in the \ref PoseEditing "Pose Editing section" of the
\ref PoseT class.\n \n
<B>Note:</B> When using the functions \ref PoseT::setLocalMatrix and \ref PoseT::setLocalTranslation the second parameter
'_keepLocalChildPositions' defines if a change of the local matrix, keeps the local matrices of the child joints and thus
updates the global matrices of the child joints or vice versa.\n \n
<B>Note:</B> When using the functions \ref PoseT::setGlobalMatrix and \ref PoseT::setGlobalTranslation the second parameter
'_keepGlobalChildPositions' defines if a change of the global matrix, keeps the global matrices of the child joints and thus
updates the local matrices of the child joints or vice versa.\n
\n
The \ref PoseT "Pose class" also provides unified matrices. These matrices are stored to minimize computations since they
are used often when the skeleton is equipped with a skin mesh. The unified matrix maps a point from global coordinates
in the reference pose to global coordinates in another pose. If the global matrix of a joint in reference pose is denoted as
\f$ G_0 \f$ and the global matrix in a target pose is denoted as \f$ G_f \f$ then the unified matrix \f$ U \f$ is given as:

\f[ U = G_f \cdot G_0^{-1} \f] \n

Functions to access the unified matrices of a pose are defined in the \ref UnifiedMatrices "Unified Matrices section".

\section skeleton_tutorial_1 Skeleton Tutorial 1: Simple Skeletal Animation

This section shows and explains a sample code to construct a simple skeletal animation. Images from the resulting animation are shown
below:
\image html skeletonTutorial1.png

To generate such an animation we first have to define the structure of the skeleton:

\code
  //add an empty skeleton in OpenFlipper
  int objectId = -1;
  
  emit addEmptyObject( DATA_SKELETON, objectId );

  SkeletonObject* skeletonObject;
  if ( !PluginFunctions::getObject(objectId, skeletonObject) ) {
    emit log(LOGERR,"Unable to create new Skeleton");
    return;
  }

  Skeleton* skeleton = PluginFunctions::skeleton(skeletonObject);

  // setup the structure of the skeleton
  // we want to construct a row of 3 joints
  Skeleton::Joint* currentParent = 0;
  int jointCount = 3;

  for (int i=0; i < jointCount; i++){
    std::string      jointName = QString("Joint" + QString::number(i)).toStdString(); // name of the joint
    Skeleton::Joint*  newJoint = new Skeleton::Joint(currentParent, jointName );      // create new joint object with a pointer to its parent joint object

    skeleton->addJoint(currentParent, newJoint);                                      // and add it to the skeleton
    currentParent = newJoint;
  }
\endcode

Now the structure of the skeleton is defined, but it does not have an animation and the position of all joints in the reference pose is \f$ p = (0,0,0)^\top \f$.
In the next step we set the correct positions for the reference pose:

\code
  // set positions for the reference pose
  Skeleton::Pose* refPose = skeleton->referencePose();
  double xOffset = 0.0;
  
  // iterate over all joints of the skeleton and set a new translation
  // the joints transformation matrix is initially the identity so changing
  // the translation yields the desired effect
  for (Skeleton::Iterator it = skeleton->begin(); it != skeleton->end(); ++it){
    refPose->setGlobalTranslation( (*it)->id(), ACG::Vec3d(xOffset, 0.0, 0.0) );
    xOffset += 1.0;
  }
\endcode

The reference pose of the skeleton is now completely defined, but we still don't have an animation. It is created and added to the skeleton as follows:

\code
  //add an animation
  int frameCount = 100;
  
  FrameAnimationT<ACG::Vec3d>* animation = new FrameAnimationT<ACG::Vec3d>(skeleton, frameCount);
  AnimationHandle animHandle = skeleton->addAnimation("Rotation", animation);
  skeleton->animation(animHandle)->setFps(25);
\endcode

We have added an animation with 100 frames and a playback rate of 25 frames per second. The transformations for every joint and every frame of the
animation however is still an identity matrix and therefore only one point is visible when this animation is played. To change this we now have to
change the transformations of all joints for the complete animation:

\code
  // set position in every pose/frame of the animation
  // joints are indexed 0,1,2 in our case. so 1 yields the middle joint
  Skeleton::Joint* middleJoint = skeleton->joint(1);

  // for the two outer joints we just use the same translation
  // like in the reference pose, but for the middle joint we also
  // apply a rotation which is incremented from 0 to 90 degrees
  ACG::GLMatrixd rotationMatrix;
  rotationMatrix.identity();
  double maxAngle = 90.0;
  ACG::Vec3d axis(0.0, 0.0, 1.0);

  for (int i=0; i < frameCount; i++){
    animHandle.setFrame(i);

    Skeleton::Pose* pose = skeleton->pose(animHandle);

    // set the same translation like in the reference pose
    for (Skeleton::Iterator it = skeleton->begin(); it != skeleton->end(); ++it)
      pose->setGlobalTranslation( (*it)->id(), refPose->globalTranslation( (*it)->id() ) );

    // update the rotation matrix
    rotationMatrix.rotate( maxAngle / frameCount, axis);
    // copy the rotation matrix to the global matrix of the middle joint
    pose->setGlobalMatrix(     middleJoint->id(), rotationMatrix, false );
    // since the translation is lost now..re-add it
    pose->setGlobalTranslation(middleJoint->id(), refPose->globalTranslation( middleJoint->id() ), false );
  }
\endcode

Now the animation is complete. In order to use these code snippets two additional things are needed. For one we need two includes:
\code
#include <ACG/Math/GLMatrixT.hh>
#include <ObjectTypes/Skeleton/Skeleton.hh>
\endcode

and after the animation is constructed we have to inform OpenFlipper about the changes:

\code
  emit updatedObject(skeletonObject->id(), UPDATE_ALL);
  PluginFunctions::viewAll();
\endcode

\section skeleton_tutorial_2 Skeleton Tutorial 2: Skinning

In this tutorial we extend the first tutorial by adding a mesh which deforms with the rotation of the skeleton. For simplicity we just
construct a mesh without faces. Additionally, the skin weights for the points of the mesh are also computed using a very simple method
and therefore the result does not look perfect. The result is shown below:

\image html skeletonTutorial2.png

The first thing we need to do is to add a mesh object:

\code
  //add a mesh
  objectId = -1;
  emit addEmptyObject( DATA_TRIANGLE_MESH, objectId );

  TriMeshObject* meshObject;
  if ( !PluginFunctions::getObject(objectId,meshObject) ) {
    emit log(LOGERR,"Unable to create new Mesh");
    return;
  }

  TriMesh* mesh = PluginFunctions::triMesh(meshObject);
\endcode

The connection between joints of the skeleton and vertices of the mesh is stored in the skin weights. They describe the weighted influence of different
joints on one vertex. The weights are stored as a mesh property and we need to add the property first:

\code
  //add skin-weights property on the mesh
  OpenMesh::VPropHandleT< BaseSkin::SkinWeights > propWeights;
  mesh->add_property(propWeights, SKIN_WEIGHTS_PROP);
\endcode

Now we can go on and add vertices to the mesh and set their skin weights. The points are added above and below the skeleton and we add 50 points between
two joints both above and below:

\code
  int steps = 50; // number of intermediate points

  for (int i=0; i < jointCount; i++)
  for (int j=0; j < steps;      j++){
    // intermediate position
    double xPos = j / double(steps-1);

    // add vertices
    TriMesh::VertexHandle vh1 = mesh->add_vertex( ACG::Vec3d(i + xPos,  0.1, 0.0) );
    TriMesh::VertexHandle vh2 = mesh->add_vertex( ACG::Vec3d(i + xPos, -0.1, 0.0) );

    // add a simple weighting from 1 directly at joint i down to 0
    // at the position of the next joint
    mesh->property(propWeights, vh1)[ i ] = 1.0 - xPos;
    mesh->property(propWeights, vh2)[ i ] = 1.0 - xPos;

    if ( i != 2 ){
      // add an increasing weight for the next joint
      // this weight starts with 0 near the joint i and increases
      // to 1 near joint i+1
      mesh->property(propWeights, vh1)[ i+1 ] = xPos;
      mesh->property(propWeights, vh2)[ i+1 ] = xPos;
    } else
      break; // no intermediate points after the last joint
  }
\endcode

This simple skin weight definition shifts the center of the rotation between the first and the second joint, but a 'correct' weight computation would
exceed the range of this tutorial. To run the code two more things have to be considered. First, we have to add an include for the skinweights:

\code
#include <ObjectTypes/Skeleton/BaseSkin.hh>
\endcode

And additionally we have to inform OpenFlipper about the changes that have been made:

\code
  // tell the skeletal animation plugin to attach the mesh to the skeleton
  RPC::callFunctionValue<bool, int, int>("skeletalanimation", "attachSkin", skeletonObject->id(), meshObject->id());
  // the mesh has been updated
  emit updatedObject(meshObject->id(), UPDATE_ALL);
  // switch to drawMode points because we have no faces in our mesh
  PluginFunctions::setDrawMode( ACG::SceneGraph::DrawModes::POINTS )
\endcode

<B>Note:</B> The RPC function call can be left out, but then the user has to connect skeleton and skin with the 'Attach Skin to Skeleton' Button in the Skeletal Animation Toolbox.\n\n
The complete sourcecode of this tutorial can be found \subpage skeletonSource "here".


*/
