Pores to Surface Analysis(空洞到表面距离分析)
Pores to Surface Analysis - User Manual
Dragonfly Prototype Apps · Pores to Surface Analysis...
版本 Version 1.0 · 2026-09-01
第一部分 中文手册
目录
1. 简介
2. 什么算实体、外部和空洞
3. 距离，以及两种定义
4. 零件被视场切断时
5. 使用步骤
6. 表格与 CSV 的内容
7. 环境需求
1. 简介
从一幅图像通道出发的一条完整工作流：分割实体 → 自动标记被实体包围的空洞 → 转成 MultiROI → 测量每个空洞到零件表面的距离 → 按距离阈值筛查。
五个页签就是工作流本身：1 数据源 → 2 分割 → 3 距离 → 4 发布 → 5 分析。五个页签始终可以打开和修改；若某一步所需的上一步结果尚未产生，点它的按钮时会告诉你要先做哪一页，而不是把整页关闭。
第 1 页上的「按当前设置执行全部步骤」按钮会依次无人值守地跑完第 1～4 步，每一步都使用它自己那一页此刻显示的设置，最后把空洞 MultiROI 发布到会话中。第 5 页「分析」在发布之后进行，其 CSV 导出会弹出文件对话框，因此不包含在自动运行中。
在点「发布」之前，本插件不会创建或修改会话中的任何对象。 第 2、3、5 步只读取通道并计算，你可以反复试阈值而不动数据。
「数据源」页的一键执行全部步骤（按当前设置）会无人值守地跑完整个流程：读取图像 → 分割固相并找出孔隙 → 计算到表面的距离 → 发布，每一步都使用你按下按钮那一刻各自页签上显示的设置。其中只有「发布」会向会话写入对象，它被特意包含在内——否则无人值守跑完之后什么也不会留下。所有页签始终可以打开和修改参数，以便在运行之前逐页检查；某一步所需的输入尚不存在时，按下它自己的按钮会给出提示，说明缺的是哪一步。
2. 什么算实体、外部和空洞
实体就是材料——对铸件而言是金属。它由通道上的一个阈值得到，可选清理，并默认只保留最大的一块连通域。
外部是所有连通到体数据边界的背景体素，也就是件外的空气。
空洞则是其余的每一个背景连通域：它触不到边界，也就是被实体完全包围的空腔。背景只被标记一次，两个答案出自同一次运算，因此「空洞的分割」与「什么算外部」不可能自相矛盾。
零件＝实体＋其内部空洞，零件的外边界就是下文所有距离所测到的零件表面。
⚠ 「只保留最大的一块实体」默认开启，这一点很重要。 否则体数据中别处的一小块噪声会被当成一个独立的零件，带着它自己的空腔和表面——而那些空腔根本不在铸件里。
3. 距离，以及两种定义
「这个空洞离零件表面多远」在体素网格上有两个都站得住脚的答案，两者相差约一个体素。插件两个都算、两个都报，不会把其中之一说成是「那个」距离。
- 到表面的距离——从空洞表面到零件表面，也就是空腔与外部之间最薄的一层材料。表面取体素的面，用 k-d 树匹配。当两个表面平整且平行时（近表面孔的常见情形）该值是精确的；在倾斜的阶梯状表面上，以面心采样最多高估半个面对角线。
- 中心距离——从空洞体素中心到外部体素中心。完全不涉及表面模型，因而没有可出错的地方。
「距离」页会打印两者在你这份数据上的实测中位差，并列出一个体素步长，让你自己看到它们的关系符合预期，而不是让你相信。
4. 零件被视场切断时
⚠ 零件超出扫描范围的地方，那条边界是「切面」而不是零件表面。 距离重建边界 1 mm 的空洞，并不等于距离铸件表面 1 mm。
默认把切面计入表面，以免距离被悄悄测到远处的另一个真实表面；但凡是相关之处都会标出：运行结果会给出表面中切面所占的百分比，每个空洞所在行也会写明它自己的最近表面是落在切面上还是零件上。
在「距离」页取消勾选把重建边界也算作零件表面，即可只测到真实表面。两种答案都合理，选哪一种取决于这次扫描；不合理的是不知道自己拿到的是哪一种。
5. 使用步骤
1. 1 数据源——选择图像通道（新发布对象后请点「刷新」）与时间步，点读取该图像。面板会显示尺寸、体素尺寸与灰度范围。若读不到体素尺寸，请先在 Dragonfly 中标定该数据：分析会被拒绝，因为所有距离都将失去意义。
2. 2 分割——选择材料是亮相（CT 中金属通常如此）、暗相，还是位于某个灰度区间。点 Otsu 自动阈值 取一个起点，也可以直接在直方图上点选或手动输入。需要时调整清理参数，然后点分割实体并查找空洞。报告给出空洞数量与孔隙率；预览可显示实体 / 空洞 / 外部三类。
3. 3 距离——决定是否把重建边界算作零件表面，然后点测量到表面的距离。报告给出最近、中位与最远的空洞，并同时说明两种定义。
4. 4 发布——填写名称前缀并点发布。空洞以带测量值的 MultiROI 形式进入会话；实体与全部空洞也可一并发布为 ROI。
5. 5 分析——设定距离阈值。所有比该阈值更靠近表面的空洞会整行标红，摘要行给出计数。点在 MultiROI 中标红可把会话中的同一批空洞也涂红，使三维视图与表格一致。导出 CSV…… 会写出全部列以及一个「低于阈值」标志。
6. 表格与 CSV 的内容
- 空洞——label 编号，与发布的 MultiROI 中一致。
- 到表面的距离（µm） 与 中心距离（µm）——即上文两种定义。
- 等效直径（µm）——等体积球的直径（二维图像则为等面积圆的直径）。
- 体积（µm³） 与 体素数——空洞的大小。
- 质心 Z / Y / X（µm）——用于定位。
- 最近表面——「零件表面」或「重建边界切面」。
7. 环境需求
无需安装、联网、GPU 或虚拟环境——进程内 PyQt6 + numpy + scipy，均为 Dragonfly 自带。需要会话中有已发布、已标定体素尺寸的单分量灰度图像通道。支持二维图像（单张切片），且不会把切片自身的上下两面误当成零件表面。
Part II English Manual
Contents
1. Introduction
2. What counts as solid, outside and a pore
3. The distance, and the two conventions
4. When the part is cut by the field of view
5. How to use it
6. What the table and the CSV contain
7. Requirements
1. Introduction
One workflow over one image channel: segment the solid, mark the cavities it encloses, turn them into a MultiROI, measure how far every pore is from the surface of the part, and screen the pores against a distance threshold.
The five tabs are the workflow, and each one opens only once the step before it has produced something: 1 Source → 2 Segment → 3 Distance → 4 Publish → 5 Analysis.
Nothing in the session is created or modified until you press Publish. Steps 2, 3 and 5 read the channel and compute; you can explore a threshold all day without touching the data.
Execute All Steps with Current Settings on the Source tab runs the whole workflow unattended - read the image, segment the solid and find the pores, measure the distance to the surface, publish - each step with whatever its own tab shows at the moment you press it. Publishing is the only step that writes to the session, and it is included on purpose: without it an unattended run would leave nothing behind. Every tab stays open at all times so the parameters can be read and changed BEFORE the run; a step whose input does not exist yet refuses when you press ITS button and says which step is missing.
2. What counts as solid, outside and a pore
Solid is the material — for a casting, the metal. It is a threshold on the channel, optionally cleaned, and by default reduced to its largest connected component.
Outside is every background voxel whose background component reaches the border of the volume. That is the air around the part.
A pore is any other background component: one that never reaches the border, i.e. a cavity fully enclosed by the solid. The background is labelled once and both answers come out of that same pass, so the pore segmentation and the decision about what counts as outside cannot disagree with each other.
The part is the solid plus its pores, and the boundary of the part is the part surface every distance below is measured to.
⚠ Keep only the largest solid component is ON by default, and that matters. A speck of noise elsewhere in the volume is otherwise treated as its own little part, with its own cavities and its own surface — and those cavities are not in the casting at all.
3. The distance, and the two conventions
The question is "how far is this pore from the surface of the part", and on a voxel grid that has two honest answers about one voxel apart. Both are computed and both are reported; neither is presented as "the" distance.
- Distance to surface — from the pore's surface to the part's surface: the thinnest wall of material between the cavity and the outside. Surfaces are the voxel FACES, matched with a k-d tree. This is exact when the two surfaces are flat and parallel, which is the usual near-surface case; on an oblique staircase surface, face-centre sampling can overestimate by at most half a face diagonal.
- Centre distance — from a pore voxel centre to an outside voxel centre. No surface model at all, so there is nothing in it to get wrong.
The Distance tab prints the measured median difference between the two, next to one voxel step, so you can see for your own data that they behave as expected instead of taking it on trust.
4. When the part is cut by the field of view
⚠ Where the part runs out of the scanned volume, that boundary is a CUT, not a surface of the part. A pore 1 mm from the edge of the reconstruction is not 1 mm from the surface of the casting.
The cut is kept in the surface by default, so a distance is never silently taken to a far-away real surface instead — but it is flagged everywhere it matters: the run says what percentage of the surface is a cut, and each pore's row says whether its own nearest surface point lies on the cut or on the part.
Untick Count the edge of the reconstruction as part surface on the Distance tab to measure to real surfaces only. Both answers are legitimate and which one you want depends on the scan; what is not legitimate is not knowing which you got.
5. How to use it
1. 1 Source — pick the image channel (press Refresh after publishing a new one) and the time step, then press Read this image. The panel shows the size, the voxel size and the value range. If the voxel size cannot be read, calibrate the dataset in Dragonfly first: the analysis is refused, because every distance would be meaningless.
2. 2 Segment — choose whether the material is the bright phase (usual for metal in CT), the dark phase, or a value band. Press Otsu for a starting threshold, or click on the histogram, or type the value. Adjust the clean-up if you need it, then press Segment the solid and find the pores. The report gives the pore count and the porosity; the preview shows solid / pore / outside.
3. 3 Distance — decide whether the edge of the reconstruction counts as part surface, then press Measure distance to the surface. The report gives the nearest, median and farthest pore, and states both conventions.
4. 4 Publish — set a name prefix and press Publish. The pores arrive as a MultiROI carrying the measurements; the solid and all pores can come as ROIs too.
5. 5 Analysis — set the distance threshold. Every pore closer to the surface than that is marked red across its whole row, and the summary counts them. Mark them red in the MultiROI recolours the same pores in the session, so the 3-D view and the table agree. Export CSV… writes every column plus a below-threshold flag.
6. What the table and the CSV contain
- Pore — the label number, the same one the published MultiROI uses.
- Distance to surface (µm) and Centre distance (µm) — the two conventions above.
- Equivalent diameter (µm) — the diameter of the equal-volume sphere (for a 2-D image, of the equal-area disc).
- Volume (µm³) and Voxels — the pore's size.
- Centroid Z / Y / X (µm) — where to find it.
- Nearest surface — part or field-of-view cut.
7. Requirements
No install, no internet, no GPU, no venv — in-process PyQt6 + numpy + scipy, all bundled with Dragonfly. Needs a published single-component grey image channel with a calibrated voxel size. A 2-D image (a single slice) is supported, and its own two Z faces are not mistaken for surfaces of the part.