Tutoriel AReVi/hLib 2

Ronan BILLON
lundi 15 janvier 2007

Table des matires

1. Introduction ........................................................................................................................................................2
2. Thorie et principe de la hLib...........................................................................................................................2
2.1. Classe de donnes ....................................................................................................................................3
2.2. Classe daffichage ....................................................................................................................................3
2.3. Classe danimation...................................................................................................................................4
3. Utilisation et pratique partir des exemples ...................................................................................................5
3.1. testBody : cration manuelle dun squelette............................................................................................6
3.2. testSkin ....................................................................................................................................................7
3.3. testLoad....................................................................................................................................................8
Bibliographie...........................................................................................................................................................9
1. Introduction
ARVi est une bibliothque constituant la base commune la majorit des travaux mens au LISYC/CERV
http://www.cerv.fr/. La thmatique de celle-ci repose sur lactivation de multiples entits autonomes en interac-
tion dans des environnements tridimensionnels interactifs (simulation biologique, circulation routire, outils de
formation...). Pour avoir de plus amples informations, un chapitre y est consacr dans Le trait de la ralit
virtuelle [HCJ06] . Le code source est la disposition de la communaut, selon la licence LGPL, depuis le site
http://www.enib.fr/~harrouet/ ou encore sur SourceForge (http://sourceforge.net/projects/arevi/)
Cette documentation ne contient pas les instructions pour linstallation, mais vous pourrez retrouver toutes les
instructions pour compiler la bibliothque dans le fichier README. Les exemples fournis avec cette documentation
se compile avec la suite de commande traditionnelle sous *nix :

Exemple 1. Compilation et excution des exemples

$ ./configure
======== Building dependencies...
...
$ make
$ ./myexecutable

Note : Pour que le script de configuration sexcute correctement, il est indispensable

que lexcutable arevi-config soit dans votre PATH. Consultez la documentation situ dans
MY_PATH_TO_AREVI/AReVi/Vrac/areviGuide.pdf.

hLib (Humanoid Library) est une bibliothque qui ajoute les fonctionnalits ncessaires pour crer des per-
sonnages anims base de squelette. Ces personnages ne sont pas obligatoirement des humanodes. En thorie
hLib peut tre compile sur toutes les plateformes o ARVi est disponible. Les objectifs de la hLib sont les
suivants :

Cration et importation de squelettes (depuis les types de fichier suivant : SMD (Half Life 2), MD5 (Doom 3),
BVH (Biovision)) ;
Importation danimation directe partir de keyframes (mme type de fichier) ;
Skinning animation de la peau en suivant le squelette ;
Animation par cinmatique inverse.
Animation en temps rel de plusieurs individus.
Le but de ce document est de prsenter les concepts de base ncessaires lutilisation de cette bibliothque.
Il sadresse un public avertit, connaissant dj ARVi et ayant des notions de mathmatiques gomtriques
3D (matrices, quaternions, ...). Pour avoir des informations sur les classes prsentes, une documentation a t
gnre automatiquement avec Doxygen. Vous la trouverez dans le ballot. Pour plus de dtails sur les diffrents
mcanismes dploys ici, nous invitions le lecteur consulter la bibliographie. La plupart des algorithmes utiliss
sont issus de publications scientifiques.
Pour utiliser cette bibliothque, veuillez ajouter votre compilateur le lien vers AReViHLib2.(so,dll).

2
 Tutoriel AReVi/hLib 2

2. Thorie et principe de la hLib

Ce chapitre prsente la structure lmentaire composant tout humanode : le squelette. Le corps humain est
compos de plus de 200 os, relis entre eux par les muscles et les ligaments. Les degrs de libert des articulations
du squelette (genou, paule, . . . ) sont contraints, ainsi tous les mouvements ne sont pas possibles. Mais, Le
squelette humain permet un ensemble de mouvements trs complexes. La reproduction de ceux-ci sur ordinateur
est difficiles. Il est commun en animation de synthse de nutiliser quun nombre restreint darticulations afin de
simplifier les calculs.

2.1. Classe de donnes

