TauFactor 迂曲度因子与有效扩散系数 插件用户手册

TauFactor: Tortuosity Factor & Effective Diffusivity - User Manual

Dragonfly Prototype Apps · TauFactor...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

TauFactor 插件用于在已分割的三维图像中，对某个选定的相（相位 / phase）计算 迂曲度因子(tortuosity factor，记为 tau) 与 有效扩散系数(effective diffusivity，记为 D_eff)。你只需选择一个作为导通/传输相的 ROI、MultiROI 类别或 Channel，指定扩散方向(X/Y/Z)，插件即在该相内部求解稳态扩散方程，并报告 tau、D_eff、体积分数、比表面积以及渗透(连通性)检查结果；同时把求解得到的稳态浓度场作为一个新的 Channel 发布回 Dragonfly 场景中。

底层求解引擎为 TauFactor 2，一个基于 PyTorch 的开源迂曲度因子求解器，可利用 NVIDIA GPU 加速(没有 GPU 时自动回退到 CPU)。渗透性(连通性)检查使用 SciPy 的连通域标记；内置的演示仿体由纯 NumPy 生成。

迂曲度因子 tau 描述的是：相对于同体积的一块自由介质，扩散路径在该相内部被迫“绕行”的程度。tau 恒大于等于 1，路径越曲折、越拥挤，tau 越大。有效扩散系数在插件内按归一化定义 D_eff = 体积分数 / tau 给出。

计算在一个 独立的 Python 虚拟环境(venv) 中运行，与 Dragonfly 自带的 Python 完全隔离——PyTorch 等重型依赖不会污染 Dragonfly，也不会因版本冲突而使 Dragonfly 不稳定。

许可证要点

• TauFactor 2、PyTorch、NumPy、SciPy 均为开源项目，各自遵循其上游许可证(TauFactor 为 MIT，NumPy/SciPy 为 BSD，PyTorch 为 BSD 类许可)。
• 这些依赖在“首次配置”阶段由你本机自行从官方源下载安装，本插件不重新分发它们的二进制文件。
• 计算所得的迂曲度、扩散系数等指标可直接用于科研与工程分析；引用 TauFactor 时请遵循其上游项目的引用要求。

2. 适用场景

本插件面向已经完成 多孔或多相微结构分割、并且需要 定量传输指标(而不仅仅是几何形貌指标)的用户。典型应用领域包括：

• 电池与燃料电池电极研究：量化电极多孔结构、电解质相对离子/气体扩散的阻碍程度，是 TauFactor 最经典的应用。
• 地球科学：评估岩石、土壤等多孔介质中流体或气体的输运能力。
• 材料科学：分析由显微 CT、FIB-SEM 等成像手段获得的多孔或复合材料微结构的传输特性。
• 任何需要传输定量的场景：只要你有一个分割好的相，希望知道“扩散通过这个相有多难”，都可以使用本插件。

此外，插件内置 初学者演示(Beginner demo)：无需任何自己的数据，即可一键生成仿体微结构并完成一次完整的 tau 计算，非常适合快速上手、教学演示或验证环境是否搭建成功。

本插件求解的是 稳态扩散(steady-state diffusion) 主导的迂曲度因子。它不是流体力学(Navier-Stokes)渗流求解器，输出的是归一化的扩散阻碍指标，而非绝对渗透率。

3. 安装与启用

TauFactor 作为 Prototype Apps 的一员，随 Full Package(完整安装包) 一起分发。安装分为两个层面：把插件代码装入 Dragonfly，以及为求解器搭建计算环境(见第 4 章)。

3.1 通过 Full Package 安装器安装

1. 将 Full Package 压缩包解压到任意较短路径(如 C:\PL\，避免过深的下载目录或 OneDrive 重定向的桌面)。

2. 双击 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式：Fresh(全新安装，重置随包的 blocks 与 recipes) 或 Compatible(兼容安装，保留你自己的 blocks 与 recipes)。此选项 只影响 Prototype Labs 核心，不影响任何插件的环境与设置。

