Skip to content

elliewlh2094/codex-robotics-skills / .agents/skills/ros2-transforms

ros2-transforms

Verified

ROS2 TF2 transform patterns for static and dynamic broadcasters, listeners, buffers, frame trees, and timestamped lookup. Use when designing robot coordinate frames, publishing sensor or odometry transforms, using tf2_ros, TransformBroadcaster, StaticTransformBroadcaster, TransformListener, lookupTransform, debugging disconnected or stale frames, ExtrapolationException, TF_OLD_DATA, /tf, /tf_static, map, odom, base_link, or camera frames.

ROS2 Transforms (TF2)

When to Use This Skill

  • Designing the coordinate-frame hierarchy for a new robot
  • Publishing static transforms (sensor mountings) and dynamic transforms (odometry, joint poses)
  • Looking up transforms in a perception or planning node
  • Diagnosing "TF tree disconnected" or "Could not find transform" errors
  • Keeping tf2_ros out of your domain/business code so it stays unit-testable

A Clean Frame Tree

A typical mobile robot:

map                              # global, fixed frame (set by SLAM/AMCL)
 └── odom                        # drift-prone but smooth, set by odometry source
      └── base_footprint         # robot ground projection (z=0)
           └── base_link         # robot body origin
                ├── lidar_link
                ├── camera_link
                │    └── camera_optical    # REP-103 optical convention (z forward)
                ├── imu_link
                └── left_wheel
                └── right_wheel

Rules of thumb:

  • map → odom is the localization correction; odom → base_footprint is the odometry estimate.
  • Each frame has exactly one parent. The TF tree is a tree, not a graph.
  • Sensor frames use REP-103: x-forward, y-left, z-up; camera optical frames use z-forward.
  • Static mountings (camera-on-base) → /tf_static. Anything that moves → /tf.

Broadcast: Static vs. Dynamic

Static (sensor mountings, fixed extrinsics) — Python

from geometry_msgs.msg import TransformStamped
from tf2_ros import StaticTransformBroadcaster

class CameraMount(Node):
    def __init__(self):
        super().__init__('camera_mount')
        self._static = StaticTransformBroadcaster(self)
        t = TransformStamped()
        t.header.stamp = self.get_clock().now().to_msg()
        t.header.frame_id = 'base_link'
        t.child_frame_id = 'camera_link'
        t.transform.translation.x = 0.10
        t.transform.translation.y = 0.00
        t.transform.translation.z = 0.20
        t.transform.rotation.w = 1.0    # identity quaternion
        self._static.sendTransform(t)

Dynamic (odometry, joint motion) — Python

from tf2_ros import TransformBroadcaster

class OdometryPublisher(Node):
    def __init__(self):
        super().__init__('odometry_publisher')
        self._tf = TransformBroadcaster(self)
        self.create_timer(0.02, self._tick)   # 50 Hz

    def _tick(self):
        x, y, theta = self._read_encoders()
        t = TransformStamped()
        t.header.stamp = self.get_clock().now().to_msg()
        t.header.frame_id = 'odom'
        t.child_frame_id = 'base_footprint'
        t.transform.translation.x = x
        t.transform.translation.y = y
        # convert theta → quaternion
        t.transform.rotation.z = math.sin(theta / 2.0)
        t.transform.rotation.w = math.cos(theta / 2.0)
        self._tf.sendTransform(t)

C++ broadcaster

#include <tf2_ros/static_transform_broadcaster.h>
#include <tf2_ros/transform_broadcaster.h>
#include <geometry_msgs/msg/transform_stamped.hpp>

class OdometryPublisher : public rclcpp::Node {
public:
  OdometryPublisher() : Node("odometry_publisher"),
      tf_(std::make_unique<tf2_ros::TransformBroadcaster>(this)) {
    timer_ = create_wall_timer(std::chrono::milliseconds(20),
        [this] () { tick(); });
  }
private:
  void tick() {
    geometry_msgs::msg::TransformStamped t;
    t.header.stamp = now();
    t.header.frame_id = "odom";
    t.child_frame_id = "base_footprint";
    // ... fill translation/rotation ...
    tf_->sendTransform(t);
  }
  std::unique_ptr<tf2_ros::TransformBroadcaster> tf_;
  rclcpp::TimerBase::SharedPtr timer_;
};

Listen: Look Up Transforms

