Photo2Mesh: COLMAP 插件用户手册

Photo2Mesh: COLMAP - User Manual

Dragonfly Prototype Apps · Photo2Mesh: COLMAP...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

5.1 COLMAP engine（引擎）分组

5.2 Photo input（照片输入）分组

5.3 Options（选项）分组

5.4 运行控制与日志区（右侧）

6. 使用步骤

6.1 工作流 A：从 Dragonfly 图像堆栈重建

6.2 工作流 B：从照片文件夹重建

6.3 取消与作业文件

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Photo2Mesh: COLMAP 是 Dragonfly Prototype Apps 中 Photo2Mesh 系列的三个摄影测量插件之一（另两个是 Photo2Mesh: Meshroom 与 Photo2Mesh: gsplat）。它利用经典的 COLMAP 摄影测量流程，从围绕物体拍摄的一组普通照片重建该物体的三维表面网格，并把结果直接发布为 Dragonfly 场景中的 Mesh 对象。

底层引擎为 COLMAP 4.1.0（插件默认下载的版本，也可在面板中指向其它已安装的 colmap.exe）。重建通过 COLMAP 的 automatic_reconstructor 命令一次性跑完完整流水线：特征提取与特征匹配 → 增量式运动恢复结构（SfM，稀疏重建）→ 图像去畸变 → 稠密 PatchMatch 多视图立体匹配（MVS）→ 立体融合 → 表面网格化（Poisson 或 Delaunay）。COLMAP 是自带全部依赖的独立 Windows 程序，完全在 Dragonfly 进程之外运行；插件只负责准备照片、启动进程、解析进度，并把生成的 meshed-*.ply 网格导入 Dragonfly 并发布。

• 照片来源二选一：Dragonfly 中的活动图像堆栈（每个 Z 切片当作一张照片），或磁盘上的一个照片文件夹（原始拍摄图片）。
• 质量四档（low / medium / high / extreme），网格化方法两种（poisson / delaunay）。
• 稠密重建阶段需要 NVIDIA CUDA 显卡（详见第 4 章）。

许可证要点：COLMAP 采用 BSD-3-Clause 开源许可证，可安全用于商业环境；插件不包含任何非商业授权的组件。

重要：摄影测量重建结果的尺度与方向是任意的（照片本身无法确定绝对尺寸）。如需真实尺寸，请在导入后于 Dragonfly 中对 Mesh 重新缩放、配准。

2. 适用场景

本插件适用于在没有 CT 或激光扫描仪的情况下，仅凭一组照片获得实物的三维表面数字模型，例如：

• 记录与数字化地质或生物标本、化石、工业零件、铸件、考古样品等实物的外表面。
• 生成用于与 CT 数据对比的参考表面。
• 把已有的环拍照片序列（例如转台拍摄）作为图像堆栈载入 Dragonfly 后直接重建。

最适合不透明、纹理丰富且相邻照片重叠充分的物体。透明、强反光或表面缺乏纹理的物体，特征匹配容易失败，重建效果差。

3. 安装与启用

本插件作为 Prototype Labs & Apps Full Package（完整安装包） 的一个组件分发，通过统一安装器安装：

1. 把 Full Package 压缩包解压到任意较短路径（例如 C:\PL\，避免过深的目录导致 Windows 路径过长）。

2. 双击 Install_FullPackage.bat。

3. 在弹出的安装对话框中，于 Prototype Apps 列表里勾选 Photo2Mesh: COLMAP...。注意：所有插件默认不勾选，必须手动勾选本插件。

4. 选择核心安装模式（Fresh 全新 / Compatible 兼容——只影响 Prototype Labs 核心的 blocks 和 recipes，不影响任何插件的环境与设置），点击 Install 并等待安装完成。

5. 完全重启 Dragonfly（彻底退出后重新打开）。

重启后，菜单出现在 Prototype Apps ▸ Photo2Mesh: COLMAP...（位于 Photo2Mesh 分组，与 Meshroom、gsplat 两个同系列插件相邻）。点击菜单项即打开标题为 "Photo2Mesh: COLMAP" 的浮动可停靠面板。

