CGAL Mesh_3 四面体网格插件用户手册

CGAL Mesh_3 (Panel) - User Manual

Dragonfly Prototype Apps · CGAL Mesh_3 (Panel)...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

1.1 工作原理

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

5.1 Input (from Dragonfly)——输入分组

5.2 Output & Executable——输出与可执行程序分组

5.3 Mesh_3 Criteria (sizes in VOXELS)——网格质量准则分组

5.4 Mesh Optimization——网格优化分组

5.5 操作按钮、日志与完成对话框

6. 使用步骤

6.1 基本流程（端到端）

6.2 网格尺寸参数的选择建议

6.3 查看与使用结果

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

CGAL Mesh_3 (Panel) 插件把 Dragonfly 中的分割结果——多材料 Multi-ROI、二值 ROI 或整数标签 Channel——直接转换为可用于数值仿真的四面体（体）网格。生成的网格以 .vtu 文件（可选附加 MEDIT .mesh 文件）写出，位于 Dragonfly 的真实世界坐标系中，每个四面体都带有 MaterialID 单元属性（等于原始标签值），可直接在 ParaView 或有限元/仿真软件中使用。

底层引擎是开源计算几何库 CGAL 的 Mesh_3 三维网格生成组件（插件针对 CGAL 5.5+/6.0 构建）：先通过标签图像网格域（create_labeled_image_mesh_domain）建立多材料域，再由 make_mesh_3 生成四面体网格，并可选运行 Perturb、Exude、Lloyd、ODT 质量优化器。全部网格计算都在独立的本地可执行程序 cgal_mesher.exe 中完成——CGAL 不会被载入 Dragonfly 自带的 Python 环境，对 Dragonfly 本体零侵入。

许可证要点：插件随 Prototype Apps 完整安装包（Full Package）分发；网格化核心 cgal_mesher.exe 基于开源组件 CGAL、GMP/MPFR 与 nlohmann-json 构建，随插件一并附带所需运行库（gmp-10.dll、mpfr-6.dll 及 MSVC 运行时 DLL），以外部子进程方式调用。各开源组件的具体许可条款请参见其官方项目页面。

• 三类输入：Multi-ROI（多材料）、ROI（二值）、整数标签 Channel。
• 输出真实世界坐标：完整携带原点、体素间距与方向（4×4 仿射矩阵），配准/旋转后的数据也能正确落位。
• 材料保留：每个四面体的 MaterialID 等于其原始标签值，多材料网格无需任何重映射。
• 质量可控：面角度/面尺寸/面距离/单元尺寸/半径-边比 5 项 Mesh_3 准则 + 4 种优化器开关。
• 结果统计：每次运行同时写出 _result.json（顶点/四面体数、各材料四面体数、包围盒、耗时、所用参数）。

1.1 工作原理

1. 面板在 Dragonfly 会话内（进程内）直接读取所选对象的标签体数据，以及完整的体素到世界几何（原点 + 间距 + 方向，编码为 4×4 voxel_to_world 仿射矩阵）。

2. 数据以 labels.npy + metadata.json 的形式导出到本次运行专属的作业文件夹（标签自动收窄为 uint8 或 uint16）。

3. cgal_mesher.exe 在体素空间中运行 CGAL Mesh_3（质量尺寸参数以体素为单位），并在体积四周自动补一圈零值边界，保证贴到图像边缘的目标也能生成完整外表面。

4. 导出网格顶点时（选择 World 输出模式）按 voxel_to_world 矩阵映射回 Dragonfly 世界坐标，写出 .vtu（可选 .mesh）与 _result.json 统计文件。

网格化在后台工作线程中运行，期间 Dragonfly 界面保持响应；运行期间 Generate Mesh 按钮被禁用，同一时间只有一个网格任务。

2. 适用场景

凡是需要在分割后的三维图像数据上进行物理仿真的用户，都可以用本插件把分割结果一步转换成仿真软件可读的体网格：

• 有限元应力、传热、流体、电磁等仿真的前处理（体网格生成）。
• 铸件、增材制造零件等工业 CT 数据的仿真建模。
• 材料科学：电池电极、多孔材料等微观结构。
• 生命科学：骨骼与组织结构。
• 多材料网格化：Multi-ROI 的每个类别（相）在网格中保留为一种独立材料，便于给不同相赋不同材料属性。
• 结果可在 ParaView 中查看，或送入 Gmsh / NGSolve / Abaqus 等仿真工具链。

3. 安装与启用

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

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

2. 双击 `Install_FullPackage.bat`。

3. 在弹出的安装对话框中，于 Prototype Apps 列表里勾选 CGAL Mesh_3 (Panel)...（位于 Simulation & Meshing 分组）。注意：所有插件默认不勾选，必须手动勾选本插件。

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

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