from tf2_ros import Buffer, TransformListener
from rclpy.duration import Duration
from tf2_ros import LookupException, ExtrapolationException

class GoalProjector(Node):
    def __init__(self):
        super().__init__('goal_projector')
        self._buf = Buffer()
        self._listener = TransformListener(self._buf, self)

    def project(self, target_frame: str, source_frame: str):
        try:
            tf = self._buf.lookup_transform(
                target_frame, source_frame, rclpy.time.Time(),
                timeout=Duration(seconds=0.1))
            return tf
        except (LookupException, ExtrapolationException) as e:
            self.get_logger().warn(
                f'TF {source_frame}->{target_frame} unavailable: {e}')
            return None
#include <tf2_ros/buffer.h>
#include <tf2_ros/transform_listener.h>

class GoalProjector : public rclcpp::Node {
public:
  GoalProjector() : Node("goal_projector"),
      tf_buffer_(get_clock()),
      tf_listener_(tf_buffer_) {}

  std::optional<geometry_msgs::msg::TransformStamped>
  lookup(const std::string& target, const std::string& source) {
    try {
      return tf_buffer_.lookupTransform(
          target, source, tf2::TimePointZero,
          tf2::durationFromSec(0.1));
    } catch (const tf2::TransformException& ex) {
      RCLCPP_WARN(get_logger(), "%s -> %s: %s",
                  source.c_str(), target.c_str(), ex.what());
      return std::nullopt;
    }
  }
private:
  tf2_ros::Buffer tf_buffer_;
  tf2_ros::TransformListener tf_listener_;
};

Keep TF2 Out of Domain Code

For codebases large enough to layer, define a domain Pose (plain dataclass with position, orientation, frame_id, timestamp) and an ITransformService port. The TF2 buffer/listener live in an infrastructure adapter that implements the port. Tests inject a fake adapter; the use case never imports tf2_ros.

See ros2-clean-architecture for the full port-and-adapter pattern.

Use Time(0) vs. Specific Timestamps

  • lookup_transform(target, source, Time()) (Python rclpy.time.Time() or C++ tf2::TimePointZero) returns the latest available transform. Convenient, but loses time correlation.
  • For data fusion, look up the transform at the timestamp of the data so you align correctly:
tf = self._buf.lookup_transform(
    'map', msg.header.frame_id, msg.header.stamp,
    timeout=Duration(seconds=0.1))

This will raise ExtrapolationException if the transform isn't yet available — handle by waiting or skipping the message.

Debugging the TF Tree

# Visualize the tree
ros2 run tf2_tools view_frames     # writes frames.pdf
xdg-open frames.pdf

# Inspect a single transform
ros2 run tf2_ros tf2_echo base_link camera_link

# Live monitor
ros2 topic echo /tf_static --once
ros2 topic hz /tf

Common warnings:

  • TF_OLD_DATA — broadcaster sent a transform with a timestamp older than what's already in the buffer. Usually a clock-mixing bug (sim time vs wall time).
  • Lookup would require extrapolation into the future — transform isn't published yet at the time you're asking for. Either wait or use Time(0).
  • frame X does not exist — typo, or a node responsible for publishing X isn't running.

Common Pitfalls

PitfallWhat goes wrongFix
Publishing static transforms on /tf instead of /tf_staticTF buffer fills with duplicate identical transformsUse StaticTransformBroadcaster; it publishes once with TRANSIENT_LOCAL durability
Two broadcasters publishing the same child_frame_idTF tree non-deterministic; "lookup would require extrapolation"One frame, one broadcaster. Audit with view_frames.
Mixing wall time and use_sim_time=trueTF_OLD_DATA warnings, lookups fail intermittentlySet use_sim_time consistently across all nodes (see ros2-launch-config)
Domain code imports tf2_rosCan't unit-test without spinning a ROS nodeDefine ITransformService; inject a fake in tests
Looking up at Time(0) then fusing with a timestamped messageSensor data ends up paired with a transform from the wrong instantLook up at the message timestamp; handle ExtrapolationException
No timeout on lookup_transformCaller blocks forever on first failureAlways pass a timeout; catch the exception

Related Skills

  • ros2-messaging — /tf and /tf_static are messaging on tf2_msgs/geometry_msgs
  • ros2-node-creation — base nodes that own a Buffer + TransformListener
  • ros2-clean-architecture — port pattern for keeping TF out of domain code
  • robot-perception — fusing sensors via TF lookups
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall