Fiber ROI to MultiROI 纤维 ROI 转 MultiROI 插件用户手册

Fiber ROI to MultiROI - User Manual

Dragonfly Prototype Apps · Fiber ROI to MultiROI...

版本 Version 1.0 · 2026-07-10

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Fiber ROI to MultiROI(纤维 ROI 转 MultiROI)是一个 Dragonfly 插件,它以向导式(wizard)的分页流程,把一个二值 Fiber ROI(把所有纤维当作一个整体分割出来的掩膜)拆分成逐根纤维的 MultiROI——即每一根纤维得到一个独立的标签。它专为纤维网络、交叉/接触纤维、纤维束等细长结构而设计:这些结构在分割阶段往往连成一片,难以逐根测量、统计或着色显示,本插件负责把它们分开。

整个转换过程遵循一条固定的处理链:Fiber ROI -> 骨架化(Skeleton) -> 体素图(Graph) -> 查找 junction -> 切开 junction(Cut) -> 按切线方向重连(Reconnect) -> 逐根纤维 MultiROI。也就是说,插件先把 ROI 细化成单体素宽的骨架(中心线),在骨架上建立体素邻接图,把度数(degree)较高的交叉点(junction)找出来并切开,从而得到一段段分支;随后按每段末端的局部切线方向把最“共线”的一对分支重新配对相连,形成一根根完整纤维的中心线;最后把每根纤维的中心线标签按“最近中心线”扩张回原始 ROI 体素,并导入为 MultiROI。

底层引擎/算法。 骨架化、距离变换等计算由成熟的开源库 scikit-image 与 scipy 完成(配合 numpy),这些库安装在插件专属的隔离 venv 中,不改动 Dragonfly 自带的 Python 环境。骨架化方法包括基于 Lee 算法的 scikit-image skeletonize(2D/3D 通用,3D 纤维推荐默认)、scikit-image 的默认方法、旧版 skeletonize_3d(若已安装的 scikit-image 仍提供)、以及逐 Z 切片的 2D 细化和 2D 中轴(medial axis)。切开与重连是本插件自带的启发式算法。

许可证要点。 插件调用的第三方库(numpy、scipy、scikit-image)均为宽松开源许可证(BSD 类),可自由用于科研与商业分析。插件在首次使用时从 PyPI 联网下载这些库到本地 venv;正常运行时完全本地、离线,不需要 GPU。

重要:界面上标为红色的参数(切割半径 Cut radius、最小分段体素 Min segment voxels、重连搜索半径 Reconnect search radius、最小对向夹角 Minimum opposite angle、切线采样体素 Tangent sample voxels)强烈依赖你的图像(纤维粗细 / 长度 / 间距)。默认值只是通用起点,请务必按你的数据调整——把鼠标悬停到红色参数上可查看调参提示。

2. 适用场景

只要你已经把细长结构分割成一个整体的二值 ROI,却需要把它拆成单根标签以便进一步分析,本插件都适用。典型场景包括:

• 纤维网络:碳纤维/玻璃纤维复合材料、无纺布、织物等,纤维彼此交叉、接触,分割结果连成一体。
• 交叉 / 接触纤维:两根或多根纤维在成像分辨率下“粘”在一起,需要在交叉点处切开再各自归位。
• 纤维束(bundle):成束的细长结构需要拆成单根用于取向、长度、直径分布等统计。
• 多孔材料中的细长结构:需要把连成网络的骨架结构分成独立个体进行可视化或测量。

拆分完成后,每根纤维成为 MultiROI 中的一个标签,你可以对它们逐根做体积、长度、取向等测量,或按标签着色以便直观检查网络结构。

前提:输入必须是一个已存在的二值 Fiber ROI。本插件不做原始图像的分割——请先用 Dragonfly 的分割工具得到 ROI,再用本插件拆分。

3. 安装与启用

本插件随 Prototype Apps 完整安装包(Full Package) 分发,不需要单独安装。安装步骤如下:

1. 把完整安装包 zip 解压到任意较短的目录(例如 C:\PL\,避免路径过长)。

2. 双击 Install_FullPackage.bat。

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在应用列表中勾选 Fiber ROI to MultiROI。

