PyDenseCRF

这是一个基于 Cython 的 Python 封装库，用于 Philipp Krähenbühl 的全连接条件随机场（版本 2，新页面，尚未完成）。

如果您在研究中使用此代码，请引用以下文献：

高效全连接条件随机场中的高斯边势能推断
Philipp Krähenbühl 和 Vladlen Koltun
NIPS 2011

并在脚注或参考文献中提供本仓库的链接。

安装

该包已在 PyPI 上发布，因此只需运行 pip install pydensecrf 即可安装。

如果您希望使用最新版本，可以执行以下命令进行安装：

pip install git+https://github.com/lucasb-eyer/pydensecrf.git

并忽略来自 Eigen 的所有警告。

请注意，此封装需要相对较新的 Cython 版本（至少 0.22），而 Ubuntu 14.04 自带的版本过旧。（感谢 Scott Wehrwein 指出这一点。）建议您使用 虚拟环境 并在其中安装最新版 Cython (pip install cython)，或者通过以下命令更新系统自带的 Cython 版本：

sudo apt-get remove cython
sudo pip install -U cython

Windows/VS 上的问题

由于该库需要编译 C++ 代码，因此其安装可能比纯 Python 包更为复杂。请确保已安装 Cython，或者如果遇到问题，可以尝试使用 conda 进行安装。欢迎提交改进 Windows 支持的 Pull Request。

Colab/Kaggle Kernel 上的问题

pydensecrf 在 Colab 或 Kaggle Kernel 中并未预装。直接运行 pip install pydensecrf 会导致构建失败。对于 Colab/Kaggle Kernel，请按照以下步骤操作：

pip install -U cython
pip install git+https://github.com/lucasb-eyer/pydensecrf.git

使用方法

对于图像，使用此库最简单的方式是使用 DenseCRF2D 类：

import numpy as np
import pydensecrf.densecrf as dcrf

d = dcrf.DenseCRF2D(640, 480, 5)  # 宽度、高度、类别数

一元势能

随后，您可以按如下方式设置固定的一元势能：

U = np.array(...)     # 以某种方式获取一元势能。
print(U.shape)        # -> (5, 480, 640)
print(U.dtype)        # -> dtype('float32')
U = U.reshape((5,-1)) # 需要展平。
d.setUnaryEnergy(U)

# 或者：d.setUnary(ConstUnary(U))

请记住，U 应为负对数概率，因此如果您使用的是概率值 py，别忘了将其转换为 U = -np.log(py)。

要求一元势能进行 reshape 是一个 API 设计上的小瑕疵，我希望未来能够修复，但目前尚不清楚如何在不引入对 NumPy 显式依赖的情况下实现这一点。

注意，在 reshape 之前，nlabels 维度位于数组的第一位；如果未处于该位置，您可能需要先将其移动到第一位再进行 reshape，例如：

print(U.shape)  # -> (480, 640, 5)
U = U.transpose(2, 0, 1).reshape((5,-1))

获取一元势能的方法

获取一元势能通常有两种常见方式：

1. 由人工标注或其他处理生成的硬标签。这种情况可以使用 from pydensecrf.utils import unary_from_labels。

2. 由深度网络的 softmax 输出等计算得到的概率分布。对此，可以使用 from pydensecrf.utils import unary_from_softmax。

有关这两种方法的具体用法，请参阅其文档字符串，或查看 示例。

成对势能

在二维情况下，有两个实用方法可用于添加最常见的成对势能：

# 添加与颜色无关的项，特征仅包括位置信息。
d.addPairwiseGaussian(sxy=(3,3), compat=3, kernel=dcrf.DIAG_KERNEL, normalization=dcrf.NORMALIZE_SYMMETRIC)

# 添加与颜色相关的项，即特征包括 (x,y,r,g,b)。
# im 是图像数组，例如 im.dtype == np.uint8 且 im.shape == (640,480,3)
d.addPairwiseBilateral(sxy=(80,80), srgb=(13,13,13), rgbim=im, compat=10, kernel=dcrf.DIAG_KERNEL, normalization=dcrf.NORMALIZE_SYMMETRIC)

这两种方法都提供了简写和默认参数，使得最常见的用法可以简化为：

d.addPairwiseGaussian(sxy=3, compat=3)
d.addPairwiseBilateral(sxy=80, srgb=13, rgbim=im, compat=10)

这些参数与论文中的对应关系如下：在“Gaussian”情况下，sxy 对应于 $\theta_{\gamma}$；而在“Bilateral”情况下，sxy 和 srgb 分别对应于 $\theta_{\alpha}$ 和 $\theta_{\beta}$。这些名称分别是“x/y 标准差”和“RGB 标准差”的缩写，公式如下：

非 RGB 双边势能

需要注意的是，addPairwiseBilateral 仅适用于 RGB 图像，即具有三个通道的图像。如果您的数据类型与此不同，则需要使用 utils.create_pairwise_bilateral 来计算自定义的成对能量。详细信息请参阅 通用非二维情况。

