网格修复与重划分 (PyMeshLab) 插件用户手册

Mesh Repair & Remesh (PyMeshLab) - User Manual

Dragonfly Prototype Apps · Mesh Repair & Remesh (PyMeshLab)...

版本 Version 1.0 · 2026-07-09

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

网格修复与重划分 (PyMeshLab) 是一个 Dragonfly 插件,用于对场景中的任意表面网格执行专业级的网格修复与重划分操作。您选择一个网格,挑选一种操作,设置参数并点击 Run;计算结果会作为一个全新的网格发布回场景,原始网格保持不变。

底层引擎是 PyMeshLab —— 著名开源网格处理软件 MeshLab 的 Python 绑定。所有几何计算都在 CPU 上完成,无需 GPU。插件提供以下六种操作:屏蔽泊松 (Screened-Poisson) 表面重建、各向同性显式重划分、二次误差边折叠简化(减面)、填补孔洞、修复清理(移除非流形边/顶点及重复/未引用元素),以及 Taubin / Laplacian 平滑。这些正是姊妹插件 Open3D 所欠缺的网格修复与重划分能力。

关于许可证与运行隔离

PyMeshLab (MeshLab) 采用 GPL-3.0 许可。为了不让 GPL 代码进入 Dragonfly 的专有进程,本插件对 PyMeshLab 做了严格隔离:PyMeshLab 只被安装到插件自建的独立虚拟环境 (venv) 中,并且仅在一个独立子进程里被导入运行,绝不导入 Dragonfly 进程。Dragonfly 一侧与该子进程之间只通过普通的 PLY 网格文件 + JSON 配置/状态/结果文件交换数据,没有任何进程内链接。该子进程即为许可隔离边界。

这种设计意味着:PyMeshLab 的 GPL 授权仅约束该独立 venv 子进程,不影响 Dragonfly 本体。所有面向对象模型 (ORSModel) 的读写都留在 Dragonfly 一侧,子进程从不接触 Dragonfly 的对象模型。

2. 适用场景

本插件适用于任何需要在进一步分析、仿真或打印之前,先对从 CT 或显微数据中提取出来的网格进行修复与预处理的场景:

• 仿真 / 3D 打印前处理:对分割得到的网格进行清理与重划分,得到干净、均匀、拓扑良好的三角网格。
• 修补分割网格缺陷:填补分割网格中的孔洞,移除非流形几何(非流形边/顶点),清除重复与未引用的顶点/面。
• 巨大网格的简化(减面):用二次误差边折叠将百万面级网格降到可管理的规模,同时保持边界与法线方向。
• 由点云重建封闭表面:把网格顶点(带法线)当作有向点云,用屏蔽泊松重建出一张水密 (watertight) 表面。
• 表面去噪 / 平滑:用 Taubin(收缩小)或 Laplacian 平滑抑制阶梯状伪影。

3. 安装与启用

本插件作为 Prototype Apps 的一员随 Full Package(完整安装包) 分发。安装步骤如下:

1. 把 Full Package 压缩包解压到任意较短的目录(如 C:\PL\;不要放在很深的下载目录或 OneDrive 重定向的桌面下)。

2. 双击 `Install_FullPackage.bat`。在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),然后在 Prototype Apps 列表里勾选 “Mesh Repair & Remesh (PyMeshLab)”。

3. 点 Install,等待控制台完成后完全退出并重启 Dragonfly。

本插件在安装列表中默认未勾选(所有插件默认关闭)。您必须手动勾选它,重启后才会在菜单中出现。

重启后,菜单项出现在:Prototype Apps ▸ Mesh Repair & Remesh (PyMeshLab)...(位于 “Measurements & Analysis / 测量与分析” 分组)。点击后打开一个可停靠 / 可浮动的面板。

以后修改勾选

最方便的做法是在 Dragonfly 内修改:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,底部 “Prototype Apps (Full Package)” 列表中每个应用都有一个复选框——勾选=部署菜单项,取消=移除菜单项。重启 Dragonfly 生效。 停用从不删除插件已搭好的环境 (venv),重新启用立即可用。

另一种方式是随时重跑安装器(它会记住上次的勾选作为新默认值)。卸载请双击 `Uninstall_FullPackage.bat`——它会移除菜单项与插件,但保留已搭好的 venv 环境(结束时会列出其路径,供您需要时手动删除以腾出磁盘空间)。

4. 运行环境与首次配置

