Qnbot Hand Algorithm Package Output

SDK overview

qnbot-sdk sits between glove data and the hand algorithm package:

Glove data -> qnbot-sdk -> Hand algorithm package -> SDK output topic -> Application

The SDK sends glove data to the selected algorithm package and converts the results into stable public Python data types. Applications subscribe to topics and receive Sample[T] values:

• Sample.sequence: the frame sequence number for the current topic, which can be used to detect dropped or out-of-order frames.
• Sample.value: the algorithm result for the current frame.

Algorithm outputs fall into two categories:

Standard robotic-hand output

Return type

The output type for a standard robotic-hand algorithm package is HandJointCommand:

@dataclass(frozen=True)
class HandJointCommand:
    target: str
    joints: dict[str, float]
    timestamp: float
    source: str | None
    metadata: dict[str, object]

Every value in joints is a joint position measured in radians (rad). It is not measured in degrees, and it is not an encoder value, velocity, torque, or current.

Example result:

HandJointCommand(
    target="primary",
    joints={
        "thumb_joint": 0.42,
        "index_joint": 0.86,
        "middle_joint": 0.74,
    },
    timestamp=123.456,
    source="retargeting",
    metadata={},
)

The joint names above demonstrate the data structure only. They are not the fixed joint list for a specific robotic hand.

Joint names and counts

Joint names and counts are defined by the algorithm package for the selected target-hand model and therefore differ between robotic hands. The joints dictionary returned by the SDK is the actual public output set for the current target.

Follow these rules when consuming it:

• Always access values by joint name. Do not assume that different hand models share array indices.
• Do not infer the robotic-hand controller order from Python dictionary iteration order.
• When converting the result to a controller array, maintain an explicit controller_joint_order in the application and assemble the array by name.
• Some hand models contain mechanically coupled or passive joints. An algorithm package may return both active joints and passive joints derived from coupling relationships; do not infer degrees of freedom from the joint count alone.
• Whether left and right hands use different joint-name prefixes depends on the specific model. Use the names returned by the SDK rather than constructing left_ or right_ prefixes yourself.

Minimal subscription example

The following example shows only the core output subscription. Device and target configuration are owned by the host application:

from qnbot_sdk import Sample
from qnbot_sdk.glove import HandJointCommand


def on_output(sample: Sample[HandJointCommand]) -> None:
    command = sample.value
    print("sequence:", sample.sequence)
    print("target:", command.target)
    for joint_name, angle_rad in command.joints.items():
        print(joint_name, angle_rad)


output_subscription = device.output().subscribe(on_output)

Dynamic OpenXR output

Dynamic OpenXR provides both joint angles and a 25-point skeleton pose. The two outputs come from the same algorithm package but use different SDK topics; their indices cannot be mapped directly to one another.

• Dynamic OpenXR 25-point skeleton pose output example 1
• Dynamic OpenXR 25-point skeleton pose output example 2

25-point skeleton pose

Subscribe with:

skeleton = device.skeleton()
skeleton.pose().subscribe(on_skeleton_pose)

The return type is HandSkeletonPose:

@dataclass(frozen=True)
class HandSkeletonPose:
    timestamp_sec: float
    hand_side: Side
    coordinate_frame: str
    names: tuple[str, ...]
    positions_local: tuple[tuple[float, float, float], ...]
    orientations_local_xyzw: tuple[tuple[float, float, float, float], ...]

Elements at the same index in all three arrays describe the same joint:

for index, name in enumerate(pose.names):
    position_m = pose.positions_local[index]
    orientation_xyzw = pose.orientations_local_xyzw[index]

The fixed joint order is:

Complete name order:

wrist
thumb_metacarpal, thumb_proximal, thumb_distal, thumb_tip
index_metacarpal, index_proximal, index_intermediate, index_distal, index_tip
middle_metacarpal, middle_proximal, middle_intermediate, middle_distal, middle_tip
ring_metacarpal, ring_proximal, ring_intermediate, ring_distal, ring_tip
little_metacarpal, little_proximal, little_intermediate, little_distal, little_tip

Hand skeleton diagram: fixed Dynamic OpenXR 25-joint names

Coordinate conventions

wrist_local is a local right-handed Cartesian coordinate frame that moves with the wrist:

• All positions are in meters and use (x, y, z) component order.
• All quaternions use (x, y, z, w) component order.
• The wrist position is fixed at (0, 0, 0).
• The wrist orientation is fixed at (0, 0, 0, 1).
• Every other joint position is expressed in the same wrist frame, not as an offset from its parent joint.
• This interface does not provide a world pose.

The coordinate transform is:

p_local = R_wrist^T * (p_node - p_wrist)
R_local = R_wrist^T * R_node

Minimal subscription example

from qnbot_sdk import Sample
from qnbot_sdk.glove import HandSkeletonPose


def on_pose(sample: Sample[HandSkeletonPose]) -> None:
    pose = sample.value
    for index, name in enumerate(pose.names):
        print(
            name,
            pose.positions_local[index],
            pose.orientations_local_xyzw[index],
        )


skeleton = device.skeleton()
pose_subscription = skeleton.pose().subscribe(on_pose)