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.

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.

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

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.

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

b. Connect to Server

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

c. Confirm connection

[C#] SampleClientML.cs : GetServerDescription

3. Get DataDescriptions

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

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

4. Get Frame Data

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.

• 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

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.

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

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"

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

b. Discover Server Address

[C++] SampleClient.cpp : Server Discovery

c. Connect to Server

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

d. Confirm Connection

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

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

3. Get DataDescriptions

a. Fetching Data Description

[C++] SampleClient.cpp : Get 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

C. Free Data Description

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)

b. Parsing/Handling Frame Data Handling

5. Disconnect

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

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

FrameOfMocapData

Additional Notes

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.

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.

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.

NPRESULT		TT_Initialize();

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

// Initializing all connected cameras
TT_Initialize();

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

// Close down all of the connected cameras
TT_Shutdown();
return 0;

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

//== Update to pick up recently-arrived cameras ==/
TT_Update();

//== Frame Processing: Polling the frame data ==//
while( programRunning ){
	if( TT_Update() == NPRESULT_SUCCESS ){
		frameNumber++;
		//== Process Frame Data ==//
	}
}

TT_UpdateSingleFrame

Updates a single frame of camera data.

NPRESULT		TT_UpdateSingleFrame();

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

//== Update to pick up recently-arrived cameras ==/
TT_Update();

//== Frame Processing: Polling the frame data ==//
while( programRunning ){
	if( TT_UpdateSingleFrame() == NPRESULT_SUCCESS ){
		frameNumber++;
		//== Process Frame Data ==//
	}
}

TT_LoadCalibration, TT_LoadCalibrationW

Loads a Motive camera calibration file.

NPRESULT		TT_LoadCalibration(const char *filename);

NPRESULT		TT_LoadCalibrationW(const wchar_t *filename);

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

const char *calFileName= "project.ttp";
NPRESULT fileload = TT_LoadCalibration(calFileName);

if (fileload == NPRESULT_SUCCESS)
{
	printf("%s successfully loaded.\n", calFileName);
}
else
{
	printf("Error: %s\n", TT_GetResultString(fileload));
}

TT_LoadRigidBodies, TT_LoadRigidBodiesW

Imports TRA files and loads Rigid Body assets from it.

NPRESULT		TT_LoadRigidBodies(const char *filename);

NPRESULT		TT_LoadRigidBodiesW(const wchar_t *filename);

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

//Loading Rigid Body Assets from a TRA file.
const char *traFile = "rigidbody.tra";
TT_LoadRigidBodies(traFile);

TT_SaveRigidBodies, TT_SaveRigidBodiesW

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

NPRESULT		TT_SaveRigidBodies(const char *filename);

NPRESULT		TT_SaveRigidBodiesW(const wchar_t *filename);

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

//== Save Rigid Bodies ==/
TT_SaveRigidBodies("traFileName.tra");

TT_AddRigidBodies, TT_AddRigidBodiesW

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

NPRESULT		TT_AddRigidBodies(const char *filename);

NPRESULT		TT_AddRigidBodiesW(const wchar_t *filename);

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

/== Adding Rigid Bodies ==/
TT_AddRigidBodies("rigidbody.tra");

TT_LoadProfile, TT_LoadProfileW

Loads a Motive User Profile (.MOTIVE).

NPRESULT		TT_LoadProfile(const char *filename);

NPRESULT		TT_LoadProfileW(const wchar_t *filename);

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

//== Loading application profile XML file ==/
const char *filename= "UserProfile.ttp";
NPRESULT profileLoad = TT_LoadProfile(filename);

if (profileLoad == NPRESULT_SUCCESS)
{
	printf("%s successfully loaded.\n", filename);
}
else
{
	printf("Error: %s\n", TT_GetResultString(profileLoad));
}

TT_LoadProject, TT_LoadProjectW

Loads a Motive TTP project file.

NPRESULT		TT_LoadProject(const char *filename);

NPRESULT		TT_LoadProjectW(const wchar_t *filename);

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

//== Loading TTP project file ==/
const char *filename= "project.ttp";
NPRESULT ttpload = TT_LoadProject(filename);

if (ttpload == NPRESULT_SUCCESS)
{
	printf("%s successfully loaded.\n", filename);
}
else
{
	printf("Error: %s\n", TT_GetResultString(ttpload));
}

TT_SaveProfile, TT_SaveProfileW

Saves current application setting into a Profile XML file.