首次使用前必须搭建插件的专用运行环境。安装 Full Package 时不会下载任何计算依赖;环境是在您首次使用时,在插件的 Setup(设置) 选项卡里一键搭建的。

Setup Environment 具体做什么

在 Setup 选项卡点击 “Setup Environment (build venv + pip install pymeshlab numpy)” 按钮后,插件会:

1. 默认使用 Dragonfly 自带的 Python 在插件代码目录旁新建一个独立虚拟环境 (venv)。

2. 在该 venv 中执行 pip install pymeshlab numpy,从 PyPI 下载并安装 PyMeshLab 与 NumPy。

3. 把生成的 venv 解释器路径记录到设置里(下方 “PyMeshLab venv python” 字段会自动填入),供后续所有计算调用。

Setup 选项卡的其他字段

• PyMeshLab venv python:venv 的 python 路径。留空即可,由 “Setup Environment” 自动填入;搭好后此处会显示解释器完整路径。
• Base Python (build):用于构建 venv 的基础解释器。留空 = 使用本 Dragonfly 自带的 python.exe(推荐);也可填一个具体路径或形如 py -3.12 的命令。
• Run mode:运行模式,windows(默认)或 wsl。一般保持默认 windows。
• Job root:作业根目录,默认 C:\PyMeshLabJobs。每次运行会在其下新建一个带时间戳的子文件夹存放中间文件与结果 PLY。

失败时的替代方案:PyMeshLab 官方为 CPython 3.8–3.12(Windows x86-64)提供 wheel。若本 Dragonfly 自带的 Python 版本不在此范围内,pip install pymeshlab 会失败——此时在 Base Python (build) 字段填入一个 3.8–3.12 的 Python(例如 py -3.12 或某个 Miniconda 的 python.exe),再重新点 “Setup Environment”。搭建过程的完整输出会显示在面板底部的 Log 区域,便于排错。

5. 界面说明

面板顶部有一段蓝色说明文字,提示 PyMeshLab 在独立 venv 子进程中运行;主体是两个选项卡 Setup 与 Operate;面板底部有一个绿色结果标签和一个只读的 Log 日志区。

Setup 选项卡

用于一次性搭建运行环境,包含 “PyMeshLab venv python”“Base Python (build)”“Run mode”“Job root” 四个字段和一个 Setup Environment 按钮(详见第 4 章)。

Operate 选项卡

日常操作在这里进行,从上到下分为若干分组:

• Input mesh(输入网格):一个 “Mesh (source)” 下拉框列出场景中的网格,右侧 Refresh 按钮刷新列表。列表项会显示网格标题及顶点数 V / 面数 F 与类型。选屏蔽泊松操作时,下方会出现灰色提示 “Poisson treats the mesh vertices as a point cloud.(泊松把网格顶点当作点云处理)”。
• Operation(操作):一个下拉框,列出六种操作(见第 7 章)。切换操作时,下方参数区会动态重建为该操作对应的参数控件。
• Parameters(参数):随所选操作自动生成的参数控件——整数用微调框 (spinbox)、浮点数用双精度微调框、布尔量用复选框、多选项用下拉框。把鼠标悬停在控件上可看到该参数的说明提示 (tooltip)。
• Output(输出):一个 “Result mesh title(结果网格标题)” 文本框。留空则自动命名(例如 “PyMeshLab Isotropic explicit remeshing”)。

选项卡底部有两个按钮:Run(蓝色,开始计算)和 Open Output Folder(打开最近一次作业的输出文件夹)。

6. 使用步骤

完成第 4 章的环境搭建后,一次典型的端到端操作如下:

1. 在场景中准备好一个表面网格(FaceVertexMesh 或基础 Mesh)。它可以来自分割结果、点云重建或其他插件的输出。

2. 打开 Prototype Apps ▸ Mesh Repair & Remesh (PyMeshLab)...,切换到 Operate 选项卡。

3. 点 Refresh,在 “Mesh (source)” 下拉框中选择要处理的网格。

4. 在 Operation 下拉框中选择一种操作(泊松 / 重划分 / 简化 / 填孔 / 修复 / 平滑)。

5. 在 Parameters 区调整参数(默认值即可作为起点;参数含义见第 7 章)。

6. (可选)在 Output 的 “Result mesh title” 里填入结果网格的名称。

7. 点 Run。底部 Log 区会流式显示进度(读取网格 → 应用滤镜 → 写出结果),结果标签会显示 “Running…”。