重启后，菜单入口出现在 Prototype Apps ▸ CGAL Mesh_3 (Panel)...。点击后面板停靠在 Dragonfly 主窗口右侧，标签页名为 "CGAL Mesh_3"，可折叠、可移动、可浮动为独立窗口。

以后启用/停用：打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，在底部 "Prototype Apps (Full Package)" 列表中勾选或取消本插件，重启 Dragonfly 生效。停用只移除菜单项，不会删除插件的任何配置；重新勾选后立即可用。也可以随时重跑安装器（上次的勾选就是新默认值）：%LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat。

• 插件包安装位置：%LOCALAPPDATA%\comet\<Dragonfly版本>\pythonUserExtensions\Plugins\OrsCgalMesh_<uuid>\
• 面板代码与网格程序：%LOCALAPPDATA%\comet\<Dragonfly版本>\pythonUserExtensions\GenericMenuItems\CgalMesh\（其中 bin\cgal_mesher.exe 为网格化程序）
• 全部安装在当前用户目录（%LOCALAPPDATA%）下，不需要管理员权限；本机每个 Dragonfly 版本都会各装一份。

卸载：双击完整安装包中的 `Uninstall_FullPackage.bat`（上述 installer 目录中也保留一份），它会移除所有 Full Package 菜单项与插件；插件自身的配置文件（见下一章）会保留，结束时列出路径，可按需手动删除。

4. 运行环境与首次配置

本插件没有 Setup Environment 按钮，也不需要任何环境搭建：网格化程序 cgal_mesher.exe 连同其运行库（gmp-10.dll、mpfr-6.dll、MSVC 运行时 DLL）已随插件打包在代码目录的 bin\ 子文件夹中，面板启动时自动检测。不需要联网、不需要 GPU、不需要 WSL——安装勾选后重启即可直接使用。

• 网格化程序（自动检测）：%LOCALAPPDATA%\comet\<Dragonfly版本>\pythonUserExtensions\GenericMenuItems\CgalMesh\bin\cgal_mesher.exe
• 用户配置文件：%LOCALAPPDATA%\CgalMesh\config.json——记住上次使用的 exe 路径与输出文件夹，每次点击 Generate Mesh 时自动更新。
• 默认输出文件夹：C:\CGALMeshJobs（可在面板中修改，修改后会被记住；不存在时运行时自动创建）。

如果 exe 路径框为空或文件被移动，可点击其右侧 … 浏览按钮手动指定 cgal_mesher.exe 的位置；该路径同样会被记入配置文件。

支持的 Dragonfly 版本：2025.1 与 2027.1（面板使用 Dragonfly 自带的 PyQt6 与 Python，同一套代码同时服务两个版本）。

与其他重型 Prototype Apps 插件不同，本插件在安装和首次使用时不下载任何内容——开箱即用。

5. 界面说明

面板自上而下依次为：一行蓝色说明文字（"Generate a tetrahedral mesh (CGAL Mesh_3) from a Multi-ROI / ROI / label Channel..."）、四个参数分组（可滚动）、两个操作按钮，以及底部的运行日志窗口。以下逐一说明。

5.1 Input (from Dragonfly)——输入分组

• Label object 下拉框：列出当前会话中所有可作为标签体的对象——全部 Multi-ROI、ROI 和 Channel（体素数为 0 的空对象不列出）。列表项格式为 名称 [类型] [Z x Y x X]，类型显示 MultiROI / ROI 或对象类名；重名时附加 GUID 前缀区分。
• 列表自动刷新（约每 2.5 秒从会话重新枚举一次），新建或删除对象后无需手动操作；刷新时保持你当前的选择不变。当前在 Dragonfly 中选中的对象会优先排在列表前面。
• 分组顶部的灰色提示："Multi-ROI / ROI / label Channels refresh automatically from the session."

5.2 Output & Executable——输出与可执行程序分组

• Output folder：输出根文件夹（默认 C:\CGALMeshJobs 或上次使用的值），右侧 … 按钮可浏览选择。每次运行都会在其下新建独立的作业子文件夹。
• cgal_mesher.exe：网格化程序路径，默认自动指向随插件附带的 bin\cgal_mesher.exe，右侧 … 按钮可手动更换。
• Output coordinates 下拉框：World (Dragonfly coordinates)（默认，网格顶点位于 Dragonfly 世界坐标，和源数据完全对齐）或 Image (origin 0, axis-aligned)（原点为 0、轴对齐的图像坐标，供某些偏好该坐标系的下游有限元工具使用）。
• Also write MEDIT .mesh 复选框（默认不勾选）：除 .vtu 外再写一份 MEDIT 格式的 .mesh 文件。

5.3 Mesh_3 Criteria (sizes in VOXELS)——网格质量准则分组

五个数值输入框对应 CGAL Mesh_3 的五项质量准则。注意：所有尺寸类参数（Facet size、Facet distance、Cell size）都以体素（VOXELS）为单位，与数据的物理间距无关；换算关系为：物理尺寸 = 体素数 × 该方向的体素间距。

