hand_tracking_sdk

Parser Module

Parsing helpers for HTS UTF-8 CSV packets.

hand_tracking_sdk.parser.parse_line(line)[source]

Parse one HTS CSV line into a typed packet object.

The input line must use one of the supported labels: Left wrist:, Right wrist:, Left landmarks:, or Right landmarks:, or Head pose:.

Parameters:

line (str) – Raw UTF-8 decoded line from HTS transport.

Returns:

A parsed packet instance for wrist or landmark data.

Return type:

ParsedPacket

Raises:

ParseError – If the line is empty, malformed, has unsupported labels, includes non-float values, or does not match expected value counts.

Transport Module

Socket transport primitives for ingesting HTS text lines.

class hand_tracking_sdk.transport.UDPReceiverConfig(host='0.0.0.0', port=9000, timeout_s=1.0, max_datagram_size=65535, encoding='utf-8')[source]

Bases: object

Configuration for UDP line reception.

Parameters:

  • host (str) – Local bind address.

  • port (int) – Local bind port. Use 0 for OS-assigned ephemeral port.

  • timeout_s (float) – Receive timeout in seconds.

  • max_datagram_size (int) – Maximum datagram size in bytes for recvfrom.

  • encoding (str) – Encoding used to decode bytes into text.

host: str
port: int
timeout_s: float
max_datagram_size: int
encoding: str
class hand_tracking_sdk.transport.TCPServerConfig(host='0.0.0.0', port=8000, accept_timeout_s=1.0, read_timeout_s=1.0, backlog=5, max_line_bytes=262144, encoding='utf-8')[source]

Bases: object

Configuration for TCP server line reception.

Parameters:

  • host (str) – Local bind address for incoming HTS TCP connections.

  • port (int) – Local bind port.

  • accept_timeout_s (float) – Timeout for waiting on a new client connection.

  • read_timeout_s (float) – Timeout while waiting for bytes from connected clients.

  • backlog (int) – Listen backlog used in socket.listen.

  • max_line_bytes (int) – Upper bound for a buffered text line.

  • encoding (str) – Encoding used to decode bytes into text.

host: str
port: int
accept_timeout_s: float
read_timeout_s: float
backlog: int
max_line_bytes: int
encoding: str
class hand_tracking_sdk.transport.TCPClientConfig(host='127.0.0.1', port=8000, connect_timeout_s=5.0, read_timeout_s=1.0, reconnect_delay_s=0.25, max_line_bytes=262144, encoding='utf-8')[source]

Bases: object

Configuration for TCP client line reception.

Parameters:

  • host (str) – Remote server address.

  • port (int) – Remote server port.

  • connect_timeout_s (float) – Timeout when establishing TCP connection.

  • read_timeout_s (float) – Timeout while waiting for bytes from the server.

  • reconnect_delay_s (float) – Delay between reconnect attempts in TCPClientLineReceiver.iter_lines().

  • max_line_bytes (int) – Upper bound for a buffered text line.

  • encoding (str) – Encoding used to decode bytes into text.

host: str
port: int
connect_timeout_s: float
read_timeout_s: float
reconnect_delay_s: float
max_line_bytes: int
encoding: str
class hand_tracking_sdk.transport.UDPLineReceiver(config=None)[source]

Bases: object

Receive UTF-8 HTS lines over UDP datagrams.

Parameters:

config (UDPReceiverConfig | None)

property local_address: tuple[str, int]

Return currently bound local (host, port).

Raises:

TransportClosedError – If the receiver is not open.

open()[source]

Open and bind the UDP socket.

Raises:

RuntimeError – If called while already open.

Return type:

None

close()[source]

Close the UDP socket if open.

Return type:

None

recv_line()[source]

Receive the next decoded non-empty line from UDP datagrams.

Returns:

Decoded line with surrounding whitespace removed.

Raises:
Return type:

str

iter_lines()[source]

Yield lines until receiver is closed.

Timeout events are ignored so callers can stop by calling close().

Returns:

Iterator of decoded text lines.

Return type:

Iterator[str]

class hand_tracking_sdk.transport.TCPServerLineReceiver(config=None)[source]

Bases: object

Receive UTF-8 HTS lines from one or more inbound TCP client connections.

Parameters:

config (TCPServerConfig | None)

property local_address: tuple[str, int]

Return currently bound local (host, port).

Raises:

TransportClosedError – If the server socket is not open.

open()[source]

Open and bind listening TCP socket.

Raises:

RuntimeError – If called while already open.

Return type:

None

close()[source]