NPRESULT		TT_SaveProfile(const char *filename);

NPRESULT		TT_SaveProfileW(const wchar_t *filename);

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

//== Saving the TTP project ==/
const char *projectname = "project.ttp";
NPRESULT result = TT_SaveProfile(projectname);

if ( result == NPRESULT_SUCCESS ){
        printf("Profile XML file saved.");
}
else {
        printf("Error: %s", TT_GetResultString(result));
}

TT_SaveProject, TT_SaveProjectW

TT_LoadCalibrationFromMemory

Loads calibration from memory.

NPRESULT		TT_LoadCalibrationFromMemory(unsigned char* buffer, int bufferSize);

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

// get a pointer to the calibration block in memory
int bufferSize;
 
// get the size of the buffer
NPRESULT result = TT_LoadCalibrationFromMemory(buffer, bufferSize);

TT_CameraExtrinsicsCalibrationFromMemory

Gets camera extrinsics from a calibration file in memory.

NPRESULT		TT_CameraExtrinsicsCalibrationFromMemory(unsigned char* buffer, int bufferSize, eMotiveAPIResult& result);

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

// get a pointer to the calibration block in memory
int bufferSize;

// get the size of the buffer
NPRESULT result = TT_CameraExtrinsicsCalibrationFromMemory(unsigned char* buffer, int bufferSize, eMotiveAPIResult& result);

Calibration

TT_StartCalibrationWanding

Start a new calibration wanding for all cameras.

void		TT_StartCalibrationWanding();

Description

• This will cancel any existing calibration process.

Function Input

• None

Function Output

C++ Example

TT_CalibrationState

Returns the current calibration state.

NPRESULT		TT_CalibrationState();

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.

std::vector<int>		TT_CalibrationCamerasLackingSamples();

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.

int		TT_CameraCalibrationSamples(int cameraIndex);

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.

void		TT_CancelCalibration();

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.

bool		TT_StartCalibrationCalculation();

Description

• Starts calibration calculations after wanding.

Function Input

• Boolean value

Function Output

• Starts calculation

C++ Example

TT_CurrentCalibrationQuality

During calibration calculation.

bool		TT_CurrentCalibrationQuality();

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

bool		TT_ApplyCalibrationCalculation();

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.

bool		TT_SetGroundPlane(bool useCustomGroundPlane);

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

void		TT_TranslateGroundPlane(float x, float y, float z);

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.

NPRESULT		TT_StreamNP(bool enabled);

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

//== Enable NP Streaming ==/
TT_StreamNP(true);

TT_StreamTrackd

Enables/disables streaming frame data into trackd.

NPRESULT		TT_StreamTrackd(bool enabled);

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

//== Enable NP Streaming ==/
TT_StreamTrackd(true);

TT_StreamVRPN

Enables/disables data stream into VRPN.

NPRESULT		TT_StreamVRPN(bool enabled, int port);

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

//== Enable Streaming into VRPN ==/
TT_StreamVRPN(true);

3D Frame Data

TT_FrameMarkerCount

Gets total number of reconstruected markers in a frame.

int		TT_FrameMarkerCount();

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

//Obtaining total marker count
int totalMarker = TT_FrameMarkerCount();
printf("Total number of markers: %d", totalMarker);

