晶粒尺寸与立体学分析(GrainSizeTools) 插件用户手册

Grain Size & Stereology (GrainSizeTools) - User Manual

Dragonfly Prototype Apps · Grain Size & Stereology (GrainSizeTools)...

版本 Version 1.0 · 2026-07-09

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

晶粒尺寸与立体学分析(GrainSizeTools) 是一个 Dragonfly 插件，基于二维晶粒（或颗粒）分割结果计算晶粒尺寸统计量，并可由二维切面反演（unfold）出三维晶粒尺寸分布。你在 Dragonfly 中选择一个代表晶粒标签（每个晶粒一个 label）的 MultiROI，插件会测量每个标签的面积，并换算为等效圆直径（ECD），然后给出描述性统计量与立体学反演结果。

等效圆直径的定义为 ECD = 2 * sqrt(面积 / pi)，即与晶粒投影面积相等的圆的直径；面积会先按像素尺寸换算为物理单位。

底层引擎与算法：

• GrainSizeTools（作者 Marco A. Lopez-Sanchez，Apache-2.0 许可证）提供立体学方法（Saltykov 反演与两步法 two-step）。该项目未发布到 PyPI，其 grain_size_tools 模块以 Apache-2.0 许可随插件内置（vendored）。
• Saltykov (1967) 方法：将二维 ECD 直方图反演（unfold）为三维晶粒尺寸（频率-直径）分布，使用 Scheil-Schwartz-Saltykov / Wicksell 几何概率。
• 两步法（two-step，Lopez-Sanchez & Llana-Funez 2016）：对 Saltykov 三维分布拟合对数正态分布，得到 shape（乘性标准差）与 MSD（中位数 / 几何中心）。
• 数值计算依赖 numpy / scipy / pandas / matplotlib（均为 BSD / PSF 系开源许可）。若内置的 GrainSizeTools 模块不可用，插件自带等效的纯 numpy 版 Saltykov / 两步法实现作为回退。

许可证要点：插件代码遵循本仓库许可条款；引擎 GrainSizeTools 为 Apache-2.0（随附 LICENSE 内置）；numpy / scipy / pandas 为 BSD，matplotlib 为 PSF/BSD 风格。

本插件是一个“测量 / 报告”工具：它不会向 Dragonfly 场景中发布（publish）任何新对象，只产出统计表、CSV 和图像 PNG。

2. 适用场景

本插件面向需要由二维切面估计三维晶粒尺寸分布的晶粒尺寸表征工作，典型领域包括：

• 岩石学 / 构造地质学：变质岩重结晶晶粒尺寸、变形晶粒尺寸古应力计算等。
• 金相学 / 材料科学：合金晶粒度、陶瓷与多晶材料的晶粒粒径分析。
• 其他需要由二维图像推断三维颗粒 / 晶粒尺寸分布的情形。

使用前请先对图像分割并分离相互接触的晶粒（例如用分水岭 watershed 方法），使每个晶粒对应 MultiROI 中一个独立的 label。否则多个相连的晶粒会被当作一个，统计会偏大。

3. 安装与启用

本插件作为 Prototype Apps 中的一个应用，随 Full Package（完整安装包） 分发。安装步骤如下：

1. 将完整安装包 zip 解压到任意位置（建议用短路径，如 C:\PL\，避免路径过长）。

2. 双击运行 `Install_FullPackage.bat`。

3. 在弹出的安装对话框中选择核心安装模式（Fresh 全新 / Compatible 兼容），并在应用列表中勾选 Grain Size & Stereology (GrainSizeTools)。

4. 点击 Install 等待控制台完成，然后完全退出并重启 Dragonfly。

本插件在安装列表中 默认未勾选（所有插件默认关闭），必须手动勾选才会安装。

重启后，菜单项出现在：Prototype Apps ▸ Grain Size & Stereology (GrainSizeTools)...（位于“Measurements & Analysis（测量与分析）”分组）。

