ODE Tutorial

This tutorial explains the basics of ODE through the construction of a simple applications that displays cubes falling on the ground.

• Preliminary setup
  • Discovering the QGLViewer
  • Compiling with qmake in a nutshell
  • Testing our example
• ODE in a nutshell
  • Dynamics
  • Collision
  • Joints
• Preparing for the show
  • Object class
  • Bounding box
  • Plane rendering
• The full monthy
  • Viewer
  • Simulation
  • Collision handling
  • Result
• Going further

Preliminary setup

Discovering the QGLViewer

We are going to use ODE for the physics and a very handy library for OpenGL display of the physic simulation, named QGLViewer. This library is based on Qt and encapsulates a viewer for rendering and manipulating (flying through, rotating with a trackball,...) a 3D scene. There are excellent tutorials on the web site, so I just present here the very fundamentals of the library.

• Create a class Viewer that derives from QGLViewer
• Override the method QGLViewer::init() to indicate the OpenGL setup, such as enabling states (e.g. alpha blending) or creating context dependent objects (e.g. texture objects, frame buffers or vertex buffer objects).
• In the overidden QGLViewer::init(), you also specify the "size" of the scene, so that the viewer can optimally compute the near and far plane of the OpenGL camera used to render the scene. You can also tell the viewer to initially setup the camera so that the whole scene is encompassed by the camera frustum. Finally, you can position the camera to the position it occupied when the application was last quit (yes, the QGLViewer saves its state in a .qglviewer.xml file!).
• Overidde the method QGLViewer::draw() to indicate what OpenGL command must be issued to render the scene.
• Overidde the method QGLViewer::animate() to indicate how to animate the scene. This function is called regularly by the viewer, using a timer whose frequency is set with QGLViewer::setAnimationPeriod() (default is every 30ms).

Here is for example a simple viewer that shows a ball whose color is changing over the time.

tutorial1/A/viewer.h 1 #ifndef VIEWER_H 2 #define VIEWER_H 3   4 #include <QGLViewer/qglviewer.h> 5   6 class Viewer : public QGLViewer 7 { 8   Q_OBJECT; 9 public: 10   Viewer(QWidget *parent=NULL); 11   ~Viewer(); 12   13 protected: 14   virtual void init(); 15   virtual void animate(); 16   virtual void draw(); 17 private: 18   float _t; 19 }; 20   21 #endif // VIEWER_H 22

tutorial1/A/viewer.cpp 1 #include "viewer.h" 2 #include <GL/glut.h> 3   4 using namespace std; 5 using namespace qglviewer; 6   7 Viewer::Viewer(QWidget *parent) 8   : QGLViewer(QGLFormat(QGL::SampleBuffers | 9                         QGL::DoubleBuffer | 10                         QGL::DepthBuffer | 11                         QGL::Rgba | 12                         QGL::AlphaChannel | 13                         QGL::StencilBuffer),parent) 14   , _t(0.0f) 15 { 16 } 17 Viewer::~Viewer() 18 { 19 } 20 void Viewer::init() 21 { 22   // Indicate the size of the scene 23   setSceneRadius(2.0f); 24   setSceneCenter(Vec(0.0f,0.0f,0.0f)); 25   // Try to restore previous state or focus the whole scene 26   if (!restoreStateFromFile()) 27   { 28     showEntireScene(); 29   } 30 } 31 void Viewer::animate() 32 { 33   _t += animationPeriod()/1000.0f; 34   if (_t>1) _t = 0.0f; 35 } 36 void Viewer::draw() 37 { 38   static const Vec red  (1.0f,0.0f,0.0f); 39   static const Vec green(0.0f,1.0f,0.0f); 40   41   glColor3fv((1-_t)*red+_t*green);  42   glutSolidSphere(0.5f,30,30); 43 } 44

tutorial1/A/main.cpp 1 #include "viewer.h" 2 #include <QApplication> 3 #include <GL/glut.h> 4   5 using namespace std; 6   7 int main(int argc,char **argv) 8 { 9   glutInit(&argc,argv); 10   11   QApplication application(argc,argv); 12   13   Viewer viewer; 14   viewer.show(); 15   16   return application.exec(); 17 } 18

Compiling with qmake in a nutshell

