rosbag-checker 4.4.0

ROS2 Bag 录制规范检查工具

ROS2 Bag 录制规范检查工具

全面验证 ROS2 bag 录制是否符合飞书文档规范要求的 Python 检查工具。

📊 项目概览

项目	说明
当前版本	v4.4.0
测试框架	配置驱动架构
测试用例	124 项 (图像 50 + 运动状态 34 + 运动指令 24 + 传感器 5 + TF 7 + 诊断 5)
性能	96MB bag 文件 ~8.6 秒完成检查（启用并行视频解码）
包管理	uv (现代化 Python 包管理)
Python 版本	3.10+

---

📖 文档导航

核心文档

• 📘 使用指南 - 快速开始、结果解读、常见问题
• 📋 测试用例文档 - 完整的110+测试用例定义 (P0/P1/P2分级)
• 📊 测试覆盖率分析 - 已实现vs文档定义的对比分析
• 📚 完整文档索引 - 所有文档导航

技术文档

• 🏗️ 测试框架架构 - 测试框架设计说明
• 🔧 测试规范 - 从飞书文档提取的完整规范
• 🚀 开发路线图 - 项目发展规划
• 🔬 ROS2扩展指南 - 高级开发文档

参考

• 🔗 飞书规范文档 - 官方测试规范

🎯 核心特性

配置驱动测试框架

• ✅ YAML 配置驱动 - 无需修改代码即可添加/修改测试
• ✅ 4 种测试状态 - PASS/FAIL/WARN/SKIP，简化状态系统
• ✅ 灵活测试控制 - 每项测试支持独立的 SKIP/WARN 参数配置
• ✅ 代码量大幅减少 - 667行硬编码 → 101行配置加载
• ✅ 自动解压缩 - 支持直接处理 .tar/.tar.gz/.tgz 压缩包，自动清理临时文件

测试覆盖范围 (124 项)

测试类别	测试项数	主要内容
图像数据	50 项	6相机 × 8测试 (帧率/时间戳有效性/单调性/视频质量/K矩阵/畸变/尺寸/frame_id) + 多相机同步 + camera_info同步
运动状态	34 项	joint_states (7) + robot_control_state (23, 含8关节组+4位姿+6力传感器) + xsens (4)
运动指令	24 项	mobile_base_servo_cmd (12, 含速度/标志位/导纳/teleop) + 末端位姿 (4) + 关节组 (8)
传感器数据	5 项	IMU 完整检查（四元数/角速度/加速度/帧率稳定性/时间戳）
TF 坐标变换	7 项	/tf 与 /tf_static 存在性 + TF 树连通性 + 时间戳检查（含单调性）
诊断信息	5 项	/diagnostics 与 /diagnostics_agg ERROR 检测 + /robot_description 存在性

测试结果状态

状态	含义	颜色
✓ PASS	测试完全符合规范	🟢 绿色
✗ FAIL	发现明确问题，需要修复	🔴 红色
⚠ WARN	测试失败但配置为警告级别（不阻塞）	🟡 黄色
○ SKIP	通过配置跳过的测试	⚪ 灰色

🚀 快速开始

1. 安装 uv 包管理器

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或使用 pip
pip install uv

2. 克隆项目并安装依赖（仅源码安装方式需要）

如果你打算用方式 1 (PyPI 安装)，直接跳到步骤 3，不需要克隆源码。

git clone [e-mail]:ad_test/robot-test/rosbag_checker.git
cd rosbag_checker

# 同步依赖并创建虚拟环境
uv sync

3. 选择安装方式

# 方式 1: 从 PyPI 安装（推荐普通用户，最简单）
uv tool install rosbag-checker

# 方式 2: 可编辑安装（推荐开发使用）
uv tool install -e .

# 方式 3: 系统安装（推荐基于源码的个人使用）
uv tool install .

# 方式 4: 打包后安装（推荐分发给他人）
uv build
pip install dist/rosbag_checker-*-py3-none-any.whl

升级 / 卸载：

# 升级到最新版（PyPI）
uv tool upgrade rosbag-checker

# 卸载
uv tool uninstall rosbag-checker

⚠️ 配置文件持久化警告：

安装位置不同时 tests_config.yaml 路径也不同：

安装方式	yaml 路径	重新安装是否覆盖
可编辑安装 (-e)	<源码>/config/tests_config.yaml	否
系统安装 / wheel 安装	$sys.prefix/share/config/tests_config.yaml	是

