Introduction

This software allows to build 3D simulated environments and robots using Bullet physics library for physics simulation and OpenGL for rendering. The library contains the CENSEngine class that is able to automatize the rendering of objects created through the physics engine. Moreover the CENSSerializedEngine::loadBulletFile method contained in CENSSerializedEngine derived from CENSEngine completely automatize the creation of btRigidBody and btHingeConstraint objects and their usage. Objects and constraints can be designed in a visual mode using Blender and then imported into CENSLIB through the method CENSSerializedEngine::loadBulletFile. By this mean writing bullet code directly can also be avoided.

The project start code is the DemoApplication class present in the Demos/OpenGL folder in the Bullet physics library package. The idea of this library was born from the need to have a cleaner code to allow users to bypass all graphics rendering issues and focus on the bullet code.

Installation

The CENSLIB library is meant to be used on a linux platform. It depends on bullet library and OpenGL. Other needed libraries are the Eigen2 linear algebra library, used for data manipulation within the graphics module, the Magick++ library used to manipulate screenshots of simulations as pixmaps and boost libraries used for regular expressions and file management.

On a debian distribution install these packages through this command:

sudo apt-get install libgl1-mesa-dev libglu1-mesa-dev freeglut3-dev \
       libmagick++-dev libeigen2-dev libboost-regex-dev \
       libboost-system-dev libboost-filesystem-dev libxmu-dev libxi-dev

Then install bullet 2.82 release. On a terminal:

svn checkout http://bullet.googlecode.com/svn/tags/bullet-2.82/ bullet
cd bullet; mkdir cmake_build; cd cmake_build
cmake  .. -DBUILD_SHARED_LIBS=ON -DBUILD_EXTRAS=ON -DINSTALL_LIBS=ON -DINSTALL_EXTRA_LIBS=ON
make -j4
sudo make install

Now download the latest CENSLIB version from here, untar, build and install it:

tar xzvf censlib-<release-number>.tar.gz
cd CENSLIB

and you can build it using cmake :

mkdir build; cd build
cmake ..
make -j4
sudo make install

or the Autotools:

mkdir build; cd build
../configure
make -j4 
sudo make install

Usage

The following command Compiles and links an example.cpp source file:

c++ -O2 -o example example.cpp \
   -I/usr/local/include/CENS \
   -I/usr/local/include/bullet -I/usr/include/eigen2 \
   -I/usr/include/ImageMagick \
   -lCENS-1.1 \
   -lBulletWorldImporter -lBulletFileLoader \
   -lBulletSoftBody -lBulletDynamics \
   -lBulletCollision -lLinearMath \
   -lboost_regex -lboost_system -lboost_filesystem\
   -lGL -lGLU -lglut \
   -lMagick++

Getting started

Building a simple program

In a typical simulation using CENSLIB a new class is derived from CENSEngine:

#include "cens_engine.h"
using namespace cens;
class MyEngine : public CENSEngine 
{   
    public:   
        // overloadings
        void initObjects();
        void step( int step_interval);
};

Two methods must be overloaded. One of them is CENSEngine::initObjects where you write bullet code about the initialization of your objects and constraints :

void MyEngine::initObjects()
{
    // YOUR BULLET CODE
    // for instance we build a simple cube:
    
    // a box shape
    btCollisionShape* shape = 
        new btBoxShape( btVector3(1,1,1) ); 
    // a transform centered on the origin
    btTransform transform;
    transform.setIdentity();
    // the mass of the object
    double mass = 1.0;
    // let's build the object!
    btRigidBody *body =  
        localCreateRigidBody(
                mass, transform, shape);
}

Note how the building of a btRigidBody is simplified by the use of the method CENSEngine::localCreateRigidBody, which automatically build and attach a btRigidBody to the world starting from a shape, a transform and a mass value.

The other method to overload is CENSEngine::step. You can write here your bullet code for applying forces at each timestep:

void MyEngine::step(int step_interval)
{
    // YOUR BULLET CODE
    CENSEngine::step(timestep);
}

the call to CENSEngine::step must always be at the end of your overloaded step method, otherwise the simulation does not start.

Once you built your class derived from CENSEngine you only need to define an object of that type and call its CENSEngine::init and CENSEngine::run methods in the main function:

int main(int argc, char** argv) 
{
    MyEngine engine;
    engine.init(argc,argv);
    
    engine.run();
    return 0;
}

When the program runs the first time two files are searched for in the ./parameters directory, one called "physics_parameters", the other called "graphics_parameters". They contain the values of graphics and physics parameters respectiivelly. Both can bechanged offline before starting a simulation. if those files do not exist they are created with default values:

