mcap2img 0.1.0__tar.gz

mcap2img-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include mcap2img/pb/proto *.proto

mcap2img-0.1.0/PKG-INFO

@@ -0,0 +1,460 @@
+Metadata-Version: 2.4
+Name: mcap2img
+Version: 0.1.0
+Summary: Export MCAP camera frames to PNG with robot coordinate axis overlays
+Author: Genrobota
+License-Expression: MIT
+Project-URL: Homepage, https://gitee.com/mimidegongkai/mcap2img
+Project-URL: Repository, https://gitee.com/mimidegongkai/mcap2img.git
+Keywords: mcap,robotics,camera,opencv,export
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcap>=1.1.1
+Requires-Dist: av>=12.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: protobuf==4.25.1
+Requires-Dist: scipy>=1.10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# mcap2img
+
+读取本地 MCAP 文件，将 `/robot0/sensor/camera2/compressed` 的每帧解码为 PNG，并在图像上叠加 `/robot1/sim/robot_info` 与 `/robot2/sim/robot_info` 的坐标轴投影。
+
+投影算法与 [web-matrix-monitor](../web-matrix-monitor/src/components/monitor/layout2d/robotAxesVideoOverlay.js) 保持一致。
+
+---
+
+## 安装
+
+### 方式一：pip 安装（推荐）
+
+从 Gitee 仓库安装最新版：
+
+```bash
+pip install git+https://gitee.com/mimidegongkai/mcap2img.git
+```
+
+安装完成后可直接使用 `mcap2img` 命令：
+
+```bash
+mcap2img --input /path/to/bag.mcap --output ./output
+mcap2img --input /path/to/mcap_dir --output ./output
+```
+
+也支持模块方式运行：
+
+```bash
+python -m mcap2img --input /path/to/bag.mcap --output ./output
+```
+
+### 方式二：本地源码开发安装
+
+克隆仓库后，在项目根目录执行：
+
+```bash
+cd mcap2img
+python3.12 -m venv .venv
+source .venv/bin/activate   # Windows: .\.venv\Scripts\Activate.ps1
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+### 方式三：打包分发
+
+维护者可将项目打包为 wheel / sdist，供他人离线安装：
+
+```bash
+pip install build
+python -m build
+pip install dist/mcap2img-0.1.0-py3-none-any.whl
+```
+
+---
+
+## 环境要求
+
+| 项 | 要求 |
+|---|---|
+| Python | **3.10 ~ 3.12**（推荐 **3.12**，已在 3.12.3 验证） |
+| 系统 | macOS / Linux / Windows |
+| 磁盘 | 输出为 PNG，默认仅导出 camera2（约千帧量级） |
+
+> **注意**：Python 3.14 与 protobuf 存在兼容问题，暂不建议使用。请用 `python3.12` 创建虚拟环境。
+
+---
+
+## 一、本地开发环境（可选）
+
+若已用 `pip install -e ".[dev]"` 安装，可跳过本节。否则进入项目目录手动创建虚拟环境：
+
+```bash
+cd /path/to/mcap2img
+```
+
+### macOS / Linux
+
+```bash
+# 推荐指定 3.12
+python3.12 -m venv .venv
+
+# 激活虚拟环境
+source .venv/bin/activate
+
+# 确认当前 Python 版本
+python --version
+# 应显示 Python 3.12.x
+
+# 安装项目及开发依赖
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+### Windows (PowerShell)
+
+```powershell
+cd C:\path\to\mcap2img
+
+py -3.12 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+
+python --version
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+### Windows (CMD)
+
+```cmd
+cd C:\path\to\mcap2img
+
+py -3.12 -m venv .venv
+.venv\Scripts\activate.bat
+
+pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+激活成功后，终端提示符前会出现 `(.venv)`。
+
+---
+
+## 二、运行
+
+### 基本用法（单个 MCAP）
+
+将 MCAP 文件放到 `input/` 目录（或任意路径），然后执行：
+
+```bash
+# 确保虚拟环境已激活
+source .venv/bin/activate   # macOS/Linux
+# 或 .\.venv\Scripts\Activate.ps1   # Windows
+
+python -m mcap2img \
+  --input input/425cb3d4fde94dd6ac03ad9030657a6a-with_gt.mcap \
+  --output output
+
+# 或使用命令行入口
+mcap2img \
+  --input input/425cb3d4fde94dd6ac03ad9030657a6a-with_gt.mcap \
+  --output output
+```
+
+### 批量处理（input 目录下多个 MCAP）
+
+将多个 `.mcap` 文件放入同一目录（例如 `input/`），指定该目录即可批量导出。每个 MCAP 会在 `output/` 下按文件名（不含扩展名）创建子目录：
+
+```bash
+python -m mcap2img \
+  --input input \
+  --output output
+```
+
+例如 `input/a.mcap` 与 `input/b-with_gt.mcap` 会分别输出到：
+
+```
+output/a/camera2/
+output/b-with_gt/camera2/
+```
+
+### 不激活虚拟环境，直接调用
+
+```bash
+# macOS/Linux
+.venv/bin/python -m mcap2img \
+  --input input/your_bag.mcap \
+  --output output
+
+# Windows
+.venv\Scripts\python.exe -m mcap2img ^
+  --input input\your_bag.mcap ^
+  --output output
+```
+
+### 常用示例
+
+**导出多路相机（例如 camera0 与 camera2）：**
+
+```bash
+python -m mcap2img \
+  --input input/your_bag.mcap \
+  --output output \
+  --cameras 0,2
+```
+
+**指定叠加的机器人：**
+
+```bash
+python -m mcap2img \
+  --input input/your_bag.mcap \
+  --output output \
+  --overlay-robots robot1,robot2
+```
+
+**开启详细日志：**
+
+```bash
+python -m mcap2img \
+  --input input/your_bag.mcap \
+  --output output \
+  -v
+```
+
+---
+
+## 三、运行时的进度输出
+
+任务较大时，终端会分两个阶段打印百分比进度：
+
+```
+INFO: Scanning input/your_bag.mcap ...
+INFO: Scanning MCAP: 503/50236 (1%)
+INFO: Scanning MCAP: 10048/50236 (20%)
+...
+INFO: camera2: 1329 frames
+INFO: Exporting 1329 frames across 1 cameras ...
+INFO: Exporting PNG: 80/7983 (1%)
+INFO: Exporting PNG: 1596/7983 (20%)
+...
+INFO: Done: saved=7983 overlay_drawn=7500 overlay_skipped=483 missing_calib=0
+```
+
+- **Scanning MCAP**：读取并解码 MCAP 中的消息
+- **Exporting PNG**：写入 PNG 并绘制坐标轴叠加
+
+---
+
+## 四、输出目录结构
+
+**单个 MCAP：**
+
+```
+output/
+  camera2/
+    1778813410223851000.png    # 文件名为 MCAP log_time（纳秒）
+    1778813410323851000.png
+    ...
+```
+
+**批量处理（`--input input/`）：**
+
+```
+output/
+  425cb3d4fde94dd6ac03ad9030657a6a-with_gt/
+    camera2/
+      1778813410223851000.png
+      ...
+  another_bag/
+    camera2/
+      ...
+```
+
+时间戳与 web-matrix-monitor 播放时间轴一致（使用 MCAP `log_time`，非 `header.timestamp`）。
+
+---
+
+## 五、命令行参数
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--input` | 必填 | 本地 `.mcap` 文件路径，或包含多个 `.mcap` 的目录（批量处理） |
+| `--output` | `./output` | PNG 输出目录 |
+| `--cameras` | `2` | 要导出的相机编号，逗号分隔 |
+| `--overlay-robots` | `robot1,robot2` | 绘制坐标轴的机器人 id |
+| `-v`, `--verbose` | 关闭 | 输出 DEBUG 级别日志 |
+
+---
+
+## 六、退出虚拟环境
+
+```bash
+deactivate
+```
+
+---
+
+## 七、运行测试
+
+```bash
+source .venv/bin/activate
+pip install pytest
+python -m pytest tests/ -v
+```
+
+---
+
+## 八、发布与 CI
+
+### 本地一键发布（推荐）
+
+只需配置一次本地文件（**不会提交到 git**）：
+
+```bash
+cp release.local.env.example release.local.env
+# 编辑 release.local.env，填入 TWINE_PASSWORD
+```
+
+之后每次发布：
+
+```bash
+chmod +x scripts/publish.sh   # 首次
+
+./scripts/publish.sh              # 发布当前版本
+./scripts/publish.sh 0.1.1        # 改版本号并发布
+./scripts/publish.sh --dry-run    # 只测试+打包，不上传
+```
+
+可选：在 `release.local.env` 里设置 `AUTO_GIT_TAG=1`，上传成功后会自动 commit、打 tag 并 push。
+
+### 手动分步发布
+
+```bash
+# 1. 更新版本号
+./scripts/bump_version.sh 0.1.1
+
+# 2. 构建并校验（自动使用 .venv 若存在）
+./scripts/release.sh
+
+# 3. 上传到 PyPI（需先配置 token）
+export TWINE_USERNAME=__token__
+export TWINE_PASSWORD=pypi-xxxxxxxx
+./scripts/release.sh --upload
+
+# 或先上传到 TestPyPI 验证
+./scripts/release.sh --testpypi
+```
+
+### GitHub Actions
+
+仓库已包含：
+
+| 工作流 | 触发条件 | 作用 |
+|--------|----------|------|
+| `.github/workflows/ci.yml` | push / PR 到 `master`/`main` | Python 3.10–3.12 测试 + 打包 |
+| `.github/workflows/publish.yml` | 推送 tag `v*` | 测试通过后发布到 PyPI |
+
+**GitHub 配置：**
+
+1. 在 [PyPI](https://pypi.org/) 创建 API Token
+2. 仓库 Settings → Secrets → `PYPI_API_TOKEN`
+3. （可选）Settings → Environments → 创建 `pypi` 环境并保护发布
+
+**发布流程：**
+
+```bash
+./scripts/bump_version.sh 0.1.1
+git add mcap2img/__init__.py
+git commit -m "release: v0.1.1"
+git tag v0.1.1
+git push origin master --tags
+```
+
+### Gitee Go 流水线
+
+仓库已包含：
+
+| 流水线 | 文件 | 触发条件 |
+|--------|------|----------|
+| CI | `.gitee/pipelines/master.yml` | push / PR 到 `master`/`main` |
+| 发布 | `.gitee/pipelines/release.yml` | 推送 tag `v*` |
+
+**Gitee 配置：**
+
+1. 仓库 → **Gitee Go** → 启用流水线
+2. 导入 `.gitee/pipelines/` 下的 YAML，或同步后自动识别
+3. 流水线 **环境变量 / 凭证** 中添加：
+   - `TWINE_USERNAME` = `__token__`
+   - `TWINE_PASSWORD` = PyPI API Token
+
+推送 tag 后自动构建并上传 PyPI；CI 流水线会在 `dist/` 保留构建产物。
+
+---
+
+## 九、常见问题
+
+### `pip install` 失败 / 找不到 python3.12
+
+```bash
+# macOS (Homebrew)
+brew install python@3.12
+
+# Ubuntu/Debian
+sudo apt install python3.12 python3.12-venv
+```
+
+### `ModuleNotFoundError: No module named 'mcap2img'`
+
+确保在 `mcap2img/` 项目根目录下运行，且使用 `python -m mcap2img`（不要直接 `python mcap2img/cli.py`）。
+
+### 导出很慢
+
+默认仅导出 camera2，扫描 + 导出通常比 6 路全量快很多。如需其他相机，使用 `--cameras` 指定。
+
+### 图像无坐标轴叠加
+
+可能原因：该帧缺少 `camera_info` 或 `robot_info`。程序仍会保存原图，并在最终统计中显示 `overlay_skipped` / `missing_calib` 数量。
+
+### 重新导出前清理旧输出
+
+```bash
+rm -rf output/*
+```
+
+---
+
+## 项目结构
+
+```
+mcap2img/
+├── pyproject.toml      # pip 包配置
+├── MANIFEST.in         # 打包额外文件
+├── scripts/
+│   ├── release.sh      # 本地构建/发布脚本
+│   └── bump_version.sh # 版本号更新脚本
+├── .github/workflows/  # GitHub Actions CI / 发布
+├── .gitee/pipelines/   # Gitee Go CI / 发布
+├── input/              # 放置待处理的 MCAP（已 gitignore）
+├── output/             # 导出结果（已 gitignore）
+├── .venv/              # 虚拟环境（已 gitignore）
+├── mcap2img/
+│   ├── cli.py          # 命令行入口
+│   ├── reader.py       # MCAP 读取与解码
+│   ├── projection.py   # 坐标轴投影
+│   ├── overlay.py      # OpenCV 绘制
+│   └── progress.py     # 进度百分比
+├── tests/
+├── requirements.txt    # 开发说明（依赖见 pyproject.toml）
+└── README.md
+```