VTK/3DConnexion Devices Support

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

Implementation

• Implementation Work Sheet

Date of Implementation

• 2009/08/21: experimental work (Linux and Windows)
• 2009/09/10: Qt on Windows, vtkTDxInteractorStyle(s), vtkTDxInteractorStyleSettings
• 2010/01/12: Support for Mac (Cocoa and Carbon and Qt)
• 2010/05/25: Support for Linux with Qt
• 2010/05/28: Added a CMakeLists.txt file to the wiki to build the 3DConnexion SDK for Linux.
• Implemented by (any question to) François Bertel.

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: yes
• Windows: yes (tested with Windows Vista Ultimate SP2 64-bit, Visual Studio 9 SP1, with a 3DConnexion SpaceNavigator)
• Windows with Qt: yes
• Mac: yes (tested with Mac OS X 10.6.2 (Snow Leopard) on an mid-2009 Apple MacBook Pro (MacBookPro5,3), with a 3DConnexion SpaceNavigator. Tested with Mac OS X 10.4.11 (Tiger) on a early-2006 Intel Apple iMac (iMac4,1) with a 3DConnexion SpaceNavigator.)
• Mac with Qt: yes

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 during the first step):

$ /tmp/xcube
$ /tmp/xvalue

Note: You must be currently running 3dxsrv from the previous step (in a separate terminal) for xcube and xvalue to work!

Windows

Easy. Nothing to add about it.

Mac OS X

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

• Download the following CMakeLists.txt file File:CMakeLists.txt and save it in the source tree you just uncompressed.
• Build and install the CMake project:
  • It will create a library libxdrvlib.so (by default BUILD_SHARED_LIBS is ON) or libxdrvlib.a
  • It will create an executable xapp (by default BUILD_EXAMPLE is ON)

Create the build tree out of the source tree

$ mkdir tdx-build
$ cd tdx-build
$ ccmake ../source_tree
$ make

Install the SDK:

$ make install

By default, the install prefix is /usr/local. It will install:

/usr/local/bin/xapp
/usr/local/lib/libxdrvlib.so
/usr/local/include/xdrvlib.h

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

If you get an error about "Can't find libxdrvlib.so", you need to add /usr/local/lib to your LD_LIBRARY_PATH in your ~/.bashrc.

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. )

Visual C++ Express Editions

+ If you use any of the Visual C++ Express Editions, then you are missing ATL (Active Template Library) which is only available in the "professional" editions. You will notice that your (express) compiler will complain that it can not find "atlbase.h". Follow these steps to remedy the situation:

1. Install "Microsoft ® Windows Server® 2003 R2 Platform SDK" from here. You only need to install the "core" and "redistributable" components, so choose a custom installation and disable everything but these components. (Neither Windows Server 2008 SDK nor Windows 7 SDK include the ATL headers)

2.1 Find the missing header in, eg, C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include\atl

2.2 You need to comment out line 293 in "atlbase.h", so that it reads:

//#pragma comment(lib, "atlthunk.lib")

3.1 Open up Visual C++ Express and click the "Tools" menu button, then the "Options" command.

3.2 In the left-hand pane, click "Projects and Solutions", then "VC++ Directories"

3.3 In the drop-down menu "Show directories for", choose "Include files"

3.4 Add the location of "atlbase.h" (probably the same as in 2.1 above) to the list of directories.

4 You are ready to compile VTK including the 3DConnexion device support with a VC++ express compiler!

Mac OS X

Easy. There is nothing more to install.

(This is because the 3DxMacWare SDK is installed as part of the 3DxMacWare driver software in /Library/Frameworks/3DconnexionClient.framework. )

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.

Mac OS X

Easy. There is nothing else to set. (cmake should find the 3Dconnexion framework in /Library/Frameworks/3DconnexionClient.framework)

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.