Contents

tomasf/navlibswift

NavLibSwift is a Swift package for interfacing with 3DConnexion's Navigation Framework (NavLib) on macOS. This allows you to add support for their SpaceMouse line of 3D controllers to your application and makes it easier than ever.

Usage

Add the NavLibSwift Package

  1. Add https://github.com/tomasf/NavLibSwift.git as a dependency in your project/package and import NavLib.
  2. Enable C++ interoperability for your target.

That's it! NavLibSwift dynamically loads the 3DconnexionNavLib framework at runtime, so you don't need to link against it or add any special linker flags. Your app will build and run even on systems without the 3DConnexion drivers installed.

If you're using the hardened runtime, make sure you disable library validation (com.apple.security.cs.disable-library-validation) to allow loading the framework.

Initialize and Use a NavLibSession

  1. Conform your app’s existing 3D vector type to Vector (provide x/y/z and init(x:y:z:)). You’ll use this as V.
  2. Create an instance of NavLibSession<V>.
  3. Make a class conform to NavLibStateProvider<V>. modelBoundingBox: V.BoundingBox and cameraTransform: Transform are the only two required properties; the rest have defaults.
  4. Call start(stateProvider:applicationName:) to initialize the session. This will throw an error if the framework is not installed.
  • Implement cameraProjection to specify the FOV used or to support orthographic projection (using V.BoundingBox).
  • Implement hitTest(parameters:) to let NavLib perform hit-testing against your model for smarter pivot points. Detect changes to the pivot point with pivotChanged(position:visible:).

If your application has multiple 3D views, you can create multiple NavLibSession instances. To activate a specific session, call setAsActiveSession().

For a minimal working example, refer to the NavLibDemo repository, which demonstrates basic integration with SceneKit.

Background

3DConnexion's macOS support is inconsistent, and documentation is sparse. Their developer forums are also relatively inactive. There are a few ways to add SpaceMouse support on macOS:

HID

SpaceMouse devices use the HID protocol, so you can connect to them via IOKit and read raw input values. However, this approach is impractical:

  • If the user has installed 3DConnexion's drivers (which most will have), they block direct HID access.
  • Correctly interpreting raw values varies between device models, adding complexity.

3DconnexionClient

The 3DconnexionClient framework is the traditional way to interface with SpaceMouse devices. It wraps HID calls and provides some preprocessing, but:

  • You still need to implement the actual 3D navigation logic yourself.
  • It's tedious to work with and relies on outdated things like Pascal strings (!).

3DconnexionNavLib

3DconnexionNavLib is a more modern, high-level library. It manages 3D navigation for you. Instead of manually handling input data, you provide callbacks to read and write properties of your 3D environment, and the library takes care of the rest.

NavLibSwift wraps 3DconnexionNavLib to provide a streamlined Swift interface. However, due to outdated headers that no longer compile with modern versions of Clang, modified headers are included in this Swift package.

License

NavLibSwift is licensed under the MIT License. See the LICENSE file for details.

This project is an independent initiative and is not affiliated with or endorsed by 3DConnexion. All trademarks and registered trademarks are the property of their respective owners.

Package Metadata

Repository: tomasf/navlibswift

Default branch: main

README: README.md