以后修改启用状态：最方便的方式是在 Dragonfly 内打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager，在底部的 “Prototype Apps (Full Package)” 列表里勾选 / 取消勾选本插件，重启 Dragonfly 生效。停用不会删除已搭建的计算环境，重新启用立即可用。

也可随时重新运行安装器（上次的选择就是新默认值）；即使 zip 已删除，也可运行 %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat。

4. 运行环境与首次配置

本插件的重型计算在一个专用的 Python 虚拟环境（venv）中以子进程方式运行，不会污染 Dragonfly 自带的 Python。首次使用时需要搭建一次环境。

Setup Environment 做什么

在面板中点击 Setup Environment 按钮后，插件会：

1. 使用基础 Python（默认为当前 Dragonfly 自带的 Python_env\python.exe）在插件代码目录下创建一个 venv 虚拟环境；

2. 升级 pip / setuptools / wheel；

3. 从 PyPI 安装 numpy + scipy + pandas + matplotlib（在 CPython 3.10 上均为纯 wheel，无需编译、无 CUDA）；

4. 运行一次 smoke 检查验证四个包可导入，并记录虚拟环境的 Python 路径。

GrainSizeTools 本身未发布到 PyPI，其 grain_size_tools 模块已随插件内置（vendored），无需额外下载。

Base Python 字段与失败时的替代方案

面板中的 Base Python 字段用于指定搭建 venv 的基础解释器：留空表示用当前 Dragonfly 的 Python；也可填入一个可执行文件路径，或形如 py -3.11 的启动器命令。

若 Setup 失败（常见原因：基础 Python 缺少 stdlib 的 venv 模块，或 numpy/scipy/pandas/matplotlib 在该 Python 版本上无可用 wheel），请在 Base Python 字段填入一个另外的 CPython 3.10 至 3.12（带 stdlib venv 与 pip）的路径，例如 C:\Python312\python.exe，再重试。

5. 界面说明

面板自上而下分为若干区域。以下逐一说明每个控件（与代码一致）。

输入区（Input grain labels (MultiROI)）

选定一个 MultiROI 后，插件会自动从其网格的平面内间距读取默认像素尺寸填入下方的 Pixel size 控件。

分析参数区（Analysis parameters）

环境区（Environment (GrainSizeTools venv)）

操作按钮与输出区

• Setup Environment（按钮）：搭建虚拟环境并安装依赖（一次性）。
• Compute Grain Size（按钮）：对所选 MultiROI 执行分析。
• 摘要行：显示晶粒数、平均 ECD、中位数、几何均值；若为 Saltykov / 两步法还会附带三维结果摘要。
• 图像区：显示生成的分布图 PNG（二维 ECD 直方图，并在 Saltykov / 两步法时附三维分布柱状图）。
• 日志区（只读）：输出进度、完整统计表、CSV 与 PNG 的文件路径。

6. 使用步骤

前提：已在 Dragonfly 中对图像分割并将相互接触的晶粒分离，每个晶粒对应一个 MultiROI label。

工作流 A：二维描述性统计

1. 打开 Prototype Apps ▸ Grain Size & Stereology (GrainSizeTools)...。

2. 首次使用先点 Setup Environment，等 Status 显示 “Ready: ...”。

3. 在 MultiROI 下拉框选择目标晶粒标签（如列表为空先在 Dragonfly 分割，然后点 Refresh）。

4. Method 选 Descriptive statistics；根据需要调整 Pixel size 与 Unit（如 um）。

5. 点 Compute Grain Size，等待完成。

6. 在摘要行、日志区的统计表与图像区查看结果；日志中会给出 CSV 与 PNG 的路径。

工作流 B：Saltykov 二维→三维反演

1. 同工作流 A 的第 1–4 步。

2. 将 Method 选为 Saltykov (2D->3D stereology)。

3. 设置 Stereology bins（建议 10–15）：分组越多分辨率越高，但每组样本数会变少、噪声变大。

4. 点 Compute Grain Size；输出除二维统计外，右侧图会多出一幅 Saltykov 三维分布柱状图，摘要行显示三维分布的分组数。

工作流 C：两步法对数正态拟合

1. 同工作流 A 的第 1–4 步。

2. 将 Method 选为 Two-step (lognormal fit)，并设置 Stereology bins。

3. 点 Compute Grain Size；除二维统计与 Saltykov 三维分布外，还会得到三维分布的 MSD（中位数）与 shape（乘性标准差），在摘要行与统计表中列出。

7. 参数说明

下表汇总全部可调参数及其默认值（与面板代码一致）：

8. 输出结果

本插件为“测量 / 报告”工具，不会向 Dragonfly 场景发布任何新对象。结果包括：

• 统计表（在日志区以文本形式显示）：晶粒数、平均 ECD、中位数、标准差、最小/最大值、几何均值、对数标准差、RMS 均值、面积加权均值、体积加权均值、众数（KDE 峰值）；两步法时还包括三维 MSD 与 shape。
• CSV 文件 grain_stats.csv：上述统计量的 metric,value 表格（日志中给出完整路径）。
• 图像 PNG grain_plot.png：二维 ECD 频率直方图；在 Saltykov / 两步法时附一幅 Saltykov 三维分布柱状图。
• Saltykov 三维分布（仅 saltykov / two-step）：分组中心、三维频率、分组宽度与分组数。

如何查看：摘要行与图像直接在面板内显示；完整统计表在日志区。CSV 与 PNG 保存在临时作业目录中（日志会打印完整路径），可拷贝至其他位置保存。

9. 常见问题与故障排除

Q1：菜单里找不到插件？

A：确认安装时已在安装器列表中勾选了本插件（默认未勾选），并已完全退出并重启 Dragonfly（菜单只在启动时扫描）。仍无则在 Developer ▸ Prototype Labs... ▸ Menu Item Manager 中确认已启用，重启后再看。

Q2：点 Compute 提示 environment not set up？

A：需先点 Setup Environment 搭建环境。若搭建失败，常见原因是基础 Python 缺少 stdlib 的 venv 模块或无可用 wheel；请在 Base Python 字段填入一个 CPython 3.10–3.12 的路径后重试。

Q3：晶粒数明显偏少、尺寸偏大？

A：最常见原因是相互接触的晶粒未被分离，多个晶粒共用一个 label 而被当作一个。请在 Dragonfly 中先用分水岭（watershed）等方法分离晶粒，使每个晶粒对应独立 label。

Q4：直径数值看上去不对 / 单位不对？

A：确认 Pixel size（一个像素的物理边长）与 Unit 设置正确。选择 MultiROI 时会从网格平面间距自动填入像素尺寸，但单位标签需自行填写（默认 px）。若像素尺寸为 1、单位为 px，则直径以像素计。

Q5：Saltykov 三维分布看起来很噪 / 不平滑？

A：降低 Stereology bins（如从 15 降到 10）：分组越多，每组样本越少、反演噪声越大。同时保证晶粒数量足够（样本太少时统计不稳定）。

10. 注意事项与已知限制

• 本插件不向场景发布新对象，仅产出统计表、CSV 与 PNG；如需长期保留请自行拷贝日志中指出的文件。
• 输入必须是 晶粒标签型 MultiROI（每晶粒一个 label）；分割质量直接决定结果准确性，请先分离接触晶粒。
• Saltykov / 两步法的前提假设是晶粒近似为等轴（近球形）且切面为随机切面；强拉长 / 强取向的晶粒反演结果仅供参考。
• 首次 Setup Environment 需联网一次；之后计算无需联网。无需 GPU / WSL / 外部软件。
• 若内置的 GrainSizeTools 模块因故不可用，插件会自动回退到等效的纯 numpy 实现，结果仍可用。
• 停用插件不会删除已搭建的 venv；如需释放磁盘，可手动删除代码目录内的 venv 文件夹。

11. 参考资料

• GrainSizeTools 上游项目（Marco A. Lopez-Sanchez，Apache-2.0）：https://github.com/marcoalopez/GrainSizeTools
• Lopez-Sanchez M.A. & Llana-Funez S. (2016)：两步法（two-step）三维晶粒尺寸分布估计方法。
• Saltykov S.A. (1967)：由二维切面反演三维尺寸分布的经典立体学方法（Scheil-Schwartz-Saltykov）。
• 依赖库：numpy / scipy / pandas（BSD）、matplotlib（PSF/BSD 风格）。
• 安装 / 启用 / 卸载的完整说明：参见完整安装包根目录的 UserManual_用户手册.docx（总手册）。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation & Enabling

4. Environment & First-Run Setup

5. User Interface

6. Step-by-Step Usage

7. Parameter Reference

8. Outputs

9. FAQ & Troubleshooting

10. Notes & Known Limitations

11. References

1. Overview

Grain Size & Stereology (GrainSizeTools) is a Dragonfly plugin that computes grain-size statistics from a 2D grain (or particle) segmentation and can estimate a 3D grain-size distribution by unfolding the 2D section. Inside Dragonfly you pick a MultiROI of grain labels (one label per grain); the plugin measures each label's area, converts it to an equivalent circular diameter (ECD), then reports descriptive statistics and stereology-unfolding results.

The equivalent circular diameter is defined as ECD = 2 * sqrt(area / pi), i.e. the diameter of a circle with the same projected area as the grain; areas are first scaled to physical units by the pixel size.

Underlying engine and algorithms:

• GrainSizeTools (author Marco A. Lopez-Sanchez, Apache-2.0) provides the stereology methods (Saltykov unfolding and the two-step method). The project is not published on PyPI, so its grain_size_tools module is vendored with the plugin (Apache-2.0).
• Saltykov (1967): unfolds the 2D ECD histogram into a 3D grain-size (frequency-vs-diameter) distribution using the Scheil-Schwartz-Saltykov / Wicksell geometric probabilities.
• Two-step method (Lopez-Sanchez & Llana-Funez 2016): fits a lognormal to the Saltykov 3D distribution to obtain the shape (multiplicative std dev) and the MSD (median / geometric center).
• Numerical work uses numpy / scipy / pandas / matplotlib (all BSD / PSF-style open source). If the vendored GrainSizeTools module is unavailable, the plugin falls back to an equivalent self-contained numpy Saltykov / two-step implementation.

License notes: the plugin code follows this repository's license terms; the engine GrainSizeTools is Apache-2.0 (vendored with its LICENSE); numpy / scipy / pandas are BSD and matplotlib is PSF/BSD-style.

This plugin is a measurement / report tool: it does not publish any new object back into the Dragonfly scene. It only produces a statistics table, a CSV, and a plot PNG.

2. Use Cases

The plugin targets grain-size characterization that needs a 3D grain-size distribution estimated from 2D sections. Typical domains include:

• Petrology / structural geology: recrystallized grain size in metamorphic rocks, deformation grain-size palaeopiezometry, etc.
• Metallography / materials science: alloy grain size, ceramics and polycrystalline grain-size analysis.
• Any case where a 3D grain / particle size distribution must be inferred from a 2D image.

Before using, segment the image and split touching grains first (e.g. watershed) so that each grain becomes a single MultiROI label. Otherwise several connected grains are counted as one and the statistics will be biased toward larger sizes.

3. Installation & Enabling

The plugin ships as one of the Prototype Apps in the Full Package installer. To install:

1. Unzip the Full Package to any location (a short path such as C:\PL\ is recommended to avoid long-path issues).

2. Double-click `Install_FullPackage.bat`.

3. In the installer dialog, choose the core install mode (Fresh / Compatible), and in the app list tick Grain Size & Stereology (GrainSizeTools).

4. Click Install, wait for the console to finish, then fully quit and restart Dragonfly.

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

After the restart, the menu item appears at: Prototype Apps ▸ Grain Size & Stereology (GrainSizeTools)... (under the "Measurements & Analysis" section).

Changing the enabled state later: the easiest way is inside Dragonfly, via Developer ▸ Prototype Labs... ▸ Menu Item Manager — tick / untick this plugin in the "Prototype Apps (Full Package)" list at the bottom and restart Dragonfly. Disabling never deletes a plugin's environment; re-enabling is instant.

Alternatively, re-run the installer at any time (your previous choices become the new defaults). Even if the zip is deleted, run %LOCALAPPDATA%\DragonflyPrototypeLabs\FullPackage\installer\Install_FullPackage.bat.

4. Environment & First-Run Setup

The heavy computation runs as a subprocess in a dedicated Python virtual environment (venv), so it never pollutes Dragonfly's own Python. On first use you build this environment once.

What Setup Environment does

When you click the Setup Environment button in the panel, the plugin:

1. Creates a venv inside the plugin's code directory, using a base Python (default: the current Dragonfly's Python_env\python.exe);

2. Upgrades pip / setuptools / wheel;

3. Installs numpy + scipy + pandas + matplotlib from PyPI (all pure wheels on CPython 3.10 — no compilation, no CUDA);

4. Runs a one-time smoke check verifying the four packages import, and records the venv's Python path.

GrainSizeTools itself is not on PyPI; its grain_size_tools module is vendored with the plugin, so nothing extra is downloaded for it.

Base Python field and fallback on failure

The Base Python field selects the base interpreter for the venv: blank means use the current Dragonfly's Python; you may also enter a path to an executable or a launcher command like py -3.11.

If Setup fails (common causes: the base Python lacks the stdlib venv module, or numpy/scipy/pandas/matplotlib have no wheel for that Python version), enter the path of another CPython 3.10–3.12 (with stdlib venv + pip) in Base Python — e.g. C:\Python312\python.exe — and retry.

5. User Interface

The panel is organized into several groups from top to bottom. Each control is described below (matching the code).

Input grain labels (MultiROI)

When you pick a MultiROI, the plugin reads its in-plane grid spacing and auto-fills the Pixel size control below.

Analysis parameters

Environment (GrainSizeTools venv)

Action buttons and output area

• Setup Environment (button): builds the venv and installs the dependencies (one time).
• Compute Grain Size (button): runs the analysis on the selected MultiROI.
• Summary line: shows the grain count, mean ECD, median, geometric mean; for Saltykov / two-step it appends a 3D-result summary.
• Plot area: shows the generated distribution PNG (2D ECD histogram, plus a Saltykov 3D distribution bar chart for Saltykov / two-step).
• Log area (read-only): progress, the full statistics table, and the file paths of the CSV and PNG.

6. Step-by-Step Usage

Prerequisite: in Dragonfly, segment the image and split touching grains so that each grain is one MultiROI label.

Workflow A: 2D descriptive statistics

1. Open Prototype Apps ▸ Grain Size & Stereology (GrainSizeTools)....

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

3. Select the target grain-label MultiROI in the MultiROI combo box (if the list is empty, segment in Dragonfly first, then click Refresh).

4. Set Method to Descriptive statistics; adjust Pixel size and Unit (e.g. um) as needed.

5. Click Compute Grain Size and wait for completion.

6. Read the results in the summary line, the log's statistics table, and the plot area; the log prints the CSV and PNG paths.

Workflow B: Saltykov 2D->3D unfolding

1. Follow steps 1–4 of Workflow A.

2. Set Method to Saltykov (2D->3D stereology).

3. Set Stereology bins (10–15 recommended): more bins give finer resolution but fewer samples per bin and more noise.

4. Click Compute Grain Size; besides the 2D statistics, the plot gains a Saltykov 3D distribution bar chart on the right, and the summary line reports the number of 3D distribution classes.

Workflow C: Two-step lognormal fit

1. Follow steps 1–4 of Workflow A.

