Photo2Mesh: gsplat 插件用户手册

Photo2Mesh: gsplat - User Manual

Dragonfly Prototype Apps · Photo2Mesh: gsplat...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

1.1 技术栈与许可证

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

4.1 前提条件

4.2 Setup Environment 具体做什么

4.3 磁盘位置一览

5. 界面说明

5.1 Environment (Apache-2.0 GS stack) 分组

5.2 Photo input 分组

5.3 Options 分组

5.4 右侧运行区

6. 使用步骤

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

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

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Photo2Mesh: gsplat 是 Dragonfly 的一个 Prototype Apps 插件。它利用高斯泼溅（Gaussian Splatting）——一种现代神经渲染技术——从围绕真实物体拍摄的一系列普通照片重建该物体的三维表面网格（Mesh）。您把照片作为 Dragonfly 中的活动图像堆栈（每个切片对应一张照片）提供，或直接指定一个照片文件夹，设置训练迭代次数与网格提取方法后点击 Reconstruct Mesh；插件会自动估计相机位姿、训练高斯泼溅模型并提取表面，最终把结果作为 Mesh 对象发布到 Dragonfly 场景中，可直接用于测量与分析。

插件内部执行一条三阶段流水线（全部在 Dragonfly 之外、插件专用的 CUDA venv 中以子进程方式运行）：

1. ns-process-data images —— 通过 COLMAP 做运动恢复结构（SfM），估计每张照片的相机位姿并生成 Nerfstudio 数据集；

2. ns-train splatfacto —— 用 Nerfstudio 的 splatfacto 方法在 gsplat 光栅化后端上训练高斯泼溅模型；

3. gs-mesh <method> —— 用 DN-Splatter 的表面导出器（TSDF / Open3D TSDF / dn / marching）从训练好的模型中提取表面网格，得到 PLY 文件。

PLY 网格随后被读入并作为已发布（published）的 Dragonfly Mesh 重建到当前场景中。

1.1 技术栈与许可证

本插件刻意只使用可商用的 Apache-2.0 开源软件栈：gsplat（洁净室实现的 Apache-2.0 高斯泼溅光栅化器）、Nerfstudio（Apache-2.0，其 splatfacto 方法在 gsplat 后端上训练）、DN-Splatter（Apache-2.0，提供 gs-mesh 表面网格导出）。链路中的每一环都允许商业再分发。

学术界追求网格质量的高斯泼溅研究方法（2DGS、SuGaR、GOF、PGSR、RaDe-GS 等）都继承了 Inria 的非商用 diff-gaussian-rasterization 许可证，无法用于商业产品，因此本插件有意不采用它们。

各组件由 pip 在环境搭建时安装（nerfstudio、gsplat 为 PyPI 最新版本，dn-splatter 直接从其 GitHub 仓库安装），未锁定具体版本号；命令行参数在上游演进时可能变化，详见第 9、10 章。

本插件是 Photo2Mesh 系列三个插件（Meshroom / COLMAP / gsplat）之一。在三者中，它在纹理丰富的物体上通常给出保真度最高的表面，代价是计算时间更长、环境最重。

2. 适用场景

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

• 用手机或单反照片数字化岩芯、化石、铸件、机加工零件、增材制造零件；
• 数字化生物标本、考古文物等不宜或无法进入 CT 设备的对象；
• 将拍照获得的外部几何与同一样品的内部 CT 数据在 Dragonfly 中进行比对分析；
• 为测量、检测或存档目的快速生成可在 Dragonfly 中直接使用的表面网格。

输入是围绕物体多角度拍摄的一组普通照片（至少 3 张，实际重建通常需要充分环绕覆盖）。物体表面纹理越丰富，COLMAP 位姿估计与高斯泼溅训练的效果越好。

3. 安装与启用

本插件随 Prototype Labs & Apps 完整安装包（Full Package）发布，通过统一安装器安装：

1. 把安装包 zip 解压到任意位置（建议较短的路径，如 C:\PL\）；

2. 双击 `Install_FullPackage.bat`；

3. 在弹出的对话框中选择核心安装模式（Fresh 全新 / Compatible 兼容），并在 Prototype Apps 列表中勾选 “Photo2Mesh: gsplat...”——注意所有插件默认不勾选，必须手动勾选才会安装；

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

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

