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;
   }

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 (http://think-async.com/) : 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.

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.

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.

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 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 SendMessageAndWait 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:

NatNetClient natnetClient;

// Sets the filter so that the client receives only 6DOF data from RigidBody-1 tracking. 
natnetCient.SendMessageAndWait("SubscribeToData,RigidBody,RigidBody-1") 

// Sets the filter so that the client receives data from assets with specific streaming ID 
natnetClient.SendMessageAndWait("SubscribeByID,RigidBody,2")

SubscribeToData

The SubscribeToData command allows you set up the filter so that NatNet client receives only the data types that it has subscribed to. Using this command, each client can subscribe to specific data types included in NatNet data packets. To set up the filter, the following string command must be sent to the Motive server using SendMessageAndWait method:

string command = "SubscribeToData,[Type],[Name]

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:

string command = "SubscribeToData,RigidBody,Bat";

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

string command = "SubscribeToData,Skeleton,Player";

To subscribe to all rigid bodies in the data stream:

string command = "SubscribeToData,RigidBody,all";

SubscribeByID

Another option for subscribing to a specific data is by providing the asset ID. This works only with rigid bodies that has Streaming ID values. This command may be easier to use when streaming to multiple clients with many rigid bodies.

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.

// Clearing the filter
NatNetClient natnetClient;

//Clearing the subscription filter to all assets
natnetClient.SendMessageAndWait(“SubscribeToData”)
natnetClient.SendMessageAndWait(“SubscribeByID”)

//Clearing subscription filter for a Rigid Bodywith Streaming ID 3.
natnetClient.SendMessageAndWait("SubscribeByID,RigidBody,3");

//Unsubscribing to a Rigid Bodywith streaming ID 3 and a Skeleton named "Josh"
natnetClient.SendMessageAndWait("SubscribeByID,RigidBody,3,None");  
natnetClient.SendMessageAndWait("SubscribeToData,Skeleton,Josh,None");

Testing Commands Using Sample Project

For quickly testing the NatNet commands, you can utilize the WinFormSamples program provided in the NatNet SDK package. This program has commands tab which can be used for calling the SendMessageAndWait method. Using this input field, you can test the command string to test out its results.

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 remote commands chart below.

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

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.

Input Parameters:

• szRequest: NatNet command string, which is one of the commands listed on the below remote commands 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

string command = "LiveMode";

Subscription Commands

Supported for Motive 3.0 or above.

Subscription commands work with Unicast streaming protocol only. When needed, unicast clients can send subscription commands to receive only specific data types through the data stream. This allows users to minimize the size of streaming packets. For more information, read through the NatNet: Unicast Data Subscription Commands page.

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

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

• SubscribeByID,[DataType],[ID]

Sample Use

Below is a sample use of the NatNet commands from the WinFormsSample application.

Start Recording

private void RecordButton_Click(object sender, EventArgs e)
{
	string command = "StartRecording";

	int nBytes = 0;
	byte[] response = new byte[10000];
	int rc = m_NatNet.SendMessageAndWait(command, 3, 100, out response, out nBytes);
	if (rc != 0)
	{
		OutputMessage(command + " not handled by server");
	}
	else
	{
		int opResult = System.BitConverter.ToInt32(response, 0);
		if (opResult == 0)
			OutputMessage(command + " handled and succeeded.");
		else
			OutputMessage(command + " handled but failed.");
	}
}

Framerate Query

// [NatNet] [optional] Query mocap server for the current camera framerate
int nBytes = 0;
byte[] response = new byte[10000];
int rc;
rc = m_NatNet.SendMessageAndWait("FrameRate", out response, out nBytes);

if (rc == 0)
{
    try
    {
        m_ServerFramerate = BitConverter.ToSingle(response, 0);
        OutputMessage(String.Format("   Camera Framerate: {0}", m_ServerFramerate));
    }
    catch (System.Exception ex)
    {
        OutputMessage(ex.Message);
    }
}

Setting name of the recorded Take

private void SetRecordingTakeButton_Click(object sender, EventArgs e)
{
    int nBytes = 0;
    byte[] response = new byte[10000];
    String strCommand = "SetRecordTakeName," + RecordingTakeNameText.Text;
    int rc = m_NatNet.SendMessageAndWait(strCommand, out response, out nBytes);
}

Setting Motive Properties

private void SetPropertyButton_Click(object sender, EventArgs e)
{
    int nBytes = 0;
    byte[] response = new byte[10000];
    string command = "SetProperty," + NodeNameText.Text + "," + PropertyNameText.Text + "," + PropertyValueText.Text;
    int rc = m_NatNet.SendMessageAndWait(command, out response, out nBytes);
    if (rc != 0)
    {
         OutputMessage(command + " not handled by server");
     }
    else
    {
        int opResult = System.BitConverter.ToInt32(response, 0);
        if (opResult == 0)
            OutputMessage(command + " handled and succeeded.");
        else
            OutputMessage(command + " handled but failed.");
    }
}

Overview

The Motive API allows control of, and access to, the backend software platform of Motive via C/C++ interface. In other words, the Motive API offers Motive functions without the graphical user interface on top. Using the API, you can employ several features of Motive in your custom applications, such as accessing 2D camera images, marker centroid data, unlabeled 3D points, labeled markers, and Rigid Body tracking data. When you install Motive, all of the required components for utilizing the API are installed within the Motive install directory. The key files for using the Motive API are listed in the below section.

What it offers:

• Camera control

• Frame control

• Point Cloud reconstruction engine control

• Obtain and use reconstructed 3D Marker data

• Rigid body tracking

• Query results

• Stream results over the network

What it doesn't offer

• In-depth hardware control (e.g. hardware sync customization). Use the Camera SDK instead.

• Direct support for data recording and playback.

• Control over peripheral devices (Force plates and NI-DAQ)

• Functionalities for Skeleton assets.

Requirements

• The Motive API is supported in Windows only

• Must have a valid Motive license and a corresponding Hardware key.

Files List

When you install Motive, all of the required components of the Motive API will be placed within the installation directory, and by default, Motive is installed in C:\Program Files\OptiTrack\Motive. The following table lists all of the key files of the API and where they could be found.

API Guide / Function Reference

This guide introduces some of the commonly used functions of the Motive API.

The following page provides a full list of the Motive API functions.

NPRESULT & VIDEO TYPES

Also, camera video types, or image processing modes, are expressed as integer values as well. These values are listed below and are commented within the header file as well.

NPRESULT Values

Camera Video Type Definitions

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

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: 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: NatNetClient class reference

• NatNet class and function references for the NatNetClient object.

NatNet: Data Types

• List of tracking data types available in the NatNet SDK streaming protocol.

NatNet: Remote Requests/Commands

• NatNet commands for remote triggering the server application

NatNet: Unicast Data Subscription Commands

• NatNet commands for subscribing to specific data types only.

User Documentation Pages

NatNet: Sample Projects

• List of NatNet sample projects and the instructions.

NatNet: Timecode

• Timecode representation in OptiTrack systems and NatNet SDK tools.

Creating a NatNet Native C++ Client

• A general guideline to using the NatNet SDK for developing a native client application.

Creating a NatNet Managed C# Client

• A general guideline to using the NatNet SDK for developing a managed client application.

Orientation Data in NatNet

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

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)

