Table Of Contents

Previous topic


This Page


The spnav module interface exactly mirrors the C API of libspnav, but the C union of event structs has been replaced with Python classes.

Event Classes

Event types are identified by module constants:


Linear and rotation force applied to controller.


Button pressed or released.


Either motion or button event. Only used with spnav_remove_events.

class spnav.SpnavEvent(ev_type)

Space Navigator Event Base class

ev_type: int
class spnav.SpnavMotionEvent(translation, rotation, period)

Space Navigator Motion Event class

translation: 3-tuple of ints
Translation force X,Y,Z in arbitrary integer units
rotation: 3-tuple of ints
Rotation torque around axes in arbitrary integer units
period: int
Corresponds to spnav_event_motion.period in libspnav. No idea what the meaning of the field is.
class spnav.SpnavButtonEvent(bnum, press)

Space Navigator Button Event class

Button events are generated when a button on the controller is pressed and when it is released.

bnum: int
Button number
press: bool
If True, button pressed down, else button released.

UNIX Socket Protocol


Open connection to the daemon via AF_UNIX socket.

The unix domain socket interface is an alternative to the original magellan protocol, and it is NOT compatible with the 3D connexion driver. If you wish to remain compatible, use the X11 protocol (spnav_x11_open, see below).

Raises SpnavConnectionException if connection cannot be established.


Blocks waiting for Space Navigator events.

Note that the block happens inside the libspnav library, so you will not be able to interrupt this function with Ctrl-C. It is almost always better to use spnav_poll_event() instead.

Returns: An instance of SpnavMotionEvent or SpnavButtonEvent.


Polls for waiting for Space Navigator events.

Returns: None if no waiting events, otherwise an instance of SpnavMotionEvent or SpnavButtonEvent.


Removes pending Space Navigator events from the queue.

This function is useful to purge old events that may have queued up after a long calculation. It helps to keep your application appearing more responsive.

event_type: int
The type of events to remove. SPNAV_EVENT_MOTION or SPNAV_EVENT_BUTTON removes just motion or button events, respectively. SPNAV_EVENT_ANY removes both types of events.

Closes connection to the daemon.

X11 Socket Protocol

spnav.spnav_x11_open(display, window)

Opens a connection to the daemon, using the original magellan X11 protocol. Any application using this protocol should be compatible with the proprietary 3D connexion driver too.

display: PyCObject containing X11 Display struct
X11 display pointer
window: int
X11 window handle

Raises SpnavConnectionException if Space Navigator daemon cannot be contacted.


Examines an arbitrary X11 event to see if it is a Space Navigator event.

Returns: None if not a Space Navigator event, otherwise an
instance of SpnavMotionEvent or SpnavButtonEvent is returned.

Closes connection to the daemon.


exception spnav.SpnavException(msg)

Base class for all spnav exceptions.

exception spnav.SpnavConnectionException(msg)

Exception caused by failure to connect to source of spnav events.

exception spnav.SpnavWaitException(msg)

Exception caused by error while waiting for spnav event to arrive.