Porosity Threshold Confidence（孔隙阈值置信度）

Porosity Threshold Confidence - User Manual

Dragonfly Prototype Apps · Porosity Threshold Confidence...

版本 Version 1.0 · 2026-08-01

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

基于阈值得到的孔径或孔隙率，其可靠性完全取决于阈值取在哪里——而通常的流程不会告诉使用者这个数字随阈值变化了多少。本插件在阈值上做扫描，每一步都用完全相同的方法测量：取最大连通孔洞、逐层提取边界、最小二乘拟合圆。

「阈值—孔径」曲线才是真正的结果。 曲线的平坦区表示测量对阈值不敏感，该区间内的离散程度就是真实的不确定度；报告中的单一数字只是平坦区的概括。

圆拟合在物理坐标（毫米）中完成。 在体素索引空间拟合、事后再乘以间距，只有在面内体素为正方形时才正确；对各向异性数据，那等于用椭圆去拟合一个圆，误差正比于长宽比——而且在各向同性数据上完全看不出来。

2. 适用场景

• 需要给孔径或孔隙率一个可辩护的不确定度，而不只是一个数字。
• 比较不同操作者、不同阈值方法得到的结果差异来源。
• 把 CT 测得的孔径与 SEM、CAD 或标称值对照。
• 在报告或客户交付中明确说明「这个测量对阈值有多敏感」。

3. 安装与启用

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

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

3. 完全重启 Dragonfly（插件只在启动时被发现）。

4. 从菜单打开：Prototype Apps ▸ Porosity Threshold Confidence…（分组：Measurements & Analysis）。

4. 运行环境与首次配置

无需任何安装或配置。 完全运行在 Dragonfly 自带的 Python 中，使用其已附带的 NumPy 与 SciPy。不需要 GPU、不创建虚拟环境，分析过程也不访问网络。唯一的例外是可选的「分享报告」标签页，它不做任何计算：发布报告会开启一条临时 Cloudflare 快速隧道，且首次使用会在你确认后下载 Cloudflare 的 cloudflared.exe（约 52 MB）。

面板顶部显示当前可用能力（能否发布 ROI 与通道）。不可用的按钮会被禁用。

5. 界面说明

顶部固定显示运行环境、当前输入、当前任务、进度条与 Cancel。前六个标签页对应六个编号步骤；第七个标签页 分享报告 不是流程步骤，它只把已生成的报告临时发布到互联网，不做任何计算。

1. 输入

选择通道（只列出已发布对象）、可选的限定 ROI、时间步。选定后显示形状、三轴间距、是否各向异性与时间步数。

2. 标定与预处理

孔隙极性（暗孔隙 / 亮孔隙）、手动指定体素尺寸（用于缺少几何信息的对象）、可选高斯平滑。预处理只作用于工作副本，绝不修改输入对象。

3. 参数

扫描步数、扫描区间宽度（0 表示按直方图自动）、阈值选取方式、参考孔径、平台窗口、置信水平、连通性。底部给出运行时间与内存的量级估算。

4. 预览与质检

在降采样数据上快速跑一遍，显示曲线与全部告警。此阶段不发布任何对象，也不会启用导出按钮。降采样时间距同步放大，因此预览得到的孔径与全分辨率结果量级一致。

5. 运行

先用一行文字列出将要执行的完整方案，然后全分辨率运行，可随时取消。

6. 结果与导出

曲线（阴影为平台区，虚线为所选阈值）、结果表、全部告警，以及发布最佳阈值 ROI，并可把报告导出为 HTML、Word 或 PDF（一个按钮加一个格式下拉框），另有 CSV 与 JSON 导出。

分享报告

通过 Cloudflare 临时隧道，直接从本机提供刚生成的报告，并返回一个临时的公网地址；不上传任何数据，也不需要账号。分享期间，拿到链接的任何人都能读取报告，没有密码，而报告中含有您的图像数据。点击停止分享、关闭窗口或退出 Dragonfly 后，该地址立即失效且永不重发。只有在本机确认地址已可访问、或明确告知无法确认时，才会把链接交给您。

