纤维取向(结构张量)插件用户手册

Fiber Orientation (structure tensor) - User Manual

Dragonfly Prototype Apps · Fiber Orientation (structure tensor)...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

1.1 算法原理简述

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

5.1 Input volume(输入体数据)

5.2 Structure-tensor parameters(结构张量参数)

5.3 Publish result channels(发布哪些结果通道)

5.4 Environment(环境)与操作按钮

6. 使用步骤

6.1 首次配置(仅一次)

6.2 计算纤维取向(端到端)

6.3 结果显示建议

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Fiber Orientation (structure tensor)(纤维取向,结构张量法)是 Dragonfly 的 Prototype Apps 插件之一,用于基于结构张量(structure tensor)方法计算三维 CT 体数据中纤维/管状结构的逐体素局部取向。选择一个图像 Channel,设置结构张量的两个高斯尺度(噪声尺度 sigma 与积分尺度 rho)和相干性阈值后,点击 Compute Fiber Orientation;插件逐体素求解主取向,并把取向角、主方向分量以及相干性(各向异性程度)等标量场作为新的 Channel 发布回 Dragonfly,与源数据网格严格对齐,可直接用色图显示,直观呈现纤维走向与排布。

计算引擎为开源库 structure-tensor(Skielex/structure-tensor,固定版本 0.3.4,MIT 许可),依赖 numpy(BSD 许可)与 scipy(BSD 许可)。三者均为宽松开源许可,可放心用于商业环境。重计算在插件专用的 Python 虚拟环境(venv)中以独立子进程运行,不影响 Dragonfly 主程序的稳定性,也不向 Dragonfly 自带的 Python 安装任何东西。

1.1 算法原理简述

结构张量方法的流程:先用高斯导数尺度 sigma 对体数据平滑并求灰度梯度,由梯度外积构成结构张量,再用积分尺度 rho 在邻域内对张量做高斯平均;随后对每个体素的结构张量做特征分解。灰度沿纤维轴向变化最小,因此最小特征值对应的特征向量就是纤维轴方向。

• Coherence(相干性) = (μ3 − μ1) / (μ3 + μ1),取值 [0, 1](μ1 ≤ μ2 ≤ μ3 为三个特征值)。取向一致的纤维区数值高,各向同性或噪声区数值低,可作为"各向异性程度"图使用。
• Azimuth(方位角) = atan2(vy, vx),折叠到 [0, 180) 度——取向是一条"线"而非"箭头",0 度与 180 度等价。
• Elevation(仰角) = asin(|vz|),取值 [0, 90] 度;0 度表示纤维躺在 XY 平面内,90 度表示沿 Z 轴。
• vx、vy、vz(方向分量,可选):逐体素单位纤维方向向量,符号统一折叠为 vz ≥ 0(线取向的符号无物理意义)。

相干性低于阈值(coherence threshold)的体素被认为不属于纤维,其角度值被置空(内部为 NaN,导入 Dragonfly 时写为 0),这样只有真正的纤维体素才携带取向信息。计算结束后面板给出一行摘要:纤维体素数与占比、平均相干性、平均方位角/仰角以及各向异性程度。

2. 适用场景

本插件面向材料科学与工业 CT 中的纤维取向表征,也适用于生命科学中的定向结构分析:

• 纤维增强复合材料(FRP):玻璃纤维、碳纤维增强塑料的纤维排布检查与局部取向成图;
• 无纺布、木材、纸张等纤维材料的取向分布分析;
• 从 CT 扫描定量评估各向异性程度(degree of anisotropy);
• 生命科学中胶原纤维、肌纤维等定向组织结构的取向分析。

本插件输出的是逐体素取向场,不是逐根分割的纤维。若需要单根纤维的数量、长度等统计,应配合专门的纤维分割工具使用。

3. 安装与启用

本插件随 Prototype Labs & Apps 完整安装包(Full Package)发布,通过图形化安装器一键安装,自动装入本机所有 Dragonfly 版本,无需管理员权限(全部安装在当前用户的 %LOCALAPPDATA% 下)。