• Facet angle (deg)（默认 30）：表面三角形的最小内角下限（角度）。
• Facet size（默认 2.0）：表面三角形外接球半径上限（体素）。
• Facet distance（默认 1.0）：表面三角形到真实边界的最大逼近误差（体素），控制边界还原精度。
• Cell size（默认 2.0）：四面体外接球半径上限（体素），是控制网格总量的主要旋钮。
• Cell radius-edge ratio（默认 3.0）：四面体外接球半径与最短边之比的上限，控制单元形状质量。

5.4 Mesh Optimization——网格优化分组

• Fast (disable all optimizers)（默认不勾选）：勾选后跳过全部优化器，最快但质量最低。
• Perturb（默认勾选）：顶点微扰优化，消除退化单元。
• Exude (sliver removal)（默认勾选）：挤出优化，去除薄片（sliver）四面体。
• Lloyd（默认不勾选）：Lloyd 全局平滑优化（较耗时）。
• ODT（默认不勾选）：ODT 全局优化（较耗时）。
• Verbose mesher log（默认不勾选）：让网格程序输出更详细的过程日志，便于排查问题。

Perturb + Exude 同时开启即 CGAL 的默认质量组合；勾选 Fast 时其余优化器选项全部无效。

5.5 操作按钮、日志与完成对话框

• Generate Mesh（蓝色按钮）：读取所选对象并启动网格化；运行期间按钮禁用。
• Open Output Folder：在 Windows 资源管理器中打开最近一次作业的输出文件夹（尚未运行过时打开输出根文件夹）。
• 日志窗口（底部只读文本框）：显示对象刷新、导出、网格程序的每一行输出以及错误信息。

运行结束后弹出 CGAL Mesh_3 完成对话框：成功时显示顶点数（Vertices）、四面体数（Tetrahedra）、材料数（Materials）、耗时（Time）和输出文件路径，并提供 Open Output Folder（默认按钮）与 Close 两个按钮；失败时显示 "Meshing failed." 与具体错误文本。

6. 使用步骤

6.1 基本流程（端到端）

1. 在 Dragonfly 中准备好分割结果：一个 Multi-ROI（多材料）、一个二值 ROI，或一个整数标签 Channel。标签值必须为非负整数，0 表示背景。

2. 打开 Prototype Apps ▸ CGAL Mesh_3 (Panel)...。

3. 在 Label object 下拉框中选择输入对象（列表自动刷新；确认名称后方括号中的类型与尺寸正确）。

4. 确认 Output folder（默认 C:\CGALMeshJobs）；如需更换点 … 选择。

5. 保持 cgal_mesher.exe 的自动路径不动（除非你特意移动过该程序）。

6. 选择 Output coordinates：做仿真且要与 Dragonfly 数据对齐时用默认的 World。

7. 按目标网格密度设置 Mesh_3 Criteria 五个参数（单位为体素，见 6.2 的选择建议）。

8. 按需调整 Mesh Optimization 勾选项；初次试跑可勾选 Fast 快速看效果。

9. 点击 Generate Mesh。日志窗口实时显示导出与网格化输出；期间可继续在 Dragonfly 中工作。

10. 完成对话框弹出后，确认顶点/四面体/材料统计，点击 Open Output Folder 打开作业文件夹，取用 .vtu（及可选 .mesh）文件。

6.2 网格尺寸参数的选择建议

尺寸参数以体素为单位，选取时把它与目标特征的体素尺度直接对比即可：Cell size / Facet size 必须明显小于你关心的最细结构的体素厚度，否则该结构无法被网格捕捉，极端情况下会得到空网格（程序报 "empty mesh"，返回码 2）。反之，参数越小网格越细，四面体数量与内存、耗时会急剧增长。

• 先用默认值（Facet size 2.0 / Cell size 2.0 体素）加 Fast 试跑一次，从完成对话框读出四面体数量，再按需要加密或放粗。
• 需要物理单位时自行换算：物理尺寸 = 体素数 × 体素间距（网格结果本身在 World 模式下已是物理坐标）。
• 只关心边界精度时优先减小 Facet distance；只想控制体网格规模时优先调 Cell size。

整个所选体积都会按当前分辨率参与网格化：数据体越大、参数越细，内存占用与计算时间越高。大体积数据建议先在粗参数下验证流程。

6.3 查看与使用结果

1. 点击 Open Output Folder 打开本次作业文件夹（命名形如 cgal_<对象名>_<日期_时间>）。

2. 把 <名称>.vtu 拖入 ParaView，按单元数据 MaterialID 着色，即可分材料检查网格。

3. 需要 MEDIT 格式的工具链（如 Gmsh 等）可使用勾选生成的 <名称>.mesh。