graphics_parameters

   800             ------- SCREEN_WIDTH      <- pixel width of the window
   600             ------- SCREEN_HEIGHT     <- pixel height of the window
   10              ------- SCREEN_XGAP       <- horizontal position of the window
   10              ------- SCREEN_YGAP       <- vertical position of the window
   10              ------- TIMESTEP          <- time interval of a single timestep (milliseconds)
   Demo            ------- SCREEN_TITLE      <- title of the window
   70              ------- FIELD_OF_VIEW     <- the angle (degrees) defining the width of the FoV
   1.2             ------- RATIO             <- ratio between horizontal/vertical FoV angle
   1               ------- NEAR              <- near plane of view
   10000           ------- FAR               <- far plane of view
   0.15            ------- ANGLE             <- from where the camera points to the target
   15              ------- DISTANCE          <- distance of the camera from the origin
   15              ------- HEIGHT            <- height of the camera with respect to the origin
   0;0;1           ------- TARGET            <- the center of the scene 
   0;0;1           ------- UP                <- direction of the UP vector
   0.1             ------- MOV               <- right-left increment when moving the scene
   0.1             ------- GAP               <- bottom-up increment when moving the scene
   0.1;0.1;0       ------- ENV_COLOR         <- background color
   0.6;0.2;0.2     ------- GROUND_COLOR      <- floor color
   0.2;0.6;0.2     ------- OBJECT_COLOR      <- generic object color 
   0.2;0.2;0.0     ------- BOX_COLOR         <- box color
   0.4;0.4;0.6     ------- CAPSULE_COLOR     <- capsule color
   0.7;0.1;0.7     ------- SPHERE_COLOR      <- sphere color
   0.2;0.6;0.2     ------- COMPOUND_COLOR    <- color of a compound object
   0;0.6;0.6       ------- SOFT_COLOR        <- color of a soft body
   0.5;.5;0.2;1    ------- LIGHT_AMBIENT     <- lights - ambient light color
   1;1;1;1         ------- LIGHT_DIFFUSE     <- lights - diffuse light color
   1;1;1;1         ------- LIGHT_SPECULAR    <- lights -specular light color
   10;10;10;1      ------- LIGHT_POSITION0   <- light0 position
   10;10;10;0      ------- LIGHT_POSITION1   <- light1 position

physics_parameters

   0;0;-9.8        ------- GRAVITY           <- a vector defining gravity amplitude and direction
   0.05            ------- STEP              <- integration step for physics
   20              ------- SUBSTEP           <- number of real teps if timestep is too long

Examples

These are some examples of how to implement the main features:

Joints

derive an Engine from CENSEngine:

 #ifndef ENGINE_H
 #define ENGINE_H
 
 #include "cens_engine.h"
 
 using namespace cens;
 
 class Engine : public CENSEngine {
 
   public:
 
     Engine():time_counter(0) {}
 
     void initObjects();
     void step( int timestep);
 
   private:
     btRigidBody *body;
     int time_counter;
 
 };
 
 #endif // ENGINE_H

Implement the overloading of CENSEngine::initObjects and CENSEngine::step

 #include "engine.h"
 
 void Engine::initObjects() {
 
     // Initialize a sphere and add an hinge attached    //
     // to the world .                                   //     
     // On runtime a force is applied to the sphere.     //
     // As a result the sphere rotates around the hinge. //
      
     
     // initializing a sphere
     btCollisionShape* spShape =  
         new btSphereShape(
                 btScalar(2.) ); 
     btTransform spTransform;
     spTransform.setIdentity();
     spTransform.setOrigin(btVector3(4,4,2)); 
     spTransform.setRotation(btQuaternion(0,0,0));
     body = 
         localCreateRigidBody(
                 btScalar(1), 
                 spTransform, 
                 spShape,
                 btVector3(.6,.6,.8) );
 
     
     //initializing a joint.
     // set the ransform information for a joint: 
     btTransform jointTransform;
     jointTransform.setIdentity();
 
     // translation: the point in the solid body that is 
     //              constrained to the hinge. Coordinates are local,
     //              relative to the body.
     jointTransform.setOrigin( btVector3(-4, -4, 0)); 
 
     // rotation:    which axis the plane of the hinge constraint 
     //              will rotate on and how much it will rotate.
     jointTransform.setRotation(
             btQuaternion(
                 btVector3(0,0,1), // axis
                 0)); // angle
 
     // build the joint. Giving a single body 
     // and a single transform is enough to tell bullet 
     // to use the world as the other body.
     btHingeConstraint *constraint =  new btHingeConstraint(
             *body,
             jointTransform);
 
     // add the joint to the world
     // (argument true means they can compenetrate!) 
     m_phDynamicsWorld->addConstraint(constraint,true);
 
     toggleTexture();
     toggleObjectAxes();
     toggleJointAxes();
 }
 
 
 
 void Engine::step( int timestep ) 
 {
 
     // A force is applied to the sphere.
     float force = 50;
     body->applyCentralForce(
             body->getWorldTransform() *   // body center of mass
             (btVector3(.1,0,0) * force) ); // direction of force
     // initialize a counter to know in 
     // which part of the simulation we are
     time_counter++;
 
     // This call should always be here. 
     // Without it bullet and graphics steps 
     // are not called, and the loop of 
     // simulation doesn't go on.
     CENSEngine::step(timestep);
 
 }
 