here are three OptiTrack developer tools for developing custom applications: the Camera SDK, the NatNet SDK, and the Motive API. All of the tools support a C/C++ interface to OptiTrack cameras and provides control over OptiTrack motion capture systems.

Visit our website to compare OptiTrack developer tools and their functions.

Camera SDK

Go to the Camera SDK page: Camera SDK

The Camera SDK provides hardware (cameras and hubs) controls and access to the most fundamental frame data, such as grayscale images and 2D object information, from each camera. Using the Camera SDK, you can develop your own image processing applications that utilize the capabilities of the OptiTrack cameras. The Camera SDK is a free tool that can be downloaded from our website.

Note: 3D tracking features are not directly supported with Camera SDK, but they are featured via the Motive API. For more information on the Camera SDK, visit our website.

Motive API

Go to the Motive API page: Motive API

The Motive API allows control of, and access to, the backend software platform of Motive. Not only does it allow access to 2D camera images and the object data, but it also gives control over the 3D data processing pipeline, including solvers for the assets. Using the Motive API, you can employ the features of Motive into your custom application.

Note: When you install Motive, all of the required components for utilizing the API will be installed within the Motive install directory.

NatNet SDK

Go to the NatNet SDK page: NatNet SDK 4.0

The NatNet SDK is a client/server networking SDK designed for sending and receiving NaturalPoint data across networks. The NatNet SDK makes the motion capture data available to other applications in real-time. It utilizes UDP along with either Unicast or Multicast communication for integrating and streaming 3D reconstructed data, Rigid Body data, and Skeleton data from OptiTrack systems. Using the NatNet SDK, you can develop custom client/server applications that utilize motion capture data. The NatNet SDK is a free tool that can be downloaded from our website.

Visit our website or Data Streaming page for more information on NatNet SDK.

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

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

This guide provides detailed instructions on commonly used functions of the Motive API for developing custom applications. For a full list of the functions, refer to the page. Also, for a sample use case of the API functions, please check out the provided project. In this guide, the following topics will be covered:

