VTK/3DConnexion Devices Support

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

THIS IS EXPERIMENTAL WORK

Implementation

• Implementation Work Sheet

Date of Implementation

• 2009/08/21: experimental work (Linux and Windows)
• 2009/09/10: Qt on Windows, vtkTDxInteractorStyle(s), vtkTDxInteractorStyleSettings

TODO

• Support for Qt on Linux
• Support for Mac

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)
• Linux with Qt: not yet
• Windows: yes (tested with Windows Vista Ultimate SP2 64-bit, Visual Studio 9 SP1, with a 3DConnexion SpaceNavigator)
• Windows with Qt: yes
• Mac: not yet
• Mac with Qt: not 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.

Mac OS

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

You can use the device with a vtkRenderWindowInteractor (1a) or a QVTKWidget (1b).

• Look at VTK/Rendering/Testing/Cxx/TestTDx.cxx for a sample code using a regular vtkRenderWindowInteractor.
• Look at VTK/Examples/GUI/Qt/Events/GUI4.cxx for a sample code using a QVTKWidget. To compile it, you have to enable BUILD_EXAMPLES, VTK_USE_QT, VTK_USE_GUISUPPORT, VTK_USE_QVTK_QOPENGL and set DESIRED_QT_VERSION to 4 in cmake. On Windows in debug mode, the executable is qtevents.exe in $BUILD/bin/Debug

1a. 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);

1b. Once the QVTKWidget is created, and before a vtkRenderWindow is assigned to it, tell it to listen to listen to the device, when the event loop starts:

qVTK1->SetUseTDx(true);
qVTK1->SetRenderWindow(renwin);

You can do step 2a or 2b or both:

2a. Basic event-driven mechanism

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 a translation (X,Y,Z) and a rotation, represented by an angle and an axis (a unit vector). Tip: use VTK/Common/vtkTransform::RotateWXYZ() to convert an angle-axis representation to an orthogonal matrix representation of a rotation.
2. vtkCommand::TDxButtonPressEvent, is invoked when a button is pressed. the callData is a pointer to a int, which is the number of the button.
3. vtkCommand::TDxButtonReleaseEvent, is invoked when a button is released. the callData is a pointer to a int, which is the number of the button.

2b. Use or write a concrete subclass of vtkTDxInteractorStyle

Initially, the vtkInteractorStyle attached to the vtkRenderWindowInteractor delegates the processing of the TDx*Events to a vtkTDxInteractorStyleCamera. It means that, by default, the 3DConnexion device controls camera motions. You can access the vtkTDxInteractorStyle attached to the vtkInteractorStyle with GetTDxStyle() and SetTDxStyle().

In addition, you can change the sensitivity settings and axe motion filtering/masking of the 3DConnexion device for a vtkTDxInteractorStyle with the vtkTDxInteractorStyleSettings object attached to it. You can share the same settings between different vtkTDxInteractorStyles. Here is the code sample from VTK/Rendering/Testing/Cxx/TestTDx.cxx that demonstrates how to set the sensitivity parameters:

  const double angleSensitivity=0.02;
  const double translationSensitivity=0.001;

  vtkRenderWindowInteractor *iren;
[...]
  vtkInteractorStyle *s=
    static_cast<vtkInteractorStyle *>(iren->GetInteractorStyle());
  vtkTDxInteractorStyleCamera *t=
    static_cast<vtkTDxInteractorStyleCamera *>(s->GetTDxStyle());
  
  t->GetSettings()->SetAngleSensitivity(angleSensitivity);
  t->GetSettings()->SetTranslationXSensitivity(translationSensitivity);
  t->GetSettings()->SetTranslationYSensitivity(translationSensitivity);
  t->GetSettings()->SetTranslationZSensitivity(translationSensitivity);

Note these settings are programmable and are applied on the input coming from the device. Therefore, they come after the device driver sensitivity and masking settings.