Microstructure Statistics & RVE（微观结构统计与代表体元）

Microstructure Statistics & RVE - User Manual

Dragonfly Prototype Apps · Microstructure Statistics & RVE...

版本 Version 1.0 · 2026-08-02

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

测量多相微观结构，并回答单一视场自己回答不了的那个问题：样品要取多大，测出来的数才算稳住了。适用对象是电池与燃料电池电极、多孔介质与复合材料。

三相界线是本插件存在的理由。 在电极里，只有三个相交汇的那条线能够发生反应；而其中只有三个相各自都能通过自身连到外界的那一段，才真正可用。插件把总长度与有效长度分开给出，并且两者都同时给出格点原始值与 2/3 修正值——因为在轴对齐的直线上原始值本来就是准确的，此时套用修正反而会小 33%。

收敛不等于正确。 代表尺寸 L* 需要同时满足两个条件：该尺寸及其之后每一档的离散度都在容差内，并且该尺寸及其之后每一档的均值相对最大档的漂移也在容差内。只看离散度会过早宣布胜利——小盒子可以「稳定地测错」。每一个 L* 都带有内插 / 外推 / 未达到的状态标注，外推值绝不会被当成实测值。

同一幅图像切出来的子体不是独立样本。 它们在空间上相关，因此自助置信区间天然偏窄（在相关合成场上实测：名义 95% 的覆盖率为 0.873–0.930）。区间照样给出，因为它正确回答了「这个数在这幅图像内部会晃多少」；但它始终附带这条告诫、重叠比例、独立体素覆盖率，以及基于积分范围的有效样本量。加宽功能是有的，默认关闭——悄悄加宽和悄悄收窄一样不诚实。

2. 适用场景

• 测量电池与燃料电池电极的三相界线，并看清其中有多少是真正可用的。
• 判断多孔介质或复合材料研究需要多大的视场，数值才不再随取样位置漂移。
• 以一种别人能够比对的口径报告界面面积（阶梯与移动立方体两种口径同时给出，并附比值）。
• 为一幅图像上测得的数值附上一份诚实的不确定度说明，用于论文或报告。

3. 安装与启用

1. 安装 Prototype Apps 完整包（或在 App Store 中勾选本插件）。

2. 本插件默认未启用，请在 App Store 或菜单项管理器中启用。

3. 完全重启 Dragonfly（插件只在启动时被发现）。菜单位置：Prototype Apps ▸ Measurements & Analysis ▸ Microstructure Statistics & RVE…

4. 运行环境与首次配置

无需任何安装或配置。 完全运行在 Dragonfly 自带的 Python 中，使用其已附带的 NumPy 与 SciPy；界面面积用到的 skimage.measure.marching_cubes 采用延迟导入（首次约 1 秒）。不联网、不下载、不需要 GPU、不创建虚拟环境。

面板顶部会显示当前 Dragonfly 版本能否读取标签、能否发布 ROI、能否发布通道。做不到的操作会直接置灰，而不是让你点下去再报错；即使一样都发布不了，导出依然可用。

5. 界面说明

1. 输入

相的来源：MultiROI 标签或通道阈值。选择 MultiROI（或通道）、可选的分析区域掩膜 ROI，以及时间步；下方列出全部标签，逐行指定角色（忽略 / A / B / C），三个角色齐备才能测三相界线。底部显示形状、三轴间距、origin 与时间步数。所有下拉框只列出已发布的对象。

2. 标定与预处理

可手动指定体素尺寸（Z/Y/X，单位 mm），或从对象读取；体素各向异性时会给出提示——所有面积、棱长与弦长都按各自方向自己的间距加权。可在测量前裁剪（各方向的体素范围）。阈值来源模式下在此设定阈值与极性；标签来源模式下在此决定标签 0 是算作一个相还是排除在分析区域之外（默认排除）。「界面面积不计入视场边界」默认开启。所有预处理都作用于工作副本，输入对象不会被修改。

3. 参数

上半部分选指标：体积分数（始终启用）、界面面积（含面积估计方法与预平滑 sigma）、三相界线、有效三相界线（含贯通方向）、连通性（含 6/18/26 连通规则）、弦长（含直方图分箱数）。下半部分是代表体元采样：采样方式、重叠策略、尺寸档数、每档子体数、最小盒与最大盒、离散度与漂移容差、绝对容差下限、置信水平、自助重采样次数、区间方法、随机种子，以及累加面积表的内存预算。底部一行给出体素数、尺寸档、预计耗时与工作副本大小——那是数量级参考，不是承诺。

