natnet_client

NatNet client implementation.

Licensed under the Apache License, Version 2.0 (the “License”);. you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

OptiTrack NatNet direct depacketization library for Python 3.x

NatNet Client Module

This module implements the communication protocol for interacting with the OptiTrack NatNet system.

It provides functionality to unpack and process motion capture data, such as marker sets, rigid bodies, skeletons, and frame data. The NatNetClient class is the primary interface for connecting to the NatNet server, sending requests, and receiving motion capture data for real-time analysis.

Updated 2025 - Leon Zlajpah

Added Model description classes and Frame classes Parser fills received data into Model and Frame

class robotblockset.optitrack.natnet_client.RigidBodyDescription(name: str | None = None, id: int | None = None, parent_id: int | None = None, offsets: Sequence[ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...]] = [], labels: Sequence[int] | None = None)[source]

Bases: _struct

A class describing a rigid body in a motion capture system.

Attributes:

  • Name (str) – The name of the rigid body.

  • ID (int) – The ID of the rigid body.

  • ParentID (int) – The ID of the parent rigid body.

  • MarkerOffsets (np.ndarray) – An array of offsets for each marker on the rigid body.

  • ActiveLabels (list) – List of active labels for the markers on the rigid body.

Initializes a RigidBodyDescription object with the provided name, ID, parent ID, marker offsets, and active labels.

Parameters:

  • name (str, optional) – The name of the rigid body (default is None).

  • id (int, optional) – The ID of the rigid body (default is None).

  • parent_id (int, optional) – The ID of the parent rigid body (default is None).

  • offsets (Sequence[ArrayLike], optional) – A sequence of marker offsets for the rigid body (default is an empty list).

  • labels (Sequence[int], optional) – A sequence of active labels for the markers on the rigid body (default is None, and is initialized as an empty list if not provided).

__init__(name: str | None = None, id: int | None = None, parent_id: int | None = None, offsets: Sequence[ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...]] = [], labels: Sequence[int] | None = None) → None[source]

Initializes a RigidBodyDescription object with the provided name, ID, parent ID, marker offsets, and active labels.

Parameters:

  • name (str, optional) – The name of the rigid body (default is None).

  • id (int, optional) – The ID of the rigid body (default is None).

  • parent_id (int, optional) – The ID of the parent rigid body (default is None).

  • offsets (Sequence[ArrayLike], optional) – A sequence of marker offsets for the rigid body (default is an empty list).

  • labels (Sequence[int], optional) – A sequence of active labels for the markers on the rigid body (default is None, and is initialized as an empty list if not provided).

property MarkerCount: int

Returns the number of markers on the rigid body.

Returns:

The number of markers on the rigid body, which is equivalent to the length of the MarkerOffsets array.

Return type:

int

class robotblockset.optitrack.natnet_client.MarkerSetDescription(name: str | None = None, markers: Sequence[str] = [])[source]

Bases: _struct

A class describing a set of markers in a motion capture system.

Attributes:

  • Name (str) – The name of the marker set.

  • Markers (list) – A list of marker names in the set.

  • Properties

  • ———-

  • MarkerCount (int) – Returns the number of markers in the marker set.

property MarkerCount: int
class robotblockset.optitrack.natnet_client.SkeletonDescription(name: str | None = None, id: int | None = None, bodies: Sequence[RigidBodyDescription] | None = None)[source]

Bases: _struct

A class that describes a skeleton in a motion capture system.

Attributes:

  • Name (str) – The name of the skeleton.

  • ID (int) – The ID of the skeleton.

  • RigidBodies (list) – A sequence of RigidBodyDescription objects associated with the skeleton.

Initializes the SkeletonDescription with the given name, ID, and a list of rigid bodies.

Parameters:

  • name (str, optional) – The name of the skeleton (default is None).

  • id (int, optional) – The ID of the skeleton (default is None).

  • bodies (Sequence['RigidBodyDescription'], optional) – A sequence of RigidBodyDescription objects associated with the skeleton (default is an empty list).

__init__(name: str | None = None, id: int | None = None, bodies: Sequence[RigidBodyDescription] | None = None) → None[source]

Initializes the SkeletonDescription with the given name, ID, and a list of rigid bodies.

Parameters:

  • name (str, optional) – The name of the skeleton (default is None).

  • id (int, optional) – The ID of the skeleton (default is None).

  • bodies (Sequence['RigidBodyDescription'], optional) – A sequence of RigidBodyDescription objects associated with the skeleton (default is an empty list).