2. Set Method to Two-step (lognormal fit) and set Stereology bins.

3. Click Compute Grain Size; besides the 2D statistics and the Saltykov 3D distribution, you also obtain the 3D distribution's MSD (median) and shape (multiplicative std dev), shown in the summary line and the statistics table.

7. Parameter Reference

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

8. Outputs

This plugin is a measurement / report tool and does not publish any new object into the Dragonfly scene. The results are:

• Statistics table (shown as text in the log): grain count, mean ECD, median, std dev, min/max, geometric mean, log std dev, RMS mean, area-weighted mean, volume-weighted mean, mode (KDE peak); for two-step it also includes the 3D MSD and shape.
• CSV file grain_stats.csv: a metric,value table of the statistics above (full path printed in the log).
• Plot PNG grain_plot.png: a 2D ECD frequency histogram; for Saltykov / two-step it adds a Saltykov 3D distribution bar chart.
• Saltykov 3D distribution (saltykov / two-step only): bin centers, 3D frequencies, bin width and bin count.

How to view: the summary line and plot are shown directly in the panel; the full statistics table is in the log. The CSV and PNG are saved in a temporary job directory (the log prints the full paths) and can be copied elsewhere to keep.

9. FAQ & Troubleshooting

Q1: The plugin's menu item is missing.

A: Confirm you ticked this plugin during installation (all plugins are OFF by default) and that you fully quit and restarted Dragonfly (menus are scanned only at startup). If still missing, verify it is enabled in Developer ▸ Prototype Labs... ▸ Menu Item Manager, then restart.

Q2: Compute says "environment not set up".

A: Click Setup Environment first. If it fails, the usual cause is a base Python lacking the stdlib venv module or with no usable wheels; enter a CPython 3.10–3.12 path in Base Python and retry.

Q3: The grain count is clearly too low / sizes too large.

A: The most common cause is touching grains not being split — several grains share one label and are counted as one. In Dragonfly, split grains first (e.g. watershed) so each grain has its own label.

Q4: Diameter values look wrong / the unit is off.

A: Check that Pixel size (physical edge length of one pixel) and Unit are correct. Selecting a MultiROI auto-fills the pixel size from the grid spacing, but the unit label must be set manually (default px). With pixel size 1 and unit px, diameters are in pixels.

Q5: The Saltykov 3D distribution looks noisy / jagged.

A: Lower Stereology bins (e.g. from 15 to 10): more bins mean fewer samples per bin and more unfolding noise. Also ensure you have enough grains (statistics are unstable with too few samples).

10. Notes & Known Limitations

• The plugin does not publish new scene objects; it only produces a statistics table, CSV and PNG. Copy the files named in the log if you need to keep them.
• The input must be a grain-label MultiROI (one label per grain); segmentation quality directly determines accuracy, so split touching grains first.
• Saltykov / two-step assume grains are approximately equant (near-spherical) and sections are random; results for strongly elongated / textured grains are only indicative.
• The first Setup Environment needs internet once; afterwards computing is offline. No GPU / WSL / external application is required.
• If the vendored GrainSizeTools module is unavailable, the plugin automatically falls back to an equivalent pure-numpy implementation and still produces results.
• Disabling the plugin does not delete the built venv; to reclaim disk space, manually delete the venv folder inside the plugin's code directory.

11. References

• GrainSizeTools upstream project (Marco A. Lopez-Sanchez, Apache-2.0): https://github.com/marcoalopez/GrainSizeTools
• Lopez-Sanchez M.A. & Llana-Funez S. (2016): the two-step method for estimating 3D grain-size distributions.
• Saltykov S.A. (1967): the classic stereology method (Scheil-Schwartz-Saltykov) for unfolding a 3D size distribution from 2D sections.
• Dependencies: numpy / scipy / pandas (BSD), matplotlib (PSF/BSD-style).
• Full install / enable / uninstall details: see the overview UserManual_用户手册.docx in the Full Package root.