4. 在应用列表中 勾选 TauFactor。注意：轻量菜单项默认开启，但 所有插件(含 TauFactor)默认未勾选，必须手动勾选才会部署。

5. 点击 Install，等待控制台完成。

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

3.2 重启后菜单出现的位置

重启 Dragonfly 后，插件出现在 Dragonfly 顶部的 Prototype Apps 菜单下，位于 Measurements & Analysis(测量与分析) 分组中，条目名为 TauFactor...。点击即可打开一个可浮动(Floating)的停靠面板。

3.3 以后如何启用 / 停用

以后若要修改是否启用 TauFactor，最方便的方式是在 Dragonfly 内操作：

1. 打开 Developer ▸ Prototype Labs...。

2. 进入 Menu Item Manager。

3. 在底部的 “Prototype Apps (Full Package)” 列表里找到 TauFactor，勾选=部署菜单项，取消勾选=移除菜单项。

4. 重启 Dragonfly 生效。

停用某个插件 从不 删除它已经搭建好的计算环境(venv/下载内容)——重新启用时立即可用，无需重新下载 PyTorch。你也可以随时重新运行安装器，它会记住上次的勾选作为新的默认值。

3.4 卸载

双击 Full Package 的 `Uninstall_FullPackage.bat` 即可移除所有 Full Package 菜单项与插件；它会保留 Prototype Labs 核心以及各插件已搭好的计算环境(venv)。若要彻底腾出磁盘空间，可手动删除 %LOCALAPPDATA%\TauFactor(venv 与配置)以及 C:\TauFactorJobs(历史作业结果)。

4. 运行环境与首次配置

TauFactor 的求解不在 Dragonfly 自带的 Python 中运行，而是在一个 独立的计算环境(venv) 中执行。第一次使用前需要构建一次该环境。

4.1 首次配置在做什么

首次配置由脚本 setup_taufactor_venv.ps1 完成，它会：

• 在本机寻找一个 非 Dragonfly 的基础 Python(版本 3.10 - 3.12)——脚本会主动排除 Dragonfly 自带的解释器。
• 在 %LOCALAPPDATA%\TauFactor\venv 下创建一个全新的 venv。
• 向该 venv 中安装 PyTorch(默认使用 CUDA 版 cu124，若失败则自动回退到 CPU 版) 以及 taufactor 与 numpy。
• 运行一次冒烟测试，确认 torch/taufactor 能正常导入，并探测是否检测到可用的 CUDA GPU。
• 把探测结果写入 %LOCALAPPDATA%\TauFactor\config.json(记录 venv python 路径、作业根目录、设备类型)。插件面板会 自动读取 该配置并填好对应字段。

4.2 如何触发首次配置

有两种方式：

1. 在插件面板的 “TauFactor venv (PyTorch / GPU)” 分组中点击 Setup / Detect venv 按钮——若已存在环境会自动检测并填入路径；若尚未搭建，日志会提示你运行搭建脚本。

2. 或直接运行随插件附带的搭建脚本：双击 setup_taufactor_venv.bat(即调用 setup_taufactor_venv.ps1)。想强制使用 CPU 版 PyTorch，可在命令行加 -Cpu 参数。

powershell -ExecutionPolicy Bypass -File setup_taufactor_venv.ps1

powershell -ExecutionPolicy Bypass -File setup_taufactor_venv.ps1 -Cpu

4.3 下载体积、联网与硬件要求

4.4 环境安装到哪些路径

• 计算环境(venv)：%LOCALAPPDATA%\TauFactor\venv
• 自动配置文件：%LOCALAPPDATA%\TauFactor\config.json
• 作业结果根目录：C:\TauFactorJobs(每次运行生成一个带时间戳的子文件夹，存放掩膜、结果 JSON 与浓度场 .npy)

4.5 失败时的替代方案