property RigidBodyCount: int

Returns the number of rigid bodies associated with the skeleton.

Returns:

The number of rigid bodies.

Return type:

int

add_rigidbody(rigidbody: RigidBodyDescription) → None[source]

Adds a rigid body to the skeleton.

Parameters:

rigidbody ('RigidBodyDescription') – The rigid body to be added to the skeleton.

class robotblockset.optitrack.natnet_client.MoCapModel(**kwargs: Any)[source]

Bases: _struct

A class representing a motion capture model consisting of rigid bodies, marker sets, and skeletons.

Attributes:

  • RigidBodies (list) – A list of RigidBodyDescription objects.

  • MarkerSets (list) – A list of MarkerSetDescription objects.

  • Skeletons (list) – A list of SkeletonDescription objects.

Initializes a MoCapModel with empty lists for rigid bodies, marker sets, and skeletons.

Parameters:

kwargs (Any) – Additional keyword arguments to initialize model attributes.

__init__(**kwargs: Any) → None[source]

Initializes a MoCapModel with empty lists for rigid bodies, marker sets, and skeletons.

Parameters:

kwargs (Any) – Additional keyword arguments to initialize model attributes.

property RigidBodyCount: int

Returns the number of rigid bodies in the model.

Returns:

The number of rigid bodies.

Return type:

int

property MarkerSetCount: int

Returns the number of marker sets in the model.

Returns:

The number of marker sets.

Return type:

int

property SkeletonCount: int

Returns the number of skeletons in the model.

Returns:

The number of skeletons.

Return type:

int

GetRigidBodyNames() → List[str][source]

Returns a list of names of all rigid bodies in the model.

Returns:

A list of rigid body names.

Return type:

list

GetMarkerSetNames() → List[str][source]

Returns a list of names of all marker sets in the model.

Returns:

A list of marker set names.

Return type:

list

GetMarkerSetMarkerCount() → List[int][source]

Returns a list of the marker counts for each marker set in the model.

Returns:

A list of marker counts for each marker set.

Return type:

list

add_markerset(name: str | None = None, markers: Sequence[str] = []) → None[source]

Adds a new marker set to the model.

Parameters:

  • name (str, optional) – The name of the marker set (default is None).

  • markers (Sequence[str], optional) – A sequence of marker names (default is an empty list).

add_rigidbody(name: str | None = None, id: int | None = None, parent_id: int | None = None, offsets: Sequence[ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...]] = [], labels: Sequence[int] | None = None) → None[source]

Adds a new rigid body to the model.

Parameters:

  • name (str, optional) – The name of the rigid body (default is None).

  • id (int, optional) – The ID of the rigid body (default is None).

  • parent_id (int, optional) – The ID of the parent rigid body (default is None).

  • offsets (Sequence[ArrayLike], optional) – A sequence of offsets for each marker on the rigid body (default is an empty list).

  • labels (Sequence[int], optional) – A sequence of active labels for the markers on the rigid body (default is None).

add_skeleton(name: str | None = None, id: int | None = None, bodies: Sequence[RigidBodyDescription] = []) → None[source]

Adds a new skeleton to the model.

Parameters:

  • name (str, optional) – The name of the skeleton (default is None).

  • id (int, optional) – The ID of the skeleton (default is None).

  • bodies (Sequence[RigidBodyDescription], optional) – A sequence of rigid bodies associated with the skeleton (default is an empty list).

class robotblockset.optitrack.natnet_client.Marker(id: int | None = None, position: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = [0, 0, 0], size: float = 0, occluded: bool = False, point_cloud_solved: bool = True, model_solved: bool = True, residual: float = 0)[source]

Bases: _struct

A class representing a marker in a motion capture system.

Attributes:

  • ID (int) – The unique identifier for the marker.

  • p (np.ndarray) – The position of the marker in 3D space (x, y, z).

  • Size (float) – The size of the marker.

  • Occluded (bool) – Indicates whether the marker is occluded (True/False).

  • PointCloudSolved (bool) – Indicates if the point cloud for the marker has been solved (True/False).

  • ModelSolved (bool) – Indicates if the marker model has been solved (True/False).

  • Residual (float) – The residual error associated with the marker.

Initializes a Marker object with the given parameters.

