· 6 min read
项目：COLMAP Forge，把视频和照片整理成 COLMAP 可以直接吃的数据
三维重建真正难的部分往往不在 SfM 本身，而在喂给它的数据。一段手机录的视频要抽成多少帧？4K 原图要不要先缩小？街景里的行人、车辆、天空、水面会产生大量错误匹配，要不要先遮掉？相机模型选哪个？每个问题都不难，但每次都要写一遍脚本，而且把掩膜正确写进 COLMAP 数据库这一步很容易踩坑。
COLMAP Forge 把这些步骤串成一个向导：加入视频或图片文件夹，一路往下点，最后得到一个 database.db 和一组掩膜图像，直接接 COLMAP 的特征提取与匹配。它既有 PyQt6 图形界面，也有不依赖 Qt 的命令行模式，可以放进脚本和 CI。
安装
项目用 uv 管理依赖，Python 3.11 以上：
git clone https://github.com/Vincentqyw/colmapforge.git
cd colmapforge
uv sync --extra cpu # CPU 版 ONNX Runtime，所有平台可用，macOS 自带 CoreML 加速
uv run colmapforge # 启动图形界面Linux 或 Windows 上有 NVIDIA 显卡的话改用 uv sync --extra gpu，会装上 CUDA 版的 ONNX Runtime（Linux 连 cuDNN 9 一起由 pip 带上，Windows 需要系统安装 CUDA 13 与 cuDNN 9）。两个 wheel 共用同一个模块名，只能装其中一个。程序会按 CUDA、CoreML、CPU 的顺序自动选择后端，工具栏上的指示灯显示当前用的是哪个。
Releases 页面还有 Linux、macOS、Windows 的打包版本，不想装 Python 的话直接下载即可。
六步流程
- 输入：添加视频文件和/或图片目录，两者可以混用。
- 抽帧：三种策略。每隔 N 帧取一帧；按目标帧率取；或者按运动量取，用稠密光流跟踪一组网格点，只有当相机移动得足够多（累计位移的 80 分位数超过阈值）、视野内剩余的跟踪点太少、或者间隔超过上限时才写出一帧。静止的片段不会产生重复帧，快速平移时帧会自动变密。
- 缩放：按最长边或固定倍数下采样。
- 分割：给动态物体和无纹理区域打掩膜，模型见下一节。
- 相机：从 COLMAP 的 18 种相机模型里选，默认 SIMPLE_RADIAL。EQUIRECTANGULAR 全景相机会按 COLMAP 的球面相机定义正确写入宽高参数。
- 构建：一键导出
database.db和掩膜图像。
四个阶段通过 QThreadPool 异步串联，界面不会卡死。右侧的预览面板实时叠加掩膜，透明度可调。
生成的数据库使用 COLMAP 3.12 / 4.x 的新 schema，包括 rigs、frames、pose_priors 等表，已经用 COLMAP 4.2 走通了「Forge 数据库、ALIKED 提取、LightGlue 匹配、mapper」的完整流程，全部图像注册成功。
分割模型
所有模型都是 ONNX 格式，首次使用时自动下载到 ~/.colmapforge/models/，下载校验 SHA256，支持 Hugging Face 镜像。
| 模型 | 提示方式 | 大小 |
|---|---|---|
| SkyWater SegFormer-B2（FP16） | 固定类别：天空、水面、人 | 约 48 MB |
| YOLO-World + MobileSAM | 文字提示（检测框再分割） | 约 720 MB |
| YOLO-World + SAM2.1-Tiny | 文字提示 | 约 835 MB |
| YOLO-World + EfficientViT-SAM-L0 | 文字提示，CUDA 上最快 | 约 815 MB |
| YOLO-World + EdgeTAM | 文字提示，Apple Silicon 上最快 | 约 715 MB |
| SAM3 ViT-H | 文字提示，直接送入原生文本编码器 | 约 3.0 GB |
选择的原则很简单：
- 只需要遮掉天空和水面，用 SkyWater，又小又快。它是笔者另一个项目，专门为重建前处理训练的 SegFormer。
- 需要按类别名遮掉行人、车辆等任意物体，用 YOLO-World + SAM 级联：YOLO-World 做开放词汇检测，再由一个轻量 SAM 对每个框出掩膜。一次检测就能处理任意多个类别。
- 对掩膜质量要求最高、而且有大显存 GPU，用 SAM3。它把类别名直接作为文本提示，但每个类别都要跑一遍解码器，类别越多越慢。
速度
在一段真实的 360° 街景序列上（79 帧 960×480 等距柱状图像，ONNX Runtime 1.28，默认的「All Dynamics」16 类预设）测得的稳态单帧耗时：
| 模型 | M4 Pro（秒/帧） | RTX 5090（秒/帧） | 加速比 |
|---|---|---|---|
| SkyWater SegFormer-B2 | 0.074 | 0.007 | 11× |
| YOLO-World + EdgeTAM | 0.85 | 0.053 | 16× |
| YOLO-World + EfficientViT-SAM-L0 | 1.10 | 0.025 | 44× |
| YOLO-World + MobileSAM | 1.26 | 0.039 | 32× |
| YOLO-World + SAM2.1-Tiny | 1.59 | 0.068 | 23× |
| SAM3 ViT-H | 15.84 | 0.659 | 24× |
SAM3 在 M4 Pro 上把类别减到 2 个大约是 7 秒一帧。日常用笔记本处理几百帧视频，YOLO-World + EdgeTAM 是比较舒服的选择。
命令行
colmapforge run（别名 cmf）跑完整流程，不需要 Qt：
# 只有图片，不做分割
uv run colmapforge run -o out/ --image-dir photos/
# 视频 → 最长边缩到 2000 → SkyWater 遮天空和水面 → 数据库
uv run colmapforge run -o out/ --video vid.mp4 --resize \
--resize-mode max_dim --resize-max-dim 2000 \
--seg-model skywater_segformer_b2_fp16 --seg-classes sky water
# SAM3 文字提示
uv run colmapforge run -o out/ --video vid.mp4 \
--seg-model sam3_vit_h_20260220 --seg-classes person car \
--seg-confidence 0.4
# 按运动量抽帧
uv run colmapforge run -o out/ --video vid.mp4 --extract-method motion
# 列出可用模型 / 相机模型，预先下载模型
uv run colmapforge run --list-models
uv run colmapforge run --list-cameras
uv run colmapforge download --all图形界面里常用的快捷键：Ctrl+O 添加图片，Ctrl+B 构建数据库，Ctrl+T 切换深浅色主题。
小结
COLMAP Forge 不做重建本身，只负责把数据准备到「COLMAP 一跑就对」的状态。配合 COLMAP Sparse Viewer 查看结果、Omni-SfM 处理全景视频，就是笔者目前日常重建的一套工具链。MIT 许可，欢迎反馈。