• Library files and header files

• Initialization and shutdown

• Capture setup (Calibration)

• Configuring camera settings

• Updating captured frames

• 3D marker tracking

• Rigid body tracking

• Data streaming

Environment Setup

Library Files

When developing a Motive API project, make sure its linker knows where to find the required library files. This can be done either by specifying its location within the project or by copying these files onto the project folder.

MotiveAPI.h

Motive API libraries (.lib and .dll) are located in the lib folder within the Motive install directory; which is located at C:\Program Files\OptiTrack\Motive\lib by default. In this folder, library files for both 64-bit (MotiveAPI.dll and MotiveAPI.lib) platforms can be found. When using the API library, all of the required DLL files must be located in the executable directory. Copy and paste the MotiveAPI.dll file onto the folder alongside the executable file.

Third-party Libraries

• Additional third-party libraries are required for Motive API, and most of the DLL files for these libraries can be found in the Motive install directory C:\Program Files\OptiTrack\Motive\. You can simply copy and paste all of the DLL files from the Motive installation directory into the directory of the Motive API project to use them. Highlighted items in the below image are the required DLL files.

• Lastly, copy the C:\Program Files\OptiTrack\Motive\plugins\platforms folder and its contents into the EXE as well since the libraries contained in this folder will also be used.

Header Files

For function declarations, there are two required header files: MotiveAPI.h and RigidBodySettings.h, and these files are located in the C:\Program Files\OptiTrack\Motive\inc\ folder. Always include the directive syntax for adding the MotiveAPI.h header file for all programs that are developed against the Motive API. The syntax for including RigidBodySetting.h file is already included in the MotiveAPI.h file, so there is no need to include this separately.

• The MotiveAPI.h file contains the declaration for most of the functions and classes in the API.

Motive Files

Motive API, by default, loads the default calibration (CAL) and Application profile (MOTIVE) files from the program data directory unless separately specified. These are the files that Motive also loads at the application startup, and they are located in the following folder:

• Default System Calibration: C:\ProgramData\OptiTrack\Motive\System Calibration.cal

• Default Application Profile: C:\ProgramData\OptiTrack\MotiveProfile.motive

Initialization and Shutdown

When using the API, connected devices and the Motive API library need to be properly initialized at the beginning of a program and closed down at the end. The following section covers Motive API functions for initializing and closing down devices.

Initialization

Update

Shutdown

Setup the Project

Motive Application Profile

Camera Calibration

Loading Calibration

1. Open Motive.

4. Close out of Motive.

6. When successfully loaded, you will be able to obtain 3D tracking data using the API functions.

Camera Settings

Fetching Camera Settings

Configuring Settings

If you wish to keep part of the current camera settings, you can use the above functions to obtain the configured settings (e.g. TT_CameraVideoType, TT_CameraFrameRate, TT_CameraExposure, etc.) and use them as input arguments for the TT_SetCameraSettings function. The following example demonstrates modifying frame rate and IR illumination intensity for all of the cameras, while keeping the other settings constant.

Camera Setting Ranges

Camera Settings

• Valid frame rate values: Varies depending on camera models, refer to the respective hardware specifications.

• Valid exposure values: Depends on camera model and frame rate settings.

• Valid threshold values: 0 - 255

• Valid intensity values: 0 - 15

Video Types

• Segment Mode: 0

• Grayscale Mode: 1

• Object Mode: 2

• Precision Mode: 4

• MJPEG Mode: 6

Other Settings

Updating the frames

In order to process multiple consecutive frames, you must update the camera frames using the following API functions: TT_Update or TT_UpdateSingleFrame. Call one of the two functions repeatedly within a loop to process all of the incoming frames. In the 'marker sample', TT_Update function is called within a while loop as the frameCounter variable is incremented, as shown in the example below.

TT_Update() vs. TT_UpdateSingleFrame()

There are two functions for updating the camera frames: TT_Update and TT_UpdateSingleFrame. At the most fundamental level, these two functions both update the incoming camera frames. However, they may act differently in certain situations. When a client application stalls momentarily, it could get behind on updating the frames and the unprocessed frames may be accumulated. In this situation, each of these two functions will behave differently.

• The TT_Update() function will disregard accumulated frames and service only the most recent frame data, but it also means that the client application will not be processing the previously missed frames.

• The TT_UpdateSingleFrame() function ensures that only one frame is processed each time the function is called. However, when there are significant stalls in the program, using this function may result in accumulated processing latency.