Close connected client and server sockets.

Return type:

None

recv_line()[source]

Receive one newline-terminated line from any connected client.

If no client is connected, this method waits for at least one inbound connection before reading lines.

Returns:

Decoded line with trailing newline removed.

Raises:
Return type:

str

iter_lines()[source]

Yield lines continuously, recovering from disconnects.

Timeout and disconnect events are treated as transient.

Returns:

Iterator of decoded text lines.

Return type:

Iterator[str]

class hand_tracking_sdk.transport.TCPClientLineReceiver(config)[source]

Bases: object

Receive UTF-8 HTS lines from an outbound TCP client connection.

Parameters:

config (TCPClientConfig)

open()[source]

Open TCP connection to configured host and port.

Raises:

  • RuntimeError – If called while already open.

  • OSError – If the remote endpoint cannot be reached.

Return type:

None

close()[source]

Close TCP client socket if open.

Return type:

None

recv_line()[source]

Receive one newline-terminated line from TCP stream.

Returns:

Decoded line with trailing newline removed.

Raises:
Return type:

str

iter_lines()[source]

Yield lines continuously and reconnect on disconnect.

Returns:

Iterator of decoded text lines.

Return type:

Iterator[str]

Frame Module

Frame assembly utilities for combining wrist and landmark packets.

class hand_tracking_sdk.frame.HandFrame(side, frame_id, wrist, landmarks, sequence_id, recv_ts_ns, recv_time_unix_ns, source_ts_ns, wrist_recv_ts_ns, landmarks_recv_ts_ns, source_frame_seq=None)[source]

Bases: object

Coherent per-hand frame assembled from wrist and landmark packets.

Parameters:

  • side (HandSide) – Hand side for this frame.

  • frame_id (str) – Frame identifier for downstream middleware mapping (for example ROS2).

  • wrist (WristPose) – Wrist pose payload.

  • landmarks (HandLandmarks) – Ordered set of 21 hand landmarks.

  • sequence_id (int) – Monotonic sequence number per hand side, incremented on each emitted frame.

  • recv_ts_ns (int) – Monotonic receive timestamp for the assembled frame.

  • recv_time_unix_ns (int | None) – Optional wall-clock timestamp in Unix nanoseconds.

  • source_ts_ns (int | None) – Optional source timestamp supplied by upstream sender.

  • source_frame_seq (int | None) – Optional upstream source frame sequence identifier.

  • wrist_recv_ts_ns (int) – Receive timestamp of the wrist payload included in this frame.

  • landmarks_recv_ts_ns (int) – Receive timestamp of the landmark payload included in this frame.

side: HandSide
frame_id: str
wrist: WristPose
landmarks: HandLandmarks
sequence_id: int
recv_ts_ns: int
recv_time_unix_ns: int | None
source_ts_ns: int | None
wrist_recv_ts_ns: int
landmarks_recv_ts_ns: int
source_frame_seq: int | None
get_joint(joint)[source]

Return one landmark point by joint name.

Parameters:

joint (JointName | str) – Joint to query, either as JointName or canonical joint string.

Returns:

Joint (x, y, z) tuple.

Raises:

ValueError – If the joint name is unknown.

Return type:

tuple[float, float, float]

get_finger(finger)[source]

Return all landmark points for one finger group.

Parameters:

finger (FingerName | str) – Finger group to query.

Returns:

Dictionary mapping JointName to (x, y, z) points for the selected finger group.

Raises:

ValueError – If the finger group is unknown.

Return type:

dict[JointName, tuple[float, float, float]]

to_dict()[source]

Serialize frame into a deterministic mapping-friendly dictionary.

Returns:

Dictionary representation suitable for adapter-layer mapping.

Return type:

dict[str, Any]

classmethod from_dict(values)[source]

Build HandFrame from serialized mapping data.

Parameters:

values (Mapping[str, Any]) – Mapping containing side, frame metadata, and geometry payloads.

Returns:

Parsed frame object.

Return type:

HandFrame

class hand_tracking_sdk.frame.HeadFrame(side, frame_id, head, sequence_id, recv_ts_ns, recv_time_unix_ns, source_ts_ns, source_frame_seq=None)[source]

Bases: object

Frame-like head pose event with normalized metadata fields.

