Skip to main content

Crate natnet

Crate natnet 

Source
Expand description

OptiTrack NatNet protocol

use natnet::{Decoder, Message, PlannedBody, SyntheticServer, Version};

let server = SyntheticServer::new(Version::V4_1, 1_000_000);
let body = PlannedBody::tracked(7, [1.0, 2.0, 3.0], [0.0, 0.0, 0.0, 1.0]);
let wire = server.datagram(42, 0.5, &[body])?;
let decoded = Decoder::new(Version::V4_1)?.parse(&wire)?;

let Message::FrameOfData(frame) = decoded.message() else {
    panic!("expected a frame");
};
assert_eq!(frame.frame_number, 42);
assert_eq!(frame.rigid_bodies[0].id, 7);
assert_eq!(decoded.to_datagram()?, wire);

§Where to start

  1. With net, call net::CommandClient::connect_handshake to get ServerInfo::protocol_version. The examples/probe.rs example shows the full exchange.
  2. Build a Decoder for that version and parse each datagram; inspect Message for ModelDef or FrameOfData.
  3. Read the command API and the net module docs for requests and socket clients.

See Decoder and ParsePolicy for parsing policies; encoder limits are documented on each method’s # Errors section.

See frame round-trip and float equality for preservation limits, and Version for supported layouts. Poses are plain arrays in the server’s frame.

§Features

  • net: std UDP clients. Peer filtering is not authentication.
  • imagery: the AUGI/1 codec (not part of NatNet); its TCP imagery::net::ImageClient requires both imagery and net.
  • serde: derives on value types.
  • nalgebra: one-way conversions from plain arrays.

Re-exports§

pub use frame::Asset;
pub use frame::Device;
pub use frame::ForcePlate;
pub use frame::FrameOfData;
pub use frame::FrameTiming;
pub use frame::LabeledMarker;
pub use frame::MarkerSet;
pub use frame::RawSection;
pub use frame::RigidBody;
pub use frame::Skeleton;
pub use generate::PlannedBody;
pub use generate::PlannedSections;
pub use generate::SyntheticServer;
pub use modeldef::AssetDef;
pub use modeldef::CameraDef;
pub use modeldef::DataSet;
pub use modeldef::DeviceDef;
pub use modeldef::ForcePlateDef;
pub use modeldef::MarkerDef;
pub use modeldef::MarkerSetDef;
pub use modeldef::ModelDef;
pub use modeldef::RigidBodyDef;
pub use modeldef::SkeletonDef;
pub use serverinfo::ConnectionInfo;
pub use serverinfo::ServerInfo;

Modules§

command
Validated NatNet command requests and guarded property writes.
frame
FrameOfData (message id 7) — one streamed data frame.
generate
Synthetic FrameOfData datagrams for tests and examples.
imageryimagery
AUGI/1 camera-image side channel (imagery feature). Not part of NatNet. Parse records with parse_record.
modeldef
MODELDEF data descriptions (message id 5).
netnet
std UDP clients (net feature).
serverinfo
SERVERINFO (message id 1): server identity, protocol version, clock frequency and data-channel parameters.

Structs§

DecodedMessage
A decoded message paired with the layout used to interpret it.
Decoder
Decodes messages using a supported protocol layout and parsing policy. Construct from ServerInfo’s reported version.
MessageHeader
The parsed 4-byte framing header.
Version
A four-part version quadruple major.minor.build.revision.

Enums§

Error
A NatNet decode/encode failure.
Message
A decoded NatNet message — the ones this crate understands, plus a verbatim fallback for any other message id.
ParsePolicy
Validation of otherwise bounded, structurally decodable input.

Constants§

HEADER_LEN
The fixed 4-byte header size.
NAT_CONNECT
NAT_CONNECT client hello.
NAT_DISCONNECT
NAT_DISCONNECT announcement; no payload or reply.
NAT_DISCONNECTBYTIMEOUT
NAT_DISCONNECTBYTIMEOUT — defined by the NatNet SDK 4.1 NatNetTypes.h; the SDK samples neither send nor handle it.
NAT_DISCOVERY
NAT_DISCOVERY — defined by the NatNet SDK 4.1 NatNetTypes.h; id only.
NAT_ECHOREQUEST
NAT_ECHOREQUEST — defined by the NatNet SDK 4.1 NatNetTypes.h. The SDK documents no payload layout for it; this crate only names the id.
NAT_ECHORESPONSE
NAT_ECHORESPONSE — the reply to NAT_ECHOREQUEST; id only, as above.
NAT_FRAMEOFDATA
NAT_FRAMEOFDATA streamed frame.
NAT_KEEPALIVE
NAT_KEEPALIVE liveness message sent by unicast clients on the command channel; no payload or reply.
NAT_MESSAGESTRING
NAT_MESSAGESTRING asynchronous string message; see parse_message_string.
NAT_MODELDEF
NAT_MODELDEF data-description reply.
NAT_REQUEST
NAT_REQUEST generic request.
NAT_REQUEST_FRAMEOFDATA
NAT_REQUEST_FRAMEOFDATA single-frame request.
NAT_REQUEST_MODELDEF
NAT_REQUEST_MODELDEF data-description request.
NAT_RESPONSE
NAT_RESPONSE generic reply.
NAT_SERVERINFO
SERVERINFO connect reply.
NAT_UNRECOGNIZED_REQUEST
NAT_UNRECOGNIZED_REQUEST — the reply a NatNet server sends to a request it does not recognize (NatNetTypes.h and the SDK samples define it as 100).

Functions§

marker_vectornalgebra
A plain [f32; 3] marker position as an nalgebra vector.
parse_message_string
Parses a NAT_MESSAGESTRING datagram, including its header, into text.

Type Aliases§

Result
Convenience alias for a Result with this crate’s Error.