Porosity Analysis (Hands-on Workshop)(孔隙率分析实操课程)

Porosity Analysis (Hands-on Workshop) - User Manual

Dragonfly Prototype Apps · Porosity Analysis...

版本 Version 1.0 · 2026-07-26

第一部分 中文手册

目录

1. 简介

2. 五个步骤与教学内容

3. 功能特点

4. 使用步骤

5. 环境需求

6. 提示与延伸

1. 简介

Porosity Analysis (Hands-on Workshop) 是 Hands-on Workshops（上手练习） 类目下的第一个实操项目：一个多标签页的教学向导,带你走完多孔介质（数字岩心、金属泡沫、过滤材料、骨骼等）孔隙结构分析的完整流程。窗口顶部是一条工具栏（Overview 总览、图像下拉框、Refresh 刷新）,下方是五个环环相扣的步骤标签页,建议从左到右依次操作。

每个标签页都把两类内容配成一对:📖 Learn（概念与原理） 按钮弹出可缩放、带 中文|EN 切换的教学窗口,用图文详解基础概念与操作要点;🛠 Try it（动手操作） 按钮在真实数据上执行分析。整套流程在进程内运行,只用 Dragonfly 自带的 numpy/scipy——无需 venv、无需下载、无需 GPU、无需联网。

「导入」页上的 Execute All Steps with Current Settings（按当前设置执行全部步骤） 会无人值守地跑完整个练习——使用所选图像、用 Otsu 选择阈值、计算总孔隙率、区分连通孔隙与封闭孔隙、统计孔隙团簇、估算渗透率——每一步都使用你按下按钮那一刻它自己那一页显示的设置。除非勾选该分组里的两个选项之一，否则不会向会话写入任何对象（创建合成样品会发布一个 Channel，创建孔隙 ROI 会发布一个 ROI），两者默认都不勾选。所有标签页始终保持可用：讲师可以在运行前把每个参数都设置好，学员也仍然可以一步一步手动操作；若某一步所需的输入尚不存在，按下它自己的按钮时会拒绝执行，并说明必须先运行哪一步。

适用场景:教学与自学（把抽象的孔隙概念与真实操作结合,边学边做）;快速培训新员工/学生建立数字岩心分析的完整认知;作为标准分析流程的向导,避免遗漏关键步骤（阈值核对、连通性、REV、渗透率估算）;也可作为客户演示与市场推广中的"可交互教程"。

2. 五个步骤与教学内容

五个标签页对应孔隙分析的五个步骤。每个标签页各带 3 篇 📖 Learn 教学文档与若干 🛠 Try it 动手按钮:

3. 功能特点

• 合成样本一键生成:输入样本尺寸（体素）、目标孔隙率 φ、孔隙粗糙度（blobiness）,即可造一份带已知孔隙率的练习体数据并发布为 Channel。优先用 porespy（若 Dragonfly 环境已含）,否则回退到 numpy 高斯随机场生成——没有数据也能立即上手。
• Otsu 自动阈值:纯 numpy 实现的 Otsu 类间方差最大化,自动给出分割阈值并预览孔隙率;可勾选 "Pore = low intensity"（CT 中孔隙通常偏暗）并手动微调阈值。
• 孔隙 ROI 分割与发布:按当前阈值把孔隙相体素构建成 ROI 并发布回 Dragonfly（getAsROIWithinRange）,便于在 2D 切片/3D 中核对分割边界。
• 孔隙率计算:φ = 孔隙体素数 / 总体素数,一个无量纲比值,与体素尺寸无关。
• 开孔/闭孔连通性分析:用 scipy.ndimage.label（26 连通）做连通域标记,把与样品边界面相接触的孔簇判为开孔,被固体完全包裹的判为闭孔,给出总/开/闭孔隙率、孔簇数量、最大孔簇占比与孔簇尺寸分布。
• Kozeny–Carman 渗透率估算:由孔隙率 φ 与平均颗粒尺寸 d 估算渗透率 k = φ³·d² / [180·(1−φ)²],同时换算为 m² / Darcy / mD（数量级参考）。
• 丰富的双语教学文档:15 篇 📖 Learn 文档覆盖成像物理、阈值/分割、孔隙率、连通性、REV、孔隙网络、SNOW、达西定律、模拟方法等,每篇都可 中文|EN 切换、缩放并保持打开。

4. 使用步骤

1. 在 Dragonfly 中打开 Prototype Apps ▸ Hands-on Workshops ▸ Porosity Analysis...。

2. 先点顶部 📘 Overview 通读课程总览,了解五个步骤的关系。

3. 步骤 1（Import）:没有数据时,设置样本尺寸/目标孔隙率/孔隙粗糙度,点 🧪 Create synthetic porous sample 生成并发布一份合成样本;有自己的数据则用 📂 Open Dragonfly import 导入后回来点 ↻ Refresh,再从顶部图像下拉框选中它。

