Anyone interested in support for space mouse (3DConnexion)?

Per project contribution guidelines, I’m opening a discussion before creating a feature request.

I use a 3D space mouse (3DConnexion) for most CAD work, including for 2D drawings. The buttery-smooth simultaneous pan & zoom you can achieve with it is really nice, and hard to do without once you’ve tried it.

I saw in some of the conversations (discussion 590, feature request 1258, etc.) that gesture support in general is still in need of some attention. It looks like it’s supported in slint now (per slint-ui/slint#6704), but maybe hasn’t been wired up yet(?).

I’d like to take a shot at implementing 3D space mouse support, and I could probably get gestures to come along for the ride if they aren’t there already (they should hook the same points for the 2D stuff).

I dug into the architecture a bit, and I think we can borrow/use quite a bit of the architecture from the FreeCAD project. They have the space mouse support integrated already, so I’d be leveraging their code base for this solution.

Thoughts?

Since I’m new… About me:

I am a digital hardware designer and deep-embedded programmer with 30+ years of professional coding experience. I do use Claude AI to assist me for most projects these days, just because it helps me keep track of the complex interfaces and code trees that my old-ish mind doesn’t quite keep up with anymore.

Hi @AvetosDesign,

I agree 100% that support for the space mouse would be awesome in the 3D viewer. Actually I also already looked into this, but then gave up since I didn’t see a straight forward solution. As far as I understand, operating systems have no generic API to talk with such devices. So the application has to talk directly to the USB drivers of every vendor providing such devices, which even needs to be dynamically detected at runtime since those drivers may or may not be available on the system LibrePCB is running on. This also makes it hard to get this implemented on every platform.

Please correct me if I’m wrong. Do you maybe have more information about how LibrePCB could talk to such a device, on every operating system?

What I clearly want to avoid is to add a huge amount of complex code which bloats up LibrePCB a lot, makes deployment more difficult, and possibly works only on one particular platform. I’d prefer some simple Rust crate that handles everything for us and just provides a simple API. However, last time I looked for this, I couldn’t find something that simple (there are some crates, but for some reason they didn’t convince me).

I’d be happy to hear about some solution that works well and isn’t too intrusive for the LibrePCB project.

They have now implemented ScaleRotateGestureHandler, but this effectively only works for touchscreens and LibrePCB is not using it yet. Trackpad gestures are only supported on macOS, not on Windows or Linux. But anyway, I think gesture support of Slint is not related at all to space mouses – as far as I understand, due to the nonexistent generic API, those two things are completely independent.

Hi @ubruhin.

I actually have the 3D mouse wired in for pan & zoom on the schematic and PCB layout (2D) prototyped and working right now. I was just about to tackle the 3D viewer. All of this is being done in my own fork so I don’t get in the way of other development.

With regard to how it’s done, there’s a HID layer in each OS (Win, macOS, and Linux) that can be hooked. FreeCAD leverages it, and it’s pretty clean. You do have to have a thin, per-OS shim to get at it, but it’s pretty light. All of the heavy stuff is common across the OS’es.

I’ve abstracted the hook points for the 3D mouse so that the gestures can piggyback (pinch is a zoom, double-finger swipe is a pan). I still need to go through the code a couple times to make sure things are structured well and clean, but it should be pretty straight-forward to handle gestures when the time comes.

When I get this completed and polished a bit, I’d appreciate a code review prior to submitting a PR. I’ll post a message here so that folks can take a look if they like.

Thanks for the opportunity!

Hmm alright. The connection to the 2D/3D views is actually the simple part I guess. I’m mainly worrying about the low-level stuff to get the movements from the space mouse.

I’d be curious to see some code how to read the movements from the space mouse, to have a better picture of the involved complexity and the overall principle.

Honestly I’d also prefer if that part gets implemented in Rust, since I don’t like to add more C++ code to LibrePCB if it could be done in Rust. Even better, since reading out the space mouse is not related to LibrePCB at all, it would be great to have this as an independent Rust crate which other projects can use as well (if this really doesn’t exist yet). Of course the integration into LibrePCB then has to be done with some C++ since the 2D/3D graphics views are still in C++.

If I understand the system correctly…

You don’t actually have to read the movements from the space mouse. The vendor’s hardware driver does that part (USB messaging to vendor driver code), and translates those movements into generic HID messages that get passed to the OS. The OS then routes those HID messages to registered consumers. That’s where we pick them up from, and why we need a per-OS (not per-vendor) shim layer – to bolt into the OS’ HID system.

I’ll get my code pushed to my fork so you can see what’s going on. It isn’t polished yet, but the form is there and it is functional (for both 2D and 3D).

To be honest, I haven’t used Rust enough to carry an intelligent conversation. I’ll look into what you’re asking for and try to learn about it.

Ah hmm maybe there exist different approaches then to talk with those mouses. For just USB HID it might be possible to build something on top of hidapi. Though I don’t have much knowledge about USB or HID in particular.

Anyway, I’m happy to look at some code first, and to try it out.

I’ve got a public branch ready with functional space mouse support. It’s not nearly ready for a PR or anything, but you’re welcome to have a look. I’ve been building/testing a release build on Windows with USE_OPENCASCADE=OFF.

You’ll find it at GitHub - AvetosDesign/LibrePCB at feature/spacemouse-support · GitHub

@ubruhin: There are a number of outstanding questions I’ll need to go over with you. One that comes up right now is the handling of the per-OS shim code. Currently, the CMake files test for the selected OS and add source files accordingly. Would you prefer that source files are included unconditionally, and gated by #if(WIN32)/#endif instead?

Nice, I quickly tried this on Windows (since Linux is not supported yet…) and indeed it worked out of the box :tada: Even the driver for the 3dConnexion device was automatically installed by Windows, and then worked in LibrePCB.

Using QAbstractNativeEventFilter is actually an interesting approach. Only the CreateWindowExW looks a bit ugly to me. Stupid question: Couldn’t we register the event filter on the already existing windows? Then we also wouldn’t have to route the events to the current window (which is unfortunately not 100% reliable).

Also I wonder if the approach with QAbstractNativeEventFilter will also work on Linux and macOS?

Some other, random notes:

  • It seems the application has to compensate a constant drift of the space mouse. At least with my space mouse, the view in LibrePCB is constantly drifting away without touching the space mouse. In FreeCAD this doesn’t happen, so I assume the drift compensation needs to be done by the application. EDIT: Maybe this is actually done by spacenavd on Linux (I didn’t test FreeCAD on Windows). Or maybe I just have to calibrate the device, though I don’t know if that is possible without installing any tool/driver manually.
  • The blue light is not switched on :see_no_evil_monkey: :sweat_smile: Not sure if this is a limitation of the driver installed by Windows. On Linux, the light switches on as soon as I run the spacenav daemon.
  • Probably we will need some configuration for the space mouse, for example to invert Y/Z axis :-/ Generally I’d like to avoid any unnecessary configuration options, but I guess in this case we have to bite that bullet.
  • I still wonder if this could be done in Rust. Though if QAbstractNativeEventFilter is the simpler solution, it probably makes sense (for now) to keep it in C++. But then we will have to migrate it some day to Rust, so generally it would be preferred to do it right from the beginning.

Yes please. We also do it that way in systeminfo.cpp. And for consistency, please use the preprocessor defines provided by Qt, not e.g. WIN32 or so.

Glad to hear it worked!

I’m going to refactor the code to get to a Rust solution for you. I based the current solution on FreeCAD’s approach without enough due diligence. As it turns out, FreeCAD approaches the three major OS’es in unique ways, making the solution cumbersome. As I’ve dug deeper, it appears that a HID-via-Rust solution is likely universal and attainable. So I’ll regroup and see what I can come up with.

To answer your questions more directly:

  • It is possible to hook the already existing windows. However, it creates a tracking/management issue when windows open and close. Using an orthogonal, message-only window allows us to avoid that at the cost of slightly “heavier” code. As things stand, the window that gets the messages is the one the OS claims has focus, so it should be reliable.
  • No, the QAbstractNativeEventFilter isn’t portable to Linux and macOS. That’s on me. I believe this point will resolve itself in the HID-via-Rust solution. I’ll keep an eye on it.
  • The drift issue and lack of LED are almost certainly due to the hardware driver. I’m fairly confident that the driver that got automatically installed is Windows’ generic HID driver, which wouldn’t have knowledge of the LED or how to calibrate the sensor. You’d need 3DConnexion’s driver for those things, and that requires a manual installation.
  • You are correct about needing a configuration system. I had that scoped for the next round of work. Axis inversion and sensitivity on all six axes will be user-configurable. We’ll also include the LED and calibration as well ;-). That work will come after an initial HID-via-Rust proof-of-concept.