1. 把安装包 zip 解压到任意较短路径的文件夹(如 C:\PL\,避免很深的下载目录或 OneDrive 重定向桌面)。

2. 双击 `Install_FullPackage.bat` 打开安装对话框。

3. 在 Prototype Apps 列表中勾选 `Fiber Orientation (structure tensor)...`——所有插件默认不勾选,必须手动勾选本插件。

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

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

重启后,菜单项出现在 Prototype Apps ▸ Fiber Orientation (structure tensor)...(位于 Measurements & Analysis 分区)。点击后打开一个浮动的可停靠面板,可自由移动、停靠或悬浮,并可随工作区保存。

以后启用/停用:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部 "Prototype Apps (Full Package)" 列表中勾选或取消本插件,重启 Dragonfly 生效。停用从不删除插件已搭建的运行环境(venv),重新启用后立即可用。也可以随时重跑安装器(它记住上次的勾选作为默认值);即使删除了解压目录,也可运行 %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat。

卸载:双击 `Uninstall_FullPackage.bat`(安装器目录中也有一份)。它会移除所有 Full Package 菜单项与插件,但保留每个插件的运行环境;结束时会列出这些路径,需要腾出磁盘空间时可手动删除。

4. 运行环境与首次配置

安装时不下载任何东西。首次使用前需在面板里点一次 `Setup Environment`,为插件搭建专用的 Python 虚拟环境。面板 Environment 区的 Status 显示 "Not set up - click 'Setup Environment'..." 即表示尚未搭建;搭建成功后显示 "Ready: <venv 的 python 路径>"。

Setup Environment 具体做什么:用一个基础 Python(默认使用 Dragonfly 自带的 Python,即安装目录下 Python_env\python.exe 的完整 CPython 3.10,无需另装 Python)在插件代码目录内创建 venv,升级 pip/setuptools/wheel,然后从默认 PyPI 源 pip 安装 structure-tensor==0.3.4 + numpy + scipy(在 CPython 3.10 上均为纯 wheel,无 CUDA、无源码编译),最后运行一次导入自检并记录 venv 的 Python 路径供后续计算使用。若已有可用的 venv,再次点击会直接复用而不是重建。

• 下载体积:约几十 MB,通常数十秒完成;
• 联网:仅首次搭建需要联网,之后完全离线可用;
• GPU:不需要;WSL:不需要;
• 隔离性:不向 Dragonfly 自带 Python 或基础解释器安装任何包。

安装位置:venv 建在插件代码目录内:%LOCALAPPDATA%\comet\<Dragonfly版本>\pythonUserExtensions\GenericMenuItems\FiberOrientation\venv。面板设置(如 Base Python)保存在同目录的 fiber_config.json。更新插件代码时,venv 与设置文件都会被保留。每个 Dragonfly 版本有各自独立的代码目录,因此在不同版本中首次使用时需各自点一次 Setup Environment。

Base Python 覆盖:Environment 区的 Base Python 输入框留空即使用 Dragonfly 自带 Python;也可以填某个 python.exe 的完整路径,或类似 py -3.11 的命令。若默认基础解释器没有可用的 pip,插件会自动搜索系统中的其他 CPython(py 启动器 -3.12/-3.11/-3.10、PATH 上的 python、%LOCALAPPDATA%\Programs\Python、C:\Python3x、Program Files 以及 miniconda/anaconda/miniforge 的常见安装位置),逐个用 pip 探测后取第一个可用者。

失败时的替代方案:安装任意 CPython 3.10-3.12(需自带 venv 与 pip,Windows 官方安装包默认满足),把其 python.exe 完整路径填入 Base Python,再点一次 Setup Environment。structure-tensor 需要 CPython 3.10 以上且有 numpy/scipy 的 wheel(Windows 上为 3.10-3.12)。

5. 界面说明

面板为单页布局,自上而下依次为:输入区、参数区、输出选择区、环境区、操作按钮行、摘要行与日志窗口。所有控件均与下文一一对应。

5.1 Input volume(输入体数据)

