rosbag-checker 4.3.0__tar.gz

rosbag_checker-4.3.0/.gitignore

@@ -0,0 +1,65 @@
+# Ignore rosbag data files
+rosbag/
+*.mcap
+*.db3
+rosbag2_*/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# UV/Virtual Environment
+.venv/
+uv.lock
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Reports
+report_*.json
+report_*.html
+
+# Temp files
+.sisyphus/drafts/
+*.tmp
+
+# 生成的报告
+*.html
+
+# Python 缓存
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# 测试缓存
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# 测试数据 (大文件)
+rosbag/
+*.db3
+*.mcap
+
+# 临时文件
+*.log
+*.tmp
+.DS_Store

rosbag_checker-4.3.0/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: rosbag-checker
+Version: 4.3.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.3.0 |
+| **测试框架** | 配置驱动架构 |
+| **测试用例** | 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/
+
+# 查看帮助
+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  
+**项目状态**: 🟢 活跃维护