HOW TO USE HAPTIC DEVICE IN SOFA
Gurvan Le Moigno - 2008

Abstract

This HOW-TO is targeted to the SOFA user who wants to use an haptic device in SOFA scenes. You need to have some experiences with SOFA. This document contains some pre-requisite to run the code, an explanation of how it works and, finaly, some code examples to integrate the Haptic Device in your own scenes.

Pre-requisite / First launch

This SOFA module use the Chai3D library to abstract haptic devices low-level interface.

Interaction between SOFA & Chai3D

For the moment, only SensAble PHANToM device have been tested, with the SensAble OpenHaptics toolkit. But we expect that all Chai3D compatible device works with our implementaton.

So let's start. You need to install the device driver and the openhaptis toolkit. Run the test and some example to be sure all is OK.
for linux user, be sure that openhaptics library (HD, HDU, HL, HLU) are installed in /usr/lib directory
for windows user, be sure that the 3DTOUCH_BASE environment variable is created and specify your openhaptic home dir.


Next, you need to download the chai3d_dependencies.zip file from the "Fichiers" tab of the Sofa Dev Gforge page and uncompress it in your Sofa root directory.
It copy several files :
extlibs/CHAI3D                                       -- contains all the Chai3D include file
bin/phantomHD.dll                                   -- chai3D needs this dll to initialize the phantom
lib/linux/libchai3d_linux.a                          --  pre-compiled version of chai3D library for linux 
lib/win32/Common/chai3d_complete.lib   -- pre-compiled version of chai3D library for windows
lib/win32/Common/chai3d_completed.lib   -- pre-compiled debug version of chai3D library for windows


If you use other device, recompile chai3D and replace the folowing files :
- $SOFA_DIR$/lib/linux/libchai3d_linux.a  for linux
- $SOFA_DIR$/lib/win32/Common/chai3d_complete.lib    for windows


Move into the SOFA directory and copy sofa-default.cfg in sofa-local.cfg. Open sofa-local.cfg and uncomment the line:
DEFINES += SOFA_HAVE_CHAI3D

Execute qmake and compile SOFA. A new executable named Haptic has been built in the bin directory. Run it and open the liver-haptic.scn scene in the scenes directory.

Launch the animation and start playing with the liver. You should see this interface with a little yellow ball following your device moves:

ScreenShot With Device

How it works

There are two main classes : HapticDevice and HapticMapping.

HapticDevice is used as a link between Chai3D and SOFA. It contains a reference to the device and the haptic loop.

HapticMapping is a specialized RigidRigidMapping. In fact, whereas a classic mapping takes two SOFA objects as input and output models, the HapticMapping only takes an output model and replaces the input by a HapticDevice object.

Mapping explanation

At every step of the simulation, the apply() method of each mapping is called. In our HapticMapping, the apply() method gets the real device position, converts it into the SOFA scene axes * and gives this new position to the output SOFA object. So if we use a rigid mechanical object  as output of the HapticMapping, this object follows the position of the physical haptic device.

* In fact, we want that the sofa object representing the device moves in a special coordinate system fixed in front of the camera. The rotation and translation of the SOFA simulation scene modifies the device position for the user.

Code Examples

You have two ways to integrate the HapticMapping in your scene graph. You can insert it directly in your scene xml file, or you can launch a scene and add the haptic node dynamicaly.

External add

Here is an example of a graph that you can add in every scene to add a little collision sphere following your device moves:

Haptic node details








Explanations :

The Mechanical Object contains a moving frame representing the device.
The HapticMapping maps the mechanical object above from the HapticDevice (hidden for the SOFA graph scene)
The collision model of the device is a simple small sphere.
The collision mapping links the sphere collision model to the moving frame. Note that you can you use any other CollisionModel to represent the shape of the device.

the complete code of this scene graph part can be found in scenes/addHaptic.xml

With this scene graph, at every simulation step, the mechanical object takes the position of the device, and the sphere collision model follows it thanks to the collision mapping.

In theory, you can connect what you want with the HapticMapping. The only restrictions are :
- The HapticMapping must have a MechanicalObject<Rigid3*Types> (Rigid3dTypes or Rigid3fTypes) sibling.
- The Haptic Device node must be under a solver.

Warning : You need to start the animation to see the visual model of the sphere.

Xml Scene add


Let's see how the HapticMapping is included in a scene file :

<Object type="HapticMapping" template="Rigid3dTypes">
        <Attribute type="name">
            <Data value="Haptic Mapping"/>
        </Attribute>
        <Attribute type="openGlInitialized">
            <Data value="1"/>
        </Attribute>
</Object>

The two important elements are :
- The template of the SOFA output model : can be Rigid3dTypes or Rigid3fTypes
- The boolean data openGlInitialized. By default, it's false and it change to true when openGl is initialized. If we add the node after loading a scene, openGL is already initialized and we have to specify the true (1) value. In summary, if you launch a scene wich contains a haptic device at the begining, you can omit or put this value to false. If you use a part of scene graph that you load after the scene, you need to put this value to true (as in the addHaptics.xml example).

Future Works

The next step is to compute feedback to feel as best as possible the collision under the device and all the SOFA objects of the scene.
Fix this bug : Chai3D can't initialize twice a scene with an haptic device.