OpenFiberSeg（纤维分离）插件 用户手册
OpenFiberSeg (Fiber Separation) Plugin - User Manual
Dragonfly Prototype Apps · OpenFiberSeg (Fiber Separation)
版本 Version 1.0 · 2026-07-10
第一部分 中文手册
目录
1. 概述
2. 算法与流程
3. 适用场景
4. 环境需求与安装
5. 操作步骤
6. 参数说明
7. 速度与精度模式
8. 输出说明
9. 与内置版的区别
10. 常见问题
11. 许可与致谢
1. 概述
OpenFiberSeg (Fiber Separation) 把一个已分割好的二值 Fiber ROI 分离成逐根纤维的 MultiROI（每根纤维一个标签/颜色），便于做取向、长度、数量等统计与可视化。它采用 OpenFiberSeg 纤维追踪算法（分水岭找中心点 → 沿方向逐根追踪 → 体素归属 → 体积后处理）。
本插件是一个完全独立的实现：与 Dragonfly 菜单 Workflows 里内置的 “Open Fiber Segmentation (beta)” 没有任何共享代码或依赖，运行在插件自己的 Python 环境里，因此更快、参数更友好，且不会互相影响。
2. 算法与流程
对输入的二值纤维体，算法依次执行：
1. 分水岭提取中心点：在纤维内部找到每根纤维的候选中心种子。
2. 逐根追踪：从中心点出发，沿局部方向把同一根纤维的体素连成一条中心线。
3. 体素归属：把每个前景体素分配给最近的、方向一致的纤维中心线。
4. 体积后处理：填补/清理标签体，得到干净的逐根标签。
5. （仅 Full 模式）三轴合并：对 X/Y/Z 三个轴排列各跑一遍并合并，处理各方向的纤维。
输出为一个 MultiROI（每根纤维一个标签），可选再输出一个中心线 MultiROI。
3. 适用场景
适用于短纤维增强复合材料等 CT 数据：纤维已被二值分割成一整块 ROI，但需要拆成单根纤维。
- 纤维密集、相互接触、近平行——骨架法容易把相邻纤维并成一根，方向追踪能更好地分开。
- 需要按单根纤维统计取向、长度、直径、数量、体积分数等。
- 需要每根纤维单独着色的可视化。
如果纤维较稀疏、交叉明显，更轻量的 Fiber ROI to MultiROI（骨架法）通常也够用且更快。
4. 环境需求与安装
输入需要一个已存在的二值 Fiber ROI（前景=纤维）。
首次使用请在 Setup 标签页点击 Setup Environment：它会创建一个独立的 Python venv 并安装 numpy(<2)、scipy、scikit-image、opencv-python。
- 安装时需要联网；运行时不需要 GPU。
- 计算在这个独立 venv 里多核并行运行，与 Dragonfly 主进程隔离。
- 如自动探测不到基础 Python，可在 Base Python 里手动指定（如 Dragonfly 的
Python_env\python.exe或系统 Python）。
5. 操作步骤
1. 1 Setup：（首次）点击 Setup Environment 建好 venv，状态显示 “Environment ready.”。
2. 2 Input：点 Refresh 选择要分离的 Fiber ROI；填写输出 MultiROI 名称；如需中心线，勾选 “Also output fiber centerlines”。
3. 3 Parameters：先在 Preset 里选一个预设（Default / Thin / Thick / Dense）并点 Apply preset，再按需要微调红色的图像相关参数。
4. 4 Run：选择 Fast（单轴，默认，约快 3 倍）或 Full（三轴，最精确），点击 “Run Fiber Separation + Create MultiROI”。
5. 运行结束后，分离出的逐根纤维会作为 MultiROI 发布到数据树；下方汇总表显示纤维数量与耗时。
6. 参数说明
长度类参数以体素为单位（面板内部按体素处理，无需换算物理单位）。标为红色的参数强烈依赖图像。
参数 | 默认 | 单位 | 说明 |
Fiber diameter (纤维直径) | 6 | 体素 | 纤维的典型直径，用于把追踪出的中心线扩张回完整纤维。依赖图像。 |
Min fiber length (最短长度) | 8 | 体素 | 保留的最短纤维长度。调大可去掉短的伪纤维；过大会删掉真实短纤维。 |
Max stitching distance (拼接距离) | 3 | 体素 | 把两段共线的追踪片段拼成一根纤维时允许的最大间隙。 |
Initial water level (水位) | 1.0 | 像素 | 分水岭种子的初始水位。调低得到更多、更小的中心点。 |
Convexity defect (凸缺陷) | 1.0 | 像素 | 在凹陷处分开相接纤维的强度。调大更激进地拆开粘连纤维。 |
Post-process all fibers | 开 | - | 对标签体做填充/清理，得到更干净的结果。 |
预设是常见情形的参数打包：Default（通用）、Thin fibers（细纤维）、Thick fibers（粗纤维）、Dense / noisy（密集/噪声多）。选预设后仍可逐项微调。
7. 速度与精度模式
- Fast（单轴，默认）：只沿一个轴排列跑一遍，跳过内置版会做的另外两个轴排列与合并步骤，约提速 3 倍。多数数据已足够。
- Full（三轴，最精确）：对三个轴排列各跑一遍并合并，能更好地处理各个方向的纤维，但耗时约为 3 倍。
内置版总是跑三轴，这是它慢的主要原因之一。本插件默认 Fast，需要极致精度时再切 Full。
8. 输出说明
- 分割纤维 MultiROI（默认）：每根纤维一个标签/颜色。
- 中心线 MultiROI（可选）：勾选后额外输出每根纤维的中心线。
两者都是分割对象（MultiROI），可直接用于测量、统计或作为后续流程的输入。
9. 与内置版的区别
- 独立：不依赖、不修改 Dragonfly 内置的 Open Fiber Segmentation。
- 更快：默认单轴（内置版固定三轴），并在独立 venv 里多核运行。
- 更友好：向导式四标签页 + 预设 + 悬停提示，参数含义清晰。
- 算法一致：核心追踪算法与内置版同源（MIT），因此结果质量可比。
10. 常见问题
- 没有分出纤维 / 数量偏少：调低 Initial water level、调小 Min fiber length，或换 “Thin fibers” 预设。
- 相邻纤维被并成一根：调大 Convexity defect，或试试 Full 模式。
- 碎的伪纤维太多：调大 Min fiber length。
- 很慢：先用 Fast 模式；大体数据可先裁剪一小块试参数。
- Setup 失败：在 Base Python 指定一个带 pip 的 Python，并确认可联网。
11. 许可与致谢
核心纤维追踪算法为 OpenFiberSeg，版权归 Facundo Sosa-Rey（2021），以 MIT 许可使用；插件内保留了 LICENSE 与署名。其余部分（面板、桥接、封装）为本项目所写。
Part Two: English Manual
Contents
1. Overview
2. Algorithm & pipeline
3. When to use
4. Requirements & setup
5. Step-by-step
6. Parameters
7. Fast vs Full mode
8. Outputs
9. Differences from the built-in
10. Troubleshooting
11. License & credits
1. Overview
OpenFiberSeg (Fiber Separation) takes an already-segmented binary Fiber ROI and separates it into individual fibers (a MultiROI) - one label/colour per fiber - for orientation, length and count statistics or visualization. It uses the OpenFiberSeg fiber-tracking algorithm (watershed center points -> orientation-guided per-fiber tracking -> voxel assignment -> volumetric post-processing).
This plugin is a fully independent implementation: it shares no code or dependency with Dragonfly's built-in "Open Fiber Segmentation (beta)" (Workflows menu). It runs in its own Python environment, so it is faster, friendlier, and cannot interfere with the built-in one.
2. Algorithm & pipeline
For the input binary fiber volume, the algorithm runs, in order:
1. Watershed center points: find a candidate seed inside each fiber.
2. Per-fiber tracking: from each seed, follow the local orientation to link one fiber's voxels into a centerline.
3. Voxel assignment: assign every foreground voxel to the nearest, orientation-consistent fiber.
4. Volumetric post-processing: fill/clean the labelled volume for tidy per-fiber labels.
5. (Full mode only) 3-axis combination: run once per X/Y/Z axis permutation and merge, to catch fibers in all directions.
The output is a MultiROI (one label per fiber), with an optional centerline MultiROI.
3. When to use
For CT of short-fiber-reinforced composites (and similar) where the fibers are already binarised as one ROI but must be split into per-fiber labels.
- Fibers that are dense, touching, near-parallel - a skeleton method merges neighbours into one; orientation tracking separates them better.
- You need per-fiber orientation, length, diameter, count or volume-fraction statistics.
- You want a per-fiber coloured visualization.
If fibers are sparse with clear crossings, the lighter Fiber ROI to MultiROI (skeleton method) is usually enough and faster.
4. Requirements & setup
The input is an existing binary Fiber ROI (foreground = fibers).
On first use, open the Setup tab and click Setup Environment: it creates an isolated Python venv and installs numpy(<2), scipy, scikit-image and opencv-python.
- Internet is needed once for setup; no GPU is required at run time.
- Compute runs multi-core inside that isolated venv, separate from the Dragonfly process.
- If the base Python is not auto-detected, set Base Python manually (e.g. Dragonfly's
Python_env\python.exeor a system Python).
5. Step-by-step
1. 1 Setup (first time): click Setup Environment; wait for "Environment ready.".
2. 2 Input: Refresh and pick the Fiber ROI; name the output MultiROI; tick "Also output fiber centerlines" if wanted.
3. 3 Parameters: pick a Preset (Default / Thin / Thick / Dense) and click Apply preset, then fine-tune the red image-dependent knobs.
4. 4 Run: choose Fast (single axis, default, ~3x faster) or Full (3 axes, most accurate), then click "Run Fiber Separation + Create MultiROI".
5. When it finishes, the separated fibers are published as a MultiROI; the summary table shows the fiber count and timing.
6. Parameters
Length parameters are in voxels (the panel works in voxels; no physical-unit conversion needed). Red parameters are strongly image-dependent.
Parameter | Default | Unit | Meaning |
Fiber diameter | 6 | voxels | Typical fiber diameter; grows tracked centerlines back to full fibers. Image-dependent. |
Min fiber length | 8 | voxels | Shortest tracked fiber kept. Raise to drop short spurious fibers; too high deletes real short fibers. |
Max stitching distance | 3 | voxels | Largest gap bridged when stitching two collinear tracked segments into one fiber. |
Initial water level | 1.0 | pixels | Initial water level for the watershed that seeds fiber center points. Lower = more, smaller seeds. |
Convexity defect | 1.0 | pixels | How strongly touching fibers are split at concave necks. Raise to split merged fibers more aggressively. |
Post-process all fibers | on | - | Fill/clean the labelled volume for a tidier result. |
Presets bundle the knobs for common cases: Default (general), Thin fibers, Thick fibers, Dense / noisy. You can still fine-tune after applying one.
7. Fast vs Full mode
- Fast (single axis, default): one axis pass; skips the two extra axis permutations AND the combine step the built-in does - ~3x faster. Enough for most data.
- Full (3 axes, most accurate): runs all three axis permutations and merges them, better for fibers in every direction, at ~3x the time.
The built-in always runs 3 axes, a main reason it is slow. This plugin defaults to Fast; switch to Full only when you need maximum accuracy.
8. Outputs
- Segmented fibers MultiROI (default): one label/colour per fiber.
- Centerline MultiROI (optional): the centerline of each fiber, when ticked.
Both are segmentation objects (MultiROI), ready for measurement, statistics, or as input to later workflows.
9. Differences from the built-in
- Independent: does not depend on or modify Dragonfly's built-in Open Fiber Segmentation.
- Faster: single-axis by default (the built-in is fixed at 3 axes) and multi-core in its own venv.
- Friendlier: a 4-tab wizard with presets and hover tooltips; clear parameter meanings.
- Same algorithm: the core tracking is the same source (MIT), so result quality is comparable.
10. Troubleshooting
- No / too few fibers: lower Initial water level, lower Min fiber length, or try the "Thin fibers" preset.
- Neighbours merged into one fiber: raise Convexity defect, or try Full mode.
- Too many fragmentary fibers: raise Min fiber length.
- Slow: use Fast mode; for big volumes, crop a small block first to tune parameters.
- Setup fails: point Base Python at a Python that has pip, and ensure internet access.
11. License & credits
The core fiber-tracking algorithm is OpenFiberSeg, Copyright Facundo Sosa-Rey (2021), used under the MIT License; the LICENSE and attribution are kept inside the plugin. The rest (panel, bridge, packaging) was written for this project.