NatNet: Class/Function Reference

Back to the Main pageBack to the NatNet SDK page


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. For additional information, refer to the provided headers files (native) or reference the NatNatML.dll file (managed).


Note:

  • Deprecated methods from previous SDK versions are not documented on this page, and their use in new applications is discouraged. They are subject to removal in a future version of the SDK. Refer to the header files for complete descriptions.
  • The NatNetServer class is being deprecated for future releases of NatNet and is not documented on this page. Motive should be used for testing client applications, and trial licenses will be provided upon request if you don't have access to Motive software.
  • Note that some parts of the managed .NET assembly may be slightly different from the native library reference provided here. Refer to the NatNetML.dll file using an object browser for detailed information.


ErrorCode[edit]


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

Error Name Integer Description
ErrorCode_OK 0 Operation successful
ErrorCode_Internal 1 Suspect internal errors. Contact support.
ErrorCode_External 2 External errors. Make sure correct parameters are used for input arguments when calling the methods.
ErrorCode_Network 3 The error occurred on the network side.
ErrorCode_Other 4 Unlisted error is conflicting the method call.


NatNetClient Class[edit]


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[edit]

NatNetClient::NatNetClient()[edit]

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


NatNetClient::NatNetClient(iConnectionType)[edit]

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()[edit]

Destructor: Destructor


Member Methods[edit]

NatNetClient::Initialize[edit]

int   Initialize( const char* szLocalAddress, const char* szServerAddress );
int   Initialize( const char* szLocalAddress, const char* szServerAddress,
			   int hostCommandPort=0, const char* szMulticastAddress = 0 );
Description[edit]
This method connects an instantiated NatNetClient object to a server application (e.g. Motive) at the inputted IP address.
Input Parameters:[edit]
  • Local address. IP address of the localhost where the client application is running.
  • Server address. IP address where the server application is streaming to.
  • (Optional) Command port. Defaults to 1510.
  • (Optional) Data port. Defaults to 1511.
  • (Optional) Multicast IP address. Defaults to 239.255.42.99:1511.
Returns:[edit]
ErrorCode, On success, it returns 0.


NatNetClient::Uninitialize[edit]

int   Uninitialize();
Description[edit]
Calling this method disconnects the client from the Motive server application.
Input Parameters:[edit]
  • None
Returns:[edit]
ErrorCode, On success, it returns 0 or ErrorCode_OK.


NatNetClient::GetServerDescription[edit]

int   GetServerDescription( sServerDescription* pServerDescription );
Description[edit]
Requests descriptions 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:[edit]
  • Pointer to an sServerDescription object which is populated with the requested information on success.
Returns:[edit]
ErrorCode, On success, it returns 0 or ErrorCode_OK.


NatNetClient::GetDataDescriptions[edit]

int   GetDataDescriptions( sDataDescriptions** pDataDescriptions );
Description[edit]
Requests a list of dataset descriptions of the capture session and saves onto the declared instance of sDataDescriptions.
Input Parameters:[edit]
  • 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:[edit]
ErrorCode, On success, it returns 0 or ErrorCode_OK.


NatNetClient::GetLastFrameOfData[edit]

sFrameOfMocapData*   GetLastFrameOfData();
Description[edit]
Requests a single instance of sFrameOfMocapData for the most recent mocap frame received from the server.
Input Parameters:[edit]
  • None
Returns:[edit]
sFrameOfMocapData


NatNetClient::SetDataCallback[edit]

int   SetDataCallback(void (*CallbackFunction)(sFrameOfMocapData* pFrameOfData, void* pUserData), 
                                                                              void* pUserData=0);
Description[edit]

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:[edit]
  • CallbackFunction: A callback function invoked to handle each incoming frame of tracking data. The prototype of the provided function must agree with the declared input parameter. For example:
void __cdecl DataHandler(sFrameOfMocapData* data, void* pUserData);
  • pUserData: User definable context data, to be provided as the second argument to the specified CallbackFunction when it is subsequently invoked.
