Difference between revisions of "NatNet: Class/Function Reference"

 
(39 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Construction}}
+
[[Main Page|Main page]] → [[NatNet SDK|NatNet SDK]] → [[NatNet: Class/Function Reference]]
 
----
 
----
[[NatNet SDK|Back to the NatNet SDK page]]
 
----
 
 
 
__TOC__
 
  
  
 
This page provides function and class references of the NatNet SDK library.
 
This page provides function and class references of the NatNet SDK library.
  
The [[#NatNetClient Class|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).
+
The [[#NatNetClient Class|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. [[#NatNet C++ API Functions|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).
 
 
The NatNetServer class is being deprecated for future releases of NatNet and it 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.
 
 
 
  
 +
{{Info|
 
'''Note:'''
 
'''Note:'''
<div style="padding-left:1em;">
+
:* NatNet SDK is backwards compatible.
* NatNet SDK is backwards compatible. Deprecated methods from previous SDK versions are not listed on this page but they are still supported.
+
:* 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.
* 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.
+
:* The NatNetServer class has been deprecated for versions 3.0 and above.
</div>
+
:* 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.
 +
}}
  
  
Line 25: Line 19:
 
----
 
----
  
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:
+
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:
  
 
{|class="wikitable" style="margin:auto"
 
{|class="wikitable" style="margin:auto"
!style="padding:1em;"|Error Name
+
!style="padding:1.5%;"|Error Name
!style="padding:1em;"|Integer
+
!style="padding:1.5%;"|Integer
!style="padding:1em;"|Description
+
!style="padding:1.5%;"|Description
 +
|-
 +
|style="padding:1.5%;"|ErrorCode_OK
 +
|style="padding:1.5%;"|0
 +
|style="padding:1.5%;"|Operation successful
 
|-
 
|-
|style="padding:1em;"|ErrorCode_OK
+
|style="padding:1.5%;"|ErrorCode_Internal
|style="padding:1em;"|0
+
|style="padding:1.5%;"|1
|style="padding:1em;"|Operation successful
+
|style="padding:1.5%;"|Suspect internal errors. Contact support.
 
|-
 
|-
|style="padding:1em;"|ErrorCode_Internal
+
|style="padding:1.5%;"|ErrorCode_External
|style="padding:1em;"|1
+
|style="padding:1.5%;"|2
|style="padding:1em;"|Suspect internal errors. Contact support.
+
|style="padding:1.5%;"|External errors. Make sure correct parameters are used for input arguments when calling the methods.
 
|-
 
|-
|style="padding:1em;"|ErrorCode_External
+
|style="padding:1.5%;"|ErrorCode_Network
|style="padding:1em;"|2
+
|style="padding:1.5%;"|3
|style="padding:1em;"|External errors. Make sure correct parameters are used for input arguments when calling the methods.
+
|style="padding:1.5%;"|The error occurred on the network side.
 
|-
 
|-
|style="padding:1em;"|ErrorCode_Network
+
|style="padding:1.5%;"|ErrorCode_Other
|style="padding:1em;"|3
+
|style="padding:1.5%;"|4
|style="padding:1em;"|The error occurred on the network side.
+
|style="padding:1.5%;"|Unlisted error is conflicting the method call.
 
|-
 
|-
|style="padding:1em;"|ErrorCode_Other
+
|style="padding:1.5%;"|ErrorCode_InvalidArgument
|style="padding:1em;"|4
+
|style="padding:1.5%;"|5
|style="padding:1em;"|Unlisted error is conflicting the method call.
+
|style="padding:1.5%;"|Invalid input arguments have been inputted.
 +
|-
 +
|style="padding:1.5%;"|ErrorCode_InvalidOperation
 +
|style="padding:1.5%;"|6
 +
|style="padding:1.5%;"|Invalid operation.
 
|}
 
|}
  
Line 56: Line 58:
 
=NatNetClient Class=
 
=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 [[NatNet SDK#File List|NatNetClient.h]] header file included in the SDK.
+
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 [[NatNet_SDK_3.0#Library_Header_Files:_NatNet_SDK.5Cinclude|NatNetClient.h]] header file included in the SDK.
  
 
<div style="padding-left:2em;">
 
 
==Constructor and Destructor==
 
==Constructor and Destructor==
  
 
+
<div class="padded">
 
 
<div style="padding-left:2em;">
 
 
====NatNetClient::NatNetClient()====
 
====NatNetClient::NatNetClient()====
<div style="padding-left:2em;">
+
<div class="padded">
 
'''Constructor:''' Creates a new instance of a NatNetClient class. Defaults to multicast connection if no input is given.
 
'''Constructor:''' Creates a new instance of a NatNetClient class. Defaults to multicast connection if no input is given.
 
</div>
 
</div>
 
  
 
====NatNetClient::NatNetClient(iConnectionType)====
 
====NatNetClient::NatNetClient(iConnectionType)====
<div style="padding-left:2em;">
+
<div class="padded">
 
'''Constructor:''' Creates a new instance of a NatNet Client using the specified connection protocol; either unicast or multicast.
 
'''Constructor:''' Creates a new instance of a NatNet Client using the specified connection protocol; either unicast or multicast.
  
 
'''Input:''' iConnectionType: (0 = Multicast, 1 = Unicast).
 
'''Input:''' iConnectionType: (0 = Multicast, 1 = Unicast).
 +
 +
{{Info|This approach is being deprecated. The NatNetClient class now determines the connection type through sNatNetClientConnectParams input when calling the '''NatNetClient::Connect''' method.}}
 
</div>
 
</div>
 
  
 
====NatNetClient::~NatNetClient()====
 
====NatNetClient::~NatNetClient()====
<div style="padding-left:2em;">
+
<div class="padded">
 
'''Destructor:''' Destructor
 
'''Destructor:''' Destructor
 
</div>
 
</div>
 
</div>
 
</div>
 
 
  
 
==Member Methods==
 
==Member Methods==
  
 
+
<div class="padded">
<div style="padding-left:2em;">
+
===NatNetClient::Connect===
===NatNetClient::Initialize===
+
<div class="padded">
<div style="padding-left:2em;">
+
  ErrorCode        Connect( const sNatNetClientConnectParams& connectParams );
  int  Initialize( const char* szLocalAddress, const char* szServerAddress );
+
<div class="padded">
 
 
int  Initialize( const char* szLocalAddress, const char* szServerAddress,
 
  int hostCommandPort=0, const char* szMulticastAddress = 0 );
 
 
 
<div style="padding-left:2em;">
 
 
=====Description=====
 
=====Description=====
 
:This method connects an instantiated NatNetClient object to a server application (e.g. Motive) at the inputted IP address.
 
:This method connects an instantiated NatNetClient object to a server application (e.g. Motive) at the inputted IP address.
  
 
=====Input Parameters:=====
 
=====Input Parameters:=====
 +
:* Connection parameters object.
 +
 +
=====Returns:=====
 +
:[[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 +
 +
{{Info|
 +
'''sNatNetClientConenectParams:'''
 +
:* Declared under the ''NatNetTypes.h'' file.
 
:* Local address. IP address of the localhost where the client application is running.
 
:* Local address. IP address of the localhost where the client application is running.
 
:* Server address. IP address where the server application is streaming to.
 
:* Server address. IP address where the server application is streaming to.
Line 109: Line 108:
 
:* (Optional) Multicast IP address. Defaults to 239.255.42.99:1511.
 
:* (Optional) Multicast IP address. Defaults to 239.255.42.99:1511.
  
=====Returns:=====
+
typedef struct sNatNetClientConnectParams
:[[#ErrorCode|ErrorCode]], On success, it returns 0.
+
{
 +
    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;
 +
}}
 
</div>
 
</div>
 
</div>
 
</div>
  
 +
===NatNetClient::Disconnect===
 +
<div class="padded">
 +
ErrorCode        Disconnect();
  
===NatNetClient::Uninitialize===
+
<div class="padded">
<div style="padding-left:2em;">
 
int  Uninitialize();
 
 
 
<div style="padding-left:2em;">
 
 
=====Description=====
 
=====Description=====
 
:Calling this method disconnects the client from the Motive server application.
 
:Calling this method disconnects the client from the Motive server application.
Line 131: Line 149:
 
</div>
 
</div>
  
 +
===NatNetClient::SetFrameReceivedCallback===
 +
<div class="padded">
 +
ErrorCode        SetFrameReceivedCallback( NatNetFrameReceivedCallback pfnDataCallback, void* pUserContext = 0 );
  
===NatNetClient::GetServerDescription===
+
<div class="padded">
<div style="padding-left:2em;">
+
=====Description=====
int  GetServerDescription( sServerDescription* pServerDescription );
+
<div class="padded">
 +
This method sets a frame handler function and creates a new thread for receiving and processing each frame of capture data.
  
<div style="padding-left:2em;">
+
* Managed Assembly: Use ''OnFrameReady'' event type to add a function delegate.
=====Description=====
+
</div>
: 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:=====
 
=====Input Parameters:=====
:* Declared sServerDescription object.
+
<div class="padded">
 +
* 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:
 +
 
 +
::<code>typedef void (NATNET_CALLCONV* NatNetFrameReceivedCallback)(sFrameOfMocapData* pFrameOfData, void* pUserData);</code>
 +
 
 +
* User definable data: the Client object.
 +
</div>
  
 
=====Returns:=====
 
=====Returns:=====
:[[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
+
<div class="padded">
 +
[[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 +
</div>
 
</div>
 
</div>
 
</div>
 
</div>
  
 +
===NatNetClient::SendMessageAndWait===
 +
<div class="padded">
 +
ErrorCode SendMessageAndWait( const char* szRequest,
 +
                                    void** ppServerResponse,
 +
                                    int* pResponseSize );
  
===NatNetClient::GetDataDescriptions===
+
ErrorCode SendMessageAndWait( const char* szRequest,
<div style="padding-left:2em;">
+
                                    int tries, int timeout,
int   GetServerDescription( sDataDescriptions** pDataDescriptions );
+
                                    void** ppServerResponse,
 +
                                    int* pResponseSize );
  
<div style="padding-left:2em;">
+
<div class="padded">
 
=====Description=====
 
=====Description=====
: Requests a list of [[NatNet: Data Types#Dataset Descriptions|dataset descriptions]] of the capture session and saves onto the declared instance of sDataDescriptions.
+
:Sends a NatNet command to the NatNet server and waits for a response. See [[NatNet: Remote Requests/Commands|NatNet: Remote Requests/Commands]] for more details.
  
 
=====Input Parameters:=====
 
=====Input Parameters:=====
:* Declared sDataDescriptions object.
+
:* 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:=====
 
=====Returns:=====
 
:[[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 
:[[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
</div>
+
</div></div>
</div>
 
  
 +
===NatNetClient::GetServerDescription===
 +
<div class="padded">
 +
ErrorCode        GetServerDescription( sServerDescription* pServerDescription );
  
===NatNetClient::GetLastFrameOfData===
+
<div class="padded">
<div style="padding-left:2em;">
 
sFrameOfMocapData*  GetLastFrameOfData();
 
<div style="padding-left:2em;">
 
 
=====Description=====
 
=====Description=====
: Requests a single instance of sFrameOfMocapData for the most recent mocap frame received from the server.
+
: Requests a [[Sandbox#Dataset Descriptions|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:=====
 
=====Input Parameters:=====
:* None
+
:* Declared sServerDescription object.
  
 
=====Returns:=====
 
=====Returns:=====
:sFrameOfMocapData
+
:[[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 
</div>
 
</div>
 
</div>
 
</div>
  
 +
===NatNetClient::GetDataDescriptionList===
 +
<div class="padded">
 +
int  GetDataDescriptions( sDataDescriptions** pDataDescriptions );
  
===NatNetClient::SetDataCallback===
+
<div class="padded">
<div style="padding-left:2em;">
 
int  SetDataCallback(void (*CallbackFunction)(sFrameOfMocapData* pFrameOfData, void* pUserData),
 
                                                                              void* pUserData=0);
 
<div style="padding-left:2em;">
 
 
=====Description=====
 
=====Description=====
This method sets a frame handler function and creates a new thread for receiving and processing each frame of capture data.
+
: Requests a list of [[NatNet: Data Types#Dataset Descriptions|dataset descriptions]] of the capture session and saves onto the declared instance of sDataDescriptions.
 
 
* Managed Assembly: Use ''OnFrameReady'' event type to add a function delegate.
 
  
 
=====Input Parameters:=====
 
=====Input Parameters:=====
:* CallbackFunction: Afunction for handling each incoming frame of tracking data. Format of the inputted function must agree with the declared input argument. For example:
+
:* 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.
 
 
::<code>void __cdecl DataHandler(sFrameOfMocapData* data, void* pUserData);</code>
 
 
 
:* User definable data: the Client object.
 
  
 
=====Returns:=====
 
=====Returns:=====
Line 204: Line 235:
 
</div>
 
</div>
  
 +
===NatNetClient::SecondsSinceHostTimestamp===
 +
<div class="padded">
 +
double    SecondsSinceHostTimestamp( uint64_t hostTimestamp ) const;
  
===NatNetClient::SendMessageCallback===
+
<div class="padded">
<div style="padding-left:2em;>
 
int SetMessageCallback(void (*CallbackFunction)(int id, char *szTraceMessage));
 
<div style="padding-left:2em;">
 
 
=====Description=====
 
=====Description=====
:This function assignes a callback handler function for receiving and reporting error/debug messages.
+
: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:=====
 
=====Input Parameters:=====
:* CallbackFunction: A function for handling the log messages that are sent out from the server application. Format of the linked function must agree with the input argument. For example:
+
:* (uint64_t) A timestamp value from a sFrameOfMocapData struct.
 
 
::<code>void __cdecl MessageHandler(int msgType, char* msg);</code>
 
  
 
=====Returns:=====
 
=====Returns:=====
:* Void
+
:(double) The time, in seconds, past since the provided timestamp.
 +
</div>
 
</div>
 
</div>
 
</div>
 
</div>
  
 +
=NatNet C++ API Functions=
 +
----
 +
Once the NatNetSDK library has been imported into a client application, the following helper functions can be used.
  
===NatNetClient::SendMessageAndWait===
+
{{Info|These functions are available ONLY for C++ applications.}}
<div style="padding-left:2em;">
 
int  SendMessageAndWait( const char* szRequest,
 
  void** ppServerResponse,
 
  int* pResponseSize );
 
  
int  SendMessageAndWait( const char* szRequest,
+
<div class="padded">
  int tries, int timeout,
+
==Function list==
  void** ppServerResponse,
+
<div class="padded">
  int* pResponseSize );
+
===NatNet_GetVersion===
<div style="padding-left:2em;">
+
<div class="padded">
=====Description=====
+
  NATNET_API void NATNET_CALLCONV NatNet_GetVersion( unsigned char outVersion[4] );
:Sends a remote command to the NatNet server and waits for a response. See [[NatNet: Remote Requests/Commands]] for more details.
+
<div class="padded">
 
 
=====Input Parameters:=====
 
:* 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:=====
 
:[[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 
</div></div>
 
 
 
 
 
===NatNetClient::NatNetVersion===
 
<div style="padding-left:2em;>
 
void   NatNetVersion( unsigned char outVersion[4] );
 
<div style="padding-left:2em;">
 
 
=====Description=====
 
=====Description=====
 
:This function gets the version (#.#.#.#) of the NatNet SDK and saves it into an array.
 
:This function gets the version (#.#.#.#) of the NatNet SDK and saves it into an array.
Line 264: Line 276:
 
</div>
 
</div>
  
 
+
===NatNet_SetLogCallback===
===NatNetClient::SetVerbosityLevel===
+
<div class="padded">
<div style="padding-left:2em;>
+
  NATNET_API void NATNET_CALLCONV NatNet_SetLogCallback( NatNetLogCallback pfnLogCallback );
void   SetVerbosityLevel(int level);
+
<div class="padded">
<div style="padding-left:2em;">
 
 
=====Description=====
 
=====Description=====
:Sets the message reporting level for internal NatNet messages.
+
:This function assignes a callback handler function for receiving and reporting error/debug messages.
  
 
=====Input Parameters:=====
 
=====Input Parameters:=====
:* Verbosity level (see Verbosity level in NatNetTypes.h)
+
:* 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:
 +
 
 +
::<code>typedef void (NATNET_CALLCONV* NatNetLogCallback)(Verbosity level, const char* message);</code>
  
 
=====Returns:=====
 
=====Returns:=====
Line 280: Line 293:
 
</div>
 
</div>
  
 
+
===NatNet_DecodeID===
===NatNetClient::DecodeID===
+
<div class="padded">
<div style="padding-left:2em;>
+
  NATNET_API void NATNET_CALLCONV NatNet_DecodeID( int compositeId,
void   DecodeID( int compositeId,
+
            int* pOutEntityId,
  int* pOutEntityId,
+
          int* pOutMemberId );
  int* pOutMemberId );
+
<div class="padded">
<div style="padding-left:2em;">
 
 
=====Description=====
 
=====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#Unique ID|NatNet: Data Types]].
 
: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#Unique ID|NatNet: Data Types]].
Line 299: Line 311:
 
</div>
 
</div>
  
 
+
===NatNet_DecodeTimecode===
===NatNetClient::DecodeTimecode===
+
<div class="padded">
<div style="padding-left:2em;>
+
  NATNET_API ErrorCode NATNET_CALLCONV NatNet_DecodeTimecode( unsigned int timecode,
  bool  DecodeTimecode(unsigned int inTimecode, unsigned int inTimecodeSubframe,
+
            unsigned int timecodeSubframe,
int* hour, int* minute, int* second, int* frame, int* subframe);
+
              int* pOutHour, int* pOutMinute,
<div style="padding-left:2em;">
+
              int* pOutSecond, int* pOutFrame,
 +
              int* pOutSubframe );
 +
<div class="padded">
 
=====Description=====
 
=====Description=====
 
:Helper function to decode OptiTrack timecode data into individual components.  
 
:Helper function to decode OptiTrack timecode data into individual components.  
Line 318: Line 332:
 
</div>
 
</div>
  
 
+
===NatNet_TimecodeStringify===
 
+
<div class="padded">
===NatNetClient::TimecodeStringify===
+
  NATNET_API ErrorCode NATNET_CALLCONV NatNet_TimecodeStringify( unsigned int timecode,  
<div style="padding-left:2em;>
+
              unsigned int timecodeSubframe,
  bool DecodeTimecode( unsigned int inTimecode,  
+
              char* outBuffer,
unsigned int inTimecodeSubframe,
+
              int outBufferSize );
char* Buffer,
+
<div class="padded">
int BufferSize );
 
<div style="padding-left:2em;">
 
 
=====Description=====
 
=====Description=====
 
:Helper function to parse OptiTrack timecode into a user friendly string in the form '''hh:mm:ss:ff:yy'''
 
:Helper function to parse OptiTrack timecode into a user friendly string in the form '''hh:mm:ss:ff:yy'''
  
 
=====Input Parameters:=====
 
=====Input Parameters:=====
:* inTimecode: Timecode integer from a packet of sFrameOfMocapData.
+
:* timecode: Timecode integer from a packet of sFrameOfMocapData. (timecode)
:* inTimecodeSubframe: [[OptiTrack Timecode#Timecode Representation|TimecodeSubframe]] integer from a packet of sFrameOfMocapData.
+
:* timecodeSubframe: TimecodeSubframe integer from a packet of sFrameOfMocapData. (timecodeSubframe)
:* Buffer: Declared char for saving the output.
+
:* outBuffer: Declared char for saving the output.
:* BufferSize: size of the character array of the output buffer.
+
:* outBufferSize: size of the character array buffer (outBuffer).
  
 
=====Returns:=====
 
=====Returns:=====
Line 340: Line 352:
 
</div></div>
 
</div></div>
  
 +
===NatNet_CopyFrame===
 +
<div class="padded">
 +
NATNET_API ErrorCode NATNET_CALLCONV NatNet_CopyFrame( sFrameOfMocapData* pSrc,
 +
              sFrameOfMocapData* pDst );
 +
<div class="padded">
 +
=====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).
  
===NatNetClient::CopyFrame===
+
=====Returns:=====
<div style="padding-left:2em;>
+
:* [[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
  void  CopyFrame( sFrameOfMocapData* pSrc, sFrameOfMocapData* pDst );
+
</div>
<div style="padding-left:2em;">
+
</div>
 +
 
 +
===NatNet_FreeFrame===
 +
<div class="padded">
 +
  NATNET_API ErrorCode NATNET_CALLCONV NatNet_FreeFrame( sFrameOfMocapData* pFrame );
 +
<div class="padded">
 
=====Description=====
 
=====Description=====
: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.
+
: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:=====
 
=====Input Parameters:=====
:* Pointer to two sFrameOfMocapData variables to copy from (pSrc) and copy to (pDst).
+
:* sFrameOfMocapData that has been copied using the NatNet_CopyFrame function.
  
 
=====Returns:=====
 
=====Returns:=====
 
:* [[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 
:* [[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 +
 +
{{Indent|{{Warning|Do not call this on any ''pFrame'' data that was not the destination of a call to ''NatNet_CopyFrame''.}}}}
 
</div>
 
</div>
 
</div>
 
</div>
  
 +
===NatNet_FreeDescriptions===
 +
<div class="padded">
 +
NATNET_API ErrorCode NATNET_CALLCONV NatNet_FreeDescriptions( sDataDescriptions* pFrame );
 +
<div class="padded">
 +
=====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|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 +
</div>
 +
</div>
  
===NatNetClient::FreeFrame===
+
===NatNet_BroadcastServerDiscovery===
<div style="padding-left:2em;>
+
<div class="padded">
  void  FreeFrame( sFrameOfMocapData* pFrame );
+
  NATNET_API ErrorCode NATNET_CALLCONV NatNet_BroadcastServerDiscovery( sNatNetDiscoveredServer* outServers, int* pInOutNumServers, unsigned int timeoutMillisec = 1000 );
<div style="padding-left:2em;">
+
<div class="padded">
 
=====Description=====
 
=====Description=====
: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.
+
:Sends broadcast messages to discover active NatNet servers and blocks for a specified time to gather responses.
  
 
=====Input Parameters:=====
 
=====Input Parameters:=====
:* sFrameOfMocapData that has been copied using the NatNetClient::CopyFrame method.
+
:* '''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:=====
 
=====Returns:=====
 
:* [[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 
:* [[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 
</div>
 
</div>
 +
</div>
 +
 +
===NatNet_CreateAsyncServerDiscovery===
 +
<div class="padded">
 +
NATNET_API ErrorCode NATNET_CALLCONV NatNet_CreateAsyncServerDiscovery( NatNetDiscoveryHandle* pOutDiscovery, NatNetServerDiscoveryCallback pfnCallback, void* pUserContext = NULL );
 +
<div class="padded">
 +
=====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|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 
</div>
 
</div>
 
</div>
 
</div>
  
 +
===NatNet_FreeAsyncServerDiscovery===
 +
<div class="padded">
 +
NATNET_API ErrorCode NATNET_CALLCONV NatNet_CreateAsyncServerDiscovery( NatNetDiscoveryHandle* pOutDiscovery, NatNetServerDiscoveryCallback pfnCallback, void* pUserContext = NULL );
 +
<div class="padded">
 +
=====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.
  
[[Category: NatNet SDK]]
+
=====Returns:=====
 +
:* [[#ErrorCode|ErrorCode]], On success, it returns 0 or ErrorCode_OK.
 +
</div>
 +
</div>
 +
</div>

Latest revision as of 23:29, 23 April 2019

Main pageNatNet SDKNatNet: Class/Function Reference


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

Info2.png

Note:

  • NatNet SDK is backwards compatible.
  • 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 has been deprecated for versions 3.0 and above.
  • 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


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:

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.
ErrorCode_InvalidArgument 5 Invalid input arguments have been inputted.
ErrorCode_InvalidOperation 6 Invalid operation.


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

Info2.png

This approach is being deprecated. The NatNetClient class now determines the connection type through sNatNetClientConnectParams input when calling the NatNetClient::Connect method.

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.

Info2.png

sNatNetClientConenectParams:

  • Declared under the NatNetTypes.h file.
  • 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.
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.

Info2.png

These functions are available ONLY for C++ applications.

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.

Warning2.png

Do not call this on any pFrame data that was not the destination of a call to NatNet_CopyFrame.

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.