Parameters:

  • side (HandSide) – Always HandSide.HEAD.

  • frame_id (str) – Frame identifier for downstream middleware mapping.

  • head (HeadPose) – Head pose payload.

  • sequence_id (int) – Monotonic sequence number for head frames.

  • recv_ts_ns (int) – Monotonic receive timestamp for the emitted frame.

  • recv_time_unix_ns (int | None) – Optional wall-clock timestamp in Unix nanoseconds.

  • source_ts_ns (int | None) – Optional source timestamp supplied by upstream sender.

  • source_frame_seq (int | None) – Optional upstream source frame sequence identifier.

side: HandSide
frame_id: str
head: HeadPose
sequence_id: int
recv_ts_ns: int
recv_time_unix_ns: int | None
source_ts_ns: int | None
source_frame_seq: int | None
to_dict()[source]

Serialize frame into a deterministic mapping-friendly dictionary.

Return type:

dict[str, Any]

classmethod from_dict(values)[source]

Build HeadFrame from serialized mapping data.

Parameters:

values (Mapping[str, Any])

Return type:

HeadFrame

hand_tracking_sdk.frame.AssembledFrame = hand_tracking_sdk.frame.HandFrame | hand_tracking_sdk.frame.HeadFrame

Frame event emitted by HandFrameAssembler.

class hand_tracking_sdk.frame.HandFrameAssembler(*, include_wall_time=True, include_head_frames=False, frame_id_by_side=None)[source]

Bases: object

Assemble coherent frames from incoming parsed HTS packets.

Emission policy: - A frame is emitted only after both wrist and landmarks are available for a hand side. - A new frame is emitted when at least one component timestamp advances. - Stale component updates (older timestamps than currently stored) are ignored.

Parameters:

  • include_wall_time (bool)

  • include_head_frames (bool)

  • frame_id_by_side (Mapping[HandSide, str] | None)

reset(side=None)[source]

Reset assembler state.

Parameters:

side (HandSide | None) – Optional side to reset. If omitted, both sides are reset.

Return type:

None

push_packet(packet, *, recv_ts_ns=None, recv_time_unix_ns=None, source_ts_ns=None)[source]

Push one parsed packet and optionally emit a coherent frame.

Parameters:

  • packet (WristPacket | LandmarksPacket | HeadPosePacket) – Parsed wrist or landmarks packet.

  • recv_ts_ns (int | None) – Monotonic receive timestamp in nanoseconds. If omitted, generated with time.monotonic_ns().

  • recv_time_unix_ns (int | None) – Optional Unix wall-clock timestamp in nanoseconds. If omitted and include_wall_time=True, generated with time.time_ns().

  • source_ts_ns (int | None) – Optional source timestamp supplied by upstream sender.

Returns:

A newly assembled frame or None if frame is incomplete/unchanged.

Return type:

HandFrame | HeadFrame | None

push_line(line, *, recv_ts_ns=None, recv_time_unix_ns=None, source_ts_ns=None)[source]

Parse and push one raw HTS line into assembler state.

Parameters:

  • line (str) – Raw UTF-8 decoded HTS CSV line.

  • recv_ts_ns (int | None) – Monotonic receive timestamp in nanoseconds.

  • recv_time_unix_ns (int | None) – Optional Unix wall-clock timestamp in nanoseconds.

  • source_ts_ns (int | None) – Optional source timestamp supplied by upstream sender.

Returns:

A newly assembled frame or None if frame is incomplete/unchanged.

Return type:

HandFrame | HeadFrame | None

Conversion Module

Coordinate conversion utilities for HTS telemetry.

hand_tracking_sdk.convert.unity_left_to_right_position(x, y, z)[source]

Convert a Unity left-handed position into a right-handed position.

HTS documentation indicates flipping the Y axis for typical right-handed consumer stacks.

Parameters:

  • x (float) – Position X in Unity left-handed coordinates.

  • y (float) – Position Y in Unity left-handed coordinates.

  • z (float) – Position Z in Unity left-handed coordinates.

Returns:

Converted (x, y, z) in right-handed coordinates.

Return type:

tuple[float, float, float]

hand_tracking_sdk.convert.unity_right_to_flu_position(x, y, z)[source]

Convert Unity right-handed coordinates into FLU basis.

Unity right-handed coordinates use x=right, y=up, z=forward while common robotics FLU basis uses x=forward, y=left, z=up. This function applies the required axis remapping and sign flips. See GitHub issue #2 for more details.

Parameters:

  • x (float) – Position X in Unity right-handed coordinates.

  • y (float) – Position Y in Unity right-handed coordinates.

  • z (float) – Position Z in Unity right-handed coordinates.

Returns:

Position converted into FLU basis.

Return type:

tuple[float, float, float]

hand_tracking_sdk.convert.unity_left_to_flu_position(x, y, z)[source]

