Open3D 网格工具 插件用户手册

Open3D Mesh Tools - User Manual

Dragonfly Prototype Apps · Open3D Mesh Tools...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Open3D 网格工具(Open3D Mesh Tools)是一个 Dragonfly 插件，它将开源几何处理库 Open3D 的专业网格（mesh）处理能力引入到 Dragonfly 中。你只需在场景中选中一个表面网格，选择一项操作（简化、平滑、清理缺陷、填补孔洞、计算法线、由顶点重建表面，或用 ICP 配准把一个网格对齐到另一个网格），设好参数，点击 Run 即可。处理结果会作为一个全新的网格发布回场景，原始网格保持不变。

本插件的底层引擎是 Open3D（官方网站 open3d.org），仅使用 CPU 版本的 wheel，不依赖 CUDA / GPU。为了不污染 Dragonfly 自带的 Python，Open3D 被安装在一个专用的虚拟环境（venv）中，并以子进程方式运行；Dragonfly 与该子进程之间通过临时 PLY 文件和 JSON 配置文件交换数据。因此，Open3D 从不被导入到 Dragonfly 自己的 Python 里。

依赖项仅 open3d 与 numpy 两个包，均从默认的 PyPI 官方源安装（无 torch、无 CUDA 源）。Open3D 采用 MIT 开源许可证，numpy 采用 BSD 许可证，均为宽松的商业友好许可证。

2. 适用场景

只要你从 CT 或显微数据中提取出了表面网格，而这些网格需要后处理，本插件就非常有用。典型场景包括：

• 精简巨大网格：将分割得到的面数极多的网格简化，以便用于仿真、3D 打印或加速渲染。
• 平滑与修复粗糙表面：处理骨骼、孔隙、纤维或工业零件等物体表面上的噪声与缺陷。
• 配准两次扫描：将同一物体的两次扫描对齐，例如前后对比（before/after）或与基准件进行计量学比对。
• 清理网格拓扑缺陷：删除重复顶点 / 面、退化三角形、非流形边等，得到更干净的网格。
• 由点云重建表面：把顶点看作点云，用 Poisson 或 Ball-Pivoting 重建出封闭表面。

3. 安装与启用

本插件作为 Prototype Apps 的一部分，通过完整安装包（Full Package）安装器部署：

1. 解压完整安装包，双击运行 `Install_FullPackage.bat`。

2. 在弹出的对话框中选择核心安装模式（Fresh 全新 / Compatible 兼容），并在插件列表中勾选 Open3D Mesh Tools...。

3. 点击 Install，等控制台提示完成。

4. 完全退出并重启 Dragonfly（菜单仅在启动时扫描）。

默认情况下，所有插件（包括本插件）在安装列表中都是未勾选的，你必须手动勾选 Open3D Mesh Tools 才会被部署。

重启后，菜单项出现在：Prototype Apps → Open3D Mesh Tools...（属于“Measurements & Analysis（测量与分析）”分组）。点击它会打开一个可停靠、可浮动的面板窗口。

以后你可以随时在 Dragonfly 内部修改启用状态：打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，在底部的 “Prototype Apps (Full Package)” 列表中勾选 = 部署，取消勾选 = 移除菜单项，重启 Dragonfly 生效。停用从不删除插件已搭建好的环境，重新启用立即可用。

4. 运行环境与首次配置

插件安装时不会下载任何东西。首次使用时，你需要在 Setup（环境）选项卡中点击 “Setup Environment” 按钮搭建一次性环境：

• 具体做什么：在插件代码目录旁边新建一个专用 venv，然后在该 venv 中执行 pip install open3d numpy。
• 下载体量：约几分钟，Open3D 是一个数百 MB 的 wheel。
• 是否需联网：需要（从 PyPI 下载 wheel）。
• 是否需 GPU：不需要，仅用 CPU，无 CUDA 依赖。
• 环境安装位置：venv 建在已安装的代码目录内（%LOCALAPPDATA%\comet\<Dragonfly版本>\pythonUserExtensions\GenericMenuItems\Open3DTools\venv）。
• 作业文件夹：默认在 C:\Open3DJobs 下，每次运行生成一个形如 o3d_<时间戳> 的子目录，用于存放 PLY 交换文件。