Thanks for your patience with me. I think this exercise has proven that 3D mouse support can work, and that it’s beneficial. We’ll get to a cleaner solution shortly.

That would be awesome – but please, only if it doesn’t make it much more complicated for you. If there are good reasons to do it in C++, feel free to take that way.

That is somehow what I expected. I suspect, on Linux the usual approach is to use libspnav(?). But on macOS I have no idea what is the usual approach.

I mean, if there are good reasons to use different approaches on different systems, I’m fine with that. But if there is a solution which works the same way on every system (without noteworthy drawbacks), that would be nice of course. I let you figure out and decide what is the best approach.

Full ack. I’m curious how this thing continues, and thanks already for working on this :+1:

Status update: I’ve got a Rust crate solution up and running. :tada: It has similar functionality to the previous code (SpaceMouse works for schematic, PCB layout, and 3D viewer). I’ve tested it on Windows, with the same USE_OPENCASCADE=OFF caveat. The solution is fully cross-platform, leveraging the HID stack on each OS. In my view, the Rust solution is cleaner than the C+±only solution, and the cross-platform aspect is definitely a win.

It’s on a different branch than I sent previously. From my GitHub site, look for the “feature/spacemouse-rust-crate” branch.

Full Disclaimer: I haven’t written in Rust before. This solution was mostly authored by Claude AI with a lot of oversight from me. I personally read every line of code, and edited most of the comments. The C++ code and architecture look fine to me. The Rust code also looks fine to me, but having never written in Rust, I don’t know if there are nuances that I’m missing, or “common practice” things that I’m not aware of. A code review from someone with experience writing in Rust would likely be prudent (and much appreciated). There aren’t a lot of lines of code in this solution, so a review shouldn’t take long.