• Channel 下拉框:列出当前 Dragonfly 会话中的所有图像 Channel,显示格式为 "名称 (Z x Y x X 尺寸)"。当没有可用数据时显示 "(no channels - load a volume in Dragonfly)"。
• Refresh 按钮:重新扫描会话中的 Channel 列表(在 Dragonfly 中新加载数据后点它刷新)。

5.2 Structure-tensor parameters(结构张量参数)

• sigma (noise scale):导数(噪声)尺度,求梯度前的高斯平滑量。数值越大,噪声抑制越强。数字微调框,范围 0.1-20.0,步长 0.5,默认 1.5。
• rho (integration scale):积分(邻域)尺度,决定取向在多大范围内平均,量级约等于纤维间距。范围 0.1-40.0,步长 0.5,默认 4.0。
• coherence threshold:相干性阈值。低于该值的体素不给出取向(保持为背景),用于滤除非纤维区域。范围 0.0-1.0,步长 0.05,默认 0.2。

5.3 Publish result channels(发布哪些结果通道)

• Coherence (anisotropy, 0-1)——默认勾选;
• Azimuth (in-plane angle, 0-180 deg)——默认勾选;
• Elevation (out-of-plane angle, 0-90 deg)——默认勾选;
• Direction components vx, vy, vz (3 channels)——默认不勾选;勾选后一次发布 3 个方向分量 Channel。

5.4 Environment(环境)与操作按钮

• Base Python 输入框:留空 = 使用本 Dragonfly 自带的 Python;也可填 python.exe 路径或 py -3.11 之类的命令(提示文字:"blank = this Dragonfly's python; or a path / 'py -3.11'")。
• Status 标签:显示环境状态——"Ready: <路径>" 或 "Not set up - click 'Setup Environment'..."。
• Setup Environment 按钮:一次性搭建/复用计算环境(见第 4 章)。
• Compute Fiber Orientation 按钮:启动计算。计算进行时两个按钮均置灰,防止重复启动。
• 摘要行:计算完成后显示一行统计结果(可用鼠标选中复制)。
• 日志窗口:只读,滚动显示环境搭建输出、计算进度百分比与阶段信息、发布结果与错误详情。

6. 使用步骤

6.1 首次配置(仅一次)

1. 确认本机可以联网(仅此一次需要)。

2. 打开 Prototype Apps ▸ Fiber Orientation (structure tensor)...。

3. (可选)在 Base Python 中填入自选的 CPython;通常留空即可。

4. 点击 `Setup Environment`,在日志中观察 venv 创建与 pip 安装输出。

5. 等待日志出现 "Environment ready: ...",Status 变为 "Ready: ..." 即完成。

6.2 计算纤维取向(端到端)

1. 在 Dragonfly 中加载或选择一个三维灰度体数据(CT 体数据的 Channel)。

2. 打开插件面板;若下拉框中没有该数据,点 Refresh,然后在 Channel 下拉框中选中它(名称后括号内为 Z x Y x X 尺寸,便于确认)。

3. 设置 sigma(建议从 1-2 个体素起步,噪声大时调大)与 rho(建议从 3-6 个体素起步,约等于纤维间距;越大取向越平滑、越稳健,但局部细节越少)。

4. 设置 coherence threshold(默认 0.2;调大则只保留取向非常明确的体素)。

5. 在 Publish result channels 中勾选需要的输出(默认发布 Coherence、Azimuth、Elevation)。

6. 点击 `Compute Fiber Orientation`。日志会显示 "=== Compute fiber orientation (sigma=..., rho=..., coh>=...) ===",随后是读取体数据、逐阶段进度百分比(计算结构张量 → 特征分解 → 求取向与相干性 → 统计摘要)。

7. 计算完成后,勾选的结果作为新 Channel 直接出现在当前场景中(无需重启),日志列出 "Published channels: ...",摘要行给出统计数字。

6.3 结果显示建议

1. 在 Dragonfly 中给 Azimuth 通道套用一个环形/彩虹类色图,即可直观看到不同走向的纤维呈不同颜色。

2. 把 Coherence 通道作为可靠性参考:相干性高的区域取向可信,接近 0 的区域(孔隙、基体、噪声)取向无意义。

3. 需要做定量方向统计时,勾选 Direction components vx, vy, vz 重新计算,得到逐体素单位方向向量。