Base Python（构建用的基础解释器）：默认为空，此时使用本 Dragonfly 自带的 python.exe构建 venv（Dragonfly 2025.1 / 2027.1 自带一个完整的 CPython 3.10，其 venv 与 pip 可正常工作），因此你无需另外安装 Python。若某个版本的自带 Python 无可用 pip，程序会自动回退到系统上已有的 CPython。

失败时的替代方案：Open3D 仅为 CPython 3.8–3.12（Windows x86-64）提供 wheel。若自动构建失败，可在 Base Python 字段填入一个在此范围内、带 pip 的 CPython 路径（如 C:\Python312\python.exe）或 py -3.12，然后重新点击 Setup Environment。

5. 界面说明

面板顶部是一段蓝色提示文字，下方是两个选项卡（Setup 与 Operate），最底部是一个结果标签和一个只读的日志（Log）区。

5.1 Setup 选项卡（环境）

• Open3D venv python：文本框，显示当前 venv 的 python 路径；由 “Setup Environment” 成功后自动填写。
• Base Python (build)：文本框，留空=用本 Dragonfly 自带的 python.exe（推荐）；也可填一个路径或形如 py -3.12。
• Run mode：下拉框，可选 windows（默认）或 wsl。普通使用保持 windows 即可。
• Job root：文本框，作业根目录，默认 C:\Open3DJobs。
• Setup Environment 按钮：点击后构建 venv 并安装 open3d + numpy（一次性，约几分钟）。

5.2 Operate 选项卡（操作）

• Mesh A (source)：下拉框，选择作为输入（源）的场景网格；旁边的 Refresh 按钮重新枚举场景中的网格。下拉项会显示每个网格的顶点数 V、面数 F 与类型。
• Mesh B (target, ICP only)：下拉框，仅在 ICP 操作时可用（其他操作时自动置灰），用于选择对齐目标网格。
• Operation：下拉框，选择要执行的操作（共 7 项，见第 7 章）。切换操作时，下方的 Parameters 区会自动重建为该操作的参数。
• Parameters：参数区，根据当前操作动态生成输入控件（整数框 / 小数框 / 复选框 / 下拉框），鼠标悬停在控件上可看到参数说明。
• Result mesh title：文本框，结果网格的标题；留空则自动命名（如 “Open3D Smooth (Taubin / Laplacian)”）。
• Run 按钮（蓝底）：开始执行操作。
• Open Output Folder 按钮：在资源管理器中打开本次（或上次）作业文件夹。

6. 使用步骤

6.1 单网格操作（简化 / 平滑 / 清理 / 填孔 / 法线 / 重建）

1. 确保已完成第 4 章的 Setup Environment（Setup 选项卡上的 venv python 路径非空）。

2. 切到 Operate 选项卡，点击 Refresh 枚举场景网格。

3. 在 Mesh A 下拉框中选择要处理的网格（需是含三角面的表面网格；重建操作可以只需顶点）。

4. 在 Operation 中选择操作，并在 Parameters 区调整参数。

5. （可选）在 Result mesh title 中填写结果网格的名称。

6. 点击 Run。日志区会按百分比显示进度。

7. 完成后，结果作为一个新的 FaceVertexMesh 发布到场景；结果标签会显示新网格的顶点数与面数。点 Open Output Folder 可查看保存的 PLY 副本。

6.2 ICP 配准（网格 A 对齐到网格 B）

1. 点击 Refresh 枚举网格。

2. 在 Mesh A 中选择待对齐（源）的网格。

3. 在 Operation 中选择 Register (ICP) mesh A -> mesh B；此时 Mesh B 下拉框变为可用。

4. 在 Mesh B 中选择目标（基准）网格。

5. 调整 ICP 参数（method / max_correspondence_distance / max_iterations）。

6. 点击 Run。完成后，结果标签会报告拟合度 fitness 与 RMSE；经变换对齐后的网格 A 会作为新网格发布。

7. 参数说明

以下列出每个操作的参数、默认值与说明（与代码中的 OPERATIONS 定义完全一致）。

7.1 Simplify 简化（二次型抽稀）

7.2 Smooth 平滑（Taubin / Laplacian）

7.3 Clean 清理

清理操作在上述步骤之后会自动额外执行一次“删除未被引用顶点”。

7.4 Fill holes 填补孔洞

7.5 Compute normals 计算法线

7.6 Reconstruct 重建表面（Poisson / Ball-Pivoting）

7.7 Register (ICP) 配准

8. 输出结果

每次成功运行后，插件会在 Dragonfly 场景中生成一个全新的 FaceVertexMesh（面顶点网格），原始网格保持不变。你可以在对象树（object tree）中找到它并在 3D 视图中查看。