• 找不到合适的基础 Python：从 python.org 或 Miniconda 安装一个 3.10 - 3.12 版本，或用 -BasePython C:\path\python.exe 指定。
• CUDA 版 PyTorch 安装失败：脚本会自动回退到 CPU 版;也可直接加 -Cpu 强制 CPU 安装。
• 面板检测不到 venv：确认 config.json 已生成;或在面板的 “venv python” 字段中手动粘贴 ...\TauFactor\venv\Scripts\python.exe 的完整路径。
• 想重建环境：运行搭建脚本时加 -Force 参数即可从头重建 venv。

5. 界面说明

面板顶部是一段功能说明文字，下方左右分栏：左栏是初学者演示区，右栏是配置区 + 运行日志。顶部工具条有一个 ◀ Hide demo / Show demo ▶ 按钮，可折叠或展开左侧演示区。

5.1 初学者演示区(左栏)

标题为 “Beginner demo (no segmentation needed)”，无需任何分割数据即可试用。

演示区还给出 “如何解读结果” 的说明：tau 越大表示路径越曲折;D_eff = 体积分数 / tau;浓度场 Channel 从入口到出口呈平滑梯度，平坦区代表死端;若某方向上相不贯通整个体块，则该方向 不渗透，tau 无定义(会在日志中报告)。

5.2 输入相分组(右栏)

标题为 “Input phase (the conducting / transport phase)”，用于选择要计算迂曲度的相。

5.3 TauFactor venv 分组(右栏)

5.4 方向与选项分组(右栏)

5.5 运行按钮与日志(右栏)

• Run TauFactor(蓝色按钮)：对上面选定的输入相与选项执行一次真实数据求解。
• Open Output Folder：打开最近一次作业的结果文件夹(若无则打开 Job root)。
• 日志区：只读文本框,实时显示进度、设备、tau/D_eff/体积分数/比表面积等结果以及导入的 Channel 名称。

求解在后台工作线程中运行,不会冻结 Dragonfly 界面;运行期间 Run / Demo 按钮会临时禁用,完成后自动恢复。

6. 使用步骤

6.1 工作流 A：初学者演示(无需数据)

1. 打开 Prototype Apps ▸ TauFactor...。

2. 确认已完成首次配置(第 4 章);如日志提示未找到 venv,先点 Setup / Detect venv 或运行搭建脚本。

3. 在左侧演示区选择一个 Phantom 仿体,并设置 Resolution(默认 64)。

4. 点击 Generate phantom + Run demo。

5. 在日志区查看结果:体积分数、各方向的 tau 与 D_eff、比表面积、所用设备与耗时;稳态浓度场会作为 Channel 导入场景。

建议尝试：对比稀疏与密集障碍(障碍越拥挤 tau 越大);“各向异性柱体” 仿体只沿 Z 方向渗透，X/Y 方向会报告为不渗透——这直观展示了渗透检查的作用。

6.2 工作流 B：对真实分割数据计算迂曲度

输入要求：场景中需有一个已分割好的目标相——ROI、MultiROI 类别，或可按灰度阈值区分相的 Channel。

1. 打开 Prototype Apps ▸ TauFactor...,确认 venv 已就绪。

2. 在 “Input phase” 分组点击 Refresh,然后从下拉框中选择作为导通相的对象。

3. 若输入是 Channel,在 Channel threshold 中填写用于区分相的灰度阈值(ROI/MultiROI 无需填写,非零即为相)。

4. 在 “Directions + options” 分组勾选要计算的方向 X / Y / Z(默认全选)。

5. 按需调整 Convergence criterion、Iteration limit、是否计算比表面积/三相界、以及导入哪个方向的浓度场。

6. 确认 Device 与 Job root 设置。

7. 点击 Run TauFactor。

8. 在日志区读取 tau / D_eff / 体积分数 / 比表面积 / 三相界结果;需要查看原始文件时点 Open Output Folder。

你会得到什么：每个所选方向的迂曲度因子 tau 与有效扩散系数 D_eff、整体体积分数、比表面积(可选)、三相界(可选，需≥3 相)、渗透判定，以及作为 Channel 导入的稳态浓度场(可选)。

7. 参数说明

下表汇总面板中的关键参数及其默认值(与代码实现一致)。