Parameters:

  • id (int, optional) – The unique identifier for the marker (default is None).

  • position (ArrayLike, optional) – The position of the marker in 3D space (default is [0, 0, 0]).

  • size (float, optional) – The size of the marker (default is 0).

  • occluded (bool, optional) – Indicates whether the marker is occluded (default is False).

  • point_cloud_solved (bool, optional) – Indicates if the point cloud for the marker has been solved (default is True).

  • model_solved (bool, optional) – Indicates if the marker model has been solved (default is True).

  • residual (float, optional) – The residual error associated with the marker (default is 0).

__init__(id: int | None = None, position: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = [0, 0, 0], size: float = 0, occluded: bool = False, point_cloud_solved: bool = True, model_solved: bool = True, residual: float = 0) → None[source]

Initializes a Marker object with the given parameters.

Parameters:

  • id (int, optional) – The unique identifier for the marker (default is None).

  • position (ArrayLike, optional) – The position of the marker in 3D space (default is [0, 0, 0]).

  • size (float, optional) – The size of the marker (default is 0).

  • occluded (bool, optional) – Indicates whether the marker is occluded (default is False).

  • point_cloud_solved (bool, optional) – Indicates if the point cloud for the marker has been solved (default is True).

  • model_solved (bool, optional) – Indicates if the marker model has been solved (default is True).

  • residual (float, optional) – The residual error associated with the marker (default is 0).

class robotblockset.optitrack.natnet_client.MarkerSet(name: str = '')[source]

Bases: _struct

A class representing a set of markers in a motion capture system.

Attributes:

  • Name (str) – The name of the marker set.

  • Markers (list) – A list of Marker objects contained in the marker set.

Initializes a MarkerSet object with the provided name and an empty list of markers.

Parameters:

name (str, optional) – The name of the marker set (default is an empty string).

__init__(name: str = '') → None[source]

Initializes a MarkerSet object with the provided name and an empty list of markers.

Parameters:

name (str, optional) – The name of the marker set (default is an empty string).

property MarkerCount: int

Returns the number of markers in the marker set.

Returns:

The number of markers in the marker set.

Return type:

int

property Markers_p: ndarray

Returns the positions of all markers as a 2D NumPy array.

Returns:

A 2D NumPy array containing the positions of all markers in the marker set.

Return type:

np.ndarray

add_marker(marker: Marker | None = None) → None[source]

Adds a new marker to the marker set.

Parameters:

marker (Marker, optional) – A Marker object to be added to the marker set (default is None).

class robotblockset.optitrack.natnet_client.RigidBody(id: int | None = None, position: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = [0, 0, 0], orientation: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = [0, 0, 0, 1], error: float = 0, tracked: bool = True)[source]

Bases: _struct

A class representing a rigid body in a motion capture system.

Attributes:

  • ID (int) – The unique identifier for the rigid body.

  • p (np.ndarray) – The position of the rigid body in 3D space (x, y, z).

  • Q (np.ndarray) – The orientation of the rigid body represented as a quaternion (w, x, y, z).

  • MeanError (float) – The mean error associated with the rigid body.

  • Tracked (bool) – Indicates whether the rigid body is being tracked (True/False).

Initializes a RigidBody object with the given parameters.

Parameters:

  • id (int, optional) – The unique identifier for the rigid body (default is None).

  • position (ArrayLike, optional) – The position of the rigid body in 3D space (default is [0, 0, 0]).

  • orientation (ArrayLike, optional) – The orientation of the rigid body represented as a quaternion (default is [0, 0, 0, 1]).

  • error (float, optional) – The mean error associated with the rigid body (default is 0).

  • tracked (bool, optional) – Indicates whether the rigid body is tracked (default is True).

__init__(id: int | None = None, position: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = [0, 0, 0], orientation: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = [0, 0, 0, 1], error: float = 0, tracked: bool = True) → None[source]

Initializes a RigidBody object with the given parameters.

Parameters:

  • id (int, optional) – The unique identifier for the rigid body (default is None).

  • position (ArrayLike, optional) – The position of the rigid body in 3D space (default is [0, 0, 0]).

  • orientation (ArrayLike, optional) – The orientation of the rigid body represented as a quaternion (default is [0, 0, 0, 1]).

  • error (float, optional) – The mean error associated with the rigid body (default is 0).

  • tracked (bool, optional) – Indicates whether the rigid body is tracked (default is True).

property x: ndarray

Returns the position and orientation of the rigid body concatenated as a 1D NumPy array.

Returns:

A 1D array containing the position and orientation of the rigid body.

Return type:

np.ndarray

property tracked: bool

Returns the tracking status of the rigid body.

Returns:

True if the rigid body is tracked, otherwise False.

Return type:

bool