以后随时可以在 Dragonfly 内启用或停用本插件：打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，底部的 "Prototype Apps (Full Package)" 列表中每个应用一个勾选框——勾选 = 部署，取消 = 移除菜单项，重启 Dragonfly 生效。停用从不删除插件已下载的 COLMAP 程序和设置，重新启用即恢复。也可以随时重跑安装器（上次的勾选会成为新的默认值）。

卸载整个 Full Package：双击 Uninstall_FullPackage.bat（%LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer 目录中也保留一份）。卸载会移除所有菜单项和插件，但保留各插件的环境（例如本插件下载的 COLMAP 程序）——结束时会列出这些路径，需要磁盘空间时可手动删除。

菜单只在 Dragonfly 启动时扫描一次：每次启用 / 停用插件后，都需要完全重启 Dragonfly 才会生效。

4. 运行环境与首次配置

本插件没有 Python 虚拟环境、不需要 pip：COLMAP 官方提供自带全部依赖（含 CUDA 支持）的预编译 Windows 发行包，插件直接下载并调用其中的 colmap.exe。安装 Full Package 时不下载任何东西，引擎在首次使用时通过面板上的 Setup / Download COLMAP 按钮配置。

点击 Setup / Download COLMAP 后依次发生：

1. 检查 %LOCALAPPDATA%\Photo2Mesh\COLMAP 下是否已有 colmap.exe；有则直接使用，跳过下载。

2. 否则从 COLMAP 官方 GitHub 发布页下载 COLMAP 4.1.0 Windows CUDA 版压缩包（colmap-x64-windows-cuda.zip，约 1–2 GB，需联网）。下载有进度显示，可用 Cancel 取消。

3. 解压到 %LOCALAPPDATA%\Photo2Mesh\COLMAP 并删除压缩包。

4. 自动定位 colmap.exe，把路径填入面板的 colmap.exe 输入框并保存到配置。

环境要求汇总：

• 联网：仅首次下载 COLMAP 时需要；之后重建本身完全离线运行。
• GPU：稠密 MVS 阶段（PatchMatch 立体匹配）必须有 NVIDIA CUDA 显卡，没有 CPU 回退——无 GPU 无法生成网格。请保持面板中 Use GPU 勾选并使用 CUDA 版 COLMAP。
• 不需要 WSL，不需要管理员权限（一切安装在当前用户目录下）。
• 磁盘：COLMAP 程序本身之外，每次重建还会在作业根目录（默认 C:\Photo2MeshJobs）下产生中间文件。

替代方案：如果本机已装有 COLMAP，可直接用 colmap.exe 输入框旁的 … 按钮指向现有的 colmap.exe，完全不必下载。如果自动下载失败（网络受限等），可以在 Download URL 框中粘贴可达的镜像地址后再点 Setup，或在能联网的电脑上手动下载发行包、解压后把路径指向其中的 colmap.exe。同一发布页还提供无 CUDA 版本（colmap-x64-windows-nocuda.zip），但没有 CUDA 就无法完成稠密重建，通常不建议使用。

面板中的所有设置（引擎路径、输入模式、质量档等）在修改后自动保存到 %LOCALAPPDATA%\Photo2Mesh\colmap_config.json（插件代码文件夹中另存一份副本），下次打开面板自动恢复。

5. 界面说明

面板顶部是一条蓝色说明文字（英文），概述插件功能与 GPU 要求。主体为左右分栏：左侧自上而下三个参数分组——COLMAP engine（引擎）、Photo input（照片输入）、Options（选项）；右侧是运行按钮行、进度条、结果行和实时日志。面板界面语言为英文。

5.1 COLMAP engine（引擎）分组

5.2 Photo input（照片输入）分组

两个单选按钮二选一，决定照片来源：