tau 与 D_eff 的关系:插件按 D_eff = 体积分数 / tau 给出归一化的有效扩散系数;tau≥1,体积分数为目标相占整个图像的比例。

8. 输出结果

一次成功的运行会产生两类输出:发布回 Dragonfly 场景的对象,以及保存在磁盘上的作业文件。

8.1 在 Dragonfly 场景中生成的对象

• 浓度场 Channel：以 Concentration_<方向> 命名(演示模式带 Demo_ 前缀)的新 Channel,几何(体素间距、原点)与原始输入对齐;可像普通 Channel 一样在 2D/3D 视图中查看、调色。
• 演示相 Channel(仅演示模式)：以 Phantom_<类型> 命名的仿体相,便于观察输入微结构。

8.2 日志中报告的定量指标

• Volume fraction(体积分数)：目标相占整个图像的体积比例。
• tau[方向](迂曲度因子)与 D_eff(有效扩散系数)：逐方向报告;若某方向不渗透,则报告 “does NOT percolate (undefined)”。
• Surface area(比表面积,可选)。
• Triple-phase(三相界,可选)。
• Device / seconds：所用计算设备与耗时。

8.3 磁盘上的作业文件

每次运行在 C:\TauFactorJobs(或你设置的 Job root) 下新建一个带时间戳的子文件夹,内含:输入相掩膜 mask.npy、结果 taufactor_result.json、进度 status.json,以及稳态浓度场 field_concentration_<方向>.npy。点击面板的 Open Output Folder 可直接打开该文件夹。

9. 常见问题与故障排除

Q1：日志提示 “TauFactor venv not set” 或找不到环境怎么办?

A：说明计算环境尚未搭建或未被检测到。请先完成第 4 章的首次配置:运行 setup_taufactor_venv.bat(或 setup_taufactor_venv.ps1) 构建 venv,再点面板的 Setup / Detect venv。若仍检测不到,可在 “venv python” 字段手动粘贴 ...\TauFactor\venv\Scripts\python.exe 的完整路径。

Q2：某个方向报告 “does NOT percolate (undefined)”,是不是出错了?

A：不是错误。它表示目标相在该方向上没有一条连通路径贯穿整个体块(不渗透),此时迂曲度因子在物理上无定义,插件如实报告。比如 “各向异性柱体” 仿体只沿 Z 渗透,X/Y 方向必然报告不渗透。若真实数据中所有方向都不渗透,请检查阈值/分割是否把相分割得过于破碎。

Q3：没有 NVIDIA GPU 还能用吗?

A：可以。GPU 是可选的。首次配置时可加 -Cpu 安装 CPU 版 PyTorch,或把面板 Device 设为 cpu/auto。CPU 求解只是较慢,结果一致。

Q4：求解很慢或一直不收敛怎么办?

A：可尝试:(1) 使用 GPU(Device 设为 cuda 或 auto);(2) 先在较小体积/较低分辨率上试算;(3) 适当放宽 Convergence criterion(如从 1e-4 调到 1e-3) 或提高 Iteration limit;(4) 只勾选真正需要的方向,减少求解次数。

Q5：Setup Environment 失败,提示找不到合适的 Python?

A：搭建脚本需要一个非 Dragonfly 的基础 Python 3.10 - 3.12。请从 python.org 或 Miniconda 安装一个符合版本要求的 Python 并加入 PATH,或运行脚本时用 -BasePython 指定其路径。

Q6：菜单里看不到 TauFactor?

A：确认安装时已勾选 TauFactor(插件默认未勾选),并且安装后 完全重启了 Dragonfly(菜单只在启动时扫描)。也可在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中勾选后重启。

10. 注意事项与已知限制

