ROS 2 TF2 实战：坐标树、变换方向与时间排查

激光雷达说障碍物在前方 1 m，机器人底盘却需要知道这个点在底盘坐标系中的位置。雷达可能装在车体前方，也可能转过一个角度；机器人还可能在采样到处理之间移动。TF2 要解决的就是：这个点属于哪个坐标系、在哪个时刻、要转换到哪个坐标系。

这篇从一条小型坐标链开始，亲手使用 view_frames、tf2_echo、tf2_monitor，然后理解时间缓存和常见报错。基线为 Ubuntu 22.04 + ROS 2 Humble，核对日期 2026-09-27。Linux Bash 命令可以在开发机或 Linux 容器内执行；RViz 需要可用的图形环境。

配套实验说明、广播程序 demo.py、查询与断言 probe.py均可下载，不需要创建 ROS 包或运行 colcon。实际验证范围见验证记录。

一、先弄清 TF2 保存的是什么

1.1 坐标系、坐标值与变换

laser_frame 是坐标系的名字，[1, 0, 0] 是某个点在它里面的坐标。离开坐标系名字，这三个数字就不完整；对于运动系统，通常还需要时间戳。

TF2 保存坐标系之间带时间的刚体变换，供各进程的 Buffer 缓存并查询。它会沿坐标链组合、求逆和在可用的动态样本之间插值，但不会自动帮你估计传感器外参或机器人位姿。那些数据来自标定、里程计、定位、关节状态等上游。

部分	作用
`TransformBroadcaster`	发布随时间变化的关系，通常进入 `/tf`
`StaticTransformBroadcaster`	发布固定关系，进入 `/tf_static`
`TransformListener`	接收消息并填充当前进程的 Buffer
`Buffer`	查询指定时刻的变换，维护局部历史
`tf2_geometry_msgs`	为点、姿态等消息提供 TF2 转换支持

因此，TF2 不是一个所有节点共用的中央查询数据库。命令行工具能查到，不代表你刚创建的业务 Buffer 已经收到了同样的数据。TF2 概念文档

1.2 树上的箭头与点的换算方向

本文统一用 T_A_B 表示“B 坐标系在 A 中的位姿，同时把 B 中的点换算到 A 中”：

p_A = R_A_B × p_B + t_A_B

发布一个 TransformStamped 时：

header.frame_id = "base_link"    # 父坐标系 A
child_frame_id  = "laser_frame"  # 子坐标系 B
transform                        # T_A_B

TF 树画成 base_link → laser_frame，表示父子关系；这份变换用于点坐标换算时，是把 laser_frame 中的坐标换到 base_link 中。树的父子箭头不能直接理解为“点坐标的输入 → 输出”。

对 C++ API，参数更直接：

auto transform = buffer.lookupTransform(
  "base_link",    // target：希望得到的坐标系
  "laser_frame",  // source：原始数据的坐标系
  tf2::TimePointZero);

它返回的正是 T_base_link_laser_frame。Python 的 lookup_transform(target, source, time) 遵循同样顺序。TimePointZero 的时间语义后面单独解释。Buffer API

TF 树父子关系和点坐标换算方向

1.3 常见坐标系的分工

移动机器人常见关系是：

map → odom → base_link → laser_frame
                       └→ camera_link → camera_optical_frame

map 用于全局定位，可以因定位修正而跳变；odom 用于局部连续运动，可能长期漂移；base_link 固连机器人机体。把这两种世界参考拆开，可以兼顾局部连续控制与全局纠偏。REP-105

一般机器人机体系采用米、弧度、右手系，轴约定为 x 前、y 左、z 上；相机 optical frame 则通常为 z 前、x 右、y 下。不要因为画面“像是转错了”就盲目加一个负号，应先核对 frame 约定。REP-103

同一个 child frame 应有一个明确的父级和发布来源。不要让两个节点同时发布 odom → base_link，也不要为了让图连通随意补一个不真实的静态变换。本实验只用 odom，不伪造定位系统的 map。

二、十分钟跑通一个确定的数值例子

2.1 安装与终端环境

以下假设 Ubuntu 已配置 ROS 2 Humble 的 apt 源：

sudo apt update
sudo apt install ros-humble-tf2-ros ros-humble-tf2-tools \
  ros-humble-tf2-geometry-msgs ros-humble-geometry-msgs \
  ros-humble-rclpy graphviz