重启后，菜单项出现在 Prototype Apps ▸ Photo2Mesh: gsplat...（位于 Photo2Mesh 分组）。点击它会打开一个名为 “Photo2Mesh: gsplat” 的浮动可停靠面板。

以后启用 / 停用：打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，在底部的 “Prototype Apps (Full Package)” 列表中勾选或取消本插件，重启 Dragonfly 生效。停用从不删除插件已搭建的环境（venv），重新启用后立即可用。也可以随时重跑安装器修改勾选（上次的选择就是新的默认值）。

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

菜单只在 Dragonfly 启动时扫描——每次修改勾选后都需要重启一次 Dragonfly。所有内容都安装在当前用户目录（%LOCALAPPDATA%）下，不需要管理员权限。

4. 运行环境与首次配置

本插件是三个 Photo2Mesh 插件中最重的一个。安装时不下载任何东西；首次使用前必须在面板里点击 Setup Environment (build venv + install) 搭建其专用 Python 环境。此过程耗时较长、下载数 GB，请预留时间与磁盘空间。

4.1 前提条件

• NVIDIA CUDA 显卡（训练与网格提取都需要 GPU）；
• 已安装的 CUDA 工具包 与 MSVC 生成工具——gsplat 在安装时要编译一个原生 CUDA 扩展；
• git——dn-splatter 直接从其 GitHub 仓库安装；
• 网络连接——需要从 PyTorch CUDA 轮子索引和 PyPI/GitHub 下载数 GB 的包；
• 一个 colmap.exe 可执行文件——ns-process-data 需要 COLMAP。最简单的获取方式是安装同系列的 Photo2Mesh: COLMAP 插件并用它下载 COLMAP（默认位于 %LOCALAPPDATA%\Photo2Mesh\COLMAP）。

4.2 Setup Environment 具体做什么

点击 Setup Environment 后，插件用一个“基础 Python”（Base Python）执行以下步骤，全部输出实时显示在右侧日志中：

1. 在 %LOCALAPPDATA%\Photo2Mesh\gsplat_venv 创建（或复用）一个专用 venv 虚拟环境——若已有 venv 但其 pip 不可用，会自动删除重建；

2. 在 venv 内升级 pip、setuptools、wheel；

3. 从 Torch CUDA wheel index（面板可配置，默认 https://download.pytorch.org/whl/cu124）安装 torch torchvision；

4. 安装其余组件：nerfstudio、gsplat（编译 CUDA 扩展，最耗时的一步）以及来自 GitHub 的 dn-splatter；

5. 运行冒烟测试：导入 torch / gsplat / nerfstudio 并在日志中打印一行 SMOKE={...}，报告 torch 版本、CUDA 是否可用（cuda: true/false）及 GPU 设备名；

6. 成功后自动把 venv 的 Python 路径填入面板的 venv python 字段并保存配置。

Base Python 的选择：“Base Python (build)” 留空时，默认使用本 Dragonfly 自带的 Python（推荐，用户无需另装 Python）。若该解释器没有可用的 pip，插件会自动搜索系统中其它 CPython（py 启动器、PATH、常见安装位置），仍找不到时才报错。您也可以手动填入某个 CPython 3.9+ 的路径（如 C:\Python312\python.exe）或命令（如 py -3.11）覆盖默认值。任何东西都不会装进 Dragonfly 自己的 Python——只装进新建的 venv。

Torch CUDA wheel index 必须与您的显卡驱动匹配（cu121 / cu124 / ...）。若 torch 安装失败，日志会提示检查该 URL。

4.3 磁盘位置一览

本插件不使用 WSL，全部在 Windows 本机运行。面板设置（路径、迭代次数、方法等）在每次运行和浏览选择后自动持久化，下次打开面板自动恢复。

5. 界面说明

面板为左右分栏布局：左侧是三个设置分组（Environment、Photo input、Options，可滚动），右侧是运行控制与日志。顶部的蓝色说明文字概述了技术栈与首次搭建环境的注意事项。

5.1 Environment (Apache-2.0 GS stack) 分组

5.2 Photo input 分组

5.3 Options 分组

5.4 右侧运行区

6. 使用步骤

两种输入方式对应两条端到端工作流。首次使用前请先完成第 4 章的环境搭建，并在 colmap.exe 字段填好 COLMAP 路径。

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

输入要求：一个已载入 Dragonfly 的图像堆栈 Channel，其中每个切片是围绕物体拍摄的一张照片，至少 3 个切片（少于 3 张会直接报错）。