4. 打开 <名称>_result.json 可查看顶点/四面体总数、每种材料的四面体数、世界坐标包围盒、耗时与本次使用的全部参数。

7. 参数说明

8. 输出结果

本插件的输出是文件（不在 Dragonfly 中生成新对象）。每次运行在输出根文件夹下新建一个作业文件夹 cgal_<对象名>_<YYYYMMDD_HHMMSS>，内含：

如何查看：在 ParaView 中打开 .vtu 并按 MaterialID 着色；World 模式下网格与 Dragonfly 中的源数据在同一坐标系中精确对齐，可与其他导出数据叠加比对。

v1 不支持把四面体体网格重新导入 Dragonfly（Dragonfly 原生网格主要是表面网格），请在 ParaView / 仿真软件中使用输出文件。

9. 常见问题与故障排除

问：菜单里找不到 CGAL Mesh_3 (Panel)...？

答：本插件默认不启用。请确认安装时勾选了它（或事后在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 的 "Prototype Apps (Full Package)" 列表中勾选），并且勾选后完全重启过 Dragonfly——菜单只在启动时扫描一次。

问：下拉列表里没有我的对象？

答：列表只显示带有体数据的 Multi-ROI / ROI / Channel（体素数为 0 的对象被过滤），且约每 2.5 秒自动刷新一次——对象刚创建或还在加载时稍等片刻。点击 Generate Mesh 时若提示 "select a valid input object (it may still be loading)"，等对象加载完成后重选即可。

问：报错 "CGAL mesher exe not found"？

答：exe 路径框指向的文件不存在。点击其右侧 … 按钮，浏览到 %LOCALAPPDATA%\comet\<Dragonfly版本>\pythonUserExtensions\GenericMenuItems\CgalMesh\bin\cgal_mesher.exe 选中即可；路径会被记住，之后无需再设。

问：提示空网格（empty mesh）、失败返回码 2？

答：这是尺寸参数相对目标结构过大所致——Cell size / Facet size 以体素为单位，若大于目标结构的体素厚度，结构会被整体略过。把 Cell size、Facet size 调小后重试；同时确认所选对象里确实存在非零标签。

问：网格太大 / 运行太慢怎么办？

答：增大 Cell size 与 Facet size（最有效），勾选 Fast 跳过优化器，不要勾选 Lloyd / ODT。可勾选 Verbose mesher log 观察进度。运行中的任务无法从面板取消，因此建议先用粗参数试跑，确认规模后再加密。

问：标签值有什么限制？

答：标签必须是非负整数：出现负值会直接报错；最大标签值不能超过 65535（超过会提示重新标号）。0 被视为背景/外部，不生成网格；每个非零标签成为一种材料。浮点型 Channel 会被四舍五入为整数后当作标签使用。

问：在 ParaView 里网格和我导出的图像数据对不上位置？

答：确认生成时 Output coordinates 选择的是 World (Dragonfly coordinates)——该模式下网格带有真实原点、间距和方向；Image 模式则是原点 0、轴对齐的图像坐标，两者不重合是正常的。

问：能把生成的体网格导回 Dragonfly 显示吗？

答：当前版本不支持——Dragonfly 的原生网格对象主要面向表面网格，而本插件输出的是四面体体网格。请使用 Open Output Folder 在 ParaView 等外部软件中查看。

10. 注意事项与已知限制

• 尺寸单位是体素：Facet size、Facet distance、Cell size 均以体素为单位（面板分组标题 "sizes in VOXELS" 已注明），与物理间距无关；输出网格坐标（World 模式）才是物理/世界单位。
• 标签 0 = 背景/外部，不参与网格化；每个非零标签生成一种材料。
• 下拉框会列出所有 Channel：请选择真正的整数标签图。普通灰度 Channel 会把每个灰度值当作一种材料，通常不是想要的结果。
• 标签最大值不能超过 65535（内部按最大值自动选用 uint8 或 uint16 存储）；不允许负值。
• 网格化前体积会自动在每侧补一圈零边界，以保证贴边目标生成完整外表面——这是预期行为。
• 输入对象若没有 Box 几何信息，将按单位间距与单位变换处理（日志会提示），此时输出实际处于图像坐标。
• 运行中的任务无法取消；Generate Mesh 按钮在任务结束前保持禁用。请先用粗参数评估规模。
• v1 不把体网格导回 Dragonfly；交付物是标准网格文件（.vtu / .mesh）。
• 作业文件夹中的 labels.npy / metadata.json 是中间文件，确认结果后可删除以节省磁盘空间。
• 配置（exe 路径、输出文件夹）保存在 %LOCALAPPDATA%\CgalMesh\config.json，卸载插件不会删除它。

11. 参考资料