• 新网格名称：取自 Result mesh title；留空时自动命名（如 “Open3D Simplify (quadric decimation)”）。
• PLY 副本：每次运行的中间产物（输入 PLY、输出 PLY、config.json、status.json、results.json）都保存在作业文件夹 C:\Open3DJobs\o3d_<时间戳>\ 中，点 Open Output Folder 可直接打开。
• ICP 额外信息：除了发布经变换的网格 A 外，还会在结果标签中报告拟合度（fitness）与内点 RMSE，并得到一个 4×4 变换矩阵。

9. 常见问题与故障排除

问：点了 Run 却提示 “Open3D venv not set”（环境未设置）？

答：你还没搭建环境。先到 Setup 选项卡点击 Setup Environment，等 venv 建好（venv python 路径自动填写）后再回到 Operate 运行。

问：Operate 选项卡的网格下拉框是空的？

答：先点 Refresh。若仍为空，说明场景中没有 FaceVertexMesh 或 Mesh 对象；请先导入或生成一个表面网格（例如从 ROI / MultiROI 生成网格）。

问：Setup Environment 失败，提示无法安装 open3d？

答：首先确认网络可访问 PyPI。其次，Open3D 仅为 CPython 3.8–3.12 提供 wheel，若 Dragonfly 自带的 Python 版本不在此范围内，请在 Base Python 字段填入一个合适版本的 CPython（如 miniconda 的 3.12）后重试。

问：选了 Fill holes 却报错说需要 tensor API？

答：填补孔洞依赖 Open3D 的张量（tensor）API（open3d.t）。新版 Open3D 都包含它；若报错提示不可用，请重新运行 Setup Environment 以安装较新版本的 Open3D。

问：选了 ICP 却提示需要第二个网格？

答：ICP 需要两个网格。选中 ICP 操作后，Mesh B 下拉框会变为可用，请在其中选择目标（基准）网格后再运行。

10. 注意事项与已知限制

• 仅支持 CPU；Open3D 仅安装 CPU 版 wheel，不会使用 GPU。
• 输入必须是表面网格（FaceVertexMesh 或基类 Mesh）；除重建外，其余操作需要网格含有三角面。
• 结果以新 FaceVertexMesh 形式写回；写回采用逐面写入，对于数百万面的超大网格可能较慢。
• 网格数据通过临时 PLY 文件与 venv 子进程交换；请确保 Job root（默认 C:\Open3DJobs）所在磁盘有足够空间。
• 菜单仅在 Dragonfly 启动时扫描；启用 / 停用插件后需重启一次。
• 重建（尤其 Poisson）对无法线的点云会先自动估计法线，结果受点分布与参数影响较大，可能需要多次调参。

11. 参考资料

• Open3D 官方网站：https://www.open3d.org/
• Open3D 采用 MIT 许可证；numpy 采用 BSD 许可证。
• 安装 / 启用 / 卸载的完整说明，参见完整安装包（Full Package）随包附带的 README。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Environment & First-Run Setup

5. Interface Guide

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

Open3D Mesh Tools is a Dragonfly plugin that brings the professional mesh-processing capabilities of the open-source geometry library Open3D into Dragonfly. You pick a surface mesh in your scene, choose an operation (simplify, smooth, clean up defects, fill holes, compute normals, reconstruct a surface from vertices, or align one mesh to another with ICP registration), set the parameters, and click Run. The result is published back into the scene as a brand-new mesh, leaving the original untouched.

The underlying engine is Open3D (open3d.org), using only the CPU wheel — there is no CUDA / GPU dependency. To avoid polluting Dragonfly's own Python, Open3D is installed into a dedicated virtual environment (venv) and runs as a subprocess; Dragonfly and that subprocess exchange data through temporary PLY files and a JSON config file. As a result, Open3D is never imported into Dragonfly's own Python.

The only dependencies are open3d and numpy, both installed from the default PyPI index (no torch, no CUDA index). Open3D is MIT-licensed and numpy is BSD-licensed — both permissive, commercially friendly licenses.

2. Use Cases

This plugin is useful whenever meshes extracted from CT or microscopy data need post-processing. Typical scenarios include:

