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.

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. If your application is sandboxed, you'll need the USB (com.apple.security.device.usb) and Bluetooth (com.apple.security.device.bluetooth) entitlements.

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.

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:

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.

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 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.

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.