8. 完成后,结果标签变为 “Done. Published mesh: V=… F=…”,同时场景中出现一个新的 FaceVertexMesh;原始网格保持不变。可点 Open Output Folder 查看该次作业保存的 PLY 副本。

若尚未搭建环境(venv python 为空)或未选择输入网格,点 Run 会在 Log 里给出明确提示,并不会开始计算。参数在提交前会先做一次校验(例如减面时若目标面数为 0,则保留比例 reduction_ratio 必须在 (0, 1] 内)。

7. 参数说明

下表按操作列出全部参数及其默认值。参数控件由代码中的操作注册表动态生成,以下取值与默认值与代码完全一致。

屏蔽泊松重建 Screened-Poisson reconstruction (from points)

把输入网格的顶点当作有向点云(丢弃原有面片),先估计法线,再做屏蔽泊松表面重建,输出一张水密表面。

各向同性显式重划分 Isotropic explicit remeshing

简化(二次误差边折叠减面)Simplify (quadric edge-collapse decimation)

填补孔洞 Close holes

修复清理 Repair

按下列开关逐步清理网格;默认全部开启。

平滑 Smooth (Taubin / Laplacian)

8. 输出结果

运行成功后,插件产生两类输出:

• 场景中的新网格:计算结果作为一个新的 FaceVertexMesh 发布回 Dragonfly 场景。它是一个独立对象,原始输入网格保持不变。您可以像任何网格一样在 3D 视图中查看、着色、测量或供其他插件继续处理。
• 磁盘上的 PLY 副本:每次运行会在作业根目录(默认 C:\PyMeshLabJobs)下新建一个带时间戳的作业文件夹(形如 pml_<时间戳>\),其中保存了结果网格的 PLY 副本,以及运行时的配置 / 状态 / 结果 JSON 文件。点 Open Output Folder 可直接打开该文件夹。

运行完成后,面板底部结果标签会给出新网格的顶点数与面数,例如 “Done. Published mesh: V=… F=…”;Log 区会记录形如 “操作 -> V=… F=…(from V=… F=…)” 的前后对比,便于确认减面 / 重划分 / 填孔的效果。

9. 常见问题与故障排除

问:点 Run 后 Log 提示 “PyMeshLab venv not set”,怎么办?

答:说明还没搭建运行环境。请切到 Setup 选项卡,点 Setup Environment 完成一次性搭建(需联网,数分钟),待 “PyMeshLab venv python” 字段自动填入后再回到 Operate 选项卡运行。

问:Setup Environment 失败,提示无法安装 pymeshlab,怎么办?

答:最常见原因是本 Dragonfly 自带的 Python 版本不在 PyMeshLab 提供 wheel 的范围内(CPython 3.8–3.12,Windows x86-64)。请在 Base Python (build) 字段填入一个 3.8–3.12 的 Python(如 py -3.12 或某 Miniconda 的 python.exe),再重新点 Setup Environment。其次请确认网络可访问 PyPI。完整错误输出见 Log 区。

问:菜单里找不到 “Mesh Repair & Remesh (PyMeshLab)...”?

答:两点最常见:(1) 安装时没有勾选它(所有插件默认关闭)——请在 Menu Item Manager 里勾选,或重跑安装器时勾选;(2) 勾选后没有重启 Dragonfly——菜单只在启动时扫描,任何启用 / 停用改动都需要完全退出并重启 Dragonfly 一次。

问:运行报 “operation produced an empty mesh(操作产生了空网格)” 或 “input mesh has no vertices”?

答:前者常见于参数过激(例如减面比例过小、泊松深度不当),请放宽参数后重试;后者说明所选对象没有可用顶点,请点 Refresh 重新选择一个包含实际几何的网格。修复 / 填孔类操作需要输入本身就是三角网格。

问:处理很大的网格很慢?

答:网格与 Dragonfly 之间通过逐面写回发布,面数达数百万时会较慢。建议先用简化(减面)把网格规模降下来,或对局部网格操作;所有计算均为纯 CPU。

10. 注意事项与已知限制

