Metadata-Version: 2.4
Name: rosbag-checker
Version: 4.4.0
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.4.0 |
| **测试框架** | 配置驱动架构 |
| **测试用例** | 124 项 (图像 50 + 运动状态 34 + 运动指令 24 + 传感器 5 + TF 7 + 诊断 5) |
| **性能** | 96MB bag 文件 ~8.6 秒完成检查（启用并行视频解码） |
| **包管理** | 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行配置加载
- ✅ **自动解压缩** - 支持直接处理 `.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 包管理器

```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. 克隆项目并安装依赖（仅源码安装方式需要）

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

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

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

### 3. 选择安装方式

```bash
# 方式 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
```

**升级 / 卸载**：

```bash
# 升级到最新版（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. 运行检查

```bash
# 基本用法 - 检查目录
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`，可在浏览器中打开查看

## ⚙️ 配置文件

### 查看配置文件路径

```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.11
  WARN: true

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

### 添加自定义测试

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

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

## 📊 性能指标

**测试环境**: 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                  # 项目文档
```

## 🔧 高级用法

### 开发环境设置

```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 项)<br>+ 自动解压缩支持 (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](LICENSE) 开源协议。

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

### 技术规范参考

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

---

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