4. 点击 Install 并等待控制台完成。

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

本插件默认未勾选(所有插件在安装器中默认关闭),必须手动勾选后才会部署。

重启后,插件出现在 Dragonfly 菜单栏的:Prototype Apps ▸ Fiber ROI to MultiROI...(位于 “Measurements & Analysis(测量与分析)” 分组)。点击即打开一个可停靠的面板(标签页名为 “Fiber ROI”),默认以浮动窗口(Floating)方式显示,可拖动、可停靠。

以后修改勾选

以后想启用或停用本插件,最方便的方式是在 Dragonfly 内操作:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 “Prototype Apps (Full Package)” 列表里勾选=部署、取消=移除菜单项,重启 Dragonfly 生效。停用从不删除插件已搭好的环境(venv),重新启用可立即使用。你也可以随时重跑安装器修改勾选。

卸载

双击 Uninstall_FullPackage.bat 即移除所有 Full Package 菜单项、插件与中央存储;它会保留每个插件已搭建的环境(venv),并在结束时列出这些路径,供你在需要腾出磁盘空间时手动删除。

4. 运行环境与首次配置

本插件的算法在一个独立的 venv(虚拟环境)中运行,与 Dragonfly 的 Python 隔离。完整安装包在安装时不下载任何依赖;你需要在首次使用前在插件面板里手动搭建环境。

Setup Environment 具体做什么

打开插件后切到第 1 个分页 1 Setup,点击 Setup Environment (scikit-image + scipy) 按钮。该按钮会:

• 在插件代码目录下创建一个隔离的 venv(默认路径为已安装代码目录 GenericMenuItems\FiberROIToMultiROI 内的 venv 子目录)。
• 把 venv 的 pip、setuptools、wheel 升级到较新版本。
• 从 PyPI 联网安装 numpy、scipy、scikit-image 三个依赖。
• 运行一个冒烟测试(import numpy/scipy/skimage 并调用 skeletonize),打印各库版本以确认环境可用。
• 成功后把 venv 的 python.exe 路径写回面板的 “Analysis venv python” 字段并保存到配置。

Base Python(基础 Python) 字段可留空,由插件自动探测 Dragonfly 或系统的 Python 来创建 venv;也可点 Browse... 手动指定一个 python.exe。Job root(作业根目录) 默认为 C:\FiberRoiJobs,每次运行会在其下生成一个带时间戳的作业子目录用于存放中间文件。

联网 / GPU / WSL / 外部软件要求

环境安装到哪些路径

• venv:已安装代码目录 %LOCALAPPDATA%\comet\<Dragonfly版本>\pythonUserExtensions\GenericMenuItems\FiberROIToMultiROI\venv(由 Setup Environment 按钮创建)。
• 作业目录:默认 C:\FiberRoiJobs\fiber_roi_<时间戳>,存放导出的 ROI 掩膜与各阶段中间结果。

失败时的替代方案:若自动探测的 Base Python 没有 venv 模块或 pip 不可用而导致搭建失败,请在 Setup 分页用 Browse... 手动指定一个可用的 python.exe(例如 Dragonfly 自带的 Python 或系统 Python),再重试。若已有 venv 但缺少可用 pip,插件会自动重建。

5. 界面说明

面板顶部是标题与一条图例说明(强调红色参数强烈依赖图像),下方是 6 个分页,最下方是绿色状态栏和一个只读日志框(实时显示运行进度)。以下逐页、逐控件说明,与代码完全一致。

分页 1 Setup(环境搭建)

• Analysis venv python(文本框):算法 venv 的 python.exe 路径;由 Setup Environment 自动填写,通常不必手动改。
• Base Python(文本框 + Browse...):创建 venv 用的基础 Python;留空=自动探测 Dragonfly / 系统 Python。
• Job root(文本框):作业根目录,默认 C:\FiberRoiJobs。
• Setup Environment (scikit-image + scipy)(按钮):搭建 venv 并安装依赖。
• 页脚说明文字:提醒使用隔离 venv,依赖为 numpy/scipy/scikit-image,无需 GPU,仅首次搭建需联网。

