PoreSpy孔隙网络分析实战指南：从图像到模拟的完整工作流

多孔介质广泛存在于能源、环境、材料等领域，其微观结构直接影响流体传输、反应效率等关键性能。传统分析方法面临算法开发复杂、专业精度不足和全流程整合困难等挑战。PoreSpy作为专注于多孔介质图像分析的Python库，通过模块化设计和专业算法，为科研人员提供了从虚拟样品生成到流体模拟的一站式解决方案。本文将系统介绍PoreSpy的核心功能与实战应用，帮助读者快速掌握多孔介质分析的关键技术。

多孔介质分析的技术挑战与PoreSpy解决方案

多孔材料研究中，科研人员常面临三大核心挑战：首先，传统图像处理工具难以准确识别复杂孔隙结构，导致分析结果偏差；其次，从图像到模拟的全流程涉及多个工具，数据转换繁琐；最后，大尺寸3D图像分析对计算资源要求高，普通方法效率低下。

PoreSpy通过三大创新解决上述痛点：

• 专业算法库：针对多孔介质优化的孔隙识别与网络提取算法，如基于分水岭的Snow2分割技术
• 全流程整合：从图像生成、预处理到模拟验证的完整工作流，数据格式无缝衔接
• 高性能计算：支持分块处理和并行计算，轻松应对GB级3D图像分析

图1：PoreSpy分析的起点——多孔介质二值化图像（黄色表示孔隙相，深紫色表示固体骨架），该图像是后续所有定量分析的基础数据

高效安装与环境配置策略

系统要求与依赖项

PoreSpy支持Python 3.11-3.13版本，核心依赖包括NumPy、SciPy、Matplotlib和Scikit-image。推荐使用uv包管理器进行安装，以获得更快的依赖解析和安装速度。

四步安装流程

1. 安装uv工具
   访问uv官方网站下载对应操作系统的安装包，或通过命令行安装：

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. 创建虚拟环境
   在项目目录中创建隔离的Python环境：

   uv venv --python 3.12
   source .venv/bin/activate  # Linux/macOS
   .venv\Scripts\activate     # Windows
   

3. 安装稳定版PoreSpy
   通过PyPI安装最新稳定版：

   uv pip install porespy
   

4. 开发版安装（可选）
   如需体验最新功能，克隆仓库后进行 editable安装：

   git clone https://gitcode.com/gh_mirrors/po/porespy
   cd porespy
   uv pip install -e .
   

💡 技巧提示：安装过程中若遇到依赖冲突，可使用uv pip install --no-cache-dir porespy强制重新解析依赖关系。详细安装说明参见官方文档：docs/installation.rst

核心模块应用指南

PoreSpy采用模块化设计，各功能模块专注于特定分析任务。以下介绍三个核心模块的使用方法与应用场景。

1. 虚拟样品生成模块（generators）

该模块提供多种算法生成具有可控参数的虚拟多孔介质，避免了实验样品制备的成本与时间消耗。核心函数包括：

• blobs：生成类似岩石的多孔结构，通过porosity参数控制孔隙率
• overlapping_spheres：生成球体堆积结构，可控制球体大小分布
• fractal_noise：生成具有分形特征的多孔介质，模拟天然岩石的自相似结构

import porespy as ps
import matplotlib.pyplot as plt

# 生成100×100×100的多孔结构
im = ps.generators.blobs(
    shape=[100, 100, 100], 
    porosity=0.3,  # 目标孔隙率
    blobiness=2.5  # 控制孔隙结构的连通性（值越大结构越连续）
)

# 显示2D切片
plt.figure(figsize=(8, 8))
plt.imshow(im[:, :, 50], cmap='gray')
plt.title('2D Slice of Generated Porous Medium')
plt.axis('off')
plt.show()

2. 孔隙网络提取模块（networks）

该模块将二值化图像转换为具有拓扑结构的孔隙网络模型，是连接结构分析与流体模拟的关键环节。核心算法实现于：src/porespy/networks/_snow2.py

# 对生成的图像进行孔隙网络提取
snow_output = ps.networks.snow2(
    im,
    voxel_size=10,  # 体素尺寸，单位：微米
    boundary_faces=['front', 'back', 'left', 'right', 'top', 'bottom']
)

# 提取孔隙和喉道属性
pore_diameters = snow_output['pore.diameter']
throat_diameters = snow_output['throat.diameter']

print(f"检测到 {len(pore_diameters)} 个孔隙，平均直径：{pore_diameters.mean():.2f} μm")
print(f"检测到 {len(throat_diameters)} 个喉道，平均直径：{throat_diameters.mean():.2f} μm")

图2：孔隙网络提取结果可视化，不同颜色代表不同孔隙区域，颜色深度表示孔隙大小

3. 流体模拟模块（simulations）

该模块基于孔隙网络模型模拟多相流体行为，可预测毛管压力曲线、相对渗透率等关键岩石物理参数。

# 进行排水过程模拟
drainage_results = ps.simulations.drainage(
    network=snow_output,
    invasion_sequence='largest_first',  # 按孔隙大小排序入侵
    capillary_number=1e-5  # 控制黏性力与毛管力比值
)

# 提取毛管压力-饱和度曲线
pc_curve = drainage_results['pc']
saturation = drainage_results['saturation']

