AnimaL - Tutorial

Tutorial

General Architecture
Implementation and namespaces
Graphic User Interface (GUI)
Modules of AnimaL
External 3D animated models

This architecture is implemented in the libAnimAL-X3DTK-Qt.so which is located in $ANIMAL/lib.
To compile this library: cd $ANIMAL/animal/X3DTK ; qmake ; make

This AnimAL-X3DTK-Qt library shows how to implement AnimaL in a specific architecture:

The input-output 3D format is the X3D norm. There are two main data structures in X3DTK::MainScene, the scene graph for the animation (X3DTK::MainScene::x3dscene) and the scene graph for the rendering (X3DTK::MainScene::glscene). All of these modules use the X3DToolKit library.
The graphic user interface (GUI) is based on Qt and among others on the QGLViewer.

This AnimAL-X3DTK-Qt library is in the main namespace X3DTK which is itself divided in three namespaces:

X3DTK::GL, the rendering of the scene
X3DTK::Qt, the GUI (Qt) and the viewer (QGLViewer),
X3DTK::X3D, input/output, internal 3D models (X3DToolKit) and use of the AnimaL library,

The directory $ANIMAL/animal/X3DTK is organized in the same way.

Graphic User Interface (GUI)

In AnimAL-X3DTK-Qt library, the main Graphic User Interface is composed of:

A main window where:
- x3d files can be loaded (Ctrl-O), saved (Ctrl-S) and reloaded (Ctrl-R).
- different frames can be shown or hidden,
A controller for the animation: play/stop, step by step, reset and diverse buttons to control the digital time and the frame rate.
A viewer to view the 3D scene (see all the default mouse behaviour and the default keyboard shortcuts of the QGLViewer).
Type the key H to view the viewer help.
Appended features:
- The size of the viewer's window can be controlled with the key R.
- Capture video can be done and encoded in MPEP-2 with the key R.
- In QGLViewer, the default SAVE_SCREENSHOT shortcut is Ctrl-S and this shortcut is used to save x3d file in the main window. So we bind the SAVE_SCREENSHOT action to the key I.
A tree structure to view all the x3d nodes in the 3D scene you can edit:
- Ctrl-C : copy a x3d node
- Ctrl-X : cut a x3d node
- Ctrl-V : past a x3d node
- Right clic: insert a x3d node loaded from a file or delete it
- Double clic: open the GUI controller asssociated to the x3d node

You can plug your own viewer if this one inherits from X3DTK::Qt::Viewer.
You just have to add in the main file:

mainController->setViewer(new  YourOwnViewer(mainController.centralWidget(), "Your own viewer"));

See the code of $ANIMAL/examples/X3DTK/qtapp/qtapp.cpp.

Modules of AnimaL

Here we present:

The concept of engine in the AnimaL library.
How to create a new engine in the AnimaL library and to use.
How to create a x3d node corresponding to one engine.
How to create a GUI controllor corresponding to one engine.
To test an engine.

What is an engine ?

The modules of animation are similar to an abstract component we call animal::Engine.
The main role of an animal::Engine is to be:

be moved, move(dt)
be drawn, draw()

How to create an engine ?

To create a new engine in AnimaL, follow the code of animal::SpinningCubeEngine in $ANIMAL/examples/X3DTK/spinningCube/spinningCubeEngine.h.
This class , as a specific engine, inherits from animal::Engine.
The specification of animal::SpinningCubeEngine is:

To draw a cube (or something else) with the GLUT library with a given translation,
To make it turn around its z axe with a given angular velocity,
To compute its corresponding bounding box.

X3D node corresponding to an engine

In the library AnimAL-X3DTK-Qt, the external and internal 3D model use the X3DToolKit library.
In order to represent an engine in the x3d graph, to load and save it in a file .x3d, we can define a x3d node, but this is not an obligation.
In the X3DToolKit documentation, there is examples for the creation of a new x3d node.

Go on the same example animal::SpinningCubeEngine.
First you have to define the x3d node tag and its attributes in the file .x3d (see $ANIMAL/examples/X3DTK/files-x3d/spinningCube.x3d).
Now code the corresponding x3d node in order to load it.
To proceed look at the code in $ANIMAL/examples/X3DTK/spinningCube/spinningCubeNode.h

GUI controller corresponding to an engine

You can create a GUI controller for one engine in order to control its behaviour, but this is not an obligation.
Actually, the associated controller QWidget to one engine is associated to its corresponding x3d node.
To proceed follow the code in $ANIMAL/examples/X3DTK/spinningCube/spinningCubeQt.h.

To test an engine

To test an engine, its x3d node and its GUI, follow the example $ANIMAL/examples/X3DTK/qtapp/qtapp.cpp.

// Include files corresponding to new x3d engine nodes and their associated GUI
#include "spinningCube/spinningCubeNode.h";
#include "spinningCube/spinningCubeQt.h"

// Definition of new x3d node types, so that they can be
// read/written from/to a file.
mainScene.newX4DClass<X3DTK::X3D::SpinningCubeNode>();

// Declaration of functions which return a control widget for given node types.
mainController->defineQWidgetCreationFunction(X3DTK::Qt::createSpinningCubeQWidget);

Thus, after parsing the x3d file, a animal::Engine relative to a specific x3d node is automatically created, connected, moved and drawn. The GUI controller corresponding to the engine will be automatically created by double-clicking on the item corresponding to the engine in the x3d tree of the main GUI.

If you don't create the associated x3d node and GUI like animal::SpinningHexahedronEngine defined in $ANIMAL/examples/X3DTK/spinningHexahedron/spinningHexahedronEngine.h, then uncomment and add this code in $ANIMAL/examples/X3DTK/qtapp/qtapp.cpp:

// Include file corresponding to the new engine
#include "spinningHexahedron/spinningHexahedronEngine.h";

// Define the new engine and add it to the main scene
animal::SpinningHexahedronEngine * SHE = new animal::SpinningHexahedronEngine();
mainController->addEngine(SHE);

Thus the specific engine is automatically created, moved and drawn.

External 3D animated models

In order to reuse an existed code, i.e. 3D animated models in C++ which are external to AnimaL, it can be implemented like an animal::Engine.
That is, to insert external code within AnimaL, you just have to implement a new class which inherits from animal::Engine.
To understand how it works, see How to create an engine ?.

Francois Faure (Francois.Faure@imag.fr) & Laure Heigeas (Laure.Heigeas@imag.fr) / 2004-12-23