角度通道中被阈值滤除的体素在导入时写为 0(内部为 NaN)。因此角度图中的 0 值既可能是"真 0 度",也可能是"无取向背景";判读时请结合 Coherence 通道或提高阈值。

7. 参数说明

8. 输出结果

计算结果以新的 Channel 形式发布到当前 Dragonfly 场景,命名规则为 "<源 Channel 名> - <结果名>",全部与源数据网格严格对齐(体素间距与原点从源数据复制),可直接与原图叠加或联动显示:

摘要行同时给出整卷统计:纤维体素数 / 总体素数(百分比)、平均相干性、平均方位角(轴向圆均值)、平均仰角、各向异性程度。这些均值均按相干性加权,只统计通过阈值的纤维体素。

每次计算的中间文件写在 Windows 临时目录下一个 fiber_ 前缀的任务文件夹中(config.json、status.json、results.json 及 fiber_*.npy 数组)。其中 results.json 除摘要外还包含一个 36 柱、按相干性加权的方位角直方图(0-180 度),可供自行绘制玫瑰图等后处理使用。

9. 常见问题与故障排除

问 1:Prototype Apps 菜单里找不到本插件?
答:本插件在 Full Package 安装器中默认不勾选,请确认安装时勾选了它;菜单只在 Dragonfly 启动时扫描,任何启用/停用改动都需要完全重启 Dragonfly。也可在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 底部列表中勾选后重启。

问 2:Setup Environment 失败,日志提示 "No base Python found to build the venv" 或 pip 不可用?
答:说明默认基础解释器不可用且自动搜索也未找到可用的 CPython。请安装 CPython 3.10-3.12(官方安装包自带 venv 与 pip),把其 python.exe 完整路径填入 Base Python,再点一次 Setup Environment。同时确认本机能访问 PyPI(首次搭建需联网)。

问 3:点 Compute 后日志提示 "ERROR: environment not set up. Click 'Setup Environment' first."?
答:计算环境尚未搭建或已被删除。先点 `Setup Environment`,等 Status 显示 "Ready: ..." 后再计算。

问 4:Channel 下拉框显示 "(no channels - load a volume in Dragonfly)"?
答:当前会话没有可用的图像 Channel。请先在 Dragonfly 中加载三维体数据,再点 Refresh 刷新列表。

问 5:计算报 "Out of memory - try a smaller ROI or downsample the volume."?
答:体数据过大,计算内存不足。整卷会被读入内存并以浮点精度计算结构张量,内存占用是原始数据的很多倍。请先在 Dragonfly 中裁剪感兴趣区域或对体数据降采样,再重新计算。

问 6:角度图里大片区域都是 0 度,是纤维都朝一个方向吗?
答:不一定。低于相干性阈值的体素角度被置空并在导入时写为 0,背景与孔隙因此也显示为 0 度。请叠加 Coherence 通道判读:只有相干性高的 0 度才是真实取向。必要时提高 coherence threshold 让非纤维区更干净。

问 7:需要 GPU 吗?每次使用都要联网吗?
答:都不需要。计算为纯 CPU(numpy/scipy),只有首次 Setup Environment 需要联网下载几十 MB 的依赖,之后完全离线可用。

10. 注意事项与已知限制

• 取向是"线"不是"箭头":方位角折叠到 0-180 度,仰角 0-90 度,方向分量符号统一为 vz ≥ 0;相差 180 度的方向视为同一取向。
• 输出为逐体素取向场,不做单根纤维分割,无法直接给出纤维数量、长度分布等统计;此类需求应配合纤维分割工具。
• 整卷一次性读入并以浮点精度计算(结构张量含多个分量),大体数据内存开销显著;遇到内存不足请裁剪 ROI 或降采样。
• 角度通道中 0 值有二义性(真 0 度 vs. 被阈值滤除的背景),请结合 Coherence 通道判读(见第 6.3 节)。
• 参数敏感性:sigma 过大会抹掉细纤维;rho 过小取向噪声大、过大则丢失局部变化。建议先在小 ROI 上试参。
• 运行环境按 Dragonfly 版本各自独立(venv 位于各版本的插件代码目录内),在新的 Dragonfly 版本中首次使用需再点一次 Setup Environment。
• 菜单的启用/停用只在 Dragonfly 启动时生效,每次修改后需完全重启一次。
• 计算结果通道的发布无需重启,完成后立即出现在场景中。