• GPL 隔离:PyMeshLab 采用 GPL-3.0,仅在插件独立 venv 子进程中运行,绝不进入 Dragonfly 进程;两者只通过 PLY + JSON 文件交换数据。
• 纯 CPU:所有操作均在 CPU 上完成,无 CUDA 依赖,不需要 GPU。
• 首次需联网:仅在 Setup Environment 时需要访问 PyPI 下载 wheel;之后离线也可运行。
• 输入要求:除屏蔽泊松把顶点当点云外,其余操作(重划分 / 简化 / 填孔 / 修复 / 平滑)都需要输入是三角网格;多边形面会按简单扇形三角化后再处理。
• 结果始终是新对象:插件从不修改原网格,而是发布一个新的 FaceVertexMesh。
• 滤镜名兼容:不同 PyMeshLab 版本的滤镜命名略有差异(2022.2 前后),插件会自动依次尝试当前名与旧别名,以兼容较宽的版本范围。
• 大网格性能:逐面发布与 PLY 往返在百万面级会较慢、较占内存,建议先减面。

11. 参考资料

• PyMeshLab 文档:https://pymeshlab.readthedocs.io/
• MeshLab 官网:https://www.meshlab.net/
• GPL-3.0 许可证:https://www.gnu.org/licenses/gpl-3.0.html
• 本插件随附文档:插件文件夹内的 README.md(功能与安装概述)。
• Full Package 安装 / 启用 / 卸载说明:完整安装包根目录的 UserManual_用户手册.docx 与安装器 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

Mesh Repair & Remesh (PyMeshLab) is a Dragonfly plugin that applies professional mesh repair and remeshing operations to any surface mesh in your scene. You pick a mesh, choose an operation, set the parameters, and click Run; the result is published back into the scene as a new mesh, leaving the original untouched.

The underlying engine is PyMeshLab — the Python binding to the well-known open-source mesh-processing application MeshLab. All geometry runs on the CPU (no GPU required). The plugin exposes six operations: Screened-Poisson surface reconstruction, isotropic explicit remeshing, quadric edge-collapse decimation (simplify), close holes, repair (remove non-manifold edges/vertices plus duplicate/unreferenced clean-up), and Taubin / Laplacian smoothing. These are exactly the mesh repair/remesh operations the sibling Open3D plugin lacks.

About the licence and run-time isolation

PyMeshLab (MeshLab) is GPL-3.0-only. To keep GPL code out of Dragonfly's proprietary process, the plugin isolates PyMeshLab strictly: PyMeshLab is installed only into the plugin's own dedicated virtual environment (venv) and is imported only inside a separate subprocess — it is never imported into the Dragonfly process. The Dragonfly side and that subprocess exchange data only as plain PLY mesh files plus JSON config/status/result files, with no in-process linkage. That subprocess IS the licence isolation boundary.

This design means PyMeshLab's GPL terms bind only the dedicated venv subprocess and do not affect Dragonfly itself. All object-model (ORSModel) reads/writes stay on the Dragonfly side; the subprocess never touches the Dragonfly object model.

2. Use Cases

The plugin is useful whenever meshes extracted from CT or microscopy data need repair and clean-up before further analysis, simulation, or printing:

• Prep for simulation / 3D printing: clean and remesh a segmentation mesh into a tidy, uniform, topologically sound triangle mesh.
• Fix segmentation-mesh defects: close holes, remove non-manifold geometry (edges/vertices), and clear duplicate and unreferenced vertices/faces.
• Simplify huge meshes (decimation): bring million-face meshes down to a manageable size with quadric edge-collapse while preserving the boundary and normals.
• Reconstruct a watertight surface from a point cloud: treat the mesh vertices (with normals) as an oriented point cloud and run screened Poisson.
• Surface denoising / smoothing: reduce staircase artifacts with Taubin (low shrinkage) or Laplacian smoothing.

3. Installation & Enabling

This plugin ships as one of the Prototype Apps inside the Full Package. To install:

1. Unzip the Full Package to any short folder (e.g. C:\PL\; avoid a deep Downloads path or a OneDrive-redirected Desktop).

2. Double-click `Install_FullPackage.bat`. In the dialog, choose the core install mode (Fresh / Compatible), then tick "Mesh Repair & Remesh (PyMeshLab)" in the Prototype Apps list.

3. Click Install, wait for the console to finish, then quit and restart Dragonfly completely.

This plugin is unticked by default (all plugins default to OFF). You must tick it yourself for the menu entry to appear after a restart.

After the restart the menu entry appears under Prototype Apps ▸ Mesh Repair & Remesh (PyMeshLab)... (in the "Measurements & Analysis" group). Clicking it opens a dockable / floating panel.

Changing your choice later

The easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager. The "Prototype Apps (Full Package)" list at the bottom has one checkbox per app — tick to deploy the menu entry, untick to remove it. 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). To uninstall, double-click `Uninstall_FullPackage.bat` — it removes the menu items and plugins but keeps any built venv environments (their paths are listed at the end so you can delete them manually to reclaim disk space).