分页 2 Input ROI(输入 ROI)

• Fiber ROI(下拉框 + Refresh 按钮):选择要拆分的二值 ROI;Refresh 重新列出当前 Dragonfly 会话中的 ROI(下拉项会附带 ROI 形状信息)。
• Output MultiROI(文本框):最终纤维 MultiROI 的标题,默认 Fiber MultiROI。
• Skeleton MultiROI(文本框):骨架预览发布对象的标题,默认 Fiber skeleton。

分页 3 Skeleton(骨架)

• Method(下拉框):骨架化方法,含 Lee(2D/3D 通用,默认)、scikit-image 默认、legacy skeletonize_3d、逐 Z 切片 2D 细化、逐 Z 切片 2D 中轴。
• Graph connectivity(下拉框):体素图邻接方式,可选 6 / 18 / 26 邻域,默认 26 邻域。
• Min segment voxels(整数框,红色):保留的最短骨架分支长度(体素),范围 1–1000000,默认 3。
• Publish skeleton preview (as MultiROI)(复选框):是否发布骨架预览(以单标签 MultiROI 形式),默认勾选。
• Run to Skeleton Preview(按钮):只运行到骨架并发布骨架预览。

分页 4 Graph/Junctions(图与交叉点)

• Junction degree >=(整数框):把度数达到该阈值的骨架体素判定为 junction,范围 3–26,默认 3。
• Cut radius (voxels)(整数框,红色):切开每个 junction 时移除的体素半径,范围 0–20,默认 1。
• Publish junction / cut / segment / centerline debug (as ROI/MultiROI)(复选框):是否发布 junction、cut zone、分段、中心线等调试对象,默认不勾选。
• Run to Graph + Cut Preview(按钮):运行到建图与切开阶段并发布相应预览。

分页 5 Reconnect(重连)

• Reconnect cut stubs by tangent direction(复选框):是否按切线方向重连被切开的分支残端,默认勾选。
• Reconnect search radius(小数框,红色):重连时可跨越的最大间隙(体素),范围 0–200,2 位小数,默认 6.00。
• Minimum opposite angle(小数框,红色):两残端方向至少需多“直”才配对(度;180=完全共线),范围 0–180,1 位小数,默认 120.0。
• Tangent sample voxels(整数框,红色):估计残端局部方向所用的体素数,范围 2–50,默认 5。
• Final label mode(下拉框):最终标签模式,可选 “Expand labels to full ROI by nearest centerline(按最近中心线扩张回整个 ROI)”(默认)或 “Centerline labels only(仅中心线标签)”。

分页 6 Output(输出)

• Run Full Workflow + Create MultiROI(蓝色高亮按钮):运行完整流程并生成最终纤维 MultiROI。
• Summary 表格(Metric / Value 两列):运行结束后显示各项统计指标(如纤维数量等)。

6. 使用步骤

下面给出端到端的完整流程。建议先用两个预览按钮观察骨架与切割效果、调好红色参数,再运行完整流程。

端到端完整流程

1. 在 Dragonfly 中准备好要拆分的二值 Fiber ROI。

2. 打开 Prototype Apps ▸ Fiber ROI to MultiROI...。

3. 在 1 Setup 分页点击 Setup Environment(仅首次需要),等待日志显示环境就绪、Analysis venv python 被自动填入。

4. 切到 2 Input ROI,点 Refresh 后在 Fiber ROI 下拉框中选择你的 ROI;按需修改 Output / Skeleton MultiROI 标题。

5. 切到 3 Skeleton,选择 Method(3D 纤维推荐 Lee)与 Graph connectivity(默认 26),设置 Min segment voxels;点 Run to Skeleton Preview 查看骨架是否合理(是否有多余毛刺、断裂)。

6. 切到 4 Graph/Junctions,设置 Junction degree >= 与 Cut radius(建议约为纤维直径体素数的一半);勾选调试发布后点 Run to Graph + Cut Preview,检查交叉点是否被干净切开。

7. 切到 5 Reconnect,按纤维形态调整 Reconnect search radius、Minimum opposite angle、Tangent sample voxels,并选择 Final label mode。

