Photo2Mesh: Meshroom 插件用户手册

Photo2Mesh: Meshroom - User Manual

Dragonfly Prototype Apps · Photo2Mesh: Meshroom...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Photo2Mesh: Meshroom 是 Dragonfly Prototype Apps 中 Photo2Mesh 系列插件之一。它使用经典的 Meshroom / AliceVision 摄影测量（photogrammetry）流程，从一组普通多角度照片重建真实物体的三维表面网格（带纹理），并把结果直接作为 Dragonfly Mesh 对象发布到当前场景中。

照片来源有两种：既可以选择已加载到 Dragonfly 中的图像堆栈（Channel，每个 Z 切片作为一张照片），也可以直接指定一个照片文件夹（使用原始全分辨率照片，质量最佳）。点击 Reconstruct Mesh 后，插件在 Dragonfly 之外启动 Meshroom 的命令行程序 meshroom_batch，依次完成特征提取、稀疏重建（SfM）、稠密重建（MVS）、网格化与纹理贴图，最后把生成的 OBJ 网格导入并发布为 Dragonfly Mesh。

底层引擎：Meshroom 官方 Windows 发行版 2023.3.0（自带 Python 运行时和 AliceVision CUDA 二进制，完全独立，无需在 Dragonfly 端安装任何 pip 包）。许可证：Meshroom / AliceVision 采用 MPL-2.0 许可证，可安全用于商业环境。

重要：摄影测量重建结果的尺度和朝向是任意的（没有真实物理单位），导入后请根据需要在 Dragonfly 中自行缩放和摆正。不透明、纹理丰富且照片重叠度高的物体重建效果最佳。

2. 适用场景

本插件适用于无需 CT 扫描即可获得实物三维数字模型的各种场合，例如：

• 数字化地质标本或生物标本，建立三维数字档案；
• 存档工业零件、失效样品的外观形貌；
• 将物体的外表面网格与其 CT 扫描获得的内部结构在同一场景中对比；
• 为可视化、教学和演示制作带纹理的网格模型；
• 对已经以图像堆栈形式载入 Dragonfly 的环拍序列直接做三维重建。

3. 安装与启用

本插件通过 Prototype Labs & Apps 完整安装包（Full Package）安装：

1. 将安装包 zip 解压到任意较短路径（如 C:\PL\，避免过深的目录导致 Windows 260 字符路径限制）。

2. 双击 `Install_FullPackage.bat` 启动安装器。

3. 在弹出的组件列表中勾选 Photo2Mesh: Meshroom...。注意：所有插件默认不勾选，必须手动勾选才会安装。

4. 点击 Install，等待控制台完成。

5. 完全退出并重启 Dragonfly（菜单只在启动时扫描一次）。

重启后，菜单项出现在 Prototype Apps ▸ Photo2Mesh: Meshroom...（位于 Photo2Mesh 分组中）。点击后打开一个可停靠的浮动面板（标题为 Photo2Mesh: Meshroom）。

以后启用 / 停用：打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，在底部 "Prototype Apps (Full Package)" 列表中勾选或取消勾选本插件，重启 Dragonfly 生效。停用不会删除已下载的 Meshroom 引擎，重新启用后立即可用。也可以随时重跑安装器（%LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat），上次的选择会作为默认值。

卸载：双击 Uninstall_FullPackage.bat 移除所有 Full Package 菜单项与插件；已下载的 Meshroom 引擎（约 2 GB）会保留在 %LOCALAPPDATA%\Photo2Mesh\Meshroom，卸载结束时会列出该路径，需要腾出磁盘空间时可手动删除。

整个安装是针对当前用户的（%LOCALAPPDATA%），不需要管理员权限。

4. 运行环境与首次配置

本插件的引擎属于 binary_download（二进制下载）类型：Meshroom 官方发行版自带全部运行时，不需要建立 Python venv，也不需要 pip 安装任何包，更不需要 WSL。Dragonfly 端只负责把它作为外部子进程启动。

4.1 首次配置（Setup / Download Meshroom）

1. 打开面板，在 Meshroom engine 组中点击 Setup / Download Meshroom 按钮。