Soft bodies

derive an Engine from CENSEngine:

 #ifndef ENGINE_H
 #define ENGINE_H
 
 #include "cens_engine.h"
 
 using namespace cens;
 
 
 class Engine : public CENSEngine {   
     public:   
         Engine():time_counter(0) {}
         void initObjects();
         void step( int timestep);
     private: 
         btRigidBody* body; // a rigid body
         int time_counter; // a counter of the simulation steps
 };
 
 #endif //ENGINE_H
 

Implement the overloading of CENSEngine::initObjects and CENSEngine::step

 #include "engine.h"
 
 using namespace cens;
 
 
 
 // Define the initObjects function
 // in which we initialize the rigid body
 // as a box
 void Engine::initObjects() {
 
     // A SPHERE
     // Create a Sphere shape 
     // with radius 2
     btCollisionShape* spShape =  
         new btSphereShape(
                 btScalar(2.) );
 
     // Create a transform
     btTransform spTransform;
     // Initialize the transform to (0,3,8), 
     // with no rotation
     spTransform.setIdentity();
     spTransform.setOrigin(btVector3(0,0,8)); 
     spTransform.setRotation(btQuaternion(0,0,0));
 
     // Create the soft body giving mass and shape.
     btSoftBody *softSphere =localCreateSoftBody(
             btScalar(10), 
             spShape); 
     // give the sphere the righttransform
     softSphere->transform( spTransform );
 
     // Linear stiffness [0,1]
     softSphere->m_materials[0]->m_kLST   =   0.1f;  
     // Area/angular stiffness [0,1]
     softSphere->m_materials[0]->m_kAST   =   0.1f; 
     // volume stiffness [0,1]
     softSphere->m_materials[0]->m_kVST   =   0.1f;
 
     softSphere->setPose( true, false );
     softSphere->generateBendingConstraints(3);
 
 
     // Create a 10x10x10 box shape 
     // ( giving the half-extents of dimensions ) 
     btCollisionShape* shape = 
         new btBoxShape( btVector3(15,15,2) );   
 
     // Create a transform
     btTransform transform;
 
     // Initialize the transform to the origin, 
     // with no rotation
     transform.setIdentity();
     transform.setOrigin(btVector3(0,0,0));
 
     // Create the body giving mass, shape and transform.
     body = 
         localCreateRigidBody(
                 0.0, // mass
                 transform, // transform 
                 shape); // shape
 }
 
 // Finally, define the step function
 // in which we apply a force to the box
 // for the first 10 steps of the simulation
 void Engine::step( int timestep ) 
 {
 
     // applying a force on the body
 
     // thetransform of the body
     btTransform &aBodyTransform = body->getWorldTransform();
     // the direction of the force
     btVector3 direction = btVector3(.5,.5,1);
     // the magnitude of the force
     float force = 20;
 
     // applying the force
     if (time_counter<10)
         body->applyCentralForce(
                 // multiplying the direction times the transform
                 // the local reference to the object is mantained
                 aBodyTransform * direction * force );
 
     // if more tha 200 steps are been run
     // end the simulation 
     if( time_counter > 200 )
         quit();
 
     // update a counter to know in 
     // which part of the simulation we are
     time_counter++;
 
     // This call should always be here. 
     // Without it bullet and graphics steps 
     // are not called, and the loop of 
     // simulation doesn't go on.
     CENSEngine::step(timestep);
 
 }
 

Importing a bullet file

derive an Engine from CENSSerializedEngine:

 #ifndef ENGINE_H
 #define ENGINE_H
 
 #include "cens_serialized_engine.h"
 
 using namespace cens;
 
 
 // First, declare a CENSEngine derived class
 class Engine : public CENSSerializedEngine {   
     public:   
         void initObjects();
         void step( int timestep);
         
 };
 
 #endif //ENGINE_H
 

