apriltag_ros Quick Start

本文记录一次基于 ROS 2 Humble 的apriltag_ros快速实验：生成 AprilTag 标定板，回放 RealSense rosbag2 数据集，启动 AprilTag 检测节点，并在 RViz 中查看检测结果和 TF。

目录

• 0. apriltag_ros 概述
• 1. 安装依赖
• 2. 准备数据集
• 3. 实验
  • 3.1 生成 AprilTag 标定板
  • 3.2 回放数据并检测
• 4. 验证结果
• 5. 参数说明
  • 5.1 Launch 参数
  • 5.2 YAML 结构
  • 5.3 基础参数
  • 5.4 Detector 调参
  • 5.5 指定 tag ID、frame 和尺寸
• 6. 常见问题
• 参考

0. apriltag_ros 概述

AprilTag 是一种视觉基准标记系统，最早由 University of Michigan APRIL Lab 提出，并在 2011 年 ICRA 论文AprilTag: A robust and flexible visual fiducial system中系统介绍。它把类似二维码的黑白标签放到环境或物体上，让机器人只通过一帧相机图像就能识别 tag ID，并结合相机内参估计 tag 相对相机的 6D 位姿。

图1 Applications and users of AprilTags，来自AprilTag 2: Efficient and robust fiducial detection。

apriltag_ros是 AprilTag 检测库的 ROS 2 节点封装。它订阅图像和CameraInfo，检测画面中的 AprilTag，然后发布 tag 的 ID、位姿、检测质量信息，以及标准 ROS TF。这样后续节点不需要直接处理图像算法，只要订阅/detections或读取/tf，就可以把 tag 用在定位、标定、导航、抓取、数据集验证等任务里。

本次实验用二进制安装的apriltag_ros做 AprilTag 检测，利用从 Intel RealSense 采集的 rosbag2 数据集回放测试。仓库包含以下内容：

• launch/detector.launch.py：启动上游apriltag_ros/apriltag_node，并把相机话题、参数文件、输出话题做成 launch 参数。
• config/tags_36h11.yaml：默认使用tag36h11，标签边长按0.045 m配置。
• launch/display.launch.py：启动 RViz，并加载rviz/tag_rivz.rviz。

上游apriltag_ros节点订阅 rectified image 和CameraInfo，发布/tf与apriltag_msgs/msg/AprilTagDetectionArray。

1. 安装依赖

以 ROS 2 Humble 为例，先 source ROS 2 环境：

source/opt/ros/humble/setup.bash

安装上游包：

sudoaptupdatesudoaptinstallros-$ROS_DISTRO-apriltag-ros

如果需要重新生成本文使用的 AprilTag 标定板，还需要 Python 依赖：

pip3installopencv-python numpy reportlab

在工作空间根目录构建本 quick start：

mkdir~/ros2_wscd~/ros2_wsgitclone https://gitee.com/jay-tan/robot_mini_projects.gitcdrobot_mini_projects rosdepinstall--from-paths src --ignore-src-r-ycolcon build --symlink-install --packages-select apriltag_ros_quickstartsourceinstall/setup.bash

2. 准备数据集

本项目按 RealSense 采集的数据集（下载链接: https://pan.baidu.com/s/1zePQvusOq-OXeCjO2MszWA?pwd=1024
）来测试, RealSense ROS 2 话题如下：

/camera/camera/color/image_raw -> sensor_msgs/msg/Image /camera/camera/color/camera_info -> sensor_msgs/msg/CameraInfo

apriltag_ros需要图像和CameraInfo的时间戳匹配，camera_info里的相机内参会用于计算 tag pose。拿到数据集后，先检查 bag 里是否包含这两个话题：

ros2 bag info<your_realsense_bag>

如果你的数据集话题名不同，后面启动detector.launch.py时把image_topic和camera_info_topic改成实际话题即可。

3. 实验

3.1 生成 AprilTag 标定板

tools/april_tag_board.py可以生成一张适合 A4 打印的tag36h11AprilTag 标定板。脚本默认生成 3 行 3 列，tag ID 为0到8，每个 tag 下方带有对应 ID 标注。

运行脚本：

cd~/ros2_ws/robot_mini_projects/src/01_apriltag_ros python3 tools/april_tag_board.py

脚本会在当前目录生成：

apriltag_board_A4.pdf apriltag_board_tmp.png

本仓库已经把生成好的文件放在doc/目录中：

doc/apriltag_board_A4.pdf doc/apriltag_board_tmp.png

实际实验时建议打印doc/apriltag_board_A4.pdf，并保持打印比例为 100%。如果修改了脚本里的tag_size、gap、rows、cols等参数，需要同步检查config/tags_36h11.yaml中每个 tag 的尺寸配置，保证检测节点使用的物理尺寸和实际打印尺寸一致。

3.2 回放数据并检测

建议开三个终端：一个回放 RealSense 数据集，一个启动 AprilTag 检测，一个启动 RViz。

终端一，回放数据集：

# 循环播放ros2 bag play rosbag2_2026_05_05-20_41_42_0.db3-l--clock