4. 步骤 2（Segment）:点 🎯 Auto threshold (Otsu) 自动求阈值并预览孔隙率,必要时手动调整 Threshold 并确认 Pore = low intensity;再点 🧩 Create pore ROI 生成孔隙 ROI,在切片/3D 中核对边界是否贴合真实孔壁。

5. 步骤 3（Porosity）:点 📊 Compute total porosity 得到总孔隙率 φ;点 🔗 Open vs closed (connectivity) 拆分开孔/闭孔并查看孔簇统计（只有开孔贡献渗流）。

6. 步骤 4（Pore Network）:点 🕸 Lightweight pore stats 得到孔簇数量、开/闭孔比例、最大孔簇占比与尺寸分布;需要完整孔体—喉道网络时,按提示转到 ROI to MultiROI (SNOW) 插件。

7. 步骤 5（Simulation）:填入平均颗粒尺寸 d,点 ⚗ Estimate permeability (Kozeny–Carman) 得到 k 的数量级估计;需要严格定量时,按提示转到 Permeability (OpenPNM) 插件。

8. 任何一步都可点该标签页的 📖 Learn 按钮深入学习对应概念,再回到 🛠 Try it 动手验证。

5. 环境需求

• 无需 venv、无需下载、无需 GPU、无需管理员权限、无需联网。 所有动手操作在进程内运行,只用 Dragonfly 自带的 numpy/scipy。
• 动手按钮需在 Dragonfly 内运行（要读取 Channel、发布 ROI 等对象模型操作）。教学文档则随处可看——在没有 Dragonfly 对象模型的独立测试环境里,📖 Learn 照常工作,🛠 Try it 会提示需在 Dragonfly 内运行。
• 合成样本生成优先使用 porespy（若 Dragonfly 环境已安装）,否则自动回退到 numpy 高斯随机场方案,两种情形都无需额外安装。

6. 提示与延伸

本插件的孔隙网络与模拟步骤只做轻量、进程内的近似:第 4 步用连通域标记给出连通性快照,第 5 步用 Kozeny–Carman 给出数量级渗透率。

• 需要完整的孔体—喉道网络提取（配位数、孔径/喉道分布）时,请用 Prototype Apps 的 ROI to MultiROI (SNOW) 插件（porespy 的 SNOW 分水岭算法）。
• 需要严格的渗透率（绝对渗透率、两相驱替、相对渗透率曲线）时,请在提取网络后用 Permeability (OpenPNM) 插件。这些较重的插件各自可能需要一次性环境安装。
• 关键洞见:渗透率 k ∝ φ³——孔隙率的三次方!孔隙率小幅变化会被立方放大,所以分割阈值必须仔细核对,不要盲信自动值。

这是 Hands-on Workshops 类目的第一个项目;其多标签页 StepTab + 双语 DocDialog 框架可复用于制作更多领域的实操课程。

Part II English Manual

Contents

1. Introduction

2. The five steps & teaching content

3. Features

4. How to use

5. Requirements

6. Tips & delegation

1. Introduction

Porosity Analysis (Hands-on Workshop) is the first project in the Hands-on Workshops category: a multi-tab teaching wizard that walks you through the complete workflow of analysing the pore structure of porous media (digital rock, metal foams, filter media, bone, ...). A toolbar at the top (Overview, an Image dropdown, Refresh) sits above five linked step tabs that you work left to right.

Every tab pairs two kinds of content: 📖 Learn buttons open a resizable, 中文|EN-switchable teaching pop-up that explains the concepts and workflow in depth; 🛠 Try it buttons run the analysis on real data. Everything runs in-process on Dragonfly's bundled numpy/scipy — no venv, no download, no GPU, no internet.

Execute All Steps with Current Settings on the Import tab runs the whole workshop unattended - use the selected image, choose the threshold with Otsu, compute the total porosity, split open from closed porosity, count the pore clusters, estimate the permeability - each step with whatever its own tab shows at the moment you press it. Nothing is written to the session unless you tick one of the two boxes in that group (creating the synthetic sample publishes a Channel; creating the pore ROI publishes an ROI); both are off by default. Every tab stays open at all times, so an instructor can set every parameter BEFORE the run and a learner can still work the steps one at a time; a step whose input does not exist yet refuses when you press ITS button and says which step has to run first.

Use it for teaching and self-study (couple abstract pore concepts with real operations, learning by doing); onboarding new staff/students to digital-rock analysis quickly; as a guided standard operating procedure that prevents skipping key steps (threshold checking, connectivity, REV, permeability estimate); and as an interactive tutorial for demos and marketing.