# 绘制毛管压力曲线
plt.figure(figsize=(10, 6))
plt.plot(saturation, pc_curve, 'bo-')
plt.xlabel('Saturation')
plt.ylabel('Capillary Pressure (Pa)')
plt.title('Capillary Pressure-Saturation Curve')
plt.grid(True)
plt.show()

完整业务场景解决方案

场景一：岩石孔隙结构表征

问题：需要从CT扫描图像中提取孔隙大小分布、连通性等关键参数，评估储层岩石的储集性能。

解决方案：

1. 图像预处理：使用filters.fill_closed_pores修复图像缺陷
2. 孔隙识别：应用filters.snow_partitioning标记独立孔隙区域
3. 参数计算：通过metrics.regionprops_3D获取孔隙形态参数
4. 结果可视化：利用visualization.show_3D展示孔隙空间分布

# 1. 加载并预处理图像
im = ps.io.imread('rock_sample.tif')
im = ps.filters.fill_closed_pores(im)

# 2. 孔隙区域标记
labeled = ps.filters.snow_partitioning(im)

# 3. 计算孔隙属性
props = ps.metrics.regionprops_3D(labeled)

# 4. 提取并可视化孔隙大小分布
pore_volumes = [prop.volume for prop in props]
plt.figure(figsize=(10, 6))
plt.hist(pore_volumes, bins=30, edgecolor='black')
plt.xlabel('Pore Volume (voxels)')
plt.ylabel('Count')
plt.title('Pore Size Distribution')
plt.grid(True, alpha=0.3)
plt.show()

图4：孔隙-骨架空间相关性分析结果，反映多孔介质结构的空间分布规律，曲线下降越快表明结构非均质性越强

场景二：多相流体流动模拟

问题：预测不同润湿性条件下的两相流驱替效率，优化油气田开发方案。

解决方案：

1. 网络提取：从岩心图像构建孔隙网络模型
2. 润湿性设置：通过接触角参数模拟不同润湿性条件
3. 驱替模拟：使用simulations.imbibition模拟水驱油过程
4. 结果分析：比较不同润湿性下的采收率曲线

# 1. 从图像提取孔隙网络（代码见场景一）
# ...

# 2. 设置不同润湿性条件
contact_angles = [30, 60, 90, 120]  # 从强水湿到强油湿
recovery = []

# 3. 模拟不同润湿性下的吸吮过程
for theta in contact_angles:
    imbib_results = ps.simulations.imbibition(
        network=snow_output,
        contact_angle=theta,
        capillary_number=1e-6
    )
    recovery.append(imbib_results['saturation'][-1])  # 最终采收率

# 4. 绘制润湿性-采收率关系
plt.figure(figsize=(8, 5))
plt.plot(contact_angles, recovery, 'ro-')
plt.xlabel('Contact Angle (degrees)')
plt.ylabel('Oil Recovery Factor')
plt.title('Effect of Wettability on Oil Recovery')
plt.grid(True, alpha=0.3)
plt.show()

高性能计算与进阶技巧

大图像处理策略

对于GB级3D图像，直接加载会导致内存溢出。PoreSpy提供分块处理功能，通过filters.chunked_func实现并行计算：

# 分块处理大图像
chunked_result = ps.filters.chunked_func(
    func=ps.filters.snow_partitioning,
    im=large_image,
    chunk_size=[256, 256, 256],  # 块大小
    overlap=10,  # 块间重叠 voxels
    num_workers=4  # 并行进程数
)

自定义算法扩展

PoreSpy支持自定义插件扩展，通过继承PoreSpyPlugin类实现特定分析需求：

from porespy.plugins import PoreSpyPlugin

class MyCustomAnalyzer(PoreSpyPlugin):
    def analyze(self, image):
        # 实现自定义分析算法
        result = self._custom_process(image)
        return result

# 注册插件
ps.plugins.register(MyCustomAnalyzer)

# 使用自定义分析器
analyzer = ps.plugins.MyCustomAnalyzer()
result = analyzer.analyze(im)

🔍 性能优化提示：对于大规模3D图像分析，建议使用具有CUDA支持的GPU，并安装CuPy库加速数组运算。相关优化代码可参考：src/porespy/simulations/_ibip_gpu.py

学习资源与技术支持

官方文档与示例

• 快速入门：examples/general/getting_started.ipynb
• API参考：docs/modules/index.rst
• 案例库：docs/_examples/包含各模块详细使用示例

进阶学习资源

1. 核心算法实现：src/porespy/filters/_snows.py
2. 并行计算模块：src/porespy/networks/_getnet_para.py
3. 单元测试用例：test/unit/test_filters.py提供标准使用范例

社区支持

PoreSpy通过GitHub Issues接收bug报告和功能请求，用户可通过项目仓库参与讨论和贡献代码。定期查看VERSIONING.md了解最新功能更新和版本变化。

图6：毛管压力侵入曲线，反映不同尺寸孔隙的体积占比，是评估储层岩石孔喉分布的关键曲线

通过本文介绍的PoreSpy核心功能与实战技巧，读者可以快速构建从多孔介质图像到流体模拟的完整分析流程。无论是学术研究还是工业应用，PoreSpy都能显著提升多孔材料表征的效率与精度，助力发现材料微观结构与宏观性能之间的内在联系。