4. Environment & First-Run Setup

Before first use you must build the plugin's dedicated run-time environment. Installing the Full Package downloads no compute dependencies; the environment is built on first use, from the plugin's Setup tab.

What Setup Environment does

On the Setup tab, click "Setup Environment (build venv + pip install pymeshlab numpy)". The plugin then:

1. Creates a dedicated virtual environment (venv) next to the plugin code, using Dragonfly's own Python by default.

2. Runs pip install pymeshlab numpy inside that venv, downloading PyMeshLab and NumPy from PyPI.

3. Records the resulting venv interpreter path in the settings (the "PyMeshLab venv python" field fills in automatically), to be used for every subsequent run.

Other fields on the Setup tab

• PyMeshLab venv python: the venv's python path. Leave blank — "Setup Environment" fills it in; once built it shows the full interpreter path.
• Base Python (build): the base interpreter used to build the venv. Blank = this Dragonfly's own python.exe (recommended); you may also enter a path or a command such as py -3.12.
• Run mode: windows (default) or wsl. Normally leave it on windows.
• Job root: the job root folder, default C:\PyMeshLabJobs. Each run creates a timestamped subfolder there for intermediate files and the result PLY.

Fallback if it fails: PyMeshLab ships wheels for CPython 3.8–3.12 (Windows x86-64). If this Dragonfly's bundled Python is outside that range, pip install pymeshlab fails — enter a 3.8–3.12 Python in the Base Python (build) field (e.g. py -3.12 or a Miniconda python.exe) and click Setup Environment again. The full build output streams to the Log area at the bottom of the panel for troubleshooting.

5. Interface Guide

A blue note at the top of the panel reminds you that PyMeshLab runs in a dedicated venv subprocess. The body has two tabs, Setup and Operate; at the bottom sit a green result label and a read-only Log area.

Setup tab

Used for the one-time environment build. It contains the four fields "PyMeshLab venv python", "Base Python (build)", "Run mode", and "Job root", plus a Setup Environment button (see Chapter 4).

Operate tab

Where day-to-day work happens, grouped top to bottom:

• Input mesh: a "Mesh (source)" dropdown lists the scene meshes, with a Refresh button on the right to reload it. Each entry shows the mesh title plus its vertex count V / face count F and class. When the Poisson operation is chosen, a grey hint appears below: "Poisson treats the mesh vertices as a point cloud."
• Operation: a dropdown listing the six operations (see Chapter 7). Switching operation rebuilds the parameter area below with that operation's controls.
• Parameters: controls generated automatically for the chosen operation — integers use a spinbox, floats a double spinbox, booleans a checkbox, choices a dropdown. Hover a control to see its parameter tooltip.
• Output: a "Result mesh title" text field. Leave it blank for an auto name (e.g. "PyMeshLab Isotropic explicit remeshing").