source /opt/ros/humble/setup.bash

每个新终端都要 source。不同终端应使用相同的 ROS_DOMAIN_ID、RMW 和网络配置；否则先排查发现与通信，TF2 工具无法替你跨越隔离的 ROS 域。

2.2 先只发布一个静态关系

在终端 A 中运行并保持进程存活：

ros2 run tf2_ros static_transform_publisher \
  --x 0.3 --y 0 --z 0.2 \
  --roll 0 --pitch 0 --yaw 1.5707963267948966 \
  --frame-id base_link --child-frame-id laser_frame

意思是：雷达坐标系原点在底盘坐标系的 [0.3, 0, 0.2] m 处，绕 z 轴旋转 +90°。这个旋转是为了让换算方向更容易验证，不代表所有雷达都应该这样安装。使用具名参数可以避免不同历史位置参数写法导致的角度顺序混淆；以本机 --help 为准。静态 broadcaster 教程

终端 B 查询：

ros2 run tf2_ros tf2_echo base_link laser_frame

应看到近似如下的平移与旋转，末位受显示精度影响：

Translation: [0.300, 0.000, 0.200]
Quaternion (xyzw): [0.000, 0.000, 0.707, 0.707]
RPY (radian): [0.000, 0.000, 1.571]

纯静态查询显示时间为 0 并不等于数据坏了，静态关系不靠每秒重发来覆盖某段动态历史。四元数 q 和 -q 表示同一旋转，也不要因为整体变号就判断姿态反了。

2.3 用一个点验证方向

假设点在雷达坐标系中为 [1, 0, 0]：先绕 z 轴旋转 +90°，变成底盘方向的 [0, 1, 0]，再加上安装平移，得到：

p_laser = [1.0, 0.0, 0.0]
p_base  = [0.3, 1.0, 0.2]

结束 B 中的命令，再反向查询：

ros2 run tf2_ros tf2_echo laser_frame base_link

反向平移应约为 [0, 0.3, -0.2]，yaw 约为 -90°。它不是简单地把原平移逐项取负，因为：

R_B_A = transpose(R_A_B)
t_B_A = -transpose(R_A_B) × t_A_B

只用纯平移练习时，“取负号”碰巧成立；一旦有旋转，这种记法就会错。

三、三个工具分别怎么看

3.1 view_frames：先检查结构

在一个有写入权限的目录运行：

mkdir -p /tmp/tf2-learning
cd /tmp/tf2-learning
ros2 run tf2_tools view_frames

它默认采集约 5 秒，在当前目录生成 Graphviz 文件和 PDF；文件可能叫 frames.pdf，也可能带时间后缀，以实际输出和目录为准。打开 PDF 后先看坐标树是否符合设计，而不是先盯着所有数字。Humble 实现

图上的信息	应该怎么用
Parent / Child	是否接到正确的机体或关节上，有没有拼写错误
多个不相连的树	两组坐标系之间缺少可用链路
Average rate	观察窗口内动态 TF 的更新情况，不是控制器执行频率
Most recent / Oldest transform	当前工具的 Buffer 实际持有哪些时间的数据
Buffer length	本次看到的时间跨度，不等于进程已经运行多久
Broadcaster	可能无法提供可靠的发布者名称，不能单独用它追责

静态边可能显示特殊的时间、很高的 rate 或零 buffer length；这些缓存表示值不能按动态发布频率解释。工具只观察了一小段时间，5 秒图中没有 10 秒历史也正常。

3.2 tf2_echo：核对两帧之间的数值

tf2_echo A B 输出 B 相对于 A 的位姿，也就是把 B 中点坐标转换到 A 的变换。Humble CLI 帮助里的 source/target 命名容易误读；其内部实际调用 lookupTransform(A, B, ...)，与前面的点换算实验相符。Humble tf2_echo 源码

使用时依次检查：

平移是否符合实际安装距离，单位是不是米。
RPY 和四元数是否符合安装方向；命令中的角度单位是弧度。
动态链的时间戳和数值是否持续更新。
反向查询是否与求逆一致。

刚启动出现一次 Waiting for transform 可能只是监听器尚未接收数据；一直出现才需要排查。该工具默认查最新可用变换，能成功不能证明某条旧传感器消息的时间戳也能成功。