Avant de voir le squelette en lui-mme, nous allons voir la structure lmentaire le composant. Il sagit
du Joint, cest la jonction entre deux os du squelette. Dans la hLib, le choix a t fait de le faire driv de
la classe Base3D. en effet, chaque Joint est compos dune position et dune orientation. Le squelette sera
alors une simple collection de joints relis entre eux, on pourra le reprsenter sous forme darbre. Les liens
entre joints se font toujours dans le sens : "un fils connat son pre" et non "un pre connat ses fils" comme
ctait le cas prcdemment dans la premire version de la hLib. Les enfants sont attachs (mthode de Base3D :
attachTo(parent)) leur pre, ce qui facilite la manipulation. Supposons par exemple que lutilisateur sou-
haite faire bouger le bras. Pour cela il lui suffit de manipuler larticulation de lpaule et les enfants (coude,
poignet, doigts. . . ) seront automatiquement mis jour.
La manipulation des joints peut se faire indiffremment dans le repre global (trs rare), le repre de
lobjet (exemple : getPosition() de la classe Base3D), le repre du parent (setLocalTranslation() et
setLocalRotation()) et le repre local du joint courant. Avant toute manipulation assurez-vous de savoir
quelle est votre rfrence.

Avertissement
Il y a deux diffrences notables avec la premire version :

1. la disparition dune position de repos et du delta. En effet, prcdemment, il tait

ncessaire de prciser une position et orientation de repos du joint dans le repre
du parent et deffectuer toutes les manipulations en faisant varier un delta. Cette
particularit ntant pas indispensable, elle a t supprime par soucis de sim-
plicit ;
2. la disparition des contraintes articulaires. Devant la difficult implmenter, puis
exprimer et utiliser correctement les contraintes, elles ont t simplement sup-
primes. La reprsentation par quaternion (3 degres de libert) nest absolu-
ment pas faite pour tre contrainte, car il existe une infinit de combinaison de
rotations simples pour atteindre une orientation donne. Cette possibilit sera
re-insre lorsquune reprsentation adquate sera trouve.

2.2. Classe daffichage

Laffichage des humanodes, de cette version, est gr par la classe BodyShape qui hrite dShape3D. Cette
classe gnre automatiquement une reprsentation symbolique du squelette avec des sphres pour les joints et des
lignes 3D pour les os. Laffichage du squelette est mis jour automatiquement ds quun joint est dplac. Il est
important de prciser que le squelette du BodyShape est une simple rfrence, toute modification effectue sera
automatiquement retranscrite laffichage. Pour toute manipulation sur les joints ( partir de setPosition() et
setOrientation() de la classe Base3D), le repre de rfrence est celui de lobjet 3D et non le repre global
du monde.

3
 Tutoriel AReVi/hLib 2

Pour embellir le squelette, une peau, se dformant en suivant ses mouvements, peut tre ajoute. La classe
Skin hritant de Surface3D gre cela parfaitement. Pour un mme BodyShape, plusieurs peaux peuvent exister,
cela permet un dcoupage de la structure du personnage, pour par exemple changer seulement sa tte. Le principe
de la dformation sappuie sur lorientation et la position des joints, ainsi quune pondration. Ce qui signifie par-
ticulirement que deux squelettes ayant une forme identique peuvent avoir des orientations de joints diffrentes,
et donc un comportement de la peau diffrent.

Figure 1. Deux squelettes identiques avec une orientation des joints diffrente

Limage prcdente montre lutilisation des programmes de test $ ./testMorphet $ ./testLoad. Avec le
premier, il y a une adaptation de lorientation des joints en fonction de la peau alors que le second montre une
application brute et directe de la skin sur le squelette.

2.3. Classe danimation

Lanimation se dcoupe en deux parties majeures : La cinmatique directe et la cinmatique inverse.
Lanimation directe est une technique courante qui se base sur une dcomposition de lanimation en po-
sitions cls. Ces images cls sont ensuite relues pour re-gnrer lanimation. La classe Keyframe drive de la
classe Skeleton, une position cl correspond un squelette avec une pose bien dfinie. La seule variable sup-
plmentaire y ajouter est le temps que doit durer cette pose. Ces images cls sont regroupes dans un conteneur
KeyframeAnimation. Il est trs rare quelles soient manipules directement. Une animation dcrit de manire

4
 Tutoriel AReVi/hLib 2

ordonne les diffrentes postures appliquer un squelette pour faire un mouvement. La dure du mouvement
est calcule automatiquement au moment dune insertion ou dune suppression dimage cl.
La cinmatique inverse permet de trouver une position et une orientation de chaque joints du squelette pour
satisfaire une condition de position dun joint particulier. Par exemple, je souhaite que la main dun humanode
atteigne la porte, lalgorithme va calculer les orientations de chacun des joints de la chane jusqu la racine.
Lalgorithme utilis par la hLib est le Cyclic Coordinate Descent (CCD). En plusieurs tapes, lalgorithme modifie
lorientation de chaque joints pour tenter datteindre la position voulue.

3. Utilisation et pratique partir des exemples

Avant de commencer, voici un diagramme UML synthtique prsentant lorganisation des classes fournient
par la hLib.

Figure 2. Synthse du diagramme de classe

Pour prsenter lutilisation de la hLib, nous utiliserons les exemples fournis dans le ballot. Dans lordre :

testBody : cration manuelle dun squelette ;

testInteractiveBody : cration manuelle dun squelette et manipulation interactive du squelette partir de cin-
matique inverse ;
testSkin : cration manuelle dun squelette simple, gnration dune peau partir dune sphre ;
testLoad : importation de plusieurs fichiers contenant le squelette, la peau et lanimation ;
testMorph : importation de plusieurs fichiers contenant le squelette, la peau et lanimation avec une adaptation
du squelette pour une dformation adapte de la peau ;

5
 Tutoriel AReVi/hLib 2

tesLoadInteractive : importation dun fichier contenant le squelette et la peau, lhumanode pourra tre manipul
par cinmatique inverse.

3.1. testBody : cration manuelle dun squelette

Ce test permet de crer un squelette qui aura la forme dune fourche. Un joint sera modifi priodiquement
par une activit.

Exemple 2. testBody.cpp

...
ArRef<Skeleton> skeleton = Skeleton::NEW();

ArRef<Joint> joint = Joint::NEW();

joint->setName("root");
joint->setLocalTranslation(Vector3d(-0.5, 0.0, 0.0));
skeleton->addJoint(joint);

joint = Joint::NEW();
joint->setName("joint1");
joint->setParent(skeleton->findJoint("root"));
joint->setLocalTranslation(Vector3d(1.0, 0.0, 0.0));
joint->setLocalRotation(Quaterniond(1.6,0.0, 1.0, 0.0));
skeleton->addJoint(joint)
...

La cration dun squelette vide se droule de la mme faon que tout objet ARVi avec la commande
Skeleton::NEW(). La suite correspond lajout des joints dans le squelette. Les tapes respecter dans lordre :

1. instancier avec Joint::NEW() ;

2. nommer le joint avec joint->setName("root"). Cette tape est trs importante car plusieurs vrification
sont faites (asssert) que ce soit lors de linsertion, du clonage de squelette, de lapplication de keyframe.
3. attribuer un parent avec joint->setParent(skeleton->findJoint("root")). Cette tape doit
prcder toute modification locale du joint. En effet, si celui-ci na pas de parent comme rfrent, il ne
pourra pas sorienter correctement.
4. placer et orienter avec les mthodes de Base3D ou celle du type joint->setLocalTranslation().
La suite est simple, il suffit de passer le squelette un BodyShape pour quil saffiche en 3D.

Exemple 3. Passage du squelette un BodyShape

ArRef<BodyShape> bodyShape = BodyShape::NEW();

bodyShape->setSkeleton(skeleton);

body = Body::NEW();
body->setShape(bodyShape);

Lors de la cration des joints, la rfrence dun a t sauvegard. Celle-ci servira durant lactivit pour faire
tourner un morceau dun angle de PI/4.

6
 Tutoriel AReVi/hLib 2

Exemple 4. testBody.cpp

...
body->setPosition(1,0,0);
scene->addObject(body);
...
bool TestBody::event(ArRef<Activity> /*act*/, double /*dt*/)
{
joint_test->pitch(M_PI_4);
return true;
}
...

Le cas suivant sappuyant fortement sur cet exemple, il ne sera pas dtaill. La diffrence notable est
linstanciation du Body avec la commande : body = InteractiveBody::NEW(). Jencourage fortement la
lecture de la documentation gnre par Doxygen pour lutilisation des chanes pour la rsolution de la cinma-
tique inverse. La mthode setAutoIk() permet dactiver la rsolution. La mthode setIkChain() permet de
dfinir la propagation de la rsolution depuis le joint slectionn jusqu la racine.
La rsolution de la cinmatique inverse se base sur lalgorithme CCD. Celui-ci est implment dans la classe
IkCcd, elle contient une variable statique dfinissant le nombre de fois que la chane entire doit tre estim. Et,
une mthode statique solve(goal, end, parent) qui modifiera la chane depuis le joint end jusquau joint
parent pour atteindre la position fournit par goal. Bien que ce paramtre soit une Base3D, seul la position est
utilise.

3.2. testSkin
Cet exemple vise raliser une peau en forme de sphre qui sera dforme en suivant les diffrents mouve-
ments des joints du squelette en toile sous-jacent.

Exemple 5. testSkin.cpp

...
ArRef<Skeleton> skeleton = Skeleton::NEW();

ArRef<Joint> joint = Joint::NEW();