• 本插件求解 稳态扩散 主导的迂曲度因子,输出为归一化指标,不是绝对渗透率或流体力学渗流结果。
• 计算在 独立 venv 中进行,不会占用 Dragonfly 的 Python;但首次配置需联网并下载约 2.5 GB(CUDA 版 PyTorch)。
• 三相界(TPB) 计算需要输入至少 3 个标签(相);对二值(单相)输入会提示不适用。
• 输入相若被分割得过于破碎、在所有方向都不连通,则所有方向都会报告不渗透;此时应回到分割步骤检查阈值。
• 作业结果保存在 C:\TauFactorJobs 下并持续累积;长期使用后可手动清理旧的时间戳文件夹以释放磁盘。
• 本插件在 Windows 环境下使用;计算设备的自动检测依赖本机 CUDA 驱动与 PyTorch 是否为 CUDA 版。

11. 参考资料

• TauFactor 2 求解器(上游开源项目):https://github.com/tldr-group/taufactor
• PyTorch:https://pytorch.org
• NumPy:https://numpy.org · SciPy:https://scipy.org
• Dragonfly Prototype Apps 安装与启用说明:Full Package 内的 README(中英双语)。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Environment & First-Run Setup

5. Interface Guide

6. Usage Steps

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

The TauFactor plugin computes the tortuosity factor (tau) and the effective diffusivity (D_eff) of a chosen phase within a segmented 3D image. You simply pick a ROI, a MultiROI class, or a Channel as the conducting/transport phase, choose the flow direction(s) (X/Y/Z), and the plugin solves the steady-state diffusion equation through that phase. It reports tau, D_eff, volume fraction, specific surface area, and a percolation (connectivity) check, and publishes the solved steady-state concentration field back into the Dragonfly scene as a new Channel.

The underlying engine is TauFactor 2, an open-source, PyTorch-based tortuosity-factor solver that can be accelerated on an NVIDIA GPU (and falls back to CPU automatically when no GPU is present). The percolation (connectivity) check uses SciPy connected-component labelling; the built-in demo phantoms are generated with pure NumPy.

The tortuosity factor tau quantifies how much diffusion paths are forced to wind through the phase compared with the same volume of free medium. tau is always >= 1: the more crowded and winding the paths, the larger tau. The plugin reports a normalized effective diffusivity defined as D_eff = volume_fraction / tau.

Computation runs in a separate Python virtual environment (venv), fully isolated from Dragonfly's own Python - heavy dependencies such as PyTorch never pollute Dragonfly or risk destabilizing it through version conflicts.

License notes

• TauFactor 2, PyTorch, NumPy, and SciPy are all open-source projects governed by their respective upstream licenses (TauFactor is MIT; NumPy/SciPy are BSD; PyTorch uses a BSD-style license).
• These dependencies are downloaded and installed from their official sources during first-time setup; this plugin does not redistribute their binaries.
• The computed metrics (tortuosity, diffusivity, etc.) are ready for scientific and engineering analysis; when citing TauFactor, please follow the upstream project's citation requirements.

2. Use Cases

This plugin is for users who have already segmented a porous or multi-phase microstructure and need quantitative transport metrics rather than geometry alone. Typical fields include:

• Battery and fuel-cell electrode research: quantifying how much a porous electrode or electrolyte phase impedes ion/gas diffusion - the classic application of TauFactor.
• Geoscience: assessing the transport capacity of fluids or gases through porous rock and soil.
• Materials science: analyzing transport properties of porous or composite microstructures imaged by micro-CT, FIB-SEM, and similar techniques.
• Any scenario needing transport quantification: whenever you have a segmented phase and want to know 'how hard is it for something to diffuse through this phase', this plugin applies.

In addition, the plugin ships a Beginner demo: with no data of your own, you can generate a phantom microstructure and run a full tau computation in one click - ideal for getting started quickly, teaching demos, or verifying that the environment was set up correctly.

This plugin solves a steady-state diffusion-dominated tortuosity factor. It is not a fluid-dynamics (Navier-Stokes) flow solver; the output is a normalized diffusion-impedance metric, not an absolute permeability.

3. Installation & Enabling

TauFactor is part of the Prototype Apps and ships inside the Full Package installer. Installation has two aspects: getting the plugin code into Dragonfly, and building the compute environment for the solver (see Chapter 4).

3.1 Install via the Full Package installer