2. 插件先在 %LOCALAPPDATA%\Photo2Mesh\Meshroom 下查找已有的 meshroom_batch.exe；若找到则直接使用，不重复下载。

3. 若未找到，则从官方 GitHub 发布页下载 Meshroom 2023.3.0 win64 zip（约 2 GB），日志区实时显示下载进度（已下载 / 总 MB 数），下载完成后自动解压到上述目录并删除 zip 包。

4. 成功后 meshroom_batch 输入框自动填入 meshroom_batch.exe 的完整路径，并写入配置文件，下次打开面板自动恢复。

默认下载地址为 https://github.com/alicevision/Meshroom/releases/download/v2023.3.0/Meshroom-2023.3.0-win64.zip。如果下载源不可达，可在 Download URL 输入框填入自定义镜像地址后再点 Setup；也可以完全跳过下载——如果本机已装有 Meshroom，直接用 meshroom_batch 输入框旁的 … 按钮浏览到现有安装中的 meshroom_batch.exe 即可。下载过程中可点 Cancel 中止。

4.2 硬件与网络要求

• 联网：仅首次下载 Meshroom 时需要（约 2 GB）；之后重建过程完全离线。
• GPU：需要一块 NVIDIA CUDA 显卡——Meshroom 的稠密深度图（DepthMap）阶段必须使用 CUDA。
• WSL：不需要。
• 磁盘：引擎约 2 GB；每次重建作业还会在作业目录下产生图像帧、缓存（MeshroomCache）和输出网格。

4.3 相关路径

5. 界面说明

面板为左右分栏布局：顶部是一条蓝色说明文字（概述功能与注意事项）；左侧是可滚动的设置区，从上到下包含 Meshroom engine、Photo input、Options 三个分组；右侧是运行控制区（按钮行、进度条、结果提示和日志窗口）。

5.1 Meshroom engine（引擎）组

• meshroom_batch：meshroom_batch.exe 的完整路径。通常由 Setup 自动填写；也可点旁边的 … 按钮手动浏览选择（占位提示：path to meshroom_batch.exe (set by Setup)）。
• Download URL：Meshroom Windows 发行版 zip 的下载地址；留空即使用官方默认地址（Meshroom 2023.3.0 win64）。
• Setup / Download Meshroom 按钮：定位或下载引擎，见第 4 章。

5.2 Photo input（照片输入）组

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

• Active image stack (each slice = one photo)（默认选中）：使用已加载的图像堆栈 Channel，每个 Z 切片导出为一张照片。下方有三个 Channel 下拉框：Red / primary（必选，主通道）、Green (optional) 与 Blue (optional)（均默认 (none)）。只选一个灰度通道时，灰度会自动复制为 RGB；同时选择 Green/Blue 可把三个灰度通道逐切片合成为 RGB 彩色照片；如果 Red 本身就是一个多分量 RGB 彩色通道，则直接按彩色使用。Refresh 按钮重新扫描当前场景中的全部 Channel 并刷新三个下拉框。
• Photos folder (original images)：指定一个包含原始全分辨率照片的文件夹（点 … 浏览），照片按原样直接送入 Meshroom，画质最佳。

5.3 Options（选项）组

• Job root：作业根目录，默认 C:\Photo2MeshJobs。每次重建在其下新建一个以时间戳命名的作业文件夹。
• Pipeline：下拉选择 photogrammetry（默认，标准完整重建管线）或 draft（传给 meshroom_batch --pipeline 的草稿管线，速度更快）。
• Max frame size (stack only, px)：数值框，范围 512–8192，步进 256，默认 2400。仅对图像堆栈模式生效：导出的照片帧最长边超过该值时按比例缩小。

5.4 运行控制区（右侧）

• Reconstruct Mesh（蓝色按钮）：开始整个重建流程。
• Cancel：请求取消当前的下载或重建（运行中才可点击）。
• Open Job Folder：在 Windows 资源管理器中打开最近一次作业文件夹（若尚无作业则打开作业根目录）。
• 进度条：0–100%，根据 Meshroom 的处理节点（CameraInit、FeatureExtraction、…、Texturing 等）粗略推进。
• 结果提示行：显示当前阶段或最终结果（如 Done. Mesh: N verts, M faces (published).）。
• Log：只读日志窗口，逐行转发 meshroom_batch 的输出以及插件自身的状态信息，是排错的第一手资料。

