SpaceController Add-on for Blender Readme



Contents


1 Add-on Description

Unfortunately the SpaceControl company stopped the development of their 3D mouse SpaceController in 2018, and the Blender add-on, delivered with the latest SpaceControl driver 2.8.3, is working only with Blender versions up to 2.79, but not with the Blender versions 2.80 and later, due to some changes in Blender's programming interface. Since the SpaceController operated very well with the old Blender versions, it would be a pity to lose it when using the newer ones. Being the author of the old add-on I ported it to the new Blender version therefore.

This add-on should enable you to move the scene and objects in Blender 2.8 and later versions with the SpaceControl 3D input devices. Furthermore it incorporates Blender's operators in the SpaceControl Panel's Function Assignment dialog for easy mapping to the device's function keys. Compared to the 3D controller support for 3Dconnexion's mice which is built-in in Blender, this add-on has some additional features: A special object move mode is available e. g., and you can assign scene objects to dedicated SpaceControllers if more than one device is connected.

I developed this add-on with Blender 2.91.0; it should work with all Blender versions from version 2.80 on, but I did not prove that.

2 Installing and Starting the Add-on

As before the add-on is a single Python script "spacecontrol.py", but comes in a ZIP archive together with some configuration files for mapping the SpaceController's keys to Blender's operators, and with this documentation.
User Preferences


3 SpaceController Menu

The add-on provides Blender with its own "SpaceController" menu in the 3D view headers:

SpaceControl Menu
There are the following menu items:


4 Hints

4.1 Configurations

The add-on is aware of Blender's workspace, selectable with the tabs in the main window, and sends its name to the SpaceControl driver. The driver tries to load a configuration file with the same name as the workspace's name automatically. You are able to have different configurations for each workspace in this way. Together with the driver come configuration files for Blender's default workspaces ("Layout.cfg", "Modeling.cfg", "Compositing.cfg", ...). They are all empty and ready to be filled by the user. Only the "Layout.cfg" configuration file is populated with some macros and settings for the device's keys and the Wheel Function Launcher. Try out if this fits your needs. To copy these settings into another configuration just click in the SpaceControl panel on menu item "File/Save Configuration As ..." and store the file "Layout.cfg" under the appropriate name, e. g. "Modeling.cfg". Do the same for your own named workspaces.
Hint: The macros in "Layout.cfg" are created for the old keymapping style used in Blender 2.79; i. e. the key "a" which is mapped to the SpaceController's key "3" should toggle between "deselect" and "select all". You can change this behaviour in Blender's preferences dialog in the "Keymap" section.

4.2 Operators

Unfortunately it is not possible to read out Blender's menu items as I liked to do to offer them in the SpaceController's Function Assignment dialog for easy mapping them to the controller's keys and the Wheel Function Launcher. Instead, the add-on reads out all so called operators defined in Blender. Blender shows you the name of an operator called by a menu item when you let rest your mouse pointer over the item. Example: Menu item "Add/Mesh/Cube" in the 3D View header calls operator "bpy.ops.mesh.primitive_cube_add()". And this can easily be found in our Function Assignment dialog.
Hint: You have to activate the option "Python Tooltips" in the "Interface" section of Blender's preferences dialog to show the operators as described above.

When mapped to a key you are able to trigger an operator in contexts it is not made for. This can produce unexpected results. Some operators need parameters to be given which is not possible by this mechanism; these operators cannot be used in a meaningful way. (In some cases it could help to edit the file "blender.mnu"; see the "Technical Notes on MNU Files" in file "<SpaceControl installation folder>/doc/mnu_files_en.html" for details.)

To avoid problems concerning the context an operator is triggered in, it is a good alternative to use Blender's keyboard shortcuts; record them as macros with the SpaceController's little macro recorder and assign these macros to the device's keys. I have used this approach in the "Layout.cfg" file delivered with the driver mentioned above.

4.3 Cameras

If the view is in Camera Perspective (numpad 0 in Blender) you can move it neither with the device nor with the normal mouse. This is only possible if you select the camera first and switches the add-on into Object Move Mode (see chapter 3). In this way you can position your camera much more comfortable than with the normal mouse. If you have more than one 3D view open be aware in which region your mouse pointer is in: The behaviour is very different if it is in a Camera Perspective region or a User Perspective region because the movement is always relative to the screen coordinates of the active region.

4.4 Getting the 3D Controller's Data into Blender's Game Engine