In general, a user should always use TT_Update(). Only in the case where a user wants to ensure their client application has access to every frame of tracking data and they are having problems calling TT_Update() in a timely fashion, should they consider using TT_UpdateSingleFrame(). If it is important for your program to obtain and process every single frame, use the TT_UpdateSingleFrame() function for updating the data.

3D Marker Tracking

Marker Index

Marker Position

Rigid Body Tracking

Importing Rigid Body Assets

Let's go through importing RB assets into a client application using the API. In Motive, Rigid Body assets can be created from three or more reconstructed markers, and all of the created assets can be exported out into either application profile (MOTIVE) or a Motive Rigid Body file (TRA). Each Rigid Body asset saves marker arrangements when it was first created. As long as the marker locations remain the same, you can use saved asset definitions for tracking respective objects.

Exporting all RB assets from Motive:

• Exporting application profile: File → Save Profile

• Exporting Rigid Body file (TRA): File → Export Rigid Bodies (TRA)

Exporting individual RB asset:

Creating New Rigid Body Assets

Example: Creating RB Assets

Rigid Body 6 DoF Tracking Data

Example: RB Tracking Data

Rigid Body Properties

Data Streaming

Data Streaming Settings

The Motive API does not currently support configuring data streaming settings directly from the API. To configure the streaming server IP address and the data streaming settings, you will need to use Motive and save an application profile MOTIVE file that contains the desired configuration. Then, the exported profile can be loaded when using the API. Through this way, you will be able to set the interface IP address and decide which data to be streamed over the network.

This page provides a sample and instructions on how to use Motive API functions to calibrate a camera system.

Sample Code

The following sample code demonstrates calibration process using the Motive API. For details on specific functions, please refer to the page.

Masking

Auto-Masking

Auto-Masking is done directly by calling the TT_AutoMaskAllCameras function. When this is called, Motive will sample for a short amount of time and apply a mask to the camera imagers where light was detected.

<source> //== To auto-mask, call TT_AutoMaskAllCameras().

TT_AutoMaskAllCameras(); printf( "============\nCamera masking started\n============\n" ); </source>

Camera Mask

This function returns memory block of the mask. One bit per a pixel of the mask. Masking pixels are rasterized from left to right and from top to bottom of the camera's view.

Clear Masks

This function can clear existing masks from the 2D camera view. It returns true when it successfully removes pixel masks. Otherwise, masking is always additive through the API.

Set Camera Mask

The TT_SetCameraMask can be used to replace the existing camera mask for any camera. A mask is an array of bytes, one byte per mask pixel block. Returns true when masks are applied.

Wanding

Ground Plane

Setting ground plane is done directly by calling the TT_SetGroundPlane function. When this is called, camera system will search for 3-markers that resemble a calibration square and uses the inputted vertical offset value to configure the ground plane.

Please use the table of contents to the right to navigate to specific functions or specific group of functions.

Project Management

TT_Initialize

Initializes the API and prepares all connected devices for capturing. Please note that TT_Initialize also loads the default profile from the ProgramData directory: C:\ProgramData\OptiTrack\MotiveProfile.motive. When there is a need to load the profile from a separate directory, use TT_LoadProfile function.

Description

• This function initializes the API library and prepares all connected devices for capturing.

• When using the API, this function needs to be called at the beginning of a program before using the cameras.

• Returns an NPRESULT value. When the function successfully updates the data, it returns 0 (or NPRESULT_SUCCESS).

Function Input

• None

Function Output

• NPRESULT

C++ Example

TT_Shutdown

Shuts down all of the connected devices.

Description

• This function closes down all connected devices and the camera library. To ensure that all devices properly shutdown, call this function before terminating an application.

• When the function successfully closes down the devices, it returns 0 (or NPRESULT_SUCCESS).

• When calling this function, currently configured camera calibration will be saved under the default System Calibration.cal file.

Function Input

• None

Function Output

• NPRESULT

C++ Example

TT_Update

Processes incoming frame data from the cameras.

Description

• This function updates frame information with the most recent data from the cameras and 3D processing engines.

• Another use of this function is to pick up newly connected cameras. Call this function at the beginning of a program in order to make sure that all of the new cameras are properly recognized.

• TT_Update vs. TT_UpdateSingleFrame: In the case when a client application stalls momentarily, the program may get behind on updating the frames. In this situation, the TT_Update() function will disregard accumulated frames and service only the most recent frame data, but this also means that the client application will be missing the previous frames. On the other hand, the TT_UpdateSingleFrame function ensures that always a consecutive frame is updated each time the function is called. In general, a user should always use TT_Update(). Only in the case where a user wants to ensure their client application has access to every frame of tracking data and they are having problems calling TT_Update() in a timely fashion, should they consider using TT_UpdateSingleFrame(). If it is important for your program to obtain and process every single frame, use the TT_UpdateSingleFrame() function for updating the data.

