血管中心线（vmtk）插件用户手册

Vessel Centerlines (vmtk) Plugin - User Manual

Dragonfly Prototype Apps · Vessel Centerlines (vmtk)

版本 Version 1.1 · 2026-07-11

第一部分中文手册

1. 简介

底层引擎与算法

许可证要点

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

Setup Environment 做了什么

下载体量、联网、GPU、WSL、外部软件

环境安装到哪些路径

失败时的替代方案

5. 界面说明

5.1 Setup 分页（环境搭建）

5.2 Centerlines 分页（提取中心线）

6. 使用步骤

6.1 首次搭建环境

6.2 自动端点模式（最常用）

6.3 手动点 id 模式

7. 参数说明

8. 输出结果

如何查看

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

血管中心线(vmtk) 是一个 Dragonfly 插件，它从场景中的封闭管状表面网格（血管、气道或其他管道结构）中提取一张中心线网络。你只需选中一个表面网格、选择端点/种子点的确定方式（自动，或手动输入表面点 id），可选地翻转法线、提取分支标签、附加血管性（vesselness）标量，然后点击 Run。

结果以一个新的中心线网络 Graph（图）发布回 Dragonfly：图的顶点是中心线上的采样点，每个顶点携带一个 MaximumInscribedSphereRadius（最大内切球半径）标量；边是中心线的各个线段；另有可选的分支（group）id 与血管性标量。

底层引擎与算法

vmtk（Vascular Modeling Toolkit，基于 VTK 的血管建模工具包） —— 本插件的计算核心。它从 PyPI 以 wheel 形式安装，并自动拉取 VTK 与 ITK 作为依赖。
中心线：基于 Voronoi 图计算（vmtkCenterlines），沿途记录每点的最大内切球半径。
分支提取：由 vmtkBranchExtractor 将网络拆分为各分支并附上每点的分支（group）id。
血管性：可选的 Frangi/Sato 滤波（vmtkImageVesselEnhancement），先在表面体素化图像上计算，再采样回中心线顶点。

许可证要点

vmtk 的中心线（vmtkCenterlines，Voronoi 图）与血管性（vmtkImageVesselEnhancement，Frangi/Sato）路径均为纯 BSD-3-Clause 许可。本插件的计算后端只使用这些路径，并刻意避开 vmtk 的 TetGen 四面体网格化路径（vmtkTetGen 等），因为其底层的 TetGen 依赖采用 Modified-MIT 许可，对商业使用有限制。因此你得到的中心线/血管性结果不会触及任何非商用限制的代码。

vmtk 完全运行在一个专用的 Python 环境（venv）中，通过子进程 + JSON 文件交互与 Dragonfly 通信，从不在 Dragonfly 自带的 Python 中导入 vmtk/vtk，也不使用网络端口。

2. 适用场景

本插件适用于对血管 / 气道 / 多孔管网等管状结构做几何量化：

沿中心线读取局部内切球半径（MaximumInscribedSphereRadius），以定位狭窄（狭窄医学上即 stenosis）或动脉瘤（aneurysm）等形态异常；
按分支拆分网络（group id），对每一段分别做逐段测量；
将中心线作为下游流动分析、骨架分析或拓扑分析的输入；
对任意封闭的三角化管状表面（不限于医学图像，例如多孔材料中的连通孔道网格）提取骨架与半径场。

典型输入是先在 Dragonfly 中从 CT/显微图像分割出 ROI，再生成表面网格（Mesh / FaceVertexMesh），然后交给本插件提取中心线。

3. 安装与启用

本插件随 Full Package（完整安装包）分发。安装与启用流程如下：

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

2. 双击 Install_FullPackage.bat。

3. 在弹出的对话框中选择核心安装模式（Fresh 全新 / Compatible 兼容），并在插件列表中勾选 Vessel Centerlines (vmtk)。注意：默认情况下所有插件都是未勾选的，需要你手动勾选后才会启用。

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

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

重启后，菜单项出现在：Prototype Apps ▸ Vessel Centerlines (vmtk)...（分组 *Measurements & Analysis*）。点击它会打开一个可停靠的浮动面板。

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

