VTK/3DConnexion Devices Support

Support for 3DConnexion Devices (SpaceNavigator, SpacePilot) inside VTK

THIS IS EXPERIMENTAL WORK

Naming convention

We pick the name TDx to refer to classes or types to support 3DConnexion Devices. "T" stands for "Three", "x" stands for "connexion". Why? because 3DConnexion calls its software 3DxWare but we cannot have types and classes starting with a number in C++, so we chose "T" instead of "3".

Supported Platform

• Linux: yes (tested with Ubuntu GNU/Linux 9.04 x86_64, gcc, with a 3DConnexion SpaceNavigator)
• Windows: yes (tested with Windows Vista Ultimate SP2 64-bit, Visual Studio 9 SP1, with a 3DConnexion SpaceNavigator)
• Mac: no yet

How to use it

Install the 3DConnexion Device driver

Linux

Download

• Download the driver from the 3DConnexion wesbite: http://www.3dconnexion.com/support/downloads.php
  • Select the product, (example SpaceNavigator SE),
  • select the OS (Linux),
  • select the driver file for the architecture (3DxWare for Linux (i386) for 32-bit, 3DxWare for Linux (x86_64) for 64-bit )

For example, for Linux 64-bit, we will get the 3 following files:

• 3dxware-linux-v1-4-3.x86_64.tar.gz,
• InstallationInstructions_Linux.txt,
• Release_Notes-All_Platforms-20090806.pdf

Install required packages

On Ubuntu, install package libmotif3. The GUI of the 3DConnexion device driver uses it.

Install the driver

As root, (from InstallationInstructions_Linux.txt):

1. $ cd /tmp
2. tar xzvf path/to/3dxware-linux-v1-4-3.x86_64.tar.gz
3. ./install-3dxunix.sh

Then, you have to change to permissions of the installed files manually (ref [forum thread]) in /etc/3DxWare:

sudo chmod go+rx /etc/3DxWare
sudo chmod go+r /etc/3DxWare/*.scg 

Test the driver

Launch the daemon (with sudo):

sudo /etc/3DxWare/daemon/3dxsrv -d usb 

The GUI is created but not on top of the desktop. Check for a 3DxWare window on your desktop.

If you forgot to change permissions of the installed files, we will have this error message:

$ sudo /etc/3DxWare/daemon/3dxsrv -d usb
3DxWareUNIX = V1.4.3
Device      = SpaceNavigator
Firmware    = V3.18
[2009-08-19 12:01:28] Error: Can't find any configuration files! Please reinstall you configurations in /etc/3DxWare properly!

For testing/disgnostic purpose (for fun too), launch of one the programs provided in the archive (uncompressed in /tmp for the first step):

$ /tmp/xcube
$ /tmp/xvalue

Windows

Easy. Nothing to add about it.

Install the 3DConnexion SDK

Linux

• Go the the 3DConnexion SDK webpage: http://www.3dconnexion.com/support/sdk.php
• Register, accept the license
• Download xdevelop.tgz
• Uncompress xdevelop.tgz wherever you want

$ tar xzvf xdevelop.tgz

• Prepare a Makefile for Linux from makefile.dec:
• a. cp makefile.dec makefile.linux
• b. edit makefile.linux and remove occurrences of -DDEC and -fullwarn . Add a -fPIC option to the build object section. Add a section to build a static library. To sum up, you end up with a makefile.linux file like (the big spaces at the beginning of lines are tabs, they must be tabs, not spaces):

all:            xapp xdrvlib.a
                ls -al xapp

xdrvlib.o:      xdrvlib.c xdrvlib.h
                gcc xdrvlib.c -c -fPIC

xdrvlib.a:      xdrvlib.o
                ar rcs xdrvlib.a xdrvlib.o

xapp:           xapp.c xdrvlib.o
                gcc xapp.c xdrvlib.o -o xapp -lX11 -lm

• Build the static library:

# 3. make -f makefile.linux

the result of the build is xdrvlib.a. There is also an application xapp.

At this point, for testing/diagnostic purpose, you can try to launch xapp.

Windows

Easy. There is nothing more to install.

(This is because The Windows SDK (TDxInput.dll) installs when you install 3DxSoftware. You can find TDxInput.dll in ..\Program Files\3Dconnexion\3Dconnexion 3DxSoftware\3DxWare\win32 or \win64. )

Configure VTK

Launch cmake and set the advanced option VTK_USE_TDx to TRUE

Linux

Set the advanced variables:

• VTK_TDX_INCLUDE_PATH to point to the path of xdrvlib.h (without mentioning xdrvlib.h)
• VTK_TDX_OBJECT_PATH to the full path to xdrvlib.a (mentioning xdrvlib.a)

Windows

Easy. There is nothing else to set.

Build VTK

Just build vtk.

Test it

Launch TestTDx in interactive mode 1. Get the full command line of the test with:

$ ctest -R TestTDx -V -N

2. Copy the full command line in the prompt and add -I at the end, to run the test in interactive mode

3. Enjoy

How to program it

Look at VTK/Rendering/Testing/Cxx/TestTDx.cxx for a sample code.

1. Once the vtkRenderWindowInteractor is created, tell it to listen to the device, when the event loop starts (must be called before the first render).

vtkRenderWindowInteractor *i=vtkRenderWindowInteractor::New();
i->SetUseTDx(true);

2. Add an observer to watch for a TDx event:

vtkCommand *c;
[...]
i->AddObserver(vtkCommand::TDxMotionEvent,c,0);

There are 3 types of events (defined in VTK/Common/vtkCommand.h), they all return some callData:

1. vtkCommand::TDxMotionEvent, is invoked when the ball or knob is actived. the callData is a pointer to a vtkTDxMotionEventInfo (defined in VTK/Rendering). This

structure stores information about the delta in translation (X,Y,Z) and in rotation (A,B,C)

1. vtkCommand::TDxButtonPressEvent, is invoked when a button is pressed. the callData is a pointer to a int, which is the number of the button.
2. vtkCommand::TDxButtonReleaseEvent, is invoked when a button is released. the callData is a pointer to a int, which is the number of the button.