1. 打开 Prototype Apps ▸ Photo2Mesh: gsplat...；

2. 确认 venv python 已填写（否则先点 Setup Environment）、colmap.exe 已指定；

3. 在 Photo input 中选中 Active image stack，点 Refresh，在 Red / primary 下拉框中选择照片堆栈 Channel（灰度堆栈自动复制为 RGB；如有三个分色灰度 Channel，可在 Green/Blue 中补齐合成彩色；单个多分量 RGB Channel 也可直接用）；

4. 在 Options 中确认 Job root、Train iterations（默认 15000）、gs-mesh method（默认 tsdf）与 Max frame size（默认 1920 像素，过大的照片会被等比缩小）；

5. 点击 Reconstruct Mesh。面板先把堆栈切片导出为 RGB PNG 照片，然后依次运行 COLMAP 位姿估计、splatfacto 训练、gs-mesh 表面提取，进度条与日志实时更新；

6. 完成后结果标签显示网格顶点数与面数，新 Mesh 以 `Photo2Mesh_gsplat_<时分秒>` 命名发布到 Dragonfly 场景中，可立即在 3D 视图中查看。

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

输入要求：磁盘上一个包含原始照片文件的文件夹（多角度环绕拍摄，至少 3 张）。此模式直接使用原图，不做尺寸缩放（Max frame size 仅对堆栈模式生效）。

1. 打开面板，确认 venv 与 colmap.exe 已就绪；

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

3. 按需调整 Options 中的参数；

4. 点击 Reconstruct Mesh，等待三阶段流水线完成；

5. 在 Dragonfly 场景中查看发布的 Mesh；需要检查中间产物或日志时点 Open Job Folder。

训练在 GPU 上进行，15000 次迭代加上 COLMAP 与网格提取可能需要较长时间。期间可以点 Cancel 中止；已生成的日志与中间文件保留在任务文件夹中。

7. 参数说明

8. 输出结果

Dragonfly 场景中：成功后插件发布一个新的 Mesh 对象，命名为 Photo2Mesh_gsplat_<时分秒>，出现在对象列表中并可在 3D 视图中显示、测量与分析。结果标签同时报告顶点数与面数。

重建出的网格具有任意的尺度与朝向（照片无法确定绝对尺寸）——导入后请按已知尺寸对 Mesh 进行缩放与摆正。

任务文件夹中（<Job root>\<YYYYMMDD_HHMMSS>，用 Open Job Folder 打开）：

9. 常见问题与故障排除

问：Setup Environment 在安装 torch 时失败？ 答：日志会提示 torch install failed... Check the CUDA index URL matches your driver (cu121/cu124/...)。把 Torch CUDA wheel index 改为与您显卡驱动匹配的索引（如 https://download.pytorch.org/whl/cu121）后重试。整个安装需要稳定的网络。

问：Setup Environment 报 “no venv module” 或找不到可用的 pip？ 答：默认基础解释器是 Dragonfly 自带的 Python；若其不可用，插件会自动搜索系统 CPython。仍失败时，把 Base Python (build) 指向一个带 stdlib venv 与 pip 的 CPython 3.9+（例如 C:\Python312\python.exe）再点一次 Setup Environment。失败留下的半成品 venv 会在下次运行时自动重建。

问：运行时报 “ns-process-data failed (COLMAP/SfM)”？ 答：先确认 colmap.exe 路径正确（可用 Photo2Mesh: COLMAP 插件下载获得）。然后打开任务文件夹中的 1_process.log——第一行是确切命令，末尾是错误输出。照片重叠不足、纹理太弱或照片太少也会导致 SfM 失败；增加环绕照片数量与重叠度后重试。

问：训练阶段（ns-train splatfacto）失败？ 答：查看 2_train.log。常见原因：没有可用的 NVIDIA CUDA GPU（可在 Setup 日志的 SMOKE= 行确认 cuda: true），或 gsplat 的 CUDA 扩展编译失败（需要 CUDA 工具包 + MSVC 生成工具）。

问：报 “gs-mesh failed or produced no PLY”？ 答：查看 3_mesh.log。可在 gs-mesh method 中换一种方法（tsdf / o3dtsdf / dn / marching）重试。另外 Nerfstudio / DN-Splatter 的命令行参数会随上游版本演进——日志第一行的确切命令可帮助确认是否为参数不兼容。