8. 切到 6 Output,点 Run Full Workflow + Create MultiROI,等待日志完成;最终的纤维 MultiROI 会导入 Dragonfly,Summary 表格显示统计结果。

骨架预览(单步)

1. 完成 Setup 与 Input ROI 选择。

2. 在 3 Skeleton 分页调整方法/连通性/最短分支后,点 Run to Skeleton Preview。

3. 得到骨架预览(单标签 MultiROI),在 Dragonfly 中查看细化质量,反复调参直至满意。

图与切割预览(单步)

1. 在 4 Graph/Junctions 分页设置 junction 阈值与 cut radius,勾选调试发布。

2. 点 Run to Graph + Cut Preview。

3. 查看 junction / cut zone / 分段 / 中心线等调试对象,确认交叉点切开是否恰当,再据此微调 cut radius。

输入要求:必须先选中一个 Fiber ROI 且已完成 Setup(存在 Analysis venv python),否则点击运行会在状态栏提示 “Select a Fiber ROI first.” 或 “Run Setup first...”。

7. 参数说明

下表列出面板上所有可调参数、默认值与说明。标注(红色)的参数强烈依赖图像,需按你的数据调整。

8. 输出结果

本插件生成的所有对象都是分割对象(ROI / MultiROI),绝不是原始 image Channel。二值预览(骨架、junction、cut zone)以单标签 MultiROI发布;带标签的映射(分段、中心线、最终纤维)以多标签 MultiROI发布。导入过程通过一个临时、自动删除的 Channel 构建标签体积,不会在场景中留下多余的 image Channel。

运行结束后,Output 分页的 Summary 表格会以 Metric / Value 两列显示本次运行的统计(如生成的纤维数量 n_fibers 等),状态栏也会提示 “Created N fiber(s)” 及作业目录路径。中间文件保存在 C:\FiberRoiJobs\fiber_roi_<时间戳> 下,便于追溯。

9. 常见问题与故障排除

Q1:点运行提示 “Select a Fiber ROI first.” 或 “Run Setup first...”

A:前者表示尚未在 Input ROI 分页选择 ROI——请点 Refresh 后在下拉框中选一个二值 ROI;后者表示 Analysis venv 未设置——请先到 Setup 分页点 Setup Environment 搭建环境(或手动填入可用的 venv python 路径)。

Q2:Setup Environment 失败(创建 venv 或安装依赖报错)

A:常见原因是自动探测的 Base Python 没有 venv 模块或 pip 不可用,或首次搭建时无网络。请确认可联网访问 PyPI,并在 Setup 分页用 Browse... 手动指定一个自带 venv 与 pip 的 python.exe(例如 Dragonfly 自带 Python)后重试。若已有损坏的 venv,插件会自动重建。

Q3:交叉纤维没被分开,或纤维被切得太碎

A:这由 Cut radius 控制。交叉处仍相连=cut radius 太小,请调大(建议约为纤维直径体素数的一半);纤维过度碎裂=cut radius 太大,请调小。改完用 Run to Graph + Cut Preview 复查后再跑完整流程。

Q4:同一根纤维被拆成多段,或相邻纤维被错误合并

A:这与重连参数有关。同一纤维被切成多段=Reconnect search radius 太小或 Minimum opposite angle 太高;相邻纤维被错误合并=search radius 太大或 opposite angle 太低。请把 search radius 设到接近数据的典型间隙尺度,并按纤维弯曲程度调整 opposite angle(弯曲纤维调低、笔直纤维调高)。也可调整 Tangent sample voxels 使方向估计更稳。

Q5:骨架有很多毛刺或短假分支

A:调高 Min segment voxels 以丢弃过短的骨架分支;必要时更换 Method(平面纤维片可试逐 Z 切片方法),或调整 Graph connectivity。

Q6:预览/调试对象为空

A:某些可选预览(如没有 junction 的网络)本就可能为空;插件会跳过并在日志中提示,不影响整体运行。

10. 注意事项与已知限制

