NatNet User's Guide
Contents
1. formal data sets described above FrameOfMocapData also contains additional per frame tracking data This additional data is not described in the DataSetDescriptions structure as it is typically not known ahead of time or out of band but on a frame by frame basis Labeled Markers TrackingTools Labeled Markers not associated with a pre defined MarkerSet or RigidBody This data type is used when MarkerSets and or RigidBodies are not explicitly defined in the Tracking Application but labeled markers are still generated Other Markers Arena TrackingTools All 3D points that were triangulated but not labeled for the given frame NatNet User s Guide NaturalPoint 11 It is possible for data to be duplicated between structures For example a given FrameOfMocapData may contain the same marker in LabeledMarkers as well as within the RigidBody data structure In those cases marker id can be used in the client code to correlate if necessary The SampleClient sample illustrates how to retrieve data descriptions and data and interpret this data Please refer to the NatNetTypes h header file or the NatNetML dll assembly for the most up to date descriptions of the types COORDINATE SYSTEM CONVENTIONS In the NatNet data stream orientation data is represented as a quaternion Quaternion orientations are order independent however they do indicated a handedness When decomposing quaternions into euler angles it is important to consider the coordinat2. Indent sz 5 FUE EDIT NAVIGATE BREAKPOINTS RUN NatNetMatlabSamplem Runand Runand i Advance Time Advance H gt m Optitrack Matlab NatNet Sample Requirements 5 or later Angle degrees function NatNetMatlabSample display NatNet Sample Begin gt NatNetMatlabSample in 27 Col 7 Frame number USING THE NATNET SDK The code samples are the quickest path towards getting NatNet data into your application We typically recommend you 1 Identify your application s development interface requirements managed native etc 2 Adapt the NatNet sample code from the corresponding NatNet sample application in the samples folder into your application 3 Use the API reference for additional information The Visual Studio solution file Samples NatNetSamples sin will open and build all of the NatNet sample projects If you are creating an application from scratch please refer to the following sections for application specific requirements NatNet User s Guide NaturalPoint BUILDING A NATIVE CLIENT TO RECEIVE NATNET DATA Steps for building a NatNet client application library to receive data from a NatNet server application such as Arena or TrackingTools 1 Adapt the SampleClient sample SampleClient cpp to your application s code 2 Include NatNetClient h NatNetHelper h and NatNetTypes h 3 Link to NatNetLib lib dynamic OR NatNetLibStatic lib s
3. NatNet server is configured to use IP Multicast the data is only sent once to the Multicast group m NanralPoi SDK CONTENTS The NatNet SDK consists of NatNet Library Native C networking library headers static library lib and dynamic import library lib dll NatNet Assembly Managed NET assembly NatNetML dll for use in Net compatible clients NatNet Samples Sample projects and executables designed to be quickly integrated into your own code FOLDER CONTENTS Folder Figure 2 NatNet SDK Folder contents Contents include NatNet SDK header files Client applications should include these lib Static and dynamic library files for the NatNet SDK lib x64 64 bit versions of the library files Samples VisualStudio 2005 samples Use the solution file here to open all sample projects Samples bin Precompiled samples with sample data files Samples SampleClient Sample NatNet console app that connects to a NatNet server receives a data stream and writes that data stream to an ascii file Samples SampleClient3D Sample NatNet console app that connects to a NatNet server receives a data stream and displays that data in an OpenGL 3D window Samples SimpleServer Sample NatNet console app that creates and starts a NatNet server creates simple Marker RigidBody and Skeleton data and streams that data onto the network Samples PacketClient Simple ex
4. Natural NatNet API User s Guide Version 2 5 0 September 2013 NaturalPoint Inc P O Box 2317 Corvallis OR 97339 E E E Copyright 2004 2013 NaturalPoint Inc All rights reserved NaturalPoint Publication Number P OT 054 Printed in the US NaturalPoint Proprietary All data and information contained in or disclosed by this document is confidential and proprietary information of NaturalPoint Inc and all rights therein are expressly reserved By accepting this material the recipient agrees that this material and the information contained therein is held in confidence and in trust and will not be used copied reproduced in whole or in part nor its contents revealed in any manner to others without the express written permission of NaturalPoint Inc Information in this document is preliminary and subject to change and does not represent a commitment on the part of NaturalPoint Inc NatNet User s Guide NaturalPoint 2 TABLE OF CONTENTS INGEN GE OVERVIOW D E 4 Else cd 5 Folder Contents RETE TREE TIE TIRE TDI 5 Running the Samples TETE X 6 Running the Simple Client Server Sample ccsccessceescessseeseccecsseeeeccecsseeseccessseeeeaaecsseeeeaaessseeeeaaessseseaaessaeeeaaessaeeseaeessaeeeeaeessaeeeeaaess 6 Running the rigid body sample SampleCli
5. RE BARRIER EUH sGnasusldausansadvaganehust caniacdbaateiienessdecausarsucnay 20 Building a Direct Depacketization Client Without NatNet ccceecesecssecssecseeceeeseeeeeeeeeeeneesecesecsaecsaecsaecaaecaeecaeeeaeeeaeseeesenseerseeeeeaees 20 T chnical SUPPOrt sasoin EET 21 NatNet User s Guide NaturalPoint 3 NATNET OVERVIEW The NatNet SDK is a Client Server networking SDK for sending and receiving NaturalPoint data across networks NatNet uses the UDP protocol in conjunction with either Point To Point Unicast or IP Multicasting for sending data The following diagram outlines the major component communication of a typical NetNet setup Figure 1 NatNet Component Overview NatNet Managed Client e g LabView MatLab NatNet Assembly NatNetML dll a Multicast Address 224 0 0 1 1001 OR Unicast Address app defined ip port NatNet Server App Arena TrackingTools NatNet Native Client NatNet SDK NatNet lib Direct Depacketization Client e g Unix clients A NatNet Server has 2 threads and 2 sockets one for sending data and one for receiving sending commands A NatNet Client has 2 threads and 2 sockets one for receiving data and one for receiving sending commands NatNet servers and clients can exist on the same or separate machines Additionally multiple NatNet clients can connect to a single NatNet server When a
6. ake name Take name none Refer to the SendMessage and SendMessageAndWait functions in the API reference for more details NatNet User s Guide NaturalPoint 13 TIMECODE On supported systems all frames of NatNet data will contain an OptiTrack timecode stamp which is an extended form of the typical studio SMPTE timecode stamp Note SMPTE Timecode support requires an OptiTrack eSync hub Because motion capture frame rates typically exceed standard SMPTE timecode frame rates an additional subframe value is added to the end of the timecode stamp This subframe value is the O based n in between frame Typical OptiTrack Timecode Representation 120 fps mocap data 30 fps no drop SMPTE timecode source MocapFrame 1 2 3 2 5 SMPTE 00 00 00 01 00 00 00 01 00 00 00 01 00 00 00 01 00 00 00 02 SubFrame 0 1 2 3 0 OptiTrack Timecode 00 00 00 01 0 00 00 00 01 1 00 00 00 01 2 00 00 00 01 3 00 00 00 02 0 In the above representation for a typical 120 fps motion capture session synched to a 30 fps no drop SMPTE timecode studio sync source there is a 4 1 ratio of motion capture frames to studio frames The extra motion capture frames are represented by the OptiTrack SubFrame field in the OptiTrack timecode The generic form for OptiTrack timecode is HH MM SS FF Y hours minutes seconds frames subframe OptiTrack timecode is sent to NatNet clients in the form of 2 unsigned integ
7. ample showing how to connect to a NatNet multicast stream and decode NatNet packets directly without using the NatNet SDK Samples WinFormsSample Simple C NET sample showing how to use the NatNet managed assembly NatNETML dll NatNet User s Guide NaturalPoint Samples Matlab Sample MAtlab code file m for using MatLab with the NatNet managed assembly NatNETML dll RUNNING THE SAMPLES Pre compiled versions of the NatNet samples have been provided in the Samples bin folder These versions can be used to quickly test your application Please refer to the instructions in this section for information on running specific samples Note The Visual C runtime libraries are required to run the samples If you encounter an error message when attempting to run the samples especially on machines without Visual C installed please install the VC runtime redistributable package located in Samples VCRedist If the problem persists please try rebuilding the samples using Visual C or contact support RUNNING THE SIMPLE CLIENT SERVER SAMPLE 1 Start the server SimpleServer exe 2 Start the client SampleClient exe IPAddress OutputFilename txt 3 Start streaming by pressing s in the SimpleServer console window You should begin to see data streaming in the client window or to text file Note e parameters are optional e IfnolP address is specified the client will assume the serve
8. e system conventions you want to convert into An euler angle convention must account for e Rotation order e Left handed or Right handed e Static Global or Relative Local Axes As an example the Optitrack Motive software uses the following Motive coordinate system convention X Pitch Y Yaw Z Roll Right Handed RHS Relative Axes aka local The NatNet SDK includes quaternion to euler conversion routines Please refer to the WinForms sample or the SampleClient3D for specific implementation details and usage examples NatNet User s Guide NaturalPoint 12 REMOTE COMMAND AND CONTROL NatNet provides a command request mechanism for passing commands and request between NatNet server s Motive and NatNet Client s your application Examples of commands requests are starting stopping record setting the current take name or querying the server for the current framerate Command Motive Supported Command Request Description Parameters UnitsToMillimeters Request current system s units in none float terms of millimeters FrameRate Request current system s tracking none float framerate StartRecording Start recording none none StopRecording Stop recording none none LiveMode Switch to Live mode none none EditMode Switch to Edit mode none none TimelinePlay Start take playback none none TimelineStop Stop take playback none none TakeName Set the current t
9. ent3D e eecceecceseceeeceseceeecaeeceeeeeeeeeeseeceeeseeecsaeceaecsaecsaecseecaeesaeeeeeseeesenseseseseeseceaeeaesaeeaes 6 RUMMIMB the NET SAMPIlC PR 8 Using the NatNet SDK seneyi ESE 9 Building a Native Client to Receive NatNet Data sssssesesesesseeeeennneneneeen nennen enne nemen nnsn netten nn sn nene enne se tenter nn entere enn entere enne 10 Building a Native Server to Send NatNet Data sssesseseeeeeeeeee nennen nennen enn ettet en nnsn terret nn en nene en ese terrens ente teens entere enne 10 Building a Managed NET Client to Receive NatNet Data 0 eee eeseeescecsnecesececeeeeeeeeceaeeeeeeecaeeeeaeecsaeseeeeecsaeeeeeeeceaeseneeecnaeeeeneesnaeeeaees 10 D idle 11 NatNet Data TY IIIA 11 INStN et Client Class e dea aioin assinei castes cheavciaende oa easel EEEE EDE ESANS Eaa EE E E AE SEO RE EEEN ERSEK ERA EEEE 12 pIscfsgTenpome 12 Constructor amp DestructorDocutmentatiOD aseo iere epa enne EE LER ka Eo RR ERE EXER uM gandina EA Re esasa ia aask aseta XR ERA REX FRENAR asiasia 15 Member Function DOCUMENTATION ETE m 16 Appendix A Bitstream SyntaX ee dt tan ere te eM a Eana aE PESE NEEE REEL BE
10. ers unsigned int Timecode OptiTrack encoded SMPTE timecode unsigned int TimecodeSubframe OptiTrack encoded sub frame data NatNet User s Guide NaturalPoint 14 Timecode values should not be used directly but decoded using the NatNet timecode utility functions bool DecodeTimecode unsigned int inTimecode unsigned int inTimecodeSubframe int hour Helper function to decode lOptiTrack timecode data into int minute int second int frame int individual timecode values subframe bool TimecodeStringify unsigned int inTimecode Helper function to decode OptiTrack timecode into a user unsigned int inTimecodeSubframe char Buffer friendly string in the form hh mm ss ff yy int BufferSize The following is an example of how to decode timecode using the NatNet helper functions from the SampleClient cpp example decode timecode to values int hour minute second frame subframe bool bValid pClient DecodeTimecode data Timecode data gt TimecodeSubframe amp hour amp minute amp second amp frame amp subframe decode timecode to friendly string char szTimecode 128 pClient TimecodeStringify data Timecode data TimecodeSubframe szTimecode 128 printf Timecode s n szTimecode NATNETCLIENT CLASS DESCRIPTION NatNetClient is a complete C class for connecting to NatNet server applications such as NaturalPoint Arena and NaturalPoin
11. escription of the Server s currently streamed objects Select a Row in the DataGrid to display that value in the graph NOM BPWN PRP Figure 3 Receiving NatNet data in a NET Environment EE NatNet Managed Client Sample Local 192 168 2 28 192 168 2 28 Yaw Pitch MarkerSet All 11 16 12 218 NatNet Version 2 1 0 0 11 16 14 625 Initialization Succeeded Skeleton Hip2 1 018 31 11 16 14 625 Connection Succeeded Skeleton Hipt 212 29 977 02 5 99 11 16 14 625 Server App Name NatNetLib 11 16 14 625 Server App Version 1 5 0 0 Skeleton Hip3 928 61 11 16 14 625 Server NatNet Version 1 5 0 0 Li 11 16 14 625 Sending TestRequest heey 1 05 30 11 16 14 625 Server No Response Skeleton Chestl 1 404 93 11 16 15 218 Retrieving Data Descriptions 113515218 Retrieved 25 Data Descriptions Skeleton Chest3 1 257 60 113515218 MarkerSet Skeleton Chest2 1 270 88 1515615218 Name All 111615218 Markers 34 Skeleton Head3 1 555 45 11 16 15 218 Skeleton Hip2 Skeleton Head 1 540 56 11 16 15 218 Skeleton H ip 11 16 15 218 Skeleton Hip3 Skeleton Head1 1 531 76 11 16 15 218 Skeleton Hip4 11 16 15 218 Skeleton Chest1 eee Am LEAT 11 16 15 218 Skeleton Chest3 Skeleton LUArm2 1 182 25 11 16 15 218 Skeleton Chest2 All NatNet User s Guide NaturalPoint 8 RUNNING THE MATLAB SAMPLE 1 Motive Start a NatNet server applicatio
12. et User s Guide NaturalPoint 19 APPENDIX A BITSTREAM SYNTAX In order to provide the most current bitstream syntax the NatNet SDK includes a testable working depacketization sample that decodes NatNet Packets directly without using the NatNet client library Note Decoding packets directly is not recommended The bitstream packet syntax is subject to change requiring an application to rebuild against the latest NatNet library NatNet packets should only be decoded directly where use of the NatNet library is not possible Using the NatNet client library protects client applications from future bistream syntax changes BUILDING A DIRECT DEPACKETIZATION CLIENT WITHOUT NATNET For situtions where you would like to receive a NatNet data stream but it is not possible to use the NatNet client library e g on an unsupported platform such as Unix you can use the PacketClient sample as a template for depacketizing NatNet packets directly 1 Adapt the PacketClient sample PacketClient cpp to your application s code 2 Regularly update your code with each revision to the NatNet bitstream syntax NatNet User s Guide NaturalPoint 20 TECHNICAL SUPPORT NaturalPoint is committed to providing best in class technical support In order to provide you with the most up to date information as quickly as possible we recommend the following procedure 1 Update to the latest software For the latest versions of OptiTrack software drivers and SDK sa
13. mples please visit our downloads section http www naturalpoint com optitrack support downloads html 2 Checkout the OptiTrack FAQs http www naturalpoint com optitrack support opti fag html 3 Check the forums Very often a similar issue has been reported and solved in the forums http forum naturalpoint com 4 Contact technical support Phone 541 753 6645 Fax 541 753 6689 Email Form http www naturalpoint com optitrack support contact Mail NaturalPoint Inc P O Box 2317 Corvallis OR 97339 NatNet User s Guide NaturalPoint 21
14. n e g Motive 2 Motive Enable NatNet streaming from the Server application 3 Matlab Start Matlab 4 Matlab Open the NatNetMatlabSample m file 5 Matlab From the editor window press Run Real Time Streaming Mocap data from Motive into Matlab Motive Body D TestData Office R2 6Cam MAtlab ttp MATLAB R2013a Fie Eat m PLOTS APPS OIC Scorch Documentation Ip S S ner A R EPAZLOOO H New Variable ES nm e E A Perspective Vie Data Str L Open Variable a New New Open i jCompare impot Save ERST cem Workspace j Clear Workspace Saak EE ty lel om SYS A eh m FILE VARIABLE gt FTL gt gt Users morgan NATURALPOINT Documents MATLAB Current Folder amp Command Window Workspace Name NatNet Sample Begin Bi Asembiytestm NatNet Creating Client f funct m NatNet Client Version 2 4 0 0 handles m NatNet Connecting to OptiTrack Server NatNetm NatNet Initialization Succeeded NatNet Tracking Models 5 LIVE Name etails lt Rigid Body JackProp MarkerSet JackProp Skeleton Jackson MarkerSet Jackson Select a file to view details jerem Vul NatNetMatlabSamp Rigid Body JackProp B 9 6 2013 1 49 NatNetMatlabSamp v OptiTrack NatNet Matlab Sample File Edit View Inset Tools Desktop Window Help dHs 5 Ss0o9uuz ajngsm Mocap Angle Plot T PUBLISH da D a CG Find Fies insert E fx Fal m Lij Compare Comment 3 43 7 v Smtr
15. r a response Parameters szCommand Application defined message tries Number of times to try and send the message timeout time to wait for response in milliseconds before timing out Response Application defined response pnBytes Number of bytes in response Returns 0 if succssful error code otherwise int NatNetClient SendMessageAndWait char szCommand void Response int pnBytes Sends an application defined message to the NatNet server and waits for a response Parameters szCommand Application defined message Response Application defined response pnBytes Number of bytes in response Returns O if successful error code otherwise int NatNetClient SetDataCallback void CallbackFunction sFrameOfMocapData FrameOfData void pUserData void pUserData NULL Sets the data callback function for NatNet frame delivery This function will be called whenever NatNet receives an in band data e g frame of data Parameters CallbackFunction Callback Function pUserData User Definable data Returns O if successful error code otherwise NatNet User s Guide NaturalPoint 18 void NatNetClient SetVerbosityLevel int iLeve Sets the message reporting level for internal NatNet messages Parameters iLevel Verbosity level see Verbosity level in NatNetTypes h int NatNetClient Uninitialize Disconnects from the current NatNet Server Returns O if successful error code otherwise NatN
16. r is on the same machine local machine RUNNING THE RIGID BODY SAMPLE SAMPLECLIENT3D With Client Server on same machine 1 Arena Load a dataset with rigid body or skeleton definitions pt2 and skl files 2 Arena Enable network streaming Other Stream Frames 3 Arena Enable streaming rigid body data check Other Rigid Body Data 4 Sample3D File gt Connect With Client Server on separate machines Arena Load a dataset with rigid body or skeleton definitions pt2 and skl files Arena Set IP address to stream from Other IP address edit box Arena Enable network streaming Other Stream Frames Arena Enable streaming rigid body data check Other Rigid Body Data Sample3D Set Client and Server IP addresses Sample3D File gt Connect oOumAB50c H Note NatNet User s Guide NaturalPoint 6 e IP Address IP Address of client NIC card you wish to use e Server IP Address IP Address of server entered in step 2 above NatNet User s Guide NaturalPoint RUNNING THE NET SAMPLE Start a NatNet server application e g Arena or TrackingTools Enable NatNet streaming from the Server application Start the WinForms sample application from the NatNet Samples folder Update the Local and Server IP Addresses as necessary Press the Connect button to connect to the server Press the GetDataDesc button to request and display a detailed d
17. t TrackingTools CONSTRUCTOR amp DESTRUCTOR DOCUMENTATION NatNetClient NatNetClient Creates a new multicast instance of a NatNet Client NatNetClient NatNetClient int iConnectionType Creates a new instance of a NatNet Client using the specified connection protocol Parameters iConnectionType Type of connection 0 Multicast 1 Unicast NatNetClient NatNetClient Destructor NatNetClient Uninitialize Disconnects from server NatNet User s Guide NaturalPoint 15 MEMBER FUNCTION DOCUMENTATION int NatNetClient GetDataDescriptions sDataDescriptions pDataDescriptions Requests a description of the current streamed data objects from the server app This call blocks until request is responded to or times out Parameters pDataDescriptions Array of Data Descriptions Returns On success number of data objects 0 otherwise NatNet User s Guide NaturalPoint 16 sFrameOfMocapData NatNetClient GetLastFrameOfData Retrieves the most recently received frame of mocap data Returns Frame of Mocap Data int NatNetClient GetServerDescription sServerDescription pServerDescription Requests a description of the current NatNet server the client is connected to This call blocks until request is responded to or times out Parameters pServerDescription Description of the NatNet server Returns On success number of data objects 0 otherwise int NatNetClient Initiali
18. tatic 4 OPTIONAL If linking dynamically define NATNETLIB_IMPORTS and distribute NatNetLib dll with your application Note Be sure to link to ws2_32 lib if linking to NatLetLib statically BUILDING A NATIVE SERVER TO SEND NATNET DATA Steps for building a NatNet server application library to send forward NatNet formatted data to a NatNet client application 1 Adapt SimpleServer SampleServer cpp to your application s code 2 Include NatNetServer h NatNetHelper h and NatNetTypes h 3 Link to NatNetLib lib dynamic OR NatNetLibStatic lib static 4 OPTIONAL if linking dynamically define NATNETLIB IMPORTS and distribute NatNetLib dll with your application Note Be sure to link to ws2 32 lib if linking to NatLetLib statically BUILDING A MANAGED NET CLIENT TO RECEIVE NATNET DATA Steps for building a managed NatNet client application 1 Add the NatNetML dll NET assembly as a reference to your VB NET C project 2 The NatNetML namespace is now available to your code in addition to intellisense library comments Note When distributing your NET application be sure to distribute the NatNetML dll as well NatNet User s Guide NaturalPoint 10 API REFERENCE The NatNET API consist of the following objects NatNetClient The class for communicating with a NatNet Server such as Arena or Tracking Tools NatNetServer The class for implementing a NatNet server and sending NatNet formatted data packets NatNet Data Types Str
19. uctures encapsulating data encoded in NatNet packets NatNet Assembly A managed NET class library that can be called by NET components The NatNet assembly wraps the underlying native NatNet library exposing the NatNetClient and NatNet Data Types for use in NET compatible environments e g VB NET C LabView MatLab NATNET DATA TYPES NatNet server applications stream the following types of motion capture data Figure 4 NatNet Data Types Data Type Description MarkerSet Data A named collection of identified markers and the marker positions X Y Z RigidBody Data A named segment with a unique ID position and orientation data and the collection of identified markers used to define it Skeleton Data A named hierarchical collection of RigidBodies NatNet clients can discover what data objects a server application is currently streaming out of band or ahead of time using the DataSetDescriptions structure NatNet clients receive actual data from a server using the FrameOfMocapData structure Both of these packets are delivered to the client via the DataHandler callback Dataset Descriptions This packet contains a description of the motion capture data sets MarkerSets Skeletons RigidBody for which a frame of motion capture data will be generated Frame of Mocap Data This packet contains a single frame of motion capture data for all the data sets described in the Dataset Descriptions In addition to the
20. ze char szLocalAddress char szServerAddress int NatNetClient Initialize char szLocalAddress char szServerAddress int HostCommandPort int NatNetClient Initialize char szLocalAddress char szServerAddress int HostCommandPort int HostDataPort Initializes client socket and attempts to connect to a NatNet server at the specified address Parameters szLocalAddress P address of client szServerAddress IP address of server HostCommandPort server command port default 1510 HostDataPort server data port default 1511 Returns O if successful error code otherwise void NatNetClient SetMulticastAddress char szMulticast Sets the NatNet server multicast group address to connect to SetMulticastAddress must be called before calling Initialize Parameters szCommand application defined Message string void NatNetClient NatNetVersion unsigned char Version 4 Retrieves the version of the NatNet library the client is using Parameters Version version array form major minor build revision NatNet User s Guide NaturalPoint 17 void NatNetClient SendMessage char szCommand Sends a message to the server and returns Response will be delivered in band Parameters szCommand application defined Message string int NatNetClient SendMessageAndWait char szCommand int tries int timeout void Response int pnBytes Sends an application defined message to the NatNet server and waits fo
Download Pdf Manuals
Related Search