Now the overloading of CENSEngine::initObjects and CENSEngine::step is very simple. Just call loadBulletFile:

 #include "engine.h"
 
 using namespace cens;
 
 
 // Then define the initObjects function
 // in which we initialize the rigid body
 // as a box
 void Engine::initObjects() {
    
     // Simply import all objects form a *.bullet file
     m_eRobots["robot_test"]=loadBulletFile("robot_test","test.bullet");
 }
 
 // Finally, define the step function
 // in which we apply a force to the box
 // for the first 10 steps of the simulation
 void Engine::step( int timestep ) 
 {
     // This call should always be here. 
     // Without it bullet and graphics steps 
     // are not called, and the loop of 
     // simulation doesn't go on.
     CENSEngine::step(timestep);
 
 }
 

Controlling motors on an imported joint

derive an Engine from CENSSerializedEngine:

 #ifndef ENGINE_H
 #define ENGINE_H
 
 #include "cens_serialized_engine.h"
 
 using namespace cens;
 
 
 // First, declare a CENSEngine derived class
 class Engine : public CENSSerializedEngine {   
     public:   
         Engine():timecounter(0) {}
         void initObjects();
         void step( int timestep);
 
         int timecounter;
 };
 
 #endif //ENGINE_H
 

Within CENSEngine::initObjects call loadBulletFile, while within CENSEngine::step call the method CENSSerializedRobot::move on the acquired CENSSerializedRobot object, indicating one of the loaded hinges:

 #include "engine.h"
 
 using namespace cens;
 
 
 // Then define the initObjects function
 // in which we initialize the rigid body
 // as a box
 void Engine::initObjects() {
    
     // Simply import all objects form a .bullet file
     m_eRobots["robot_test"] = loadBulletFile("robot_test","test.bullet");
     
     // Object3 is a touch sensor
     addTouchSensor(m_eBodies["Object3"],"Object3");
     
     // Object3 is red
     m_eShapes[m_eBodies["Object3"]]->setColor(Vector3f(1,0,0));
    
     toggleTexture();
     toggleJointAxes();
 }
 
 // Finally, define the step function
 // in which we apply a force to the box
 // for the first 10 steps of the simulation
 void Engine::step( int timestep ) 
 {
  
    
     static double angle = 0; 
     static double impulse = 1; 
     angle -= M_PI/100.;
    
 
     //saveCameraPixelMap(0, timecounter,"png");
 
     // if Object3 touches something
     if(m_eSensors["Object3"]->isTouched())
     {     
         // go backward 
         angle += M_PI/10.;
         
         // std::cout <<  
             // impulse << " " <<
             // m_eSensors["Object3"]->getPressure() << std::endl;
          
         // higher impulse
         impulse += .01;
 
     } 
 
     m_eRobots["robot_test"]->move("Object2_to_Object1", angle, impulse);
     m_eRobots["robot_test"]->move("Object3_to_Object2", angle, impulse);
     
     // if(timecounter>200)
         // exit(0);
 
     timecounter++;
 
     // This call should always be here. 
     // Without it bullet and graphics steps 
     // are not called, and the loop of 
     // simulation doesn't go on.
     CENSSerializedEngine::step(timestep);
 
 }
 
 

Cameras

derive an Engine from CENSSerializedEngine

 #ifndef ENGINE_H
 #define ENGINE_H
 
 #include "cens_serialized_engine.h"
 
 using namespace cens;
 
 class Engine : public CENSSerializedEngine {
 
   public:
 
     void initObjects();
     void step( int timestep);
 
 };
 
 #endif // ENGINE_H

Implement the overloading of CENSSerializedEngine::initObjects and CENSSerializedEngine::step

 #include "engine.h"
 
 void Engine::initObjects() {
     
     // Simply import all objects form a .bullet file
     m_eRobots["robot_test"] = 
         loadBulletFile("robot_test","test.bullet");
 
     btTransform local;
     local.setOrigin(btVector3(0,0,-1));
     local.setRotation(btQuaternion(M_PI/2.,0,0));
 
     addCamera( 
             "SphereCamera",
             m_eBodies["Sphere"], // pointer to the attached body 
             local,  // local transform relative to the attached body 
             "Sphere_EYE", // name of the camera 
             480,400, // dimensions of the camera window (pixels)
             800,50, // position of the camera window on the screen (pixels) 
             btVector3(0,0,1),  // UP vector of the camera
             10, // target distance
             100,
             .00001); 
 
     toggleTexture();
     toggleCameraAxis();
 }
 
 void Engine::step( int timestep ) 
 {
 
     // This call should always be here. 
     // Without it bullet and graphics steps 
     // are not called, and the loop of 
     // simulation doesn't go on.
     CENSEngine::step(timestep);
 }
 

CENSLIB - Computational Embodied Neuroscience Simulation Library

Table of Contents