NatNet: Data Types

Back to the Main page → Back to the NatNet page

---

This page provides an overview of the general data structure used in the NatNet software development kit (SDK) and how the library is used to parse received tracking information.

For specific details on each of the data types, please refer to the NatNetTypes.h header file.

General Structure

---

When receiving streamed data using the NatNet SDK library, its data descriptions should be received before receiving the tracking data. NatNet data is packaged mainly into two different formats: data descriptions and frame-specific tracking data. Utilizing this format, the client application can discover which data are streamed out from the server application in advance to accessing the actual tracking data.

For every asset (e.g. reconstructed markers, rigid bodies, skeletons, force plates) included within streamed capture sessions, their descriptions and tracking data are stored separately. This format allows frame-independent parameters (e.g. name, size, and number) to be stored within instances of the description structs, and frame-dependent values (e.g. position and orientation) to be stored within instances of the frame data structs. When needed, two different packets of an asset can be correlated by referencing to its unique identifier values.

When streaming from Motive, received NatNet data will contain only the assets that are enabled in the Project pane and the asset types that are set to true under Streaming Settings in the Data Streaming pane.

• Dataset Descriptions contains descriptions of the motion capture data sets for which a frame of motion capture data will be generated. (e.g. sSkeletonDescription, sRigidBodyDescription)
• Frame of Mocap Data contains a single frame of motion capture data for all the datasets described from the Dataset Descriptions. (e.g. sSkeletonData, sRigidBodyData)

Dataset Descriptions

---

To receive data descriptions from a connected server, use the NatNetClient::GetDataDescriptions method. Calling this function saves a list of available descriptions in an instance of sDataSetDescriptions.

The sDataSetDescriptions structure stores an array of multiple descriptions for each of assets (MarkerSets, RigidBodies, Skeletons, and Force Plates) involved in a capture and necessary information can be parsed from it. The following table lists out the main data description structs that are available through the SDK. For a complete list of structs and their members, are listed in the NatNetTypes.h header file.

Description Struct

Data Type	Saved struct Type	Description
Native Library	Managed Assembly
Server Description	sServerDescription	ServerDescription	Contains basic network information of the connected server application and the host computer that it is running on. Server descriptions are obtained by calling the GetServerDescription method.
Data Descriptions	sDataDescriptions	List<DataDescriptor>	Contains a list of multiple DataDescriptions each storing description objects for corresponding assets.
MarkerSet Description	sMarkerSetDescription	MarkerSet	MarkerSet description contains a total number of markers in a MarkerSet and each of their labels. Note that rigid body and skeleton assets are included in the MarkerSet as well. Also, for every mocap session, there is a spcial MarkerSet named all, which contains a list of all of the labeld markers from the capture.
Rigid Body Description	sRigidBodyDescription	RigidBody	Rigid body description contains corresponding rigid body names. Skeleton bones are also considered as rigid bodies, and in this case, the description also contains hierarchial relationship for parent/chile rigid bodies.
Skeleton Description	sSkeletonDescription	Skeleton	Skeleton description contains corresponding skeleton asset name, skeleton ID, and total number of rigid bodies (bones) involved in the asset. The skeleton desciption also contains an array of rigid body descriptions which relates to individual bones of the corresponding skeleton.
Force Plate Description	sForcePlateDescription	ForcePlate	Force plate description contains names and IDs of the plate and its channels as well as other hardware parameter settings. Please refer to the NatNetTypes.h header file for specific details.

Frame of Mocap Data

---

As mentioned in the beginning, frame-specific tracking data are stored separately from the DataDescription instances as this cannot be known ahead of time or out of band but only by per frame basis. These data gets saved into instances of sFrameOfMocapData for corresponding frames, and they will contain arrays of frame-specific data structs (e.g.sRigidBodyData, sSkeletonData) for each types of assets included in the capture. Respective frame number, timecode, and streaming latency values are also saved in these packets.

