natnet.protocol

NatNet protocol parsing.

Copyright (c) 2017, Matthew Edwards. This file is subject to the 3-clause BSD license, as found in the LICENSE file in the top-level directory of this distribution and at https://github.com/mje-nz/python_natnet/blob/master/LICENSE. No part of python_natnet, including this file, may be copied, modified, propagated, or distributed except according to the terms contained in the LICENSE file.

Each message is implemented as a class with a serialize method and/or deserialize classmethod (messages are not required to implement both).

To deserialize a packet, use deserialize() and check the type of the return value (against the message types you’re interested in). Alternatively, use deserialize_header() and check the message ID (against the message IDs you’re interested in), then use deserialize_payload() to get a message instance.

natnet.protocol.serialize(*args, **kwargs)

Serialize a message instance into a binary packet.

Parameters:message – A message instance Returns:bytes – The message serialized as a packet, ready to be sent

natnet.protocol.deserialize(*args, **kwargs)

Deserialize a packet into a message instance.

Parameters:

• data (bytes) – A NatNet packet
• version (Version) – Protocol version to use when deserializing
• strict (bool) – Raise an exception if there is data left in the buffer after parsing.

Returns:

Message instance

natnet.protocol.deserialize_header(*args, **kwargs)

Deserialize a packet into message ID and payload.

Parameters:data (bytes) – A NatNet packet Returns:tuple[MessageId, ParseBuffer] – Message ID and raw payload

natnet.protocol.deserialize_payload(*args, **kwargs)

Deserialize the payload of a packet into a message instance.

Parameters:

• message_id (MessageId)
• payload_data (ParseBuffer) – raw payload
• version (Version) – Protocol version to use when deserializing
• strict (bool) – Raise an exception if there is data left in the buffer after parsing

Returns:

Message instance

class natnet.protocol.MessageId

Message IDs for each NatNet message (as in NatNetTypes.h).

Variables:

• Connect – Request for server info
• ServerInfo – Motive version, NatNet version, clock frequency, data port, and multicast address
• RequestModelDef – Request for model definitions
• ModelDef – List of definitions of rigid bodies, markersets, skeletons etc
• FrameOfData – Frame of motion capture data
• EchoRequest – Request server to immediately respond with its current time (used for clock sync)
• EchoResponse – Current server time (and time contained in EchoRequest message)

class natnet.protocol.Version

NatNet version, with correct comparison operator.

Believe it or not, this is performance-critical.

Variables:

• major (int) –
• minor (int) –
• build (int) –
• revision (int) –

classmethod deserialize(data, version=None)

Deserialize a Version from a ParseBuffer.

serialize()

Serialize a Version to bytes.

class natnet.protocol.ConnectMessage(payload='', version1=Version(major=3, minor=0, build=0, revision=0), version2=Version(major=3, minor=0, build=0, revision=0))

Connect message (request ServerInfo from server).

classmethod deserialize(data, version)

Deserialize a Connect message.

Parameters:

• data (ParseBuffer)
• version (Version)

class natnet.protocol.DiscoveryMessage(payload='', version1=Version(major=3, minor=0, build=0, revision=0), version2=Version(major=3, minor=0, build=0, revision=0))

Discovery message (request ServerInfo from every server).

classmethod deserialize(data, version)

Deserialize a Discovery message.

Parameters:

• data (ParseBuffer)
• version (Version)

class natnet.protocol.MocapFrameMessage(frame_number, markersets, rigid_bodies, skeletons, labelled_markers, force_plates, devices, timing_info, params)

Frame of mocap data.

Variables:

• frame_number (int) –
• markersets (list of Markerset) –
• rigid_bodies (list of RigidBody) –
• skeletons (list of Skeleton) –
• labelled_markers (list of LabelledMarker) – A LabelledMarker instance for each tracked marker, whether part of a rigid body or not
• force_plates (list of Device) –
• devices (list of Device) –
• timing_info (TimingInfo) – Timestamps (in server time)

classmethod deserialize(data, version)

Deserialize a FrameOfData message.

Parameters:

• data (ParseBuffer)
• version (Version)

Returns:

MocapFrameMessage – Deserialized message

is_recording

True if Motive is recording.

tracked_models_changed

True if the tracked models have changed since the last frame.

class natnet.protocol.ModelDefinitionsMessage(models)

Tracked model definitions.

Variables:models – Mixed list of MarkersetDescription, RigidBodyDescription, SkeletonDescription, ForcePlateDescription, and DeviceDescription.