6. 使用步骤

6.1 工作流 A：从已加载的图像堆栈重建

1. 拍摄一组围绕物体的多角度照片（相邻照片之间保证充分重叠），并将其作为图像堆栈载入 Dragonfly（成为一个 Channel）。

2. 打开 Prototype Apps ▸ Photo2Mesh: Meshroom...；首次使用先完成第 4 章的 Setup。

3. 在 Photo input 组保持选中 Active image stack，点 Refresh，在 Red / primary 下拉框中选中该图像堆栈。灰度堆栈无需再选 Green/Blue；若照片以 R/G/B 三个灰度通道分开加载，则分别在三个下拉框中选择。

4. 按需调整 Options（作业目录、管线、最大帧尺寸）。

5. 点击 Reconstruct Mesh。插件先把每个切片导出为 RGB PNG 帧（frame_0000.png 起，堆栈至少需要 3 个切片），然后启动 Meshroom 依次运行各个节点，进度条与日志实时更新。整个过程通常需要数分钟（GPU 稠密重建）。

6. 完成后，带纹理的网格自动导入并发布为名为 Photo2Mesh_Meshroom_<时分秒> 的 Mesh 对象，结果行显示顶点数和面数。

6.2 工作流 B：从照片文件夹重建（推荐画质）

1. 把原始全分辨率照片放入一个文件夹（无需事先载入 Dragonfly）。

2. 在 Photo input 组选中 Photos folder (original images)，点 … 选择该文件夹。

3. 点击 Reconstruct Mesh。照片按原样直接交给 Meshroom（不做缩放），其余流程与工作流 A 相同。

6.3 取消与作业文件夹

运行中可随时点 Cancel 终止 Meshroom 子进程（日志显示 cancelled）。每次重建的全部中间产物都保存在 作业根目录\<YYYYMMDD_HHMMSS> 下（images\ 为导出的照片帧，output\ 为 Meshroom 输出与 MeshroomCache 缓存），点 Open Job Folder 即可打开查看；不再需要时可整个删除该文件夹以释放磁盘空间。

7. 参数说明

所有设置在修改或运行后自动写入配置文件（%LOCALAPPDATA%\Photo2Mesh\meshroom_config.json），下次打开面板自动恢复。

8. 输出结果

重建成功后，插件在 Dragonfly 中生成并发布以下对象与文件：

• Mesh 对象：名为 Photo2Mesh_Meshroom_<HHMMSS> 的表面网格，出现在 Dragonfly 的对象列表中，可直接在 3D 视图中显示、测量或与其它数据叠加。导入优先使用 Dragonfly 原生网格加载器（快速、稳健）；不可用时插件会自动改用内置的 OBJ/PLY 解析器逐顶点重建（大网格时较慢）。
• 作业文件夹（Job root\<时间戳>\）：images\ 内是导出的照片帧（Photos folder 模式下不生成）；output\ 内是 Meshroom 的最终输出（优先取 texturedMesh.obj，其次 mesh.obj、其它 OBJ、PLY）以及 MeshroomCache 中间缓存。OBJ 文件可用于其它三维软件。

结果提示行会显示导入网格的顶点数与面数；日志中同时记录输出网格的完整磁盘路径。

再次提醒：网格的尺度与朝向是任意的（无真实物理单位）。如需与 CT 数据对比，请在 Dragonfly 中先对 Mesh 做缩放 / 配准。

9. 常见问题与故障排除

问 1：点了 Setup 后提示 Download failed / Setup FAILED，怎么办？

答：先检查网络（首次下载约 2 GB，超时或断网都会失败）。可以：(a) 在 Download URL 中填入可达的镜像地址后重试；(b) 在浏览器中手动下载 Meshroom win64 zip，解压到任意位置，再用 meshroom_batch 旁的 … 按钮指向解压出来的 meshroom_batch.exe——插件不强制使用自动下载。

问 2：运行时日志报 `ERROR: set meshroom_batch (click 'Setup / Download Meshroom').`

答：meshroom_batch 路径为空。先完成第 4 章的 Setup，或手动浏览指定 meshroom_batch.exe。

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