4. 预览与质检

在抽稀副本上快速跑一遍（抽稀倍数会自动提高，保证任一方向不超过 128 体素），给出尺寸档表格、收敛曲线与相对离散度图。不发布任何对象，也不启用导出按钮。抽稀会改变所有由表面导出的数值，所以预览只用于检查形态与趋势，不能作为可报告的数值。

5. 运行

先复述一遍本次计划（相的来源、采样方式、重叠策略、随机种子、A/B/C、是否开启连通性、是否裁剪）与预计代价，然后全分辨率运行，随时可取消。运行同样不发布任何对象。

6. 结果与导出

选择要显示的指标，看它的收敛曲线与相对离散度图。曲线上有两条带，永远不共用颜色和纹理：宽的斜纹带是单个子体的离散（均值 ± 1 个标准差），窄的实心带是 n 个子体均值的置信区间——后者按 √n 收窄，与「一个盒子够不够有代表性」毫无关系。下面依次是 L* 与其状态、积分范围、逐相指标表、逐档扫描表与全部告警，最后是三个导出按钮与三个发布按钮。

分享报告

第七个标签页 分享报告 不是流程步骤，它只把已生成的报告临时发布到互联网，不做任何计算。它通过 Cloudflare 临时快速隧道，直接从本机提供刚生成的报告，并返回一个临时的公网地址；不上传任何数据，也不需要账号，而报告页面本身就带着您的图像数据。该地址不是立刻可用的：隧道建立之后大约还要 40 秒它才开始响应（本机实测：一次为 45 秒，另有两次始终没能解析），所以状态转绿之前不要把链接发出去。分享期间，拿到链接的任何人都能读取报告，没有密码。点击停止分享、关闭窗口或退出 Dragonfly 后，该地址立即失效且永不重发。只有在本机确认地址已可访问、或明确告知无法确认时，才会把链接交给您。

6. 使用步骤

1. 第 1 步选择 MultiROI（或通道加阈值），并为三个标签指定 A、B、C 角色。

2. 第 2 步确认体素尺寸，决定标签 0 是否算作一个相，必要时裁剪。

3. 第 3 步勾选需要的指标，并设定采样档数与容差。

4. 第 4 步先跑预览，确认形态合理、曲线走势可信、没有大量告警。

5. 第 5 步全分辨率运行。

6. 第 6 步查看 L* 及其状态，然后导出或发布。

7. 参数说明

指标

代表体元采样

8. 输出结果

9. 常见问题与故障排除

• L* 显示「外推」或「未达到」 —— 这不是故障，而是如实报告：实测尺寸范围内没有收敛。外推值来自拟合幂律，实测对比显示在测试范围 1.5 倍处偏小约 12%、2 倍处偏小约 16%。要拿到「内插」，需要更大的视场或更宽松的容差。
• 提示只测到 2 个尺寸档 —— 几何间距的相邻档舍入到了同一个整数体素值。降低最小盒、提高最大盒比例，或者换更大的视场。
• 有效三相界线为 0% —— 至少有一个相完全连不到外界。先检查贯通方向（指定方向比「任意外表面」严格得多），再检查标签 0 是否被排除出了分析区域，以及分析区域掩膜是否把结构封死了。
• 两个界面面积差了约 1.5 倍 —— 这是正常的，不是错误。对法向各向同性的表面，阶梯面积恰好是真值的 3/2，而且这个误差不随分辨率减小。移动立方体是头条数值，在未平滑的二值数据上本身还偏高约 8%。
• 置信区间看起来太窄 —— 它确实偏窄，原因写在区间旁边：子体来自同一幅图像。可以用积分范围推出的设计效应加宽，也可以直接把它读作「本图像内部的采样波动」。
• 提示拟合指数落在合理区间之外 —— 盒子多半还没走出相关区，或者所选指标本身不可加。数值照样给出，假设不被藏起来。
• 嵌套方式下没有任何区间 —— 嵌套盒互相包含，样本完全相关，每档只有一个值，因此拒绝自助法。要区间就用随机子体。
• 提示体素各向异性 —— 所有面积、棱长与弦长都已按各自方向加权；但连通域标记是纯拓扑运算（scipy.ndimage.label 没有间距参数），近邻不区分远近，这一点无法在标记层面修正。

10. 注意事项与已知限制