1. Unzip the Full Package to a short path (e.g. C:\PL\), avoiding very deep download folders or a OneDrive-redirected Desktop.

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, choose the core install mode: Fresh (reset the shipped blocks & recipes) or Compatible (keep your own blocks & recipes). This choice only affects the Prototype Labs core - it does NOT touch any plugin's environment or settings.

4. Tick TauFactor in the app list. Note: light menu items are on by default, but all plugins (including TauFactor) are unticked by default and must be selected explicitly to be deployed.

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

6. Fully quit and restart Dragonfly (menus are only scanned at startup).

3.2 Where the menu appears after restart

After restarting Dragonfly, the plugin appears under the top-level Prototype Apps menu, in the Measurements & Analysis group, as the entry TauFactor.... Clicking it opens a floating dockable panel.

3.3 Enabling / disabling later

To change whether TauFactor is enabled later, the easiest way is from inside Dragonfly:

1. Open Developer > Prototype Labs....

2. Go to the Menu Item Manager.

3. In the 'Prototype Apps (Full Package)' list at the bottom, find TauFactor: tick = deploy the menu entry, untick = remove it.

4. Restart Dragonfly to apply.

Disabling a plugin never deletes its already-built compute environment (venv/downloads) - re-enabling is instant and requires no re-download of PyTorch. You may also re-run the installer anytime; it remembers your previous choices as the new defaults.

3.4 Uninstall

Double-click the Full Package's `Uninstall_FullPackage.bat` to remove all Full-Package menu items and plugins; it keeps the Prototype Labs core and every plugin's built environment (venv). To reclaim disk space, you may manually delete %LOCALAPPDATA%\TauFactor (venv + config) and C:\TauFactorJobs (past job results).

4. Environment & First-Run Setup

TauFactor's solver does not run in Dragonfly's own Python; it runs in a separate compute environment (venv). You build this environment once before first use.

4.1 What first-run setup does

First-run setup is performed by the script setup_taufactor_venv.ps1, which:

• Locates a non-Dragonfly base Python (version 3.10 - 3.12) on the machine - the script deliberately excludes Dragonfly's own interpreter.
• Creates a fresh venv under %LOCALAPPDATA%\TauFactor\venv.
• Installs PyTorch (CUDA build cu124 by default, with automatic fallback to the CPU build if that fails), plus taufactor and numpy, into that venv.
• Runs a smoke test to confirm torch/taufactor import correctly and detects whether a usable CUDA GPU is present.
• Writes the detected settings to %LOCALAPPDATA%\TauFactor\config.json (venv python path, job root, device). The panel auto-detects this config and fills the corresponding fields.

4.2 How to trigger first-run setup

There are two ways:

1. In the 'TauFactor venv (PyTorch / GPU)' group, click Setup / Detect venv - if an environment already exists it is auto-detected and filled in; if not, the log tells you to run the setup script.

2. Or run the bundled setup script directly: double-click setup_taufactor_venv.bat (which invokes setup_taufactor_venv.ps1). To force the CPU build of PyTorch, add the -Cpu argument on the command line.

powershell -ExecutionPolicy Bypass -File setup_taufactor_venv.ps1

powershell -ExecutionPolicy Bypass -File setup_taufactor_venv.ps1 -Cpu

4.3 Download size, internet, and hardware requirements

4.4 Where the environment is installed

• Compute environment (venv): %LOCALAPPDATA%\TauFactor\venv
• Auto-generated config file: %LOCALAPPDATA%\TauFactor\config.json
• Job results root: C:\TauFactorJobs (each run creates a timestamped subfolder holding the mask, result JSON, and concentration-field .npy files)

4.5 Fallbacks when setup fails

• No suitable base Python found: install a 3.10 - 3.12 build from python.org or Miniconda, or specify it with -BasePython C:\path\python.exe.
• CUDA PyTorch install fails: the script falls back to the CPU build automatically; you can also add -Cpu to force a CPU install.
• The panel cannot detect the venv: confirm config.json was generated, or paste the full path to ...\TauFactor\venv\Scripts\python.exe into the panel's 'venv python' field.
• Rebuild the environment: add -Force when running the setup script to rebuild the venv from scratch.

