🚀 速览与主线流程 >>

• COLMAP = 先稀疏 SfM 求相机位姿与稀疏点，再用 MVS 得到稠密点云/网格。
• GUI 快捷：Reconstruction > Automatic Reconstruction 指定图片目录即可产出稀疏/稠密结果。
• 推荐先跑自动重建看结果，再按需用手动流水线微调参数。

典型输出结构

project/
├─ images/...
├─ database.db
├─ sparse/0/{cameras.bin,images.bin,points3D.bin,...}
└─ dense/0/{images,sparse,stereo,fused.ply,meshed-poisson.ply,meshed-delaunay.ply}

📖 基础概念释义 >>

• 相机(Camera)：同一物理机位/镜头/焦段的内参模型，可对应多张图片。
• 图像(Image)：磁盘上的单张照片；包含外参、关联相机内参。
• 特征/描述子：SIFT 等局部特征；匹配后经几何验证成为 内点匹配。
• SfM：由匹配恢复相机位姿与稀疏 3D 点。
• MVS：在已知位姿上做逐像素深度/法线估计并融合，得到稠密点云/网格。

📷 采集与数据组织 >>

• 保持图片放在单一 images/ 目录（可含子目录）；其他文件分离以免 IO 干扰。
• 拍摄建议：有纹理、光照一致、视角覆盖且有重叠（≥3 张看到同物体）。
• 避免只原地转身拍摄；移动机位获取视差，更利于三角化。
• 用视频帧时可降帧，减少冗余并节省匹配时间。

# 新建项目常见三件套
/path/to/project/
├─ images/          # 原始图
├─ database.db      # SQLite 存特征/匹配
└─ project.ini      # GUI 保存的项目配置，可被 --project_path 复用

🖥️ GUI 快速操作 >>

• File > New project 选图片目录与数据库路径，保存 .ini 便于复用。
• Processing > Extract features：选相机模型，EXIF 自动读焦距，默认即可。
• Processing > Feature matching：按数据量选 Exhaustive/Sequential/Vocab Tree。
• Reconstruction > Start：运行增量 SfM，可在工具栏选择/合并多模型。
• Reconstruction > Multi-view stereo：依次 undistort → stereo → fuse → meshing。
• Processing > Manage database：检查/修改相机分组、匹配质量。

⌨️ CLI 自动/手动流水线 >>

• 自动一键：colmap automatic_reconstructor --workspace_path $DATASET --image_path $DATASET/images
• 手动可控：典型 8 步，便于在中间检查/调参/重跑。

DATASET=/path/to/project

colmap feature_extractor \
  --database_path $DATASET/database.db \
  --image_path $DATASET/images

colmap exhaustive_matcher \
  --database_path $DATASET/database.db

mkdir -p $DATASET/sparse
colmap mapper \
  --database_path $DATASET/database.db \
  --image_path $DATASET/images \
  --output_path $DATASET/sparse

mkdir -p $DATASET/dense
colmap image_undistorter \
  --image_path $DATASET/images \
  --input_path $DATASET/sparse/0 \
  --output_path $DATASET/dense \
  --output_type COLMAP \
  --max_image_size 2000

colmap patch_match_stereo \
  --workspace_path $DATASET/dense \
  --workspace_format COLMAP \
  --PatchMatchStereo.geom_consistency true

colmap stereo_fusion \
  --workspace_path $DATASET/dense \
  --workspace_format COLMAP \
  --input_type geometric \
  --output_path $DATASET/dense/fused.ply

colmap poisson_mesher \
  --input_path $DATASET/dense/fused.ply \
  --output_path $DATASET/dense/meshed-poisson.ply

🔍 特征提取要点 >>

• 默认用 GPU SIFT，服务器无显示可切 CPU；高反差场景 GPU 版质量更好。
• EXIF 缺失时会尝试相机库推断焦距；同机同焦段建议共享内参（single_camera）。
• 导入自有特征：每张图旁边放 .txt，第一行 NUM_FEATURES 128，后续每行 X Y SCALE ORI D1...D128。

4 128
1.2 2.3 0.1 0.3 1 2 ... 21
2.2 3.3 1.1 0.3 3 2 ... 32
0.2 1.3 1.1 0.3 3 2 ... 2
1.2 2.3 1.1 0.3 3 2 ... 3

🤝 特征匹配模式 >>

• Exhaustive：小规模（≤几百张）优先，质量最佳。
• Sequential：视频/序列帧用，含回环检测（需 vocab tree）。
• Vocab Tree：大规模检索式匹配，需预训练树（自动下载或自建）。
• Spatial：用 GPS/手工位置信息选最近邻匹配。
• Transitive：基于已有匹配的传递补全。
• Custom：自定义成对列表或导入匹配（image1.jpg image2.jpg 后跟索引对）。

🕸️ 稀疏重建（SfM） >>

• Reconstruction > Start 或 CLI mapper，增量注册新图并三角化点。
• 若初始化失败，可在 GUI 指定初始成对照片后重跑。
• 多模型输出可用 model_converter 合并；注册率低多半是匹配覆盖不足。
• 优化思路：增加匹配（更高近邻数/回环），或人工剔除模糊/重复图。

🧊 稠密重建（MVS） >>

• 顺序：undistort → stereo → fuse → meshing。
• 若 GPU 显存不足/卡死，调小 --PatchMatchStereo 相关参数或用 FAQ 中的分块策略。
• 法线/网格需外部工具（Meshlab）查看；COLMAP GUI 仅显示点云。
• 导出 PMVS/CMP 等格式：Extras > Undistort images 选择所需格式。

📤 导入导出与格式 >>

• File > Export 导出当前模型；Export all 导出全部组件。
• COLMAP 自身格式（txt/bin）便于继续重建或做 undistort；也支持 PLY/Bundler/VRML。
• File > Import 可重新载入已导出的模型或普通 PLY 点云。
• 格式细节见 Output Format。

🗄️ 数据库管理 >>

• Processing > Manage database 查看/编辑相机、图像、匹配。
• 共享内参：选多图 Set camera，统一 camera_id；prior_focal_length 置 1 表示相信标定焦距。
• 需要批量操作/导入自定义匹配，可直接用 SQLite 操作 database.db。

🛠️ 常见问题与排查 >>

• 程序崩溃/无输出：从命令行启动查看 traceback，并调高 --log_to_stderr 级别。
• 稠密阶段卡死：参考 FAQ freeze / memory，减小分辨率或拆分场景。
• 匹配速度慢：减少图片数（抽帧）、改用 Vocab Tree/Sequential，或调整匹配近邻数。

👁️ 可视化与外部工具 >>

• SfM 点云：GUI 里 File > Import Model 选 cameras.txt / images.txt / points3D.txt 所在目录。
• 稠密点云：File > Import Model from... 选择 fused.ply。
• 网格：meshed-*.ply 需 Meshlab 等外部查看。