Qt has a very nice tool to manage compilation, called qmake. You write a simple project file describing the sources and some configuration, and qmake generates the appropriate Makefile for your platform. Here is such a .pro for our simple example abobe:

If you notice the first line, I indicate that I want the project to use qglviewer and glut configuration. These are non standard Qt configuration, so I need to tell Qt what to do when they are presents. For that, I define a qglviewer.prf and a glut.prf files that I put in some directory pointed by the environment variable QMAKEFEATURES. Here are what it looks like on my linux desktop:

qmakefeatures/qglviewer.prf 1 CONFIG *= qt 2 QT     *= opengl xml 3   4 LIBS        *= -lQGLViewer 5

qmakefeatures/glut.prf 1 QT     *= opengl 2 LIBS   *= -lglut 3

I let you adapt this to you particular machine setup. The cool thing about the "feature" mechanism is that it separates machine-dependent configuration (where a particular library is installed) from project-dependent configuration (which file to compile, which library to link with).

Testing our example

Ok, now we can run our example. It displays a simple sphere. Use the three mouse button (+wheel) to turn around the sphere. This is the trackball metaphor. You can press space to switch to a fly metaphor. Press enter to toggle the animation. Quit and re-run the application: the viewpoint is restored! If you want to find more about the existing keybindings, press H, or (better) read the QGLViewer excellent documentation.

ODE in a nutshell

There are many things to know to use ODE correctly, because a lot of magical parameters have to be tuned for your particular application to run as you want. Fortunately, the documentation is quite verbose about this. Conversely (and unfortunately), it lacks a gentle introduction. Let's remedy to this. Here are what you need to know to begin.

Dynamics

ODE has a number of base concepts. Let's start with the two fundamental ones:

• Body: this is a solid rigid body whose dynamics will be computed by ODE during simulation. As so, it does not have a "shape" or a visual appearance. It is just a position and orientation (a "local frame" placed on the center of gravity if you will), a linear and angular velocity (how fast it moves and spins), and a mass together with an intertia tensor (how the mass is distributed in the object).
• World: this is what holds a bunch of bodies (dynamic and static) along with forces, and a current time. Running the physical simulation is just advancing the world's time by small steps and updating each bodies dynamics according to the existing forces and the fundamental law of dynamics.

So basically, here is how you create a physical simulation.

Here, we create just a cube but you can add as many objects as you want. We'll see more about this later on. For the moment, notice how we specified the mass. We used helper functions. Indeed, what the dynamics need is not the mass as you usually think of it (I weight xxx), but the mass inertia matrix, which also gives you how the weight is distributed over the body (it drives how the body spins). This inertia matrix is inintuitive to specify in matrix form. Luckily, for specific cases, such as a uniformly dense cube or sphere, it is easy to compute from the box/sphere dimensions and density. This is what the helper functions do for you. You can find more in section 9.2.0 of the ODE manual.

Collision

I said above that dynamics simulation itself does not need to know the shape of each body. Well, that is true only if you consider that objects do not interact with each other. In reality, a physical simulation is interesting if bodies interact, namely if they collide, bounce and push each other. To compute such interactions, you know need to know the shape of objects, because this is what commands when/where/how bodies interact. Thus, ODE has two other concepts.

• Geom: this is what describe the shape (the geometry) of a body. It can be a canonical shape such as a cube or a sphere, or a polygonal object described by a triangulation of its surface (known as a B-rep).
• Space: this is what holds a bunch of geoms and manages the collision detection more or less intelligently. ODE comes with several flavor of space, as we will see in a moment.

So here is how we would define a geom in ODE, continuing the body example of above.

The important thing to notice is that we "bind" together a body and a geom. Once this is done, changing the position or orientation of one will change that of the other, that is we can call indifferently dBodySetPosition(body,0,6,0); or dGeomSetPosition(body,geom,6,0);.

The interest of separating the body from the (collision) geometry is that we can create "static" geometry. For that, we just create a geom in the space, and not associated body in the world. Typically, this is used to create a ground plane.

Joints

Bodies do not interact only because of collision. They can also interact because they are "attached" together. In ODE terminology, such an attachment is called a joint. I will not describe here the types of join and how to create them, because in this tutorial, we will only consider indpendent objects (e.g. falling cubes on a plane). Moreover, you will find detailed information in the ODE manual.

