Units and Conventions

Units

All values are SI unless stated otherwise.

Quantity

Unit

Position, length, size, distance

metre (m)

Angle, joint position of a revolute joint

radian (rad)

Joint position of a prismatic joint (linear rail)

metre (m)

Joint velocity

rad/s or m/s

Force / torque (Wrench)

newton (N) / newton-metre (Nm)

Mass

kilogram (kg)

Inertia

kg·m²

Area (mesh filters)

m²

Rotations

Orientations are unit quaternions:

message Quaternion { double x = 1; double y = 2; double z = 3; double w = 4; }

Warning

An unset quaternion is all zeros. The SDK conversion helpers (Math Conversions) read it as the identity, but the server does not guarantee the same. When you build a Quaternion by hand, always set w=1.0 for “no rotation”. This also applies to the origin of Visual and Collision and to PathRefinement.rotation_offset.

Normalize quaternions before sending them.

Some component messages (Adapter) use xyz plus rpy (roll, pitch, yaw in radians) instead of a quaternion.

Element order in the helpers

The protobuf Quaternion stores x, y, z, w. The conversion helpers follow their libraries’ conventions:

  • Python to_numpy(Quaternion) returns [w, x, y, z], and to_proto(array, Quaternion) reads [w, x, y, z].

  • C++ ToEigen/ToProto use Eigen::Quaterniond, which has named accessors, so there is no ordering ambiguity.

See Math Conversions.

Poses

SE3Pose is a position and a rotation. A pose is always relative to some frame:

  • ConfigHeader.pose_in_parent is relative to ConfigHeader.parent.

  • Frame carries both pose_world and pose_parent.

  • Points in path generator requests are in the parent object’s frame unless the field documentation says world frame (for example MeshRasterPath.specified_direction).

Joint vectors

Joint vectors are plain repeated double lists. For a 7-DoF Rizon arm they hold seven values ordered from base to flange. With external axes, the JOINT_GROUP_SYSTEM group contains all actuated joints of the system; JOINT_GROUP_ARM, JOINT_GROUP_EXTERNAL_ROBOT_AXIS and JOINT_GROUP_EXTERNAL_WORKPIECE_AXIS select a subset.

Proto3 defaults

Fields you do not set take their proto3 default: 0, "", false, the first enum value, or an empty message. Some proto comments describe a different “default” (for example a boolean documented as “default true”). The server may treat zero values as “use the default”, but do not rely on it: set every field you care about explicitly.