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
```