• Returns an NPRESULT integer value, depending on whether the operation was successful or not. Returns NPRESULT_SUCCESS when it successfully updates the frame data.

Function Input

• None

Function Output

• NPRESULT

C++ Example

TT_UpdateSingleFrame

Updates a single frame of camera data.

Description

• Every time this function is called, it updates frame information with the next frame of camera data.

• Using this function ensures that every frame of data is processed.

• TT_Update() vs. TT_UpdateSingleFrame(): In the case when a client application stalls momentarily, the program may get behind on updating the frames. In this situation, the TT_Update() function will disregard accumulated frames and service only the most recent frame data, but this also means that the client application will be missing the previous frames. On the other hand, the TT_UpdateSingleFrame function ensures that always a consecutive frame is updated each time the function is called. In general, a user should always use TT_Update(). Only in the case where a user wants to ensure their client application has access to every frame of tracking data and they are having problems calling TT_Update() in a timely fashion, should they consider using TT_UpdateSingleFrame(). If it is important for your program to obtain and process every single frame, use the TT_UpdateSingleFrame() function for updating the data.

• Returns an NPRESULT value. When the function successfully updates the data, it returns 0 (or NPRESULT_SUCCESS).

Function Input

• None

Function Output

• NPRESULT

C++ Example

TT_LoadCalibration, TT_LoadCalibrationW

Loads a Motive camera calibration file.

Description

• These functions load a camera calibration file (CAL).

• Camera calibration files need to be exported from Motive.

• Returns a NPRESULT integer value. If the file was successfully loaded, it returns NPRESULT_SUCCESS.

Function Input

• Filename (const char, const wchar_t)

Function Output

• NPRESULT

C++ Example

TT_LoadRigidBodies, TT_LoadRigidBodiesW

Imports TRA files and loads Rigid Body assets from it.

Description

• This function imports and loads Rigid Body assets from a saved TRA file.

• TRA files contain exported Rigid Body asset definitions from Motive.

• All existing assets in the project will be replaced with the Rigid Body assets from the TRA file when this function is called. If you want to keep existing assets and only wish to add new Rigid Bodies, use TT_AddRigidBodies function.

• Returns an NPRESULT integer value. It returns NPRESULT_SUCCESS when the file is successfully loaded.

Function Input

Filename (const char, const wchat_t)

Function Output

NPRESULT

C++ Example

TT_SaveRigidBodies, TT_SaveRigidBodiesW

Saves all of the Rigid Body asset definitions into a TRA file.

Description

• This function saves all of the Rigid Body assets from the project into a TRA file.

• Attach *.tra extension at the end of the filename.

• Returns an NPRESULT integer value. It returns 0 or NPRESULT_SUCCESS when successfully saving the file.

Function Input

Filename (const char, const wchar_t)

Function Output

NPRESULT

C++ Example

TT_AddRigidBodies, TT_AddRigidBodiesW

Loads a TRA file and adds its Rigid Body assets onto the project.

Description

• This function adds Rigid Body assets from the imported TRA file onto the existing list.

• Adds Rigid Bodies from imported TRA files onto the asset list of the current project.

• Returns an NPRESULT integer value. If the Rigid Bodies have been added successfully, it returns 0 or NPRESULT_SUCCESS.

Function Input

Filename (const char, const wchat_t)

Function Output

NPRESULT

C++ Example

TT_LoadProfile, TT_LoadProfileW

Loads a Motive User Profile (.MOTIVE).

Description

• Loads the default application profile file (MOTIVE), which is located in the ProgramData directory: C:\ProgramData\OptiTrack\MotiveProfile.motive

• The MOTIVE files store software configurations as well as other software-wide settings.

• Profile files also loads trackable asset definitions. Once the application profile containing trackable assets is imported, there is no need to import TRA and SKL files separately.

• Returns an NPRESULT integer value. If the project file was successfully loaded, it returns 0 (NPRESULT_SUCCESS).

Function Input

Filename (const char, const wchar_t)

Function Output

NPRESULT

C++ Example

TT_LoadProject, TT_LoadProjectW

Loads a Motive TTP project file.

Description

• Loads a Motive TTP project file. TTP project file loads and saves both camera calibration and Rigid Body assets, so when using TTP files, there is no need to import or export CAL or TRA files separately.

• Loading a project file will import all of the required information for tracking. These include camera calibration and Rigid Body assets that are associated with a Motive project.

• Returns an NPRESULT integer value. If the project file was successfully loaded, it returns 0 (NPRESULT_SUCCESS).