3.3 tf2_monitor：观察更新和时间滞后

有动态坐标链时运行：

ros2 run tf2_ros tf2_monitor odom laser_frame

它会持续输出链路和延迟统计，观察十几秒后按 Ctrl+C。重点看动态边的更新时间和平均／最大延迟是否明显异常。

对逐帧统计，Humble 实现计算的是“监听器当前 ROS 时间减消息 stamp”；链路的 Net delay 则涉及当前时间与最新可用组合变换的时间差。它们包含时间戳策略、采样／处理滞后、传输与调度等影响，不能直接命名为网络 RTT 或单向网络耗时。Humble tf2_monitor 源码

静态消息只发布固定关系，晚加入的 monitor 可能把很早的 stamp 与当前时间相减；不要把这个值当作静态外参“延迟越来越大”。显示 <no authority available> 也不直接证明广播者不存在。要查谁在发，结合 ros2 topic info /tf --verbose、节点启动配置和源码。

另外，Humble 的 Net delay avg 使用从 0 初始化的低通估计，并非逐帧 delay 的普通算术平均；启动十几秒时可能尚未收敛。看结果前，先分清输出所在的段落和统计定义。

四、动态实验：把结构、数值和时间放在一起

4.1 启动随文程序

先 Ctrl+C 停掉前面的静态发布器，避免与实验重复发布相同 child。下载两个 Python 文件到同一目录，终端 A 执行：

source /opt/ros/humble/setup.bash
python3 demo.py

它生成下面这条链：

odom ── 动态，20 Hz ──> base_link ── 静态安装关系 ──> laser_frame
         x = 0.5 sin(t)                [0.3, 0, 0.2] m
                                      yaw = +90°

20 Hz 是设定的 timer 频率，不保证每次实际间隔恰好 50 ms。动态边的姿态为单位旋转，机体只沿 odom 的 x 方向往复移动；这只是学习夹具，不是运动学仿真或定位算法。

终端 B 执行：

source /opt/ros/humble/setup.bash
python3 probe.py

脚本在收齐链路后验证正向平移、反向平移、点坐标变换和跨边组合，同时故意查询不存在的 frame、未来时间和过去时间。正常结果应包含 "passed": true；缺帧为 LookupException，时间越界为 ExtrapolationException，具体报错文字可能因版本变化。

这里查询过去 60 秒失败，不只是因为默认缓存有限：这个 probe 是刚创建的监听器，根本没有运行并接收那么久。进程 A 已广播一分钟，不意味着进程 B 一启动就拥有一分钟动态历史。

4.2 再用三个工具交叉验证

分别运行 view_frames、tf2_echo odom laser_frame 和 tf2_monitor odom laser_frame，持续命令之间用 Ctrl+C 结束。此时应该看到：

坐标树是一条完整链，不应有第二个父节点。
base_link → laser_frame 始终固定。
odom → laser_frame 的 x 等于动态 base 的 x 加 0.3，z 等于 0.2。
动态更新时间持续推进；普通 Linux 上允许存在调度波动。

安装 ros-humble-rviz2 后，在图形 Linux 中运行 rviz2，把 Global Options 的 Fixed Frame 设为 odom，Add 一个 TF 显示并开启坐标轴和名称。应看到机体及雷达一起往复移动。若 Fixed Frame 设成 base_link，机体自身会固定在观察参考系中，这是换了观察方式，不是 TF 停止了。

4.3 人为制造 0.5 秒旧数据

停掉 demo，重新启动：

python3 demo.py --ros-args -p stamp_delay:=0.5

再次运行 probe 和 monitor。该模式发布“0.5 秒前的位姿及对应时间戳”，可用于模拟处理链滞后；它不是只把当前位姿的时间标签改旧。

你会看到最新查询仍可能成功，但 latest_age_seconds 和动态边 delay 明显增加到约半秒量级。能查到变换，与查到足够新的变换，是两个检查。 本机实际数值和工具输出保存在验证记录中，不把一次容器测量当成通用性能基准。

本次实测中，base_link 的 Average Delay 从约 1.18 ms 增至 501.09 ms；probe 测得最新动态 TF 年龄从约 2.31 ms 增至 501.20 ms。normal 会话里静态 laser_frame 却显示约 15.27 s，这是静态 stamp 的年龄，不能与动态边一视同仁。

