# 20 · ros2 bag 录制与回放 完全指南

> **目标**: 掌握 ros2 bag 命令行,能录制 topic、回放、调试、训练数据采集。

---

## 目录

- [1. 是什么](#1-是什么)
- [2. 录制 topic](#2-录制-topic)
- [3. 回放 topic](#3-回放-topic)
- [4. 查看包信息](#4-查看包信息)
- [5. 转换格式](#5-转换格式)
- [6. QoS 与 bag](#6-qos-与-bag)
- [7. VLA 训练数据采集](#7-vla-训练数据采集)
- [8. 推荐阅读](#8-推荐阅读)

---

## 1. 是什么

**ros2 bag** = ROS2 自带的 topic 录制 / 回放工具,生成 `.db3` (SQLite) 文件 + `metadata.yaml`。

用途:
- 调试:录一段数据,反复回放调试算法
- 测试:用录的数据做单元测试
- 训练:VLA / 机器学习数据采集
- 回归:确保算法在新数据上仍 work

## 2. 录制 topic

```bash
# 录制所有 topic
ros2 bag record -a -o my_bag

# 录制指定 topic
ros2 bag record /chatter /tf /joint_states -o my_bag

# 指定压缩格式
ros2 bag record /chatter -o my_bag --compression-mode file --compression-format zstd

# 限制时长
ros2 bag record /chatter -o my_bag --duration 30  # 30 秒

# 限制大小
ros2 bag record /chatter -o my_bag --max-bag-size 100000000  # 100 MB

# 排除 topic
ros2 bag record -a -o my_bag --exclude "/_.*"
```

输出:

```
my_bag/
├── metadata.yaml
└── my_bag_0.db3
```

## 3. 回放 topic

```bash
# 回放(需要原始节点还在,否则消息无 subscriber)
ros2 bag play my_bag

# 循环回放
ros2 bag play my_bag --loop

# 调整速率(2 倍速)
ros2 bag play my_bag --rate 2.0

# 从中间开始
ros2 bag play my_bag --start-offset 10  # 10 秒处开始

# 延迟发布
ros2 bag play my_bag --delay 1.0  # 每条消息延迟 1 秒
```

## 4. 查看包信息

```bash
# 概览
ros2 bag info my_bag

# YAML 格式详情
ros2 bag info my_bag --yaml

# 单个 topic 详情
ros2 bag info my_bag -t /chatter
```

输出:

```
Files:             my_bag_0.db3
Bag size:          1.2 MiB
Storage id:        sqlite3
Duration:          10.05s
Start:             Aug  4 2026 14:00:00.123
End:               Aug  4 2026 14:00:10.123
Messages:          100
Topic information: MessageType       Count
                  std_msgs/String   100
```

## 5. 转换格式

### 导出元数据 YAML

```bash
ros2 bag info my_bag --yaml > my_bag_info.yaml
```

### 用 rosbags 库(Python)

```python
from rosbags.rosbag2 import Reader

with Reader('my_bag') as reader:
    for msg in reader.messages():
        topic = msg.topic
        timestamp = msg.timestamp
        data = msg.message
        ...
```

## 6. QoS 与 bag

**关键**: 回放时 subscriber 的 QoS 必须 **兼容** publisher 的 QoS(录制时的 QoS)。

```bash
# 默认 bag 会用 RELIABLE 录制,如果你用 BEST_EFFORT subscriber,会报错
# 解决:用 --qos-profile-overrides 覆盖回放 QoS
ros2 bag play my_bag --qos-profile-overrides-path qos_override.yaml
```

`qos_override.yaml`:

```yaml
/chatter:
  reliability: best_effort
  history: keep_last
  depth: 1
```

## 7. VLA 训练数据采集

OpenVLA / π0 等模型需要大量 (image, instruction, action) 三元组。ROS2 bag 录制:

```bash
# 录制图像 + 关节 + 指令
ros2 bag record \
  /camera/color/image_raw \
  /camera/depth/color/points \
  /joint_states \
  /ee_pose \
  /task_instruction \
  -o vla_episode_001
```

回放 + 转 VLA 训练格式:

```python
from rosbags.rosbag2 import Reader
from cv_bridge import CvBridge
import numpy as np

bridge = CvBridge()
samples = []

with Reader('vla_episode_001') as reader:
    for msg in reader.messages():
        if msg.topic == '/camera/color/image_raw':
            image = bridge.imgmsg_to_cv2(msg.message, 'bgr8')
            samples.append({'image': image, 'timestamp': msg.timestamp})
```

## 8. 推荐阅读

- [ROS2 bag 命令行](https://docs.ros.org/en/humble/Tutorials/Beginner-Client-Libraries/Recording-And-Playing-Back-Data.html)
- [rosbags Python 库](https://github.com/idx-lab/rosbags)
- [Foxglove Studio(可视化 bag)](https://studio.foxglove.dev/)

---

---

## 📖 阅读路径导航

> 💡 这是仓库 `doc/` 下所有文档的推荐阅读顺序。[返回 README 总导航](../README.md#-23-篇文档怎么读)
>
> ⏱ **本文预计阅读时间**: 20 分钟
> 📍 **当前位置**: 第 12 / 24 篇

- ⏮ **上一篇**: [Topic pub/sub 深度](20-topics.md)
- ⏭ **下一篇**: [DDS 配置 + colcon overlay](21-overlay-dds.md)