• 红色参数(cut radius、min segment voxels、reconnect radius、min opposite angle、tangent sample voxels)没有对所有纤维网络都正确的通用取值——默认值仅为起点,务必按你的数据调参,并善用两个预览按钮先看效果。
• 重连是一种启发式:它把每个切开交叉点附近方向最接近相反的一对残端贪心配对相连,对高度弯曲、密集缠绕或交叉角度接近的纤维可能出错,请用调试预览核对。
• 逐 Z 切片的 2D 骨架化方法(2D thin / 2D medial axis)不跨 Z 连接,仅适合近似平面的纤维掩膜。
• 输入必须是二值 Fiber ROI;插件本身不做原始图像分割。
• 首次使用必须联网搭建 venv;若为长期离线的机器,请在有网环境完成 Setup 后再离线使用。
• 运行会在 Job root(默认 C:\FiberRoiJobs)下累积带时间戳的作业目录,可定期清理以释放磁盘。

11. 参考资料

• scikit-image(骨架化 / 中轴等图像处理):https://scikit-image.org
• SciPy(距离变换 / 标记等):https://scipy.org
• NumPy:https://numpy.org
• Dragonfly 3D World:https://www.theobjects.com/dragonfly/

更多安装/启用说明见完整安装包根目录的总手册 UserManual_用户手册.docx。

Part II English Manual

Contents

1. Overview

2. Use cases

3. Installation and enabling

4. Runtime environment and first-run setup

5. User interface

6. Step-by-step usage

7. Parameter reference

8. Outputs

9. FAQ and troubleshooting

10. Notes and known limitations

11. References

1. Overview

Fiber ROI to MultiROI is a Dragonfly plugin that uses a wizard-style, tabbed workflow to convert one binary Fiber ROI (a mask that segments all fibers as a single object) into an individual-fiber MultiROI, where each fiber becomes its own label. It targets fiber networks, crossing/touching fibers, and bundles - elongated structures that segmentation tends to merge into one blob, making them hard to measure, count, or colour per fiber. This plugin splits them apart.

The conversion follows a fixed processing chain: Fiber ROI -> Skeleton -> Graph -> Find junctions -> Cut junctions -> Reconnect by tangent -> individual-fiber MultiROI. In other words, the plugin thins the ROI into a single-voxel-wide skeleton (centerline), builds a voxel adjacency graph on that skeleton, locates high-degree crossing points (junctions) and cuts them to yield branch segments, then pairs the most collinear branch stubs around each cut using their local tangent direction to reassemble whole-fiber centerlines. Finally it expands each fiber's centerline label back into the original ROI voxels by nearest centerline and imports the result as a MultiROI.

Underlying engine / algorithms. Skeletonization and distance transforms are performed by the mature open-source libraries scikit-image and scipy (with numpy), installed in a plugin-private isolated venv so Dragonfly's own Python is never modified. Skeletonization methods include Lee-based scikit-image skeletonize (2D/3D, recommended default for 3D fibers), scikit-image's default, the legacy skeletonize_3d (when the installed scikit-image still provides it), and per-Z-slice 2D thinning and 2D medial axis. The cut and reconnect steps are the plugin's own heuristic.

Licensing. The third-party libraries used (numpy, scipy, scikit-image) are permissive open source (BSD-style) and free for research and commercial analysis. They are downloaded from PyPI into a local venv on first use; normal runs are fully local and offline, and no GPU is required.

Important: the parameters shown in RED (Cut radius, Min segment voxels, Reconnect search radius, Minimum opposite angle, Tangent sample voxels) are strongly image-dependent (fiber thickness / length / gap). The defaults are only a generic starting point - tune them to your data. Hover a red parameter for guidance.

2. Use cases

Use this plugin whenever you have already segmented elongated structures into a single binary ROI but need them split into per-fiber labels for further analysis. Typical cases:

• Fiber networks: carbon/glass-fiber composites, non-wovens, textiles, where fibers cross and touch and segmentation merges them.
• Crossing / touching fibers: two or more fibers appear fused at imaging resolution and must be cut at the crossing then reassigned.
• Bundles: bundled elongated structures that need splitting into single fibers for orientation, length, or diameter statistics.
• Elongated structures in porous materials: network-like skeletal structures that must be separated into individual objects for visualization or measurement.