• CGAL（Computational Geometry Algorithms Library）项目及其 Mesh_3 三维网格生成组件的官方文档（本插件针对 CGAL 5.5+/6.0 构建；使用 GMP/MPFR 数值后端）。
• VTK / ParaView：.vtu（VTK XML UnstructuredGrid）格式说明与网格查看。
• MEDIT .mesh 格式：Gmsh 等工具可读取的经典网格交换格式。
• 下游仿真工具示例：Gmsh、NGSolve、Abaqus。
• Prototype Labs & Apps 完整安装包自带的安装说明（安装包内 README，中英双语）。

Part II English Manual

Contents

1. Overview

1.1 How it works

2. Use Cases

3. Installation & Enabling

4. Runtime Environment & First-time Setup

5. User Interface

5.1 Input (from Dragonfly) group

5.2 Output & Executable group

5.3 Mesh_3 Criteria (sizes in VOXELS) group

5.4 Mesh Optimization group

5.5 Action buttons, log and completion dialog

6. Step-by-step Usage

6.1 Basic workflow (end to end)

6.2 Choosing the mesh size criteria

6.3 Viewing and using the results

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

The CGAL Mesh_3 (Panel) plugin turns your Dragonfly segmentation — a multi-material Multi-ROI, a binary ROI, or an integer label Channel — directly into a simulation-ready tetrahedral (volume) mesh. The mesh is written as a .vtu file (optionally plus a MEDIT .mesh file) in true Dragonfly world coordinates, with every tetrahedron carrying a MaterialID cell attribute equal to its original label value, ready for ParaView or FEM/simulation packages.

The underlying engine is the Mesh_3 3D mesh generation component of the open-source computational geometry library CGAL (the plugin is built against CGAL 5.5+/6.0): a labeled-image mesh domain (create_labeled_image_mesh_domain) is built from your labels, make_mesh_3 generates the tetrahedra, and the Perturb, Exude, Lloyd and ODT quality optimizers can be applied. All meshing runs in a standalone local executable, cgal_mesher.exe — CGAL is never loaded into Dragonfly's bundled Python, so the plugin is completely non-invasive to the Dragonfly installation.

Licensing notes: the plugin ships with the Prototype Apps Full Package; the meshing core cgal_mesher.exe is built on the open-source components CGAL, GMP/MPFR and nlohmann-json, and is bundled together with the required runtime libraries (gmp-10.dll, mpfr-6.dll and the MSVC runtime DLLs). It is invoked as an external subprocess. For the exact license terms of the open-source components, please refer to their official project pages.

• Three input types: Multi-ROI (multi-material), ROI (binary), integer label Channel.
• True world-coordinate output: the full origin + voxel spacing + orientation (4x4 affine) is carried through, so registered/rotated data lands in the right place.
• Material preservation: each tetrahedron's MaterialID equals its original label value — multi-material meshes need no remapping.
• Controllable quality: five Mesh_3 criteria (facet angle/size/distance, cell size, radius-edge ratio) plus four optimizer switches.
• Run statistics: every run also writes _result.json (vertex/tet counts, per-material tet counts, bounding box, timing, parameters used).

1.1 How it works

1. The panel reads the selected object's label volume directly (in-process) from the live Dragonfly session, together with its full voxel-to-world geometry (origin + spacing + orientation, encoded as a 4x4 voxel_to_world affine matrix).

2. The data is exported as labels.npy + metadata.json into a per-run job folder (labels are automatically narrowed to uint8 or uint16).

3. cgal_mesher.exe runs CGAL Mesh_3 in voxel space (the quality size criteria are in voxels) and automatically zero-pads the volume by one voxel on every side, so objects touching the image border still get a complete outer surface.

4. When exporting the mesh vertices (in the World output mode) they are mapped back to Dragonfly world coordinates through the voxel_to_world matrix; the run writes .vtu (optionally .mesh) plus the _result.json statistics file.

Meshing runs on a background worker thread, so the Dragonfly UI stays responsive; the Generate Mesh button is disabled while a job runs, and only one job runs at a time.

2. Use Cases

For anyone who needs to run physics simulations on segmented 3D image data, this plugin converts the segmentation into a solver-readable volume mesh in one step:

• Pre-processing (volume mesh generation) for FEM stress, heat transfer, fluid flow, electromagnetics and similar simulations.
• Simulation modeling of industrial CT data — cast parts, additively manufactured parts.
• Materials science: battery electrodes, porous materials and other microstructures.
• Life science: bone and tissue structures.
• Multi-material meshing: every class (phase) of a Multi-ROI is preserved as a separate material in the mesh, so different phases can get different material properties.
• Results open in ParaView, or feed into simulation toolchains such as Gmsh / NGSolve / Abaqus.

3. Installation & Enabling

The plugin installs through the Prototype Labs & Apps Full Package:

1. Unzip the Full Package zip anywhere (a short path such as C:\PL\ is recommended).

2. Double-click `Install_FullPackage.bat`.