安装时插件不会下载任何依赖。vmtk 环境在首次使用时才在面板里点 Setup Environment 搭建（见第 4 章）。

4. 运行环境与首次配置

vmtk（基于 VTK）体量较大，绝不能装入 Dragonfly 自带的 Python。因此本插件采用 venv-in-code 机制：在首次使用时为它单独搭建一个专用的 Python 环境。

Setup Environment 做了什么

在 Setup 分页点击 Setup Environment 后：

1. 定位 conda / mamba（Miniconda/Anaconda/Miniforge）：依次检查 --conda 指定、CONDA_EXE 环境变量、PATH，以及常见安装目录；也可在面板的 Conda 框里手动填 conda.exe 的完整路径。

2. 在一个短的中央路径新建独立 conda 环境（%LOCALAPPDATA%\DragonflyPrototypeLabs\vmtk_env），用 conda create -c conda-forge 安装 vmtk 1.5 + numpy（conda-forge 会一并拉取 VTK + ITK；win-64/py310 版本与 Dragonfly 的 Python 3.10 匹配）。

3. 运行一次导入自检（numpy / vtk / vmtk）。runner 在导入 vtk/vmtk 前用 os.add_dll_directory 把该环境的 Library\bin 等目录加入 DLL 搜索路径，因此无需 conda activate 即可加载 VTK/ITK 的 DLL。

4. 成功后把该 conda 环境的 python 路径填入 vmtk env python。

为什么用中央短路径：conda + VTK/ITK 的内部路径很深；若环境建在很深的插件安装目录里会超过 Windows 的 260 字符 MAX_PATH，导致 vtk 的 DLL 加载失败（“文件名或扩展名太长”）。中央短路径可避免该问题，并能在多个 Dragonfly 版本间复用（同为 Python 3.10），Setup 只需一次。

下载体量、联网、GPU、WSL、外部软件

首次 conda create 需要联网下载 vmtk + VTK + ITK（约几十到上百 MB，视缓存而定，通常几分钟）。仅用 CPU，无需 GPU。runner 以子进程方式运行，与 Dragonfly 进程隔离；不涉及 WSL 或其它外部软件。

必须先装 conda：vmtk 无法用 pip 安装（其 PyPI 项目没有任何发行文件），只能通过 conda 分发。请先安装 Miniconda/Anaconda/Miniforge。

环境安装到哪些路径

conda 环境：%LOCALAPPDATA%\DragonflyPrototypeLabs\vmtk_env（短路径以避免 MAX_PATH；跨 Dragonfly 版本复用）。
作业目录：默认 C:\VmtkJobs（PLY/JSON 文件 IPC 的临时作业文件夹，可在 Setup 分页修改）。

失败时的替代方案

找不到 conda：安装 Miniconda（docs.conda.io/en/latest/miniconda.html），或在 Conda 框里填 conda.exe 的完整路径（如 C:\Users\<你>\miniconda3\Scripts\conda.exe）后重试。
conda create 失败：确认能联网访问 conda-forge；日志会显示具体报错。可再点一次 Setup 重试。
导入 vtk 报“文件名或扩展名太长”：环境路径太深超过 MAX_PATH；本插件默认已用中央短路径，正常不会发生。

5. 界面说明

面板顶部是一段蓝色提示文字，简要说明插件用途。主体分为两个分页：Setup 与 Centerlines。面板底部是一个结果标签与一个只读的 Log（日志）区。

5.1 Setup 分页（环境搭建）

控件	类型	默认值	说明
vmtk venv python	文本框	（空）	venv 解释器路径；由 Setup Environment 自动回填，一般无需手改。
Base Python (build)	文本框	（空）	构建 venv 所用的基底解释器。空 = 用本 Dragonfly 自带的 python.exe（推荐）；也可填一个路径或 py -3.10。
Run mode	下拉框	windows	运行模式，可选 windows / wsl。普通使用保持 windows。
Job root	文本框	C:\VmtkJobs	存放每次运行产生的 PLY/JSON 作业文件夹的根目录。
Setup Environment	按钮	—	点击构建 venv 并 pip install vmtk numpy（首次几分钟，需联网）。

5.2 Centerlines 分页（提取中心线）