示例文件夹中提供了一个关于 非 RGB 数据处理的良好示例，以笔记本形式呈现。

兼容性

compat 参数可以是以下几种类型：

• 数字：此时使用的是 Potts 兼容性。
• 一维数组：此时使用的是对角兼容性。
• 二维数组：此时使用的是矩阵兼容性。

这些表示标签之间的兼容性 µ(xi, xj)，其参数可以通过 学习 来确定。例如，它们可以表明将“鸟”像素误判为“天空”并不如将“猫”误判为“天空”那样严重。这些数组的形状应为 nlabels 或 (nlabels,nlabels)，数据类型为 float32。

核函数

kernel 参数的取值包括：

• CONST_KERNEL
• DIAG_KERNEL（默认）
• FULL_KERNEL

这决定了核的精度矩阵 Λ(m)，其参数同样可以通过学习来优化。这些参数反映了特征类型之间的相关性，默认值表示无相关性。再次强调，这些参数也可以通过 学习 来确定。

归一化

normalization 参数的取值包括：

• NO_NORMALIZATION
• NORMALIZE_BEFORE
• NORMALIZE_AFTER
• NORMALIZE_SYMMETRIC（默认）

核权重

到目前为止，我还没有找到设置核权重 w(m) 的方法。根据论文，w(2) 被设为 1，而 w(1) 则通过交叉验证确定，但并未明确说明具体值。在查看 Philip 的代码（包含在 pydensecrf/densecrf 中）时，我也没有发现显式的权重设置，因此我猜测这些权重被硬编码为 1。如果有人知道其他情况，请提交一个问题，或者更好的是，提交一个拉取请求。

更新：用户 @waldol1 在 这个问题 中提出了一种想法，欢迎大家尝试！

推理

使用 5 次迭代进行推理的最简单方法就是直接调用：

Q = d.inference(5)

然后，最大后验预测结果为：

map = np.argmax(Q, axis=0).reshape((640,480))

如果你对类别概率 Q 感兴趣，你会发现 Q 是一个封装的 Eigen 矩阵。该项目的 Eigen 封装实现了缓冲区接口，可以像下面这样简单地转换为 NumPy 数组：

proba = np.array(Q)

逐步推理

如果你出于某种原因想要手动运行推理循环，可以这样做：

Q, tmp1, tmp2 = d.startInference()
for i in range(5):
    print("KL散度在第 {} 次迭代时为: {}".format(i, d.klDivergence(Q)))
    d.stepInference(Q, tmp1, tmp2)

通用非二维

DenseCRF 类可用于通用（非二维）密集条件随机场。其用法与上述完全相同，只是缺少专门针对二维的成对势能函数 addPairwiseGaussian 和 addPairwiseBilateral。

相反，你需要使用通用的 addPairwiseEnergy 方法，如下所示：

d = dcrf.DenseCRF(100, 5)  # 点数，标签数

feats = np.array(...)  # 从某处获取成对特征。
print(feats.shape)     # -> (7, 100) = (特征维度，点数)
print(feats.dtype)     # -> dtype('float32')

dcrf.addPairwiseEnergy(feats)

此外，你还可以像在二维高斯和双边情况下一样，传递 compatibility、kernel 和 normalization 参数。

势能将按照 w*exp(-0.5 * |f_i - f_j|^2) 计算。

N 维的成对势能

用户 @markusnagel 编写了几个 NumPy 函数，将经典的两种二维图像成对势能（高斯和双边）推广到任意维度：create_pairwise_gaussian 和 create_pairwise_bilateral。你可以通过 from pydensecrf.utils import create_pairwise_gaussian 来访问它们，并查看其文档字符串以了解如何使用。

学习

学习功能尚未完全封装。如果你需要它，请联系我们，或者更好的是，自行封装并提交一个拉取请求！

这里有一个入门提示：问题#24。我们需要封装梯度以及参数的获取和设置。之后，我们还需要对这些数据做进一步处理，很可能需要调用 optimization.cpp 中的 minimizeLBFGS。只需按照 原始代码 中包含的学习示例操作，应该会相对简单。

常见问题

导入时出现“未定义符号”错误

如果你在导入 pydensecrf 时遇到关于某些未定义符号的错误（例如 .../pydensecrf/densecrf.so: undefined symbol: _ZTINSt8ios_base7failureB5cxx11E），很可能是无意中混用了不同的编译器或工具链。可以使用 ldd 等工具来检查具体情况。如果你使用的是 Anaconda，运行 conda install libgcc 可能是一个解决方案。

ValueError: 缓冲区数据类型不匹配，期望 'float' 却得到 'double'