3. In the installer dialog, tick CGAL Mesh_3 (Panel)... in the Prototype Apps list (under the Simulation & Meshing group). Note: all plugins are unticked by default — you must tick this one.

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

5. Quit Dragonfly completely and restart it (menus are scanned only at startup).

After the restart the menu entry appears at Prototype Apps ▸ CGAL Mesh_3 (Panel).... Clicking it docks the panel on the right side of the Dragonfly main window, in a tab named "CGAL Mesh_3"; the panel is collapsible, movable and can be floated as a separate window.

Enable/disable later: open Developer ▸ Prototype Labs... ▸ Menu Item Manager and tick/untick the plugin in the "Prototype Apps (Full Package)" list at the bottom; restart Dragonfly to apply. Disabling only removes the menu entry — it never deletes the plugin's settings; re-enabling is instant. You can also re-run the installer anytime (your previous choices are the new defaults): %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat.

• Plugin package location: %LOCALAPPDATA%\comet\<DragonflyVersion>\pythonUserExtensions\Plugins\OrsCgalMesh_<uuid>\
• Panel code and mesher: %LOCALAPPDATA%\comet\<DragonflyVersion>\pythonUserExtensions\GenericMenuItems\CgalMesh\ (with bin\cgal_mesher.exe inside)
• Everything is per-user (%LOCALAPPDATA%); no admin rights needed. Every Dragonfly version on the PC gets its own copy.

Uninstall: double-click `Uninstall_FullPackage.bat` from the Full Package (a copy is kept in the installer folder above). It removes all Full Package menu items and plugins; the plugin's own configuration file (see the next chapter) is kept, and its path is listed at the end so you can delete it manually if desired.

4. Runtime Environment & First-time Setup

This plugin has no Setup Environment button and needs no environment build: the mesher cgal_mesher.exe, together with its runtime libraries (gmp-10.dll, mpfr-6.dll, MSVC runtime DLLs), ships bundled in the bin\ subfolder of the plugin's code folder and is auto-detected when the panel opens. No internet, no GPU, no WSL — after ticking it in the installer and restarting Dragonfly it is ready to use.

• Mesher executable (auto-detected): %LOCALAPPDATA%\comet\<DragonflyVersion>\pythonUserExtensions\GenericMenuItems\CgalMesh\bin\cgal_mesher.exe
• User configuration: %LOCALAPPDATA%\CgalMesh\config.json — remembers the last-used exe path and output folder; updated automatically on every Generate Mesh click.
• Default output folder: C:\CGALMeshJobs (changeable in the panel; the change is remembered; created automatically at run time if missing).

If the exe path field is empty or the file has been moved, click the … browse button next to it and point it at cgal_mesher.exe; the path is stored in the configuration file as well.