如果你在装好的位置改了 yaml（如调整阈值），重新执行安装命令时这些改动会被原版覆盖。

推荐做法：

• 在源码 config/tests_config.yaml 改完后再 uv tool install . 重装；或
• 用可编辑安装 uv tool install -e .，改动直接生效，无覆盖风险。

用 rosbag-check --config 可查看当前生效的 yaml 路径。

4. 运行检查

# 基本用法 - 检查目录
rosbag-check /path/to/bag_directory/

# 基本用法 - 直接检查压缩文件（自动解压）
rosbag-check /path/to/rosbag.tar
rosbag-check /path/to/rosbag.tar.gz
rosbag-check /path/to/rosbag.tgz

# 上传 html 文件到 fds
rosbag-check /path/to/bag_directory/ --upload

# 启用性能埋点 (输出阶段耗时与 Top-N 慢测试)
rosbag-check /path/to/bag_directory/ --profile

# 查看帮助
rosbag-check --help

# 查看版本
rosbag-check --version

# 查看配置文件路径
rosbag-check --config

💡 提示: 工具支持自动解压 .tar、.tar.gz、.tgz 格式的压缩包，无需手动解压！

5. 输出示例

=================== ROS2 Bag 检查报告 ===================
📁 Bag: rosbag2_2026_01_22-11_40_19
📊 测试统计:
  ✓ 通过: 85项 (85.0%)
  ✗ 失败: 8项 (8.0%)
  ⚠ 警告: 5项 (5.0%)
  ○ 跳过: 2项 (2.0%)

🎯 综合判定: PASS (警告不阻塞)
📄 HTML报告: complete_test_rosbag2_2026_01_22-11_40_19.html

运行后会自动生成：

• 彩色终端报告 - 实时显示在控制台
• HTML 报告 - 保存为 complete_test_<bag_name>.html，可在浏览器中打开查看

⚙️ 配置文件

查看配置文件路径

rosbag-check --config

输出示例：

测试配置文件路径: /path/to/config/tests_config.yaml
配置文件包含 6 个测试类别:
  - image_tests
  - motion_state_tests
  - motion_command_tests
  - sensor_tests
  - tf_tests
  - diagnostics_tests

修改测试配置

编辑 config/tests_config.yaml 文件（安装后路径见 rosbag-check --config 输出）：

# 跳过某项测试
- id: 1.1.1-wrist_left
  SKIP: true

# 将失败降级为警告（不阻塞整体通过）
- id: 3.2.11
  WARN: true

# 修改测试参数
- id: 2.2.8
  params:
    joint_group: waist
    threshold: 0.1

添加自定义测试

1. 在 config/tests_config.yaml 添加测试配置
2. 指定测试类 (test_class) 和参数 (params)
3. 无需修改代码，配置即生效

详见 测试框架架构文档

📊 性能指标

测试环境: 96MB MCAP 文件，40550 条消息，~80 秒录制（SSD/tmpfs）

指标	数值
测试执行时间	~8.6 秒
测试用例数	124 项
吞吐量	~11 MB/s

性能预估（基于 mcap.get_summary O(1) + topics= 过滤跳读 + VideoclipQuality 并行解码）:

• 小文件 (<100MB): 5-10 秒
• 中等文件 (100MB-1GB): 10-30 秒
• 大文件 (1-10GB): 30 秒-2.5 分钟

💡 用 --profile 选项可输出详细的阶段耗时与 Top-N 慢测试分布，用于诊断瓶颈。

📁 项目结构

rosbag_checker/
├── bin/                        # 可执行脚本
│   └── run_complete_tests.py  # 主测试程序
├── test_framework/             # 测试框架核心
│   ├── test_case.py           # 测试用例基类
│   ├── specialized_tests.py   # 专门测试实现 (~30 个 TestCase 类)
│   ├── protocol_tests.py      # 协议字段测试 (RobotControlState/MobileBaseServoCmd)
│   ├── test_registry.py       # 测试注册表
│   ├── runner.py              # 测试执行引擎 (含并行批处理)
│   └── protocol_loader.py     # 协议加载器
├── validators/                 # 检查器实现
│   ├── tf_checker.py          # TF 树连通性 (主流程使用)
│   ├── diagnostics_checker.py # 诊断 ERROR 检测 (主流程使用)
│   └── ...                    # 其他 11 个 checker (单元测试用)
├── utils/                      # 工具模块
│   ├── paths.py               # 路径解析 (开发/打包模式自动切换)
│   ├── colored_reporter.py    # 彩色终端报告
│   ├── html_reporter.py       # HTML 报告生成
│   ├── config_loader.py       # 配置加载器
│   └── performance.py         # 性能埋点 (--profile)
├── config/                     # 配置文件
│   └── tests_config.yaml      # 测试用例配置 (124 项)
├── docs/                       # 文档目录
├── tests/                      # 测试目录
├── msg/                        # 自定义消息定义
├── pyproject.toml             # 项目配置
├── uv.lock                    # uv 依赖锁文件
└── README.md                  # 项目文档