The sFrameOfMocapData can be obtained by setting up a frame handler function using the NatNetClient::SetDataCallback method or by calling the GetLastFrameOfData() method. In most cases, a frame handler function must be assigned in order to make sure every frames are promptly processed. Refer to the provided SampleClient project for an exemplary setup.

FrameOfMocapData

Data Type	Saved struct Type	Description
Native Library	Managed Assembly
MarkerSet Data	sMarkerSetData	MarkerSetData	A named collection of identified markers and the marker positions (X, Y, Z). This list is ordered, padded, point cloud solved, model filled (where occluded). This list also contains special MarkerSet named "all" which is a list of all labeled markers.
Unlabeled Markers (Other markers)	MarkerData	Marker	List of point cloud solved 3D positions (X, Y, Z) for all markers in the frame that are not labeled.
Labeled Markers	sMarker	Marker	Ordered, padded, point cloud solved, model filled (where occluded) labeled Marker data (labeled markers not associated with a "MarkerSet").
RigidBody Data	sRigidBodyData	RigidBodyData	A named segment with a unique ID, position, and orientation data, and the collection of identified markers used to define it. Its marker data indicates model-solved positions.
Skeleton Data	sSkeletonData	SkeletonData	A named, hierarchical collection of RigidBodies. Marker data is model-solved positions.
Force Plate Data	sForcePlateData	ForcePlateData	Force plate channel data (Fx, Fy, Fz, Mx, My, Mz). Force plate data will contain multiple samples per mocap frame, depending upon the force plate acquisition rate.
Frame Number	int	int	Host (server) defined frame number.
Latency	float	float	For every sFrameOfMocapData received through NatNet, a latency value is reported: (For NatNet versions 2.11 and above) the latency value represents the system latency, which is the calculated time between the camera hardware exposure and when Motive is ready to stream the data out; in other words, combining both the hardware and software latency. (For NatNet 2.10) the latency value represents the software processing latency, which is the calculated time between when Motive receives frame data from all of the connected cameras to the time when it is ready to stream the data out. (For NatNet versions below 2.10) the latency was used to report the capture computer’s hardware timestamp for the given frame. This was kept in for compatibility reasons.
Timestamp data	unsigned int	uint	Timing information for the frame. If SMPTE timecode is detected in the system, this time code is also included. See: OptiTrack Timecode Frame ID Frame Timestamp SMPTE Timecode (If timecode is present)

Additional Notes

• One reconstructed 3D marker can be stored in two different places (e.g. in LabeledMarkers and in RigidBody) within a frame of mocap data. In those cases, unique identifier values of the marker can be used to correlate them in the client application if necessary.

• Declarations for these data types are listed in the NatNetTypes.h header files within the SDK. The SampleClient project included in the \NatNet SDK\Sample folder illustrates how to retrieve and interpret the data descriptions and frame data.

Tip: Please refer to the NatNetTypes.h header file or the NatNetML.dll assembly for the most up to date descriptions of the types.

Unique ID

---

Most of the NatNet SDK data packets contain ID values. This value is assigned uniquely to individual markers as well as each of assets within a capture. These values can be used to figure out which asset a given data packet is associated with. One common use is for correlating data descriptions and frame data packets of an asset.

Decoding Member IDs

For each member object that is included within a parental model, its unique ID value points to both its parental model and the member itself. Thus, the ID value of a member object needs to be decoded in order to parse which objects and the parent models they are referencing to.

For example, a skeleton asset is a hierarchical collection of bone rigid bodies, and each of its bone rigid bodies has unique ID that references to the involved skeleton model and the rigid body itself. ID values for skeleton bones must be decoded for use.

Within the NatNetClient class, the NatNetClient::DecodeID method can be used for decoding member ID and model ID of an member object. You can also decode by manually parsing the ID as demonstrated in the WinFormSample or the SampleClientML sample.