Every pose in ROS, from a robot's odometry to a camera's mounting angle, stores its orientation as a quaternion: four numbers called x, y, z and w. Most developers learn to pass them along without looking inside, until a sensor ends up pointing the wrong way. This guide gives you a working intuition for quaternions, enough to read them, build them and debug them.

Why not just use angles?

Roll, pitch and yaw are easy to picture, which is why we type them in launch files and URDFs. But as a storage format for orientation they have two problems. They depend on a convention (which axes, in which order), and they break down at certain orientations, a problem called gimbal lock. Rotation matrices avoid both, but use nine numbers that must stay consistent. Quaternions use four numbers, have no singularities, combine cheaply and interpolate smoothly, so ROS uses them in every message.

The one idea you need: axis and angle

Any orientation can be reached from the starting orientation by a single rotation about one axis. A unit quaternion simply encodes that axis and angle:

So (x, y, z) points along the rotation axis, and w tells you how far around it you turn. A few examples you will meet constantly:

With practice you can read a quaternion at a glance: a large w means a small rotation; whichever of x, y, z is large tells you the main axis.

Three rules that prevent most bugs

1. A rotation quaternion has length 1

x² + y² + z² + w² must equal 1. A quaternion of (0, 0, 1, 1) is not a valid rotation; normalised, it becomes (0, 0, 0.7071, 0.7071). Many libraries normalise silently, which hides the bug that produced the bad value. Tools such as tf2 reject or warn about unnormalised quaternions in transforms, and the Quaternion ↔ Euler Converter warns you too.

2. q and −q are the same rotation

Flipping the sign of all four numbers gives the same orientation (turning by angle θ about an axis is the same as turning by 360° − θ about the opposite axis). Two libraries can therefore print different-looking quaternions for one orientation, and both are right. Compare rotations, not raw numbers.

3. Know the component order

ROS messages (geometry_msgs/Quaternion), tf2, SciPy and most ROS tooling use (x, y, z, w). Eigen's constructor, many textbooks and some other libraries use (w, x, y, z). Mixing them up produces a valid but completely wrong rotation without any error. Our guide to converting in Python and C++ shows each library's order, tested side by side.

Combining rotations

Two rotations combine by quaternion multiplication, and the order matters. In ROS's tf2 (and in SciPy), q = q1 * q2 applies q2 first, in the frame rotated by q1. In practice you rarely multiply quaternions by hand: tf2 chains transforms for you when you look up a transform between two frames. When you do multiply, test with a simple case you can picture, such as two 90° turns.

Reading quaternions on a running robot

# the transform between two frames, with RPY and the matrix already worked out
ros2 run tf2_ros tf2_echo base_link camera_link

# orientation of the robot in odometry
ros2 topic echo /odom --field pose.pose.orientation

tf2_echo is the best friend of anyone debugging orientation: it prints the quaternion, the roll-pitch-yaw in radians and degrees, and the full matrix. To read a matrix, remember that its columns are the child frame's X, Y and Z axes expressed in the parent frame.

When you need angles

For a human-readable display, a heading for a controller or a value to type into a config file, convert to roll, pitch and yaw, but convert at the last moment and keep quaternions everywhere else. The converter does it in either direction using the ROS conventions, draws the result in 3D and writes the matching tf2 command, URDF snippet and code. Our guide to roll, pitch and yaw in ROS explains those conventions.