4.12 `spacedevice` -- Wrapper around the 3Dconnexion Developer's Kits

The spacedevice module allows applications to support 3D input devices such as a SpaceMouse or a SpaceBall. The module wraps the 3DxWare SDK by 3Dconnexion. For a more detailed description of the SDK see the documentation that is part of the SDK.

The module has to be used in conjunction with a GUI toolkit as there must be a window that receives the 3D input device events. In principle, any GUI toolkit can be used as long as it allows obtaining the native windows handle and accessing system events. The steps necessary to use a 3D input device are as follows:

Create a SpaceDevice object.
Open the device using the open() method. This requires a windows handle of the window that will receive the SpaceDevice events.
For every system event received call the translateWin32Event() method and check if the event was generated by a SpaceDevice. If it was, check for the event type and process the event.
When the application terminates, call the close() method to close the device.

available( ): Returns True if the module functionality is available. Currently, this function will only return True under Windows and if the functionality was enabled during compilation.
If this function returns False, an exception will be raised whenever you try to instantiate a class from this module.

class SpaceDevice( ): The SpaceDevice class provides the interface to the 3DxWare library that is used to communicate with the 3D input device. The constructor of this class calls the SDK function SiInitialize() to initialize the 3DxWare library. The destructor closes the device if it is open and calls SiTerminate().

open( appname, hwnd, devID=SI_ANY_DEVICE): Establish a connection to a 3D input device. appname is a string containing the application name, hwnd is the native window handle (as integer) of the window that should receive the events. devID is the device id. An exception is thrown if a connection cannot be established.
This method calls the SDK functions SiOpenWinInit() and SiOpen().

close( ): Close the connection to a device. The function returns immediately if there is no open connection.
This method calls the SDK function SiClose().

translateWin32Event( msgid, wparam, lparam)

Translates a Win32 event into a SpaceDevice event. The return value is a tuple (RetVal, EventType, Data).

RetVal is an object of type RetVal that represents an enumeration. It is RetVal.IS_EVENT if the event was generated by a 3D input device, otherwise it is RetVal.NOT_EVENT.

EventType is an object of type EventType that again represents an enumeration. It can take one of the following values:

EventType.BUTTON_EVENT
EventType.MOTION_EVENT
EventType.ZERO_EVENT
EventType.EXCEPTION_EVENT

The contents of the third value, Data, depend on the event type:

Event type	Data
`BUTTON_EVENT`	(`pressed`, `released`)
`MOTION_EVENT`	(`translation`, `rotation`, `period`)
`ZERO_EVENT`	`None`
`EXCEPTION_EVENT`	`None`

pressed and released are each lists that contain the numbers of the button that were either pressed or released. translation is a 3-tuple containing the translation vector and rotation is a 3-tuple containing the rotation vector. period contains the time in milliseconds since the last device event.

This method calls the SDK functions SiGetEventWinInit() and SiGetEvent().

beep( s): Causes the device to emit a sequence of tones and pauses that is encoded in the string s. Lowercase letters represent a tone, uppercase letters represent a pause. The closer the letter is to the beginning of the alphabet the shorter the pause or tone.
This method calls the SDK function SiBeep().

getDeviceID( ): Return the device id of the currently open device.
This method calls the SDK function SiGetDeviceID().

getDeviceInfo( ): Return information about the currently open device. The return value is a 5-tuple (device type, numButtons, numDegrees, canBeep, firmware).
This method calls the SDK function SiGetDeviceInfo().

getDriverInfo( ): Return version information about the driver. The return value is a 5-tuple (major, minor, build, versionstr, datestr).
This method calls the SDK function SiGetDriverInfo().

getNumDevices( ): Return the number of input devices detected by the driver.
This method calls the SDK function SiGetNumDevices().

rezero( ): Causes the input device's current setting to be defined as the rest position.
This method calls the SDK function SiRezero().

setUIMode( show): Change the state of the driver menu window from within an application. The function has to be called before a call to open(). show is a boolean that specifies if the driver menu should be displayed or not.
This method calls the function SiSetUiMode().

Note: The module uses the SDK by 3Dconnexion which can be found at http://www.3dconnexion.com/sdk.htm. The following is the copyright information of the SDK:

Permission to use, copy, modify, and distribute this software for all purposes and without fees is hereby granted provided that this copyright notice appears in all copies. Permission to modify this software is granted and 3Dconnexion will support such modifications only if said modifications are approved by 3Dconnexion

4.12 spacedevice -- Wrapper around the 3Dconnexion Developer's Kits

4.12 `spacedevice` -- Wrapper around the 3Dconnexion Developer's Kits