11. 参考资料

• structure-tensor(计算引擎,MIT 许可,版本 0.3.4):https://github.com/Skielex/structure-tensor
• numpy(BSD 许可):https://numpy.org
• scipy(BSD 许可):https://scipy.org
• Prototype Labs & Apps Full Package 安装说明:随安装包附带的 README(安装、Menu Item Manager、卸载与路径过长问题均有中英双语说明)。

Part II English Manual

Contents

1. Overview

1.1 How the algorithm works

2. Use cases

3. Installation and enabling

4. Runtime environment and first-run setup

5. User interface

5.1 Input volume

5.2 Structure-tensor parameters

5.3 Publish result channels

5.4 Environment group and action buttons

6. Step-by-step usage

6.1 First-time setup (once)

6.2 Computing fiber orientation (end to end)

6.3 Display tips

7. Parameter reference

8. Outputs

9. FAQ and troubleshooting

10. Notes and known limitations

11. References

1. Overview

Fiber Orientation (structure tensor) is a Dragonfly Prototype Apps plugin that computes the per-voxel local orientation of fibrous or tubular structures in 3D CT data using the structure-tensor method. Pick an image Channel, set the two structure-tensor Gaussian scales (noise scale sigma and integration scale rho) plus a coherence threshold, and click Compute Fiber Orientation; the plugin solves the dominant orientation per voxel and publishes orientation-angle, principal-direction, and coherence (degree of anisotropy) scalar fields back into Dragonfly as new Channels, exactly aligned with the source grid, ready for colormap display to reveal fiber directions and alignment.

The compute engine is the open-source library structure-tensor (Skielex/structure-tensor, pinned version 0.3.4, MIT license), with numpy (BSD) and scipy (BSD). All licenses are permissive. The heavy computation runs as a separate subprocess inside a dedicated Python virtual environment (venv), so it never destabilizes the Dragonfly host and installs nothing into Dragonfly's own Python.

1.1 How the algorithm works

The structure-tensor pipeline: the volume is smoothed at the derivative (noise) scale sigma before computing intensity gradients; the gradient outer products form the structure tensor, which is then averaged over a neighborhood at the integration scale rho; finally an eigen-decomposition is performed per voxel. Intensity varies least along a fiber, so the eigenvector of the smallest eigenvalue is the fiber axis.

• Coherence = (mu3 - mu1) / (mu3 + mu1), in [0, 1] (mu1 <= mu2 <= mu3 are the eigenvalues). High on well-aligned fibers, low in isotropic or noisy regions - a per-voxel "degree of anisotropy" map.
• Azimuth = atan2(vy, vx), folded to [0, 180) degrees - an orientation is a line, not an arrow, so 0 and 180 degrees are equivalent.
• Elevation = asin(|vz|), in [0, 90] degrees; 0 means the fiber lies in the XY plane, 90 means along Z.
• vx, vy, vz (optional) - unit fiber-direction components per voxel, sign-folded so that vz >= 0 (the sign of a line orientation is meaningless).

Voxels whose coherence falls below the coherence threshold are treated as non-fiber: their angles are blanked (NaN internally, written as 0 on import into Dragonfly), so only genuine fiber voxels carry an orientation. After the run, the panel shows a one-line summary: fiber-voxel count and fraction, mean coherence, mean azimuth/elevation, and degree of anisotropy.

2. Use cases

The plugin targets fiber-orientation characterization in materials science and industrial CT, and directional structures in life science:

• Fiber-reinforced composites (FRP): checking fiber alignment and mapping local orientation in glass-fiber / carbon-fiber parts;
• Nonwovens, wood, and paper fibers - orientation-distribution analysis;
• Quantifying the degree of anisotropy of a material from a CT scan;
• Life-science directional structures such as collagen or muscle fibers.