五、时间：多数难查问题都在这里

5.1 最新可用，不等于此刻

动态链中，各条边的最新时间戳可能不同。最新查询必须找一个整条链都能成立的公共时间，而不是把各边不同时间的最后一个值直接拼起来。

边 A → B：已有样本到 10.20 s
边 B → C：已有样本到 10.15 s
链 A → C：最新公共时间最多到 10.15 s

还需要两条边的历史区间存在交集。静态边没有相同的动态时间覆盖限制。tf2::TimePointZero / Python Time() 是“查询最新”的约定值，不能解释为必须取得物理时刻 0 的动态样本。

动态样本覆盖范围与最新公共时间示意

5.2 为什么查 now 会报 future extrapolation

应用读到 now = 10.21 s，但 Buffer 最新收到的动态 TF 只有 10.20 s。查询此刻就要求向未来推算。TF2 不会凭空预测运动，所以报错是合理的；正常系统也可能因为发布周期与传输时间出现这种差距。TF2 与时间教程

处理方式取决于任务：

只想查看当前附近的位姿，用 latest 并检查新鲜度。
转换激光／点云数据，应查消息采样时间，必要时等对应 TF 到达。
必须在控制时刻使用状态，需要明确状态预测或延迟补偿设计，不能指望 TF2 自动完成。

不要把所有输入 stamp 改成 now，也不要对所有报错都改用 latest。机器人运动时，这会把旧测量配到新位姿上，产生几何误差，却可能不再报错。

5.3 timeout 是等待，不是放宽时间条件

给 lookup 加 50 ms timeout，意思是允许数据在这段等待期间到达；不会自动接受 50 ms 前后的任意时间，也不会做未来外推。

同时需要有人继续处理 TF 订阅回调。若单线程 Executor 正在你的回调里同步等待，而 TF Listener 的回调也只能在同一个线程执行，就可能出现“越等越收不到”。保持 Buffer/Listener 长期存活，合理安排监听线程；高频传感器可以考虑 tf2_ros::MessageFilter，等所需时间的变换可用后再处理消息。MessageFilter 教程

5.4 仿真时间、bag 与多机器

ros2 param get /your_node use_sim_time
ros2 topic echo /clock --once

把 /your_node 换成实际节点。使用仿真时，相关广播者、查询者、可视化工具都应采用一致的时间体系；设置 use_sim_time=true 但没有 /clock，时间可能不推进。不要混用仿真秒数与系统 Unix 时间。

查看仿真 TF 时，工具也可以加载 ROS 参数，例如：

ros2 run tf2_ros tf2_echo odom base_link --ros-args -p use_sim_time:=true
ros2 run tf2_ros tf2_monitor odom base_link --ros-args -p use_sim_time:=true

bag 回放应同时检查 /tf、/tf_static 是否录到，目标节点是否使用回放时钟，以及回放跳转后缓存是否已经重建。多机器上则先确认时钟同步；时间戳在未来、monitor 出现负延迟，优先查时钟与 stamp 生成方式，不能据此认定网络“负延迟”。ROS 2 时钟设计

六、把 TF2 用到 C++ 消息处理里

下面是消息回调中的片段，假设 msg 为 geometry_msgs::msg::PointStamped::SharedPtr，tf_buffer_ 和对应 Listener 已经初始化且持续接收数据：

try {
  const auto transform = tf_buffer_->lookupTransform(
    "base_link",
    msg->header.frame_id,
    rclcpp::Time(msg->header.stamp),
    rclcpp::Duration::from_seconds(0.05));

  geometry_msgs::msg::PointStamped point_in_base;
  tf2::doTransform(*msg, point_in_base, transform);
  // 在这里使用 point_in_base，包含新的 frame_id 和变换后的坐标。
} catch (const tf2::TransformException & error) {
  RCLCPP_WARN(get_logger(), "TF unavailable: %s", error.what());
}

需要包含 tf2_ros/buffer.h、tf2_ros/transform_listener.h、tf2_geometry_msgs/tf2_geometry_msgs.hpp 以及 rclcpp/geometry_msgs 的相应头文件，包依赖包含 tf2、tf2_ros、tf2_geometry_msgs、geometry_msgs、rclcpp。它是工程接入片段，不是完整可执行程序；本篇运行验证使用可直接下载的 Python 实验。

