3d_mouse

3D mouse (SpaceMouse)

A 3Dconnexion 3D mouse — SpaceMouse, SpacePilot, SpaceNavigator and the like — can pan and zoom QElectroTech's sheets and the element editor with one hand, leaving the other on the ordinary mouse for drawing. Its buttons can run any QElectroTech command that has a keyboard shortcut.

Support was asked for, and is still discussed, in discussion #599. Reports from real devices are welcome there: see §6.

---

1. What it does

On the device	In QElectroTech
Slide the cap left/right, forward/back	pans the view
Push/pull the cap (default), or twist it (setting)	zooms
Tilt	nothing
A button	the command you bound to it, if any

It acts on whichever window is in front: the current sheet of the schematic editor, or the element editor's drawing. Zoom stops at the same limits as the mouse wheel.

Nothing happens on a button press until you bind that button (§3). There is no default binding.

---

2. Which builds have it

3D mouse support is a compile-time option, off by default. How the device is read depends on the build:

Build	Reads the device through	Needs
Windows package	USB directly (hidapi)	nothing extra; no 3Dconnexion driver is required
macOS package	3DxWare when it is installed and running, otherwise USB directly	nothing extra
Flatpak	USB directly (hidapi)	read access to /dev/hidraw*, see §5
Snap	spacenavd	the spacenavd daemon running
Linux distribution packages, own builds	whatever the packager chose	see §7

If the 3D mouse page is missing from the preferences (§3), your build does not have 3D mouse support.

On macOS, while QElectroTech is the front application, 3DxWare's own actions are switched off in it, so the view does not move twice.

---

3. Settings

Settings → Configure QElectroTech, page 3D mouse.

Mouvement (Motion)

Setting	Range	Default	Does
Pan speed	10–400 %	100 %	how fast the view pans
Zoom speed	10–400 %	100 %	how fast it zooms
Zoom by	Push / pull the cap, Twist the cap	push/pull	which movement zooms
Dead zone	0–200	0	movements smaller than this are ignored; raise it if the view drifts while you are not touching the device
Reverse horizontal movement	on/off	off	reverses left/right
Reverse vertical movement	on/off	off	reverses forward/back
Reverse zoom	on/off	off	reverses zoom in/out

The speed on screen does not depend on how often the driver sends updates, so the same setting feels the same on every system. An equal push and pull cancel out exactly.

Boutons (Buttons)

A table of button number → command:

1. Click Add a link.
2. Set Button no to the button's number.
3. Pick the command under Action. The list holds every command that has a shortcut in QElectroTech, grouped by editor.
4. Click OK to save.

The number a button sends depends on the device and on how it is read. The device's documentation may give it; otherwise try 0, 1, 2… in turn. The button at the end of a row removes the binding.

---

4. Where the settings are kept

In QElectroTech's own settings, not in any project: under spacemouse/motion/ for the motion settings and spacemouse/buttons/ for the bindings. They apply to every project, and to both editors.

---

5. When nothing happens

Symptom	Check
No 3D mouse page in the preferences	the build has no 3D mouse support: §2
Snap: the device does nothing	spacenavd is installed and running (systemctl status spacenavd)
Flatpak: the device does nothing	your user can read the device: ls -l /dev/hidraw*. On many distributions these nodes are readable by root only, and a udev rule is needed (below)
The view drifts on its own	raise Dead zone
It moves the wrong way	the Inverser… settings
A button does nothing	it is not bound yet, or bound to the wrong number: §3

A udev rule giving the logged-in user access to 3Dconnexion devices, for the Flatpak or any build using the USB backend on Linux. Save it as /etc/udev/rules.d/70-3dmouse.rules:

KERNEL=="hidraw*", ATTRS{idVendor}=="256f", TAG+="uaccess"
KERNEL=="hidraw*", ATTRS{idVendor}=="046d", TAG+="uaccess"

256f is 3Dconnexion; 046d is Logitech, which sold the older models. Then run sudo udevadm control --reload && sudo udevadm trigger and replug the device. QElectroTech looks for a device every three seconds, so it does not need restarting, and it reconnects on its own after the device is unplugged.

---

6. Helping with a recording

The USB backend decodes each device model's raw reports itself. A short recording from a real device lets that model be tested. The script misc/spacemouse-capture.py in the source tree guides you through a few movements, saves one .json file, and sends nothing anywhere. It runs on Linux, macOS and Windows with only Python 3.

curl -LO https://raw.githubusercontent.com/qelectrotech/qelectrotech-source-mirror/master/misc/spacemouse-capture.py
python3 spacemouse-capture.py --help      # step-by-step instructions for your system
python3 spacemouse-capture.py --seconds 3 # record, three times the default time per step

On Linux, run it with sudo, for the reason in §5. Attach the file to discussion #599. One recording per device model is enough.

---

7. Building it in

Two CMake options:

Option	Values	Default
QET_ENABLE_SPACEMOUSE	ON, OFF	OFF
QET_SPACEMOUSE_BACKEND	auto, spnav, hid	auto

Backend	Reads through	Library (pkg-config)
spnav	the spacenavd daemon, Linux	libspnav-dev (spnav)
hid	USB directly, any system	libhidapi-dev on Linux (hidapi-hidraw), MSYS2 mingw-w64-ucrt-x86_64-hidapi, Homebrew hidapi
auto	spnav on Linux when libspnav is found, hid otherwise

On macOS the 3DxWare backend is always added as well. It loads 3DxWare's library at run time and needs nothing to build.

cmake -B build -DQET_ENABLE_SPACEMOUSE=ON -DQET_SPACEMOUSE_BACKEND=hid

If the chosen backend's library is not found, CMake prints a warning and builds without 3D mouse support rather than failing. Check the configure output for a line like QET_ENABLE_SPACEMOUSE ON (backend: hidapi 0.14.0).

---

8. Limitations

Limitation	Detail
Pan and zoom only	tilting the cap does nothing; there is no rotation of the sheet
Button numbers are raw	there is no "press the button to bind it"; find the number by trying
3DxWare app events	on macOS, only raw button presses are read, not the named actions newer 3DxWare versions send
Hardware coverage	tested on the devices reported in discussion #599; other models may need a recording (§6)

---

See also

• Preferences reference — the other preference pages
• Finding your place on a sheet — going to a cell, keeping the headers in sight
• Keyboard-only control — the commands a button can be bound to
• Building from Source — the full build instructions