• Shrinking huge meshes: simplify very-high-triangle-count segmentation meshes for simulation, 3D printing, or faster rendering.
• Smoothing and repairing noisy surfaces: clean up noise and defects on bones, pores, fibers, or industrial parts.
• Aligning two scans: register two scans of the same object, e.g. before/after comparison or metrology against a reference part.
• Cleaning topology defects: remove duplicated vertices/faces, degenerate triangles, and non-manifold edges for a cleaner mesh.
• Reconstructing a surface from a point cloud: treat the vertices as a point cloud and rebuild a closed surface with Poisson or Ball-Pivoting.

3. Installation & Enabling

The plugin ships as part of Prototype Apps and is deployed with the Full Package installer:

1. Unzip the Full Package and double-click `Install_FullPackage.bat`.

2. In the dialog, pick the core install mode (Fresh / Compatible) and tick Open3D Mesh Tools... in the plugin list.

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

4. Quit and restart Dragonfly completely (menus are discovered only at startup).

By default every plugin (including this one) is unchecked in the installer list; you must tick Open3D Mesh Tools yourself for it to be deployed.

After the restart the menu item appears at: Prototype Apps → Open3D Mesh Tools... (in the “Measurements & Analysis” group). Clicking it opens a dockable, floatable panel.

You can change the enabled state later from inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, and use the checkbox next to Open3D Mesh Tools in the “Prototype Apps (Full Package)” list — tick = deploy, untick = remove the menu entry. Restart Dragonfly to apply. Disabling never deletes the plugin's already-built environment; re-enabling is instant.

4. Environment & First-Run Setup

Nothing is downloaded at install time. On first use, go to the Setup tab and click the “Setup Environment” button to build a one-time environment:

• What it does: creates a dedicated venv next to the plugin code, then runs pip install open3d numpy inside that venv.
• Download size: a couple of minutes; Open3D is a wheel of a few hundred MB.
• Internet: required (the wheels are fetched from PyPI).
• GPU: not required — CPU only, no CUDA dependency.
• Where it installs: the venv lives inside the installed code directory (%LOCALAPPDATA%\comet\<DragonflyVersion>\pythonUserExtensions\GenericMenuItems\Open3DTools\venv).
• Job folder: defaults to C:\Open3DJobs; each run creates an o3d_<timestamp> subfolder to hold the PLY exchange files.

Base Python (build interpreter): left blank by default, which means the venv is built from this Dragonfly's own python.exe (Dragonfly 2025.1 / 2027.1 bundle a full CPython 3.10 whose venv + pip work), so you need no separate Python install. If a given Dragonfly build's interpreter lacks a working pip, the tool automatically falls back to a system CPython.

Fallback if setup fails: Open3D only ships wheels for CPython 3.8–3.12 (Windows x86-64). If the automatic build fails, put a path to a CPython in that range with pip (e.g. C:\Python312\python.exe) or py -3.12 in the Base Python field, then click Setup Environment again.

5. Interface Guide

The panel has a short blue note at the top, two tabs (Setup and Operate), and at the bottom a result label plus a read-only Log area.

5.1 Setup tab (Environment)

• Open3D venv python: text field showing the current venv's python path; filled in automatically after a successful “Setup Environment”.
• Base Python (build): text field; blank = use this Dragonfly's own python.exe (recommended); or a path / py -3.12.
• Run mode: dropdown, windows (default) or wsl. Keep windows for normal use.
• Job root: text field, the job root directory; default C:\Open3DJobs.
• Setup Environment button: builds the venv and installs open3d + numpy (one-time, a couple of minutes).

5.2 Operate tab

• Mesh A (source): dropdown to pick the input (source) scene mesh; the Refresh button next to it re-enumerates scene meshes. Each entry shows vertex count V, face count F, and class.
• Mesh B (target, ICP only): dropdown, enabled only for the ICP operation (greyed out otherwise), used to pick the alignment target mesh.
• Operation: dropdown to choose the operation (7 in total; see Chapter 7). Switching the operation automatically rebuilds the Parameters area below for that operation.
• Parameters: a form built dynamically for the current operation (spin boxes / double spin boxes / checkboxes / dropdowns); hover a control to see its help tooltip.
• Result mesh title: text field for the result mesh title; blank = auto-named (e.g. “Open3D Smooth (Taubin / Laplacian)”).
• Run button (blue): starts the operation.
• Open Output Folder button: opens this (or the last) job folder in the file explorer.

6. Step-by-Step Usage

6.1 Single-mesh operations (simplify / smooth / clean / fill holes / normals / reconstruct)

