Metadata-Version: 2.4
Name: rosbag-checker
Version: 4.3.1
Summary: ROS2 Bag 录制规范检查工具
Author: ROS2 Bag Checker Team
License: MIT
Keywords: ros2,rosbag,testing,validation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: av>=10.0.0
Requires-Dist: galaxy-fds-sdk>=1.4.44
Requires-Dist: mcap>=1.0.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: rosbags>=0.10.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# ROS2 Bag 录制规范检查工具

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

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
[![ROS2](https://img.shields.io/badge/ROS2-Humble%2B-orange.svg)](https://docs.ros.org/)
[![uv](https://img.shields.io/badge/uv-enabled-green.svg)](https://github.com/astral-sh/uv)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

## 📊 项目概览

| 项目 | 说明 |
|------|------|
| **当前版本** | v4.3.1 |
| **测试框架** | 配置驱动架构 |
| **测试用例** | 100+ 项 (图像 36 + 运动状态 34 + 运动指令 24 + 传感器 5 + TF 7 + 诊断 5) |
| **性能** | 20秒 bag 文件 ~10秒 完成检查 |
| **包管理** | uv (现代化 Python 包管理) |
| **Python 版本** | 3.10+ |

---

## 📖 文档导航

### 核心文档
- 📘 **[使用指南](docs/guides/USAGE_GUIDE.md)** - 快速开始、结果解读、常见问题
- 📋 **[测试用例文档](docs/specs/test_cases.md)** - 完整的110+测试用例定义 (P0/P1/P2分级)
- 📊 **[测试覆盖率分析](docs/specs/TEST_COVERAGE_ANALYSIS.md)** - 已实现vs文档定义的对比分析
- 📚 **[完整文档索引](docs/DOCS_INDEX.md)** - 所有文档导航

### 技术文档
- 🏗️ **[测试框架架构](docs/architecture/NEW_FRAMEWORK_SUMMARY.md)** - 测试框架设计说明
- 🔧 **[测试规范](docs/specs/ROSBAG_TEST_SPECIFICATION.md)** - 从飞书文档提取的完整规范
- 🚀 **[开发路线图](docs/development/ROADMAP.md)** - 项目发展规划
- 🔬 **[ROS2扩展指南](docs/development/ROS2_EXTENSION_GUIDE.md)** - 高级开发文档

### 参考
- 🔗 **[飞书规范文档](https://mi.feishu.cn/wiki/QZ44wwD1KiNWlukOSWrcSekxnlc)** - 官方测试规范

## 🎯 核心特性

### 配置驱动测试框架

- ✅ **YAML 配置驱动** - 无需修改代码即可添加/修改测试
- ✅ **4 种测试状态** - PASS/FAIL/WARN/SKIP，简化状态系统
- ✅ **灵活测试控制** - 每项测试支持独立的 `SKIP`/`WARN` 参数配置
- ✅ **代码量大幅减少** - 667行硬编码 → 101行配置加载

### 测试覆盖范围 (100+ 项)

| 测试类别 | 测试项数 | 主要内容 |
|---------|---------|---------|
| **图像数据** | 36 项 | 6相机 × 6测试 (帧率/质量/camera_info/时间戳同步等) |
| **运动状态** | 34 项 | joint_states + robot_control_state(8关节组) + 位姿(4组) + 力传感器(6组) + xsens |
| **运动指令** | 24 项 | mobile_base_servo_cmd 末端执行器(4组) + 关节(8组) + 导纳控制(左右2项) |
| **传感器数据** | 5 项 | IMU 完整检查（时间戳/角速度/加速度/四元数/帧率稳定性） |
| **TF 坐标变换** | 7 项 | /tf 存在性/时间戳有效性 + TF 树连通性 + /tf_static 完整性 |
| **诊断信息** | 5 项 | diagnostics ERROR 检测 + robot_description |

### 测试结果状态

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

## 🚀 快速开始

### 1. 安装 uv 包管理器

```bash
# 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. 克隆项目并安装依赖

```bash
git clone git@git.n.xiaomi.com:ad_test/robot-test/rosbag_checker.git
cd rosbag_checker

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

### 3. 选择安装方式

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

# 方式 2: 系统安装（推荐个人使用）
uv tool install .

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

### 4. 运行检查

```bash
# 基本用法
rosbag-check /path/to/bag_directory/

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

# 查看帮助
rosbag-check --help

# 查看版本
rosbag-check --version

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

### 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`，可在浏览器中打开查看

## ⚙️ 配置文件

### 查看配置文件路径

```bash
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` 输出）：

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

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

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

### 添加自定义测试

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

详见 [测试框架架构文档](docs/architecture/NEW_FRAMEWORK_SUMMARY.md)

## 📊 性能指标

**测试环境**: 73MB MCAP 文件，24634 条消息，20 秒录制

| 指标 | 数值 |
|------|------|
| 测试执行时间 | ~10 秒 |
| 测试用例数 | 100+ 项 |
| 吞吐量 | ~7.3 MB/s |

**性能预估**:
- 小文件 (<100MB): 5-15 秒
- 中等文件 (100-500MB): 15-60 秒
- 大文件 (>500MB): 60-180 秒

## 📁 项目结构

```
rosbag_checker/
├── bin/                        # 可执行脚本
│   └── run_complete_tests.py  # 主测试程序
├── test_framework/             # 测试框架核心
│   ├── test_case.py           # 测试用例基类
│   ├── specialized_tests.py   # 专门测试实现
│   ├── test_registry.py       # 测试注册表
│   ├── runner.py              # 测试执行引擎
│   └── protocol_loader.py     # 协议加载器
├── validators/                 # 检查器实现 (14个)
│   ├── videoclip_checker.py
│   ├── camera_info_checker.py
│   ├── joint_states_checker.py
│   ├── robot_control_state_checker.py
│   ├── mobile_base_servo_cmd_checker.py
│   ├── imu_checker.py
│   ├── xsens_checker.py
│   ├── tf_checker.py
│   └── diagnostics_checker.py
├── utils/                      # 工具模块
│   ├── bag_reader.py          # MCAP 读取封装
│   ├── colored_reporter.py    # 彩色终端报告
│   ├── html_reporter.py       # HTML 报告生成
│   └── config_loader.py       # 配置加载器
├── config/                     # 配置文件
│   └── tests_config.yaml      # 测试用例配置 (100+ 项)
├── docs/                       # 文档目录
├── tests/                      # 测试目录
├── msg/                        # 自定义消息定义
├── pyproject.toml             # 项目配置
├── uv.lock                    # uv 依赖锁文件
└── README.md                  # 项目文档
```

## 🔧 高级用法

### 开发环境设置

```bash
# 克隆仓库
git clone git@git.n.xiaomi.com: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` 注册测试用例

详见 [测试框架架构](docs/architecture/NEW_FRAMEWORK_SUMMARY.md)

## 📚 文档导航

### 核心文档
- 📘 [使用指南](docs/guides/USAGE_GUIDE.md) - 快速开始、结果解读、常见问题
- 📋 [测试用例文档](docs/specs/test_cases.md) - 完整的 110+ 测试用例定义
- 📊 [测试覆盖率分析](docs/specs/TEST_COVERAGE_ANALYSIS.md) - 已实现 vs 文档定义对比
- 📚 [完整文档索引](docs/DOCS_INDEX.md) - 所有文档导航

### 技术文档
- 🏗️ [测试框架架构](docs/architecture/NEW_FRAMEWORK_SUMMARY.md) - 测试框架设计说明
- 🔧 [测试规范](docs/specs/ROSBAG_TEST_SPECIFICATION.md) - 从飞书文档提取的完整规范
- 🚀 [开发路线图](docs/development/ROADMAP.md) - 项目发展规划
- 🔬 [ROS2 扩展指南](docs/development/ROS2_EXTENSION_GUIDE.md) - 高级开发文档

### 参考
- 🔗 [飞书规范文档](https://mi.feishu.cn/wiki/QZ44wwD1KiNWlukOSWrcSekxnlc) - 官方测试规范

## 🐛 常见问题

### 依赖冲突或环境问题

```bash
# 重新同步依赖
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. 确认所有相机使用统一时间源

更多问题见 [使用指南](docs/guides/USAGE_GUIDE.md)

## 🤝 贡献与开发路线图

欢迎提交 Issue 和 Pull Request！

### 版本历史

| 版本 | 状态 | 主要功能 |
|------|------|---------|
| v3.0 | ✅ | 测试框架完整实现 (51 项) |
| v4.0 | ✅ | 测试框架扩展 (78 项) |
| v4.1 | ✅ | IMU/TF 完整集成 (82 项) |
| v4.3 | ✅ | camera_info/xsens/TF_static (87 项) |
| v5.0 | ✅ | 配置驱动框架 (100+ 项)<br>- 667行硬编码 → 101行配置<br>- 4种状态系统<br>- SKIP/WARN 灵活控制 |
| v5.1 | 📋 计划中 | 补全所有关节组和传感器测试 |
| v6.0 | 🚀 规划中 | 性能优化 + 测试报告增强 |

## 📄 许可证与致谢

本项目采用 [MIT License](LICENSE) 开源协议。

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

### 技术规范参考

- **官方规范**: [飞书文档 - ROS2 Bag 录制规范](https://mi.feishu.cn/wiki/QZ44wwD1KiNWlukOSWrcSekxnlc)
- **本地规范**: [ROSBAG_TEST_SPECIFICATION.md](docs/specs/ROSBAG_TEST_SPECIFICATION.md)

---

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