Supported Dragonfly versions: 2025.1 and 2027.1 (the panel uses Dragonfly's own PyQt6 and Python; one codebase serves both versions).

Unlike other heavy Prototype Apps plugins, this one downloads nothing at install or first use — it works out of the box.

5. User Interface

From top to bottom the panel shows: one blue hint line ("Generate a tetrahedral mesh (CGAL Mesh_3) from a Multi-ROI / ROI / label Channel..."), four parameter groups (scrollable), two action buttons, and the run log window at the bottom. Each element is described below.

5.1 Input (from Dragonfly) group

• Label object dropdown: lists every object in the current session that can serve as a label volume — all Multi-ROIs, ROIs and Channels (empty objects with zero voxels are filtered out). Entries are formatted Title [Kind] [Z x Y x X], where Kind is MultiROI / ROI or the object class name; duplicate names get a GUID prefix suffix for disambiguation.
• The list auto-refreshes (re-enumerated from the session roughly every 2.5 seconds) — no manual action needed after creating or deleting objects; your current selection is preserved across refreshes. Objects currently selected in Dragonfly are listed first.
• Grey hint at the top of the group: "Multi-ROI / ROI / label Channels refresh automatically from the session."

5.2 Output & Executable group

• Output folder: the output root folder (default C:\CGALMeshJobs, or your last-used value); the … button opens a folder browser. Every run creates its own job subfolder inside it.
• cgal_mesher.exe: path to the mesher executable, pre-filled automatically with the bundled bin\cgal_mesher.exe; the … button lets you point elsewhere.
• Output coordinates dropdown: World (Dragonfly coordinates) (default — mesh vertices in Dragonfly world coordinates, perfectly aligned with the source data) or Image (origin 0, axis-aligned) (an origin-0, axis-aligned image frame for downstream FE tools that prefer it).
• Also write MEDIT .mesh checkbox (off by default): additionally writes a MEDIT-format .mesh file next to the .vtu.

5.3 Mesh_3 Criteria (sizes in VOXELS) group

Five numeric fields map to CGAL Mesh_3's five quality criteria. Note: all size-type criteria (Facet size, Facet distance, Cell size) are in VOXELS, independent of the data's physical spacing; the conversion is: physical size = voxels x voxel spacing along that axis.

• Facet angle (deg) (default 30): lower bound on the surface-triangle angles, in degrees.
• Facet size (default 2.0): upper bound on the surface-triangle circumball radius, in voxels.
• Facet distance (default 1.0): maximum approximation error between a surface facet and the true boundary, in voxels — controls how faithfully the boundary is reproduced.
• Cell size (default 2.0): upper bound on the tetrahedron circumball radius, in voxels — the main knob for overall mesh density.
• Cell radius-edge ratio (default 3.0): upper bound on the ratio of a tetrahedron's circumball radius to its shortest edge — controls element shape quality.

5.4 Mesh Optimization group

• Fast (disable all optimizers) (off by default): skips every optimizer — fastest, lowest quality.
• Perturb (on by default): vertex perturbation, removes degenerate elements.
• Exude (sliver removal) (on by default): exudation, removes sliver tetrahedra.
• Lloyd (off by default): Lloyd global smoothing optimizer (slower).
• ODT (off by default): ODT global optimizer (slower).
• Verbose mesher log (off by default): makes the mesher print a much more detailed progress log — useful for troubleshooting.

Perturb + Exude together is CGAL's default quality combination; when Fast is ticked, the other optimizer checkboxes have no effect.

5.5 Action buttons, log and completion dialog

• Generate Mesh (blue button): reads the selected object and starts the meshing job; disabled while a job is running.
• Open Output Folder: opens the most recent job's output folder in Windows Explorer (or the output root if nothing has run yet).
• Log window (read-only text box at the bottom): shows object refreshes, the export, every line of the mesher's output, and error messages.

When a run finishes, a CGAL Mesh_3 completion dialog pops up: on success it shows Vertices, Tetrahedra, Materials, Time and the output file path, with an Open Output Folder button (the default) and Close; on failure it shows "Meshing failed." plus the exact error text.

6. Step-by-step Usage

6.1 Basic workflow (end to end)

1. Prepare your segmentation in Dragonfly: a Multi-ROI (multi-material), a binary ROI, or an integer label Channel. Labels must be non-negative integers; 0 means background.

2. Open Prototype Apps ▸ CGAL Mesh_3 (Panel)....

3. Pick the input object in the Label object dropdown (the list auto-refreshes; check the kind and dimensions shown in brackets).

4. Confirm the Output folder (default C:\CGALMeshJobs); click … to change it.

5. Leave the auto-detected cgal_mesher.exe path untouched (unless you deliberately moved the executable).

6. Choose Output coordinates: keep the default World when the mesh must align with your Dragonfly data.

7. Set the five Mesh_3 Criteria for the target mesh density (units are voxels — see 6.2 for guidance).

8. Adjust the Mesh Optimization checkboxes as needed; for a first trial run, ticking Fast gives a quick preview.

9. Click Generate Mesh. The log window streams the export and mesher output; you can keep working in Dragonfly meanwhile.

10. When the completion dialog appears, check the vertex/tetrahedron/material statistics, click Open Output Folder, and take the .vtu (and optional .mesh) files.

6.2 Choosing the mesh size criteria

The size criteria are in voxels, so compare them directly with the voxel scale of the features you care about: Cell size / Facet size must be clearly smaller than the voxel thickness of the finest structure of interest, otherwise that structure cannot be captured — in the extreme case the mesh comes out empty (the mesher reports "empty mesh", return code 2). Conversely, smaller values mean a finer mesh, and the tetrahedron count, memory and run time grow steeply.

• Do a first trial with the defaults (Facet size 2.0 / Cell size 2.0 voxels) plus Fast, read the tetrahedron count from the completion dialog, then refine or coarsen as needed.
• When you need physical units, convert manually: physical size = voxels x voxel spacing (the mesh itself, in World mode, is already in physical coordinates).
• To improve boundary fidelity only, reduce Facet distance first; to control the overall mesh size, adjust Cell size first.

The whole selected volume is meshed at its current resolution: the larger the volume and the finer the criteria, the higher the memory use and run time. For large volumes, validate the workflow with coarse criteria first.

6.3 Viewing and using the results

1. Click Open Output Folder to open this run's job folder (named like cgal_<objectname>_<date_time>).

2. Drag <name>.vtu into ParaView and color by the MaterialID cell array to inspect the mesh per material.

3. For toolchains that read MEDIT (e.g. Gmsh), use the optionally generated <name>.mesh.

4. Open <name>_result.json for the total vertex/tetrahedron counts, per-material tetrahedron counts, the world-space bounding box, the timing, and all parameters used in this run.

7. Parameter Reference

8. Outputs

This plugin outputs files (it does not create new objects inside Dragonfly). Each run creates a job folder cgal_<objectname>_<YYYYMMDD_HHMMSS> under the output root, containing:

How to view: open the .vtu in ParaView and color by MaterialID; in World mode the mesh sits in exactly the same coordinate frame as the source data in Dragonfly, so it can be overlaid with other exported data.

v1 does not re-import the tetrahedral volume mesh into Dragonfly (Dragonfly's native mesh support is mainly surface meshes) — use the output files in ParaView / your simulation package.

9. FAQ & Troubleshooting

Q: The menu entry CGAL Mesh_3 (Panel)... is missing?

A: The plugin is disabled by default. Make sure it was ticked during installation (or tick it later in Developer ▸ Prototype Labs... ▸ Menu Item Manager, "Prototype Apps (Full Package)" list), and that Dragonfly was fully restarted afterwards — menus are scanned only at startup.

Q: My object does not appear in the dropdown?

A: The list only shows Multi-ROIs / ROIs / Channels that actually contain volume data (zero-voxel objects are filtered out), and it refreshes about every 2.5 seconds — wait a moment if the object was just created or is still loading. If Generate Mesh reports "select a valid input object (it may still be loading)", re-select once loading has finished.

Q: Error "CGAL mesher exe not found"?

A: The exe path field points to a missing file. Click the … button next to it and browse to %LOCALAPPDATA%\comet\<DragonflyVersion>\pythonUserExtensions\GenericMenuItems\CgalMesh\bin\cgal_mesher.exe; the path is remembered afterwards.

Q: "empty mesh" error / failure with return code 2?

A: The size criteria are too large relative to your structures — Cell size / Facet size are in voxels, and if they exceed the voxel thickness of a structure it is skipped entirely. Reduce Cell size and Facet size and retry; also verify the selected object really contains non-zero labels.

Q: The mesh is too big / the run is too slow?

A: Increase Cell size and Facet size (most effective), tick Fast to skip the optimizers, and leave Lloyd / ODT unticked. Tick Verbose mesher log to watch progress. A running job cannot be cancelled from the panel, so it is best to try coarse settings first and refine once the mesh size is confirmed.

Q: What are the label restrictions?

A: Labels must be non-negative integers: negative values raise an error; the maximum label value must not exceed 65535 (above that you are asked to re-label). 0 is treated as background/exterior and is not meshed; every non-zero label becomes one material. Floating-point Channels are rounded to the nearest integer before use.

Q: In ParaView, the mesh does not line up with my exported image data?

A: Check that Output coordinates was set to World (Dragonfly coordinates) when the mesh was generated — that mode carries the true origin, spacing and orientation; the Image mode is an origin-0, axis-aligned frame, so a mismatch between the two is expected.

Q: Can I load the generated volume mesh back into Dragonfly?

A: Not in the current version — Dragonfly's native mesh objects mainly target surface meshes, while this plugin outputs tetrahedral volume meshes. Use Open Output Folder and view the files in ParaView or another external tool.

10. Notes & Known Limitations

• Sizes are in voxels: Facet size, Facet distance and Cell size are in voxel units (the group title says "sizes in VOXELS"), independent of physical spacing; only the output mesh coordinates (World mode) are in physical/world units.
• Label 0 = background/exterior and is not meshed; every non-zero label produces one material.
• The dropdown lists all Channels: pick a genuine integer label map. A plain grayscale Channel would turn every gray value into a material, which is usually not what you want.
• The maximum label value is 65535 (internally stored as uint8 or uint16 depending on the maximum); negative labels are rejected.
• Before meshing, the volume is automatically zero-padded by one voxel on every side so that border-touching objects get a complete outer surface — this is intended behavior.
• If the input object has no Box geometry, unit spacing and an identity transform are used (a log message says so) — the output is then effectively in image coordinates.
• A running job cannot be cancelled; the Generate Mesh button stays disabled until it finishes. Evaluate the mesh size with coarse criteria first.
• v1 does not import the volume mesh back into Dragonfly; the deliverables are standard mesh files (.vtu / .mesh).
• labels.npy / metadata.json in the job folder are intermediate files; once you have verified the result they can be deleted to save disk space.
• The configuration (exe path, output folder) is stored in %LOCALAPPDATA%\CgalMesh\config.json; uninstalling the plugin does not delete it.

11. References

• The CGAL (Computational Geometry Algorithms Library) project and the official documentation of its Mesh_3 3D mesh generation component (this plugin is built against CGAL 5.5+/6.0; GMP/MPFR numeric backend).
• VTK / ParaView: the .vtu (VTK XML UnstructuredGrid) format and mesh viewing.
• The MEDIT .mesh format: a classic mesh exchange format readable by Gmsh and other tools.
• Downstream simulation tools (examples): Gmsh, NGSolve, Abaqus.
• The installation guide shipped inside the Prototype Labs & Apps Full Package (bilingual README in the package).