该分页分为四个分组：输入表面、端点/种子选择、选项、输出，下方是 Run 与 Open Output Folder 两个按钮。

Surface（下拉框 + Refresh）：选择输入的封闭管状表面网格。列表列出场景中的 Mesh / FaceVertexMesh，后面附带顶点数 V、面数 F 与类型。点 Refresh 重新扫描场景。
Mode（下拉框）：端点/种子选择模式，auto（默认）或 point_ids。
Source point ids（文本框）：作为中心线起点的表面点 id（逗号/空格分隔）。仅在 point_ids 模式下可用。
Target point ids（文本框）：作为中心线终点的表面点 id；留空则由 vmtk 自动选择。仅在 point_ids 模式下可用。
Flip surface normals（复选框）：默认关。当表面法线“内外颠倒”导致中心线失败或贴着壁走时勾选。
Extract branches (labels)（复选框）：默认开。运行 vmtkbranchextractor 将网络拆为分支并附上每点的分支（group）id。
Append vesselness（复选框）：默认关。额外计算一个血管性标量并携带到中心线顶点上。
Vesselness method（下拉框）：frangi（默认）或 sato，仅在勾选 Append vesselness 时可用。
Result Graph title（文本框）：结果图的标题；留空则自动命名，如 Centerlines of Aorta。
Run（按钮）：开始提取中心线。
Open Output Folder（按钮）：打开上一次作业所在的文件夹。

当 Mode = auto 时，Source/Target point ids 两个文本框会自动置灰（禁用）；只有切到 point_ids 才可输入。同样，Vesselness method 仅在勾选 Append vesselness 时才可用。

6. 使用步骤

6.1 首次搭建环境

1. 打开 Prototype Apps ▸ Vessel Centerlines (vmtk)...，切到 Setup 分页。

2. （可选）若不想用 Dragonfly 自带 Python，在 Base Python (build) 填一个 CPython 3.9+ 路径。

3. 点 Setup Environment，等待日志出现 Environment ready. venv python: ...（首次几分钟，需联网）。

6.2 自动端点模式（最常用）

1. 确保场景中已有一个封闭的、三角化的管状表面网格。

2. 切到 Centerlines 分页，点 Refresh，在 Surface 下拉框选中该网格。

3. Mode 保持 auto（vmtk 自动提取端点）。

4. 根据需要勾选 Extract branches（默认已开）；若中心线贴壁失败，可试勾 Flip surface normals。

5. （可选）在 Result Graph title 填写结果名称。

6. 点 Run；完成后结果标签会显示 Done. Published centerline Graph: V=... E=... Scalars: ...。

6.3 手动点 id 模式

1. 先在 Dragonfly 中确定你想用作起点/终点的表面点 id（例如管两端开口处的顶点）。

2. 将 Mode 切为 point_ids；此时两个点 id 文本框变为可输入。

3. 在 Source point ids 填入至少一个起点 id（逗号/空格分隔，如 0, 128）；可选地在 Target point ids 填入终点（留空则自动选）。

4. 点 Run。（若 point_ids 模式下起点为空，面板会报错提醒你填入或换回 auto。）

整体数据流：面板将选中网格导出为一个临时 PLY → 在 venv 中启动 runner 子进程（携 config.json）→ 轮询 status.json → 读取 results.json → 将中心线网络发布为 Graph。

7. 参数说明

参数	默认值	说明
seed_mode（Mode）	auto	端点/种子选择方式。auto = vmtk 自动选取表面上相距最远的两点作为起点/终点；point_ids = 使用下方输入的点 id。
source_point_ids	（空）	作为中心线起点的表面点 id（逗号/空格分隔）。仅 point_ids 模式。空 = 交给 vmtk 自动。
target_point_ids	（空）	作为中心线终点的表面点 id（逗号/空格分隔）。仅 point_ids 模式。空 = 交给 vmtk 自动。
flip_normals	false	计算前翻转表面法线。当表面“内外颠倒”、中心线失败或贴壁时启用。
extract_branches	true	运行 vmtkbranchextractor 拆分分支并附上每点的分支（group）id。
append_vesselness	false	额外计算 Frangi/Sato 血管性标量，并携带到中心线顶点。
vesselness_method	frangi	血管性滤波类别，frangi 或 sato。仅在 append_vesselness 开启时使用。