这是一种相当常见的用户错误。它的意思就是字面意思：你传递了一个 double 类型的数据，但函数期望的是 float 类型。解决办法是，例如，调用 d.setUnaryEnergy(U.astype(np.float32)) 而不是直接调用 d.setUnaryEnergy(U)，或者在代码一开始就使用 float32 数据类型。

我的结果全都像 MS Paint 的喷枪工具 一样像素化！

你在某个地方搞错了形状重塑，把类别/标签维度当成了空间维度。这是你对 NumPy 内存布局的理解出现了偏差，而 PyDenseCRF 无法检测或帮助解决这个问题。

这种错误通常发生在单体势能部分，详见 README 中该部分的注释。

维护

以下是一些面向维护者的发布新版本的说明。（主要是给自己看的。）

# 去 setup.py 中将版本号递增
> python setup.py build_ext
> python setup.py sdist
> twine upload dist/pydensecrf-VERSION_NUM.tar.gz

就这样。将来可以在 TravisCI 上实现自动化部署，但现在还不值得。届时，也可以考虑 创建 "manylinux" 轮子，那会是个不错的想法。

测试

感谢 @MarvinTeichmann，我们现在有了完善的测试。安装包后运行 py.test 即可。也许还有更好的运行方式，但我们俩都不太清楚 :smile:

PyDenseCRF 快速上手指南

PyDenseCRF 是 Philipp Krähenbühl 提出的全连接条件随机场（Fully-Connected CRFs）的 Python 封装（基于 Cython），常用于图像分割任务的后处理，以优化边缘细节。

环境准备

• 系统要求：支持 Linux、macOS 和 Windows。
  • 注意：Windows 用户需确保已安装支持 C++ 编译的工具链（如 Visual Studio Build Tools），或直接使用 Conda 安装。
• 前置依赖：
  • Python 3.x
  • NumPy
  • Cython（版本需 >= 0.22，旧版 Ubuntu 自带版本过低，建议升级）
  • C++ 编译器（用于编译底层 C++ 代码）

安装步骤

方法一：通过 PyPI 安装（推荐）

最简便的方式是使用 pip 直接安装预编译包或源码包：

pip install pydensecrf

国内加速建议：如果下载速度慢，可使用清华或阿里镜像源：

pip install pydensecrf -i https://pypi.tuna.tsinghua.edu.cn/simple

方法二：安装最新开发版

如需获取最新功能，可从 GitHub 源码安装：

pip install git+https://github.com/lucasb-eyer/pydensecrf.git

特殊环境安装

1. Windows 用户 若 pip 安装失败（通常因缺少编译器），建议使用 Conda：

conda install -c conda-forge pydensecrf

2. Colab / Kaggle 环境 这些环境未预装该库且直接 pip 安装可能报错，请按顺序执行以下命令：

pip install -U cython
pip install git+https://github.com/lucasb-eyer/pydensecrf.git

基本使用

以下是针对二维图像的最简使用流程，包含初始化、设置势能、添加成对项及推理。

1. 初始化与一元势能 (Unary Potential)

一元势能通常来自深度学习模型的输出（如 Softmax 概率）。注意：CRF 需要负对数概率作为输入，且数据维度需调整为 (nlabels, -1)。

import numpy as np
import pydensecrf.densecrf as dcrf
from pydensecrf.utils import unary_from_softmax

# 假设 unaries 是模型输出的概率图，形状为 (H, W, nlabels)
# 例如：unaries = softmax_output_from_network

# 转换为 CRF 所需的一元势能 (负对数概率) 并展平
# 工具函数会自动处理 transpose 和 -log 操作
U = unary_from_softmax(unaries)
U = U.reshape((U.shape[0], -1))

# 初始化 CRF: 宽，高，标签数量
d = dcrf.DenseCRF2D(unaries.shape[1], unaries.shape[0], unaries.shape[2])
d.setUnaryEnergy(U)

2. 添加成对势能 (Pairwise Potentials)

添加两项常见的成对势能以平滑结果并保留边缘：

1. 颜色无关项 (Gaussian)：仅基于像素位置。
2. 颜色相关项 (Bilateral)：基于像素位置和颜色相似度。

# im 为原始 RGB 图像数组，形状 (H, W, 3), dtype=uint8
im = original_image 

# 添加高斯核 (位置平滑)
d.addPairwiseGaussian(sxy=3, compat=3)

# 添加双边核 (颜色保持边缘)
d.addPairwiseBilateral(sxy=80, srgb=13, rgbim=im, compat=10)

3. 执行推理 (Inference)

运行迭代推理并获取最终的分类结果。

# 执行 5 次迭代推理
Q = d.inference(5)

# 获取最大后验概率 (MAP) 预测结果
# Q 的形状为 (nlabels, H*W)，需取最大值索引并重塑回图像尺寸
map_prediction = np.argmax(Q, axis=0).reshape((unaries.shape[0], unaries.shape[1]))

# 如果需要每个类别的概率分布，可转换为 numpy 数组
probabilities = np.array(Q)