Function Input

Filename (const char, const wchar_t)

Function Output

NPRESULT

C++ Example

TT_SaveProfile, TT_SaveProfileW

Saves current application setting into a Profile XML file.

Description

• This function saves the current configuration into an application Profile XML file.

• Attach *.xml extension at the end of the filename.

• Returns an NPRESULT integer value. If the profile XML file was saved successfully, it returns 0 (NPRESULT_SUCCESS).

Function Input

Filename (const char, const wchar_t)

Function Output

NPRESULT

C++ Example

TT_SaveProject, TT_SaveProjectW

TT_LoadCalibrationFromMemory

Loads calibration from memory.

Description

• This function loads camera calibration from memory. In order to do this, the program must have saved calibration memory.

• It assumes the pointer argument (unsigned char*) points to a memory block where calibration data is already stored. The address and size of the calibration buffer must be determined by the developer using the API.

Function Input

• Buffer (unsigned char*)

• Size of the buffer (int)

Function Output

• NPRESULT

C++ Example

TT_CameraExtrinsicsCalibrationFromMemory

Gets camera extrinsics from a calibration file in memory.

Description

• This allows for acquiring camera extrinsics for cameras not connected to system.

• It simply returns the list of details for all cameras contained in the calibration file.

Function Input

• Buffer (unsigned char*)

• Size of the buffer (int)

• Result

Function Output

• NPRESULT

C++ Example

Calibration

TT_StartCalibrationWanding

Start a new calibration wanding for all cameras.

Description

• This will cancel any existing calibration process.

Function Input

• None

Function Output

C++ Example

TT_CalibrationState

Returns the current calibration state.

Description

• Returns the current calibration state.

Function Input

• None

Function Output

• NPRESULT

C++ Example

TT_CalibrationCamerasLackingSamples

During calibration wanding, this will return a vector of camera indices that are lacking the minimum number of calibration samples to begin calculation.

Description

• When the returned vector for this method goes to zero size, you can call TT_StartCalibrationCalculation() to begin calibration calculations.

• Wanding samples will continue to be collected until TT_StartCalibrationCalculation() is called.

Function Input

• None

Function Output

• Vector (int)

C++ Example

TT_CameraCalibrationSamples

During calibration wanding.

Description

• This will return the number of wand samples collected for the given camera.

• Return 0 otherwise.

Function Input

• Camera index (int)

Function Output

• Number of samples (int)

C++ Example

TT_CancelCalibration

Cancels wanding or calculation and resets calibration engine.

Description

• Cancels wanding or calculation

• Resets calibration engine

Function Input

• none

Function Output

• Exits either TT_StartCalibrationWanding() or TT_StartCalibratoinCalculation()

C++ Example

TT_StartCalibrationCalculation

Once wanding is complete, call this to begin the calibration calculations.

Description

• Starts calibration calculations after wanding.

Function Input

• Boolean value

Function Output

• Starts calculation

C++ Example

TT_CurrentCalibrationQuality

During calibration calculation.

Description

• This method will return the current calibration quality in the range [0-5], with 5 being best.

• Returns zero otherwise

Function Input

• none

Function Output

• Quality on scale of 0-5 (int)

C++ Example

TT_ApplyCalibrationCalculation

Run once TT_CalibrationState() returns "Complete".

Description

• Call this method to apply the calibration results to all cameras.

Function Input

• none

Function Output

• Apply calibration results

C++ Example

TT_SetGroundPlane

Set the ground plane using a standard or custom ground plane template.

Description

• If true then this function will use a custom ground plane.

Function Input

• Boolean value of useCustomGroundPlane

Function Output

• Either applies custom or preset ground plane to calibration.

C++ Example

TT_TranslateGroundPlane

Translate the existing ground plane (in mm).

Description

• Takes float variables to alter existing ground plane.

Function Input

• X, Y, and Z values (float)

Function Output

• Applies new values to existing ground plane.

C++ Example

Data Streaming

TT_StreamNP

Enables/disables the NatNet streaming of the Natrual Point tracking data.

Description

• This function enables/disables NaturalPoint data stream.

• This is equivalent to the Broadcase Frame Data in the Data Streaming panel in Motive.

• Returns a NPRESULT integer value. If the operation was successful, it returns 0 (NPRESULT_SUCCESS).

Function Input

• Boolean argument enabled (true) / disabled (false)

Function Output

• NPRESULT

C++ Example

TT_StreamTrackd

Enables/disables streaming frame data into trackd.

Description

• This function enables/disables streaming data into trackd.

• Returns a NPRESULT integer value. If the operation was successful, it returns 0 (NPRESULT_SUCCESS).