5. Interface Guide

The top of the panel shows a description of the tool, below which the layout splits left/right: the left column is the beginner demo area, and the right column is the configuration area plus the run log. A ◀ Hide demo / Show demo ▶ button in the top bar collapses or reveals the demo column.

5.1 Beginner demo (left column)

Titled 'Beginner demo (no segmentation needed)' - you can try the tool without any segmented data.

The demo area also explains 'how to read it': higher tau means more winding paths; D_eff = volume_fraction / tau; the concentration-field Channel shows a smooth inlet-to-outlet gradient with flat plateaus marking dead ends; if a phase does not span the box in a direction it does NOT percolate and tau is undefined (this is reported in the log).

5.2 Input phase group (right column)

Titled 'Input phase (the conducting / transport phase)', used to select the phase whose tortuosity you compute.

5.3 TauFactor venv group (right column)

5.4 Directions + options group (right column)

5.5 Run buttons and log (right column)

• Run TauFactor (blue button): runs a real-data solve for the selected input phase and options.
• Open Output Folder: opens the most recent job's result folder (or the Job root if none yet).
• Log area: a read-only text box that streams progress, device, and results (tau / D_eff / volume fraction / surface area, etc.) plus the names of imported Channels.

The solve runs on a background worker thread and does not freeze the Dragonfly UI; the Run / Demo buttons are temporarily disabled during a run and re-enabled when it finishes.

6. Usage Steps

6.1 Workflow A: Beginner demo (no data needed)

1. Open Prototype Apps > TauFactor....

2. Make sure first-run setup is complete (Chapter 4); if the log says no venv was found, click Setup / Detect venv first or run the setup script.

3. In the left demo area, pick a Phantom and set the Resolution (default 64).

4. Click Generate phantom + Run demo.

5. Read the results in the log: volume fraction, per-direction tau and D_eff, surface area, the device used and elapsed time; the steady-state concentration field is imported into the scene as a Channel.

Try changing: compare sparse vs dense obstacles (tau rises with crowding); the 'anisotropic columns' phantom percolates along Z only, so X/Y are reported as non-percolating - a clear illustration of the percolation check.

6.2 Workflow B: Compute tortuosity on real segmented data

Input requirement: the scene must contain a segmented target phase - a ROI, a MultiROI class, or a Channel whose phase can be separated by a grayscale threshold.

1. Open Prototype Apps > TauFactor... and confirm the venv is ready.

2. In the 'Input phase' group click Refresh, then select the conducting-phase object from the dropdown.

3. If the input is a Channel, enter the grayscale Channel threshold used to separate the phase (not needed for ROI/MultiROI, where nonzero = phase).

4. In the 'Directions + options' group, tick the directions X / Y / Z to compute (all selected by default).

5. Adjust Convergence criterion, Iteration limit, whether to compute surface area / TPB, and which direction's concentration field to import, as needed.

6. Confirm the Device and Job root settings.

7. Click Run TauFactor.

8. Read tau / D_eff / volume fraction / surface area / TPB in the log; click Open Output Folder to inspect the raw files.

What you get: tau and D_eff for each selected direction, the overall volume fraction, specific surface area (optional), triple-phase boundary (optional, needs >= 3 phases), a percolation verdict, and the steady-state concentration field imported as a Channel (optional).

7. Parameter Reference

The table below summarizes the key panel parameters and their defaults (matching the code).

Relationship between tau and D_eff: the plugin reports a normalized effective diffusivity as D_eff = volume_fraction / tau; tau >= 1, and volume fraction is the phase's share of the whole image.

8. Outputs

A successful run produces two kinds of output: objects published back into the Dragonfly scene, and job files saved on disk.

8.1 Objects created in the Dragonfly scene

• Concentration-field Channel: a new Channel named Concentration_<direction> (with a Demo_ prefix in demo mode), aligned to the original input's geometry (voxel spacing and origin); view and re-color it like any other Channel in 2D/3D.
• Phantom-phase Channel (demo mode only): a Channel named Phantom_<type> holding the phantom phase, so you can inspect the input microstructure.