Convert Unity left-handed coordinates directly into FLU basis.

This composes unity_left_to_right_position() followed by unity_right_to_flu_position(), so Unity left-handed input is first converted to Unity right-handed coordinates, then to FLU.

Parameters:

  • x (float) – Position X in Unity left-handed coordinates.

  • y (float) – Position Y in Unity left-handed coordinates.

  • z (float) – Position Z in Unity left-handed coordinates.

Returns:

Position converted into FLU basis.

Return type:

tuple[float, float, float]

hand_tracking_sdk.convert.unity_left_to_right_quaternion(qx, qy, qz, qw)[source]

Convert quaternion orientation from Unity left-handed to right-handed.

The conversion applies basis transform R' = S * R * S with S = diag(1, -1, 1).

Parameters:

  • qx (float) – Quaternion X in Unity left-handed basis.

  • qy (float) – Quaternion Y in Unity left-handed basis.

  • qz (float) – Quaternion Z in Unity left-handed basis.

  • qw (float) – Quaternion W in Unity left-handed basis.

Returns:

Converted quaternion (qx, qy, qz, qw) in right-handed basis.

Return type:

tuple[float, float, float, float]

hand_tracking_sdk.convert.convert_wrist_pose_unity_left_to_right(pose)[source]

Convert one wrist pose from Unity left-handed to right-handed.

Parameters:

pose (WristPose) – Wrist pose to convert.

Returns:

Converted wrist pose.

Return type:

WristPose

hand_tracking_sdk.convert.convert_landmarks_unity_left_to_right(landmarks)[source]

Convert hand landmarks from Unity left-handed to right-handed.

Parameters:

landmarks (HandLandmarks) – Landmark set to convert.

Returns:

Converted landmark set preserving original point order.

Return type:

HandLandmarks

hand_tracking_sdk.convert.convert_hand_frame_unity_left_to_right(frame)[source]

Convert a full assembled hand frame from Unity left-handed to right-handed.

Metadata fields are preserved and only geometry fields are transformed.

Parameters:

frame (HandFrame) – Input frame in Unity left-handed coordinates.

Returns:

Converted frame in right-handed coordinates.

Return type:

HandFrame

hand_tracking_sdk.convert.basis_transform_position(pos, basis)[source]

Apply a basis matrix to a position vector.

Computes result = basis @ pos.

Parameters:

  • pos (tuple[float, float, float]) – Input position (x, y, z).

  • basis (tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]) – 3×3 basis change matrix.

Returns:

Transformed position.

Return type:

tuple[float, float, float]

hand_tracking_sdk.convert.basis_transform_rotation(qx, qy, qz, qw, basis)[source]

Transform a quaternion orientation via a basis change matrix.

Computes R_new = basis @ R @ basis^T and returns the result as a normalized quaternion (qx, qy, qz, qw).

Parameters:

  • qx (float) – Quaternion X component.

  • qy (float) – Quaternion Y component.

  • qz (float) – Quaternion Z component.

  • qw (float) – Quaternion W component.

  • basis (tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]) – 3×3 basis change matrix.

Returns:

Transformed quaternion (qx, qy, qz, qw).

Return type:

tuple[float, float, float, float]

hand_tracking_sdk.convert.basis_transform_rotation_matrix(qx, qy, qz, qw, basis)[source]

Transform a quaternion orientation via a basis change matrix.

Same operation as basis_transform_rotation() but returns the result as a 3×3 rotation matrix instead of a quaternion.

Parameters:

  • qx (float) – Quaternion X component.

  • qy (float) – Quaternion Y component.

  • qz (float) – Quaternion Z component.

  • qw (float) – Quaternion W component.

  • basis (tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]) – 3×3 basis change matrix.

Returns:

Transformed 3×3 rotation matrix.

Return type:

tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]

hand_tracking_sdk.convert.unity_left_to_rfu_position(x, y, z)[source]

Convert Unity left-handed coordinates into RFU basis.

Parameters:

  • x (float)

  • y (float)

  • z (float)

Return type:

tuple[float, float, float]

hand_tracking_sdk.convert.unity_left_to_rfu_rotation(qx, qy, qz, qw)[source]

Convert Unity left-handed quaternion into RFU basis.

Parameters:

  • qx (float)

  • qy (float)

  • qz (float)

  • qw (float)

Return type:

tuple[float, float, float, float]

hand_tracking_sdk.convert.unity_left_to_rfu_rotation_matrix(qx, qy, qz, qw)[source]