Function Input

• True for enabling and false for disabling (bool)

Function Output

• NPRESULT

C++ Example

TT_StreamVRPN

Description

• This function enables/disables data streaming into VRPN.

• To stream onto VRPN, the port address must be specified. VRPN server applications run through 3883 port, which is default port for the VRPN streaming.

• Returns an NPRESULT integer value. If streaming was successfully enabled, or disabled, it returns 0 (NPRESULT_SUCCESS).

Function Input

• True for enabling and false for disabling (bool)

• Streaming port address (int)

Function Output

• NPRESULT

C++ Example

3D Frame Data

TT_FrameMarkerCount

Gets total number of reconstruected markers in a frame.

Description

• This function returns a total number of reconstructed 3D markers detected in current capture frame.

• Use this function to count a total number of markers, access every markers, and obtain the marker index values.

Function Input

• None

Function Output

• Total number of reconstructed markers in the frame (int)

C++ Example

TT_FrameMarkerX

Returns x-position of a reconstructed marker.

Description

• This function returns X coordinate of a reconstructed 3D marker in respect to the global coordinate system, in meters.

• It requires a marker index value.

Function Input

• Marker index (int)

Function Output

• X-position of the 3D marker (float)

C++ Example

TT_FrameMarkerY

Returns y-position of a reconstructed marker.

Description

• This function returns Y coordinate of a reconstructed 3D marker in respect to the global coordinate system, in meters.

• It requires a marker index value.

Function Input

• Marker index (int)

Function Output

• Y-position of the 3D marker (float)

C++ Example

TT_FrameMarkerZ

Returns z-position of a reconstructed marker.

Description

• This function returns Z coordinate of a reconstructed 3D marker in respect to the global coordinate system, in meters.

• It requires a marker index value.

Function Input

• Marker index (int)

Function Output

• Z-position of the 3D marker (float)

C++ Example

TT_FrameMarkerResidual

Returns residual value of a marker.

Description

• This function returns a residual value for a given marker indicated by the marker index.

• Unit of the returned value is in millimeters.

• The marker index value may change between frames, but the unique identifier will always remain the same.

Function Input

• Marker index (int)

Function Output

• Residual value (float)

TT_FrameMarkerLabel

Returns a unique identifier of a marker.

Description

• This function returns a unique identifier (cUID) for a given marker.

• Markers have an index from 0 to [totalMarkers -1] for a given frame. In order to access unique identifier of any marker, it's index must be inputted.

• The marker index value may change between frames, but the unique identifier will always remain the same.

Function Input

• Marker index (int)

Function Output

• Marker label (cUID)

C++ Example

TT_FrameTimeStamp

Returns a timestamp value for the current frame.

Description

• This function returns a timestamp value of the current frame.

Function Input

• None

Function Output

• Frame timestamp (double)

C++ Example

TT_FrameCameraCentroid

Checks whether a camera is contributing to reconstruction of a 3D marker, and saves corresponding 2D location as detected in the camera's view.

Description

• This function evaluates whether the specified camera (cameraIndex) is contributing to point cloud reconstruction of a 3D point (markerIndex).

• It returns true if the camera is contributing to the marker.

• After confirming that the camera contributes to the reconstruction, this function will save the 2D location of the corresponding marker centroid in respect to the camera's view.

• The 2D location is saved in the declared variable.

Function Input

• 3D reconstructed marker index (int)

• Camera index (int)

• Reference variables for saving x and y (floats).

Function Output

• True / False (bool)

C++ Example

TT_FlushCameraQueues

Flushes out the camera queues.

Description

• This function flushes camera queues.

• In an event when you are tracking a very high number (hundreds) of markers and the application has accumulated data processing latency, you can call TT_FlushCameraQueues() to refresh the camera queue before calling TT_Update() for processing the frame. After calling this function, avoid calling it again until the TT_Update() function is called and NPRESULT_SUCCESS is returned.

Function Input

• None

Function Output

• Void

C++ Example

Rigid Bodies

TT_IsRigidBodyTracked

Checks whether Rigid Body is tracked or not.

Description

• Checks whether the Rigid Body is being tracked in the current frame.

• Returns true if the Rigid Body is tracked.

Function Input

• Rigid body index (int)

Function Output

• True / False (bool)

C++ Example

TT_RigidBodyLocation

Obtains and saves 3D position, quaternion orientation, and Euler orientation of a Rigid Body

Description

• This function saves position and orientation of a Rigid Body. Specifically, position and orientation at the Rigid Body pivot point is obtained.

• 3D coordinates of the Rigid Body will be assigned in declared variable addresses (*x, *y, *z).