8.2 Quantitative metrics reported in the log

• Volume fraction: the phase's volumetric share of the whole image.
• tau[direction] (tortuosity factor) and D_eff (effective diffusivity): reported per direction; if a direction does not percolate, it reports 'does NOT percolate (undefined)'.
• Surface area (specific surface area, optional).
• Triple-phase (triple-phase boundary, optional).
• Device / seconds: the compute device used and the elapsed time.

8.3 Job files on disk

Each run creates a timestamped subfolder under C:\TauFactorJobs (or your configured Job root) containing: the input phase mask mask.npy, the results taufactor_result.json, progress status.json, and the steady-state concentration field field_concentration_<direction>.npy. Click the panel's Open Output Folder to open this folder directly.

9. FAQ & Troubleshooting

Q1: The log says 'TauFactor venv not set' or cannot find the environment. What do I do?

A: This means the compute environment has not been built or was not detected. First complete the first-run setup in Chapter 4: run setup_taufactor_venv.bat (or setup_taufactor_venv.ps1) to build the venv, then click Setup / Detect venv in the panel. If it still isn't detected, paste the full path to ...\TauFactor\venv\Scripts\python.exe into the 'venv python' field.

Q2: A direction reports 'does NOT percolate (undefined)'. Is that an error?

A: No. It means the target phase has no connected path spanning the whole box in that direction (it does not percolate), so the tortuosity factor is physically undefined and the plugin reports this honestly. For example, the 'anisotropic columns' phantom percolates only along Z, so X/Y necessarily report non-percolation. If real data reports non-percolation in every direction, check whether the threshold/segmentation fragmented the phase too much.

Q3: Can I use it without an NVIDIA GPU?

A: Yes. A GPU is optional. During first-run setup you can add -Cpu to install the CPU build of PyTorch, or set the panel's Device to cpu/auto. CPU solving is only slower; the results are the same.

Q4: The solve is very slow or never converges. What can I do?

A: Try: (1) use a GPU (set Device to cuda or auto); (2) test on a smaller volume / lower resolution first; (3) relax the Convergence criterion (e.g. from 1e-4 to 1e-3) or raise the Iteration limit; (4) tick only the directions you actually need to reduce the number of solves.

Q5: Setup fails, saying it cannot find a suitable Python.

A: The setup script needs a non-Dragonfly base Python 3.10 - 3.12. Install a matching Python from python.org or Miniconda and add it to PATH, or pass its path via -BasePython when running the script.

Q6: I don't see TauFactor in the menu.

A: Confirm you ticked TauFactor at install time (plugins are unticked by default) and that you fully restarted Dragonfly afterwards (menus are only scanned at startup). You can also tick it under Developer > Prototype Labs... > Menu Item Manager and then restart.

10. Notes & Known Limitations

• This plugin solves a steady-state diffusion-dominated tortuosity factor; the output is a normalized metric, not an absolute permeability or a fluid-dynamics flow result.
• Computation runs in a separate venv and does not use Dragonfly's Python; but first-run setup needs internet and downloads ~2.5 GB (CUDA build of PyTorch).
• The triple-phase boundary (TPB) computation requires an input with at least 3 labels (phases); it reports as not applicable for binary (single-phase) inputs.
• If the input phase is fragmented too finely and is not connected in any direction, every direction reports non-percolation; in that case return to the segmentation step and check the threshold.
• Job results accumulate under C:\TauFactorJobs; after prolonged use you can manually clear old timestamped folders to reclaim disk space.
• This plugin is used on Windows; automatic device detection depends on the machine's CUDA drivers and whether PyTorch was installed as the CUDA build.

11. References

• TauFactor 2 solver (upstream open-source project): https://github.com/tldr-group/taufactor
• PyTorch: https://pytorch.org
• NumPy: https://numpy.org · SciPy: https://scipy.org
• Dragonfly Prototype Apps install & enable guide: the bilingual README inside the Full Package.