• 整卷读入内存；超大体积请先用预览确定参数。
• 输入必须是已发布的对象；所有下拉框只列出已发布对象。
• 发布始终是第 6 步的显式操作，预览与运行都不会发布任何对象；任何输入或参数改动都会立即作废上一次结果并禁用导出。
• 预览是抽稀的，只用于检查形态与趋势，其数值不可作为报告值。
• 连通性、有效三相界线与弦长都是全局量，不能由累加面积表加速；每个子体都要单独算，开启后代价显著上升。
• 嵌套采样仅供显示：每档一个盒、盒盒相含，整条曲线还取决于中心放在哪里。
• 本插件不重复别处已有的能力。 阈值敏感性属于 Porosity Threshold Confidence；基于欧氏距离变换的厚度与间距属于 Structure Scale Analyzer；曲折度属于 TauFactor；Minkowski 泛函属于 Minkowski Functionals (QuantImPy)。需要这些量时请用对应的插件。
• 本插件不做欧拉示性数意义上的连通密度，也不做取向扫描与织构张量；弦长各向异性比只是三个方向弦长均值之比，仅此而已。
• 所有区间都只描述这一幅图像内部的采样波动，无法代表样品之间的差异；后者只能靠多做几个样品。

11. 参考资料

整体工作流与「哪些量值得报告」的取舍参考 NREL 的 MATBOX Microstructure Analysis Toolbox（BSD 2-Clause，Copyright (c) 2020, Alliance for Sustainable Energy, LLC）：https://github.com/NREL/MATBOX_Microstructure_analysis_toolbox 。未复制、移植、翻译或打包其任何源代码，运行时不需要 MATLAB、MATLAB Runtime 或 Octave；每个指标都按算法描述用 NumPy/SciPy 重新实现，并对解析模型做了测试。弦长与两点相关的先例参考 PoreSpy（MIT）。

方法引用（与代码无关）：Lorensen 与 Cline 1987（移动立方体）；Lindblad 2005（表面积的加权局部构型）；Iwai 等，J. Power Sources 195 (2010) 955（三相界线的格点计数偏差与 2/3 修正）；Kanit 等 2003 与 Matheron（代表体元、积分范围、L^-3 方差标度）；Efron 与 Tibshirani（自助法）；Debye（小 r 段两点相关斜率与比表面）。

本插件不导入任何 GPL 或 LGPL 组件：距离变换一律用 scipy.ndimage.distance_transform_edt，连通域标记一律用 scipy.ndimage.label。完整声明见插件目录下的 THIRD_PARTY_NOTICES.md。

Part II English Manual

Contents

1. Introduction

2. Use cases

3. Installation & enabling

4. Runtime environment & first-run setup

5. Interface

6. How to use

7. Parameters

8. Output

9. FAQ & troubleshooting

10. Notes & known limitations

11. References

1. Introduction

Measures a multi-phase microstructure and answers the question one field of view never answers on its own: how large a volume do you need before the numbers stop moving? Its subject is battery and fuel-cell electrodes, porous media and composites.

The triple phase boundary is why this plugin exists. In an electrode only the line where three phases meet can carry a reaction, and only the part of that line whose three phases each reach the outside through their own phase can carry one at all. The total and the active length are reported separately, and both come back raw and with the 2/3 lattice-count correction — because on an axis-aligned line the raw value is already exact and applying the correction there would make it 33% too small.

A converged number and a correct number are different things. L* requires two conditions at once: the spread is within tolerance at that size and at every larger size tested, and the mean is within tolerance of the mean at the largest size tested, again at that size and every larger one. Dispersion alone declares victory far too early — a small box can be precisely wrong. Every L* therefore carries an interpolated / extrapolated / not reached status, so an extrapolated number is never mistaken for a measured one.

Subvolumes cut from one image are not independent samples. They are spatially correlated, so a bootstrap interval over them is too narrow (measured coverage on a correlated synthetic field, nominal 95%: 0.873 to 0.930). The interval is still reported, because it correctly answers "how much does this number move inside this image" — but it always travels with that caveat, the overlap fraction, the distinct voxel coverage and an integral-range-based effective sample size. Widening is available and off by default: silently widening an interval is as dishonest as silently narrowing one.

2. Use cases

• Measuring the triple phase boundary of a battery or fuel-cell electrode and seeing how much of it is actually usable.
• Deciding how large a field of view a porous-media or composite study needs before its numbers stop drifting with where you sampled.
• Reporting an interfacial area in a convention someone else can compare against — both the staircase and the marching-cubes value, with their ratio.
• Attaching an honest uncertainty statement to a number measured on a single image, for a paper or a report.