另有环境相关参数（在 Setup 分页）：

参数	默认值	说明
run_mode（Run mode）	windows	运行模式 windows / wsl。
job_root（Job root）	C:\VmtkJobs	作业文件夹根目录。
base_python（Base Python）	（空）	空 = 本 Dragonfly 自带 python.exe。

8. 输出结果

运行成功后，插件在 Dragonfly 中发布一个新的 Graph（图）对象，代表中心线网络：

顶点（vertices）：中心线上的采样点。
边（edges）：中心线的各个线段（折线连接关系）。
每顶点标量 slot 0 = MaximumInscribedSphereRadius（单位为长度），即局部最大内切球半径。图默认按该标量上色。
可选 BranchId：若勾选了 Extract branches，每顶点携带分支（group）id。
可选 Vesselness：若勾选了 Append vesselness，每顶点携带 Frangi/Sato 血管性值。

如何查看

新图会出现在 Dragonfly 的对象列表中，标题为你填的名称或自动名（如 Centerlines of Aorta）。
可在三维视图中直接显示该图；因为当前顶点标量设为半径 slot，图会自动按半径上色，便于直观定位狭窄与扩张。
可切换当前标量 slot 来改按 BranchId 或 Vesselness 上色。

中间的临时文件（surface.ply、config.json、status.json、results.json）保存在作业文件夹中（默认 C:\VmtkJobs\vmtk_<时间戳>），可用 Open Output Folder 按钮打开。

9. 常见问题与故障排除

Q1：点 Run 提示 “vmtk venv not set” 怎么办？

A：说明环境还没搭好。先到 Setup 分页点 Setup Environment，等日志显示 Environment ready 且 vmtk venv python 字段自动回填后，再回 Centerlines 分页 Run。

Q2：提示选中的网格“no faces”或“需要封闭三角化表面”？

A：中心线需要一个封闭的、带面的三角网格。若你选的对象只有点云或无面，请先在 Dragonfly 中生成/修复一个封闭表面网格再重试。

Q3：结果为空或报 “no centerline points”？

A：常见原因是表面法线方向不对（内外颠倒）或拓扑不完整。可先勾选 Flip surface normals 再试；若仍失败，改用 point_ids 模式手动指定两端开口处的表面点 id 作为起点/终点。

Q4：Setup Environment 失败（如 pip 试图从源码构建 vmtk）怎么办？

A：vmtk 只对部分 CPython 版本（通常 3.7–3.10，Windows x86-64）提供 wheel。若报错提示从源码构建，说明当前 Python 版本不支持；请在 Base Python (build) 填一个有 wheel 的版本（如 C:\Python310\python.exe）后重试。同时确保网络可访问 PyPI。

Q5：为什么血管性（Vesselness）没有出现在结果中？

A：首先确认已勾选 Append vesselness。该步骤是尽力而为的：它需要先将表面体素化再做 Frangi/Sato 滤波，若中间任一步骤失败，日志会提示“vesselness skipped/failed”并继续完成中心线提取（只是不带血管性标量）。

10. 注意事项与已知限制

输入必须是封闭的、三角化的表面网格；点云或带孔洞的开放表面可能得不到正确中心线。
本插件只使用 vmtk 的纯 BSD-3 中心线与血管性路径，不使用 TetGen 四面体网格化（非商用限制）。
血管性为尽力而为的步骤，失败时会自动跳过而不中断中心线提取。
仅使用 CPU；首次 Setup Environment 需联网下载 wheel。
菜单只在 Dragonfly 启动时扫描；启用/停用插件后均需重启一次。
多条中心线（多个 cell）会合并为一个 Graph；边按每条折线的相邻点对生成。
point_ids 模式下，起点至少需一个；点 id 必须是非负整数，会自动去重并排序。

11. 参考资料

vmtk（Vascular Modeling Toolkit）官方网站：http://www.vmtk.org/
vmtk 代码仓库：https://github.com/vmtk/vmtk
VTK（Visualization Toolkit）：https://vtk.org/
完整安装包总手册：本 zip 根目录下的 UserManual_用户手册.docx，同时涵盖 Prototype Labs 与全部 Prototype Apps。