问：点 Reconstruct Mesh 提示 “need >= 3 photos” 或 “no channel selected”？ 答：堆栈模式要求所选 Channel 至少有 3 个切片；下拉框为空时先点 Refresh 再选择图像堆栈。文件夹模式则要求填入一个存在的照片目录。

问：菜单里找不到 “Photo2Mesh: gsplat...”？ 答：插件在完整安装包中默认不勾选。重跑安装器勾选它，或在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 底部勾选后重启 Dragonfly。

问：重建出的网格大小/方向不对？ 答：这是原理性现象——纯照片流水线无法恢复绝对尺度与方向。在 Dragonfly 中按已知尺寸对 Mesh 缩放并旋转摆正即可。

10. 注意事项与已知限制

• 三个 Photo2Mesh 插件中最重的一个：首次 Setup Environment 可能需要很长时间并下载数 GB；venv 独立于 Dragonfly，重装 Dragonfly 不影响它。
• 必须有 NVIDIA CUDA GPU；环境搭建还需要 CUDA 工具包、MSVC 生成工具、git 与网络。
• 重建结果具有任意尺度与朝向，导入后需手动缩放/摆正。
• Nerfstudio / DN-Splatter 的 CLI 参数可能随版本漂移；若某阶段失败，对应的 1_process.log / 2_train.log / 3_mesh.log 中记录了确切命令与错误。
• 网格按逐顶点/逐面方式导入 Dragonfly，特别巨大的网格导入可能较慢。
• 面板设置自动保存在 %LOCALAPPDATA%\Photo2Mesh\gsplat_config.json；停用或更新插件代码都不会清除环境与设置。
• 任务文件夹（默认 C:\Photo2MeshJobs 下）会随使用不断累积中间数据，可定期手动清理。

11. 参考资料

• gsplat —— Apache-2.0 的高斯泼溅光栅化器（PyPI 包 gsplat），本插件的训练后端。
• Nerfstudio —— Apache-2.0 的神经渲染框架（PyPI 包 nerfstudio），提供 ns-process-data、ns-train splatfacto 命令。
• DN-Splatter —— Apache-2.0 的表面重建扩展，提供 gs-mesh 命令：https://github.com/maturk/dn-splatter。
• COLMAP —— 运动恢复结构（SfM）引擎，由 ns-process-data 调用；可通过 Photo2Mesh: COLMAP 插件下载。
• PyTorch CUDA 轮子索引 —— https://download.pytorch.org/whl/cu124（按驱动换用 cu121 等）。
• 同系列插件：Photo2Mesh: Meshroom、Photo2Mesh: COLMAP（各自有独立用户手册）。

Part II English Manual

Contents

1. Overview

1.1 Software stack and licensing

2. Use cases

3. Installation and enabling

4. Runtime environment and first-time setup

4.1 Prerequisites

4.2 What Setup Environment actually does

4.3 Where things live on disk

5. User interface

5.1 Environment (Apache-2.0 GS stack) group

5.2 Photo input group

5.3 Options group

5.4 Run area (right side)

6. Step-by-step usage

6.1 Workflow A: reconstruct from the active image stack

6.2 Workflow B: reconstruct from a photos folder

7. Parameter reference

8. Outputs

9. FAQ and troubleshooting

10. Notes and known limitations

11. References

1. Overview

Photo2Mesh: gsplat is a Dragonfly Prototype Apps plugin. It reconstructs a 3D surface mesh of a real object from a series of ordinary photos taken around it, using Gaussian Splatting — a modern neural rendering technique. You provide the photos either as the active image stack in Dragonfly (each slice is one photo) or as a folder of photo files, choose the training iterations and the meshing method, and click Reconstruct Mesh; the plugin estimates the camera poses, trains a Gaussian Splatting model, extracts a surface, and publishes the result as a Mesh in your Dragonfly scene, ready for measurement and analysis.