3. Installation & enabling

1. Install the Prototype Apps package (or tick this plugin in the App Store).

2. This plugin is disabled by default — enable it in the App Store or the Menu Item Manager.

3. Restart Dragonfly completely (plugins are discovered at startup only). Menu: Prototype Apps ▸ Measurements & Analysis ▸ Microstructure Statistics & RVE…

4. Runtime environment & first-run setup

Nothing to install or configure. It runs entirely in Dragonfly's own Python using the NumPy and SciPy it already ships; skimage.measure.marching_cubes, used only for the interfacial area, is imported lazily (about 1 s the first time). No internet, no download, no GPU, no virtual environment.

The header reports whether this build can read labels, publish ROIs and publish Channels. Anything it cannot do is greyed out rather than left to fail on click, and exports stay available even when nothing can be published.

5. Interface

1. Inputs

Phase source: MultiROI labels or a Channel threshold. Pick the MultiROI (or Channel), an optional domain-mask ROI and the timestep; every label is listed with a role (ignore / A / B / C), and all three roles must be assigned before the triple phase boundary can be measured. Shape, spacing, origin and timestep count are shown at the bottom. Every picker lists published objects only.

2. Calibration & Preprocessing

Override the voxel size (Z/Y/X in mm) or read it from the object; anisotropic voxels raise a notice — every area, edge length and chord is weighted by its own axis' spacing. Crop before measuring (voxel ranges per axis). In threshold mode, the threshold and the polarity live here; in label mode, this is where you decide whether label 0 is a phase or excluded from the domain (excluded by default). "Exclude the field-of-view boundary from the interfacial area" is on by default. All preprocessing acts on a working copy — the input object is never modified.

3. Parameters

The upper half selects metrics: volume fraction (always on), interfacial area (with the estimator and the pre-smoothing sigma), triple phase boundary, active triple phase boundary (with the percolation axis), connectivity (with the 6/18/26 rule) and chord lengths (with the histogram bin count). The lower half is the sampling: scheme, overlap policy, number of sizes, subvolumes per size, smallest and largest box, dispersion and drift tolerances, absolute tolerance floor, confidence level, bootstrap resamples, interval method, random seed and the summed-area-table memory budget. One line at the bottom gives the voxel count, the size ladder, an estimated sweep time and the working-copy size — an order-of-magnitude guide, never a promise.

4. Preview & QC

A fast pass on a decimated copy (the factor is raised automatically so no axis exceeds 128 voxels), showing the size table, the convergence curve and the relative-spread plot. Nothing is published and the export buttons stay disabled. Decimation changes every surface-derived number, so a Preview is a shape check and not a value to report.

5. Run

The plan is restated first (phase source, scheme, overlap policy, seed, A/B/C, whether connectivity is on, whether the data is cropped) together with the estimated cost; then the full-resolution run, cancellable at any time. The run publishes nothing either.

6. Results & Export

Choose the metric to display and read its convergence curve and relative-spread plot. The curve carries two bands that never share a colour or a texture: the wide hatched band is the spread of a SINGLE subvolume (mean ± 1 sd), the narrow solid band is the confidence interval on the MEAN of n — the second shrinks as √n and says nothing about whether one box is representative. Below it: L* with its status, the integral range, the per-phase metric table, the per-size sweep table and every warning, then three export buttons and three publish buttons.

Share Report

A seventh tab, Share Report, is not a workflow step — it puts a finished report on the internet temporarily and does no analysis. It serves the report you just generated from this computer through a temporary Cloudflare quick tunnel and hands back a temporary public address; nothing is uploaded, no account is needed, and the page carries your image data itself. The address is not usable immediately: it only starts answering roughly 40 s AFTER the tunnel is started (measured from this machine: 45 s once, while two other tunnels never resolved at all), so do not send the link before the status turns green. While it is running anyone who has the link can read the report — there is no password. Pressing Stop sharing, closing the window or quitting Dragonfly makes the address stop working permanently; it is never reissued. The link is only offered once this machine has confirmed the address answers, or has said plainly that it could not confirm it.

6. How to use

1. Pick the MultiROI (or a Channel plus a threshold) in step 1 and give three labels the roles A, B and C.

2. Confirm the voxel size in step 2, decide whether label 0 is a phase, and crop if you need to.

3. Tick the metrics in step 3 and set the size ladder and the tolerances.

4. Run a preview in step 4 and check the shape looks sensible, the curve is plausible and there is no wall of warnings.