Part II English Manual

Contents

1. Overview

Underlying engine and algorithms

License note

2. Use Cases

3. Installation and Enabling

4. Environment and First-Run Setup

What Setup Environment does

Download size, internet, GPU, WSL, external apps

Where the environment is installed

If setup fails

5. User Interface

5.1 Setup tab (build the environment)

5.2 Centerlines tab (extract centerlines)

6. Usage Steps

6.1 First-time environment build

6.2 Auto endpoint mode (most common)

6.3 Manual point-id mode

7. Parameter Reference

8. Output

How to view it

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

Vessel Centerlines (vmtk) is a Dragonfly plugin that extracts a centerline network from a closed tubular surface mesh (a vessel, airway, or other tubular structure) in your scene. Pick a surface, choose how endpoints/seeds are selected (auto, or type surface point ids), optionally flip normals, extract branch labels, and append a vesselness scalar, then click Run.

The result is published back into Dragonfly as a new centerline-network Graph: vertices are sample points along the centerline, each carrying a MaximumInscribedSphereRadius (local inscribed-sphere radius) scalar; edges are the centerline segments; plus an optional branch (group) id and an optional vesselness scalar.

Underlying engine and algorithms

vmtk (the VTK-based Vascular Modeling Toolkit) is the compute core. It is installed from PyPI as wheels and pulls in VTK and ITK as dependencies.
Centerlines are computed from the Voronoi diagram (vmtkCenterlines), recording each point's maximum inscribed-sphere radius.
Branch extraction (vmtkBranchExtractor) splits the network into branches and attaches a per-point branch (group) id.
Vesselness is an optional Frangi/Sato filter (vmtkImageVesselEnhancement), computed on a voxelized image of the surface and sampled back onto the centerline vertices.

License note

vmtk's centerline (vmtkCenterlines, Voronoi diagram) and vesselness (vmtkImageVesselEnhancement, Frangi/Sato) paths are pure BSD-3-Clause. This plugin's backend uses only those paths and deliberately avoids vmtk's TetGen tetrahedral-meshing path (vmtkTetGen, etc.), because the underlying TetGen dependency ships under a Modified-MIT license that restricts commercial use. Your centerline/vesselness results therefore never exercise any non-commercial-restricted code.

vmtk runs entirely inside a dedicated Python environment (venv), talking to Dragonfly only through a subprocess + JSON files. The plugin never imports vmtk/vtk into Dragonfly's own Python and uses no network ports.

2. Use Cases

This plugin is useful for quantifying the geometry of vessels / airways / tubular networks:

Read the local inscribed-sphere radius (MaximumInscribedSphereRadius) along the centerline to locate stenoses (narrowings) or aneurysms;
Split the network by branch (group id) for per-segment measurement;
Feed the centerline into downstream flow, skeleton, or topology analysis;
Extract a skeleton and radius field for any closed triangulated tubular surface (not only medical images — e.g. connected pore networks in porous materials).

A typical input is produced by segmenting an ROI from a CT/microscopy image in Dragonfly, generating a surface mesh (Mesh / FaceVertexMesh) from it, and then handing it to this plugin.

3. Installation and Enabling

This plugin ships with the Full Package. Install and enable it as follows:

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

2. Double-click Install_FullPackage.bat.

3. In the dialog, pick a core install mode (Fresh / Compatible) and tick Vessel Centerlines (vmtk) in the plugin list. Note: all plugins are unticked by default — you must tick this one to enable it.

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

5. Quit and restart Dragonfly (the menu list is built only at startup).

After the restart the menu entry appears at: Prototype Apps ▸ Vessel Centerlines (vmtk)... (group *Measurements & Analysis*). Clicking it opens a dockable floating panel.

Change the enable state later: in Dragonfly open Developer ▸ Prototype Labs... ▸ Menu Item Manager; the "Prototype Apps (Full Package)" list has a checkbox per app — tick to deploy, untick to remove the menu entry. Restart Dragonfly to apply. Disabling never deletes a plugin's built environment; re-enabling is instant.

