Glossary

Fictionlab > Glossary > tf2 (transform library)

tf2 (transform library)

tf2 – definition

tf2 is the transform library used in ROS and ROS 2 to manage spatial relationships between coordinate frames over time. It allows a robot application to determine the pose of one frame relative to another frame at a requested timestamp. In mobile robotics, tf2 is the standard mechanism for connecting robot body frames, wheel odometry, sensors, maps, and global positioning references.

A tf2 transform is represented by a translation vector and a rotation quaternion. ROS 2 commonly transports transforms in geometry_msgs/msg/TransformStamped. The message identifies a parent frame in header.frame_id and a child frame in child_frame_id. The transform expresses the pose of the child frame relative to the parent frame.

T_parent_child =
[ R  t ]
[ 0  1 ]

In this homogeneous transformation matrix, R is a 3 × 3 rotation matrix and t is a 3D translation vector. tf2 normally uses quaternions instead of matrices on ROS topics to avoid Euler-angle singularities and reduce message size.

On an unmanned ground vehicle (UGV), tf2 provides the frame tree required by localization, SLAM, sensor fusion, navigation, and perception nodes. A Leo Rover or Raph Rover operating with ROS 2 typically needs a consistent relationship between map, odom, base_link, wheel frames, and sensor frames before Nav2, robot_localization, or SLAM software can operate correctly.

Coordinate frame conventions for UGVs

ROS coordinate conventions are defined primarily by REP 103 and REP 105. REP 103 specifies right-handed coordinate frames and the common mobile robot axis convention: X forward, Y left, and Z up. REP 105 defines commonly used frames for mobile robots, including map, odom, and base_link.

A practical UGV transform tree often follows this structure:

map
 └── odom
      └── base_footprint
           └── base_link
                ├── laser_frame
                ├── imu_link
                ├── camera_link
                └── gps_link

The frames have distinct responsibilities:

  • map is a globally consistent reference frame produced by SLAM or localization.
  • odom is a locally continuous frame derived from wheel odometry, visual odometry, or state estimation.
  • base_footprint is commonly placed on the ground projection of the robot base for a wheeled UGV.
  • base_link is rigidly attached to the robot body and is the primary frame for payload integration.
  • Sensor frames define the physical location and orientation of a LiDAR, IMU, depth camera, GNSS antenna, or other device.

REP 105 recommends separating map and odom. The odom frame should remain continuous over short periods, while the transform between map and odom may change when a localization system corrects accumulated drift.

How tf2 works in ROS 2

ROS 2 tf2 distributes transforms through two standard topics. Dynamic transforms are published on /tf. Static transforms are published on /tf_static. Nodes query a local tf2 buffer rather than directly calculating every transform chain.

The main ROS 2 tf2 components are:

  • tf2_ros::TransformBroadcaster publishes time-varying transforms, such as odom → base_link.
  • tf2_ros::StaticTransformBroadcaster publishes fixed sensor mounting transforms.
  • tf2_ros::Buffer stores received transforms and resolves frame-to-frame queries.
  • tf2_ros::TransformListener subscribes to transform topics and fills a buffer.

The default tf2 buffer cache duration is 10 seconds in the tf2 ROS API. A lookup can fail when transform data is older than the requested timestamp, arrives late, or connects frames from separate transform trees. These failures are common when sensor timestamps, simulation time, and system clocks are not synchronized.

ros2 run tf2_ros tf2_echo base_link laser_frame
ros2 run tf2_tools view_frames
ros2 topic echo /tf --once
ros2 topic echo /tf_static --once

The tf2_echo command verifies a transform at runtime. The view_frames tool generates a frame-tree report and helps identify missing parents, duplicate broadcasters, and disconnected subtrees.

Static and dynamic transforms on Leo Rover and Raph Rover

Leo Rover can be used with ROS 2 and has a differential/skid-steer mobile-base architecture. Its motion estimate normally provides a dynamic relationship from odom to a robot body frame. A navigation stack still requires an externally integrated localization or SLAM component to provide map → odom.

For a Leo Rover, sensor mounting should be described in URDF or Xacro and published through robot_state_publisher where possible. This makes fixed transforms reproducible across simulation, laboratory testing, and field deployment. A LiDAR frame must reflect the actual mounting height, forward offset, roll, pitch, and yaw relative to base_link.

Raph Rover uses the same tf2 concepts but may carry larger or multiple payloads. For example, a perception configuration can include a 3D LiDAR, stereo or depth camera, GNSS/RTK antenna, and IMU. Each device needs a calibrated rigid transform to the vehicle body frame. GNSS integration also requires a defined antenna reference point because the antenna position is not normally coincident with base_link.

A fixed LiDAR transform can be published for validation during integration:

ros2 run tf2_ros static_transform_publisher \
  0.18 0.00 0.32 0 0 0 \
  base_link laser_frame

The six pose values above are only an example. They must be replaced with measured or CAD-derived mounting parameters. Incorrect extrinsic calibration causes systematic errors in obstacle positions, point-cloud registration, scan matching, and camera-LiDAR fusion.

tf2 requirements for navigation and perception

Most autonomous UGV stacks depend on specific transform availability. Nav2 requires a valid transform chain between the robot base frame, odometry frame, and configured global frame. SLAM packages typically publish or require map → odom. LiDAR-based obstacle layers need a transform from the scan frame to the costmap frame at the scan timestamp.

The following checks should be completed before autonomous testing:

  • Use REP 103 axis orientation for all robot and sensor frames.
  • Ensure every child frame has one parent in the active tf2 tree.
  • Publish rigid sensor transforms on /tf_static.
  • Publish motion-dependent transforms on /tf with valid timestamps.
  • Use a consistent time source for all nodes that exchange transforms; configure use_sim_time consistently when using a simulation clock.
  • Verify that URDF frame names match Nav2, SLAM, and sensor-driver parameters exactly.

Normative references and technical sources

The following primary references define the conventions and APIs used by tf2 in ROS-based mobile robotics:

See also