5. Run at full resolution in step 5.

6. Read L* and its status in step 6, then export or publish.

7. Parameters

Metrics

RVE sampling

8. Output

9. FAQ & troubleshooting

• L* says extrapolated or not reached — that is a report, not a fault: nothing converged inside the sizes actually measured. An extrapolated value comes from the fitted power law and, measured against ground truth, errs by -12% at 1.5x the tested range and -16% at 2x. Getting an interpolated answer needs a larger field of view or a looser tolerance.
• It says only 2 subvolume sizes were measured — consecutive rungs of the geometric ladder rounded onto the same whole number of voxels. Lower the smallest box, raise the largest-box fraction, or use a larger field of view.
• The active triple phase boundary is 0% — at least one phase never reaches the outside. Check the percolation axis first (naming an axis is far stricter than "any outside face"), then whether label 0 was excluded from the domain, and whether the domain-mask ROI seals the structure in.
• The two interfacial areas differ by about 1.5x — that is expected, not an error. For a surface with isotropic normals the staircase area is exactly 3/2 of the truth, and that error does not shrink with resolution. Marching cubes is the headline number and is itself about 8% high on unsmoothed binary data.
• The confidence interval looks too narrow — it is, and the reason sits next to it: the subvolumes come from one image. Widen it with the design effect from the integral range, or read it for what it is — sampling within this image.
• It warns that the fitted exponent is outside the plausible band — the boxes are probably still inside the correlated regime, or the chosen metric is not additive. The number is still reported; the assumption is not hidden.
• The nested scheme produces no intervals at all — nested boxes contain one another, so the samples are perfectly correlated and there is one value per size; the bootstrap refuses them. Use random subvolumes when you need an interval.
• It says the voxels are anisotropic — every area, edge length and chord is already weighted per axis, but connected-component labelling is purely topological (scipy.ndimage.label has no spacing argument), so a near neighbour and a far one count the same. That cannot be fixed at the labelling step.

10. Notes & known limitations

• The whole volume is read into memory; use the preview to settle parameters on large data.
• Inputs must be published objects; every picker lists published objects only.
• Publishing is always an explicit step-6 action; neither preview nor run publishes anything, and any change to an input or a parameter drops the previous result and disables the exports immediately.
• The preview is decimated: it is a shape check, and its numbers must not be reported.
• Connectivity, the active triple phase boundary and chord lengths are global quantities that no summed-area table can accelerate; every subvolume is evaluated directly, so turning them on costs real time.
• Nested sampling is display-only: one box per size, each containing the last, and the whole curve depends on where the centre was placed.
• This plugin does not duplicate what already exists elsewhere. Threshold sensitivity belongs to Porosity Threshold Confidence; distance-transform thickness and spacing to Structure Scale Analyzer; tortuosity to TauFactor; Minkowski functionals to Minkowski Functionals (QuantImPy). Use those when you need those quantities.
• No Euler-characteristic connectivity density is emitted, and no orientation sweep or fabric tensor is computed or implied; the chord anisotropy ratio is the ratio of three axial chord means and nothing more.
• Every interval describes sampling within this one image. It cannot capture specimen-to-specimen variation — only more specimens can.

11. References

The overall workflow, and the choice of which quantities are worth reporting, were informed by NREL's MATBOX Microstructure Analysis Toolbox (BSD 2-Clause, Copyright (c) 2020, Alliance for Sustainable Energy, LLC): https://github.com/NREL/MATBOX_Microstructure_analysis_toolbox — no source was copied, ported, translated or bundled, and no MATLAB, MATLAB Runtime or Octave is required at runtime; every metric is implemented from its algorithmic description in NumPy/SciPy and tested against analytic phantoms. PoreSpy (MIT) is prior art for chord-length and two-point correlation measurement.

Method citations (no code relationship): Lorensen & Cline 1987 (marching cubes); Lindblad 2005 (weighted local configurations for surface area); Iwai et al., J. Power Sources 195 (2010) 955 (triple-phase-boundary lattice-count bias and the 2/3 correction); Kanit et al. 2003 and Matheron (representative volume element, integral range, L^-3 variance scaling); Efron & Tibshirani (the bootstrap); Debye (the small-r slope of the two-point correlation against specific surface).

No GPL or LGPL component is imported: every distance transform uses scipy.ndimage.distance_transform_edt and every connected-component labelling uses scipy.ndimage.label. The full statement is in THIRD_PARTY_NOTICES.md in the plugin folder.