堆栈模式支持三种通道用法：单个灰度通道（每个切片按 1–99 百分位自动窗宽化为 8 位灰度，再复制为 RGB 三通道）；三个灰度通道分别作 R / G / B 合成一张彩色照片（Green / Blue 与 Red 分辨率不同时自动按最近邻缩放对齐）；单个自带多分量（RGB 彩色）的通道直接按彩色使用。

5.3 Options（选项）分组

• Job root：作业根目录。每次重建在其下新建一个以时间戳命名的作业文件夹，存放导出帧和 COLMAP 工作区。
• Quality：COLMAP 质量档（low / medium / high / extreme），档位越高细节越多、耗时越长。
• Mesher：网格化方法。poisson 生成水密封闭曲面（可能过度封闭凹陷处）；delaunay 更贴合实测点云（表面可能有孔洞）。
• Use GPU (CUDA) — required for dense MVS（复选框）：GPU 开关。稠密 MVS 阶段必须 CUDA GPU，请保持勾选。
• Max frame size (stack only, px)（数字框）：堆栈模式导出帧的最长边像素上限，超过则等比缩小；仅堆栈模式生效，照片文件夹模式不受影响。

各项默认值见第 7 章参数表。

5.4 运行控制与日志区（右侧）

6. 使用步骤

两条端到端工作流，区别只在照片来源；COLMAP 流水线与网格导入部分完全相同。

6.1 工作流 A：从 Dragonfly 图像堆栈重建

输入要求：一个已加载的 Channel，其 Z 方向切片是围绕物体不同角度拍摄的照片序列（至少 3 张，实际应远多于 3 张且相邻重叠充分）；灰度或彩色均可。

1. 在 Dragonfly 中把照片序列载入为图像堆栈 Channel。

2. 打开 Prototype Apps ▸ Photo2Mesh: COLMAP...。

3. 首次使用：点击 Setup / Download COLMAP，等待日志显示 "COLMAP ready"（详见第 4 章）。

4. 选中 Active image stack 单选；点击 Refresh，在 Red / primary 中选择该 Channel（若照片由三个灰度通道组成，再在 Green / Blue 中选择另外两个通道）。

5. 按需调整 Quality / Mesher / Use GPU / Max frame size。

6. 点击 Reconstruct Mesh。面板先把每个切片导出为 frame_0000.png、frame_0001.png… 存入作业文件夹的 images 子目录（少于 3 帧会报错终止），随后启动 COLMAP 完整流水线。

7. 观察进度条与日志。单个物体的重建通常为分钟级，随 Quality 档提高而变长。

8. 完成后网格自动导入并发布为名为 Photo2Mesh_COLMAP_<时分秒> 的 Mesh；结果行显示顶点数与面数。

6.2 工作流 B：从照片文件夹重建

输入要求：一个包含原始照片的文件夹。照片按原样直接交给 COLMAP（不缩放、不转换）。拍摄建议：围绕物体多角度环拍、相邻照片重叠充分、物体不透明且纹理丰富、对焦清晰。

1. 打开面板（首次先完成 Setup）。

2. 选中 Photos folder (original images) 单选，用 … 按钮选择照片所在文件夹。

3. 按需调整 Options（注意 Max frame size 在此模式下不生效）。

4. 点击 Reconstruct Mesh，其余流程与工作流 A 第 7–8 步相同。

6.3 取消与作业文件

• 运行中随时可点 Cancel 请求取消：COLMAP 子进程被终止，结果行显示 cancelled。
• 每次重建在 <Job root>\<YYYYMMDD_HHMMSS>\ 下留下 images（堆栈模式的导出帧）与 workspace（COLMAP 的稀疏 / 稠密中间结果和最终网格）。
• 点 Open Job Folder 直接打开该文件夹。插件不会自动清理旧作业，需要磁盘空间时请手动删除。

7. 参数说明

8. 输出结果

Dragonfly 中：重建成功后自动生成一个已发布（published）的 Mesh 对象，名为 Photo2Mesh_COLMAP_<时分秒>，出现在对象列表中，可像任何 Mesh 一样在 3D 视图中显示、测量或导出。导入优先使用 Dragonfly 原生网格加载器（一次调用、快速稳健）；该加载器不可用时自动退回逐顶点重建（大网格会明显较慢）。结果行同时显示顶点数与面数。