At the bottom of the tab are two buttons: Run (blue, starts the computation) and Open Output Folder (opens the most recent job's output folder).

6. Step-by-Step Usage

After building the environment (Chapter 4), a typical end-to-end run looks like this:

1. Have a surface mesh ready in the scene (a FaceVertexMesh or a base Mesh). It can come from a segmentation, a point-cloud reconstruction, or another plugin's output.

2. Open Prototype Apps ▸ Mesh Repair & Remesh (PyMeshLab)... and switch to the Operate tab.

3. Click Refresh and pick the mesh to process in the "Mesh (source)" dropdown.

4. Choose an operation in the Operation dropdown (Poisson / remesh / decimate / close holes / repair / smooth).

5. Adjust the values in the Parameters area (the defaults are a fine starting point; see Chapter 7 for meanings).

6. (Optional) type a name for the result in the Output "Result mesh title" field.

7. Click Run. The Log area streams progress (reading mesh -> applying filter -> writing result) and the result label shows "Running…".

8. When finished, the result label reads "Done. Published mesh: V=… F=…" and a new FaceVertexMesh appears in the scene; the original mesh is unchanged. Click Open Output Folder to inspect the PLY copy saved for that run.

If the environment is not built yet (venv python is empty) or no input mesh is selected, clicking Run prints a clear message in the Log and does not start the computation. Parameters are validated before submission (for example, when decimating with a target face count of 0, the reduction_ratio must be within (0, 1]).

7. Parameter Reference

The tables below list every parameter and its default, per operation. The controls are generated dynamically from the plugin's operation registry; the values and defaults below match the code exactly.

Screened-Poisson reconstruction (from points)

Treats the input mesh's vertices as an oriented point cloud (the original faces are dropped), estimates normals, then runs screened-Poisson reconstruction to output a watertight surface.

Isotropic explicit remeshing

Simplify (quadric edge-collapse decimation)

Close holes

Repair

Cleans the mesh step by step using the toggles below; all default to on.

Smooth (Taubin / Laplacian)

8. Outputs

A successful run produces two kinds of output:

• A new mesh in the scene: the result is published back into the Dragonfly scene as a new FaceVertexMesh. It is a standalone object and the original input mesh is left unchanged. You can view, colour, measure, or feed it into other plugins like any mesh.
• A PLY copy on disk: each run creates a timestamped job folder under the Job root (default C:\PyMeshLabJobs, e.g. pml_<timestamp>\) containing a PLY copy of the result plus the run's config/status/result JSON files. Click Open Output Folder to open it directly.

When the run finishes, the result label at the bottom shows the new mesh's vertex and face counts, e.g. "Done. Published mesh: V=… F=…"; the Log records a before/after summary like "operation -> V=… F=… (from V=… F=…)", making it easy to confirm the effect of decimation / remeshing / hole closing.

9. FAQ & Troubleshooting

Q: After clicking Run, the Log says "PyMeshLab venv not set" — what now?

A: The run-time environment has not been built yet. Go to the Setup tab and click Setup Environment for the one-time build (needs internet, a few minutes). Once the "PyMeshLab venv python" field fills in, return to the Operate tab and run.

Q: Setup Environment fails saying it cannot install pymeshlab — how do I fix it?

A: The most common cause is that this Dragonfly's bundled Python is outside the range for which PyMeshLab ships wheels (CPython 3.8-3.12, Windows x86-64). Enter a 3.8-3.12 Python in the Base Python (build) field (e.g. py -3.12 or a Miniconda python.exe) and click Setup Environment again. Also confirm PyPI is reachable. See the Log area for the full error output.

Q: I can't find "Mesh Repair & Remesh (PyMeshLab)..." in the menu.

A: Two common reasons: (1) it was not ticked at install time (all plugins default to OFF) — tick it in the Menu Item Manager, or when re-running the installer; (2) you didn't restart after ticking — menus are scanned only at startup, so every enable/disable change needs one full quit and restart of Dragonfly.

Q: The run reports "operation produced an empty mesh" or "input mesh has no vertices".

A: The former often means the parameters were too aggressive (e.g. too small a decimation ratio or an inappropriate Poisson depth) — relax them and retry. The latter means the selected object has no usable vertices — click Refresh and pick a mesh with real geometry. Repair/close-holes operations require the input to already be a triangle mesh.

Q: Processing a very large mesh is slow.

A: The mesh is published back to Dragonfly face by face, which is slow at millions of faces. Consider using Simplify (decimation) first to reduce the mesh, or operating on a local sub-mesh; all compute is CPU-only.

10. Notes & Known Limitations

• GPL isolation: PyMeshLab is GPL-3.0 and runs only in the plugin's dedicated venv subprocess, never in the Dragonfly process; the two exchange data only via PLY + JSON files.
• CPU-only: all operations run on the CPU, with no CUDA dependency; no GPU is needed.
• Internet on first use: only Setup Environment needs internet (to download wheels from PyPI); afterwards it runs offline.
• Input requirement: apart from Screened-Poisson (which uses the vertices as a point cloud), all operations (remesh / decimate / close holes / repair / smooth) require a triangle-mesh input; polygonal faces are fan-triangulated before processing.
• Result is always a new object: the plugin never modifies the original mesh; it publishes a new FaceVertexMesh.
• Filter-name compatibility: PyMeshLab filter names differ slightly between releases (around 2022.2). The plugin tries the current name then legacy aliases in turn, to work across a wide wheel range.
• Large-mesh performance: the per-face publish and the PLY round-trip are slower and more memory-hungry at millions of faces — decimate first.

11. References

• PyMeshLab documentation: https://pymeshlab.readthedocs.io/
• MeshLab website: https://www.meshlab.net/
• GPL-3.0 licence: https://www.gnu.org/licenses/gpl-3.0.html
• Bundled with this plugin: the README.md in the plugin folder (feature and install overview).
• Full Package install / enable / uninstall details: the UserManual_用户手册.docx in the Full Package root and the installer README.