Returns:[edit]
ErrorCode, On success, it returns 0 or ErrorCode_OK.


NatNetClient::SendMessageCallback[edit]

int SetMessageCallback(void (*CallbackFunction)(int id, char *szTraceMessage));
Description[edit]
This function assignes a callback handler function for receiving and reporting error/debug messages.
Input Parameters:[edit]
  • CallbackFunction: A callback function for handling the log messages that are sent out from the server application. The prototype of the provided function must agree with the declared input parameter. For example:
void __cdecl MessageHandler(int msgType, char* msg);
Returns:[edit]
  • Void


NatNetClient::SendMessageAndWait[edit]

int   SendMessageAndWait( const char* szRequest,
			   void** ppServerResponse, 
			   int* pResponseSize );
int   SendMessageAndWait( const char* szRequest,
			   int tries, int timeout, 
			   void** ppServerResponse,
			   int* pResponseSize );
Description[edit]
Sends a remote command to the NatNet server and waits for a response. See NatNet: Remote Requests/Commands for more details.
Input Parameters:[edit]
  • szRequest: NatNet command.
  • (Optional) tries: Number of attempts to send the command. Default: 10.
  • (Optional) 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:[edit]
ErrorCode, On success, it returns 0 or ErrorCode_OK.


NatNetClient::NatNetVersion[edit]

void   NatNetVersion( unsigned char outVersion[4] );
Description[edit]
This function gets the version (#.#.#.#) of the NatNet SDK and saves it into an array.
Input Parameters:[edit]
  • Unsigned char array with a array length of 4.
Returns:[edit]
  • Void


NatNetClient::DecodeID[edit]

void   DecodeID( int compositeId,
		  int* pOutEntityId,
		  int* pOutMemberId );
Description[edit]
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:[edit]
  • 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:[edit]
  • Void


NatNetClient::DecodeTimecode[edit]

bool   DecodeTimecode(unsigned int inTimecode, unsigned int inTimecodeSubframe,
			int* hour, int* minute, int* second, int* frame, int* subframe);
Description[edit]
Helper function to decode OptiTrack timecode data into individual components.
Input Parameters:[edit]
  • 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:[edit]
  • ErrorCode, On success, it returns 0 or ErrorCode_OK.


NatNetClient::TimecodeStringify[edit]

bool	DecodeTimecode( unsigned int inTimecode, 
			unsigned int inTimecodeSubframe,
			char* Buffer,
			int BufferSize );
Description[edit]
Helper function to parse OptiTrack timecode into a user friendly string in the form hh:mm:ss:ff:yy
Input Parameters:[edit]
  • inTimecode: Timecode integer from a packet of sFrameOfMocapData.
  • inTimecodeSubframe: TimecodeSubframe integer from a packet of sFrameOfMocapData.
  • Buffer: Declared char for saving the output.
  • BufferSize: size of the character array of the output buffer.
Returns:[edit]
  • ErrorCode, On success, it returns 0 or ErrorCode_OK.


NatNetClient::CopyFrame[edit]

void   CopyFrame( sFrameOfMocapData* pSrc, sFrameOfMocapData* pDst );
Description[edit]
This helper function performs a deep copy of frame data from pSrc into pDst. Some members of pDst will be dynamically allocated; call NatNetClient::FreeFrame method with pDst input to clean them up.
Input Parameters:[edit]
  • Pointer to two sFrameOfMocapData variables to copy from (pSrc) and copy to (pDst).
Returns:[edit]
  • ErrorCode, On success, it returns 0 or ErrorCode_OK.


NatNetClient::FreeFrame[edit]

void   FreeFrame( sFrameOfMocapData* pFrame );
Description[edit]
Frees the dynamic members of a frame copy created using CopyFrame. Do not call this on any frame that was not the destination of such a copy.
Input Parameters:[edit]
  • sFrameOfMocapData that has been copied using the NatNetClient::CopyFrame method.
Returns:[edit]
  • ErrorCode, On success, it returns 0 or ErrorCode_OK.