注意三点：

header.frame_id 必须真实描述输入数据，不能只改字符串就假装完成了坐标变换。
PointStamped 的变换会应用旋转和平移；自由向量如速度方向和 Vector3Stamped 的语义不同，不该随便加位置平移。
若需要在不同时间的两个运动坐标系之间换算，要使用带 source time、target time、fixed frame 的高级查询，不能把普通一次同时间 lookup 当作时间补偿。跨时间变换教程

七、静态 TF、URDF 与机器人状态

7.1 为什么静态 TF 要让发布器保持存活

/tf_static 通常使用 transient-local durability，让后来加入的订阅者在发布者仍在时获得保留的静态数据。现有 Buffer 收到后可以继续持有它，但普通 DDS 场景中不能指望发布者退出后，新启动的监听器仍能从网络上取回它。

调试时要区分“RViz 一直开着所以能看到”和“刚启动的 probe 能收到”。不要先启动静态发布器、立刻关闭，再把新节点收不到归因于 TF2 缓存出错。StaticTransformBroadcaster 实现

7.2 已经有 URDF 时谁来发

robot_state_publisher 根据 URDF 的关节结构和 /joint_states 计算 link 变换；固定关节通常进入 /tf_static，可动关节进入 /tf。如果 URDF 已定义 base_link → laser_frame，不要再额外运行一个同名静态发布器。robot_state_publisher 说明

joint_state_publisher 是关节状态的来源之一；robot_state_publisher 才负责把模型和关节状态转换成 TF。移动底盘的 odom → base_link、定位的 map → odom 往往还需要里程计／定位节点负责，不是加载 URDF 后就自动齐全。

八、遇到报错，按这个顺序查

现象	常见原因	第一条验证动作
frame does not exist	名称拼错、还未接收、域不一致	`view_frames` 查看实际名字，再检查端点
两个 frame 存在但无法连接	属于两棵树，缺一条真实变换	找断开的父子边，确认应该由哪个节点发布
extrapolation into the future	查询时间比最新动态 TF 更晚	比较请求 stamp 和最新 TF；核查 now 与消息时间
extrapolation into the past	消息太旧、缓存未覆盖、监听器启动太晚	看 Buffer 最早时间与消息 stamp
latest 成功，传感器转换失败	指定时间不可用或 frame 不同	用失败消息的真实 frame/stamp 复查
RViz 模型抖动／跳变	重复广播、来源切换、定位修正、时间不一致	查同一 child 的发布责任及时间线
坐标正负或方向奇怪	变换求反、单位、机体系／optical 约定混淆	用一个已知点手算，再正反查询
静态 TF 旧进程能看、新进程不能	发布者已退出、durability 不匹配	保持发布器存活，用新监听器重试

网络层辅助命令：

ros2 topic info /tf --verbose
ros2 topic info /tf_static --verbose
ros2 topic echo /tf_static --qos-durability transient_local --once

一条 /tf 消息可以包含多个 transform，不同节点也会共享 /tf。因此 ros2 topic hz /tf 不是某条边的精确频率，rqt_graph 里的 topic 连接也不能替代 TF 坐标树。若要查重复发布，结合消息里的 child、发布节点配置和受控停用实验，不能只凭 /tf 有多个发布者就断定异常。官方排障流程

九、三次练习的验收标准

练习一：方向。 发布固定平移和 +90° yaw，正向查到 [0.3, 0, 0.2]，反向查到 [0, 0.3, -0.2]；能解释为什么一个雷达点 [1, 0, 0] 会变成底盘点 [0.3, 1, 0.2]。

练习二：工具。 运行 demo 和 probe，得到 passed: true；在 view_frames 找到完整链，用 tf2_echo 对照组合变换，用 monitor 检查动态更新时间。能解释为什么 RViz 换 Fixed Frame 后画面变了。

练习三：时间。 启用 0.5 秒滞后，再查询最新与指定时间。能解释“能查到”和“足够新”的区别，看到 future/past 错误时先写出“请求时间、最早可用时间、最晚可用时间”。

把每个 TF 问题缩成五项：目标 frame、来源 frame、请求时刻、实际链路、Buffer 覆盖时间。 这五项齐全，通常就能分清是坐标设计、通信、时间还是代码执行的问题。