6. 使用步骤

1. 第 1 步选择通道，必要时加限定 ROI。

2. 第 2 步确认孔隙极性与体素尺寸。

3. 第 4 步先跑一次预览，确认曲线形状合理、没有「不是圆形」的告警。

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

5. 第 6 步读取孔径与置信区间，注意离散化偏差是单独列出的。

6. 发布 ROI 或导出 HTML 报告。

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

• 告警「不是圆形」 —— 阈值化得到的区域边界严重偏离圆形。任何闭合区域都能拟合出一个圆，所以这条告警的意思是：这个孔径不是孔径。请检查孔隙极性、限定 ROI，以及该体积中是否真的存在一个圆孔。
• 告警「即使最平坦的区间也变化了 x%」 —— 该测量确实对阈值敏感，此时给出的区间就是诚实的不确定度，不应只引用中心值。
• 结果比预期小约一个体素 —— 这是离散化偏差，属于预期行为，已在结果表中单独列出。若需要更高精度请提高分辨率。
• 参考值模式下偏差极小 —— 这不能说明测量准确：阈值本来就是照着该参考值挑的。若要评估准确度，请用平台区模式，再与参考值比较。
• 没有任何阈值能拟合出圆 —— 通常是孔隙极性选反了，或限定 ROI 把孔洞排除在外。

10. 注意事项与已知限制

• 本插件测量的是单个近似圆形的孔洞（钻孔、通道、管腔）。它不是通用的孔径分布工具。
• 整卷读入内存；超大体积请先裁剪，或先用预览确认参数。
• 输入必须是已发布的通道；未发布对象不会出现在下拉列表中。
• 置信区间只反映阈值敏感度，不包含离散化偏差、噪声或分割方法本身的系统误差。两者在结果表中分开列出。
• 预处理与预览都不会修改输入对象；发布始终是第 6 步的显式操作。

11. 参考资料

工作流参考了 STFC Multi Threshold Comparator（BSD 许可）：https://edata.stfc.ac.uk/items/dbcef852-e77b-4ac6-9690-dd71eef54ab9 ——未复制其任何源代码，运行时也不需要 Avizo 或 Hx API。阈值方法：N. Otsu, IEEE Trans. SMC 9(1), 1979。圆拟合：I. Kåsa, IEEE Trans. Instrum. Meas. 25(1), 1976，并做几何精化。

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

A pore diameter or porosity figure obtained by thresholding is only as good as the threshold, and the usual workflow never tells you how much the number moved. This plugin sweeps the threshold and measures the pore identically at every step: largest connected pore, per-slice boundary extraction, least-squares circle fit.

The threshold-to-diameter curve is the real result. Its flat region is where the measurement is insensitive to the threshold, and the spread across that region is the real uncertainty. The single reported number is a summary of that flat region.

Circles are fitted in physical coordinates (mm). Fitting in voxel indices and multiplying by a spacing afterwards is only valid when the in-plane voxels are square; on anisotropic data it fits an ellipse to a circle and is wrong by the aspect ratio — and it looks perfectly fine on isotropic data.

2. Use cases

• When a pore diameter or porosity figure needs a defensible uncertainty, not just a value.
• When comparing results between operators or thresholding methods, to see where the difference comes from.
• When checking a CT-measured aperture against SEM, CAD or a nominal figure.
• When a report or customer deliverable has to state how threshold-sensitive the measurement is.

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).

4. Open it from: Prototype Apps ▸ Porosity Threshold Confidence… (group: Measurements & Analysis).

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. No GPU, no virtual environment, and the analysis never touches the network. The one exception is the optional Share Report tab, which performs no computation: publishing opens a temporary Cloudflare quick tunnel, and the first use downloads Cloudflare's cloudflared.exe (about 52 MB) after you confirm it.