I’m now working through testing on a MacBook and Linux before moving on to the configuration tab/page/dialog.

Please let me know how things go if you choose to try it out.

EDIT: It’s working on macOS, too.

Oh wow, that was fast. And the result is indeed amazing:

  • It’s working for me on Windows too. Now even the constant drift is gone.
  • It’s working now even on Linux (see comments below)
  • And I couldn’t resist to try it out on macOS too – works as well.

So: really nice work so far :slightly_smiling_face:

On Linux, I just observed two things:

  • There is currently a linker error because linkage to libudev is missing. I just added udev as a dependency to a CMakeLists.txt to fix it. We will have to figure out some time if udev can be assumed to be available on every Linux system (and what about UNIX, BSD, etc.?) or if this could be some kind of “weak” dependency (space mouse support simply not compiled when libudev is not found).
  • Initially, LibrePCB doesn’t have the permission to open the hidraw device. I quickly did sudo chmod 777 /dev/hidrawX, then it worked. I don’t know what would be a clean solution for this – Installing a udev rule together with LibrePCB? User needs to add himself to some group that has permission to open those devices? Or is it even generally considered bad practice if user-space applications access those devices directly? I mean, maybe there are security concerns about this?

Regarding Rust crate: I think in the end it would be nice to move it to a separate repository and publish it on crates.io. You can choose if you want to do this under your GitHub/crates.io accounts or if you like this crate to belong to the LibrePCB organization – I’m fine with either way.

Anyway, I’m aware this is just a proof-of-concept so far, the decision about which way to go is not made yet, and there’s still a lot of work to do. But so far it looks promising to me :slightly_smiling_face:

(btw, thanks for disclosing the usage of AI, much appreciated!)

@ubruhin: I’m glad to hear things worked. :smiley:

The two Linux hiccups you ran into were anticipated. I’m working through updates for each of them. I’ve got build code that will issue a warning if libudev isn’t found, but it won’t fail, and the app will still run. It uses a similar trick to the one you’re leveraging in the testing. :slightly_smiling_face:

The Linux permissions is a trickier one, because it needs to be handled by an installation process. There’s lots of approaches to this, of course, so I’d like to understand your vision with respect to installing LibrePCB on *nix systems. Is there a reference someplace I can turn to?

EDIT: I’m not sure if I understand your question correctly. If my answer below doesn’t help, please ask more specifically :see_no_evil_monkey:

That is a bit complicated since there exist many different ways how LibrePCB is installed on *nix systems, see Installation | LibrePCB Documentation. That list is not even complete, there are lots of distribution-specific packages created by independent package maintainers.

The only official methods provided by us, are *.tar.gz, AppImage, Snap and Flatpak. For Snap and Flatpak we have to request the permission to access devices from the sandbox. And for any of them, the user will need to have permissions to access hidraw devices. So I’d expect we will have to provide an udev rule which the user needs to install.

The distribution packages (Debian, NixOS, AUR etc.) are probably easier to handle, since they are able to install an udev rule directly (no user interaction needed).

But that is just my guess, I’m not an expert in this area.

You understood it, and answered it just fine. I was just looking for any documentation you had already produced regarding how I should approach Linux installation. I now have a udev rules file, and was investigating how I should “hook” it into the established system. I didn’t want to burden you with an explanation if the answer was already documented somewhere. :slightly_smiling_face:

I’ll go ahead and check in (on my branch) the udev rule file, and plan on additional installation documentation and/or provisioning to come in a later commit. Currently, I have that rule file located in share/udev/ (a new directory). Is there a different location you would rather have it live in?

Thanks again for your help. :folded_hands:

I think that’s good :+1: A bit unusual to have udev rules in the share folder, but this way it would actually be possible e.g. for the AppImage to copy it to the system’s udev folder at runtime – e.g. in the space mouse settings in LibrePCB, if no space mouse is found, there could be a button to install the udev rule (after prompting for root rights). Maybe even distro packagers could simply symlink it from /usr/lib/udev/rules.d/, though I don’t know if they like that approach.

Correction: share/udev/ is not good, it has to be share/librepcb/udev/. Otherwise packagers will be angry about us :see_no_evil_monkey:

Thanks for looking into that. I’ll make that change.