Once split, each fiber becomes a label in the MultiROI, so you can measure volume, length, orientation, etc. per fiber, or colour by label to inspect the network.

Prerequisite: the input must be an existing binary Fiber ROI. This plugin does not segment the raw image - segment the ROI first with Dragonfly's tools, then split it here.

3. Installation and enabling

This plugin ships with the Prototype Apps Full Package and needs no separate installer. To install:

1. Unzip the Full Package to any short folder (e.g. C:\PL\, to avoid path-too-long errors).

2. Double-click Install_FullPackage.bat.

3. In the dialog, pick the core install mode (Fresh / Compatible) and tick Fiber ROI to MultiROI in the app list.

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

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

This plugin is unticked by default (all plugins are OFF in the installer); you must tick it to deploy it.

After the restart, the plugin appears at Prototype Apps ▸ Fiber ROI to MultiROI... (in the “Measurements & Analysis” section). Clicking it opens a dockable panel (tab named “Fiber ROI”) shown as a floating window by default; it can be moved and docked.

Changing your choice later

To enable or disable this plugin later, the easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager, and in the “Prototype Apps (Full Package)” list tick to deploy or untick to remove the menu entry; restart Dragonfly to apply. Disabling never deletes the plugin's built environment (venv), so re-enabling is instant. You can also re-run the installer at any time.

Uninstall

Double-click Uninstall_FullPackage.bat to remove all Full-Package menu items, plugins, and the central store. It keeps each plugin's built environment (venv) and lists those paths at the end so you can delete them manually to reclaim disk space.

4. Runtime environment and first-run setup

The plugin's algorithm runs in a dedicated venv, isolated from Dragonfly's Python. The Full Package downloads no dependencies at install time; you build the environment from the panel before first use.

What Setup Environment does

Open the plugin, go to the first tab 1 Setup, and click Setup Environment (scikit-image + scipy). This button:

• Creates an isolated venv under the installed code directory (default: a venv subfolder inside GenericMenuItems\FiberROIToMultiROI).
• Upgrades the venv's pip, setuptools, and wheel.
• Installs numpy, scipy, and scikit-image from PyPI (internet required).
• Runs a smoke test (imports numpy/scipy/skimage and calls skeletonize), printing each library version to confirm the environment works.
• On success, writes the venv python.exe path back into the panel's “Analysis venv python” field and saves it to the config.

Base Python can be left blank so the plugin auto-detects Dragonfly's or the system Python to build the venv; or click Browse... to pick a python.exe manually. Job root defaults to C:\FiberRoiJobs; each run creates a timestamped job subfolder there for intermediate files.

Internet / GPU / WSL / external-app requirements

Where the environment is installed

• venv: %LOCALAPPDATA%\comet\<Dragonfly version>\pythonUserExtensions\GenericMenuItems\FiberROIToMultiROI\venv (built by the Setup Environment button).
• Job folders: by default C:\FiberRoiJobs\fiber_roi_<timestamp>, holding the exported ROI mask and intermediate results.