🔧 高级用法

开发环境设置

# 克隆仓库
git clone [e-mail]:ad_test/robot-test/rosbag_checker.git
cd rosbag_checker

# 安装开发依赖
uv sync --extra dev

# 代码格式化
uv run black .
uv run ruff check .

添加自定义测试

配置驱动方式（推荐）:

1. 在 config/tests_config.yaml 添加测试配置
2. 指定测试类 (test_class) 和参数 (params)
3. 无需修改代码即可生效

代码方式:

1. 在 test_framework/specialized_tests.py 创建新 TestCase 类
2. 实现 run() 方法，返回 TestResult
3. 在 config/tests_config.yaml 注册测试用例

详见 测试框架架构

📚 文档导航

核心文档

• 📘 使用指南 - 快速开始、结果解读、常见问题
• 📋 测试用例文档 - 完整的 110+ 测试用例定义
• 📊 测试覆盖率分析 - 已实现 vs 文档定义对比
• 📚 完整文档索引 - 所有文档导航

技术文档

• 🏗️ 测试框架架构 - 测试框架设计说明
• 🔧 测试规范 - 从飞书文档提取的完整规范
• 🚀 开发路线图 - 项目发展规划
• 🔬 ROS2 扩展指南 - 高级开发文档

参考

• 🔗 飞书规范文档 - 官方测试规范

🐛 常见问题

依赖冲突或环境问题

# 重新同步依赖
uv sync --reinstall

# 清理并重建虚拟环境
rm -rf .venv uv.lock
uv sync

相机帧率不足

问题: videoclip 帧率检查 ✗ - 帧率 1.5 Hz < 29.8 Hz

解决方案:

1. 检查相机驱动配置文件
2. 确认 frame_rate 参数 ≥ 30
3. 重新录制 bag

多相机时间戳不同步

问题: 多相机时间戳同步检查 ✗ - 偏差 201.6ms > 50ms

解决方案:

1. 启用硬件时间同步 (PTP/gPTP)
2. 验证系统 NTP 配置
3. 确认所有相机使用统一时间源

更多问题见 使用指南

🤝 贡献与开发路线图

欢迎提交 Issue 和 Pull Request！

版本历史

版本	状态	主要功能
v3.0	✅	测试框架完整实现 (51 项)
v4.0	✅	测试框架扩展 (78 项)
v4.1	✅	IMU/TF 完整集成 (82 项)
v4.3	✅	camera_info/xsens/TF_static (87 项) + 自动解压缩支持 (tar/tar.gz/tgz)
v4.3.7~14	✅	性能优化批次：read_bag_stats 改 O(1)、TF/Diagnostics 加采样上限、所有 iter_messages 加 topics= 跳读、VideoclipQuality 多进程并行解码、tar.gz 用 pigz 流式解压、新增 --profile 埋点。整体耗时下降 ~65% (24.6s → 8.6s)
v4.3.16~24	✅	YAML 审查与修复：补全 1.1.2/1.1.3 videoclip 时间戳检查、1.1.5 加 wrist 相机、test_id 顺序双修复、2.2/3.1/3.2 重编号消除跳号、删除冗余配置
v4.3.25~29	✅	业务阈值 yaml 化：13 项硬编码阈值改为 yaml 可配置（max_offset_ms/max_linear_velocity/quaternion_tolerance 等），1.1.6 阈值由 10ms 调整到 150ms
v5.0	📋 规划中	visitor 架构接入主流程（已有骨架）+ 大 bag 优化

📄 许可证与致谢

本项目采用 MIT License 开源协议。

感谢所有贡献者对项目的支持！

技术规范参考

• 官方规范: 飞书文档 - ROS2 Bag 录制规范
• 本地规范: ROSBAG_TEST_SPECIFICATION.md

---

维护团队: ROS2 Bag Checker Team
最后更新: 2026-06-02
项目状态: 🟢 活跃维护