答：摄影测量至少需要 3 张不同角度的照片；所选 Channel 的切片数不足 3。请确认选择了正确的图像堆栈（点 Refresh 后重选），或改用 Photos folder 模式。

问 4：Meshroom 运行到一半失败，日志显示 `meshroom_batch exited with code ...`。

答：查看日志窗口中 Meshroom 自身的报错行。最常见的原因是没有 NVIDIA CUDA 显卡——DepthMap 稠密重建阶段强制要求 CUDA。其次是照片质量问题：反光、无纹理、透明物体或照片重叠不足会导致 SfM 匹配失败。改善拍摄（更多角度、更大重叠、漫射光照）后重试。

问 5：Channel 下拉框是空的。

答：当前场景中没有可用的 Channel。先把图像堆栈载入 Dragonfly，再点 Refresh。

问 6：重建出的网格特别小 / 方向不对。

答：这是摄影测量的固有特性——结果没有真实尺度和统一朝向。在 Dragonfly 中对导入的 Mesh 进行缩放和旋转即可；如需精确尺寸，可依据物体上已知长度进行标定缩放。

问 7：日志报 `meshroom finished but no OBJ/PLY mesh found in ...`。

答：Meshroom 正常退出但没有产出网格文件，通常意味着重建在网格化之前已经退化（有效相机太少）。点 Open Job Folder 检查 output\ 与 MeshroomCache，并对照问 4 的拍摄建议改进输入照片。

10. 注意事项与已知限制

• 重建结果尺度与朝向任意（无度量单位），需要时请在导入后自行缩放 / 配准。
• 最适合不透明、纹理丰富、照片重叠度高的物体；反光、无纹理或透明物体重建效果差。
• 必须有 NVIDIA CUDA 显卡（DepthMap 阶段硬性要求）；无独立显卡的机器无法完成完整管线。
• 每个物体的重建耗时以分钟计（GPU 稠密重建），照片越多、分辨率越高耗时越长。
• 图像堆栈模式下照片会被重新编码为 8-bit RGB PNG，且最长边受 Max frame size 限制；追求最高画质请使用 Photos folder 模式直接提供原始照片。
• 作业文件夹（帧 + 缓存 + 输出）可能占用大量磁盘空间，重建完成后可手动清理。
• 菜单项的启用 / 停用只在 Dragonfly 启动时生效，每次修改后需重启一次。

11. 参考资料

• Meshroom（AliceVision）项目主页与源码：https://github.com/alicevision/Meshroom
• 本插件使用的引擎发行版：Meshroom 2023.3.0 win64（https://github.com/alicevision/Meshroom/releases/download/v2023.3.0/Meshroom-2023.3.0-win64.zip）
• 许可证：Meshroom / AliceVision 均为 MPL-2.0（可商用）。
• 同系列 Photo2Mesh 插件：Photo2Mesh: COLMAP、Photo2Mesh: gsplat、Photo2Mesh: SAM3D（见各自的用户手册）。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Runtime Environment and First-Time Setup

5. User Interface

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

Photo2Mesh: Meshroom is one of the Photo2Mesh family of Dragonfly Prototype Apps. It reconstructs a textured 3D surface mesh of a real object from a series of ordinary multi-angle photographs using the classic Meshroom / AliceVision photogrammetry pipeline, and publishes the result directly into your Dragonfly scene as a Mesh object.

Photos can come from two sources: an image stack already loaded in Dragonfly (a Channel — each Z-slice becomes one photo), or a folder of original full-resolution photos (best quality). When you click Reconstruct Mesh, the plugin launches Meshroom's command-line program meshroom_batch outside Dragonfly, which runs feature extraction, sparse reconstruction (SfM), dense reconstruction (MVS), meshing and texturing; the resulting OBJ mesh is then imported and published as a Dragonfly Mesh.

Engine: the official Meshroom Windows release 2023.3.0 — a fully self-contained binary with its own Python runtime and AliceVision CUDA binaries, so nothing needs to be pip-installed on the Dragonfly side. License: Meshroom / AliceVision are MPL-2.0, safe for commercial use.

Important: photogrammetric reconstructions have arbitrary scale and orientation (no real physical units) — rescale and reorient the imported mesh in Dragonfly as needed. Opaque, well-textured objects photographed with good overlap give the best results.