• Orientation of the Rigid Body will be saved in two different formats; Euler and quaternion rotations. Yaw, pitch, and roll values for Euler representation will be saved in the declared variable addresses (*yaw, *pitch, *roll), and qx, qy, qz, and qw values for the quaternion rotation will be saved in declared variable addresses (*qx, *qy, *qz, and *qw).

Function Input

• Rigid body index (int)

• Declared variable (float) addresses for:

  • 3D coordinates (x,y,z)

  • Quaternion Rotation (qx, qy, qz, qw)

  • Euler Rotation ( yaw, pitch, roll)

Function Output

• Void

C++ Example

TT_ClearRigidBodyList

Clears and removes all Rigid Body assets.

Description

• This function clears all of existing Rigid Body assets in the project.

Function Input

• None

Function Output

• Void

C++ Example

TT_RemoveRigidBody

Removes a Rigid Body from the project

Description

• This function removes a single Rigid Body from a project.

• Returns a NPRESULT integer value. If the operation was successful, it returns 0 (NPRESULT_SUCCESS).

Function Input

• Rigid body index (int)

Function Output

• NPRESULT

C++ Example

TT_RigidBodyCount

Returns a total number of Rigid Bodies.

Description

• This function returns a total count of Rigid Bodies involved in the project.

• This can be used within a loop to set required number iterations and access each of the Rigid Bodies.

Function Input

• None

Function Output

• Total Rigid Body count (int)

C++ Example

TT_RigidBodyUserData

Returns the User Data ID value of a Rigid Body.

Description

• This function returns the User Data ID number of a Rigid Body.

• User ID is a user definable ID for the Rigid Body. When working with capture data in external pipelines, this value can be used to address specific Rigid Bodies in the scene.

Function Input

• Rigid body index (int)

Function Output

• User Data ID (int)

C++ Example

TT_SetRigidBodyUserData

Assigns a User Data ID number to a Rigid Body.

Description

• Assigns a User Data ID number to a Rigid Body.

• The User Data ID numbers can be used to point to particular assets when processing the data in external applications.

Function Input

• Rigid body index (int)

• Desired User Data ID (int)

Function Output

• Void

C++ Example

TT_RigidBodyMeanError

Returns a mean error of the Rigid Body tracking data.

Description

• Returns a mean error value of the respective Rigid Body data for the current frame.

Function Input

• Rigid body index (int)

Function Output

• Mean error (meters)

TT_RigidBodyName, TT_RigidBodyNameW

Returns the name for the Rigid Body.

Description

• These functions are used to obtain name of a Rigid Body.

• Returns the assigned name of the Rigid Body.

Function Input

• Rigid body index (int)

Function Output

• Rigid body name (const char*, const w_chart*)

C++ Example

TT_SetRigidBodyEnabled

Enables/disables tracking of a Rigid Body.

Description

• This function enables, or disables, tracking of the selected Rigid Body.

• All Rigid Bodies are enabled by default. Disabled Rigid Bodies will not be tracked, and no data will be received from it.

Function Input

• Rigid body index (int)

• Tracking status (bool)

Function Output

• Void

C++ Example

TT_RigidBodyEnabled

Checks whether a Rigid Body is enabled.

Description

• This function checks whether tracking of the Rigid Body is enabled or not.

• The function returns true is the tracking is enabled.

Function Input

• Rigid body index (int)

Function Output

• True / False (bool)

C++ Example

TT_RigidBodyTranslatePivot

Translates the pivot point of a Rigid Body.

Description

• This function translates a Rigid Body.

• 3D position of a Rigid Body will be displaced in x/y/z directions by inputted amount (meters).

• Translation is applied in respect to the local Rigid Body coordinate axis, not the global axis.

• Returns a NPRESULT integer value. If the operation was successful, it returns 0 (NPRESULT_SUCCESS).

Function Input

• Rigid body index (int)

• Translation along x-axis, in meters. (float)

• Translation along y-axis, in meters. (float)

• Translation along z-axis, in meters. (float)

Function Output

• NPRESULT

C++ Example

TT_RigidBodyResetOrientation

Resets orientation of a Rigid Body.

Description

• This function resets orientation of the Rigid Body and re-aligns its orientation axis with the global coordinate system.

• Additional Note: When creating a Rigid Body, its zero orientation is set by aligning its axis with the global axis at the moment of creation. Calling this function essentially does the same thing on an existing Rigid Body asset.

• Returns true if the Rigid Body orientation was reset.

Function Input

• Rigid body index (int)

Function Input

• True / False (bool)

C++ Example

TT_RigidBodyMarkerCount

Gets total number of markers in a Rigid Body.

Description