class robotblockset.optitrack.natnet_client.Skeleton(id: int = None)[source]

Bases: _struct

A class representing a skeleton in a motion capture system.

Attributes:

  • ID (int) – The unique identifier for the skeleton.

  • RigidBodies (list) – A list of RigidBody objects associated with the skeleton.

Initializes a Skeleton object with the given ID and an empty list of rigid bodies.

Parameters:

id (int, optional) – The unique identifier for the skeleton (default is None).

__init__(id: int = None) → None[source]

Initializes a Skeleton object with the given ID and an empty list of rigid bodies.

Parameters:

id (int, optional) – The unique identifier for the skeleton (default is None).

property RigidBodyCount: int

Returns the number of rigid bodies in the skeleton.

Returns:

The number of rigid bodies in the skeleton.

Return type:

int

add_rigidbody(rigidbody: RigidBody | None = None) → None[source]

Adds a new rigid body to the skeleton.

Parameters:

rigidbody (RigidBody, optional) – A RigidBody object to be added to the skeleton (default is None).

class robotblockset.optitrack.natnet_client.MoCapFrame(id: int | None = None, ts: float | None = None, timecode: int = 0, timecode_sub: int = 0, wall_time: float | None = None)[source]

Bases: _struct

A class representing a single frame of motion capture data.

Attributes:

  • FrameID (int) – The unique identifier for the frame.

  • Timestamp (float) – The timestamp of the frame.

  • Timecode (int) – The timecode of the frame.

  • TimecodeSub (int) – The sub-timecode of the frame.

  • MarkerSets (list) – A list of MarkerSet objects associated with the frame.

  • LabeledMarkers (list) – A list of Marker objects that are labeled in the frame.

  • UnlabeledMarkers (list) – A list of positions for unlabeled markers.

  • RigidBodies (list) – A list of RigidBody objects associated with the frame.

  • Skeletons (list) – A list of Skeleton objects associated with the frame.

  • Time (float) – The wall time associated with the frame.

Initializes a MoCapFrame object with the given parameters.

Parameters:

  • id (int, optional) – The unique identifier for the frame (default is None).

  • ts (float, optional) – The timestamp of the frame (default is None).

  • timecode (int, optional) – The timecode of the frame (default is 0).

  • timecode_sub (int, optional) – The sub-timecode of the frame (default is 0).

  • wall_time (float, optional) – The wall time associated with the frame (default is None).

__init__(id: int | None = None, ts: float | None = None, timecode: int = 0, timecode_sub: int = 0, wall_time: float | None = None) → None[source]

Initializes a MoCapFrame object with the given parameters.

Parameters:

  • id (int, optional) – The unique identifier for the frame (default is None).

  • ts (float, optional) – The timestamp of the frame (default is None).

  • timecode (int, optional) – The timecode of the frame (default is 0).

  • timecode_sub (int, optional) – The sub-timecode of the frame (default is 0).

  • wall_time (float, optional) – The wall time associated with the frame (default is None).

property RigidBodyCount: int

Returns the number of rigid bodies in the frame.

Returns:

The number of rigid bodies in the frame.

Return type:

int

property MarkerSetCount: int

Returns the number of marker sets in the frame.

Returns:

The number of marker sets in the frame.

Return type:

int

property LabeledMarkersCount: int

Returns the number of labeled markers in the frame.

Returns:

The number of labeled markers in the frame.

Return type:

int

property UnlabeledMarkersCount: int

Returns the number of unlabeled markers in the frame.

Returns:

The number of unlabeled markers in the frame.

Return type:

int

property SkeletonCount: int

Returns the number of skeletons in the frame.

Returns:

The number of skeletons in the frame.

Return type:

int

property RigidBodies_x: ndarray

Returns the position and orientation (x) of all rigid bodies in the frame.

Returns:

A 2D NumPy array of shape (n, 7) where each row contains position and orientation data of a rigid body.

Return type:

np.ndarray

property RigidBodies_tracked: List[bool]

Returns the tracking status of each rigid body in the frame.

Returns:

A list of tracking statuses for each rigid body.

Return type:

list

property RigidBodies_p: ndarray

Returns the position of all rigid bodies in the frame.

Returns:

A 2D NumPy array of shape (n, 3) containing the positions of the rigid bodies.

Return type:

np.ndarray

property RigidBodies_Q: ndarray

Returns the orientation (quaternion) of all rigid bodies in the frame.

Returns:

A 2D NumPy array of shape (n, 4) containing the orientations (quaternions) of the rigid bodies.

