3D mouse (SpaceMouse)
A 3Dconnexion 3D mouse — SpaceMouse, SpacePilot, SpaceNavigator and the like — can pan and zoom QElectroTech's folios 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 folio 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 Souris 3D 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
Edit → Preferences, page Souris 3D (3D mouse).
Mouvement (Motion)
| Setting | Range | Default | Does |
|---|---|---|---|
| Vitesse de déplacement (Pan speed) | 10–400 % | 100 % | how fast the view pans |
| Vitesse du zoom (Zoom speed) | 10–400 % | 100 % | how fast it zooms |
| Zoomer en (Zoom by) | Pousser / tirer le capuchon (push/pull the cap), Tourner le capuchon (twist the cap) | push/pull | which movement zooms |
| Zone morte (Dead zone) | 0–200 | 0 | movements smaller than this are ignored; raise it if the view drifts while you are not touching the device |
| Inverser le déplacement horizontal | on/off | off | reverses left/right |
| Inverser le déplacement vertical | on/off | off | reverses forward/back |
| Inverser le 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:
- Click Ajouter une association (Add a binding).
- Set N° bouton to the button's number.
- Pick the command under Action. The list holds every command that has a shortcut in QElectroTech, grouped by editor.
- 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 Souris 3D 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 Zone morte |
| 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 folio |
| 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 folio — 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
Getting Started
🌐 Languages — English · Français · Deutsch
Guides
Conductors — wire properties, what feeds which export, and cables
Printing and exporting — paper, PDF, images, and what each path does differently
Linking elements — master, slave, terminal
PLC modules — I/O tables and linking a wire to a specific point
Using the element editor — drawing tools, saving, checks
Grid size and element size — why symbols aren't all the same scale
Preferences reference — what each settings page does
Keyboard-only control — mouseless QET, and what still needs a mouse
Mouse modifiers — what Shift, Ctrl and Alt change while you drag
3D mouse — SpaceMouse pan, zoom and buttons
Aligning items — snap symbols back to the grid, or line them up
Pictures on a folio — labels, crop, transparency, what they cost in the file
Grouping items — select, move and copy several items as one
Finding your place on a folio — go to a cell like B13 or 4-B7, keep the headers in sight, show the cell limits
Drawing faster — place without dragging, the S shortcut bar, command search, gestures
Managing collections — folders, writability, building your own shortlist
Templates — reusable multi-element blocks, and why clicking one does nothing
Search & Replace — bulk property changes
Building a nomenclature query — the BOM/summary table builder
Linking wires across pages — folio reports
Variables & formulas — %f, %{label}, sequences
Auto-numbering — schemes, sequences, freezing
Terminal strips — strips, levels, bridges
Title block templates — the .titleblock format
Importing EPLAN parts (.edz) — EPLAN Data Portal
DXF import & export — two unrelated features, one format; command-line export and layers
The project database — the in-memory SQLite cache
Development
Automating QET — CLI, XML formats, external tools
CLI Reference — command line usage
JavaScript Scripting — --run, geometry editing, undo
MCP server — let an AI assistant read, verify and edit projects
Vision — proposal, under discussion