The header shows what this build supports (publishing ROIs and Channels). Unavailable actions are disabled.

5. Interface

The header always shows the environment, the current input, the running task, a progress bar and Cancel. The six numbered steps are the first six tabs. A seventh tab, Share Report, is not a workflow step — it puts a finished report on the internet temporarily and does no analysis.

1. Inputs

Pick a Channel (published objects only), an optional restricting ROI, and the timestep. Shape, spacing, anisotropy and timestep count are shown.

2. Calibration & Preprocessing

Pore polarity (dark or bright), a manual voxel size for objects without geometry, and optional Gaussian smoothing. Preprocessing acts on a working copy and never modifies the input object.

3. Parameters

Sweep steps, sweep span (0 = automatic from the histogram), selection mode, reference diameter, plateau window, confidence level and connectivity, with an order-of-magnitude runtime and memory estimate.

4. Preview & QC

A fast pass on downsampled data showing the curve and every warning. Nothing is published here and the export buttons stay disabled. Spacing is scaled with the downsampling, so the preview diameter is comparable to the full-resolution one.

5. Run

One line spelling out exactly what will run, then the full-resolution pass, cancellable at any time.

6. Results & Export

The curve (plateau shaded, chosen threshold dashed), the results table, all warnings, a button to publish the best-threshold ROI, and exports: the report as HTML, Word or PDF (one button plus a format chooser), plus CSV and JSON.

Share Report

Serves the report you just generated from this computer through a Cloudflare quick tunnel, and hands back a temporary public address. Nothing is uploaded and no account is needed. While it is running anyone who has the link can read the report — there is no password, and the report contains your image data. 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. In step 1 pick the Channel, adding a restricting ROI if useful.

2. In step 2 confirm the pore polarity and the voxel size.

3. In step 4 run a preview first and check the curve looks sensible with no 'NOT round' warning.

4. In step 5 run at full resolution.

5. In step 6 read the diameter and its interval, noting that the discretisation bias is listed separately.

6. Publish the ROI or export the HTML report.

7. Parameters

8. Output

9. FAQ & troubleshooting

• "NOT round" warning — the thresholded region's boundary deviates badly from a circle. A circle can be least-squares fitted to any closed blob, so this warning means the diameter is not a pore diameter. Check the polarity, the restricting ROI, and whether there is a round bore in this volume at all.
• "even the flattest part of the curve varies by x%" — the measurement genuinely is threshold-sensitive. The interval is the honest uncertainty; do not quote the central value alone.
• The result is about one voxel small — that is the discretisation bias, expected and listed separately in the results table. Acquire at a higher resolution if it matters.
• Reference mode shows a tiny deviation — that is not evidence of accuracy: the threshold was picked to match that reference. To assess accuracy, use plateau mode and then compare.
• No threshold produces a fittable pore — usually the polarity is inverted, or the restricting ROI excludes the pore.

10. Notes & known limitations

• This measures a single, approximately circular pore (a drilled hole, a channel, a lumen). It is not a general pore-size-distribution tool.
• The whole volume is read into memory; crop very large volumes, or use the preview to settle parameters first.
• Inputs must be published Channels; unpublished objects do not appear in the picker.
• The confidence interval covers threshold sensitivity only — not the discretisation bias, noise, or systematic error in the segmentation approach. The first two are listed separately.
• Neither preprocessing nor preview modifies the input object, and publishing is always an explicit step-6 action.

11. References

The workflow was informed by the STFC Multi Threshold Comparator (BSD licence): https://edata.stfc.ac.uk/items/dbcef852-e77b-4ac6-9690-dd71eef54ab9 — no source code was copied and no Avizo or Hx API is needed at runtime. Thresholding: N. Otsu, IEEE Trans. SMC 9(1), 1979. Circle fitting: I. Kasa, IEEE Trans. Instrum. Meas. 25(1), 1976, with geometric refinement.