2. Use Cases

Use this plugin whenever you need a 3D digital model of a physical sample without a CT scan, for example:

• Digitizing geological or biological specimens into 3D digital archives;
• Archiving the outer shape of industrial parts or failure samples;
• Comparing an object's outer surface mesh with its CT-scanned interior in the same scene;
• Creating textured meshes for visualization, teaching and presentations;
• Reconstructing directly from a turntable / orbit photo sequence already loaded in Dragonfly as an image stack.

3. Installation and Enabling

The plugin is installed through the Prototype Labs & Apps Full Package installer:

1. Unzip the package to any short path (e.g. C:\PL\; avoid deep folders to stay clear of the Windows 260-character path limit).

2. Double-click `Install_FullPackage.bat`.

3. In the component list, tick Photo2Mesh: Meshroom.... Note: all plugins are unticked by default — you must enable it explicitly.

4. Click Install and wait for the console to finish.

5. Fully quit and restart Dragonfly (menus are scanned only at startup).

After the restart, the menu entry appears at Prototype Apps ▸ Photo2Mesh: Meshroom... (in the Photo2Mesh section). Clicking it opens a dockable floating panel titled Photo2Mesh: Meshroom.

Enable / disable later: open Developer ▸ Prototype Labs... ▸ Menu Item Manager and use the checkbox for this plugin in the "Prototype Apps (Full Package)" list at the bottom; restart Dragonfly to apply. Disabling never deletes the downloaded Meshroom engine — re-enabling is instant. You can also re-run the installer at any time (%LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat); your previous choices are remembered as defaults.

Uninstall: double-click Uninstall_FullPackage.bat to remove all Full Package menu items and plugins. The downloaded Meshroom engine (~2 GB) is kept at %LOCALAPPDATA%\Photo2Mesh\Meshroom; the uninstaller lists this path at the end so you can delete it manually to reclaim disk space.

Everything installs per-user (%LOCALAPPDATA%); no administrator rights are needed.

4. Runtime Environment and First-Time Setup

The engine is of the binary_download kind: the official Meshroom release ships its own complete runtime, so no Python venv, no pip installs, and no WSL are needed. Dragonfly only launches it as an external subprocess.

4.1 First-time setup (Setup / Download Meshroom)

1. Open the panel and click Setup / Download Meshroom in the Meshroom engine group.

2. The plugin first looks for an existing meshroom_batch.exe under %LOCALAPPDATA%\Photo2Mesh\Meshroom; if found, it is used directly with no re-download.

3. Otherwise it downloads the Meshroom 2023.3.0 win64 zip (~2 GB) from the official GitHub release page, showing live progress (downloaded / total MB) in the log, then extracts it to that folder and deletes the zip.

4. On success the meshroom_batch field is filled with the full path to meshroom_batch.exe and saved to the config file, so it is restored automatically next time.

The default download URL is https://github.com/alicevision/Meshroom/releases/download/v2023.3.0/Meshroom-2023.3.0-win64.zip. If that source is unreachable, enter a custom mirror URL in the Download URL field before clicking Setup — or skip downloading entirely: if Meshroom is already installed on this machine, use the … button next to meshroom_batch to browse to the existing meshroom_batch.exe. The download can be aborted with Cancel.

4.2 Hardware and network requirements

• Internet: needed only for the one-time engine download (~2 GB); reconstruction itself runs fully offline.
• GPU: an NVIDIA CUDA GPU is required — Meshroom's dense DepthMap stage runs on CUDA only.
• WSL: not needed.
• Disk: ~2 GB for the engine, plus per-job image frames, cache (MeshroomCache) and output meshes in the job folder.

4.3 Paths

5. User Interface

The panel is a two-column layout: a blue note at the top (summarizing the function and caveats); the left side is a scrollable settings area with three groups — Meshroom engine, Photo input, and Options; the right side holds the run controls (button row, progress bar, result line and log window).

5.1 Meshroom engine group

• meshroom_batch: full path to meshroom_batch.exe. Normally filled by Setup; you can also browse manually with the … button (placeholder: path to meshroom_batch.exe (set by Setup)).
• Download URL: URL of the Meshroom Windows release zip; leave blank to use the official default (Meshroom 2023.3.0 win64).
• Setup / Download Meshroom button: locates or downloads the engine (see Chapter 4).