磁盘上（作业文件夹，可用 Open Job Folder 打开）：

• <Job root>\<时间戳>\images\frame_####.png —— 堆栈模式导出的 RGB 帧（照片文件夹模式无此目录，直接使用原照片）。
• <Job root>\<时间戳>\workspace\ —— COLMAP 工作区，含稀疏模型与稠密重建的中间结果。
• workspace\dense\<i>\meshed-poisson.ply 或 meshed-delaunay.ply —— 最终表面网格文件；导入 Dragonfly 的就是它。

网格的尺度与方向是任意的：做尺寸测量前，请先依据已知尺寸对 Mesh 进行缩放与配准。

9. 常见问题与故障排除

问：点了 Setup，下载失败怎么办？

答：日志会显示 "Download failed"。先检查网络；或在 Download URL 中粘贴可达的镜像地址后重试；也可以在能联网的电脑上手动下载 COLMAP 发行包，解压后用 colmap.exe 输入框旁的 … 按钮直接指向其中的 colmap.exe——路径会被记住，之后无需再 Setup。

问：Red / primary 下拉列表是空的。

答：点击 Refresh 重新扫描，并确认 Dragonfly 中已加载至少一个 Channel。下拉列出的是当前会话中的所有 Channel。

问：报错 "need >= 3 photos; stack has N slice(s)"。

答：所选通道的 Z 切片少于 3 张，无法进行多视角重建。请确认选择的是照片序列堆栈而不是单张图像；实际重建需要数量充足、重叠充分的多角度照片。

问：COLMAP 跑完了，却报 "colmap finished but no meshed-*.ply found"。

答：最常见原因是稠密阶段（PatchMatch MVS）没有可用的 NVIDIA CUDA 显卡——该阶段没有 CPU 回退，没有 GPU 就不会生成网格。请确认本机有 NVIDIA 显卡、使用的是 CUDA 版 COLMAP、且 Use GPU 保持勾选，然后在日志中查看 dense / meshing 阶段的具体报错。

问：报 "colmap exited with code N"。

答：COLMAP 进程自身失败，完整原因在右侧日志里。常见诱因是照片之间重叠不足、纹理太少或反光 / 透明导致特征匹配失败；请改善拍摄（更多角度、更充分的重叠、漫射光照、不透明表面）后重试。

问：导入的网格尺寸 / 方向不对。

答：这是摄影测量的固有特性——照片无法确定绝对尺度和方向，重建结果的尺度与朝向是任意的。请依据已知尺寸的特征在 Dragonfly 中对 Mesh 进行缩放和旋转配准。

问：Mesher 该选 poisson 还是 delaunay？

答：poisson 生成水密封闭曲面，适合需要封闭表面的后续分析，但可能把凹陷处"封"起来；delaunay 更贴合实测点云、细节更忠实，但表面可能留有孔洞。默认 poisson；两种都可以尝试，作业文件夹中会保留各自的输出。

10. 注意事项与已知限制

• 重建结果的尺度与方向是任意的，如需真实尺寸必须在导入后重新缩放。
• 稠密 MVS 必须 NVIDIA CUDA 显卡，没有 CPU 回退；无 GPU 时无法得到网格。
• 最适合不透明、纹理丰富、重叠充分的照片；透明、强反光或无纹理表面效果差。
• 单个物体的重建通常为分钟级，耗时随 Quality 档提高而增加。
• Poisson 网格可能过度封闭（把凹陷封住）；Delaunay 网格可能有孔洞。
• 作业文件夹（默认 C:\Photo2MeshJobs）不会自动清理，稠密重建的中间文件可能占用较多磁盘空间，请定期手动删除旧作业。
• 首次 Setup 需联网下载约 1–2 GB；此后重建全程离线。
• 面板界面语言为英文。
• 启用 / 停用菜单项后必须完全重启 Dragonfly 才生效。