本文示例数据集文件名为rosbag2_2026_05_05-20_41_42_0.db3，如果使用自己的数据集，请替换为实际 rosbag2 路径。

终端二，启动检测节点：

ros2 launch apriltag_ros_quickstart detector.launch.py\image_topic:=/camera/camera/color/image_raw\camera_info_topic:=/camera/camera/color/camera_info

终端三，启动 RViz。回放 bag 时建议打开仿真时间：

ros2 launch apriltag_ros_quickstart display.launch.py use_sim_time:=true

如果直接接 RealSense 相机实时运行，而不是回放 bag，RViz 可以保持默认：

ros2 launch apriltag_ros_quickstart display.launch.py

4. 验证结果

查看检测数组：

ros2 topicecho/detections

查看 TF。默认 frame 名形如tag36h11:<id>：

ros2 run tf2_ros tf2_echo camera_color_opuical_frame tag36h11:0

图2 运行效果图。

5. 参数说明

这个 quick start 有两层参数：

• launch 参数：控制本 demo 如何把话题和配置文件传给上游节点。
• apriltag_ros参数：写在config/tags_36h11.yaml，控制 AprilTag 检测行为。

5.1 Launch 参数

detector.launch.py参数：

display.launch.py参数：

5.2 YAML 结构

config/tags_36h11.yaml的顶层 key 是apriltag：

apriltag:ros__parameters:family:36h11size:0.045

这个名字要和 launch 文件中启动的节点名一致。本 demo 里节点名是apriltag：

Node(package="apriltag_ros",executable="apriltag_node",name="apriltag",)

如果以后把节点名改成tag_detector，YAML 顶层也要对应改成tag_detector，否则参数不会加载到目标节点。

5.3 基础参数

size是最容易影响结果的参数。只看 2D 检测时它不太敏感，但做定位、抓取、相机外参验证时必须量准，图3中红色箭头即不同 tag 的尺寸位置。

图3 AprilTag size 示意。

这里的size不是整张纸的宽度，也不是白色留边后的外框尺寸，而是 AprilTag 图案本身的边长：从黑色外边框的一侧量到另一侧。实际使用前建议用尺子量打印后的实物尺寸，并把米制数值写入配置，例如 4.5 cm 对应0.045。

5.4 Detector 调参

这些参数位于 YAML 的detector下：

detector:threads:2decimate:1.0blur:0.0refine:truesharpening:0.25debug:false

5.5 指定 tag ID、frame 和尺寸

默认不写tag.ids时，会按检测到的 tag 发布结果。想只关心指定 tag，或给不同 tag 配不同 frame/尺寸，可以加入：

tag:ids:[0,1]frames:[tag_0,tag_1]sizes:[0.162,0.120]

ids、frames、sizes如果同时填写，长度需要一致。只要不同 tag 的真实尺寸不一样，就不要只依赖全局size，应该给每个 ID 单独写tag.sizes。

6. 常见问题

1./detections没有输出怎么办？

先确认图像话题和相机内参话题是否正确：

ros2 topic list ros2 topicecho/camera/camera/color/camera_info--once

然后确认画面中的 tag family 和配置文件里的family一致。例如本文使用的是tag36h11，配置中应为family: 36h11。

2. 能看到图像，但检测不到 tag 怎么办？

优先检查打印质量、光照、运动模糊和 tag 在画面中的大小。远距离或 tag 很小时，可以先把detector.decimate保持为1.0，避免降采样导致漏检。

3. 检测到了 tag，但距离或位姿不准怎么办？

重点检查size。它必须是 AprilTag 黑白图案本身的真实边长，单位是米，不是整张纸的宽度，也不是白色留边后的外框尺寸。打印后建议用尺子重新量一遍。

4. RViz 看不到 TF 怎么办？

回放 rosbag2 时，需要ros2 bag play加--clock，并且 RViz 使用use_sim_time:=true。如果实时接相机运行，则 RViz 可以保持默认的use_sim_time:=false。

5. 公众号或 CSDN 中图片不显示怎么办？

Gitee README 可以直接使用仓库内的相对路径，例如images/the_tag_size.png。发布到 CSDN 或微信公众号时，建议把图片上传到对应平台，再把 Markdown 中的图片链接替换为平台生成的图片地址。

参考

• apriltag_ros官方文档：https://docs.ros.org/en/ros2_packages/humble/api/apriltag_ros/
• apriltag_rosROS Index：https://index.ros.org/p/apriltag_ros/
• apriltag_msgsROS Index：https://index.ros.org/p/apriltag_msgs/
• AprilTag 原始论文：https://april.eecs.umich.edu/papers/details.php?name=olson2011tags
• AprilTag 检测库文档：https://docs.ros.org/en/ros2_packages/rolling/api/apriltag/index.html
• AprilTag 2: Efficient and robust fiducial detectionhttps://april.eecs.umich.edu/pdfs/wang2016iros.pdf
• apriltag_ros githubhttps://github.com/christianrauch/apriltag_ros