This guide covers essential points to developing a native client application using the NatNet SDK. The guideline uses sample codes in the SampleClient.cpp application in the \NatNet SDK\Sample folder, please refer to this project as an additional reference.

1. Import Library

a. Link the Library

When developing a native NatNet client application, NatNetLib.dll file needs to be linked to the project and placed alongside its executable in order to utilize the library classes and functions. Make sure the project is linked to DLL files with matching architecture (32-bit/64-bit).

b. Include the Header Files

After linking the library, include the header files within your application and import required library declarations. The header files are located in the NatNet SDK/include folder.

1. include "NatNetTypes.h"

2. include "NatNetClient.h"

NatNet SDK

2. Connect

a. Create a Client Object

Connection to a NatNet server application is accomplished through an instance of NatNetClient object. The client object is instantiated by calling the NatNetClient constructor with desired connection protocol (Multicast/Unicast) as its argument. Designate a desired connection protocol and instantiate the client object. In the SampleClient example, this step is done within the CreateClient function.

• ConnectionType_Multicast = 0

• ConnectionType_Unicast = 1

int CreateClient(ConnectionType connectionType) {
  // release previous server
   if(g_pClient)
   {
       g_pClient -> Disconnect();
       delete g_pClient;
   }
      // create NatNet client
   g_pClient = new NatNetClient(connectionType);

b. Discover Server Address

The NatNet SDK includes functions for discovering available tracking servers. While client applications can connect to a tracking server by simply inputting the matching IP address, the auto-detection feature provides easier use.The NatNet_BroadcastServerDiscovery function searches the network for a given amount of time and reports IP addresses of the available servers. The reported server information can be used to establish the connection. The NatNet_CreateAsyncServerDiscovery function continuously searches for available tracking servers by repeatedly calling a callback function. This is all demonstrated in the SampleClient application.

[C++] SampleClient.cpp : Server Discovery

const unsigned int kDiscoveryWaitTimeMillisec = 5 * 1000; // Wait 5 seconds for responses.
const int kMaxDescriptions = 10; // Get info for, at most, the first 10 servers to respond. sNatNetDiscoveredServer servers[kMaxDescriptions]; 
 int actualNumDescriptions = kMaxDescriptions;
 NatNet_BroadcastServerDiscovery( servers, &actualNumDescriptions );
 if ( actualNumDescriptions < kMaxDescriptions ) {
    // If this happens, more servers responded than the array was able to store.
 }

c. Connect to Server

Now that you have instantiated a NatNetClient object, connect the client to the server application at the designated IP address by calling the NatNetClient::Connect method.The Connect method requires a sNatNetClientConnectParams struct for the communication information; including the local IP address that the client is running on and the server IP address that the tracking data is streamed to. It is important that the client connects to appropriate IP addresses; otherwise, the data will not be received.Once the connection is established, you can use methods within the NatNetClient object to send commands and query data.

 typedef struct sNatNetClientConnectParams {
 ConnectionType connectionType;
   uint16_t serverCommandPort;
   uint16_t serverDataPort;
   const char* serverAddress;
   const char* localAddress;
   const char* multicastAddress;
   if defined(__cplusplus) {
        sNatNetClientConnectParams()
       : connectionType( ConnectionType_Multicast )
       , serverCommandPort( 0 )
       , serverDataPort( 0 )
       , serverAddress( NULL )
       , localAddress( NULL )
       , multicastAddress( NULL )
   }
   endif {
    sNatNetClientConnectParams;
  }
}

[C++] SampleClient.cpp : Connect to the Server

d. Confirm Connection

Now that the NatNetClient object is connected, let’s confirm the connection by querying the server for its descriptions. This can be obtained by calling the NatNetClient::GetServerDescription method and the information gets saved in the provided instance of sServerDescriptions. This is also demonstrated in the CreateClient function of the SampleClient project.

[C++] SampleClient.cpp : Request Server Description

// print server info
 memset( &g_serverDescription, 0, sizeof( g_serverDescription ) );
 ret = g_pClient->GetServerDescription( &g_serverDescription );
 if ( ret != ErrorCode_OK || ! g_serverDescription.HostPresent )
 {
    printf("Unable to connect to server. Host not present. Exiting.");
    return 1;
 }
 printf("[SampleClient] Server application info:\n");

 printf("Application: %s (ver. %d.%d.%d.%d)\n", g_serverDescription.szHostApp, g_serverDescription.HostAppVersion[0],
         g_serverDescription.HostAppVersion[1],g_serverDescription.HostAppVersion[2],
         g_serverDescription.HostAppVersion[3]);

 printf("NatNet Version: %d.%d.%d.%d\n", g_serverDescription.NatNetVersion[0], g_serverDescription.NatNetVersion[1],
         g_serverDescription.NatNetVersion[2], g_serverDescription.NatNetVersion[3]);

 printf( "Client IP:%s\n", g_connectParams.localAddress );
 printf( "Server IP:%s\n", g_connectParams.serverAddress );
 printf("Server Name:%s\n\n", g_serverDescription.szHostComputerName);

You can also confirm connection by sending a NatNet remote command to the server. NatNet commands are sent by calling the NatNetClient::SendMessageAndWait method with supported NatNet Command as one of its input arguments. The following sample sends a command for querying the number of analog sample for each of the mocap frames. If the client is successfully connected to the server, this method will save the data and return 0.

[C++] SampleClient.cpp : Send NatNet Commands

// send/receive test request
printf("[SampleClient] Sending Test Request\n");
void* pResult;
int ret = 0;
int nBytes = 0;

// Querying configured system frame rate from the connected server
'''ret = g_pClient -> SendMessageAndWait("AnalogSamplesPerMocapFrame", &pResult, &nBytes);'''

if (ret == ErrorCode_OK)
{
 analogSamplesPerMocapFrame = *((int*)pResult);
 printf("Analog Samples Per Mocap Frame : %d", analogSamplesPerMocapFrame);
}

3. Get DataDescriptions

a. Fetching Data Description

Now that the client application is connected, data descriptions for the streamed capture session can be obtained from the server. This can be done by calling the NatNetClient::GetDataDescriptionList method and saving the descriptions list into an instance of sDataDescriptions. From this instance, the client application can figure out how many assets are in the scene as well as their descriptions.This is done by the following line in the SampleClient project:Collapse

[C++] SampleClient.cpp : Get Data Descriptions

// Retrieve Data Descriptions from server printf("\n\n[SampleClient] Requesting Data Descriptions..."); sDataDescriptions* pDataDefs = NULL; iResult = g_pClient->GetDataDescriptions(&pDataDefs);
if (iResult != ErrorCode_OK || pDataDefs == NULL){
printf("[SampleClient] Unable to retrieve Data Descriptions.");
}

b. Parsing Data Description

After an sDataDescriptions instance has been saved, data descriptions for each of the assets (marker, Rigid Body, Skeleton, and force plate from the server) can be accessed from it.Collapse

[C++] SampleClient.cpp : Parsing Data Descriptions

// Retrieve Data Descriptions from server printf("\n\n[SampleClient] Requesting Data Descriptions..."); sDataDescriptions* pDataDefs = NULL; iResult = g_pClient->GetDataDescriptions(&pDataDefs);
if (iResult != ErrorCode_OK || pDataDefs == NULL) { Retrieve Data Descriptions from server printf("\n\n[SampleClient] Requesting Data Descriptions..."); sDataDescriptions* pDataDefs = NULL; 
iResult = g_pClient->GetDataDescriptions(&pDataDefs);
if (iResult != ErrorCode_OK || pDataDefs == NULL) {
    printf("[SampleClient] Unable to retrieve Data Descriptions.");
    } 
    else {
    printf("[SampleClient] Received %d Data Descriptions:\n", pDataDefs->nDataDescriptions );
   for(int i=0; i < pDataDefs->nDataDescriptions; i++)
   {
           printf("Data Description # %d (type=%d)\n", i, pDataDefs->arrDataDescriptions[i].type);
           if(pDataDefs->arrDataDescriptions[i].type == Descriptor_MarkerSet)
           {
                // Marker Set
                sMarkerSetDescription* pMS = pDataDefs->arrDataDescriptions[i].Data.MarkerSetDescription;
            }
            else if(pDataDefs->arrDataDescriptions[i].type == Descriptor_RigidBody)
            {
                // RigidBody
               sRigidBodyDescription* pRB = pDataDefs->arrDataDescriptions[i].Data.RigidBodyDescription;
            }
            else if(pDataDefs->arrDataDescriptions[i].type == Descriptor_Skeleton)
            {
                // Skeleton
               sSkeletonDescription* pSK = pDataDefs->arrDataDescriptions[i].Data.SkeletonDescription;
            }
            else if(pDataDefs->arrDataDescriptions[i].type == Descriptor_ForcePlate)
            {
                // Force Plate
               sForcePlateDescription* pFP = pDataDefs->arrDataDescriptions[i].Data.ForcePlateDescription;
            }
            else
            {
                printf("Unknown data type.");
                // Unknown
            }
   }      

C. Free Data Description

When you are finished using the data description structure, you should free the memory resources allocated by GetDataDescription using the NatNet helper routine NatNet_FreeDescriptions().

    if ( pDataDefs ) {
    NatNet_FreeDescriptions( pDataDefs );
    pDataDefs = NULL; 
    }

4. Get FrameOfMocapData

a. Set Callback Functions

Now that we have data descriptions, let's fetch the corresponding frame-specific tracking data. To do this, a callback handler function needs to be set for processing the incoming frames. First, create a NatNetFrameReceivedCallback function that has the matching input arguments and the return values as described in the NatNetTypes.h file:typedef void (NATNET_CALLCONV* NatNetFrameReceivedCallback)(sFrameOfMocapData* pFrameOfData, void* pUserData);The SampleClient.cpp project sets DataHandler function as the frame handler function.void NATNET_CALLCONV DataHandler(sFrameOfMocapData* data, void* pUserData)

The NatNetClient::SetFrameReceivedCallback method creates a new thread and assigns the frame handler function. Call this method with the created function and the NatNetClient object as its arguments. In the SampleClient application, this is called within the CreateClient function:

//set the callback handlers 
//The DataHandler function will receive data from the server g_pClient -> SetFrameReceivedCallback( DataHandler, theClient ); 

b. Parsing/Handling Frame Data Handling

Once you call the SetDataCallback method to link a data handler callback function, this function will receive a packet of sFrameOfMocapData each time a frame is received. The sFrameOfMocapData contains a single frame data for all of the streamed assets. This allows prompt processing of the capture frames within the handler function.

// set the callback handlers
// The DataHandler function will receive data from the server
g_pClient->SetDataCallback( DataHandler, theClient );

void __cdecl DataHandler(sFrameOfMocapData* data, void* pUserData)
{
    NatNetClient* pClient = (NatNetClient*) pUserData;

    const double softwareLatencyMillisec = (softwareLatencyHostTicks * 1000) / static_cast<double>(g_serverDescription.HighResClockFrequency);

    if(fp)
    _WriteFrame(fp,data);

    int i=0;

    printf("FrameID : %d\n", data->iFrame);
    printf("Timestamp :  %3.2lf\n", data->fTimestamp);
    printf("Latency :  %3.2lf\n", data->softwareLatencyMillisec);

    // FrameOfMocapData params
    bool   bIsRecording = ((data->params & 0x01)!=0);
    bool   bTrackedModelsChanged = ((data->params & 0x02)!=0);

    if(bIsRecording)
    printf("RECORDING\n");

    if(bTrackedModelsChanged)
    printf("Models Changed.\n");

    // Printing Rigid Body Data…
    //…

    // Printing Skeleton Data…
    //…

    // Printing Rigid Body Data…
    //…

    // labeled markers…
    //…

     // force plates…
    //…
}

5. Disconnect

When exiting the program, call Disconnect method to disconnect the client application from the server.

if (g_pClient) {
   g_pClient->Disconnect();
   delete g_pClient;
   g_pClient = NULL;
   }

This page provides an overview of the general data structure used in the NatNet software development kit (SDK) and how the library is used to parse received tracking information.

General Structure

When receiving streamed data using the NatNet SDK library, its data descriptions should be received before receiving the tracking data. NatNet data is packaged mainly into two different formats: data descriptions and frame-specific tracking data. Utilizing this format, the client application can discover which data are streamed out from the server application in advance to accessing the actual tracking data.

For every asset (e.g. reconstructed markers, Rigid Bodies, Skeletons, force plates) included within streamed capture sessions, their descriptions and tracking data are stored separately. This format allows frame-independent parameters (e.g. name, size, and number) to be stored within instances of the description structs, and frame-dependent values (e.g. position and orientation) to be stored within instances of the frame data structs. When needed, two different packets of an asset can be correlated by referencing to its unique identifier values.

• Dataset Descriptions contains descriptions of the motion capture data sets for which a frame of motion capture data will be generated. (e.g. sSkeletonDescription, sRigidBodyDescription)

• Frame of Mocap Data contains a single frame of motion capture data for all the datasets described from the Dataset Descriptions. (e.g. sSkeletonData, sRigidBodyData)

Dataset Descriptions

To receive data descriptions from a connected server, use the NatNetClient::GetDataDescriptionList method. Calling this function saves a list of available descriptions in an instance of sDataSetDescriptions.

The sDataSetDescriptions structure stores an array of multiple descriptions for each of assets (Marker Sets, RigidBodies, Skeletons, and Force Plates) involved in a capture and necessary information can be parsed from it. The following table lists out the main data description structs that are available through the SDK.

Description Struct

Frame of Mocap Data

As mentioned in the beginning, frame-specific tracking data are stored separately from the DataDescription instances as this cannot be known ahead of time or out of band but only by per frame basis. These data gets saved into instances of sFrameOfMocapData for corresponding frames, and they will contain arrays of frame-specific data structs (e.g.sRigidBodyData, sSkeletonData) for each types of assets included in the capture. Respective frame number, timecode, and streaming latency values are also saved in these packets.

The sFrameOfMocapData can be obtained by setting up a frame handler function using the NatNetClient::SetFrameReceivedCallback method. In most cases, a frame handler function must be assigned in order to make sure every frames are promptly processed. Refer to the provided SampleClient project for an exemplary setup.

FrameOfMocapData

Additional Notes

• One reconstructed 3D marker can be stored in two different places (e.g. in LabeledMarkers and in RigidBody) within a frame of mocap data. In those cases, unique identifier values of the marker can be used to correlate them in the client application if necessary.

• Declarations for these data types are listed in the NatNetTypes.h header files within the SDK. The SampleClient project included in the \NatNet SDK\Sample folder illustrates how to retrieve and interpret the data descriptions and frame data.

Unique ID

Most of the NatNet SDK data packets contain ID values. This value is assigned uniquely to individual markers as well as each of assets within a capture. These values can be used to figure out which asset a given data packet is associated with. One common use is for correlating data descriptions and frame data packets of an asset.

Decoding Member IDs

For each member object that is included within a parental model, its unique ID value points to both its parental model and the member itself. Thus, the ID value of a member object needs to be decoded in order to parse which objects and the parent models they are referencing to.

For example, a Skeleton asset is a hierarchical collection of bone Rigid Bodies, and each of its bone Rigid Bodies has unique ID that references to the involved Skeleton model and the Rigid Body itself. When analyzing Skeleton bones, its ID value needs to be decoded in order to extract the segment Rigid Body ID, and only then, it can be used to reference its descriptions.

• NatNet SDK provides a C++ helper function, NatNet_DecodeID, for decoding member ID and model ID of an member object. You can also decode by manually parsing the ID as demonstrated in the WinFormSample or the SampleClientML sample.

NatNet-Matlab Wrapper

To ease your use of NatNet data in MATLAB applications, we provide a wrapper class (natnet.p) for using real-time streamed NatNet data. Using this class, you can easily connect/disconnect to the server, receive the tracking data, and parse each component.

Matlab Wrapper: Setup

The Matlab-NatNet wrapper class is a wrapper for the NatNet assembly and provides a simplified interface for managing the native members in MATLAB. Ther class definition and supporting code should be placed within the MATLAB PATH. The implementation automatically disposes running connections when ending a streaming session, along with basic object management. In order to use the Matlab wrapper class, the NatNetML assembly must be loaded into the MATLAB session. This is handled automatically and the first time the class is used the user is prompted to find the NatNetML.dll file in the Windows file browser. A reference to this location is used in future MATLAB sessions.

Overview

To create an instance of the natnet wrapper class, simply call the class with no input arguments and store it in a variable.

Class Properties: The available properties to the class can be seen with the following command, properties('natnet').

Class Methods: And Available methods

Creating an instance of the class does not automatically connect the object to a host application. After enabling the broadcast frame data under the Data Streaming pane in Motive or in any other server, configure the connection type and IP addresses for the client and host to reflect your network setup.

Then enter the following line to call the connect method for connecting to the natnet object to the host.

When creating a natnet class instance, the default host and client IP address is set to '127.0.0.1', which is the local loopback address of the computer. Ther natnet object will fail to connect if the network address of the host or client is incorrect.

Matlab Wrapper: Polling

The natnet wrapper class interface has a method to poll mocap data called getFrame. getFrame method returns the data structure of the streamed data packet. Polling is supported but not recommended due to accessing errors. The function, poll.m, provides a simple exmple showing out to poll the frames of mocap data. After connecting the natnet object to the host server, run the polling script to acquire the data packets in the main workspace.

Matlab Wrapper: Event Callbacks

The natnet class implements a simple interface to use event callbacks. The natnet method, addlistener, requires two input arguments. The first input is which listener slot to use, and the second is the name of the m-function file to be attached to the listener. Once the function is attached using addlistener method, it will be called each time a frame is received. When the callback function is first created, the listener is turned off by default. This is to ensure the user had control of the execution of the even callback function.

Callback Function

Enabling Listener: Start receiving streamed data by enabling the callback function by calling the enable method. The input of the enable method indicates the index value of the listener to enable. Multiple functions can be attached to the listener, and you can enable a specific listener by inputing its index value. Entering 0 will enable all listeners.

Disabling Listener: There are three types of callback functions that ships with the natnet class. IF they are added to the natnet listener list and enabled, they will execute each time the host sends a frame of data. The setup.m file, contains an example of how to operate the class. To stop streaming, use the disable method and be sure to enter a value of 0 to disable all listeners.

Matlab Wrapper: Motive Control

The natnet class also has functionality to control the Motive application. To enable recording use the startRcord and stopRecord methods, and for playback, use the startPlayback and stopPlayback methods. There are a number of additional commands as shown below.

To display the actions of the class, set the IsReporting property to true. This displays operations of the class to the Command Window.

NatNet SDK

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.

Overview

SDK Contents

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.

Additional Info

• 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: 239.255.42.99 and Port: 1511.

• IP address for unicast is defined by a server application.

File List

The NatNet SDK is shipped in a compressed ZIP file format. Within the unzipped NatNet SDK directory, the following contents are included:

Sample Projects: NatNet SDK\Samples

Library Header Files: NatNet SDK\include

The include folder contains headers files for using the NatNet SDK library.

Library DLL Files: NatNet SDK\lib

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.

API Reference

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

User Documentation Pages

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

Orientation Data in NatNet

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')

Direct Depacketization

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.

Bit-stream Syntax

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.

Bit-stream Version

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)

This page provides function and class references of the NatNet SDK library.

The NatNetClient class (or NatNetClientML from the managed assembly) is the key object of the SDK. An instance of this client class allows an application to connect to a server application and query data. API helper functions are provided with the C++ library for a more convenient use of the SDK tools. For additional information, refer to the provided headers files (native) or reference the NatNatML.dll file (managed).

ErrorCode

Most of the NatNet SDK functions return their operation results in an integer type representation named ErrorType, which is just an enumerator that describes operation results as the following:

NatNetClient Class

The NatNetClient class is the main component of the NatNet SDK. Using an instance of the NatNetClient class, you can establish a network connection with a server application (e.g. Motive) and query data descriptions, tracking data, and send/receive remote commands. For detailed declarations, refer to the NatNetClient.h header file included in the SDK.

Constructor and Destructor

NatNetClient::NatNetClient()

Constructor: Creates a new instance of a NatNetClient class. Defaults to multicast connection if no input is given.

NatNetClient::NatNetClient(iConnectionType)

Constructor: Creates a new instance of a NatNet Client using the specified connection protocol; either unicast or multicast.

Input: iConnectionType: (0 = Multicast, 1 = Unicast).

NatNetClient::~NatNetClient()

Destructor: Destructor

Member Methods

NatNetClient::Connect

ErrorCode        Connect( const sNatNetClientConnectParams& connectParams );

Description

This method connects an instantiated NatNetClient object to a server application (e.g. Motive) at the inputted IP address.

Input Parameters:

• Connection parameters object.

Returns:

ErrorCode, On success, it returns 0 or ErrorCode_OK.

typedef struct sNatNetClientConnectParams
{
    ConnectionType connectionType;
    uint16_t serverCommandPort;
    uint16_t serverDataPort;
    const char* serverAddress;
    const char* localAddress;
    const char* multicastAddress;

#if defined(__cplusplus)
    sNatNetClientConnectParams()
        : connectionType( ConnectionType_Multicast )
        , serverCommandPort( 0 )
        , serverDataPort( 0 )
        , serverAddress( NULL )
        , localAddress( NULL )
        , multicastAddress( NULL )
    {
    }
#endif
} sNatNetClientConnectParams;

NatNetClient::Disconnect

ErrorCode        Disconnect();

Description

Calling this method disconnects the client from the Motive server application.

Input Parameters:

• None

Returns:

ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNetClient::SetFrameReceivedCallback

ErrorCode        SetFrameReceivedCallback( NatNetFrameReceivedCallback pfnDataCallback, void* pUserContext = 0 );

Description

This method sets a frame handler function and creates a new thread for receiving and processing each frame of capture data.

• Managed Assembly: Use OnFrameReady event type to add a function delegate.

Input Parameters:

• pfnDataCallback: A NatNetFrameReceivedCallback function. NatNetFrameReceivedCallback is a type of a pointer to a frame handler function which processes each incoming frame of tracking data. Format of the inputted function must agree with the following type definition:

typedef void (NATNET_CALLCONV* NatNetFrameReceivedCallback)(sFrameOfMocapData* pFrameOfData, void* pUserData);

• User definable data: the Client object.

Returns:

ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNetClient::SendMessageAndWait

ErrorCode	SendMessageAndWait( const char* szRequest, 
                                    void** ppServerResponse, 
                                    int* pResponseSize );

ErrorCode	SendMessageAndWait( const char* szRequest,
                                    int tries, int timeout, 
                                    void** ppServerResponse,
                                    int* pResponseSize );

Description

Sends a NatNet command to the NatNet server and waits for a response. See NatNet: Remote Requests/Commands for more details.

Input Parameters:

• szRequest: NatNet command.

• tries: Number of attempts to send the command. Default: 10.

• timeout: Number of milliseconds to wait for a response from the server before the call times out. Default: 20.

• ppServerResponse: Application defined response.

• pResponseSize: Number of bytes in response

Returns:

ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNetClient::GetServerDescription

ErrorCode        GetServerDescription( sServerDescription* pServerDescription );

Description

Requests a description of the current NatNet server that a client object is connected to and saves it into an instance of sServerDescription. This call is blocked until the request is responded or times out.

Input Parameters:

• Declared sServerDescription object.

Returns:

ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNetClient::GetDataDescriptionList

int   GetDataDescriptions( sDataDescriptions** pDataDescriptions );

Description

Requests a list of dataset descriptions of the capture session and saves onto the declared instance of sDataDescriptions.

Input Parameters:

• Pointer to an sDataDescriptions pointer which receives the address of the client's internal sDataDescriptions object. This pointer is valid until the client is destroyed or until the next call to GetDataDescriptions.

Returns:

ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNetClient::SecondsSinceHostTimestamp

double    SecondsSinceHostTimestamp( uint64_t hostTimestamp ) const;

Description

This method calculates and returns the time difference between a specific event in the processing pipeline and when the NatNet client application receives the tracking data. For example, if sFrameOfMocapData::CameraMideExposureTimestamp is inputted, it will return the latency from the camera exposure to when the tracking data is received. For more information on how it is used, read through the Latency Measurements page.

Input Parameters:

• (uint64_t) A timestamp value from a sFrameOfMocapData struct.

Returns:

(double) The time, in seconds, past since the provided timestamp.

NatNet C++ API Functions

Once the NatNetSDK library has been imported into a client application, the following helper functions can be used.

Function list

NatNet_GetVersion

 NATNET_API void	NATNET_CALLCONV NatNet_GetVersion( unsigned char outVersion[4] );

Description

This function gets the version (#.#.#.#) of the NatNet SDK and saves it into an array.

Input Parameters:

• Unsigned char array with a array length of 4.

Returns:

• Void

NatNet_SetLogCallback

 NATNET_API void	NATNET_CALLCONV NatNet_SetLogCallback( NatNetLogCallback pfnLogCallback );

Description

This function assignes a callback handler function for receiving and reporting error/debug messages.

Input Parameters:

• pfnLogCallback: NatNetLogCallback function. NatNetLogCallback is a type of a pointer to a callback function that is used to handle the log messages sent from the server application. Format of the linked function must agree with the following type definition:

typedef void (NATNET_CALLCONV* NatNetLogCallback)(Verbosity level, const char* message);

Returns:

• Void

NatNet_DecodeID

 NATNET_API void	NATNET_CALLCONV NatNet_DecodeID( int compositeId,
           						int* pOutEntityId,
         						int* pOutMemberId );

Description

Takes an ID of a data set (a marker, a Rigid Body, a Skeleton, or a force plate), and decodes its model ID and member ID into the provided integer variables. For example, ID of a Skeleton bone segment will be decoded into its model ID (Skeleton) and Rigid Body ID (bone). See NatNet: Data Types.

Input Parameters:

• An ID value for a respective data set (sRigidBodyData, sSkeletonData, sMarker, or sFrocePLateData) from a sFrameOfMocapData packet.

• Pointer to declared integer value for saving the entity ID and the member ID (e.g. Skeleton ID and its bone Rigid Body ID).

Returns:

• Void

NatNet_DecodeTimecode

NATNET_API ErrorCode	NATNET_CALLCONV	NatNet_DecodeTimecode( 	unsigned int timecode,
           						unsigned int timecodeSubframe,
              						int* pOutHour, int* pOutMinute,
              						int* pOutSecond, int* pOutFrame,
             						int* pOutSubframe );

Description

Helper function to decode OptiTrack timecode data into individual components.

Input Parameters:

• Timecode integer from a packet of sFrameOfMocapData. (timecode)

• TimecodeSubframe integer from a packet of sFrameOfMocapData. (timecodeSubframe)

• Pointers to declared integer variables for saving the hours (pOutHour), minutes (pOutMinute), seconds (pOutSecond), frames (pOutFrame), and subframes (pOutSubframe) values.

Returns:

• ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNet_TimecodeStringify

NATNET_API ErrorCode	NATNET_CALLCONV NatNet_TimecodeStringify( unsigned int timecode, 
              							unsigned int timecodeSubframe,
              							char* outBuffer,
              							int outBufferSize );

Description

Helper function to parse OptiTrack timecode into a user friendly string in the form hh:mm:ss:ff:yy

Input Parameters:

• timecode: Timecode integer from a packet of sFrameOfMocapData. (timecode)

• timecodeSubframe: TimecodeSubframe integer from a packet of sFrameOfMocapData. (timecodeSubframe)

• outBuffer: Declared char for saving the output.

• outBufferSize: size of the character array buffer (outBuffer).

Returns:

• ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNet_CopyFrame

NATNET_API ErrorCode	NATNET_CALLCONV NatNet_CopyFrame( sFrameOfMocapData* pSrc,
              						sFrameOfMocapData* pDst );

Description

This helper function performs a deep copy of frame data from pSrc into pDst. Some members of pDst will be dynamically allocated; use NatNet_FreeFrame( pDst ) to clean them up.

Input Parameters:

• Pointer to two sFrameOfMocapData variables to copy from (pSrc) and copy to (pDst).

Returns:

• ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNet_FreeFrame

NATNET_API ErrorCode	NATNET_CALLCONV NatNet_FreeFrame( sFrameOfMocapData* pFrame );

Description

Frees the dynamically allocated members of a frame copy created using NatNet_CopyFrame function. Note that the object pointed to by pFrame itself is NOT de-allocated, but only its nested members which were dynamically allocated are freed.

Input Parameters:

• sFrameOfMocapData that has been copied using the NatNet_CopyFrame function.

Returns:

• ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNet_FreeDescriptions

NATNET_API ErrorCode	NATNET_CALLCONV NatNet_FreeDescriptions( sDataDescriptions* pFrame );

Description

Deallocates data descriptions pDesc and all of its members; after this call, this object is no longer valid.

Input Parameters:

• Data descriptions (sDataDescriptions).

Returns:

• ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNet_BroadcastServerDiscovery

NATNET_API ErrorCode	NATNET_CALLCONV NatNet_BroadcastServerDiscovery( sNatNetDiscoveredServer* outServers, int* pInOutNumServers, unsigned int timeoutMillisec = 1000 );

Description

Sends broadcast messages to discover active NatNet servers and blocks for a specified time to gather responses.

Input Parameters:

• outServers: An array of length equal to the input value of pInOutNumServers. This array will receive the details of all servers discovered by the broadcast.

• pInOutNumServers: A pointer to an integer containing the length of the array. After this function returns, the integer is modified to contain the total number of servers that responded to the broadcast inquiry. If the modified number is larger than the original number passed to the function, there was insufficient space for those additional servers.

• timeoutMillisec: Amount of time, in milliseconds, to wait for server responses to the broadcast before returning.

Returns:

• ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNet_CreateAsyncServerDiscovery

NATNET_API ErrorCode	NATNET_CALLCONV NatNet_CreateAsyncServerDiscovery( NatNetDiscoveryHandle* pOutDiscovery, NatNetServerDiscoveryCallback pfnCallback, void* pUserContext = NULL );

Description

Begin sending periodic broadcast messages to discover active NatNet servers in the background.

Input Parameters:

• pOutDiscovery: Out pointer that will receive a handle representing the asynchronous discovery process. The handle returned should be passed to NatNet_FreeAsyncServerDiscovery method later for clean up.

• pfnCallback: A NatNetServerDiscoveryCallback function pointer that will be invoked once for every new server that's discovered by the asynchronous search. The callback will also be passed onto the provided pUserContext argument.

• pUserContext: User-specified context data to be passed to the provided pfnCallback when invoked.

Returns:

• ErrorCode, On success, it returns 0 or ErrorCode_OK.

NatNet_FreeAsyncServerDiscovery

NATNET_API ErrorCode	NATNET_CALLCONV NatNet_CreateAsyncServerDiscovery( NatNetDiscoveryHandle* pOutDiscovery, NatNetServerDiscoveryCallback pfnCallback, void* pUserContext = NULL );

Description

Begin sending periodic broadcast messages to continuously search and discover active NatNet servers in the background.

Input Parameters:

• pOutDiscovery: Out pointer that will receive a handle representing the asynchronous discovery process. The handle returned should be passed to NatNet_FreeAsyncServerDiscovery method later for clean up.

• pfnCallback: A NatNetServerDiscoveryCallback function pointer that will be invoked once for every new server that's discovered by the asynchronous search. The callback will also be passed onto the provided pUserContext argument.

• pUserContext: User-specified context data to be passed to the provided pfnCallback when invoked.

Returns:

• ErrorCode, On success, it returns 0 or ErrorCode_OK.

This page is created to guide help users migrating their NatNet projects onto NatNet 3.0 libraries.

Statically Linked Libraries

NatNet 3.0 no longer allows static linking of the libraries. If a NatNet project was utilizing NatNetLibStatic.lib to accomplish static linking, you will need to make changes to the project configurations, so that it links dynamically instead.

Rigid Body Marker Data

In NatNet 3.0, the structure of Rigid Body descriptions and Rigid Body frame data has been slightly modified. The sRigidBodyData:Markers member has been removed, and instead, the Rigid Body description (sRigidBodyDescription) now includes the expected Rigid Body marker positions in respect to the corresponding RB orientation axis.

Per-frame positions of Rigid Body markers have to be derived using the Rigid Body tracking data and the expected Rigid Body markers positions included in the description packet.

This page lists out the NatNet sample applications provided with the SDK and provides instructions for some of the samples. The code samples are the quickest path towards getting NatNet data into your application. We typically recommend you:

1. Identify your application’s development/interface requirements (managed, native, etc).2. Adapt the NatNet sample code from the corresponding NatNet sample application in the samples folder into your application.3. Use the API reference in the next page for additional information.

The Visual Studio solution file \Samples\NatNetSamples.sln will open and build all of the NatNet sample projects. If you are creating an application from scratch, please refer to the following sections for application specific requirements.

NatNet Sample Projects

The following projects are located in the NatNet SDK\Samples folder.

NatNet SDK Samples

The following sample projects utilizes NatNet SDK library for obtaining tracking data from a connected server application.

Direct Depacketization Samples

The following sample projects do not use the NatNet SDK library. Client/Server connection is established at a low-level by creating sockets and threads within the program, and the streamed data are depacketized directly from the bit-stream syntax. The following sample approaches should be used only when the use of NatNet SDK library is not applicable (e.g. streaming into UNIX clients).

XML trigger broadcast

The following samples demonstrate how to use remote triggering in Motive using the XML formatted UDP broadcast packets.

Running the Console Output Sample (Sample Client)

On Windows

1. [Motive] Start the Optitrack Server (e.g. Motive) and begin streaming data via the Streaming Panel.

2. [SampleClient] Start the client application from the command prompt or directly from the NatNet SDK/Samples/bin folder.

3. [SampleClient] Once the sample application starts up, it will search the local network and list out IP addresses of available tracking servers where tracking data is streamed from. Select a server address by pressing the corresponding number key.

4. [SampleClient] The client application is connected to the local loopback address (127.0.0.1) and receiving tracking data.

Running the Rigid Body Sample (SampleClient3D)

The Rigid Body sample (SampleClient3D) illustrates how to decode NatNet 6DOF Rigid Body and Skeleton Segment data from OptiTrack quaternion format to euler angles and display them in a simple OpenGL 3D viewer. This sample also illustrates how to associate RigidBody/Skeleton Segment names and IDs from the data descriptions with the IDs streamed in the FrameOfMocapData packet.

With Client/Server on same machine:

1. [Motive] Load a dataset with Rigid Body or Skeleton definitions

2. [Motive] Enable network streaming ( Data Streaming Pane -> Check Broadcast Frame Data )

3. [Motive] Enable streaming Rigid Body data (check Stream Options -> Stream Rigid Bodies = True)

4. [Sample3D] File -> Connect

With Client/Server on separate machines:

1. [Motive] Load a dataset with Rigid Body or Skeleton definitions

2. [Motive] Set IP address to stream from (Network Interface Selection -> Local Interface)

3. [Motive] Enable network streaming ( Data Streaming Pane -> Check Broadcast Frame Data )

4. [Motive] Enable streaming Rigid Body data (check Stream Options -> Stream Rigid Bodies = True)

5. [Sample3D] Set Client and Server IP addresses

6. [Sample3D] File -> Connect

• IP Address IP Address of client NIC card you wish to use.

• Server IP Address IP Address of server entered in step 2 above.

Running the .NET Sample

1. [Motive] Start a NatNet server application (e.g. Motive).

2. [Motive] Enable NatNet streaming from the Server application.

3. [WinFormTestApp] Start the WinForms sample application from the NatNet Samples folder.

4. [WinFormTestApp] Update the “Local” and “Server” IP Addresses as necessary.

5. [WinFormTestApp] Press the “Connect” button to connect to the server.

6. [WinFormTestApp] Press the “Get Data Descriptions” button to request and display a detailed description of the Server’s currently streamed objects.

7. [WinFormTestApp] Select a Row in the DataGrid to display that value in the graph.

Running the Matlab Sample

1. [Motive] Start a NatNet server application (e.g. Motive).

2. [Motive] Enable NatNet streaming from the Server application.

3. [Matlab] Start Matlab

4. [Matlab] Open the NatNetPollingSample.m file.

5. [Matlab] From the editor window, press Run

Rebroadcast Motive Data sample. This is a sample NatNet application that receives tracking data from a NatNet Server (Motive) and redistributes it in other formats.

Currently, there are two supported protocols in this sample; Unity and LightCraft. The Unity protocol repackages mocap data into XML packets and delivers it to the unity game engine. The LightCraft protocol takes definitions for a single Rigid Body and sends them over a serial port in a format called the Spydercam protocol. The LightCraft protocol in addition to being a demonstration of serial port communication, it allows Motive and Previzion to be completely compatible, using Mocap data to track the Previzion camera.

Unity Protocol

Rebroadcasts data into a XML format compatible for unity.

Previzion Protocol

Rebroadcasts data via Spyder Cam protocol which

Requirements

The following third-party library must be linked in order to build and run this sample application

• Asio library () : Required for communicating tracking data through serial port communication.

Build

• Download the asio C++ library.

• In the RebroadcastMotiveData VS project, link the downloaded library.

• Build the sample project.

Running the Sample

You can run the app from the command line with appropriate input arguments. For example: RebroadcastMotiveData.exe 127.0.0.1 127.0.0.1 unity There are total four arguments that can be inputed when running the sample application.

• argument 1: IP address of the server, Motive, machine

• argument 2: When streaming to unity, input the IP address of the local machine. When streaming to the lightcraft protocol, input local serial port name (e.g. COM1)

• argument 3: Protocol type [unity/lightcraft]

• argument 4 (optional): Input test, to run in the test mode.

Remote Requests/Commands

The NatNet SDK features sending remote commands/requests from a client application over to a connected server application (i.e. Motive).

The SendMessageAndWait method under NatNetClient class is the core method for sending remote commands. This function takes in a string value of the command and sends it over to the connected Motive server each time it's called, and once the server receives the remote command, corresponding actions will be performed. Please note that only a selected set of commands can be understood by the server, which are listed under the chart below.

NatNet commands are sent via the UDP connection, 1510 port by default.

NatNetClient::SendMessageAndWait

Description

Sends a NatNet command to the NatNet server and waits for a response.

Input Parameters:

• szRequest: NatNet command string, which is one of the commands listed on the below chart. If the command requires input parameters, corresponding parameters should be included in the command with comma delimiters. (e.g. string strCommand = "SetPlaybackTakeName," + TakeName;).

• tries: Number of attempts to send the command. Default: 10.

• timeout: Number of milliseconds to wait for a response from the server before the call times out. Default: 20.

• ppServerResponse: Server response for the remote command. The response format depends on which command is sent out.

• pResponseSize: Number of bytes in response

Returns:

ErrorCode, On success, it returns 0 or ErrorCode_OK.

Remote Commands

Motive Supported NatNet Commands/Requests

Subscription Commands

Supported for Motive 3.0 or above.

Following is a general format used for the subscription command strings:

• SubscribeToData,[DataType],[All or specific asset]

• SubscribeByID,[DataType],[ID]

Sample Use

Start Recording

Framerate Query

Setting name of the recorded Take

Setting Motive Properties

The following guide references SampleClientML.cs client application that is provided with the SDK. This sample demonstrates the use of .NET NatNet assembly for connecting to a NatNet server, receiving a data stream, and parsing and printing out the received data.

1. NatNet Library

When developing a managed client applications, you will need to link both native and managed DLL files(NatNetLib.dll and NatNetML.dll). The managed NatNet assembly is derived from the native library, so without the NatNetLib.dll, NatNetML.dll will not be imported properly. These library files can be found in the NatNetSDK\lib folder for 32-bit platform and in the NatNetSDK\lib\x64 folder for 64-bit platform. Make sure these DLL files are properly linked and placed alongside the executables.

Also, when using the NatNetML assembly, place the NatNetML.xml file alongside imported DLL file. This allows XML documentation to be included as a reference. These library files can be found in the NatNetSDK\lib folder for 32-bit platform and in the NatNetSDK\lib\x64 folder for 64-bit platform. Make sure these DLL files are properly linked and placed alongside the executables.

2. Connect

a. Create a NatNetClientML object

Tracking server and client network is established through an instance of NatNet client object (NatNetML.NatNetClientML). Also, this NatNetClientML object will be used for receiving tracking data and sending NatNet commands to and from the server application. When instantiating the NatNetClientML object, input an integer value for determining the desired type of UDP connection; whether it connects via multicast (0) or unicast (1).

[C#] SampleClientML.cs : Instantiating NatNetClientML

/*  [NatNet] Network connection configuration    */
private static NatNetML.NatNetClientML m_NatNet;    // The client instance
private static string strLocalIP = "127.0.0.1";     // Local IP address (string)
private static string strServerIP = "127.0.0.1";    // Server IP address (string)
private static int iConnectionType = 0;             // Connection Type

static void connectToServer()
{
    /*  [NatNet] Instantiate the client object  */
    m_NatNet = new NatNetML.NatNetClientML(iConnectionType);

    /*  [NatNet] Checking verions of the NatNet SDK library  */
    int[] verNatNet = new int[4];           // Saving NatNet SDK version number
    verNatNet = m_NatNet.NatNetVersion();
    Console.WriteLine("NatNet SDK Version: {0}.{1}.{2}.{3}", verNatNet[0], verNatNet[1], verNatNet[2], verNatNet[3]);
 
    /*  [NatNet] Connecting to the Server    */
    Console.WriteLine("\nConnecting...\n\tLocal IP address: {0}\n\tServer IP Address: {1}\n\n", strLocalIP, strServerIP);
    m_NatNet.Initialize(strLocalIP, strServerIP);
}

b. Connect to Server

To connect to the server, use the Initialize method from the instantiated NatNetClientML object. When calling this method, input the proper Local IP address and the Server IP address. The local IP address must match the IP address of the host PC, and the server IP address must match the address that the server is streaming onto, which is defined in the Data Streaming panel in Motive.

[C#] SampleClientML.cs : Connect to Server. Initialize

/*  [NatNet] Network connection configuration    */
private static NatNetML.NatNetClientML m_NatNet;    // The client instance
private static string strLocalIP = "127.0.0.1";     // Local IP address (string)
private static string strServerIP = "127.0.0.1";    // Server IP address (string)
private static int iConnectionType = 0;             // Connection Type

static void connectToServer()
{
    /*  [NatNet] Instantiate the client object  */
    m_NatNet = new NatNetML.NatNetClientML(iConnectionType);

    /*  [NatNet] Checking verions of the NatNet SDK library  */
    int[] verNatNet = new int[4];           // Saving NatNet SDK version number
    verNatNet = m_NatNet.NatNetVersion();
    Console.WriteLine("NatNet SDK Version: {0}.{1}.{2}.{3}", verNatNet[0], verNatNet[1], verNatNet[2], verNatNet[3]);

    /*  [NatNet] Connecting to the Server    */
    Console.WriteLine("\nConnecting...\n\tLocal IP address: {0}\n\tServer IP Address: {1}\n\n", strLocalIP, strServerIP);
    m_NatNet.Initialize(strLocalIP, strServerIP);
}

c. Confirm connection

To confirm whether the client has successfully connected to the server application, let's try querying for a ServerDescriptor packet using the GetServerDescription method. If the server is connected, the corresponding server descriptions will be obtained. This method returns an ErrorCode value, and when successfully operated it will return a value of 0.

[C#] SampleClientML.cs : GetServerDescription

static bool fetchServerDescriptor()
{
    NatNetML.ServerDescription m_ServerDescriptor = new NatNetML.ServerDescription();
    int errorCode = m_NatNet.GetServerDescription(m_ServerDescriptor);

    if (errorCode == 0)
    {
        Console.WriteLine("Success: Connected to the server\n");
        parseSeverDescriptor(m_ServerDescriptor);
        return true;
    }
    else
    {
        Console.WriteLine("Error: Failed to connect. Check the connection settings.");
        Console.WriteLine("Program terminated (Enter ESC to exit)");
        return false;
    }
}

3. Get DataDescriptions

As explained in the NatNet: Data Types page, there are two kinds of data formats included in streamed NatNet packets; one of which is Data Descriptions. In managed NatNet assembly, data descriptions for each of the assets (Marker Sets, Rigid Bodies, Skeletons, and force plates) included in the capture session is stored in a DataDescriptor class. A single capture take (or live streaming) may contain more than one assets, and respectively, there may be more than one data descriptions. For this reason, data descriptions are stored in a list format.

a. GetDataDescription

GetDataDescriptions method in the NatNetClientML class queries a list of DataDescriptors from the connected server and saves it in a declared list of NatNetML.DataDescriptions. In the SampleClientML sample, the following lines are executed to accomplish this:

[C#] SampleClientML.cs : GetDataDescription

/*  List for saving each of datadescriptors */
private static List<NatNetML.DataDescriptor> m_DataDescriptor = new List<NatNetML.DataDescriptor>();

static void fetchDataDescriptor()
{
    /*  [NatNet] Fetch Data Descriptions. Instantiate objects for saving data descriptions and frame data    */        
    bool result = m_NatNet.GetDataDescriptions(out m_DataDescriptor);

    if (result)
    {
        Console.WriteLine("Success: Data Descriptions obtained from the server.");
        parseDataDescriptor(m_DataDescriptor);
    }
    else
    {
        Console.WriteLine("Error: Could not get the Data Descriptions");
    }
        Console.WriteLine("\n");
}

b. ParseDataDescription

After obtaining a list of data descriptions, use the saved DataDescriptor objects to access and output data descriptions as needed. In many cases, it is better to re-organize and save the received descriptor objects into separate lists, or into hashtables, of corresponding data types, so that they can be referenced later in the program.

[C#] SampleClientML.cs : Parsing/Saving Data Descriptions

static void parseDataDescriptor(List<NatNetML.DataDescriptor> description)
{
    //  [NatNet] Request a description of the Active Model List from the server. 
    //  This sample will list only names of the data sets, but you can access 
    int numDataSet = description.Count;
    Console.WriteLine("Total {0} data sets in the capture:", numDataSet);

    for (int i = 0; i < numDataSet; ++i)
    {
        int dataSetType = description[i].type;
        // Parse Data Descriptions for each data sets and save them in the delcared lists and hashtables for later uses.
        switch (dataSetType){
            case ((int) NatNetML.DataDescriptorType.eMarkerSetData):
                  NatNetML.MarkerSet mkset = (NatNetML.MarkerSet)description[i];
                  Console.WriteLine("\tMarkerSet ({0})", mkset.Name);
                  break;

            case ((int) NatNetML.DataDescriptorType.eRigidbodyData):
                  NatNetML.RigidBody rb = (NatNetML.RigidBody)description[i];
                  Console.WriteLine("\tRigidBody ({0})", rb.Name);

                  // Saving Rigid Body Descriptions
                  mRigidBodies.Add(rb);
                  break;

            case ((int) NatNetML.DataDescriptorType.eSkeletonData):
                  NatNetML.Skeleton skl = (NatNetML.Skeleton)description[i];
                  Console.WriteLine("\tSkeleton ({0}), Bones:", skl.Name);
 
                  //Saving Skeleton Descriptions
                  mSkeletons.Add(skl);
 
                  // Saving Individual Bone Descriptions
                  for (int j = 0; j < skl.nRigidBodies; j++)
                  {
                      Console.WriteLine("\t\t{0}. {1}", j + 1, skl.RigidBodies[j].Name);
                      int uniqueID = skl.ID * 1000 + skl.RigidBodies[j].ID;
                      int key = uniqueID.GetHashCode();
                      htSkelRBs.Add(key, skl.RigidBodies[j]); //Saving the bone segments onto the hashtable
                  }
                  break;

            case ((int) NatNetML.DataDescriptorType.eForcePlateData):
                    NatNetML.ForcePlate fp = (NatNetML.ForcePlate)description[i];
                    Console.WriteLine("\tForcePlate ({0})", fp.Serial);

                    // Saving Force Plate Channel Names
                    mForcePlates.Add(fp);
         
                    for (int j = 0; j < fp.ChannelCount; j++)
                    {
                          Console.WriteLine("\t\tChannel {0}: {1}", j + 1, fp.ChannelNames[j]);
                    }
                    break;

            default:
                  // When a Data Set does not match any of the descriptions provided by the SDK.
                  Console.WriteLine("\tError: Invalid Data Set");
                  break;
    }
  }
}

4. Get Frame Data

Now, let's obtain the tracking data from the connected server. Tracking data for a captured frame is stored in an instance of NatNetML.FrameOfMocapData. As explained in the Data Types page, every FrameOfMocapData contains tracking data of the corresponding frame. There are two approaches for obtaining frame data using the client object; by calling the GetLastFrameOfData method or by linking a callback handler function using the OnFrameReady method. In general, creating a callback function is recommended because this approach ensures that every frame of tracking data gets received.

a. Callback Handler (OnFrameReady)

The best way to receive tracking data without losing any of its frames is to create a callback handler function for processing the data. The OnFrameReady event type from the client object can be used to declare a callback event, and the linked function gets called each time a frame is received from the server. Setting up a frame handler function will ensure that every frame gets processed promptly. However, these handler functions should return as quickly as possible to prevent accumulation of frames due to processing latency within the handler.

m_NatNet.OnFrameReady += new NatNetML.FrameReadyEventHandler(frameHandlerFunction);

• OnFrameReady2: Alternate function signatured frame ready callback handler for .NET applications/hosts that don't support the OnFrameReady event type defined above (e.g. MATLAB)

[C#] SampleClientML.cs : Frame Data Callback Handler

Console.WriteLine("============================= FRAME OF DATA ===================================\n");
Console.WriteLine("Now Fetching the Frame Data\n");

/*  [NatNet] Assigning a event handler function for fetching frame data each time a frame is received   */
m_NatNet.OnFrameReady += new NatNetML.FrameReadyEventHandler(parseFrameData);

Console.WriteLine("Success: Data Port Connected \n");

/// [NatNet] parseFrameData will be called when a frame of Mocap data has is received from the server application
static void parseFrameData(NatNetML.FrameOfMocapData data, NatNetML.NatNetClientML client)
{

    /*  Exception handler for cases where assets are added or removed.
    Data description is re-obtained in the main function so that contents
    in the frame handler function is kept minimal. */

    if (( data.bTrackingModelsChanged == true || data.nRigidBodies != mRigidBodies.Count ||
      data.nSkeletons != mSkeletons.Count || data.nForcePlates != mForcePlates.Count))
    {
              assetChanged = true;
    }

    /*  Processing and outputting frame data every 200th frame.
    This conditional statement is included in order to simplify the program output */

    if(data.iFrame % 200 == 0)
    {
        if (data.bRecording == false)
        Console.WriteLine("Frame #{0} Received:", data.iFrame);
    
    else if (data.bRecording == true)
        Console.WriteLine("[Recording] Frame #{0} Received:", data.iFrame);
        processFrameData(data);
    }
}

b. Single Frame (GetLastFrameOfData)

Calling the GetLastFrameOfData method returns a FrameOfMocapData of the most recent frame that was streamed out from the connected server application. This approach is should only be used for .NET applications/hosts that do not support the OnFrameReady callback handler function.

FrameOfMocapData data = m_NatNet.GetLastFrameOfData();

5. Disconnect

When exiting the program, call Uninitialize method using the connected client object and disconnect the client application from the server.

[C#] SampleClientML.cs : Disconnect

    /*  [NatNet] Disabling data handling function   */
    m_NatNet.OnFrameReady -= parseFrameData;

    /*  Clearing Saved Descriptions */
    mRigidBodies.Clear();
    mSkeletons.Clear();
    htSkelRBs.Clear();
    mForcePlates.Clear();

    /*  Disconnecting from the Server  */
    m_NatNet.Uninitialize();
} // End. Main()

This page provides detailed information on the definition of latency measurements in Motive and the NatNet SDK streaming protocol.

Overview

The OptiTrack systems combine state of art technologies to provide swift processing of captured frame data in order to accomplish 3D tracking in real-time. However, minimal processing latencies are inevitably introduced throughout processing pipelines. For timing-sensitive applications, these latency metrics can be monitored from the Status Panel of Motive or in the NatNet SDK 4.0 streaming protocol.

Latency Simplified

The latency in an OptiTrack system can be broken down in the the components described in the image below.

With Motive 3.0+ PrimeX cameras now can go at up to 1000 Hz. In order to do this the image size processes reduces as the frequency goes over the native frame rate for a particular camera. Because less camera data is being process at higher rates, the latency also decreases. The image below shows how the latency changed from the previous image by going from 240 Hz to 500 Hz with PrimeX 13 cameras.

Example frame rates vs the latency added by the camera for a PrimeX 41 camera....

Latency Details

In Motive

System Latency

• This measurement is reported in the Status Panel in Motive.

• (Available for Ethernet camera systems only) This value represents current system latency. This is reported under the Status Panel, and it represents the total time taken from when the cameras expose and when the data is fully solved.

Software Latency (Motive)

• This measurement is reported in the Status Panel in Motive.

• It represents the amount of time it takes Motive to process each frame of captured data. This includes the time taken for reconstructing the 2D data into 3D data, labeling and modeling the trackable assets, displaying in the viewport, and other processes configured in Motive.

• Please note that this does not include the time it takes for Motive to convert the solved data into the NatNet streaming protocol format. This conversion accounts for a slight additional latency (≈ 0.2 ms) which is only reflected in the software latency value reported via NatNet SDK 4.0, therefore resulting in a small delta between the software latency values as reported by Motive and NatNet.

Pipeline Specific Latencies

• Latencies from the point cloud reconstruction engine, Rigid Body solver, and Skeleton solver are reported individually on the Status Panel in Motive.

In NatNet

In NatNet 3.0, new data types have been introduced to allow users to monitor measured timestamps from specific points in the pipeline. From sFrameOfMocapData received in the NatNet client applications, the following timestamps can be obtained:

• Timestamp of Point A: sFrameOfMocapData::CameraMidExposureTimestamp. Available for Ethernet cameras only (Prime / Slim13E).

• Timestamp of Point B: sFrameOfMocapData::CameraDataReceivedTimestamp.

• Timestamp of Point D: sFrameOfMocapData::TransmitTimestamp.

• Refer to the NatNet:_Data_Types page or the NatNetTypes.h file for more information

These timestamps are reported in “ticks” that are provided by the host computer clock. When computing latencies, you need to divide the timestamp values by the clock frequency in order to obtain the time values in seconds. The clock frequency is included in the server description packet: sServerDescriptionPacket::HighResClockFrequency. To calculate the time that has elapsed since a specific timestamp, you can simply call the NatNetClient::SecondsSinceHostTimestamp method, passing the desired timestamp as its input. Using clock synchronization between the client and server, this will return the time in seconds since the corresponding timestamp.

System Latency (NatNet)

• (Available for Ethernet camera systems only)

• This is the latency introduced by both hardware and software component of the system. This represents the time difference between when the cameras expose and when the capture data is all processed and prepared to be streamed out.

• This value needs to be derived from the NatNet SDK 4.0 streaming protocol by subtracting two timestamp values that are reported in NatNet:

const bool bSystemLatencyAvailable = data->CameraMidExposureTimestamp != 0;

// From SampleClient.cpp (522 ~ 531)
if ( bSystemLatencyAvailable )
{
 
        const uint64_t systemLatencyHostTicks = data->TransmitTimestamp - data->CameraMidExposureTimestamp;
        const double systemLatencyMillisec = (systemLatencyHostTicks * 1000) / static_cast<double>(g_serverDescription.HighResClockFrequency);
}

Software Latency (NatNet)

• This value needs be derived from the NatNet streaming protocol.

• This latency value represents the time it takes Motive to process the captured data and have it fully ready to be streamed out. This measurement also covers the data packaging time.

• This can be derived by subtracting two timestamp values that are reported in NatNet:

// From SampleClient.cpp (502~503)
const uint64_t softwareLatencyHostTicks = data->TransmitTimestamp - data->CameraDataReceivedTimestamp;
const double softwareLatencyMillisec = (softwareLatencyHostTicks * 1000) / static_cast<double>(g_serverDescription.HighResClockFrequency);

Transmission Latency

• This value must be derived from the NatNet SDK 4.0 streaming protocol.

• The transmission latency represents the time difference between when Motive streams out the packaged tracking data and when the data reaches the client application(s) through a selected network.

• This value can be obtained by calling the SecondsSinceHostTimestampmethod using sFrameOfMocapData::TransmitTimestamp as the input.

// From SampleClient.cpp (507)
const double transitLatencyMillisec = pClient->SecondsSinceHostTimestamp( data->TransmitTimestamp ) * 1000.0;

Client Latency

• This value must be derived from the NatNet SDK 4.0 streaming protocol.

• The client latency is the time difference between when the cameras expose and when the NatNet client applications receive the processed data. This is basically the total time it takes for a client application(s) to receive the tracking data from a mocap system.

• This value can be obtained by calling the SecondsSinceHostTimestamp method using sFrameOfMocapData::CameraMidExposureTimestamp as the input.

// Sample code
const bool bSystemLatencyAvailable = data->CameraMidExposureTimestamp != 0;

if ( bSystemLatencyAvailable )
{
    const double clientLatencyMillisec = pClient->SecondsSinceHostTimestamp(data->CameraMidExposureTimestamp) * 1000.0;
}

Latency in Older Versions

In previous versions of Motive (prior to 2.0), the only reported latency metric was the software latency. This was an estimation of the software latency derived from the sum of the processing times taken from each of the individual solvers in Motive. The latency calculation in Motive 2.0 is a more accurate representation and will be slightly larger by comparison than the latency reported in the older versions.

Troubleshooting

This page provides instructions on how to use the subscribe commands in natNet. This feature is supported for Unicast streaming clients only.

Overview

Starting from Motive 3.0, the size of the data packets that are streamed over Unicast can be configured from each NatNet client. More specifically, each client can now send commands to the Motive server and subscribe to only the data types that they need to receive. For situations where we must stream to multiple wireless clients through Unicast, this will greatly reduce the size of individual frame data packets, and help to ensure that each client continuously receives frame data packets streamed out from Motive.

Notes

• Supported for Unicast only.

• Supported for Motive versions 3.0 or above.

• This configuration is not necessary when streaming over a wired network since streaming packets are less likely to be dropped.

• To make sure the packet size is minimized, it is recommended to clear out the filter at the beginning.

Use

In order to set which type of tracking data gets included in the streamed packets, a filter must be set by sending subscription commands to Motive. This filter will allow client applications to receive only the desired data over a wireless Unicast network. To setup the filter, each NatNet client application(s) needs to call the method and send one of the following subscribe subscription command to the Motive server:

• “SubscribeToData, [Data Type], [Name of the Asset]”

• “SubscribeByID, RigidBody, [StreamingID]”

• “SubscribedDataOnly”

Examples:

SubscribeToData

Type

In the Type field, you will be specifying which data type to subscribe to. The following values are accepted:

• RigidBody

• Skeleton

• ForcePlate

• Device

• LabeledMarkers

• MarkersetMarkers

• LegacyUnlabeledMarkers

• AllTypes

Name

Once the type field is specified, you can also subscribe to a specific asset by inputting the name of the rigid body. You can also input "All" or leave the name field empty to subscribe to all of the assets in that data type.

Examples

If you wish to subscribe to a Rigid Bodynamed Bat, you will be sending the following string command:

You can also subscribe to specific Skeleton also. The following command subscribes to Player Skeleton only:

To subscribe to all rigid bodies in the data stream:

SubscribeByID

Examples

For subscribing to a Rigid Bodywith streaming ID 3: <source>string command = "SubscribeByID,RigidBody,3";</source>

Multiple Filters

Subscription filters are additive. When needed, you can send multiple subscription commands to set multiple filters. If a subscription filter contradicts one another, the order of precedence listed (high-to-low) below is followed:

Filter Precedence Order:

1. Specified asset, either by name or the streaming ID.

2. Specified data type, all

3. Specified data type, none

4. All types, all

5. All types, none

6. Unspecified – respects Motive settings.

Unsubscribing / Clearing Filters

To clear the subscription filter, a client application can send an empty subscribe command OR disconnect and reconnect entirely. It’s suggested to clear the filter at the beginning to make sure the client application(s) is subscribing only to the data that’s necessary.

If you subscribe to a Rigid Bodywith a specific name or specific streaming ID, commands for unsubscribing to all will not unsubscribe to that specific object. To stop receiving data for a particular object, whether it's a Rigid Bodyor a Skeleton, the client will need to send an unsubscribe command for that specific object also.

Testing Commands Using Sample Project