Difference between revisions of "NatNet SDK 3.1"

(Replaced content with "Category: NatNet SDK Category: Developer Tools Back to the Main page ---- {{Info|NatNet 3.0 is coming soon. Go to the following page for NatNet 2.1...")
Line 3: Line 3:
 
  [[Main Page|Back to the Main page]]
 
  [[Main Page|Back to the Main page]]
 
----
 
----
 +
 +
{{Info|NatNet 3.0 is coming soon. Go to the following page for NatNet 2.10 documentations: http://v110.wiki.optitrack.com/index.php?title=NatNet_SDK}}
  
 
{{Construction}}
 
{{Construction}}
 
'''SDK Overview'''
 
 
{{Indent|
 
The [http://optitrack.com/products/natnet-sdk/ NatNet SDK] is a networking software development kit (SDK) for receiving NaturalPoint data across networks. It allows streaming of live or recorded motion capture data from a tracking server (e.g. Motive) into various client applications. Using the SDK, you can develop custom client applications to receive data packets containing real-time tracking data and send remote commands to the connected server.  NatNet uses the '''UDP protocol''' in conjunction with either '''Point-To-Point Unicast''' or '''IP Multicasting''' for sending and receiving data. The following diagram outlines the major components of a typical NatNet network setup and how they establish communication between NatNet server and client application.
 
 
* For previous versions of NatNet, please refer to the provided PDF user guide that ships with the SDK.
 
}}
 
 
 
{{Info|
 
'''3.0 Update Notes:'''
 
 
:* '''Bit-stream syntax change.''' NatNet 3.0 involves bit-stream syntax changes for implementing streaming of analog data, streaming of additional parameters, and support for other useful remote commands. For client applications using the direct depacketization approach, the corresponding changes must be updated on the client application; otherwise, the client application will not work with newer version of the server application, Motive 2.0. For detailed updates on the bit-stream
 
 
:* Starting from NatNet 3.0, the NatNet library will strictly work only with Motive. This means the new versions of NatNet and other OptiTrack streaming plugins will no longer be compatible with other server applications, such as Arena and Tracking tools.
 
}}
 
 
 
<center>'''''NatNet Component Overview'''''</center>
 
 
 
[[Image:natnetDataFlow.png|center|550 px|NatNet Component Overview]]
 
 
 
'''SDK Contents'''
 
{{Indent|
 
The NatNet SDK consists of the following:
 
* '''NatNet Library:''' Native C++ networking library contents, including the static library file (.lib), the dynamic library file (.dll), and the corresponding header files.
 
* '''NatNet Assembly:''' Managed .NET assembly (NatNetML.dll) for use in .NET compatible clients.
 
* '''NatNet Samples:''' Sample projects and compiled executables designed to be quickly integrated into your code.
 
}}
 
 
'''Additional Info'''
 
{{Indent|
 
* A NatNet server (e.g. Motive) has 2 threads and 2 sockets:  one for sending tracking data to a client and one for sending/receiving commands.
 
* NatNet servers and clients can exist either on a same machine or on separate machines.
 
* Multiple NatNet clients can connect to a single NatNet server. 
 
* When a NatNet server is configured to use IP Multicast, the data is broadcasted only once, to the Multicast group.
 
* Default multicast IP address: 239.255.42.99 and Port: 1511.
 
* IP address for unicast is defined by a server application.
 
}}
 
 
 
=File List=
 
----
 
 
The NatNet SDK is shipped in a compressed ZIP file format. Within the unzipped NatNet SDK directory, the following contents are included:
 
 
<div class="padded">
 
====Sample Projects: <code>NatNet SDK\Samples</code>====
 
<div class="padded">
 
The Sample folder, contains Visual Studio 2013 projects that use the NatNetSDK libraries for various applications. These samples are the quickest path towards getting NatNet data into your application. '''We strongly recommend taking a close look into these samples and adapt applicable codes into your application.''' More information on these samples are covered in the [[NatNet: Sample Projects|NatNet Samples]] page.
 
</div>
 
 
====Library Header Files: <code>NatNet SDK\include</code>====
 
<div class="padded">
 
The include folder contains headers files for using the NatNet SDK library.
 
 
{| class="wikitable" style ="width:100%;"
 
!style = "padding: 1%;"|File
 
!style = "padding: 1%;"|Description
 
|-
 
|style = "padding: 1%;"|\include\NatNetTypes.h
 
|style = "padding: 1%;"|NatNetTypes.h header file contains the type declaration for all of the data formats that are communicated via the NatNet protocol. 
 
|-
 
|style = "padding: 1%;"|\include\NatNetClient.h
 
|style = "padding: 1%;"|NetNetClient.h header file contains declaration of the [[NatNet: Class/Function Reference|NatNetClient]] class, which is the key object used in the SDK. This object must be initialized in order to run a client application for receiving the data packets.
 
|-
 
|style = "padding: 1%;"|\include\NatNetRequests.h
 
|style = "padding: 1%;"|NatNetRequest.h header file contains a list of [[NatNet: Remote Requests/Commands|NatNet commands]] that can be sent over to a server application using the ''SendMessageAndWait'' function.
 
|-
 
|style = "padding: 1%;"|\include\NatNetCAPI.h
 
|style = "padding: 1%;"|NatNetCAPI.h header file contains declaration for the NatNet API helper functions. These functions are featured for use with native client applications only.
 
|}
 
</div>
 
 
====Library DLL Files: <code>NatNet SDK\lib</code>====
 
<div class="padded">
 
NatNet library files are contained in the lib folder. When running applications that are developed against the NatNet SDK library, corresponding DLL files must be placed alongside the executables.
 
 
{| class="wikitable" style ="width:100%;"
 
!style = "padding: 1%;"|File
 
!style = "padding: 1%;"|Description
 
|-
 
|style = "padding: 1%;"|\lib\
 
|style = "padding: 1%;"|This folder contains NatNet SDK library files for 32-bit architecture.
 
|-
 
|style = "padding: 1%;"|\lib\x64
 
|style = "padding: 1%;"|This folder contains NatNet SDK library files for 64-bit architecture.
 
|-
 
|style = "padding: 1%;"|\lib\NatNetLib.dll
 
\lib\x64\NatNetLib.dll
 
|style = "padding: 1%;"|Native NatNet library for 32-bit and 64-bit platform architecture. These libraries are used for working with NatNet native clients.
 
|-
 
|style = "padding: 1%;"|\lib\NatNetML.dll
 
\lib\x64\NatNetML.dll
 
|style = "padding: 1%;"|Managed NatNet assembly files for 32-bit and 64-bit platform architecture. These libraries are used for working with NatNet managed clients, including applications that use .NET assemblies.
 
 
Note that this assembly is derived from the native library, and to use the NatNetML.dll, NatNetLib.dll must be linked as well.
 
|-
 
|style = "padding: 1%;"|\lib\NatNetML.xml
 
\lib\x64\NatNetML.xml
 
|style = "padding: 1%;"|Includes XML documentations for use with the NatNetML.dll assembly. Place this alongside the DLL file to view the assembly reference.
 
|}
 
</div>
 
</div>
 
 
=API Reference=
 
----
 
 
<div class="padded" style="font-size:125%">
 
===[[NatNet: Class/Function Reference|NatNet: NatNetClient class reference]]===
 
* NatNet class and function references for the ''NatNetClient'' object.
 
 
===[[NatNet: Data Types]]===
 
* List of tracking data types available in the NatNet SDK streaming protocol.
 
 
===[[NatNet: Remote Requests/Commands]]===
 
* NatNet commands for remote triggering the server application</div>
 
 
=User Documentation Pages=
 
----
 
{{Info|'''Tip:''' Code samples are the quickest path to towards getting familiar with the NatNet SDK. Please check out the NatNet samples page.}}
 
<div class="padded" style="font-size:115%;">
 
===[[NatNet: Sample Projects]]===
 
* List of NatNet sample projects and the instructions.
 
 
===[[OptiTrack Timecode|NatNet: Timecode]]===
 
* Timecode representation in OptiTrack systems and NatNet SDK tools.
 
 
===[[NatNet: Creating a Native (C++) Client Application|Creating a NatNet Native C++ Client]]===
 
* A general guideline to using the NatNet SDK for developing a '''native''' client application.
 
 
===[[NatNet: Creating a Managed (C sharp) Client Application|Creating a NatNet Managed C# Client]]===
 
* A general guideline to using the NatNet SDK for developing a '''managed''' client application.</div>
 
 
=Orientation Data in NatNet=
 
----
 
 
In streamed NatNet data packets, orientation data is represented in the '''quaternion format''' (qx, qy, qz, qw). In contrast to Euler angles, Quaternion orientation convention is ''order independent'', however, it indicates the ''handedness''. When converting quaternion orientation into Euler angles, it is important to consider and decide which coordinate convention that you want to convert into. Some of the provided NatNet samples demonstrate quaternion to Euler conversion routines. Please refer to the included [[NatNet: Sample Projects#NatNet Sample Projects|WinFormSample, SampleClient3D, or Matlab samples]] for specific implementation details and usage examples.
 
 
<div class="padded">
 
To convert from provided quaternion orientation representation, the following aspects of desired Euler angle convention must be accounted:
 
 
<div class="padded">
 
* Rotation Order
 
* Handedness: Left handed or Right handed
 
* Axes: Static (Global) or relative (local) axes.
 
</div>
 
 
 
For example, Motive uses the following convention to display the Euler orientation of an object:
 
 
<div class="padded">
 
* '''Rotation Order:''' X (Pitch), Y (Yaw), Z (Roll)
 
* '''Handedness:''' Right-handed (RHS)
 
* '''Axes:''' Relative Axes (aka 'local')
 
</div>
 
</div>
 
 
 
=Direct Depacketization=
 
----
 
 
{{Warning|'''Important Note:''' If applicable, we recommend using the Direct depacketization approach is not recommended.  The bit-stream packet syntax is subject to change, requiring an application to update its parsing routines to be compatible with the new format. NatNet packets should be decoded directly only where the use of the NatNet library is not applicable.}}
 
 
{{Info|The NatNet SDK 3.0 update involves bit-stream syntax changes with the addition of analog data and other functionalities in the protocol. This will require corresponding updates for programs that utilize the direct depacketization approach for parsing the streamed data.}}
 
 
In situations where the use of the NatNet library is not applicable (e.g. developing on unsupported platforms such as Unix), you can also depacketize the streamed data directly from the raw bit-stream without using the NatNet library. In order to provide the most current bitstream syntax, the NatNet SDK includes a testable working depacketization sample (PacketClient) that decodes NatNet Packets directly without using the NatNet client class.
 
 
<div class="padded">
 
===Bit-stream Syntax: PacketClient Sample===
 
----
 
<div class="padded">
 
For the most up-to-date syntax, refer to the PacketClient sample, or use it as a template for depacketizing NatNet data packets.
 
 
# Adapt the PacketClient sample (PacketClient.cpp) to your application's code.
 
# Regularly update your code with each revision to the NatNet bitstream syntax.
 
</div>
 
</div>
 

Revision as of 17:10, 23 July 2017

Back to the Main page

Info2.png

{{{1}}}


Warning2.png

THIS PAGE IS UNDER CONSTRUCTION THIS PAGE IS UNDER CONSTRUCTION THIS PAGE IS UNDER CONSTRUCTION THIS PAGE IS UNDER CONSTRUCTION THIS PAGE IS UNDER CONSTRUCTION THIS PAGE IS UNDER CONSTRUCTION THIS PAGE IS UNDER CONSTRUCTION THIS PAGE IS UNDER CONSTRUCTION

NatNet SDK 3.1 is under development. It will be available soon. Thank you for your patience!