joint->setName("root");
skeleton->addJoint(joint);
...
ArRef<BodyShape> bodyShape = BodyShape::NEW();
bodyShape->setSkeleton(skeleton);
body = Body::NEW();
body->setShape(bodyShape);
...

La premire tape est la cration du squelette avec des joints disposs en toile autour dun noeud racine.
Puis dappliquer ce squelette une BodyShape. Ensuite vient la gnration de la peau, pour le cas prsent et dun
point de vue didactique, elle est gnre partir dune sphre. Toute Skin est un objet Surface3D avec deux
informations fondamentales pour chaque vertex : une liste de joints suivre et une pondration pour chaque joints
de la liste.

7
 Tutoriel AReVi/hLib 2

Exemple 6. testSkin.cpp

...
ArRef<Skin> skin = Skin::NEW();
ArRef<Sphere3D> sphere = Sphere3D::NEW();
sphere->setRadius(1.0);
generate(skin, sphere, skeleton);
bodyShape->addSkin(skin);

Comme indiqu dans la documentation gnre par Doxygen, il faut imprativement utiliser la mthode
setRestPose() aprs avoir ajout toutes les peaux au corps, sinon, il risque dy avoir des dformations
tranges . Le reste du code permet de crer six cube de manipulation qui sont attachs aux joints grce la
mthode attachTo(), voici un exemple dintrt pour la classe Joint dhriter de Base3D. En manipulant les
cubes, on remarque bien la dformation de la peau.

3.3. testLoad
Cette utilisation sera la plus commune de la hLib. Ce programme prend en argument un ou deux fichiers et
affiche ce quil contient. Il peut sagir :

dun squelette simple ;

dun squelette avec une peau (type *.md5mesh et *.smd) ;
dun squelette avec une animation (type *.bvh, *.md5anim et *.smd) ;
Plusieurs combinaisons sont possibles, tant que lordre et le nom des joints est respect. Dans ce programme
la premire tape est dutiliser les mthodes static de la classe HLibLoader. Puis en suivant les mmes tapes
que la version prcdente, rcupration des donnes aprs avoir charg les fichiers avec : LoaderData data
= HLibLoader::loadFile(str);. LoaderData contient trois champs : body, animation et failed qui
sont suffisamment explicite. Le champs animation peut avoir la valeur Animation::nullRef() si aucune in-
formation na t trouve dans le fichier.

Exemple 7. testLoad.cpp

...
StlString str = ArSystem::getCommandLine()[1];
cerr << "Loading " << str << " ...\t";
LoaderData data = HLibLoader::loadFile(str);
if(data.failed) {
cerr << "FAILED" << endl;
} else {
cerr << "done" << endl;
}
body = data.body;

scene->addObject(body);
...

Lanimation seffectue simplement en appliquant une pose au corps. Cette pose est dtermine en fonction
du temps courant, les tapes sont les suivantes :

1. fmod(act->getTime(),animation->getDuration()) : on calcule le temps courant modulo la dure de lanimation

;

8
 Tutoriel AReVi/hLib 2

2. animation->evaluate(dt) : lanimation retourne une pose (Keyframe) en fonction des positions cls ;
3. body->applyPose() : qui est lapplication de cette pose par recopie des donnes de la Keyframe.

Le dernier exemple testMorph ne sera pas dtaill, car une seule ligne a t ajoute. Il sagit de ladaptation
du Body pour que les orientations de dpart de lanimation correspondent aux orientations de dpart de la peau.
Si cette adaptation nest pas faite, la peau devient trange , voir les images Figure 1. Cette dformation ne
se produira pas si les joints de lanimation sont bien en correspondance avec les joints du squelette associ la
peau, ce qui arrive souvent lorsque toute la cration est faite dun coup, mais plus rarement lorsque lon rcupre
des animations venant dailleurs (exemple fichier *.bvh appliqu avec un bonhomme *.md5). La commande est
simple : body->setBaseframe(animation->evaluate(0),false). Le premier paramtre est la premire
pose de lanimation et le second paramtre est un boolen permettant lalgorithme de dformer le squelette.
Cette option nest utiliser que si les squelettes sont trs proches sinon, l trange reviendra.

Bibliographie
[HCJ06] Fabrice Harrouet, Eric Cazeaux, et Thomas Jourdan, Arvi, chapitre du volume Outils et modles
informatiques des environnements virtuels du trait de la ralit virtuelle, P. Fuchs, G. Moreau, et 72
auteurs, 4 volumes, Les Presses de lEcole des Mines de Paris, www.esnmp.fr/Presses, mars 2006.