The output is a per-voxel orientation field, not individually segmented fibers. For per-fiber counts or length statistics, pair it with a dedicated fiber-segmentation tool.

3. Installation and enabling

The plugin ships with the Prototype Labs & Apps Full Package and installs through a graphical installer into every Dragonfly version on the PC. Everything is per-user (%LOCALAPPDATA%); no admin rights are needed.

1. Unzip the package anywhere with a short path (e.g. C:\PL\; avoid deep Downloads folders or a OneDrive-redirected Desktop).

2. Double-click `Install_FullPackage.bat` to open the installer dialog.

3. In the Prototype Apps list, tick `Fiber Orientation (structure tensor)...` - all plugins are unticked by default, so this plugin must be ticked explicitly.

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 entry appears under Prototype Apps ▸ Fiber Orientation (structure tensor)... (in the Measurements & Analysis section). Clicking it opens a floating, dockable panel that can be moved, docked, or left floating, and is savable with the workspace.

Enable/disable later: open Developer ▸ Prototype Labs... ▸ Menu Item Manager; the "Prototype Apps (Full Package)" list at the bottom has a checkbox per app - tick = deploy, untick = remove the menu entry; restart Dragonfly to apply. Disabling never deletes the plugin's environment (venv) - re-enabling is instant. You can also re-run the installer anytime (it remembers your previous choices); even after deleting the unzipped folder, run %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat.

Uninstall: double-click `Uninstall_FullPackage.bat` (also kept in the installer folder above). It removes all Full-Package menu items and plugins but keeps every plugin environment; the paths are listed at the end so you can delete them manually to reclaim disk space.

4. Runtime environment and first-run setup

Nothing is downloaded at install time. Before first use, click `Setup Environment` once in the panel to build the plugin's dedicated Python virtual environment. If the Status label in the Environment group reads "Not set up - click 'Setup Environment'...", the environment is missing; once built it reads "Ready: <path to the venv's python>".