2. The five steps & teaching content

The five tabs are the five steps of pore analysis. Each carries 3 📖 Learn documents and one or more 🛠 Try it actions:

3. Features

• One-click synthetic sample: enter a sample size (voxels), target porosity φ and pore coarseness (blobiness) to generate a practice volume with a known porosity and publish it as a Channel. It prefers porespy (if present in the Dragonfly environment) and otherwise falls back to a numpy Gaussian-random-field generator — so you can start even with no data.
• Otsu auto-threshold: a pure-numpy Otsu (maximum between-class variance) finds the segmentation threshold and previews the porosity; tick "Pore = low intensity" (pores are usually dark in CT) and fine-tune the threshold manually.
• Pore ROI segmentation & publishing: build an ROI of the pore-phase voxels at the current threshold and publish it back into Dragonfly (getAsROIWithinRange) so you can check the boundary in 2D slices / 3D.
• Porosity calculation: φ = pore voxels / total voxels — a dimensionless ratio, independent of voxel size.
• Open/closed connectivity analysis: scipy.ndimage.label (26-connectivity) labels pore clusters, marks clusters touching a boundary face as open and fully-enclosed ones as closed, and reports total/open/closed porosity, cluster count, largest-cluster share and cluster-size distribution.
• Kozeny–Carman permeability estimate: from porosity φ and a mean grain size d, estimate k = φ³·d² / [180·(1−φ)²], converted to m² / Darcy / mD (order-of-magnitude).
• Rich bilingual teaching docs: 15 📖 Learn documents cover imaging physics, thresholding/segmentation, porosity, connectivity, REV, the pore network model, SNOW, Darcy's law, simulation methods and more — each 中文|EN-switchable, resizable and left open while you work.

4. How to use

1. Open Prototype Apps ▸ Hands-on Workshops ▸ Porosity Analysis... in Dragonfly.

2. Click 📘 Overview at the top first to read the workshop overview and see how the five steps connect.

3. Step 1 (Import): with no data, set the sample size / target porosity / coarseness and click 🧪 Create synthetic porous sample to generate and publish one; with your own data use 📂 Open Dragonfly import, then come back, click ↻ Refresh and pick it in the Image dropdown.

4. Step 2 (Segment): click 🎯 Auto threshold (Otsu) to find the threshold and preview porosity, adjust the Threshold manually if needed and confirm Pore = low intensity; then 🧩 Create pore ROI and check the boundary hugs the real pore walls in slices / 3D.

5. Step 3 (Porosity): click 📊 Compute total porosity for φ; click 🔗 Open vs closed (connectivity) to split open/closed pores and view cluster stats (only open porosity contributes to flow).

6. Step 4 (Pore Network): click 🕸 Lightweight pore stats for cluster count, open/closed fractions, largest-cluster share and size distribution; for a full pore-body/throat network, follow the prompt to the ROI to MultiROI (SNOW) plugin.

7. Step 5 (Simulation): enter a mean grain size d and click ⚗ Estimate permeability (Kozeny–Carman) for an order-of-magnitude k; for rigorous quantitative values, follow the prompt to the Permeability (OpenPNM) plugin.

8. At any step, click that tab's 📖 Learn buttons to study the concept, then return to 🛠 Try it to verify hands-on.

5. Requirements

• No venv, no download, no GPU, no admin, no internet. All actions run in-process on Dragonfly's bundled numpy/scipy.
• The action buttons run inside Dragonfly (they read Channels and publish ROIs via the object model). The teaching docs work anywhere — in a standalone test environment with no Dragonfly object model, 📖 Learn still works and 🛠 Try it reports that it must run inside Dragonfly.
• Synthetic-sample generation prefers porespy (if installed in the Dragonfly environment) and otherwise falls back to a numpy Gaussian-random-field generator; neither path needs any extra install.

6. Tips & delegation

The pore-network and simulation steps here are deliberately lightweight, in-process approximations: Step 4 gives a connectivity snapshot via connected-component labelling, and Step 5 gives an order-of-magnitude permeability via Kozeny–Carman.

• For a full pore-body/throat network extraction (coordination number, pore/throat-size distributions), use the Prototype Apps ROI to MultiROI (SNOW) plugin (porespy's SNOW watershed algorithm).
• For rigorous permeability (absolute permeability, two-phase drainage, relative-permeability curves), extract the network first then use the Permeability (OpenPNM) plugin. These heavier plugins may each need a one-time environment setup.
• Key insight: permeability k ∝ φ³ — the cube of porosity! A small porosity change is amplified cubically, so always verify the segmentation threshold rather than blindly trusting the automatic value.

This is the first project in the Hands-on Workshops category; its multi-tab StepTab + bilingual DocDialog framework is reusable to build more hands-on workshops for other domains.