如何 10 分钟跑通 Brainmu-SpikeCamera:CPU 轻量环境下的脉冲相机影像重建快速上手教程
如何 10 分钟跑通 Brainmu-SpikeCamera:CPU 轻量环境下的脉冲相机影像重建快速上手教程
Brainmu-SpikeCamera 是北京大学余肇飞团队与北京智源人工智能研究院(BAAI)联合推出的脉冲相机影像重建研究项目:它能把脉冲(事件)相机采集的 DAT 数据流重建为清晰的自然图像。本教程将带你用仅 18 万参数的小网络,在 CPU 轻量环境下 10 分钟内跑通脉冲相机影像重建推理,无需 GPU。
一、30 秒了解 Brainmu-SpikeCamera 📦
脉冲相机(Spike Camera)以极高的时间分辨率捕捉场景中的亮度变化,输出的是一串二值"脉冲"事件,而非传统帧图像。Brainmu-SpikeCamera 分两个阶段处理这些数据:
| 阶段 | 说明 | 硬件要求 |
|---|---|---|
| ① 卷积重建前端(SpikeConvFrontend) | 180,705 参数的小网络,直接把脉冲流映射为图像 | CPU 即可 |
| ② Brainμ 生成阶段(可选) | 大模型 + LoRA 微调做精细重建 | 需 NVIDIA GPU,权重暂未发布 |
本教程聚焦阶段 ①:它是发布包里开箱即用的部分,根目录的 config.json(网络结构与输入规格)和 model.safetensors(小网络权重)都已就绪。
二、动手前:先认识数据格式
推理脚本对输入有严格的格式约定,提前确认可以少走弯路:
- 脉冲数据:
*.dat文件,每条包含41 × 250 × 400的二值序列(little-bit 打包,共 512,500 字节),读取时会沿高度方向翻转; - 真值图像(可选):与 DAT 同名的 PNG,尺寸为
400 × 250。提供后才会计算 PSNR/SSIM 指标; - 网络结构与输入参数均由 config.json 声明,权重加载时会校验 SHA256,见 src/code/project_config.py。
三、第一步:搭建 CPU 轻量环境(约 3 分钟)⏱️
完整 GPU 环境需要 PyTorch + FlashAttention,编译较重;而小网络推理只需要 CPU 版 PyTorch,依赖极其精简(完整说明见 src/USAGE.md)。
1. 获取代码
git clone https://gitcode.com/BAAI/Brainmu-SpikeCamera
cd Brainmu-SpikeCamera
2. 创建虚拟环境并安装依赖(需已安装 uv,Python 3.12)
uv venv --python 3.12 .venv
source .venv/bin/activate
# CPU 版 PyTorch + 四个轻量依赖
uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install numpy==1.26.4 opencv-python-headless==4.11.0.86 Pillow==11.3.0 safetensors==0.4.5
Windows PowerShell 用户将激活命令换为 .\.venv\Scripts\Activate.ps1。到这里,CPU 轻量环境就完成了——比完整 GPU 环境少了 FlashAttention、transformers 等一长串依赖(见 src/requirements.txt)。
四、第二步:运行脉冲相机影像重建推理(约 2 分钟)
在仓库根目录执行 src/scripts/infer_frontend.py:
python src/scripts/infer_frontend.py \
--spike-dir /path/to/spike \
--gt-dir /path/to/gt \
--output-dir outputs/frontend_test \
--device cpu
常用参数一览(src/scripts/infer_frontend.py):
| 参数 | 必填 | 说明 |
|---|---|---|
--spike-dir |
✅ | DAT 文件所在目录 |
--gt-dir |
❌ | 同名 GT PNG 目录,省略则只出图、不算指标 |
--output-dir |
✅ | 输出目录,必须是不存在的空目录 |
--device |
❌ | 默认 cpu,有 GPU 可写 cuda:0 |
--limit 3 |
❌ | 只跑排序后的前 3 张,快速试错 |
--config / --checkpoint |
❌ | 默认读根目录的 config.json 与 model.safetensors |
💡 建议:第一次运行加上 --limit 3,几秒内即可验证环境是否配置正确,再跑完整数据集。
五、第三步:查看重建结果 📊
脚本完成后会在输出目录生成三类内容:
| 文件 | 内容 |
|---|---|
prediction/*.png |
每张 DAT 对应的重建灰度图像 |
metrics.csv |
逐样本的 PSNR / SSIM(提供 GT 时) |
metrics.json |
运行状态、完成数量与平均指标 |
看到终端输出 COMPLETE 3/3; frontend only; output: ...,且 metrics.json 中 status 为 complete,即代表 10 分钟跑通成功!
六、进阶:完整 GPU 流程与网页演示 🔍
小网络只是"前端"。若你准备了基础大模型 + LoRA 权重(暂未随仓库发布),并拥有 NVIDIA GPU,可以走完整重建与评测流程:
# 1. 搭建完整环境(Python 3.12 + CUDA 13.0 + FlashAttention)
bash src/scripts/setup_uv.sh
# 2. 完整推理与评测(默认 1,000 对数据)
CUDA_VISIBLE_DEVICES=0 bash src/scripts/test.sh \
--model-path /path/to/base_model \
--adapter /path/to/adapter.safetensors \
--frontend "$PWD/model.safetensors" \
--spike-dir /path/to/test/spike \
--gt-dir /path/to/test/gt \
--output-dir "$PWD/outputs/test1000"
此外,项目还内置网页演示(src/ui/,支持 1/2/4/8 卡调度):激活 src/.venv 后执行 bash src/scripts/start_ui.sh,打开 http://127.0.0.1:8997 即可在浏览器里加载权重、跑评测。远程部署请通过 SSH 端口转发访问,界面没有用户认证,不要直接暴露公网。
七、常见问题快速解答 ❓
- 报错 "Use a new output directory":输出目录已存在,换一个空目录即可(程序刻意禁止覆盖旧结果)。
- 报错 "Default checkpoint SHA256 mismatch":
model.safetensors损坏或不完整,重新获取仓库。 - 报错 "No DAT files found":检查
--spike-dir路径,目录下需直接包含*.dat文件。 - 报错 "GT size mismatch":GT 必须与预测尺寸一致(400 × 250),且文件名与 DAT 同名。
- CPU 上跑得慢?:属正常现象,先用
--limit 3验证流程;完整数据集建议用 GPU。
八、文件资料速查 📁
| 资料 | 说明 |
|---|---|
| README.md | 项目总览与环境安装 |
| src/USAGE.md | CPU 轻量环境安装与推理说明 |
| config.json / model.safetensors | 小网络结构与权重 |
| src/scripts/infer_frontend.py | 本教程使用的 CPU 推理入口 |
| src/scripts/setup_uv.sh | 完整 GPU 环境安装脚本 |
| src/scripts/test.sh | 完整流程评测入口 |
| src/code/ | 训练、微调与数据导出代码 |
| src/ui/ | 网页演示与多 GPU 调度 |
从 git clone 到看到第一张重建图像,整个过程只需要一条轻量安装命令和一条推理命令。掌握这套流程后,你便拥有了继续探索事件相机影像重建的起点——祝实验顺利!