The NatNet SDK is a networking software development kit (SDK) for receiving NaturalPoint data across networks. It allows streaming of live or recorded motion capture data from a tracking server (e.g. Motive) into various client applications. Using the SDK, you can develop custom client applications that receive data packets containing real-time tracking information and send remote commands to the connected server. NatNet uses the UDP protocol in conjunction with either Point-To-Point Unicast or IP Multicasting for sending and receiving data. The following diagram outlines the major components of a typical NatNet network setup and how they establish communication between NatNet server and client application.
- For previous versions of NatNet, please refer to the provided PDF user guide that ships with the SDK.
NatNet is backwards compatible with any version of Motive, however, in older versions there may be missing features that are present in newer versions.
The NatNet SDK consists of the following:
- NatNet Library: Native C++ networking library contents, including the static library file (.lib), the dynamic library file (.dll), and the corresponding header files.
- NatNet Assembly: Managed .NET assembly (NatNetML.dll) for use in .NET compatible clients.
- NatNet Samples: Sample projects and compiled executables designed to be quickly integrated into your code.
- A NatNet server (e.g. Motive) has 2 threads and 2 sockets: one for sending tracking data to a client and one for sending/receiving commands.
- NatNet servers and clients can exist either on a same machine or on separate machines.
- Multiple NatNet clients can connect to a single NatNet server.
- When a NatNet server is configured to use IP Multicast, the data is broadcasted only once, to the Multicast group.
- Default multicast IP address: 220.127.116.11 and Port: 1511.
- IP address for unicast is defined by a server application.
The NatNet SDK is shipped in a compressed ZIP file format. Within the unzipped NatNet SDK directory, the following contents are included:
The Sample folder, contains Visual Studio 2013 projects that use the NatNetSDK libraries for various applications. These samples are the quickest path towards getting NatNet data into your application. We strongly recommend taking a close look into these samples and adapt applicable codes into your application. More information on these samples are covered in the NatNet Samples page.
Library Header Files:
The include folder contains headers files for using the NatNet SDK library.
Library DLL Files:
NatNet library files are contained in the lib folder. When running applications that are developed against the NatNet SDK library, corresponding DLL files must be placed alongside the executables.
- NatNet class and function references for the NatNetClient object.
- List of tracking data types available in the NatNet SDK streaming protocol.
- NatNet commands for remote triggering the server application
- NatNet commands for subscribing to specific data types only.
Tip: Code samples are the quickest path to towards getting familiar with the NatNet SDK. Please check out the NatNet samples page.
- List of NatNet sample projects and the instructions.
- Timecode representation in OptiTrack systems and NatNet SDK tools.
- A general guideline to using the NatNet SDK for developing a native client application.
- A general guideline to using the NatNet SDK for developing a managed client application.
In streamed NatNet data packets, orientation data is represented in the quaternion format (qx, qy, qz, qw). In contrast to Euler angles, Quaternion orientation convention is order independent, however, it indicates the handedness. When converting quaternion orientation into Euler angles, it is important to consider and decide which coordinate convention that you want to convert into. Some of the provided NatNet samples demonstrate quaternion to Euler conversion routines. Please refer to the included WinFormSample, SampleClient3D, or Matlab samples for specific implementation details and usage examples.
To convert from provided quaternion orientation representation, the following aspects of desired Euler angle convention must be accounted:
- Rotation Order
- Handedness: Left handed or Right handed
- Axes: Static (Global) or relative (local) axes.
For example, Motive uses the following convention to display the Euler orientation of an object:
- Rotation Order: X (Pitch), Y (Yaw), Z (Roll)
- Handedness: Right-handed (RHS)
- Axes: Relative Axes (aka 'local')
Important Note: Use of the direct depacketization is not recommended. The syntax of the bit-stream packets is subject to change, requiring an application to update its parsing routines to be compatible with the new format. The direct depacketization approach should be used only where the use of the NatNet library is not applicable.
In situations where the use of the NatNet library is not applicable (e.g. developing on unsupported platforms such as Unix), you can also depacketize the streamed data directly from the raw bit-stream without using the NatNet library. In order to provide the most current bitstream syntax, the NatNet SDK includes a testable working depacketization sample (PacketClient, PythonClient) that decodes NatNet Packets directly without using the NatNet client class.
For the most up-to-date syntax, please refer to either the PacketClient sample or the PythonClient sample to use them as a template for depacketizing NatNet data packets.
- 1.Adapt the PacketClient sample (PacketClient.cpp) or the PythonClient sample (NatNetClient.py) to your application's code.
- 2.Regularly update your code with each revision to the NatNet bitstream syntax.
The 4.0 update includes bit-stream syntax changes to allow up to 32 force plates to be streamed at once. This requires corresponding updates for each program that uses the direct depacketization approach for parsing streamed data. A system under 32 force plates should still avoid using direct depacketization. See the Important Note above in the Direct Depacketization section for more information.
Starting from Motive 3.0, you can send NatNet remote commands to Motive and select the version of bitstream syntax to be outputted from Motive. This is accomplished by sending a command through the command port. For details on doing this, please refer to the SetNatNetVersion function demonstrated in the PacketClient.
Bit-Stream NatNet Versions
- NatNet 4.0 (Motive 3.0)
- NatNet 3.1 (Motive 2.1)
- NatNet 3.0 (Motive 2.0)
- NatNet 2.10 (Motive 1.10)
- NatNet 2.9 (Motive 1.9)