Convert Unity left-handed quaternion into RFU rotation matrix.

Parameters:

  • qx (float)

  • qy (float)

  • qz (float)

  • qw (float)

Return type:

tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]

hand_tracking_sdk.convert.unity_left_to_flu_rotation(qx, qy, qz, qw)[source]

Convert Unity left-handed quaternion into FLU basis.

Parameters:

  • qx (float)

  • qy (float)

  • qz (float)

  • qw (float)

Return type:

tuple[float, float, float, float]

hand_tracking_sdk.convert.unity_left_to_flu_rotation_matrix(qx, qy, qz, qw)[source]

Convert Unity left-handed quaternion into FLU rotation matrix.

Parameters:

  • qx (float)

  • qy (float)

  • qz (float)

  • qw (float)

Return type:

tuple[tuple[float, float, float], tuple[float, float, float], tuple[float, float, float]]

Client Module

High-level streaming client API for HTS telemetry.

class hand_tracking_sdk.client.TransportMode(*values)[source]

Bases: StrEnum

Transport mode used by HTSClient.

UDP = 'udp'
TCP_SERVER = 'tcp_server'
TCP_CLIENT = 'tcp_client'
class hand_tracking_sdk.client.StreamOutput(*values)[source]

Bases: StrEnum

Output type emitted by HTSClient.iter_events().

PACKETS = 'packets'
FRAMES = 'frames'
BOTH = 'both'
class hand_tracking_sdk.client.HandFilter(*values)[source]

Bases: StrEnum

Hand-side filter applied before packet/frame emission.

BOTH = 'both'
LEFT = 'left'
RIGHT = 'right'
class hand_tracking_sdk.client.ErrorPolicy(*values)[source]

Bases: StrEnum

Error policy applied to parse failures.

STRICT = 'strict'
TOLERANT = 'tolerant'
class hand_tracking_sdk.client.LogEventKind(*values)[source]

Bases: StrEnum

Structured log event kinds emitted by HTSClient.

RECEIVED_LINE = 'received_line'
PARSE_ERROR = 'parse_error'
FILTERED_PACKET = 'filtered_packet'
EMITTED_PACKET = 'emitted_packet'
EMITTED_FRAME = 'emitted_frame'
CALLBACK_ERROR = 'callback_error'
class hand_tracking_sdk.client.StreamLogEvent(kind, message, side=None, line=None, exception=None)[source]

Bases: object

Structured client log event for observability hooks.

Parameters:

  • kind (LogEventKind) – Event kind discriminator.

  • message (str) – Human-readable event message.

  • side (HandSide | None) – Optional hand side associated with the event.

  • line (str | None) – Optional raw input line associated with the event.

  • exception (Exception | None) – Optional exception associated with the event.

kind: LogEventKind
message: str
side: HandSide | None
line: str | None
exception: Exception | None
class hand_tracking_sdk.client.ClientStats(lines_received=0, parse_errors=0, dropped_lines=0, packets_filtered=0, packets_emitted=0, frames_emitted=0, callbacks_invoked=0, callback_errors=0)[source]

Bases: object

Observable counters for HTSClient runtime behavior.

Parameters:

  • lines_received (int)

  • parse_errors (int)

  • dropped_lines (int)

  • packets_filtered (int)

  • packets_emitted (int)

  • frames_emitted (int)

  • callbacks_invoked (int)

  • callback_errors (int)

lines_received: int
parse_errors: int
dropped_lines: int
packets_filtered: int
packets_emitted: int
frames_emitted: int
callbacks_invoked: int
callback_errors: int
class hand_tracking_sdk.client.HTSClientConfig(transport_mode=TransportMode.UDP, host='0.0.0.0', port=9000, timeout_s=1.0, reconnect_delay_s=0.25, output=StreamOutput.FRAMES, hand_filter=HandFilter.BOTH, error_policy=ErrorPolicy.STRICT, include_wall_time=True, log_hook=None)[source]

Bases: object

Configuration for high-level HTS streaming client.

Parameters:

  • transport_mode (TransportMode) – Network transport mode.

  • host (str) – Host address used for bind/connect according to transport mode.

  • port (int) – Port used for bind/connect according to transport mode.

  • timeout_s (float) – I/O timeout in seconds for receive operations. In tcp_server mode, initial connection wait uses max(timeout_s, 5.0) to avoid premature startup timeouts while waiting for a device to connect.

  • reconnect_delay_s (float) – Delay used by TCP client reconnect loop.

  • output (StreamOutput) – Event output mode (packets, frames, or both).

  • hand_filter (HandFilter) – Hand-side filter for emitted events.

  • error_policy (ErrorPolicy) – Parse error handling strategy.

  • include_wall_time (bool) – Whether assembled frames include recv_time_unix_ns by default.

  • log_hook (Callable[[StreamLogEvent], None] | None) – Optional structured log callback invoked for client lifecycle events.