Nothing is downloaded at install time. The vmtk environment is built on first use by clicking Setup Environment on the Setup tab (see Chapter 4).

4. Environment and First-Run Setup

vmtk (VTK-based) is heavy and must never touch Dragonfly's bundled Python. The plugin therefore uses a venv-in-code approach: it builds a dedicated Python environment for vmtk the first time you use it.

What Setup Environment does

When you click Setup Environment on the Setup tab:

1. Locate conda / mamba (Miniconda/Anaconda/Miniforge): it checks the --conda value, the CONDA_EXE env var, PATH, then common install dirs; you can also type the full conda.exe path into the panel's Conda field.

2. Create an isolated conda env at a short central path (%LOCALAPPDATA%\DragonflyPrototypeLabs\vmtk_env) and install vmtk 1.5 + numpy via conda create -c conda-forge (which pulls VTK + ITK; the win-64/py310 builds match Dragonfly's Python 3.10).

3. Run an import smoke test (numpy / vtk / vmtk). Before importing vtk/vmtk the runner adds the env's Library\bin dirs via os.add_dll_directory, so the VTK/ITK DLLs load without `conda activate`.

4. On success, fill the conda env's python path into vmtk env python.

Why a short central path: conda + VTK/ITK have very deep internal paths; an env buried in the deep plugin dir overflows Windows' 260-char MAX_PATH and vtk DLLs fail to load ('the filename or extension is too long'). A short central path avoids this and is reused across Dragonfly versions (both Python 3.10), so Setup is one-time.

Download size, internet, GPU, WSL, external apps

The first conda create needs internet to download vmtk + VTK + ITK (tens to a few hundred MB depending on cache; usually a few minutes). CPU only, no GPU. The runner is a separate subprocess, isolated from Dragonfly; no WSL or other external apps are involved.

conda is required: vmtk is not pip-installable (its PyPI project ships zero files) -- it is distributed only via conda. Install Miniconda/Anaconda/Miniforge first.

Where the environment is installed

conda env: %LOCALAPPDATA%\DragonflyPrototypeLabs\vmtk_env (short path to avoid MAX_PATH; reused across Dragonfly versions).
Job root: C:\VmtkJobs by default (temp PLY/JSON IPC job folders; changeable on the Setup tab).

If setup fails

conda not found: install Miniconda (docs.conda.io/en/latest/miniconda.html), or type the full conda.exe path into the Conda field (e.g. C:\Users\<you>\miniconda3\Scripts\conda.exe) and retry.
conda create fails: make sure conda can reach conda-forge (internet); the log shows the exact error. Click Setup again to retry.
vtk import says 'filename or extension is too long': the env path is too deep for MAX_PATH; the plugin already uses a short central path, so this should not occur.

5. User Interface

The top of the panel shows a short blue note describing the plugin. The body has two tabs: Setup and Centerlines. Below them are a result label and a read-only Log area.

5.1 Setup tab (build the environment)

Control	Type	Default	Description
vmtk venv python	text field	(empty)	Path to the venv interpreter; filled automatically by Setup Environment. Normally left untouched.
Base Python (build)	text field	(empty)	Base interpreter used to build the venv. Empty = this Dragonfly's own python.exe (recommended); or a path / py -3.10.
Run mode	dropdown	windows	Run mode, windows / wsl. Keep windows for normal use.
Job root	text field	C:\VmtkJobs	Root folder for the per-run PLY/JSON job folders.
Setup Environment	button	—	Builds the venv and pip installs vmtk + numpy (a few minutes the first time; needs internet).

5.2 Centerlines tab (extract centerlines)

This tab has four groups — input surface, endpoint/seed selection, options, output — with Run and Open Output Folder buttons at the bottom.

Surface (dropdown + Refresh): pick the input closed tubular surface mesh. The list shows scene Mesh / FaceVertexMesh objects with vertex count V, face count F, and class. Click Refresh to rescan the scene.
Mode (dropdown): endpoint/seed selection mode, auto (default) or point_ids.
Source point ids (text field): surface point ids used as centerline sources (comma/space separated). Only active in point_ids mode.
Target point ids (text field): surface point ids used as centerline targets; blank = let vmtk auto-pick. Only active in point_ids mode.
Flip surface normals (checkbox): default off. Tick when the surface is inside-out and centerlines fail or hug the wall.
Extract branches (labels) (checkbox): default on. Runs vmtkbranchextractor to split the network into branches and attach a per-point branch (group) id.
Append vesselness (checkbox): default off. Also computes a vesselness scalar and carries it onto the centerline vertices.
Vesselness method (dropdown): frangi (default) or sato; only active when Append vesselness is ticked.
Result Graph title (text field): title for the output Graph; blank auto-names it (e.g. Centerlines of Aorta).
Run (button): starts the centerline extraction.
Open Output Folder (button): opens the last job's folder.

When Mode = auto, the Source/Target point-id fields are greyed out (disabled); only point_ids mode enables them. Likewise, Vesselness method is only enabled when Append vesselness is ticked.

6. Usage Steps

6.1 First-time environment build

1. Open Prototype Apps ▸ Vessel Centerlines (vmtk)... and go to the Setup tab.

2. (Optional) If you do not want to use Dragonfly's own Python, type a CPython 3.9+ path into Base Python (build).

3. Click Setup Environment and wait for the log to show Environment ready. venv python: ... (a few minutes the first time; needs internet).

6.2 Auto endpoint mode (most common)

1. Make sure the scene has a closed, triangulated tubular surface mesh.

2. Go to the Centerlines tab, click Refresh, and pick the mesh in the Surface dropdown.

3. Leave Mode on auto (vmtk auto-extracts endpoints).

4. Tick Extract branches as needed (on by default); if centerlines hug the wall, try ticking Flip surface normals.

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

6. Click Run; when finished, the result label shows Done. Published centerline Graph: V=... E=... Scalars: ....

6.3 Manual point-id mode

1. First determine, in Dragonfly, the surface point ids you want as sources/targets (e.g. vertices at the tube's open ends).

2. Switch Mode to point_ids; the two point-id fields become editable.

3. Enter at least one source id in Source point ids (comma/space separated, e.g. 0, 128); optionally enter targets in Target point ids (blank = auto).

4. Click Run. (If point_ids mode has no source id, the panel raises an error asking you to fill it in or switch back to auto.)

Overall data flow: the panel exports the selected mesh to a temporary PLY → launches the runner subprocess inside the venv (with a config.json) → polls status.json → reads results.json → publishes the centerline network as a Graph.

7. Parameter Reference

Parameter	Default	Description
seed_mode (Mode)	auto	Endpoint/seed selection. auto = vmtk picks the two most distant surface points as source/target; point_ids = use the ids you type below.
source_point_ids	(empty)	Surface point ids used as centerline sources (comma/space separated). point_ids mode only. Blank = let vmtk auto-pick.
target_point_ids	(empty)	Surface point ids used as centerline targets (comma/space separated). point_ids mode only. Blank = let vmtk auto-pick.
flip_normals	false	Flip surface normals before computing centerlines. Use when the surface is inside-out and centerlines fail or hug the wall.
extract_branches	true	Run vmtkbranchextractor to split the network into branches and attach a per-point branch (group) id.
append_vesselness	false	Also compute a Frangi/Sato vesselness scalar and carry it onto the centerline vertices.
vesselness_method	frangi	Vesselness filter family, frangi or sato. Only used when append_vesselness is on.

Environment-related parameters (on the Setup tab):

Parameter	Default	Description
run_mode (Run mode)	windows	Run mode, windows / wsl.
job_root (Job root)	C:\VmtkJobs	Root folder for job folders.
base_python (Base Python)	(empty)	Empty = this Dragonfly's own python.exe.

8. Output

On success, the plugin publishes a new Graph object in Dragonfly representing the centerline network:

Vertices: sample points along the centerline.
Edges: the centerline segments (polyline connectivity).
Per-vertex scalar slot 0 = MaximumInscribedSphereRadius (unit: length) — the local maximum inscribed-sphere radius. The Graph colours by this scalar by default.
Optional BranchId: present when Extract branches is ticked — a per-vertex branch (group) id.
Optional Vesselness: present when Append vesselness is ticked — a per-vertex Frangi/Sato vesselness value.

How to view it

The new Graph appears in Dragonfly's object list, titled with your name or the auto name (e.g. Centerlines of Aorta).
It can be displayed directly in a 3D view; because the current vertex scalar slot is set to radius, the Graph is automatically coloured by radius, making stenoses and dilations easy to spot.
Switch the current scalar slot to colour by BranchId or Vesselness instead.

Intermediate files (surface.ply, config.json, status.json, results.json) are kept in the job folder (default C:\VmtkJobs\vmtk_<timestamp>) and can be opened with the Open Output Folder button.

9. FAQ and Troubleshooting

Q1: Run says “vmtk venv not set” — what do I do?

A: The environment is not built yet. Go to the Setup tab, click Setup Environment, wait until the log shows Environment ready and the vmtk venv python field is auto-filled, then Run from the Centerlines tab.

Q2: It says the selected mesh has “no faces” or that it needs a closed triangulated surface?

A: Centerlines need a closed, faced triangle mesh. If your object is a point cloud or has no faces, first generate/repair a closed surface mesh in Dragonfly and retry.

Q3: The result is empty or reports “no centerline points”?

A: A common cause is wrong-facing surface normals (inside-out) or incomplete topology. Try ticking Flip surface normals and rerun; if it still fails, switch to point_ids mode and manually specify the surface point ids at the tube's open ends as sources/targets.

Q4: Setup Environment fails (e.g. pip tries to build vmtk from source)?

A: vmtk only ships wheels for certain CPython versions (typically 3.7–3.10, Windows x86-64). If it tries to build from source, the current Python is unsupported; type a wheel-supported version into Base Python (build) (e.g. C:\Python310\python.exe) and retry. Also make sure PyPI is reachable.

Q5: Why is Vesselness missing from my result?

A: First confirm Append vesselness is ticked. That step is best-effort: it must voxelize the surface and run a Frangi/Sato filter, and if any intermediate step fails the log reports “vesselness skipped/failed” and the run continues to finish the centerlines (just without the vesselness scalar).

10. Notes and Known Limitations

The input must be a closed, triangulated surface mesh; point clouds or open surfaces with holes may not yield correct centerlines.
This plugin uses only vmtk's pure-BSD-3 centerline and vesselness paths; it does not use TetGen tetrahedral meshing (non-commercial restriction).
Vesselness is a best-effort step; on failure it is skipped without aborting the centerline extraction.
CPU only; the first Setup Environment needs internet to download wheels.
Menus are discovered only at Dragonfly startup; every enable/disable change needs one restart.
Multiple centerlines (multiple cells) are merged into one Graph; edges are generated from each polyline's consecutive point pairs.
In point_ids mode at least one source is required; point ids must be non-negative integers and are automatically de-duplicated and sorted.

11. References

vmtk (Vascular Modeling Toolkit) website: http://www.vmtk.org/
vmtk source repository: https://github.com/vmtk/vmtk
VTK (Visualization Toolkit): https://vtk.org/
Full Package overview manual: UserManual_用户手册.docx in the zip root, covering both Prototype Labs and all Prototype Apps.

第一部分 中文手册

1. 简介

底层引擎与算法

许可证要点

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

Setup Environment 做了什么

下载体量、联网、GPU、WSL、外部软件

环境安装到哪些路径

失败时的替代方案

5. 界面说明

5.1 Setup 分页（环境搭建）

5.2 Centerlines 分页（提取中心线）

6. 使用步骤

6.1 首次搭建环境

6.2 自动端点模式（最常用）

6.3 手动点 id 模式

7. 参数说明

8. 输出结果

如何查看

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

Part II English Manual

1. Overview

Underlying engine and algorithms

License note

2. Use Cases

3. Installation and Enabling

4. Environment and First-Run Setup

What Setup Environment does

Download size, internet, GPU, WSL, external apps

Where the environment is installed

If setup fails

5. User Interface

5.1 Setup tab (build the environment)

5.2 Centerlines tab (extract centerlines)

6. Usage Steps

6.1 First-time environment build

6.2 Auto endpoint mode (most common)

6.3 Manual point-id mode

7. Parameter Reference

8. Output

How to view it

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

第一部分中文手册