Unfortunately the Blender game engine (BGE) has been removed from Blender from version 2.8 on. But there is a fork in the meantime, and the game engine is back! Have a look at the UPBGE project: https://upbge.org. And with this Blender version it is still possible to use the 3D controller's data to move your objects in the BGE by means of a Blender Python controller. The minimal script for moving Blender's default cube is this:

#-------------------------------------------------------------------------------

import bge

# import the global plug-in data object:
from spacecontrol import gBlenderPlugin

# choose the device to get data from (always 0 if only one device is connected):
devIdx = 0

# just as a shortcut:
data = gBlenderPlugin.devDataList[devIdx]

# get the device's data:
x      = data.x      # translation in x direction
y      = data.y      # translation in y direction
z      = data.z      # translation in z direction
a      = data.a      # rotation around x axis
b      = data.b      # rotation around y axis
c      = data.c      # rotation around z axis
event  = data.event  # pressed keys and other events
tvSec  = data.tvSec  # timestamp, seconds
tvUsec = data.tvUsec # timestamp, microseconds
print(x, y, z, a, b, c, event, tvSec, tvUsec)

# get the sample scenes controller and actuator:
controller = bge.logic.getCurrentController()
motionActuator = controller.actuators["Motion"]

# move the cube:
motionActuator.dLoc = [ x/1000, -z/1000, y/1000 ]
motionActuator.dRot = [ a/1000, -c/1000, b/1000 ]
controller.activate(motionActuator)

#
-------------------------------------------------------------------------------

I. e. you have to import the global gBlenderPlugin object of the Blender add-on to get access to the 3D controller's raw data, and you can access the translation data coordinates x, y, z and the rotational coordinates a, b, c around these axes. Scale the data as you need it (divisor 1000 in the above example). See the sample file "<SpaceControl installation folder>\Blender\sc_sample.blend" how to assign the script to a demo cube's logic bricks.

4.5 Using Several Devices Concurrently

The add-on supports using of more SpaceControl devices than just one. It is possible to bind a selected object or a group of objects to a device, and the device will move and rotate these objects exclusively then. Bind a spotlight to another device, a camera to a third, and you can have three persons to be in the role of an actor, an illuminator and a cameraman by handling their Blender objects with their individual SpaceControl devices concurrently!

If more than one device is connected, the SpaceController menu described above changes a little; there is a new submenu Bind Selection to Device which basically contains the serial numbers of all connected devices (three in this example):

SpaceControl Menu with new Submenu

Binding a Blender object to a device is easy: Just select the wanted object in Blender and press the menu item with the appropriate serial number in the menu. From now on the device moves and rotates the object(s) in the selection - even if the selection is deselected. To free the object(s) press the menu item again. Whether objects are bound to a device or not, is signaled by the menu item's check box.

If the cameraman e. g. controls the camera view with his device it is sometimes difficult for the other actors to move their objects in the same view because the SpaceControl devices' axes are oriented relative to the screen and not to the virtual world showed in the scene, and the other actors are permanently forced to rethink their position when the cameraman rotates the camera. Therefore it is recommended to split the view to allow each actor to have its own to concentrate on. But this would not help so much because a bound object is still moved relative to the screen coordinates, but in fact to that view the mouse pointer is over currently. That is where menu item Remember View When Bind Selection comes into play: If the item is activated the add-on remembers the currently active view (i. e. the view with the last device-controlled movement in it) when the selection is bound and will not change it even if the mouse pointer is moved to another view. Try out the difference with some split views.
Attention: Blender's Quad View is only one view, not four views as needed by this mechanism; you have to create real split views to get the menu item working.

If more than three devices are connected you may observe a slight performance decrease which results in a time lag when moving the scene or an object because the data is buffered and delivered even after a device's cap is released. To avoid this it is necessary to reduce the devices' data rate. This can be achieved by increasing the devices' Send Gap in the SpaceControl Panel's Advanced Configuration dialog (activate the check box Further Settings there to see the Send Gap slider; see section 3.3.2 in the SpaceController user manual for details).
Increasing the Send Gap by hand for each device is inconvenient; therefore the plug-in can do this for you by itself when menu item Set Send Gap Automatically is activated. In this case, as soon as a change in the number of connected devices is detected, the plug-in measures the data rate of the first new few data packets for each device and adjusts the Send Gap appropriately to avoid the time lag.

5 Known Issues


6 Change Log

27 December 2020, Version 1.0.0:




Author: Friedemann Seebass, Germany, December 2020