transport_mode: TransportMode
host: str
port: int
timeout_s: float
reconnect_delay_s: float
output: StreamOutput
hand_filter: HandFilter
error_policy: ErrorPolicy
include_wall_time: bool
log_hook: Callable[[StreamLogEvent], None] | None
hand_tracking_sdk.client.StreamEvent = hand_tracking_sdk.models.WristPacket | hand_tracking_sdk.models.LandmarksPacket | hand_tracking_sdk.models.HeadPosePacket | hand_tracking_sdk.frame.HandFrame | hand_tracking_sdk.frame.HeadFrame

Public event type emitted by HTSClient streaming methods.

class hand_tracking_sdk.client.HTSClient(config, *, receiver_factory=None)[source]

Bases: object

High-level client for streaming parsed packets and assembled frames.

Parameters:
iter_events()[source]

Iterate streaming events from configured transport.

Returns:

Iterator yielding packet and/or frame events per configured output mode.

Raises:

ParseError – When error_policy=strict and an incoming line cannot be parsed.

Return type:

Iterator[WristPacket | LandmarksPacket | HeadPosePacket | HandFrame | HeadFrame]

run(callback, *, max_events=None, wrap_callback_exceptions=False)[source]

Run stream loop and invoke callback for each emitted event.

Parameters:

  • callback (Callable[[WristPacket | LandmarksPacket | HeadPosePacket | HandFrame | HeadFrame], None]) – Function called for each emitted stream event.

  • max_events (int | None) – Optional cap on processed events; useful for controlled execution.

  • wrap_callback_exceptions (bool) – If True, callback exceptions are re-raised as ClientCallbackError.

Returns:

Number of callback invocations performed.

Raises:
Return type:

int

get_stats()[source]

Return a snapshot of current client counters.

Return type:

ClientStats

reset_stats()[source]

Reset client counters to zero values.

Return type:

None

Models Module

Typed packet models for HTS telemetry.

class hand_tracking_sdk.models.HandSide(*values)[source]

Bases: StrEnum

Logical side for a tracked hand.

LEFT = 'Left'
RIGHT = 'Right'
HEAD = 'Head'
class hand_tracking_sdk.models.PacketType(*values)[source]

Bases: StrEnum

Packet data category emitted by HTS.

WRIST = 'wrist'
LANDMARKS = 'landmarks'
POSE = 'pose'
class hand_tracking_sdk.models.JointName(*values)[source]

Bases: StrEnum

Canonical joint names matching HTS landmark order.

WRIST = 'Wrist'
THUMB_METACARPAL = 'ThumbMetacarpal'
THUMB_PROXIMAL = 'ThumbProximal'
THUMB_DISTAL = 'ThumbDistal'
THUMB_TIP = 'ThumbTip'
INDEX_PROXIMAL = 'IndexProximal'
INDEX_INTERMEDIATE = 'IndexIntermediate'
INDEX_DISTAL = 'IndexDistal'
INDEX_TIP = 'IndexTip'
MIDDLE_PROXIMAL = 'MiddleProximal'
MIDDLE_INTERMEDIATE = 'MiddleIntermediate'
MIDDLE_DISTAL = 'MiddleDistal'
MIDDLE_TIP = 'MiddleTip'
RING_PROXIMAL = 'RingProximal'
RING_INTERMEDIATE = 'RingIntermediate'
RING_DISTAL = 'RingDistal'
RING_TIP = 'RingTip'
LITTLE_PROXIMAL = 'LittleProximal'
LITTLE_INTERMEDIATE = 'LittleIntermediate'
LITTLE_DISTAL = 'LittleDistal'
LITTLE_TIP = 'LittleTip'
class hand_tracking_sdk.models.FingerName(*values)[source]

Bases: StrEnum

Supported finger groups for convenience accessors.

WRIST = 'wrist'
THUMB = 'thumb'
INDEX = 'index'
MIDDLE = 'middle'
RING = 'ring'
LITTLE = 'little'
class hand_tracking_sdk.models.PacketDebugInfo(source_frame_seq=None, source_ts_ns=None)[source]

Bases: object

Optional source-side metadata attached to one streamed packet.

Parameters:

  • source_frame_seq (int | None)

  • source_ts_ns (int | None)

