mcap2img 0.1.0

Export MCAP camera frames to PNG with robot coordinate axis overlays

mcap2img

读取本地 MCAP 文件，将 /robot0/sensor/camera2/compressed 的每帧解码为 PNG，并在图像上叠加 /robot1/sim/robot_info 与 /robot2/sim/robot_info 的坐标轴投影。

投影算法与 web-matrix-monitor 保持一致。

---

安装

方式一：pip 安装（推荐）

从 Gitee 仓库安装最新版：

pip install git+https://gitee.com/mimidegongkai/mcap2img.git

安装完成后可直接使用 mcap2img 命令：

mcap2img --input /path/to/bag.mcap --output ./output
mcap2img --input /path/to/mcap_dir --output ./output

也支持模块方式运行：

python -m mcap2img --input /path/to/bag.mcap --output ./output

方式二：本地源码开发安装

克隆仓库后，在项目根目录执行：

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，供他人离线安装：

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]" 安装，可跳过本节。否则进入项目目录手动创建虚拟环境：

cd /path/to/mcap2img

macOS / Linux

# 推荐指定 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)

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)

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/ 目录（或任意路径），然后执行：

# 确保虚拟环境已激活
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/ 下按文件名（不含扩展名）创建子目录：

python -m mcap2img \
  --input input \
  --output output

例如 input/a.mcap 与 input/b-with_gt.mcap 会分别输出到：

output/a/camera2/
output/b-with_gt/camera2/

不激活虚拟环境，直接调用

# 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）：

python -m mcap2img \
  --input input/your_bag.mcap \
  --output output \
  --cameras 0,2

指定叠加的机器人：

python -m mcap2img \
  --input input/your_bag.mcap \
  --output output \
  --overlay-robots robot1,robot2

开启详细日志：

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 级别日志

---

六、退出虚拟环境

deactivate

---

七、运行测试

source .venv/bin/activate
pip install pytest
python -m pytest tests/ -v

---

八、发布与 CI

本地一键发布（推荐）

只需配置一次本地文件（不会提交到 git）：

cp release.local.env.example release.local.env
# 编辑 release.local.env，填入 TWINE_PASSWORD

之后每次发布：

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。

手动分步发布

# 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 创建 API Token
2. 仓库 Settings → Secrets → PYPI_API_TOKEN
3. （可选）Settings → Environments → 创建 pypi 环境并保护发布

发布流程：

./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

# 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 数量。

重新导出前清理旧输出

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