Return type:

np.ndarray

add_markerset(markerset: MarkerSet | None = None) → None[source]

Adds a marker set to the frame.

Parameters:

markerset (MarkerSet, optional) – A MarkerSet object to be added to the frame (default is None).

add_labeledmarker(id: int | None = None, pos: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = [0, 0, 0], size: float = 0, occluded: bool = False, point_cloud_solved: bool = True, model_solved: bool = True, residual: float = 0) → None[source]

Adds a labeled marker to the frame.

Parameters:

  • id (int, optional) – The ID of the labeled marker (default is None).

  • pos (ArrayLike, optional) – The position of the labeled marker in 3D space (default is [0, 0, 0]).

  • size (float, optional) – The size of the labeled marker (default is 0).

  • occluded (bool, optional) – Whether the marker is occluded (default is False).

  • point_cloud_solved (bool, optional) – Whether the point cloud is solved (default is True).

  • model_solved (bool, optional) – Whether the model is solved (default is True).

  • residual (float, optional) – The residual error associated with the labeled marker (default is 0).

add_rigidbody(id: int | None = None, position: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = [0, 0, 0], orientation: ndarray | List[float] | List[int] | Tuple[float, ...] | Tuple[int, ...] = [0, 0, 0, 1], error: float = 0, tracked: bool = True) → None[source]

Adds a rigid body to the frame.

Parameters:

  • id (int, optional) – The ID of the rigid body (default is None).

  • position (ArrayLike, optional) – The position of the rigid body (default is [0, 0, 0]).

  • orientation (ArrayLike, optional) – The orientation (quaternion) of the rigid body (default is [0, 0, 0, 1]).

  • error (float, optional) – The mean error associated with the rigid body (default is 0).

  • tracked (bool, optional) – Whether the rigid body is being tracked (default is True).

add_skeleton(skeleton: Skeleton | None = None) → None[source]

Adds a skeleton to the frame.

Parameters:

skeleton (Skeleton, optional) – A Skeleton object to be added to the frame (default is None).

robotblockset.optitrack.natnet_client.trace(*args: Any) → None[source]
class robotblockset.optitrack.natnet_client.NatNetClient[source]

Bases: object

NAT_PING = 0
NAT_PINGRESPONSE = 1
NAT_REQUEST = 2
NAT_RESPONSE = 3
NAT_REQUEST_MODELDEF = 4
NAT_MODELDEF = 5
NAT_REQUEST_FRAMEOFDATA = 6
NAT_FRAMEOFDATA = 7
NAT_MESSAGESTRING = 8
NAT_DISCONNECT = 9
NAT_UNRECOGNIZED_REQUEST = 100
sendCommand(command: int, commandStr: str, socket: socket, address: Tuple[str, int]) → None[source]
run() → None[source]
isConnected() → bool[source]

Checks if the client is connected to the NatNet server.

Returns:

True if the client is connected, False otherwise.

Return type:

bool

GetFrame() → None[source]

Checks if a new frame is available and requests a new frame if needed.

If the current frame is None or too old (older than 1 second), the client will resend a NAT request to fetch the latest frame.

Return type:

None

GetFrameData() → MoCapFrame | None[source]

Retrieves the current motion capture frame.

Returns:

The most recent frame received from the NatNet server, or None if no frame is available yet.

Return type:

MoCapFrame or None

GetModel() → None[source]

Requests the motion capture model description from the NatNet server.

Return type:

None

GetModelDescription() → MoCapModel | None[source]

Retrieves the current model description.

Returns:

The model description of the motion capture system, or None if unavailable.

Return type:

MoCapModel or None

Functions

trace(*args)

Classes

Marker([id, position, size, occluded, ...])

A class representing a marker in a motion capture system.

MarkerSet([name])

A class representing a set of markers in a motion capture system.

MarkerSetDescription([name, markers])

A class describing a set of markers in a motion capture system.

MoCapFrame([id, ts, timecode, timecode_sub, ...])

A class representing a single frame of motion capture data.

MoCapModel(**kwargs)

A class representing a motion capture model consisting of rigid bodies, marker sets, and skeletons.

NatNetClient()

RigidBody([id, position, orientation, ...])

A class representing a rigid body in a motion capture system.

RigidBodyDescription([name, id, parent_id, ...])

A class describing a rigid body in a motion capture system.

Skeleton([id])

A class representing a skeleton in a motion capture system.

SkeletonDescription([name, id, bodies])

A class that describes a skeleton in a motion capture system.