Internally the plugin runs a three-stage pipeline (entirely outside Dragonfly, as a subprocess inside the plugin's own dedicated CUDA venv):

1. ns-process-data images — Structure-from-Motion via COLMAP: estimates the camera pose of every photo and builds a Nerfstudio dataset;

2. ns-train splatfacto — trains a Gaussian Splatting model with Nerfstudio's splatfacto method on the gsplat rasterizer backend;

3. gs-mesh <method> — extracts a surface mesh from the trained model with DN-Splatter's exporters (TSDF / Open3D TSDF / dn / marching), producing a PLY file.

The PLY mesh is then read back and rebuilt as a published Dragonfly Mesh in the current scene.

1.1 Software stack and licensing

This plugin deliberately uses only a commercially safe Apache-2.0 open-source stack: gsplat (a clean-room Apache-2.0 Gaussian-Splatting rasterizer), Nerfstudio (Apache-2.0; its splatfacto method trains on gsplat), and DN-Splatter (Apache-2.0; provides the gs-mesh surface exporter). Every link in the chain is commercially redistributable.

The mesh-quality Gaussian-Splatting research methods (2DGS, SuGaR, GOF, PGSR, RaDe-GS, ...) inherit Inria's non-commercial diff-gaussian-rasterization license and are therefore intentionally NOT used by this plugin.

The components are installed by pip during environment setup (nerfstudio and gsplat as the latest PyPI releases, dn-splatter directly from its GitHub repository); no specific version numbers are pinned, and upstream command-line flags can evolve — see chapters 9 and 10.

This is one of the three sibling Photo2Mesh plugins (Meshroom / COLMAP / gsplat). Of the three it typically gives the highest-fidelity surfaces on well-textured objects, at the cost of longer computation and the heaviest environment.

2. Use cases

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

• digitizing rock cores, fossils, castings, machined or additively manufactured parts from smartphone or DSLR photos;
• digitizing biological specimens or archaeological objects that cannot (or should not) go into a CT scanner;
• comparing external photographed geometry against internal CT data of the same sample inside Dragonfly;
• quickly producing a surface mesh for measurement, inspection, or archival directly usable in Dragonfly.

The input is a set of ordinary photos taken from many angles around the object (at least 3; real reconstructions normally need good all-around coverage). The richer the surface texture, the better COLMAP pose estimation and Gaussian-Splatting training work.

3. Installation and enabling

The plugin ships with the Prototype Labs & Apps Full Package and is installed by its unified installer:

1. Unzip the package anywhere (a short path such as C:\PL\ is recommended);

2. Double-click `Install_FullPackage.bat`;

3. In the dialog, pick the core install mode (Fresh / Compatible) and tick "Photo2Mesh: gsplat..." in the Prototype Apps list — all plugins are unticked by default, so it must be enabled explicitly;

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

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

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

Enable / disable later: open Developer ▸ Prototype Labs... ▸ Menu Item Manager — the "Prototype Apps (Full Package)" list at the bottom has a checkbox per app; tick = deploy, untick = remove the menu entry, then restart Dragonfly to apply. Disabling never deletes the plugin's built environment (venv); re-enabling is instant. Alternatively, re-run the installer anytime — it remembers your previous choices as the new defaults.

Uninstall: double-click `Uninstall_FullPackage.bat` (a copy is kept in %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer). It removes all Full-Package menu items and plugins but keeps every plugin environment (such as this plugin's venv) — the paths are listed at the end so you can delete them manually if you want the disk space back.

Menus are discovered only at Dragonfly startup — every enable/disable change needs one restart. Everything is installed per-user (%LOCALAPPDATA%); no admin rights are needed.

4. Runtime environment and first-time setup

This is the heaviest of the three Photo2Mesh plugins. Nothing is downloaded at install time; before first use you must click Setup Environment (build venv + install) in the panel to build its dedicated Python environment. This is a long operation that downloads several GB — allow time and disk space.

4.1 Prerequisites

• an NVIDIA CUDA GPU (needed for training and mesh extraction);
• an installed CUDA toolkit and the MSVC build tools — gsplat compiles a native CUDA extension during installation;
• git — dn-splatter is installed directly from its GitHub repository;
• internet access — several GB are downloaded from the PyTorch CUDA wheel index and from PyPI/GitHub;
• a colmap.exe executable — ns-process-data requires COLMAP. The easiest source is the sibling Photo2Mesh: COLMAP plugin, which downloads COLMAP to %LOCALAPPDATA%\Photo2Mesh\COLMAP.

4.2 What Setup Environment actually does

When you click Setup Environment, the plugin runs the following steps with a "base Python", streaming all output into the log on the right:

1. creates (or reuses) a dedicated venv at %LOCALAPPDATA%\Photo2Mesh\gsplat_venv — an existing venv whose pip is broken is deleted and rebuilt automatically;

2. upgrades pip, setuptools, and wheel inside the venv;

3. installs torch torchvision from the Torch CUDA wheel index (configurable in the panel; default https://download.pytorch.org/whl/cu124);

4. installs the rest of the stack: nerfstudio, gsplat (compiles the CUDA extension — the slowest step), and dn-splatter from GitHub;

5. runs a smoke test that imports torch / gsplat / nerfstudio and prints a SMOKE={...} line to the log reporting the torch version, whether CUDA is available (cuda: true/false), and the GPU device name;

6. on success, automatically fills the panel's venv python field with the venv interpreter path and saves the configuration.

Choosing the base Python: with "Base Python (build)" left blank, the plugin uses this Dragonfly's own bundled Python (recommended — no separate Python install is needed). If that interpreter has no working pip, the plugin automatically searches for another system CPython (the py launcher, PATH, and common install locations) before giving up. You can also override the field with a CPython 3.9+ path (e.g. C:\Python312\python.exe) or a command such as py -3.11. Nothing is ever installed into Dragonfly's own Python — only into the freshly created venv.

The Torch CUDA wheel index must match your GPU driver (cu121 / cu124 / ...). If the torch installation fails, the log tells you to check this URL.

4.3 Where things live on disk

The plugin does not use WSL; everything runs natively on Windows. Panel settings (paths, iterations, method, ...) are persisted automatically after every run and browse action, and restored the next time the panel opens.

5. User interface

The panel is split left/right: the left side holds three settings groups (Environment, Photo input, Options; scrollable), the right side holds the run controls and the log. The blue note at the top summarizes the software stack and the first-time setup requirements.

5.1 Environment (Apache-2.0 GS stack) group

5.2 Photo input group

5.3 Options group

5.4 Run area (right side)

6. Step-by-step usage

The two input modes give two end-to-end workflows. Before the first run, complete the environment setup of chapter 4 and fill in the colmap.exe path.

6.1 Workflow A: reconstruct from the active image stack

Input requirement: an image-stack Channel loaded in Dragonfly whose slices are the photos taken around the object — at least 3 slices (fewer is rejected with an error).

1. Open Prototype Apps ▸ Photo2Mesh: gsplat...;

2. Check that venv python is filled in (otherwise click Setup Environment first) and that colmap.exe is set;

3. In Photo input select Active image stack, click Refresh, and pick the photo-stack Channel in the Red / primary dropdown (a grayscale stack is replicated to RGB; with three per-color grayscale Channels, add Green/Blue to compose a color image; a single multi-component RGB Channel also works directly);

4. In Options confirm Job root, Train iterations (default 15000), gs-mesh method (default tsdf) and Max frame size (default 1920 px; larger photos are downscaled proportionally);

5. Click Reconstruct Mesh. The panel first exports the stack slices as RGB PNG photos, then runs COLMAP pose estimation, splatfacto training, and gs-mesh surface extraction, with live progress and log output;

6. When finished, the result label reports the vertex and face counts, and the new Mesh is published into the Dragonfly scene as `Photo2Mesh_gsplat_<HHMMSS>`, immediately visible in the 3D view.

6.2 Workflow B: reconstruct from a photos folder

Input requirement: a folder on disk containing the original photo files (taken around the object, at least 3). This mode uses the originals directly; Max frame size applies to stack mode only.

1. Open the panel and check that the venv and colmap.exe are ready;

2. Select Photos folder (original images) and pick the folder with the … button;

3. Adjust the Options as needed;

4. Click Reconstruct Mesh and wait for the three-stage pipeline to finish;

5. Inspect the published Mesh in the Dragonfly scene; use Open Job Folder to look at intermediate products and logs.

Training runs on the GPU; 15000 iterations plus COLMAP and meshing can take a long time. You can click Cancel at any point; the logs and intermediate files produced so far remain in the job folder.

7. Parameter reference

8. Outputs

In the Dragonfly scene: on success the plugin publishes a new Mesh object named Photo2Mesh_gsplat_<HHMMSS>; it appears in the object list and can be displayed, measured, and analyzed in the 3D view. The result label also reports the vertex and face counts.

The reconstructed mesh has an arbitrary scale and orientation (photos cannot determine absolute size) — rescale and reorient the Mesh after import using a known dimension.

In the job folder (<Job root>\<YYYYMMDD_HHMMSS>, opened via Open Job Folder):

9. FAQ and troubleshooting

Q: Setup Environment fails while installing torch? A: The log says torch install failed... Check the CUDA index URL matches your driver (cu121/cu124/...). Change the Torch CUDA wheel index to the index matching your GPU driver (e.g. https://download.pytorch.org/whl/cu121) and retry. The whole installation needs a stable internet connection.

Q: Setup Environment reports "no venv module" or cannot find a usable pip? A: The default base interpreter is Dragonfly's own Python; if it is unusable the plugin automatically searches for another system CPython. If it still fails, point Base Python (build) at a CPython 3.9+ with the stdlib venv module and pip (e.g. C:\Python312\python.exe) and click Setup Environment again. A half-built venv left by a failed run is rebuilt automatically on the next attempt.

Q: The run fails with "ns-process-data failed (COLMAP/SfM)"? A: First check the colmap.exe path (the Photo2Mesh: COLMAP plugin can download one). Then open 1_process.log in the job folder — the first line is the exact command, the tail is the error. Too little photo overlap, weak surface texture, or too few photos also make SfM fail; take more photos around the object with more overlap and retry.

Q: The training stage (ns-train splatfacto) fails? A: Check 2_train.log. Common causes: no usable NVIDIA CUDA GPU (verify cuda: true in the SMOKE= line of the setup log), or the gsplat CUDA extension failed to build (needs the CUDA toolkit + MSVC build tools).

Q: "gs-mesh failed or produced no PLY"? A: Check 3_mesh.log. Try another gs-mesh method (tsdf / o3dtsdf / dn / marching). Note that Nerfstudio / DN-Splatter command-line flags can drift across upstream versions — the exact command in the first log line helps identify a flag incompatibility.

Q: Reconstruct Mesh says "need >= 3 photos" or "no channel selected"? A: Stack mode requires the selected Channel to have at least 3 slices; if the dropdown is empty, click Refresh first and pick the image stack. Folder mode requires an existing photo directory.

Q: "Photo2Mesh: gsplat..." does not appear in the menu? A: The plugin is unticked by default in the Full Package. Re-run the installer and tick it, or tick it at the bottom of Developer ▸ Prototype Labs... ▸ Menu Item Manager, then restart Dragonfly.

Q: The mesh has the wrong size/orientation? A: This is inherent — a photos-only pipeline cannot recover absolute scale or orientation. Rescale and rotate the Mesh in Dragonfly using a known dimension.

10. Notes and known limitations

• The heaviest of the three Photo2Mesh plugins: the first Setup Environment can take a long time and downloads several GB; the venv is independent of Dragonfly and survives Dragonfly reinstalls.
• An NVIDIA CUDA GPU is required; environment setup additionally needs a CUDA toolkit, the MSVC build tools, git, and internet access.
• The result has an arbitrary scale and orientation and must be rescaled/reoriented manually after import.
• Nerfstudio / DN-Splatter CLI flags can drift across versions; if a stage fails, the corresponding 1_process.log / 2_train.log / 3_mesh.log records the exact command and error.
• The mesh is imported into Dragonfly vertex-by-vertex / face-by-face; very large meshes can take a while to import.
• Panel settings are saved automatically to %LOCALAPPDATA%\Photo2Mesh\gsplat_config.json; neither disabling the plugin nor updating its code deletes the environment or the settings.
• Job folders (under C:\Photo2MeshJobs by default) accumulate intermediate data over time and can be cleaned up manually.

11. References

• gsplat — Apache-2.0 Gaussian-Splatting rasterizer (PyPI package gsplat), the training backend of this plugin.
• Nerfstudio — Apache-2.0 neural rendering framework (PyPI package nerfstudio), providing the ns-process-data and ns-train splatfacto commands.
• DN-Splatter — Apache-2.0 surface-reconstruction extension providing the gs-mesh command: https://github.com/maturk/dn-splatter.
• COLMAP — the Structure-from-Motion engine invoked by ns-process-data; downloadable via the Photo2Mesh: COLMAP plugin.
• PyTorch CUDA wheel index — https://download.pytorch.org/whl/cu124 (switch to cu121 etc. to match your driver).
• Sibling plugins: Photo2Mesh: Meshroom and Photo2Mesh: COLMAP (each with its own user manual).