Minkowski 泛函 (QuantImPy) 插件用户手册

Minkowski Functionals (QuantImPy) - User Manual

Dragonfly Prototype Apps · Minkowski Functionals (QuantImPy)...

版本 Version 1.0 · 2026-07-09

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

Minkowski 泛函 (QuantImPy) 是一个 Dragonfly 插件,用于对三维二值图像计算四个 Minkowski 泛函——体积 (Volume)、表面积 (Surface area)、积分平均曲率 (Integral mean curvature) 与 Euler 示性数 (Euler characteristic),并可选地对同一掩膜执行 形态学运算(腐蚀 / 膨胀 / 开运算 / 闭运算)。它以一个可停靠面板的形式加入到 Prototype Apps ▸ Minkowski Functionals (QuantImPy)... 菜单下。

Minkowski 泛函是积分几何与形貌学中一组稳健的形状描述量:在三维中一共有四个,分别对应体积、表面积、平均曲率积分与拓扑连通性。它们对多孔介质、泡沫、骨小梁、颗粒堆积等结构的孔隙率、比表面积、平均曲率、连通性给出全对象(whole-object)标量,而不是逐标签(per-label)的表格。

底层引擎与算法

计算由开源库 QuantImPy(项目地址 https://github.com/boeleman/quantimpy)完成。其中 Minkowski 泛函由 quantimpy.minkowski.functionals 计算(编译型 Cython 实现),形态学运算由 quantimpy.morphology 提供。QuantImPy 依赖 numpy 与 scipy。

• 体积 (Volume) —— 前景区域的度量。
• 表面积 (Surface area) —— 前景边界的面积。
• 积分平均曲率 (Integral mean curvature) —— 边界上平均曲率的积分。
• Euler 示性数 (Euler characteristic) —— 描述拓扑连通性的示性数。

关于 Euler 示性数的两个数值:QuantImPy 返回的第四个泛函值是拓扑 Euler 数按 chi × 3/(4π) 缩放后的量。面板在结果中同时给出 QuantImPy 的原始第四个值(标为 Euler characteristic (QuantImPy))以及换算回来的真实拓扑 Euler 示性数(标为 Euler characteristic (topological),一个实心凸块对应 chi = 1),便于对照与解释。

许可证要点

QuantImPy 采用 GPL-3.0-or-later 许可。为了与 Dragonfly 主程序保持“隔臂”(arm's-length)隔离,该库只会被安装进插件专属的独立虚拟环境(venv),并且只以子进程方式运行,绝不导入到 Dragonfly 自带的 Python 中。Dragonfly 一侧的插件代码只依赖 PyQt6 与 ORSModel。插件自身代码遵循 DragonflyPrototypeLabs 仓库的许可条款;依赖中 numpy、scipy 为 BSD 许可。

2. 适用场景

本插件适用于材料科学与生命科学中对三维结构做定量形貌分析的场景。典型对象包括:

• 多孔介质与岩心:通过体积/前景占比表征孔隙率,通过表面积表征比表面积。
• 泡沫与开孔/闭孔材料:用平均曲率与 Euler 示性数刻画孔壁曲率与连通性。
• 骨小梁 (trabecular bone):骨微结构的连通性与表面积分析。
• 颗粒堆积 (packed particles):堆积体的表面积、连通性描述。
• 任意三维结构:凡是关心积分几何描述量(孔隙率、比表面积、曲率、连通性)的场合皆可使用。

需要注意:本插件给出的是整体标量,而非逐对象/逐标签的测量表。如果你需要对 MultiROI 的每个标签分别测量,请配合 Dragonfly 自带的 MultiROI 测量工具使用。

3. 安装与启用

本插件随 Full Package(完整安装包) 分发。安装与启用流程如下:

1. 将安装包解压到任意较短的目录(建议如 C:\PL\,避免过深路径导致的 260 字符限制)。

2. 双击 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在应用列表中勾选 “Minkowski Functionals (QuantImPy)”。

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

5. 完全退出并重启 Dragonfly。

本插件在安装包中默认未勾选(所有插件默认关闭,仅轻量菜单项默认开启)。要使用它,务必在安装对话框里手动勾选,或稍后在 Menu Item Manager 中启用。

重启后,插件出现在 Prototype Apps ▸ Minkowski Functionals (QuantImPy)... 菜单下(该项归属 “Measurements & Analysis / 测量与分析” 分组)。点击即可打开可停靠面板。

以后修改勾选

最方便的方式是在 Dragonfly 内修改:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,底部的 “Prototype Apps (Full Package)” 列表中每个应用一个勾选框——勾选=部署,取消=移除菜单项,重启 Dragonfly 生效。停用从不删除已搭好的插件环境,重新启用立即可用。

菜单只在 Dragonfly 启动时扫描,因此每次修改勾选后都需要重启一次。全部内容安装在当前用户目录 %LOCALAPPDATA% 下,无需管理员权限。

卸载

双击 `Uninstall_FullPackage.bat`(安装器目录中也有一份),即可移除所有 Full Package 的菜单项与插件。卸载会保留已搭建的插件环境(venv),如需腾出磁盘空间可按提示手动删除。

4. 运行环境与首次配置

由于 QuantImPy 是 GPL 库且为编译型,插件采用 venv-in-code 模式:计算发生在一个安装在插件代码目录内的独立虚拟环境的子进程中,与 Dragonfly 自带 Python 保持隔离。

Setup Environment 具体做什么

首次使用时,在面板中点击 Setup Environment 按钮。它会:

1. 以 Base Python 字段指定的解释器为基础创建一个虚拟环境(该字段留空时默认使用当前 Dragonfly 自带的 Python,无需另装 Python);

2. 升级 pip / setuptools / wheel;

3. 从默认 PyPI 源安装 quantimpy、numpy<2、scipy<1.14(无 CUDA);

4. 运行一次导入自检(smoke test),并记录虚拟环境 Python 路径供后续计算调用。

numpy 必须保持 < 2:已发布的 quantimpy 构建是针对 numpy 1.x 的 C-ABI 编译的,若使用 numpy 2.x 会在导入时报 “numpy.dtype size changed”。requirements 已固定 numpy<2 与 scipy<1.14。已验证 quantimpy 在 numpy 1.26.4 下可正常导入与计算。

联网、GPU、WSL、外部软件

• 需要联网:仅在首次 Setup Environment 时需要一次联网从 PyPI 拉取依赖;之后使用无需联网。
• 不需要 GPU:计算为纯 CPU。
• 不需要 WSL:全程在 Windows 本地虚拟环境运行。
• 不需要外部软件:无需另外安装 Fiji/ImageJ 或其它第三方程序。

环境安装到哪里

虚拟环境创建在已安装的插件代码目录内,即 <Dragonfly 版本>\pythonUserExtensions\GenericMenuItems\QuantImPy\venv(位于 %LOCALAPPDATA%\comet\ 之下)。重装或更新插件代码时,这个 venv 会被保留,不会被清除,因此无需重复搭建。

失败时的替代方案

如果默认基础 Python 缺少 venv 模块,或 numpy/scipy 轮子(wheel)不可用而导致创建/安装失败,可在面板的 Base Python 字段中显式指向一个 CPython 3.10+(Windows 上推荐 3.10–3.12,有现成的 numpy<2 / scipy 轮子),例如填入 C:\Python312\python.exe 或形如 py -3.11 的启动器命令,然后再次点击 Setup Environment。面板状态栏会显示 “Ready: <python 路径>”(就绪)或提示尚未搭建。

5. 界面说明

面板自上而下由若干分组框(GroupBox)组成,逐一说明如下。所有耗时操作(读取对象、搭建环境、计算)都在后台线程执行,不会冻结界面。

Input(输入)分组

标题为 “Input (binary mask, or Channel + threshold)”。

• Input type(输入类型) 下拉框:可选 ROI、MultiROI、Channel 三种,默认 ROI。选择不同类型会自动刷新对象列表,并启用/禁用相关控件。
• Object(对象) 下拉框 + Refresh(刷新) 按钮:列出当前 Dragonfly 会话中对应类型的对象(显示标题与形状,如为 MultiROI 还显示标签数)。点击 Refresh 重新扫描。
• MultiROI label (0=all)(MultiROI 标签,0=全部) 数字框:仅在输入类型为 MultiROI 时可用;取值 0 表示所有标签的并集,取值范围会依所选 MultiROI 的标签数自动调整,默认 0。
• Channel threshold(通道阈值) 数字框:仅在输入类型为 Channel 时可用;前景 = 强度 ≥ 该阈值的体素,默认 0.5,可保留 4 位小数。

Minkowski functionals to report(要报告的泛函)分组

四个复选框——Volume、Surface area、Integral mean curvature、Euler characteristic,默认全部勾选。取消某项则该项不在结果中报告。

另有一个复选框 Use voxel size from grid geometry (physical units)(使用网格几何的体素尺寸,物理单位),默认勾选:勾选时按源对象的体素间距以物理单位报告泛函;取消时按单位体素(=1)计算。

Morphology(形态学,可选)分组

标题为 “Morphology (optional; publishes a new binary Channel)”。

• Operation(操作) 下拉框:none、erode(腐蚀)、dilate(膨胀)、open(开运算)、close(闭运算),默认 none。取 none 时不发布任何形态学 Channel。
• Radius (voxels)(半径,体素) 数字框:结构元半径,取值 1–100,默认 1。

Environment(环境)分组

标题为 “Environment (QuantImPy venv - GPL, kept arm's-length)”。

• Base Python 文本框:留空表示使用当前 Dragonfly 的 Python;也可填一个 Python 路径或形如 py -3.11 的命令。
• Status(状态) 标签:显示环境是否就绪(“Ready: <路径>” 或提示尚未搭建、点击 Setup Environment)。

操作按钮与输出区

• Setup Environment 按钮:搭建/复用虚拟环境并安装依赖(见第 4 章)。
• Compute Minkowski Functionals 按钮:对所选输入执行计算。
• 结果摘要标签:一行显示各泛函数值以及前景体素数 / 总体素数,可用鼠标选中复制。
• 日志文本框(只读):滚动显示搭建与计算过程的详细信息,包括错误堆栈。

6. 使用步骤

工作流 A:对二值 ROI 计算 Minkowski 泛函

1. 在 Dragonfly 中加载/生成一个二值 ROI,并确保插件面板已打开。

2. 首次使用先点击 Setup Environment,等待状态栏显示 “Ready”。

3. 将 Input type 设为 ROI,点击 Refresh,在 Object 下拉框中选择目标 ROI。

4. 在 Minkowski functionals to report 中勾选需要的泛函(默认四项全选)。

5. 如需物理单位结果,保持 Use voxel size from grid geometry 勾选;若要单位体素结果则取消。

6. 点击 Compute Minkowski Functionals;完成后在摘要标签与日志中查看数值。

工作流 B:对 MultiROI 的某个标签测量

1. 将 Input type 设为 MultiROI,点击 Refresh 并选择目标 MultiROI。

2. 在 MultiROI label (0=all) 中填入要测量的标签编号(填 0 表示所有标签的并集)。

3. 选择要报告的泛函与体素尺寸选项。

4. 点击 Compute Minkowski Functionals 得到该标签(或并集)的泛函。

工作流 C:对 Channel 加阈值提取前景后测量

1. 将 Input type 设为 Channel,点击 Refresh 并选择目标 Channel。

2. 在 Channel threshold 中设定阈值(前景 = 强度 ≥ 该值,默认 0.5)。

3. 选择要报告的泛函与体素尺寸选项。

4. 点击 Compute Minkowski Functionals。

工作流 D:附带形态学运算并发布结果 Channel

1. 按工作流 A/B/C 选好输入。

2. 在 Morphology 分组中选择 erode / dilate / open / close,并设定 Radius。

3. 点击 Compute Minkowski Functionals:插件在计算泛函的同时执行该形态学运算,并把结果作为新的二值 Channel 发布回 Dragonfly(与源网格对齐)。

4. 在日志的 “Published channels” 行确认发布成功,并在 Dragonfly 对象列表中查看新 Channel。

关于开/闭运算的实现:在 QuantImPy 中 open 是 dilate 的别名、close 是 erode 的别名,因此插件内部把真正的开运算组合成“先腐蚀后膨胀”(dilate∘erode)、把闭运算组合成“先膨胀后腐蚀”(erode∘dilate),以得到符合直觉的结果。

7. 参数说明

8. 输出结果

计算完成后,插件产生两类输出:

• 泛函数值(面板内):在结果摘要标签与日志文本框中列出所勾选的 Minkowski 泛函。日志同时给出前景体素数 / 总体素数;当勾选 Euler 示性数时,会同时列出 Euler characteristic (QuantImPy)(原始第四值)与 Euler characteristic (topological)(换算回的真实拓扑 Euler 数)。
• 形态学结果 Channel(可选,发布到 Dragonfly):当 Morphology 操作不为 none 时,插件把运算后的二值掩膜作为一个新的二值 Channel 发布回 Dragonfly,命名形如 “<源对象名> - <操作> r<半径> (binary)”,并与源对象的网格几何(spacing / origin)对齐。

查看方法:泛函数值直接在面板中读取(可用鼠标选中复制);发布的 Channel 出现在 Dragonfly 的对象/数据浏览器中,可像普通 Channel 一样在 2D/3D 视图中显示、进一步分析或导出。

本插件的物理单位取决于 “Use voxel size from grid geometry” 是否勾选:勾选时按源对象体素间距的比例给出结果(QuantImPy 内部按最小间距归一化,因此只有间距的相对比例影响结果)。

9. 常见问题与故障排除

Q1:点击 Compute 提示 “environment not set up”?

说明虚拟环境尚未搭建。请先点击 Setup Environment,等待状态栏显示 “Ready: <python 路径>” 后再计算。

Q2:Setup Environment 失败,提示 venv 或 numpy/scipy 安装出错?

常见原因是基础 Python 缺少 venv 模块,或该 Python 版本没有对应的 numpy<2 / scipy 轮子。解决办法:在 Base Python 字段填入一个 CPython 3.10–3.12 的路径(如 C:\Python312\python.exe)后重试。同时确认首次搭建时网络可访问 PyPI。

Q3:导入时报 “numpy.dtype size changed” 或类似 ABI 错误?

这是 numpy 2.x 与已发布 quantimpy 构建的 C-ABI 不兼容所致。requirements 已固定 numpy<2;若你手动改动过环境,请重新执行 Setup Environment 以恢复 numpy<2 与 scipy<1.14。

Q4:提示 “No foreground voxels: nothing to measure”?

表示所选输入在当前设置下没有前景体素。若输入是 Channel,请检查 Channel threshold 是否过高;若是 MultiROI,请确认 MultiROI label 选到了确实存在体素的标签(或用 0 表示全部标签的并集);若是 ROI,请确认它非空。

Q5:计算报 “Out of memory”?

体积过大时可能内存不足。请尝试对更小的 ROI 计算,或先对体积做下采样后再测量。

Q6:菜单里找不到该插件?

菜单仅在 Dragonfly 启动时扫描。请确认已在安装对话框或 Menu Item Manager 中勾选了该应用,然后完全退出并重启 Dragonfly。

10. 注意事项与已知限制

• GPL 隔离:QuantImPy 为 GPL-3.0-or-later,只在插件独立 venv 的子进程中运行,绝不导入 Dragonfly 自带 Python。请勿手动把 quantimpy 装进 Dragonfly 的 Python_env。
• numpy 必须 < 2:published quantimpy 构建针对 numpy 1.x 的 C-ABI;requirements 已固定 numpy<2 与 scipy<1.14。
• 只给整体标量:输出是全对象 Minkowski 泛函,不是逐标签测量表;逐标签需求请配合 Dragonfly 自带 MultiROI 测量工具。
• 物理单位取决于体素间距:勾选 “Use voxel size from grid geometry” 时按源对象间距的比例报告;QuantImPy 内部按最小间距归一化,因此只有间距比例(各方向相对关系)影响结果。
• 内部边界填充:核心计算会在掩膜四周填充一圈 False 边界,避免对象贴到数组边界造成表面积 / Euler 数的伪影。
• 平台:面板与安装路径按 Windows 设计(虚拟环境位于代码目录下的 venv\Scripts\python.exe)。
• 首次联网:仅 Setup Environment 需一次联网;之后使用离线即可。无需 GPU、无需 WSL、无需外部软件。

11. 参考资料

• QuantImPy 项目主页(GPL-3.0-or-later):https://github.com/boeleman/quantimpy
• Full Package 安装 / 启用 / 卸载说明:随包 UserManual_用户手册.docx 与安装器目录中的 README。
• 在 Dragonfly 内修改勾选:Developer ▸ Prototype Labs... ▸ Menu Item Manager。

Part II English Manual

Contents

1. Overview

2. Use cases

3. Installation and enabling

4. Runtime environment and first-run setup

5. Interface reference

6. Step-by-step usage

7. Parameter reference

8. Outputs

9. FAQ and troubleshooting

10. Notes and known limitations

11. References

1. Overview

Minkowski Functionals (QuantImPy) is a Dragonfly plugin that computes the four Minkowski functionals of a 3D binary image - Volume, Surface area, Integral mean curvature, and the Euler characteristic - with an optional morphological operation (erode / dilate / open / close) on the same mask. It appears as a dockable panel under Prototype Apps ▸ Minkowski Functionals (QuantImPy)....

The Minkowski functionals are a robust set of integral-geometry / morphology descriptors: in 3D there are exactly four, corresponding to volume, surface area, integral of mean curvature, and topological connectivity. They give whole-object scalars (not a per-label table) for porosity, specific surface area, mean curvature, and connectivity of porous media, foams, trabecular bone, packed particles, and similar structures.

Engine and algorithm

The computation is performed by the open-source QuantImPy library (project page https://github.com/boeleman/quantimpy). The Minkowski functionals come from quantimpy.minkowski.functionals (compiled Cython) and the morphology from quantimpy.morphology. QuantImPy depends on numpy and scipy.

• Volume - the measure of the foreground region.
• Surface area - the area of the foreground boundary.
• Integral mean curvature - the integral of mean curvature over the boundary.
• Euler characteristic - the topological connectivity number.

Two Euler numbers are reported: QuantImPy's fourth returned value is the topological Euler number scaled as chi × 3/(4π). The panel reports BOTH QuantImPy's raw fourth value (labelled Euler characteristic (QuantImPy)) and the recovered true topological Euler characteristic (labelled Euler characteristic (topological); a solid convex blob gives chi = 1), for direct comparison and interpretability.

Licensing

QuantImPy is GPL-3.0-or-later. To keep it arm's-length from Dragonfly, the library is installed only into the plugin's own dedicated virtual environment (venv) and is executed only as a subprocess - it is never imported into Dragonfly's own Python. The Dragonfly side of the plugin touches only PyQt6 + ORSModel. The plugin's own code follows the DragonflyPrototypeLabs repository terms; numpy and scipy are BSD-licensed.

2. Use cases

The plugin targets quantitative 3D morphology analysis in materials and life science. Typical subjects include:

• Porous media and core samples: porosity via volume / foreground fraction, specific surface area via surface area.
• Foams and open/closed-cell materials: pore-wall curvature and connectivity via mean curvature and the Euler characteristic.
• Trabecular bone: connectivity and surface area of the bone microstructure.
• Packed particles: surface area and connectivity descriptors of the packing.
• Any 3D structure where integral-geometry descriptors (porosity, specific surface area, curvature, connectivity) matter.

Note: the plugin returns whole-object scalars, not a per-object / per-label measurement table. For per-label measurements of a MultiROI, pair it with Dragonfly's built-in MultiROI measurement tools.

3. Installation and enabling

The plugin ships in the Full Package. To install and enable it:

1. Unzip the package to any short folder (e.g. C:\PL\, to avoid the 260-character path limit from deep paths).

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, choose the core install mode (Fresh or Compatible) and tick "Minkowski Functionals (QuantImPy)" in the app list.

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

5. Fully quit and restart Dragonfly.

This plugin is OFF by default in the installer (all plugins default OFF; only light menu items default ON). You must tick it in the install dialog, or enable it later in the Menu Item Manager.

After the restart, the plugin appears under Prototype Apps ▸ Minkowski Functionals (QuantImPy)... (in the "Measurements & Analysis" group). Click it to open the dockable panel.

Changing your choices later

The easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager; the "Prototype Apps (Full Package)" list at the bottom has a checkbox per app - tick to deploy, untick to remove the menu entry, then restart Dragonfly. Disabling never deletes a plugin's environment: re-enabling is instant.

Menus are discovered only at Dragonfly startup, so every enable/disable change needs one restart. Everything is per-user under %LOCALAPPDATA%; no admin rights are required.

Uninstall

Double-click `Uninstall_FullPackage.bat` (also kept in the installer folder). It removes all Full-Package menu items and plugins while keeping each built environment (venv); the listed paths let you delete them manually to reclaim disk space.

4. Runtime environment and first-run setup

Because QuantImPy is a GPL, compiled library, the plugin uses a venv-in-code model: the computation runs in a subprocess of a dedicated virtual environment installed inside the plugin's code folder, kept isolated from Dragonfly's own Python.

What Setup Environment does

On first use, click Setup Environment in the panel. It will:

1. Create a virtual environment from the interpreter in the Base Python field (blank = this Dragonfly's own Python by default, so no separate Python install is needed);

2. Upgrade pip / setuptools / wheel;

3. pip-install quantimpy, numpy<2, and scipy<1.14 from the default PyPI index (no CUDA);

4. Run an import smoke test and record the venv Python path for subsequent computations.

numpy must stay < 2: the published quantimpy build is compiled against the numpy 1.x C-ABI, so numpy 2.x raises "numpy.dtype size changed" at import. The requirements pin numpy<2 and scipy<1.14. Verified: quantimpy imports and computes cleanly on numpy 1.26.4.

Internet, GPU, WSL, external apps

• Internet needed once: only the first Setup Environment needs internet to fetch dependencies from PyPI; use afterwards is offline.
• No GPU: computation is CPU-only.
• No WSL: everything runs in a local Windows virtual environment.
• No external software: no Fiji/ImageJ or other third-party program is required.

Where the environment is installed

The venv is created inside the installed plugin code folder, i.e. <Dragonfly version>\pythonUserExtensions\GenericMenuItems\QuantImPy\venv (under %LOCALAPPDATA%\comet\). Reinstalling or updating the plugin code preserves this venv, so you do not have to rebuild it.

Fallback if setup fails

If the default base Python lacks the venv module, or numpy/scipy wheels are unavailable, point the panel's Base Python field at a CPython 3.10+ (3.10-3.12 recommended on Windows, with prebuilt numpy<2 / scipy wheels) - for example C:\Python312\python.exe or a launcher command like py -3.11 - then click Setup Environment again. The Status label shows "Ready: <python path>" when it succeeds, or a prompt that setup is still needed.

5. Interface reference

The panel is a stack of group boxes, described from top to bottom. All time-consuming operations (reading objects, building the environment, computing) run on a background thread, so the UI never freezes.

Input group

Titled "Input (binary mask, or Channel + threshold)".

• Input type dropdown: ROI, MultiROI, or Channel (default ROI). Changing it refreshes the object list and enables/disables the related controls.
• Object dropdown + Refresh button: lists the objects of the chosen type in the current Dragonfly session (title and shape; a MultiROI also shows its label count). Refresh re-scans.
• MultiROI label (0=all) spin box: available only for MultiROI input; 0 = union of all labels; its upper bound adjusts to the chosen MultiROI's label count. Default 0.
• Channel threshold spin box: available only for Channel input; foreground = voxels with intensity >= this value. Default 0.5, 4 decimals.

Minkowski functionals to report group

Four checkboxes - Volume, Surface area, Integral mean curvature, Euler characteristic - all checked by default. Unchecking one omits it from the results.

Plus a checkbox Use voxel size from grid geometry (physical units), checked by default: when on, functionals are reported in physical units using the source object's spacing; when off, they use a unit voxel (=1).

Morphology group (optional)

Titled "Morphology (optional; publishes a new binary Channel)".

• Operation dropdown: none, erode, dilate, open, close (default none). none publishes no morphology Channel.
• Radius (voxels) spin box: structuring-element radius, 1-100, default 1.

Environment group

Titled "Environment (QuantImPy venv - GPL, kept arm's-length)".

• Base Python text field: blank = this Dragonfly's Python; or a Python path, or a command like py -3.11.
• Status label: shows whether the environment is ready ("Ready: <path>" or a prompt to click Setup Environment).

Action buttons and output area

• Setup Environment button: builds/reuses the venv and installs dependencies (see Section 4).
• Compute Minkowski Functionals button: runs the computation on the selected input.
• Summary label: a single line listing the functional values plus foreground / total voxel counts; selectable for copying.
• Log text box (read-only): scrolls the details of setup and computation, including any error tracebacks.

6. Step-by-step usage

Workflow A: functionals of a binary ROI

1. Load/generate a binary ROI in Dragonfly and open the plugin panel.

2. On first use, click Setup Environment and wait until the Status shows "Ready".

3. Set Input type to ROI, click Refresh, and pick the target ROI in Object.

4. Tick the functionals you want under Minkowski functionals to report (all four by default).

5. Keep Use voxel size from grid geometry ticked for physical units, or untick it for unit-voxel results.

6. Click Compute Minkowski Functionals; read the values in the summary label and log.

Workflow B: one label of a MultiROI

1. Set Input type to MultiROI, click Refresh, and select the MultiROI.

2. Enter the label number in MultiROI label (0=all) (0 = union of all labels).

3. Choose the functionals and the voxel-size option.

4. Click Compute Minkowski Functionals to get the functionals for that label (or the union).

Workflow C: a Channel plus a threshold

1. Set Input type to Channel, click Refresh, and select the Channel.

2. Set the Channel threshold (foreground = intensity >= this value; default 0.5).

3. Choose the functionals and the voxel-size option.

4. Click Compute Minkowski Functionals.

Workflow D: run a morphology op and publish a Channel

1. Pick the input as in workflow A/B/C.

2. In the Morphology group choose erode / dilate / open / close and set Radius.

3. Click Compute Minkowski Functionals: alongside the functionals, the plugin applies the morphology operation and publishes the result as a new binary Channel back into Dragonfly, aligned with the source grid.

4. Confirm success on the "Published channels" log line and view the new Channel in Dragonfly's object list.

About opening/closing: in QuantImPy open is an alias for dilate and close an alias for erode. The plugin therefore composes a true opening as "erode then dilate" (dilate∘erode) and a true closing as "dilate then erode" (erode∘dilate) for intuitive results.

7. Parameter reference

8. Outputs

After a computation, the plugin produces two kinds of output:

• Functional values (in the panel): the selected Minkowski functionals are listed in the summary label and the log. The log also gives the foreground / total voxel counts; when the Euler characteristic is selected, it lists both Euler characteristic (QuantImPy) (the raw fourth value) and Euler characteristic (topological) (the recovered true topological Euler number).
• Morphology result Channel (optional, published to Dragonfly): when the Morphology operation is not none, the plugin publishes the resulting binary mask as a new binary Channel back into Dragonfly, named like "<source object> - <op> r<radius> (binary)", aligned with the source object's grid geometry (spacing / origin).

How to view: the functional values are read directly in the panel (selectable for copying); the published Channel appears in Dragonfly's object/data browser and can be shown in 2D/3D views, analysed further, or exported like any other Channel.

Physical units depend on "Use voxel size from grid geometry": when on, results follow the ratios of the source object's spacing (QuantImPy normalizes internally by the minimum spacing, so only the relative ratios between axes affect the result).

9. FAQ and troubleshooting

Q1: Compute says "environment not set up"?

The venv has not been built yet. Click Setup Environment first and wait until the Status shows "Ready: <python path>" before computing.

Q2: Setup Environment fails on venv or numpy/scipy install?

Common causes: the base Python has no venv module, or that Python version has no matching numpy<2 / scipy wheels. Fix: put a CPython 3.10-3.12 path into Base Python (e.g. C:\Python312\python.exe) and retry. Also make sure PyPI is reachable during the first setup.

Q3: An import error like "numpy.dtype size changed" (ABI mismatch)?

This is numpy 2.x being incompatible with the published quantimpy build's C-ABI. The requirements pin numpy<2; if you altered the environment manually, re-run Setup Environment to restore numpy<2 and scipy<1.14.

Q4: "No foreground voxels: nothing to measure"?

The selected input has no foreground voxels under the current settings. For a Channel, check whether the Channel threshold is too high; for a MultiROI, make sure the MultiROI label points at a label that actually has voxels (or use 0 for the union of all labels); for an ROI, confirm it is non-empty.

Q5: Computation reports "Out of memory"?

Very large volumes can exhaust memory. Try computing on a smaller ROI, or downsample the volume before measuring.

Q6: The plugin does not appear in the menu?

Menus are scanned only at Dragonfly startup. Confirm the app is ticked in the install dialog or the Menu Item Manager, then fully quit and restart Dragonfly.

10. Notes and known limitations

• GPL isolation: QuantImPy is GPL-3.0-or-later and runs only in the plugin's own venv subprocess; it is never imported into Dragonfly's own Python. Do not manually install quantimpy into Dragonfly's Python_env.
• numpy must stay < 2: the published quantimpy build targets the numpy 1.x C-ABI; the requirements pin numpy<2 and scipy<1.14.
• Whole-object scalars only: outputs are whole-object Minkowski functionals, not a per-label table; use Dragonfly's built-in MultiROI measurement tools for per-label needs.
• Physical units depend on spacing: with "Use voxel size from grid geometry" on, results follow the source object's spacing ratios; QuantImPy normalizes internally by the minimum spacing, so only the relative ratios between axes matter.
• Internal boundary padding: the core pads the mask with a False border so the object never touches the array boundary, avoiding surface-area / Euler artifacts.
• Platform: the panel and install paths are designed for Windows (the venv lives at venv\Scripts\python.exe inside the code folder).
• Internet once: only Setup Environment needs internet; later use is offline. No GPU, no WSL, no external software.

11. References

• QuantImPy project page (GPL-3.0-or-later): https://github.com/boeleman/quantimpy
• Full Package install / enable / uninstall guide: the bundled UserManual_用户手册.docx and the README in the installer folder.
• Change your choices inside Dragonfly: Developer ▸ Prototype Labs... ▸ Menu Item Manager.