VTK/3DConnexion Devices Support: Difference between revisions

From KitwarePublic
< VTK
Jump to navigationJump to search
m (→‎Visual C++ Express Editions: Update dead link)
 
(62 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Support for 3DConnexion Devices (SpaceNavigator, SpacePilot) inside VTK
Support for 3DConnexion Devices (SpaceNavigator, SpaceExplorer, SpacePilot) inside VTK


<b>THIS IS EXPERIMENTAL WORK</b>
= Implementation =
* [[VTK/3DConnexion Devices Support Implementation Work Sheet | Implementation Work Sheet]]
== Date of Implementation ==
* 2009/08/21: experimental work (Linux and Windows)
* 2009/09/10: Qt on Windows, <tt>vtkTDxInteractorStyle</tt>(s), <tt>vtkTDxInteractorStyleSettings</tt>
* 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 =
= Naming convention =
Line 8: Line 16:
= Supported Platform =
= Supported Platform =
* Linux: yes (tested with Ubuntu GNU/Linux 9.04 x86_64, gcc, with a 3DConnexion SpaceNavigator)
* 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: yes (tested with Windows Vista Ultimate SP2 64-bit, Visual Studio 9 SP1, with a 3DConnexion SpaceNavigator)
* Mac: no yet
* 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=
= How to use it =
== Install the 3DConnexion Device driver ==
== Install the 3DConnexion Device driver ==
=== Linux ===
=== Linux ===
Line 29: Line 40:


==== Install the driver ====
==== Install the driver ====
<b>As root</b>, follow the instructions of InstallationInstructions_Linux.txt. Basically:
<b>As root</b>, (from InstallationInstructions_Linux.txt):
#  
# $ cd /tmp
# tar xzvf 3dxware-linux-v1-4-3.x86_64.tar.gz
# tar xzvf path/to/3dxware-linux-v1-4-3.x86_64.tar.gz
# ./install-3dxunix.sh
# ./install-3dxunix.sh


Line 55: Line 66:
[2009-08-19 12:01:28] Error: Can't find any configuration files! Please reinstall you configurations in /etc/3DxWare properly!
[2009-08-19 12:01:28] Error: Can't find any configuration files! Please reinstall you configurations in /etc/3DxWare properly!
</pre>
</pre>
For testing/disgnostic purpose (for fun too), launch of one the programs provided in the archive (uncompressed in /tmp during the first step):
<pre>
$ /tmp/xcube
$ /tmp/xvalue
</pre>
Note: You must be currently running 3dxsrv from the previous step (in a separate terminal) for xcube and xvalue to work!


=== Windows ===
=== Windows ===
Easy. Nothing to add about it.
Easy. Nothing to add about it.
=== Mac OS X ===
Easy. Nothing to add about it.
== Install the 3DConnexion SDK ==
== Install the 3DConnexion SDK ==
=== Linux ===
=== Linux ===
Line 67: Line 90:
$ tar xzvf xdevelop.tgz
$ tar xzvf xdevelop.tgz
</pre>
</pre>
* Prepare a Makefile for Linux from makefile.dec:
* a. cp makefile.dec makefile.linux
* b. edit makefile.linux and remove occurences of -DDEC and -fullwarn


*Build the static library:
* 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
<pre>
$ mkdir tdx-build
$ cd tdx-build
$ ccmake ../source_tree
$ make
</pre>
Install the SDK:
<pre>
$ make install
</pre>
By default, the install prefix is <tt>/usr/local</tt>. It will install:
<pre>
<pre>
# 3. make -f makefile.linux
/usr/local/bin/xapp
/usr/local/lib/libxdrvlib.so
/usr/local/include/xdrvlib.h
</pre>
</pre>
the result of the build is <b><tt>xdrvlib.a</tt></b>
 
At this point, for testing/diagnostic purpose, you can try to launch <tt>xapp</tt>.
 
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 ===
=== 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 [http://www.microsoft.com/en-us/download/details.aspx?id=6510 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:
<pre>
//#pragma comment(lib, "atlthunk.lib")
</pre>
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.
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. )
(This is because the 3DxMacWare SDK is installed as part of the 3DxMacWare driver software in <tt>/Library/Frameworks/3DconnexionClient.framework</tt>. )


== Configure VTK ==
== Configure VTK ==
Line 90: Line 156:
=== Windows ===
=== Windows ===
Easy. There is nothing else to set.
Easy. There is nothing else to set.
=== Mac OS X ===
Easy. There is nothing else to set. (cmake should find the 3Dconnexion framework in <tt>/Library/Frameworks/3DconnexionClient.framework</tt>)


== Build VTK ==
== Build VTK ==
Line 96: Line 165:
== Test it ==
== Test it ==
Launch TestTDx in interactive mode
Launch TestTDx in interactive mode
1. Get the full command line of the test with:
*1. Get the full command line of the test with:
<pre>
<pre>
$ ctest -R TestTDx -V -N
$ ctest -R TestTDx -V -N
</pre>
</pre>
2. Copy the full command line in the prompt and add -I at the end, to run the test in interactive mode
*2. Copy the full command line in the prompt and add <tt>-I</tt> at the end, to run the test in interactive mode
 
*3. Enjoy
 
= How to program it =
You can use the device with a <tt>vtkRenderWindowInteractor</tt> (1a) or a <tt>QVTKWidget</tt> (1b).
* Look at <tt>VTK/Rendering/Testing/Cxx/TestTDx.cxx</tt> for a sample code using a regular <tt>vtkRenderWindowInteractor</tt>.
* Look at <tt>VTK/Examples/GUI/Qt/Events/GUI4.cxx</tt> for a sample code using a <tt>QVTKWidget</tt>. <em>To compile it, you have to enable <tt>BUILD_EXAMPLES</tt>, <tt>VTK_USE_QT</tt>, <tt>VTK_USE_GUISUPPORT</tt>, <tt>VTK_USE_QVTK_QOPENGL</tt> and set <tt>DESIRED_QT_VERSION</tt> to 4 in cmake. On Windows in debug mode, the executable is <tt>qtevents.exe</tt> in <tt>$BUILD/bin/Debug</tt></em>
 
1a. Once the <tt>vtkRenderWindowInteractor</tt> is created, tell it to listen to the device, when the event loop starts (must be called before the first render).
<pre>
vtkRenderWindowInteractor *i=vtkRenderWindowInteractor::New();
i->SetUseTDx(true);
</pre>
 
1b. Once the <tt>QVTKWidget</tt> is created, and before a <tt>vtkRenderWindow</tt> is assigned to it, tell it
to listen to listen to the device, when the event loop starts:
<pre>
qVTK1->SetUseTDx(true);
qVTK1->SetRenderWindow(renwin);
</pre>
 
You can do step 2a or 2b or both:
 
<b>2a. Basic event-driven mechanism</b>
 
Add an observer to watch for a TDx event:
<pre>
vtkCommand *c;
[...]
i->AddObserver(vtkCommand::TDxMotionEvent,c,0);
</pre>
There are 3 types of events (defined in VTK/Common/vtkCommand.h), they all return some callData:


3. Enjoy
# <tt>vtkCommand::TDxMotionEvent</tt>, is invoked when the ball or knob is actived. the callData is a pointer to a <tt>vtkTDxMotionEventInfo</tt> (defined in <tt>VTK/Rendering</tt>). This structure stores information about a translation (X,Y,Z) and a rotation, represented by an angle and an axis (a unit vector). <em>Tip: use <tt>VTK/Common/vtkTransform::RotateWXYZ()</tt> to convert an angle-axis representation to an orthogonal matrix representation of a rotation.</em>
# <tt>vtkCommand::TDxButtonPressEvent</tt>, is invoked when a button is pressed. the callData is a pointer to a <tt>int</tt>, which is the number of the button.
# <tt>vtkCommand::TDxButtonReleaseEvent</tt>, is invoked when a button is released. the callData is a pointer to a <tt>int</tt>, which is the number of the button.
 
<b>2b. Use or write a concrete subclass of <tt>vtkTDxInteractorStyle</tt></b>
 
Initially, the <tt>vtkInteractorStyle</tt> attached to the <tt>vtkRenderWindowInteractor</tt> delegates the processing of the <tt>TDx*Events</tt> to a <tt>vtkTDxInteractorStyleCamera</tt>.
It means that, by default, the 3DConnexion device controls camera motions.
You can access the <tt>vtkTDxInteractorStyle</tt> attached to the <tt>vtkInteractorStyle</tt> with <tt>GetTDxStyle()</tt> and
<tt>SetTDxStyle()</tt>.
 
In addition, you can change the sensitivity settings and axe motion filtering/masking of the 3DConnexion device for a <tt>vtkTDxInteractorStyle</tt> with the <tt>vtkTDxInteractorStyleSettings</tt> object attached to it. You can share the same settings between different <tt>vtkTDxInteractorStyle</tt>s. Here is the code sample from <tt>VTK/Rendering/Testing/Cxx/TestTDx.cxx</tt> that demonstrates how to set the sensitivity parameters:
<pre>
  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);
</pre>
<em>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.</em>

Latest revision as of 12:59, 27 February 2015

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

Implementation

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

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