5.2 Photo input group

Two mutually exclusive radio buttons select the photo source:

• Active image stack (each slice = one photo) (default): uses a loaded image-stack Channel; each Z-slice is exported as one photo. Below it are three Channel dropdowns: Red / primary (required), Green (optional) and Blue (optional) (both default (none)). With a single grayscale channel, the grayscale is replicated to RGB; adding Green/Blue composes three grayscale channels into RGB colour photos slice by slice; if Red itself is a multi-component RGB channel, it is used as colour directly. The Refresh button rescans all Channels in the current scene and repopulates the dropdowns.
• Photos folder (original images): point at a folder of original full-resolution photos (browse via …); the photos are passed to Meshroom as-is — best quality.

5.3 Options group

• Job root: root folder for jobs, default C:\Photo2MeshJobs. Each reconstruction creates a new timestamped subfolder there.
• Pipeline: dropdown with photogrammetry (default, the standard full pipeline) or draft (a faster draft pipeline, passed to meshroom_batch --pipeline).
• Max frame size (stack only, px): spinbox, range 512–8192, step 256, default 2400. Stack mode only: exported frames whose longest side exceeds this value are downscaled proportionally.

5.4 Run controls (right side)

• Reconstruct Mesh (blue button): starts the whole reconstruction.
• Cancel: requests cancellation of the current download or reconstruction (enabled only while running).
• Open Job Folder: opens the most recent job folder in Windows Explorer (or the job root if no job has run yet).
• Progress bar: 0–100%, advanced coarsely by the Meshroom processing nodes (CameraInit, FeatureExtraction, ..., Texturing).
• Result line: shows the current stage or the final result (e.g. Done. Mesh: N verts, M faces (published).).
• Log: read-only log window streaming meshroom_batch output plus the plugin's own status messages — your first stop for troubleshooting.

6. Step-by-Step Usage

6.1 Workflow A: reconstruct from a loaded image stack

1. Take a series of multi-angle photos around the object (ensure generous overlap between neighbouring shots) and load them into Dragonfly as an image stack (a Channel).

2. Open Prototype Apps ▸ Photo2Mesh: Meshroom...; on first use complete the Setup from Chapter 4.

3. In Photo input, keep Active image stack selected, click Refresh, and pick the stack in the Red / primary dropdown. A grayscale stack needs nothing else; if your photos were loaded as separate R/G/B grayscale channels, select all three dropdowns accordingly.

4. Adjust the Options (job root, pipeline, max frame size) if needed.

5. Click Reconstruct Mesh. The plugin first exports each slice as an RGB PNG frame (frame_0000.png onwards; the stack must have at least 3 slices), then runs Meshroom node by node with live progress and log output. Expect minutes per object (GPU dense reconstruction).

6. When finished, the textured mesh is imported and published as a Mesh object named Photo2Mesh_Meshroom_<HHMMSS>; the result line reports vertex and face counts.

6.2 Workflow B: reconstruct from a photos folder (best quality)

1. Put the original full-resolution photos into one folder (no need to load them into Dragonfly).

2. In Photo input, select Photos folder (original images) and browse to that folder with ….

3. Click Reconstruct Mesh. The photos go to Meshroom unmodified (no rescaling); everything else matches Workflow A.

6.3 Cancelling and the job folder

You can click Cancel at any time to terminate the Meshroom subprocess (the log reports cancelled). All intermediate products of each run live under job root\<YYYYMMDD_HHMMSS> — images\ holds the exported photo frames (not created in Photos-folder mode) and output\ holds Meshroom's results plus the MeshroomCache cache. Click Open Job Folder to inspect it; delete the whole folder afterwards to reclaim disk space.

7. Parameter Reference

All settings are saved automatically to the configuration file (%LOCALAPPDATA%\Photo2Mesh\meshroom_config.json) and restored the next time the panel opens.

8. Outputs

A successful reconstruction produces the following objects and files:

• A Mesh object named Photo2Mesh_Meshroom_<HHMMSS>, published into Dragonfly's object list — display it in the 3D view, measure it, or overlay it with other data. Import prefers Dragonfly's native mesh loader (fast and robust); if unavailable, the plugin falls back to its built-in OBJ/PLY parser and rebuilds the mesh vertex by vertex (slower for very large meshes).
• A job folder (Job root\<timestamp>\): images\ contains the exported photo frames (absent in Photos-folder mode); output\ contains Meshroom's final output — preferring texturedMesh.obj, then mesh.obj, then any other OBJ, then PLY — plus the MeshroomCache intermediate cache. The OBJ file can be reused in other 3D software.

The result line reports the imported mesh's vertex and face counts; the log also records the full disk path of the output mesh.

Reminder: the mesh has arbitrary scale and orientation (no physical units). To compare it with CT data, rescale / register the Mesh in Dragonfly first.

9. FAQ and Troubleshooting

Q1: Setup reports Download failed / Setup FAILED. What now?

A: Check your internet connection first (the one-time download is ~2 GB; timeouts or dropped connections fail it). Then either (a) enter a reachable mirror URL in Download URL and retry, or (b) download the Meshroom win64 zip manually in a browser, extract it anywhere, and point the meshroom_batch field at the extracted meshroom_batch.exe via the … button — the automatic download is optional.

Q2: The log says `ERROR: set meshroom_batch (click 'Setup / Download Meshroom').`

A: The meshroom_batch path is empty. Complete the Setup from Chapter 4, or browse to meshroom_batch.exe manually.

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

A: Photogrammetry needs at least 3 photos from different angles; the selected Channel has fewer than 3 slices. Make sure you picked the right image stack (click Refresh and re-select), or switch to Photos folder mode.

Q4: Meshroom fails mid-run with `meshroom_batch exited with code ...`.

A: Read Meshroom's own error lines in the log window. The most common cause is the lack of an NVIDIA CUDA GPU — the dense DepthMap stage strictly requires CUDA. Next most common are photo-quality problems: shiny, textureless or transparent objects, or insufficient overlap, make SfM matching fail. Improve the capture (more angles, more overlap, diffuse lighting) and retry.

Q5: The Channel dropdowns are empty.

A: No Channel is available in the current scene. Load your image stack into Dragonfly first, then click Refresh.

Q6: The reconstructed mesh is tiny / oriented wrongly.

A: This is inherent to photogrammetry — results carry no real scale or canonical orientation. Rescale and rotate the imported Mesh in Dragonfly; for accurate dimensions, calibrate the scale against a known length on the object.

Q7: The log says `meshroom finished but no OBJ/PLY mesh found in ...`.

A: Meshroom exited normally but produced no mesh file — usually the reconstruction degenerated before meshing (too few valid cameras). Click Open Job Folder to inspect output\ and MeshroomCache, and improve the input photos following the advice in Q4.

10. Notes and Known Limitations

• Reconstructions have arbitrary scale and orientation (no metric units) — rescale / register after import as needed.
• Works best on opaque, well-textured objects with good photo overlap; shiny, textureless or transparent objects reconstruct poorly.
• An NVIDIA CUDA GPU is mandatory (hard requirement of the DepthMap stage); machines without a discrete NVIDIA GPU cannot complete the full pipeline.
• Runtime is minutes per object (GPU dense reconstruction); more and higher-resolution photos take longer.
• In image-stack mode photos are re-encoded as 8-bit RGB PNGs and capped by Max frame size; for maximum quality use Photos folder mode with the original photos.
• Job folders (frames + cache + outputs) can consume substantial disk space; clean them up manually after reconstruction.
• Menu enable/disable changes take effect only at Dragonfly startup — restart once after each change.

11. References

• Meshroom (AliceVision) project page and source code: https://github.com/alicevision/Meshroom
• Engine release used by this plugin: Meshroom 2023.3.0 win64 (https://github.com/alicevision/Meshroom/releases/download/v2023.3.0/Meshroom-2023.3.0-win64.zip)
• License: Meshroom / AliceVision are MPL-2.0 (commercially usable).
• Sibling Photo2Mesh plugins: Photo2Mesh: COLMAP, Photo2Mesh: gsplat, Photo2Mesh: SAM3D (see their own user manuals).