1. Make sure you have completed Setup Environment from Chapter 4 (the venv python path on the Setup tab is not empty).

2. Switch to the Operate tab and click Refresh to enumerate scene meshes.

3. In the Mesh A dropdown, select the mesh to process (a triangle surface mesh; reconstruct can work from vertices only).

4. Pick an operation in Operation and adjust the values in the Parameters area.

5. (Optional) Enter a name in Result mesh title.

6. Click Run. The Log area shows progress as a percentage.

7. When finished, the result is published as a new FaceVertexMesh; the result label shows its vertex and face counts. Click Open Output Folder to see the saved PLY copy.

6.2 ICP registration (align mesh A to mesh B)

1. Click Refresh to enumerate meshes.

2. Select the mesh to align (source) in Mesh A.

3. In Operation, choose Register (ICP) mesh A -> mesh B; the Mesh B dropdown becomes enabled.

4. Select the target (reference) mesh in Mesh B.

5. Adjust the ICP parameters (method / max_correspondence_distance / max_iterations).

6. Click Run. When finished, the result label reports the fitness and RMSE, and the transformed mesh A is published as a new mesh.

7. Parameter Reference

The following tables list every operation's parameters, defaults, and descriptions (matching the OPERATIONS definition in the code exactly).

7.1 Simplify (quadric decimation)

7.2 Smooth (Taubin / Laplacian)

7.3 Clean

The clean operation always additionally removes unreferenced vertices after the steps above.

7.4 Fill holes

7.5 Compute normals

7.6 Reconstruct surface (Poisson / Ball-Pivoting)

7.7 Register (ICP)

8. Outputs

After each successful run, the plugin creates a brand-new FaceVertexMesh in the Dragonfly scene, leaving the original mesh untouched. You can find it in the object tree and view it in the 3D view.

• New mesh name: taken from Result mesh title; auto-named when blank (e.g. “Open3D Simplify (quadric decimation)”).
• PLY copies: all intermediate artifacts of each run (input PLY, output PLY, config.json, status.json, results.json) are saved in the job folder C:\Open3DJobs\o3d_<timestamp>\; click Open Output Folder to open it.
• ICP extra info: besides publishing the transformed mesh A, the result label reports the fitness and inlier RMSE, and a 4×4 transform matrix is produced.

9. FAQ & Troubleshooting

Q: I clicked Run but it says “Open3D venv not set”.

A: You have not built the environment yet. Go to the Setup tab, click Setup Environment, wait for the venv to be built (the venv python path fills in automatically), then run from the Operate tab.

Q: The mesh dropdown on the Operate tab is empty.

A: Click Refresh first. If it is still empty, there is no FaceVertexMesh or Mesh object in the scene; import or generate a surface mesh first (for example, generate a mesh from an ROI / MultiROI).

Q: Setup Environment fails saying it cannot install open3d.

A: First confirm you have internet access to PyPI. Second, Open3D only ships wheels for CPython 3.8–3.12; if this Dragonfly's Python is outside that range, set a matching CPython (e.g. miniconda 3.12) in the Base Python field and retry.

Q: I chose Fill holes but it says the tensor API is required.

A: Fill holes relies on Open3D's tensor API (open3d.t). Recent Open3D releases include it; if you get this error, re-run Setup Environment to install a recent Open3D.

Q: I chose ICP but it says a second mesh is required.

A: ICP needs two meshes. After selecting the ICP operation, the Mesh B dropdown becomes enabled — pick the target (reference) mesh there before running.

10. Notes & Known Limitations

• CPU only; Open3D installs only the CPU wheel and never uses a GPU.
• The input must be a surface mesh (FaceVertexMesh or base Mesh); apart from reconstruct, operations require the mesh to have triangle faces.
• The result is written back as a new FaceVertexMesh; the write-back is done face-by-face, which can be slow for very large meshes with millions of faces.
• Mesh data is exchanged with the venv subprocess through temporary PLY files; make sure the disk holding Job root (default C:\Open3DJobs) has enough free space.
• Menus are discovered only at Dragonfly startup; a restart is needed after enabling or disabling the plugin.
• Reconstruct (especially Poisson) auto-estimates normals for point clouds without them; results depend heavily on point distribution and parameters and may need several tuning passes.

11. References

• Open3D official website: https://www.open3d.org/
• Open3D is MIT-licensed; numpy is BSD-licensed.
• For the full install / enable / uninstall story, see the README bundled with the Full Package.