However, I will describe a particular type of joints: contact ones. Indeed, we have seen that the space manages the collision detection based on the given geoms. However, once collisions are detected, the dynamics must account for them. It turns out that collision/contact interaction can be described as temporary joints that exists only during the time of the contact. Thus, during simulation, we will:

• detect collision,
• create contact objects (indicating physical parameters such as friction coefficients or bouncyness),
• create joints from these contacts,
• attach this joint two the two bodies involved.

We will see more about how to do this in a moment.

Preparing for the show

Before we go to the full monthy and a working example, we should prepare the terrain a little bit, so that the code is organized cleanly and you can quickly identify where to put additional codes to extend the tutorial example. This involves some code engineering that I describe shortly here.

Object class

Since bodies and geoms are tightly linked in a normal ODE application, we will encapsulate them together in a bigger entity called object. We will also encapsulate how to render the object to make our application more sexy. For the moment, we will make a very crude encapsulation; we will see later how to make a better object based one.

An object owns a body and a geom, publicly accessible for simplicity. It can also be required to render itself (using OpenGL), and finally, it can be placed at a given position. The interface and implementation are:

tutorial1/C/object.h 1 #ifndef OBJECT_H 2 #define OBJECT_H 3   4 #include <ode/ode.h> 5   6 class Object 7 { 8 public: 9   dBodyID body; 10   dGeomID geom; 11   12   virtual ~Object(); 13   void render() const; 14   void setPosition(dReal x,dReal y,dReal z); 15 protected: 16   virtual void renderInLocalFrame() const = 0; 17   18 }; 19   20 #endif // OBJECT_H 21

tutorial1/C/object.cpp 1 #include "object.h" 2 #include <GL/gl.h> 3   4 using namespace std; 5   6 Object::~Object() 7 { 8 } 9 void Object::render() const 10 { 11   glPushMatrix(); 12   13   const dReal *p = dBodyGetPosition(body); 14   const dReal *r = dBodyGetRotation(body); 15   float m[16]; 16   m[ 0] = r[ 0];m[ 1] = r[ 4];m[ 2] = r[ 8];m[ 3] = 0; 17   m[ 4] = r[ 1];m[ 5] = r[ 5];m[ 6] = r[ 9];m[ 7] = 0; 18   m[ 8] = r[ 2];m[ 9] = r[ 6];m[10] = r[10];m[11] = 0; 19   m[12] = p[ 0];m[13] = p[ 1];m[14] = p[ 2];m[15] = 1; 20   glMultMatrixf(m); 21   22   renderInLocalFrame(); 23   glPopMatrix(); 24 } 25 void Object::setPosition(dReal x,dReal y,dReal z) 26 { 27   // Equivalent to dGeomSetPosition(geom,x,y,z); 28   dBodySetPosition(body,x,y,z); 29 } 30

The render() function does some fiddling to pass from ODE representation (a position and rotation) to OpenGL representation (a general 4x4 matrix) of transformations. After that matrix is added to OpenGL model view matrix, and object can render itself by using coordinates in its local frame. That's the purpose of the pure virtual function renderInLocalFrame().

We can now subclass Object for various shapes we want to handle. Here is what we could come up with for a cube, for example:

tutorial1/C/cube.h 1 #ifndef CUBE_H 2 #define CUBE_H 3   4 #include "object.h" 5   6 class Cube : public Object 7 { 8 public: 9   Cube(dWorldID world,dSpaceID space,dReal width,dReal height,dReal depth,dReal mass); 10   unsigned char color[3]; 11 protected: 12   virtual void renderInLocalFrame() const; 13 }; 14   15   16 #endif // CUBE_H 17

tutorial1/C/cube.cpp 1 #include "cube.h" 2 #include <GL/glut.h> 3   4 using namespace std; 5   6 Cube::Cube(dWorldID world,dSpaceID space,dReal width,dReal height,dReal depth,dReal mass) 7 { 8   body = dBodyCreate(world); 9   geom = dCreateBox(space,width,height,depth); 10   11   dMass m; 12   dMassSetBox(&m,1.0f,width,height,depth);    13   dMassAdjust(&m,mass);   14   dBodySetMass(body,&m); 15   16   dGeomSetBody(geom,body);  17 } 18 void Cube::renderInLocalFrame() const 19 { 20   dVector3 lengths; 21   dGeomBoxGetLengths(geom,lengths); 22   glScalef(lengths[0],lengths[1],lengths[2]); 23   glColor3ubv(color); 24   glutSolidCube(1.0f); 25 } 26