If setup fails: a common cause is that the auto-detected Base Python lacks the venv module or a working pip. In the Setup tab, use Browse... to point at a working python.exe (e.g. Dragonfly's Python or the system Python) and retry. If an existing venv has no usable pip, the plugin rebuilds it automatically.

5. User interface

The panel has a title and a legend at the top (highlighting that red parameters are strongly image-dependent), six tabs in the middle, and a green status line plus a read-only log box (live progress) at the bottom. Each tab and control is described below, matching the code exactly.

Tab 1 Setup

• Analysis venv python (text field): path to the algorithm venv's python.exe; filled automatically by Setup Environment - usually no need to edit.
• Base Python (text field + Browse...): the base Python used to create the venv; blank = auto-detect Dragonfly / system Python.
• Job root (text field): the job root directory, default C:\FiberRoiJobs.
• Setup Environment (scikit-image + scipy) (button): builds the venv and installs dependencies.
• Footer note: reminds you it uses an isolated venv, deps are numpy/scipy/scikit-image, no GPU, internet only for first setup.

Tab 2 Input ROI

• Fiber ROI (dropdown + Refresh): selects the binary ROI to split; Refresh re-lists the ROIs in the current Dragonfly session (entries include shape info).
• Output MultiROI (text field): title of the final fiber MultiROI, default Fiber MultiROI.
• Skeleton MultiROI (text field): title of the skeleton preview object, default Fiber skeleton.

Tab 3 Skeleton

• Method (dropdown): skeletonization method - Lee (2D/3D, default), scikit-image default, legacy skeletonize_3d, per-Z 2D thin, per-Z 2D medial axis.
• Graph connectivity (dropdown): voxel-graph adjacency, 6 / 18 / 26 neighborhood, default 26.
• Min segment voxels (integer, red): shortest skeleton branch (voxels) to keep, range 1-1000000, default 3.
• Publish skeleton preview (as MultiROI) (checkbox): publish the skeleton preview (single-label MultiROI), default on.
• Run to Skeleton Preview (button): runs only to the skeleton and publishes the preview.

Tab 4 Graph/Junctions

• Junction degree >= (integer): skeleton voxels with degree at least this threshold are junctions, range 3-26, default 3.
• Cut radius (voxels) (integer, red): voxel radius removed around each junction, range 0-20, default 1.
• Publish junction / cut / segment / centerline debug (as ROI/MultiROI) (checkbox): publish junction, cut zone, segment, and centerline debug objects, default off.
• Run to Graph + Cut Preview (button): runs to the graph/cut stage and publishes the corresponding previews.

Tab 5 Reconnect

• Reconnect cut stubs by tangent direction (checkbox): reconnect cut branch stubs by tangent direction, default on.
• Reconnect search radius (double, red): max gap bridged when rejoining (voxels), range 0-200, 2 decimals, default 6.00.
• Minimum opposite angle (double, red): how straight two stubs must be to be joined (degrees; 180 = perfectly collinear), range 0-180, 1 decimal, default 120.0.
• Tangent sample voxels (integer, red): voxels used to estimate a stub's local direction, range 2-50, default 5.
• Final label mode (dropdown): “Expand labels to full ROI by nearest centerline” (default) or “Centerline labels only”.

Tab 6 Output

• Run Full Workflow + Create MultiROI (blue-highlighted button): runs the complete workflow and creates the final fiber MultiROI.
• Summary table (Metric / Value columns): shows run statistics (e.g. number of fibers) after completion.

6. Step-by-step usage

The full end-to-end flow is below. Use the two preview buttons to inspect the skeleton and cuts and tune the red parameters before running the full workflow.

Full end-to-end workflow

1. Prepare the binary Fiber ROI you want to split in Dragonfly.

2. Open Prototype Apps ▸ Fiber ROI to MultiROI....

3. On 1 Setup, click Setup Environment (first time only) and wait for the log to report the environment is ready and the Analysis venv python is filled in.

4. Go to 2 Input ROI, click Refresh, select your ROI in Fiber ROI, and adjust the Output / Skeleton MultiROI titles if desired.

5. Go to 3 Skeleton, choose Method (Lee recommended for 3D fibers) and Graph connectivity (default 26), set Min segment voxels, then click Run to Skeleton Preview to check the skeleton (spurs, breaks).

6. Go to 4 Graph/Junctions, set Junction degree >= and Cut radius (about half the fiber diameter in voxels); enable debug publishing and click Run to Graph + Cut Preview to verify junctions are cleanly cut.

7. Go to 5 Reconnect, tune Reconnect search radius, Minimum opposite angle, and Tangent sample voxels for your fiber morphology, and pick a Final label mode.

8. Go to 6 Output, click Run Full Workflow + Create MultiROI, wait for the log to finish; the final fiber MultiROI is imported into Dragonfly and the Summary table shows the statistics.

Skeleton preview (single step)

1. Complete Setup and select the Input ROI.

2. On tab 3 Skeleton, adjust method / connectivity / min-branch, then click Run to Skeleton Preview.

3. Inspect the skeleton preview (single-label MultiROI) in Dragonfly and iterate until satisfied.

Graph + cut preview (single step)

1. On tab 4 Graph/Junctions, set the junction threshold and cut radius, and enable debug publishing.

2. Click Run to Graph + Cut Preview.

3. Inspect the junction / cut zone / segment / centerline debug objects, confirm the crossings are cut appropriately, then fine-tune the cut radius.

Input requirements: you must select a Fiber ROI and have completed Setup (an Analysis venv python exists), otherwise clicking Run shows “Select a Fiber ROI first.” or “Run Setup first...” in the status line.

7. Parameter reference

The table lists every tunable parameter, its default, and its meaning. Parameters marked (red) are strongly image-dependent and must be tuned to your data.

8. Outputs

Every object the plugin creates is a segmentation object (ROI / MultiROI), never a raw image Channel. Binary previews (skeleton, junctions, cut zone) are published as single-label MultiROIs; labelled maps (segments, centerlines, final fibers) as multi-label MultiROIs. Import builds the label volume through a temporary, auto-deleted Channel, so no extra image Channel is left in the scene.

After a run, the Summary table on the Output tab shows run statistics (Metric / Value), such as the number of fibers created (n_fibers), and the status line reports “Created N fiber(s)” and the job directory. Intermediate files are saved under C:\FiberRoiJobs\fiber_roi_<timestamp> for traceability.

9. FAQ and troubleshooting

Q1: Running shows “Select a Fiber ROI first.” or “Run Setup first...”

A: The former means no ROI is selected on the Input ROI tab - click Refresh and pick a binary ROI from the dropdown. The latter means the Analysis venv is not set - go to the Setup tab and click Setup Environment (or fill in a valid venv python path manually).

Q2: Setup Environment fails (venv creation or dependency install errors)

A: A common cause is that the auto-detected Base Python lacks the venv module or a working pip, or there is no network during first setup. Ensure PyPI is reachable, and in the Setup tab use Browse... to point at a python.exe that includes venv and pip (e.g. Dragonfly's Python), then retry. A broken existing venv is rebuilt automatically.

Q3: Crossing fibers are not separated, or fibers are cut too finely

A: This is governed by Cut radius. Still merged at crossings = cut radius too small; raise it (about half the fiber diameter in voxels). Over-fragmented = cut radius too large; lower it. Re-check with Run to Graph + Cut Preview before running the full workflow.

Q4: A single fiber is split into pieces, or neighbours are wrongly merged

A: This concerns the reconnect parameters. A single fiber split = Reconnect search radius too small or Minimum opposite angle too high; neighbours merged = search radius too large or opposite angle too low. Set the search radius near your data's typical gap size, and tune the opposite angle by fiber curvature (lower for curvy, higher for straight). Adjusting Tangent sample voxels can stabilize direction estimates.

Q5: The skeleton has many spurs or short false branches

A: Raise Min segment voxels to drop overly short skeleton branches; if needed, change the Method (try per-Z-slice methods for planar fiber sheets) or adjust Graph connectivity.

Q6: A preview / debug object comes out empty

A: Some optional previews can legitimately be empty (e.g. a network with no junctions); the plugin skips them and notes this in the log without aborting the run.

10. Notes and known limitations

• The red parameters (cut radius, min segment voxels, reconnect radius, min opposite angle, tangent sample voxels) have no value that is correct for every fiber network - the defaults are only a starting point. Tune them to your data and use the two preview buttons first.
• Reconnect is a heuristic: it greedily pairs the two stubs whose directions are closest to opposite around each cut junction, and may err on highly curved, densely tangled, or near-parallel crossings - verify with the debug previews.
• The per-Z 2D skeletonization methods (2D thin / 2D medial axis) do not connect across Z and suit only near-planar fiber masks.
• The input must be a binary Fiber ROI; the plugin does not segment the raw image.
• First use requires internet to build the venv; on long-offline machines, complete Setup on a networked machine before going offline.
• Runs accumulate timestamped job folders under Job root (default C:\FiberRoiJobs); clean them periodically to free disk space.

11. References

• scikit-image (skeletonization / medial axis / image processing): https://scikit-image.org
• SciPy (distance transforms / labeling): https://scipy.org
• NumPy: https://numpy.org
• Dragonfly 3D World: https://www.theobjects.com/dragonfly/

For more install/enable details, see the overview manual UserManual_用户手册.docx in the root of the Full Package.