What Setup Environment actually does: using a base Python (by default Dragonfly's own Python - the full CPython 3.10 at Python_env\python.exe inside the Dragonfly installation, so no separate Python install is needed), it creates a venv inside the plugin's code folder, upgrades pip/setuptools/wheel, then pip-installs structure-tensor==0.3.4 + numpy + scipy from the default PyPI index (pure wheels on CPython 3.10 - no CUDA, no source builds), runs an import smoke test, and records the venv's Python path for later runs. If a working venv already exists, clicking again reuses it instead of rebuilding.

• Download size: roughly tens of MB; typically finishes in seconds;
• Internet: needed only for this one-time setup; fully offline afterwards;
• GPU: not required; WSL: not required;
• Isolation: nothing is installed into Dragonfly's own Python or the base interpreter.

Where things live: the venv is created inside the installed code folder: %LOCALAPPDATA%\comet\<Dragonfly version>\pythonUserExtensions\GenericMenuItems\FiberOrientation\venv. Panel settings (e.g. Base Python) persist in fiber_config.json in the same folder. Both the venv and the settings survive plugin-code updates. Each Dragonfly version has its own code folder, so run Setup Environment once per Dragonfly version.

Base Python override: leave the Base Python field blank to use Dragonfly's own Python, or enter a full path to a python.exe, or a command like py -3.11. If the default base interpreter has no working pip, the plugin automatically searches for another CPython (the py launcher -3.12/-3.11/-3.10, python on PATH, %LOCALAPPDATA%\Programs\Python, C:\Python3x, Program Files, and common miniconda/anaconda/miniforge locations), probing each with pip and using the first that works.

Fallback if setup fails: install any CPython 3.10-3.12 (the official Windows installer includes venv and pip), put its full python.exe path into Base Python, and click Setup Environment again. structure-tensor requires CPython >= 3.10 with numpy/scipy wheels (3.10-3.12 on Windows).

5. User interface

The panel is a single page. From top to bottom: input group, parameter group, output-selection group, environment group, action buttons, then a summary line and a log window. Every control is documented below.

5.1 Input volume

• Channel combo box: lists every image Channel in the current Dragonfly session as "name (Z x Y x X size)". When no data is available it shows "(no channels - load a volume in Dragonfly)".
• Refresh button: re-scans the session's Channel list (click after loading new data in Dragonfly).

5.2 Structure-tensor parameters

• sigma (noise scale): derivative (noise) scale - Gaussian smoothing before the gradient; larger = more noise suppression. Spin box, range 0.1-20.0, step 0.5, default 1.5.
• rho (integration scale): integration (neighborhood) scale - over how large a region the orientation is averaged; roughly the fiber spacing. Range 0.1-40.0, step 0.5, default 4.0.
• coherence threshold: voxels below this coherence get no orientation (kept as background) - filters out non-fiber regions. Range 0.0-1.0, step 0.05, default 0.2.

5.3 Publish result channels

• Coherence (anisotropy, 0-1) - checked by default;
• Azimuth (in-plane angle, 0-180 deg) - checked by default;
• Elevation (out-of-plane angle, 0-90 deg) - checked by default;
• Direction components vx, vy, vz (3 channels) - unchecked by default; when ticked, three direction-component Channels are published in one run.

5.4 Environment group and action buttons

• Base Python field: blank = this Dragonfly's Python; or a python.exe path, or a command such as py -3.11 (placeholder text: "blank = this Dragonfly's python; or a path / 'py -3.11'").
• Status label: environment state - "Ready: <path>" or "Not set up - click 'Setup Environment'...".
• Setup Environment button: one-time environment build/reuse (see chapter 4).
• Compute Fiber Orientation button: starts the computation. Both buttons are disabled while a job is running to prevent double starts.
• Summary line: one line of statistics after a run (selectable with the mouse for copying).
• Log window: read-only; streams setup output, per-stage progress percentages, published-channel names, and full error details.

6. Step-by-step usage

6.1 First-time setup (once)

1. Make sure the machine has internet access (needed only this once).

2. Open Prototype Apps ▸ Fiber Orientation (structure tensor)....

3. (Optional) enter a CPython of your choice in Base Python; normally leave it blank.

4. Click `Setup Environment` and watch the venv creation and pip output in the log.

5. Wait for "Environment ready: ..." in the log; the Status label switches to "Ready: ...".

6.2 Computing fiber orientation (end to end)

1. Load or select a 3D grayscale volume (a CT Channel) in Dragonfly.

2. Open the panel; if the volume is missing from the combo box, click Refresh, then select it in the Channel dropdown (the Z x Y x X size in parentheses helps confirm the right one).

3. Set sigma (start around 1-2 voxels; increase for noisy data) and rho (start around 3-6 voxels, roughly the fiber spacing; larger = smoother, more robust orientation but less local detail).

4. Set the coherence threshold (default 0.2; raise it to keep only voxels with a very well-defined orientation).

5. Tick the desired outputs under Publish result channels (Coherence, Azimuth, and Elevation are published by default).

6. Click `Compute Fiber Orientation`. The log prints "=== Compute fiber orientation (sigma=..., rho=..., coh>=...) ===", then the volume read and per-stage progress percentages (structure tensor -> eigen-decomposition -> orientation + coherence -> summary statistics).

7. When the run finishes, the selected results appear as new Channels in the current scene immediately (no restart needed); the log lists "Published channels: ..." and the summary line shows the statistics.

6.3 Display tips

1. Apply a cyclic/rainbow-style colormap to the Azimuth Channel in Dragonfly - fibers with different in-plane directions light up in different colors.

2. Use the Coherence Channel as a reliability map: orientation is trustworthy where coherence is high and meaningless where it approaches 0 (pores, matrix, noise).

3. For quantitative direction work, re-run with Direction components vx, vy, vz ticked to get per-voxel unit direction vectors.

Voxels removed by the threshold are written as 0 in the angle Channels (NaN internally). A 0 in an angle map can therefore mean either "truly 0 degrees" or "no orientation / background" - always read angle maps together with the Coherence Channel, or raise the threshold.

7. Parameter reference

8. Outputs

Results are published as new Channels in the current Dragonfly scene, named "<source Channel name> - <result name>", all exactly aligned with the source grid (voxel spacing and origin copied from the source) so they overlay and link with the original data:

The summary line additionally reports whole-volume statistics: fiber voxels / total voxels (percentage), mean coherence, mean azimuth (axial circular mean), mean elevation, and degree of anisotropy. All means are coherence-weighted and computed over fiber voxels only (those passing the threshold).

Each run writes its intermediate files into a fiber_-prefixed job folder under the Windows temp directory (config.json, status.json, results.json, plus the fiber_*.npy arrays). Besides the summary, results.json contains a 36-bin, coherence-weighted azimuth histogram (0-180 degrees) - handy raw data for rose plots and further post-processing.

9. FAQ and troubleshooting

Q1: The plugin is missing from the Prototype Apps menu.
A: The plugin is unticked by default in the Full Package installer - make sure it was ticked during installation. Menus are scanned only at Dragonfly startup, so every enable/disable change needs a full restart. You can also tick it under Developer ▸ Prototype Labs... ▸ Menu Item Manager and restart.

Q2: Setup Environment fails with "No base Python found to build the venv" or a pip error.
A: The default base interpreter is unusable and the automatic search found no working CPython. Install CPython 3.10-3.12 (the official installer includes venv and pip), enter its full python.exe path into Base Python, and click Setup Environment again. Also verify the machine can reach PyPI (internet is required for this one-time setup).

Q3: Clicking Compute logs "ERROR: environment not set up. Click 'Setup Environment' first."
A: The compute environment has not been built (or was deleted). Click `Setup Environment` and wait for the Status label to read "Ready: ..." before computing.

Q4: The Channel dropdown shows "(no channels - load a volume in Dragonfly)".
A: The session has no usable image Channel. Load a 3D volume in Dragonfly first, then click Refresh.

Q5: The run fails with "Out of memory - try a smaller ROI or downsample the volume."
A: The volume is too large for the available RAM - the whole volume is loaded and the structure tensor is computed in floating point, which multiplies the memory footprint. Crop a region of interest or downsample the volume in Dragonfly, then re-run.

Q6: Large areas of the azimuth map read 0 degrees - are all fibers aligned the same way?
A: Not necessarily. Angles of voxels below the coherence threshold are blanked and imported as 0, so background and pores also show 0 degrees. Overlay the Coherence Channel: only high-coherence 0-degree voxels are real orientations. Raise the coherence threshold if the non-fiber regions are too noisy.

Q7: Do I need a GPU? Does it need internet every time?
A: Neither. The computation is pure CPU (numpy/scipy). Internet is needed only for the one-time Setup Environment download (tens of MB); afterwards the plugin works fully offline.

10. Notes and known limitations

• An orientation is a line, not an arrow: azimuth is folded to 0-180 degrees, elevation to 0-90 degrees, and the direction components are sign-folded to vz >= 0; directions 180 degrees apart are the same orientation.
• The output is a per-voxel orientation field - the plugin does not segment individual fibers, so per-fiber counts or length distributions require a separate segmentation tool.
• The whole volume is read at once and processed in floating point (the structure tensor has multiple components), so memory usage is a significant multiple of the volume size; crop a ROI or downsample if you hit out-of-memory errors.
• Zeros in the angle Channels are ambiguous (true 0 degrees vs. thresholded background) - always interpret them together with the Coherence Channel (see section 6.3).
• Parameter sensitivity: too large a sigma erases thin fibers; too small a rho gives noisy orientations, too large loses local variation. Tune the parameters on a small ROI first.
• The runtime environment is per Dragonfly version (the venv lives inside each version's plugin code folder), so click Setup Environment once in every Dragonfly version you use.
• Menu enable/disable changes take effect only at Dragonfly startup - one full restart per change.
• Publishing the result Channels needs no restart; they appear in the scene as soon as the run finishes.

11. References

• structure-tensor (compute engine, MIT license, version 0.3.4): https://github.com/Skielex/structure-tensor
• numpy (BSD license): https://numpy.org
• scipy (BSD license): https://scipy.org
• Prototype Labs & Apps Full Package installation guide: the bilingual README shipped with the installer package (installation, Menu Item Manager, uninstall, and path-too-long troubleshooting).