source_frame_seq: int | None
source_ts_ns: int | None
class hand_tracking_sdk.models.WristPose(x, y, z, qx, qy, qz, qw)[source]

Bases: object

Cartesian wrist position and orientation quaternion.

Parameters:

  • x (float)

  • y (float)

  • z (float)

  • qx (float)

  • qy (float)

  • qz (float)

  • qw (float)

x: float
y: float
z: float
qx: float
qy: float
qz: float
qw: float
to_dict()[source]

Serialize wrist pose into a mapping-friendly dictionary.

Returns:

Deterministic dictionary with position and quaternion fields.

Return type:

dict[str, float]

classmethod from_dict(values)[source]

Build WristPose from serialized mapping data.

Parameters:

values (Mapping[str, Any]) – Mapping containing x, y, z, qx, qy, qz, qw.

Returns:

Parsed wrist pose instance.

Return type:

WristPose

class hand_tracking_sdk.models.HeadPose(x, y, z, qx, qy, qz, qw)[source]

Bases: object

Cartesian head position and orientation quaternion.

Parameters:

  • x (float)

  • y (float)

  • z (float)

  • qx (float)

  • qy (float)

  • qz (float)

  • qw (float)

x: float
y: float
z: float
qx: float
qy: float
qz: float
qw: float
to_dict()[source]

Serialize head pose into a mapping-friendly dictionary.

Return type:

dict[str, float]

classmethod from_dict(values)[source]

Build HeadPose from serialized mapping data.

Parameters:

values (Mapping[str, Any])

Return type:

HeadPose

class hand_tracking_sdk.models.HandLandmarks(points)[source]

Bases: object

Ordered set of 21 hand landmarks as (x, y, z) points.

Parameters:

points (tuple[tuple[float, float, float], ...])

points: tuple[tuple[float, float, float], ...]
get_joint(joint)[source]

Return one joint point by name.

Parameters:

joint (JointName | str) – Joint to query, either as JointName or canonical joint string (for example "IndexTip").

Returns:

Joint (x, y, z) tuple.

Raises:

ValueError – If the joint name is unknown.

Return type:

tuple[float, float, float]

get_finger(finger)[source]

Return all joint points for one finger group.

Parameters:

finger (FingerName | str) – Finger group to query. Accepts FingerName or one of wrist, thumb, index, middle, ring, little.

Returns:

Dictionary mapping JointName to (x, y, z) points for the selected finger group.

Raises:

ValueError – If the finger group is unknown.

Return type:

dict[JointName, tuple[float, float, float]]

to_dict()[source]

Serialize landmarks into a mapping-friendly dictionary.

Returns:

Dictionary with ordered points list.

Return type:

dict[str, list[list[float]]]

classmethod from_dict(values)[source]

Build HandLandmarks from serialized mapping data.

Parameters:

values (Mapping[str, Any]) – Mapping containing points as nested coordinate lists.

Returns:

Parsed landmarks instance preserving point order.

Return type:

HandLandmarks

class hand_tracking_sdk.models.WristPacket(side, kind, data, debug=None)[source]

Bases: object

Parsed wrist packet for one hand side.

Parameters:
side: HandSide
kind: PacketType
data: WristPose
debug: PacketDebugInfo | None
class hand_tracking_sdk.models.LandmarksPacket(side, kind, data, debug=None)[source]

Bases: object

Parsed landmark packet for one hand side.

Parameters:
side: HandSide
kind: PacketType
data: HandLandmarks
debug: PacketDebugInfo | None
class hand_tracking_sdk.models.HeadPosePacket(side, kind, data, debug=None)[source]

Bases: object

Parsed head pose packet.

Parameters:
side: HandSide
kind: PacketType
data: HeadPose
debug: PacketDebugInfo | None

Exceptions Module

Custom exception hierarchy for SDK parsing and runtime errors.

exception hand_tracking_sdk.exceptions.HTSError[source]

Bases: Exception

Base exception for SDK errors.

exception hand_tracking_sdk.exceptions.ParseError[source]

Bases: HTSError

Raised when incoming HTS lines cannot be parsed.

exception hand_tracking_sdk.exceptions.TransportError[source]

Bases: HTSError

Base exception for transport-level errors.

exception hand_tracking_sdk.exceptions.TransportClosedError[source]

Bases: TransportError

Raised when operating on a transport receiver that is not open.

exception hand_tracking_sdk.exceptions.TransportTimeoutError[source]

Bases: TransportError

Raised when waiting for network I/O exceeds configured timeout.