for (int i = 0 ; i < totalMarker; i++) {
        //== Use a loop to access every marker in the frame ==//
        printf("Marker %d (X/Y/Z): (%f, %f, %f)\n", i,
		TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

TT_FrameMarkerX

Returns x-position of a reconstructed marker.

float		TT_FrameMarkerX(int markerIndex);

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

int totalMarker = TT_FrameMarkerCount();
printf("Total number of markers: %d", totalMarker);

//== Outputting marker positions ==//
for (int i = 0 ; i < totalMarker; i++) {
        //== Use a loop to access every marker in the frame ==//
        printf("Marker %d (X/Y/Z): (%f, %f, %f)", i,
		TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

TT_FrameMarkerY

Returns y-position of a reconstructed marker.

float		TT_FrameMarkerY(int markerIndex);

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

int totalMarker = TT_FrameMarkerCount();
printf("Total number of markers: %d", totalMarker);

//== Outputting marker positions ==//
for (int i = 0 ; i < totalMarker; i++) {
        //== Use a loop to access every marker in the frame ==//
        printf("Marker %d (X/Y/Z): (%f, %f, %f)", i,
		TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

TT_FrameMarkerZ

Returns z-position of a reconstructed marker.

float		TT_FrameMarkerZ(int markerIndex);

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

int totalMarker = TT_FrameMarkerCount();
printf("Total number of markers: %d", totalMarker);

//== Outputting marker positions ==//
for (int i = 0 ; i < totalMarker; i++) {
        //== Use a loop to access every marker in the frame ==//
        printf("Marker %d (X/Y/Z): (%f, %f, %f)", i,
		 TT_FrameMarkerX(i), TT_FrameMarkerY(i), TT_FrameMarkerZ(i));
}

TT_FrameMarkerResidual

Returns residual value of a marker.

float		TT_FrameMarkerResidual(int markerIndex);

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.

Core::cUID		TT_FrameMarkerLabel(int markerIndex);

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

int totalMarkers = TT_FrameMarkerCount();
vector<Core::cUID> unique_Marker_ID(totalMarkers);

for (int i = 0; i < totalMarkers; ++i)
{
    unique_Marker_ID[i] = TT_FrameMarkerLabel(int markerIndex); 
}

TT_FrameTimeStamp

Returns a timestamp value for the current frame.

double		TT_FrameTimeStamp();

Description

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

Function Input

• None

Function Output

• Frame timestamp (double)

C++ Example

int frameNumber = 0;

//== Display Frame number and Time stamp ==//
while( !_kbhit() )
{
	if( !TT_Update() ){
		frameNumber++;	// increment frame number each time a frame is processed.

		printf("Frame #%d: (Timestamp: %f)\n", frameNumber, TT_FrameTimeStamp());
	}
}

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.

bool		TT_FrameCameraCentroid(int markerIndex, int cameraIndex, float &x, float &y);

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

//== Getting 2D location of marker centroids from a camera.==//
float x, y;
int targetcam = 1;
int frameMarkercount = TT_FrameMarkerCount();

for (int i = 0; i < frameMarkercount; i++) // For each detected markers
{
	bool result = TT_FrameCameraCentroid(i, targetcam, x, y)

	if (result)
	{
		printf("Marker %d location in camera #%d: %f, %f\n", i, targetcam, x, y);
	}
}

TT_FlushCameraQueues

Flushes out the camera queues.

void		TT_FlushCameraQueues();

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

//== Flush Camera Queues to remove accumulated latency. ==//
TT_FlushCameraQueues();

//== Update the incoming camera data after. ==//
TT_Update();

Rigid Bodies

TT_IsRigidBodyTracked

Checks whether Rigid Body is tracked or not.

bool		TT_IsRigidBodyTracked(int rbIndex);

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

int totalRB = TT_RigidBodyCount();

//== Checking if the Rigid Body is tracked or not ==//
for(int i = 0; i < totalRB)
{
	If(TT_IsRigidBodyTracked(i))
	{
		// Process Rigid Body
	}
}

TT_RigidBodyLocation

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

void		TT_RigidBodyLocation(int rbIndex,
			float *x, float *y, float *z,
			float *qx, float *qy, float *qz, float *qw,
			float *yaw, float *pitch, float *roll);

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

//== Declared variables ==//
float	x, y, z;
float 	qx, qy, qz, qw;
float	yaw, pitch, roll;
int rbcount = TT_RigidBodyCount();

for(int i = 0; i < rbcount; i++)
{
	//== Obtaining/Saving the Rigid Body position and orientation ==//
	TT_RigidBodyLocation( i, &x, &y, &z, &qx, & qy, &qz, &qw, &yaw, &pitch, &roll );
	
	if( TT_IsRigidBodyTracked( i ) )
	{
		printf( "%s: Pos (%.3f, %.3f, %.3f) Orient (%.1f, %.1f, %.1f)\n", 
					TT_RigidBodyName( i ), x, y, z, yaw, pitch, roll );
	}
}

TT_ClearRigidBodyList

Clears and removes all Rigid Body assets.

void		TT_ClearRigidBodyList();

Description

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

Function Input

• None

Function Output

• Void

C++ Example

//== Clear all Rigid Bodies ==//
TT_ClearRigidBodyList();

TT_RemoveRigidBody

Removes a Rigid Body from the project

NPRESULT		TT_RemoveRigidBody(int rbIndex);

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

//== Removing Rigid Bodies that are not tracked in the scene ==//
int totalRB = TT_RigidBodyCount();

for (int i = 0; i < totalRB; i++)
{
	if(!TT_IsRigidBodyTracked(i))
	{
 		TT_RemoveRigidBody(i);
	}
}

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

//== Getting names of all Rigid Bodies ==//
int totalRB = TT_RigidBodyCount();

for (int i = 0; i < totalRB; i++)
{
	printf("Rigid Body #%d: %s\n", i, TT_RigidBodyName(i));
}

TT_RigidBodyUserData

Returns the User Data ID value of a Rigid Body.

int		TT_RigidBodyUserData(int rbIndex);

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

int totalRB = TT_RigidBodyCount();

//== User Data ID for all Rigid Bodies ==//
for ( int i = 0 ; i < totalRB; i++ )
{
	printf("%s User Data ID: %d", TT_RigidBodyName(i), TT_RigidBodyUserData(i));
}

TT_SetRigidBodyUserData

Assigns a User Data ID number to a Rigid Body.

void		TT_SetRigidBodyUserData(int rbIndex, int ID);

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

int totalRB = TT_RigidBodyCount();

//== Assigning incremental User Data ID for Rigid Bodies. ==//
for( int i = 0; i < totalRB; i++ )
{
	TT_SetRigidBodyUserData(i, i+1);
	printf("Rigid Body: %s, \t User Data ID: %d", TT_RigidBodyName(i), TT_RigidBodyUserData(i)); 
}

TT_RigidBodyMeanError

Returns a mean error of the Rigid Body tracking data.

void		TT_RigidBodyMeanError(int rbIndex, int ID);

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.

const char* 	 	TT_RigidBodyName(int rbIndex);

const wchar_t*		TT_RigidBodyNameW(int rbIndex);

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

int totalRB = TT_RigidBodyCount();

//== Printing Rigid Body Names ==//
for( int i = 0; i < totalRB; i++ )
{
	printf("Rigid Body: %s, \t User Data ID: %d", TT_RigidBodyName(i), TT_RigidBodyUserData(i)); 
}

TT_SetRigidBodyEnabled

Enables/disables tracking of a Rigid Body.

void		TT_SetRigidBodyEnabled(int rbIndex, bool enabled);

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

int totalRB = TT_RigidBodyCount();

//== Disabling all Rigid Bodies ==//
for(int i = 0; i < totalRB; i++)
{
	TT_SetRigidBodyEnabled(i, FALSE);
} 

TT_RigidBodyEnabled

Checks whether a Rigid Body is enabled.

bool		TT_RigidBodyEnabled(int rbIndex);

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

int totalRB = TT_RigidBodyCount();

for (int i = 0; i < totalRB; i++)
{
	if (TT_RigidBodyEnabled(i))
	{
 		//== Disabling all enabled Rigid Bodies ==//
		TT_SetRigidBodyEnabled(i, FALSE);
	}
}

TT_RigidBodyTranslatePivot

Translates the pivot point of a Rigid Body.

NPRESULT		TT_RigidBodyTranslatePivot(int index, float x, float y, float z);

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

int rbIndex = 1;

//== Translating a Rigid Body 2 cm in positive x-direction ==//
TT_RigidBodyTranslate(rbIndex, 0.02, 0, 0);

TT_RigidBodyResetOrientation

Resets orientation of a Rigid Body.

bool		TT_RigidBodyResetOrientation(int rbIndex);

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

int rbcount = TT_RigidBodyCount();

//== Resetting orientation of each Rigid Body. ==//
for( int i = 0; i < rbcount i++ )
{
	if(TT_RigidBodyResetOrientation(i))
	{
		printf("Rigid body (%s) orientation reset", TT_RigidBodyName(i));
	}
}

TT_RigidBodyMarkerCount

Gets total number of markers in a Rigid Body.

int		TT_RigidBodyMarkerCount(int rbIndex);

Description

• This function returns total number of markers involved in a Rigid Body.

Function Input

• Rigid body index (int)

Function Output

• Total number of marker in the Rigid Body (int)

C++ Example

int rbcount = TT_RigidBodyCount();

//== Listing out all of the Rigid Body markers ==// 
for(int i = 0; i < rbcount; i++)
{
	printf("Rigid Body:%s\t Marker Count: %d", TT_RigidBodyName(i), TT_RigidBodyMarkerCount(i));
}

TT_RigidBodyMarker

Saves 3D coordinates of a solved Rigid Body marker in respect to respective Rigid Body's local space.

void		TT_RigidBodyMarker(int rbIndex, int markerIndex, float *x, float *y, float *z);

Description

• This function gets 3D position of a solved Rigid Body marker and saves them in designated addresses. Rigid body marker positions from this function represents solved (or expected) location of the Rigid Body markers. For actual reconstructed marker positions, use the TT_RigidBodyPointCloudMarker function.

• Note that the 3D coordinates obtained by this function is represented in respect to Rigid Body's local coordinate axis. For obtaining 3D coordinate in respect to global coordinates, use TT_RigidBodyPointCloudMarker function.

Function Input

• Rigid body index (int)

• Marker index (int)

• Three declared variable addresses for saving x, y, z coordinates of the marker (float)

Function Output

• Void

C++ Example

//== Listing out all of the Rigid Body markers and its respective position. ==//
int rbcount = TT_RigidBodyCount();

for(int i = 0; i < rbcount; i++)
{
	float	x,y,z;

	for(int j = 0; j < TT_RigidBodyMarkerCount(i); j++)
	{
		printf("Rigid Body:%s\t Marker #%d\n", TT_RigidBodyName(i), j);
		
		//== Marker Locations ==//
		TT_RigidBodyMarker(i, j, &x, &y, &z);
		printf("Local: (%f, %f, %f)\n", x, y, z);
	}
}

TT_RigidBodyUpdateMarker

Changes and updates the Rigid Body marker positions.

bool     TT_RigidBodyUpdateMarker( int rbIndex, int markerIndex, float *x, float *y, float *z );

Description

• This function is used to change the expected positions of a single Rigid Body marker.

• Rigid body markers are expected marker positions. Read about marker types in Motive.

Function Input

• Rigid body index (int)

• Marker index (int)

• New x-position of the Rigid Body marker in respect to the local coordinate system.

• New y-position of the Rigid Body marker in respect to the local coordinate system.

• New z-position of the Rigid Body marker in respect to the local coordinate system.

Function Output

• Returns true if marker locations have been successfully updated.

TT_RigidBodyPointCloudMarker

Saves 3D coordinates of a Rigid Body marker in respect to the global space.

void		TT_RigidBodyPointCloudMarker(int rbIndex, int markerIndex, bool &tracked, float &x, float &y, float &z);

Description

• This function saves 3D coordinates of each Rigid Body marker in designated addresses.

• 3D coordinates are saved in respect to global coordinate system.

Function Input

• Rigid body index (int)

• Marker index (int)

• Tracked status, True or False (bool)

• Three declared variable addresses for saving x, y, z coordinates of the marker (float).

Function Output

• Void

C++ Example

//== Listing out all of the Rigid Body markers and its respective position. ==//
int rbcount = TT_RigidBodyCount();

for(int i = 0; i < rbcount; i++)
{
	float	gx, gy, gz;
	bool	tracked;

	for(int j = 0; j < TT_RigidBodyMarkerCount(i); j++)
	{
		printf("Rigid Body:%s\t Marker #%d\n", TT_RigidBodyName(i), j);
		 
		//== Rigid Body Marker Global Coordinates ==//
		TT_RigidBodyPointCloudMarker(i, j, tracked, gx, gy, gz);
		printf("Global: (%f, %f, %f)\n", x, y, z);
	}
}

TT_RigidBodyPlacedMarker

Saves 3D coordinates of a Rigid Body solved marker positions in respect to the global space. Unlike TT_RigidBodyPointCloudMarker function, it does not report point cloud solved positions, but it reports the expected marker positions in respect to Rigid Body position and orientation.

void		TT_RigidBodyPlacedMarker(int rbIndex, int markerIndex, bool &tracked, float &x, float &y, float &z);

Description

• This function saves 3D coordinates of each expected Rigid Body marker positions in designated variable addresses.

• 3D coordinates are saved in respect to global coordinate system.

Function Input

• Rigid body index (int)

• Marker index (int)

• Tracked status, True or False (bool)

• Three declared variable addresses for saving x, y, z coordinates of the marker (float).

Function Output

• Void

C++ Example

//== Listing out all of the Rigid Body markers and its respective position. ==//
int rbcount = TT_RigidBodyCount();

for(int i = 0; i < rbcount; i++)
{
	float	gx, gy, gz;
	bool	tracked;

	for(int j = 0; j < TT_RigidBodyMarkerCount(i); j++)
	{
		printf("Rigid Body:%s\t Marker #%d\n", TT_RigidBodyName(i), j);
		 
		//== Expected Rigid Body marker positions. ==//
		TT_RigidBodyPlacedMarker(i, j, tracked, gx, gy, gz);
		printf("Global: (%f, %f, %f)\n", x, y, z);
	}
}

TT_RigidBodyID

This function is used for obtaining unique identifiers for a specific Rigid Body indicated by the Rigid Body index number.

Core::cUID		TT_RigidBodyID( int rbIndex );

Function Input

• Rigid body index (int)

Function Output

• Rigid body unique ID (Core::cUID)

TT_CreateRigidBody

Creates a Rigid Body asset from a set of reconstructed 3D markers.

NPRESULT		TT_CreateRigidBody(const char* name, int userDataID, int markerCount, float *markerList);

Description

• This functions creates a Rigid Body from the marker list and marker count provided in its argument.

• The marker list is expected to contain a list of marker coordinates in the following order: (x1, y1, z1, x2, y2, z2, …, xN, yN, zN). The x/y/z coordinates must be in respect to the Rigid Body pivot point, in meters.

• Inputted 3D locations are taken as Rigid Body marker positions about the Rigid Body pivot point. If you are using TT_FrameMarkerX/Y/Z functions to obtain the marker coordinates, you will need to subtract the pivot point location from the global marker locations when creating a Rigid Body. This is shown in the below example. If this is not done, created Rigid Body will have its pivot point at the global origin.

• Returns an NPRESULT integer value. If the Rigid Body was successfully created, it returns 0 or NPRESULT_SUCCESS.

Function Input

• Rigid body name (char)

• User Data ID (int)

• Marker Count (int)

• Marker list (float list)

Function Output

• NPRESULT

C++ Example

int markerCount = TT_FrameMarkerCount;
vector<float> markerListRelativeToGlobal;

// add markers to markerListRelativeToGlobal using TT_FrameMarkerX, etc
for (int i = 0; i < markerCount; ++i)
{
    	markerListRelativeToGlobal.push_back(TT_FrameMarkerX(i));
    	markerListRelativeToGlobal.push_back(TT_FrameMarkerY(i));
	markerListRelativeToGlobal.push_back(TT_FrameMarkerZ(i));
}

// then average the locations in x, y and z
float sx = 0, sy = 0, sz = 0;
for (int i = 0; i < markerCount; ++i)
{
    	sx += markerListRelativeToGlobal[3*i];
    	sy += markerListRelativeToGlobal[3*i + 1];
    	sz += markerListRelativeToGlobal[3*i + 2];
}


float ax = sx/markerCount;
float ay = sy/markerCount;
float az = sz/markerCount;


vector<float> pivotPoint = {ax, ay, az};
vector<float> markerListRelativeToPivotPoint;

// subtract the pivot point location from the marker location
for (int i = 0; i < markerCount; ++i)
{
    markerListRelativeToPivotPoint.push_back(markerListRelativeToGlobal[3*i] - ax);
    markerListRelativeToPivotPoint.push_back(markerListRelativeToGlobal[3*i + 1] - ay);
    markerListRelativeToPivotPoint.push_back(markerListRelativeToGlobal[3*i + 2] - az);
}

TT_CreateRigidBody("Rigid Body New", 1, markerCount, markerListRelativeToPivotPoint);

TT_RigidBodySettings

Obtains Rigid Body settings for a given asset, and saves them in a cRigidBodySettings instance.

NPRESULT		TT_RigidBodySettings(int rbIndex, RigidBodySolver::cRigidBodySettings &settings);

Description

• This function obtains Rigid Body settings for a given Rigid Body asset and saves them into a declared cRigidBodySetting instance address.

• Rigid body settings are saved into an instance of the cRigidBodySettings class.

• For detailed information on member function and variables in the cRigidBodySettings class, refer to its declaration in the RigidBodySettings.h header file.

• Returns a NPRESULT integer value.

Function Input

• Rigid body index (int)

• declared instance address (cRigidBodySettings)

Function Output

• NPRESULT

C++ Example

//== Constructor at the Beginning of the program ==//
RigidBodySolver::cRigidBodySettings::cRigidBodySettings()	{};

//== Obtaining Rigid Body Settings ==//
int rbcount = TT_RigidBodyCount();
RigidBodySolver::cRigidBodySettings	settings;

for( int i = 0; i < rbcount; i++ )
{
	TT_RigidBodySettings(i, settings);

	printf("Rigid Body: %s\n", TT_RigidBodyName(i));

	//== Printing Some of the Settings==// 
	printf("MaxMarkerDeflection: %f\n", settings.MaxMarkerDeflection);
	printf("MinimumMarkerCount: %d\n", settings.MinimumMarkerCount);

	if (settings.Unique) 
	{
		printf("Unique: True\n");
	}
}

TT_SetRigidBodySettings

Changes property settings of a Rigid Body.

NPRESULT		TT_SetRigidBodySettings(int rbIndex, RigidBodySolver::cRigidBodySettings &settings);

Description

• This function assigns a set of Rigid Body settings to a Rigid Body asset.

• An instance of cRigidBodySettings will be attached to the provided Rigid Body.

• Returns a NPRESULT integer value. If the marker was successfully created, it returns 0 (NPRESULT_SUCCESS).

Function Input

• Rigid body index (int)

Function Output

• NPRESULT

C++ Example

//== Constructor at the Beginning of the program ==//
int rbcount = TT_RigidBodyCount();
RigidBodySolver::cRigidBodySettings::cRigidBodySettings()	{};

RigidBodySolver::cRigidBodySettings	settings;

for(int i = 0; i < rbcount; i++)
{

	//== Obtaining configured settings for each Rigid Body ==//
	TT_RigidBodySettings(i, settings);

	if(settings.Unique){
		printf("Rigid Body #%d is already set to Unique", i);
	}
	else
	{
 		//== Setting/assigning all Rigid Bodies to Unique ==//
		settings.Unique = TRUE;
 		TT_SetRigidBodySettings(i,settings);

		printf("Rigid Body #%d has been set to Unique", i);
}

TT_RigidBodyRefineStart

Initiates the Rigid Body refinement process. Input the number of samples and the ID of the Rigid Body you wish to refine. After starting the process, TT_RigidBodyRefineSample bust be called on everyframe in order to collect samples.

bool     TT_RigidBodyRefineStart( Core::cUID rigidBodyID, int sampleCount );

Description

• This function is used to start Rigid Body refinement.

Function Input

• Target Rigid Body ID

• Sample count (int)

Function Output

• Returns true if the refinement process has successfully initiated.

TT_RigidBodyRefineSample

This function collects samples for Rigid Body refinement started by calling the TT_RigidBodyRefineStart function. Call this function for every frame; within the update loop. You can check the progress of calibration by calling the TT_RigidBodyRefineProgress function.

bool     TT_RigidBodyRefineSample();

Description

• This function collects sample Rigid Body tracking data for refining the definition of corresponding Rigid Body.

Function Input

• None. Samples frames for the initialized refine process.

Function Output

• Returns true if the refinement process has successfully collected a sample. This function does not collect samples if Rigid Body is not tracked on the frame.

TT_RigidBodyRefineState

This function inquiries the state of the refinement process. It returns TT_RigidBodyRefineStates enum as a result.

TT_RIgidBodyRefineStates     TT_RigidBodyRefineState();

Description

• This function queries the state of the Rigid Body refinement process. It returns an enum value for indicating whether the proess is intialized, sampling, solving, complete, or uninitialized.

<source> enum TT_RigidBodyRefineStates {

   TT_RigidBodyRefine_Initialized = 0,
   TT_RigidBodyRefine_Sampling,
   TT_RigidBodyRefine_Solving,
   TT_RigidBodyRefine_Complete,
   TT_RigidBodyRefine_Uninitialized

};

</source>

Function Input

• None. Checks the state on the ongoing refinement process.

Function Output

• Returns TT_RigidBodyRefineStates enum value.

TT_RigidBodyRefineProgress

This function inquiries the progress of the refinement sampling process.

float     TT_RigidBodyRefintProgress();

Description

• When the refinement process is under the sampling state, calling this function returns the sampling progress. It will return a percentage value representing the sampling progress in respect to the total number of samples given in the TT_RigidBodyRefineStart parameter.

Function Input

• None. Checks the progress on the ongoing refinement process.

Function Output

• Returns percentage completness of the sampling process (float).

TT_RigidBodyRefineInitialError / TT_RigidBodyRefineResultError

These two functions returns error values of the Rigid Body definition before and after the refinement.

float     TT_RigidBodyRefineInitialError();
float     TT_RigidBodyRefineResultError();

Description

• Once the refinement process has reached complete stage, these two functions can be called to compare the error values from corresponding Rigid Body defintion before and after the refinement.

Function Input

• None.

Function Output

• Average error value of the target Rigid Body defintion prior (TT_RigidBodyRefineInitialError) and after (TT_RigidBodyRefineResultError) the refinement.

TT_RigidBodyRefineApplyResult

This function applies the refined result to the corresponding Rigid Body definition.

bool     TT_RigidBodyRefineApplyResult();

Description

• This function applies the refined Rigid Body definition. After comparing the error values before and after the refinement using TT_RigidBodyRefineInitialError and TT_RigidBodyRefineResultError functions, use this function to apply if the results are satisfying.

Function Input

• None.

Function Output

• Returns true if the refined results have been successfully applied.

TT_RigidBodyRefineReset

This function discards the final refinement result and resets the refinement process.

bool     TT_RigidBodyRefineReset();

Description

• If the final refinement result from the TT_RigidBodyRefineResultError call is not satisfying, you can call this function to discard the result and start over from the sampling process again.

Function Input

• None.

Function Output

• Returns true if the refined results have been successfully resetted.

Camera Group

TT_GetCameraManager

Returns pointer to the CameraManager instance.

CameraLibrary::CameraManager*		TT_GetCameraManager();

Description

• This function returns a pointer to the CameraManager instance from the Camera SDK.

• Camera SDK must be installed to use this function.

• The version number of Motive and the Camera SDK must match.

• Corresponding headers and libraries must be included in the program.

Function Input

• None

Function Output

• Pointer to the CameraManager instance (CameraLibrary::CameraManager*)

C++ Example

CameraLibrary::CameraManager *cman = TT_GetCameraManager();
// cman is declared as a pointer to a camera manager used in conjuction with the Camera SDK

TT_BuildNumber

Returns Motive build number.

Description

• This function returns corresponding Motive build number.

Function Input

• None

Function Output

• Build number (int)

C++ Example

//== Printing Motive Build Number ==//
printf("Motive Build: %d\n", TT_BuildNumber());

TT_CameraGroupCount

Returns camera group count.

int		TT_CameraGroupCount();

Description

• This function returns total count of camera groups that are involved in the project.

Function Input

• None

Function Output

• Camera group count (int)

C++ Example

int groupcount = TT_CameraGroupCount();

//== Processing Camera Groups ==//
for(int i = 0; i < groupcount; i++)
{
	//== Process each camera group ==//
}

TT_CreateCameraGroup

Creates a new camera group.

bool		TT_CreateCameraGroup();

Description

• This function adds an additional camera group (empty) to a project.

• Note: Creating an additional camera group is unnecessary for most applications. Most common case is to group cameras to set them as a reference group for recording grayscale videos.

Function Input

• None

Function Output

• True/False (bool)

C++ Example

//== Creating a new camera group ==//
TT_CreateCameraGroup();

TT_RemoveCameraGroup

Removes a camera group.

bool		TT_RemoveCameraGroup(groupIndex);

Description

• This function removes a camera group, specified by its index number.

• The camera group must contain no cameras in order to be removed.

• Returns true if the group was successfully removed.

Function Input

• Camera group index (int)

Function Output

• True/False (bool)

C++ Example

//== For projects with multiple camera groups ==//
int cameracount = TT_CameraCount();
int groupcount = TT_CameraGroupCount();

if(groupcount  > 1)
{
	//== Moving all cameras to the first camera group (index = 0) ==//
	for(int i = 0; i < cameracount; i++)
	{
		TT_SetCameraGroup( i, 0);
	}
	
	//== Removing all other camera groups==//
	for(int j = 1; j < groupcount; j++)
	{
		TT_RemoveCameraGroup(j);
	}
}

TT_CamerasGroup

Returns an index value of a camera group that a camera is involved in.

int		TT_CamerasGroup(int cameraIndex);

Description

• This function takes an index value of a camera and returns corresponding camera group index which the camera is involved in.

Function Input

• Camera index (int)

Function Output

• Camera group index (int)

C++ Example

//== Listing out all of the cameras and their associate group index ==//
int cameracount = TT_CameraCount();

for(int i = 0; i < cameracount; i ++)
{
	printf("Camera: %s\t CameraGroup: #%d", TT_CameraName(i), TT_CamerasGroup(i));
}

TT_SetGroupShutterDelay

Introduces shutter delay to a camera group.

void		TT_SetGroupShutterDelay(int groupIndex, int microseconds);

Description

• This function sets a shutter delay (in microseconds) to a camera group, which is designated by its index number.

• After assigning the delay, all of the cameras involved in the camera group will shutter at a delayed timing when recording.