Bounding box

As we said earlier, the QGLViewer needs to know the size of the world to correclty setup the camera for rendering. Here is a helper function that takes a vector of objects and compute their axis aligned bounding box.

Note that the foreach is a Qt helper construction, very handy. If you are adapting this code to be Qt independent, just use a for loop.

Plane rendering

Finally, we need a little helper function to render an infinite plane, such as the ground plane.

The full monthy

Viewer

We create our Viewer class that extends the QGLViewer. We make the world and space be private members. We also add members for storing objects, and additional static collision geoms. Here we will just use planes.

In the constructor, we create the world, space, objects and static planes.

In the destructor, we clean up everything. Note that world and space take care of deleting the bodies and geoms create inside them. The qDeleteAll() is a handy Qt algorithm: it calls delete on each element of the container.

For the viewer initialization, we use the computed bounding box to set up scene center and radius. We stick the center to the ground plane because it feels more natural for the trackball. We also setup OpenGL lighting.

Finally, the drawing just traverses the objects and planes to render them.

Simulation

For the simulation, we must be carreful with time management. Between two QGLViewer::animate() calls, a certain amount of time has elapsed. Naively, we would advance the world time of that amount. But because ODE uses a numerical integration of the underlying differential equation, we cannot make big steps, or the simulation will be innacurate, or even worse, unstable. So instead, we make "enough" small steps to cover the time delta. For measuring the elapsed time between two successive calls, we use the handy Qt class QTime, of which we store an occurence _time in the viewer.

Since the use can toggle the animation (by pressing the Return key), we need to "start" this time in the QGLViewe::startAnimation() function. Then, at the end of QGLViewer::animate(), we restart it, so that next time we are in animate(), the value _time.elapsed() is what we want.

Collision handling

The last thing we need to do is to handle collision. The way ODE does it (in a nutshell, collision detection can be managed manually completely) is by calling dSpaceCollide. This function finds all collision between geoms of the space, and invoke a callback function on each pair of colliding geoms. Callbacks must be "global" functions. But the callback will need to access world and space, which are private members of the viewer. Luckily, the callback accept a void * data pointer, so we can pass a pointer to the viewer. We add the following public method to the viewer.

Then, we define the callback as a global function local to the viewer.cpp file.

Now we can invoke the collision detection prior to doing small step in the world simulation.

The next thing is to create a joint group to hold temporary joints. Remember that we said that ODE handles collision by creating temporary, local joints that "repulses" colliding objects. We add a private member to the viewer:

We create this member in the constructor.

And in the simulation loop, we empty this group after every step.

The last thing we have to do is to implement handleCollisionBetween(). We borrow the code and comments of another tutorial on the web.

Now we set the joint properties of each contact. Going into the full details here would require a tutorial of its own. I'll just say that the members of the dContact structure control the joint behaviour, such as friction, velocity and bounciness. See section 7.3.7 of the ODE manual and have fun experimenting to learn more.

Here we do the actual collision test by calling dCollide. It returns the number of actual contact points or zero if there were none. As well as the geom IDs, max number of contacts we also pass the address of a dContactGeom as the fourth parameter. dContactGeom is a substructure of a dContact object so we simply pass the address of the first dContactGeom from our array of dContact objects and then pass the offset to the next dContactGeom as the fifth paramater, which is the size of a dContact structure.

Collision handling

That's it, we can run the program and we will see a single cube falling on the ground.

Going further

Now we have a skeleton to play with. For example, we can now add more cubes and a second plane to our scene.

Running the simulation is a bit slower, but here is the result.

From now, it is probably time to read the ODE manual in more details. I suggest in particular the following sections.

• ODE Manual 11.0.0: How To Make Good Simulations

Last modified on Wednesday December 20th, 2006 any comment © Artis 2005