11. 参考资料

• COLMAP 项目主页（源码与文档）：https://github.com/colmap/colmap
• COLMAP Windows 发行版下载页：https://github.com/colmap/colmap/releases —— 插件默认使用 4.1.0 版的 colmap-x64-windows-cuda.zip（同页另有无 CUDA 的 colmap-x64-windows-nocuda.zip）。
• COLMAP 许可证：BSD-3-Clause（可商用）。
• 同系列插件：Photo2Mesh: Meshroom、Photo2Mesh: gsplat（均位于 Prototype Apps 菜单的 Photo2Mesh 分组）。

Part II English Manual

Contents

1. Overview

2. Typical use cases

3. Installation and enabling

4. Runtime environment and first-time setup

5. User interface

5.1 COLMAP engine group

5.2 Photo input group

5.3 Options group

5.4 Run controls and log (right pane)

6. Step-by-step usage

6.1 Workflow A: reconstruct from a Dragonfly image stack

6.2 Workflow B: reconstruct from a photos folder

6.3 Cancelling and job files

7. Parameter reference

8. Outputs

9. FAQ and troubleshooting

10. Notes and known limitations

11. References

1. Overview

Photo2Mesh: COLMAP is one of the three photogrammetry plugins in the Photo2Mesh family of Dragonfly Prototype Apps (the other two are Photo2Mesh: Meshroom and Photo2Mesh: gsplat). It reconstructs a 3D surface mesh of a physical object from a series of ordinary photos taken around it, using the classical COLMAP photogrammetry pipeline, and publishes the result directly as a Mesh object in the Dragonfly scene.

The underlying engine is COLMAP 4.1.0 (the version the plugin downloads by default; you can also point the panel at any other installed colmap.exe). Reconstruction runs COLMAP's automatic_reconstructor command, which executes the full pipeline in one go: feature extraction and matching → incremental structure-from-motion (SfM, sparse reconstruction) → image undistortion → dense PatchMatch multi-view stereo (MVS) → stereo fusion → surface meshing (Poisson or Delaunay). COLMAP is a self-contained Windows binary that runs entirely outside the Dragonfly process; the plugin only prepares the photos, launches the process, parses its progress, and imports the resulting meshed-*.ply mesh into Dragonfly as a published Mesh.

• Two photo sources: the active image stack in Dragonfly (each Z-slice treated as one photo) or a folder of original photo files on disk.
• Four quality levels (low / medium / high / extreme) and two meshing methods (poisson / delaunay).
• The dense reconstruction stage requires an NVIDIA CUDA GPU (see Chapter 4).

Licensing: COLMAP is released under the BSD-3-Clause open-source license and is safe for commercial use; the plugin contains no non-commercial components.

Important: photogrammetric reconstructions have arbitrary scale and orientation (photos alone cannot determine absolute dimensions). If real-world dimensions matter, rescale and register the mesh in Dragonfly after import.

2. Typical use cases

Use this plugin whenever you want a digital 3D surface model of a physical object without a CT or laser scanner, for example:

• Documenting and digitizing the outer surface of geological or biological specimens, fossils, industrial parts, casts, or archaeological samples.
• Creating reference surfaces to compare against CT data.
• Reconstructing directly from an existing turntable-style photo sequence loaded into Dragonfly as an image stack.

It works best on opaque, well-textured objects photographed with good overlap between neighbouring shots. Transparent, highly reflective, or texture-poor surfaces make feature matching fail and reconstruct poorly.

3. Installation and enabling

The plugin is distributed as a component of the Prototype Labs & Apps Full Package and is installed through its unified installer:

1. Unzip the Full Package archive to any short path (e.g. C:\PL\; avoid deep folders that can trigger the Windows path-length limit).

2. Double-click Install_FullPackage.bat.

3. In the installer dialog, tick Photo2Mesh: COLMAP... in the Prototype Apps list. Note: all plugins are unticked by default, so you must tick this one explicitly.