exception hand_tracking_sdk.exceptions.TransportDisconnectedError[source]

Bases: TransportError

Raised when a connected TCP peer disconnects.

exception hand_tracking_sdk.exceptions.ClientError[source]

Bases: HTSError

Base exception for high-level client errors.

exception hand_tracking_sdk.exceptions.ClientConfigurationError[source]

Bases: ClientError

Raised when high-level client configuration is invalid.

exception hand_tracking_sdk.exceptions.ClientCallbackError[source]

Bases: ClientError

Raised when a user callback invoked by the client fails.

exception hand_tracking_sdk.exceptions.VisualizationError[source]

Bases: HTSError

Base exception for visualization-layer errors.

exception hand_tracking_sdk.exceptions.VisualizationDependencyError[source]

Bases: VisualizationError

Raised when an optional visualization dependency is not installed.

Visualization Module

Optional real-time visualization helpers.

class hand_tracking_sdk.visualization.VisualizationFrame(*values)[source]

Bases: StrEnum

Output frame convention used for visualization points.

SDK = 'sdk'
FLU = 'flu'
class hand_tracking_sdk.visualization.RerunVisualizerConfig(application_id='hand-tracking-sdk', spawn=True, landmarks_are_wrist_relative=True, wrist_radius=0.025, landmark_radius=0.015, wrist_color=(255, 220, 0), left_landmark_color=(64, 128, 255), right_landmark_color=(255, 64, 64), convert_to_right_handed=True, background_color=(18, 22, 30), visualization_frame=VisualizationFrame.FLU, show_jitter_panel=False, jitter_window_size=200, show_coordinate_frames=False, coordinate_frame_axis_length=0.08)[source]

Bases: object

Configuration for RerunVisualizer.

Parameters:

  • application_id (str) – Application identifier displayed in Rerun.

  • spawn (bool) – If True, spawn a local Rerun viewer on initialization.

  • landmarks_are_wrist_relative (bool) – If True, landmark points are interpreted as wrist-local coordinates and transformed into world frame before logging.

  • wrist_radius (float) – Point radius for wrist markers in meters.

  • landmark_radius (float) – Point radius for landmark markers in meters.

  • wrist_color (tuple[int, int, int]) – RGB color for wrist markers.

  • left_landmark_color (tuple[int, int, int]) – RGB color for left-hand landmark markers.

  • right_landmark_color (tuple[int, int, int]) – RGB color for right-hand landmark markers.

  • convert_to_right_handed (bool) – If True, incoming Unity left-handed data are converted to right-handed coordinates before visualization.

  • background_color (tuple[int, int, int] | None) – Optional RGB background color for the Rerun 3D view.

  • visualization_frame (VisualizationFrame) – Point frame convention for visualization output. flu means x=forward, y=left, z=up.

  • show_jitter_panel (bool) – If True, log jitter/drop scalar metrics under metrics/jitter/....

  • jitter_window_size (int) – Rolling window size for jitter percentile metrics.

  • show_coordinate_frames (bool) – If True, render local XYZ axes for wrist/head poses.

  • coordinate_frame_axis_length (float) – Axis length in meters for rendered coordinate frames.

application_id: str
spawn: bool
landmarks_are_wrist_relative: bool
wrist_radius: float
landmark_radius: float
wrist_color: tuple[int, int, int]
left_landmark_color: tuple[int, int, int]
right_landmark_color: tuple[int, int, int]
convert_to_right_handed: bool
background_color: tuple[int, int, int] | None
visualization_frame: VisualizationFrame
show_jitter_panel: bool
jitter_window_size: int
show_coordinate_frames: bool
coordinate_frame_axis_length: float
class hand_tracking_sdk.visualization.RerunVisualizer(config=None)[source]

Bases: object

Visualizer that logs hand telemetry to rerun.

This component is optional and requires installing the visualization extra.

Parameters:

config (RerunVisualizerConfig | None)

log_packet(packet)[source]

Log one parsed packet to Rerun.

Parameters:

packet (WristPacket | LandmarksPacket | HeadPosePacket) – Parsed packet event from HTS stream.

Return type:

None

log_frame(frame)[source]

Log one assembled frame to Rerun.

Parameters:

frame (HandFrame) – Assembled hand frame.

Return type:

None

log_event(event)[source]

Log either packet or frame event.

Parameters:

event (WristPacket | LandmarksPacket | HeadPosePacket | HandFrame | HeadFrame) – Stream event from hand_tracking_sdk.HTSClient.

Return type:

None