4. Choose the core install mode (Fresh / Compatible — this affects only the Prototype Labs core blocks and recipes, never any plugin's environment or settings), click Install, and wait for it to finish.

5. Fully restart Dragonfly (quit completely, then reopen).

After the restart, the menu entry appears at Prototype Apps ▸ Photo2Mesh: COLMAP... (in the Photo2Mesh group, next to the sibling Meshroom and gsplat plugins). Clicking it opens a floating, dockable panel titled "Photo2Mesh: COLMAP".

You can enable or disable the plugin later from inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager — the "Prototype Apps (Full Package)" list at the bottom has one checkbox per app. Tick = deploy, untick = remove the menu entry; restart Dragonfly to apply. Disabling never deletes the plugin's downloaded COLMAP engine or settings — re-enabling restores it instantly. You can also re-run the installer at any time (your previous choices become the new defaults).

To uninstall the whole Full Package, double-click Uninstall_FullPackage.bat (a copy is kept in %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer). It removes all menu items and plugins but keeps every plugin environment (such as this plugin's downloaded COLMAP binaries) — their paths are listed at the end so you can delete them manually to reclaim disk space.

Menus are discovered only at Dragonfly startup: every enable/disable change requires one full Dragonfly restart to take effect.

4. Runtime environment and first-time setup

This plugin has no Python virtual environment and needs no pip: COLMAP ships an official self-contained prebuilt Windows release (with CUDA support), and the plugin simply downloads it and calls its colmap.exe. Nothing is downloaded when the Full Package is installed — the engine is provisioned on first use via the Setup / Download COLMAP button on the panel.

Clicking Setup / Download COLMAP does the following, in order:

1. Checks whether colmap.exe already exists under %LOCALAPPDATA%\Photo2Mesh\COLMAP; if so, it is used directly and the download is skipped.

2. Otherwise downloads the COLMAP 4.1.0 Windows CUDA release zip (colmap-x64-windows-cuda.zip, roughly 1–2 GB, internet required) from the official COLMAP GitHub releases page, with progress display; the download can be cancelled with Cancel.

3. Extracts it under %LOCALAPPDATA%\Photo2Mesh\COLMAP and deletes the zip.

4. Locates colmap.exe automatically, fills its path into the colmap.exe field, and saves it to the configuration.

Environment requirements at a glance:

• Internet: needed only for the one-time COLMAP download; reconstruction itself runs fully offline afterwards.
• GPU: the dense MVS stage (PatchMatch stereo) requires an NVIDIA CUDA GPU — there is no CPU fallback; without a GPU no mesh can be produced. Keep Use GPU ticked and use the CUDA build.
• No WSL and no administrator rights are needed (everything installs under the current user profile).
• Disk: besides the COLMAP binaries, each reconstruction leaves intermediate files under the job root (default C:\Photo2MeshJobs).

Alternatives: if COLMAP is already installed on this machine, use the … button next to the colmap.exe field to point directly at the existing colmap.exe — no download needed. If the automatic download fails (restricted network etc.), paste a reachable mirror URL into Download URL and click Setup again, or download the release zip manually on another machine, extract it, and point the field at its colmap.exe. The same releases page also offers a no-CUDA build (colmap-x64-windows-nocuda.zip), but without CUDA the dense reconstruction cannot complete, so it is generally not recommended.

All panel settings (engine path, input mode, quality, etc.) are saved automatically after each change to %LOCALAPPDATA%\Photo2Mesh\colmap_config.json (with a second copy in the plugin's code folder) and restored the next time the panel opens.

5. User interface

The top of the panel shows a blue note summarizing what the plugin does and its GPU requirement. The body is a two-pane layout: the left pane holds three parameter groups from top to bottom — COLMAP engine, Photo input, and Options; the right pane holds the run buttons, a progress bar, a result line, and the live log.

5.1 COLMAP engine group

5.2 Photo input group

Two mutually exclusive radio buttons choose the photo source:

Stack mode supports three channel configurations: a single grayscale channel (each slice is auto-windowed to 8-bit at the 1st–99th percentile and replicated to RGB); three grayscale channels composed as R / G / B into one colour photo per slice (Green / Blue are resized to Red's resolution with nearest-neighbour interpolation if they differ); or a single multi-component (RGB colour) channel, used directly as colour.

5.3 Options group

• Job root: the job root directory. Each reconstruction creates a new timestamped job folder under it for the exported frames and the COLMAP workspace.
• Quality: the COLMAP quality preset (low / medium / high / extreme); higher presets give more detail and take longer.
• Mesher: the meshing method. poisson produces a watertight closed surface (may over-close concavities); delaunay hugs the measured points more closely (may leave holes).
• Use GPU (CUDA) — required for dense MVS (checkbox): the GPU switch. The dense MVS stage requires a CUDA GPU, so keep it ticked.
• Max frame size (stack only, px) (spin box): upper limit on the longest side of frames exported in stack mode; larger frames are downscaled proportionally. Has no effect in photos-folder mode.

See the parameter table in Chapter 7 for all default values.

5.4 Run controls and log (right pane)

6. Step-by-step usage

There are two end-to-end workflows; they differ only in the photo source — the COLMAP pipeline and the mesh import are identical.

6.1 Workflow A: reconstruct from a Dragonfly image stack

Input requirement: a loaded Channel whose Z-slices are a photo sequence taken around the object from different angles (at least 3 photos, in practice far more, with good overlap between neighbouring shots); grayscale or colour.

1. Load the photo sequence into Dragonfly as an image-stack Channel.

2. Open Prototype Apps ▸ Photo2Mesh: COLMAP....

3. First time only: click Setup / Download COLMAP and wait until the log reports "COLMAP ready" (see Chapter 4).

4. Select the Active image stack radio button; click Refresh and pick the Channel in Red / primary (if the photos are stored as three grayscale channels, also set Green and Blue).

5. Adjust Quality / Mesher / Use GPU / Max frame size as needed.

6. Click Reconstruct Mesh. The panel first exports each slice as frame_0000.png, frame_0001.png, … into the job folder's images subfolder (fewer than 3 frames aborts with an error), then launches the full COLMAP pipeline.

7. Watch the progress bar and the log. A typical per-object run takes minutes and grows with the Quality preset.

8. When finished, the mesh is imported and published automatically as a Mesh named Photo2Mesh_COLMAP_<HHMMSS>; the result line shows its vertex and face counts.

6.2 Workflow B: reconstruct from a photos folder

Input requirement: a folder containing the original photos. They are handed to COLMAP as-is (no resizing, no conversion). Shooting advice: orbit the object from many angles, keep generous overlap between neighbouring shots, prefer opaque and well-textured objects, and keep the photos in focus.

1. Open the panel (complete Setup first if this is the first use).

2. Select the Photos folder (original images) radio button and choose the folder with the … button.

3. Adjust the Options as needed (note that Max frame size has no effect in this mode).

4. Click Reconstruct Mesh; the rest is identical to steps 7–8 of Workflow A.

6.3 Cancelling and job files

• Click Cancel at any time while running: the COLMAP subprocess is terminated and the result line reports cancelled.
• Each reconstruction leaves <Job root>\<YYYYMMDD_HHMMSS>\ containing images (frames exported in stack mode) and workspace (COLMAP's sparse/dense intermediates and the final mesh).
• Open Job Folder opens that folder directly. Old jobs are never cleaned up automatically — delete them manually to reclaim disk space.

7. Parameter reference

8. Outputs

In Dragonfly: a successful reconstruction creates a published Mesh object named Photo2Mesh_COLMAP_<HHMMSS>. It appears in the object list and can be displayed in the 3D view, measured, or exported like any other Mesh. Import prefers Dragonfly's native mesh loader (one fast, robust call); if that loader is unavailable it falls back to a per-vertex rebuild (noticeably slower for very large meshes). The result line also shows the vertex and face counts.

On disk (the job folder, reachable via Open Job Folder):

• <Job root>\<timestamp>\images\frame_####.png — the RGB frames exported in stack mode (absent in photos-folder mode, which uses the originals directly).
• <Job root>\<timestamp>\workspace\ — the COLMAP workspace with the sparse model and dense-reconstruction intermediates.
• workspace\dense\<i>\meshed-poisson.ply or meshed-delaunay.ply — the final surface-mesh file; this is what gets imported into Dragonfly.

The mesh has arbitrary scale and orientation: rescale and register it before taking dimensional measurements.

9. FAQ and troubleshooting

Q: I clicked Setup and the download failed.

A: The log shows "Download failed". Check your network first; or paste a reachable mirror address into Download URL and retry. You can also download the release zip manually on a machine with internet access, extract it, and use the … button next to the colmap.exe field to point directly at its colmap.exe — the path is remembered and Setup is no longer needed.

Q: The Red / primary dropdown is empty.

A: Click Refresh to re-scan, and make sure at least one Channel is loaded in Dragonfly. The dropdown lists all Channels in the current session.

Q: Error "need >= 3 photos; stack has N slice(s)".

A: The selected channel has fewer than 3 Z-slices, which is not enough for multi-view reconstruction. Make sure you selected the photo-sequence stack rather than a single image; a real reconstruction needs plenty of well-overlapping views.

Q: COLMAP finished but reports "colmap finished but no meshed-*.ply found".

A: The most common cause is that the dense stage (PatchMatch MVS) had no usable NVIDIA CUDA GPU — that stage has no CPU fallback, so without a GPU no mesh is produced. Verify the machine has an NVIDIA GPU, that you are using the CUDA build of COLMAP, and that Use GPU is ticked; then check the log around the dense/meshing stage for the specific error.

Q: Error "colmap exited with code N".

A: The COLMAP process itself failed; the full reason is in the log on the right. Frequent triggers are insufficient overlap between photos, too little texture, or reflective/transparent surfaces breaking feature matching. Improve the capture (more angles, more overlap, diffuse lighting, opaque surfaces) and retry.

Q: The imported mesh has the wrong size or orientation.

A: This is inherent to photogrammetry — photos cannot determine absolute scale or orientation, so the reconstruction's scale and pose are arbitrary. Rescale and rotate the Mesh in Dragonfly against features of known size.

Q: Should I pick poisson or delaunay?

A: poisson yields a watertight closed surface — good when a closed surface is needed downstream, but it may "seal over" concavities; delaunay follows the measured points more faithfully but may leave holes. The default is poisson; feel free to try both — each run's output stays in its job folder.

10. Notes and known limitations

• Reconstructions have arbitrary scale and orientation; rescale after import whenever real dimensions matter.
• Dense MVS requires an NVIDIA CUDA GPU with no CPU fallback; without a GPU no mesh can be produced.
• Best results on opaque, well-textured objects with generous photo overlap; transparent, reflective, or textureless surfaces reconstruct poorly.
• A per-object run typically takes minutes and grows with the Quality preset.
• Poisson meshes may over-close concavities; Delaunay meshes may contain holes.
• Job folders (default C:\Photo2MeshJobs) are never cleaned up automatically; dense-reconstruction intermediates can use considerable disk space — delete old jobs manually.
• The first Setup downloads roughly 1–2 GB and needs internet; everything afterwards runs offline.
• The panel UI is in English.
• Enabling/disabling the menu entry requires a full Dragonfly restart.

11. References

• COLMAP project home (source and documentation): https://github.com/colmap/colmap
• COLMAP Windows release downloads: https://github.com/colmap/colmap/releases — the plugin defaults to colmap-x64-windows-cuda.zip of version 4.1.0 (a no-CUDA colmap-x64-windows-nocuda.zip is on the same page).
• COLMAP license: BSD-3-Clause (commercial use permitted).
• Sibling plugins: Photo2Mesh: Meshroom and Photo2Mesh: gsplat (both in the Photo2Mesh group of the Prototype Apps menu).