像素自适应卷积神经网络

项目页面 | 论文 | 视频

像素自适应卷积神经网络
苏航、瓦伦·詹帕尼、孙德清、奥拉齐奥·加洛、埃里克·勒恩德-米勒以及扬·考茨。
CVPR 2019。

许可证

版权所有 © 2019 NVIDIA Corporation。保留所有权利。 根据 CC BY-NC-SA 4.0 许可证授权（https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode）。

安装

• 确保您已安装 Python>=3.5（我们建议使用 Conda 环境）。
• 将项目目录添加到您的 Python 路径中。
• 安装依赖项：
  • PyTorch v0.4-1.1（包括 torchvision）并支持 CUDA：请参阅 PyTorch 安装说明。
  • 其他库：

    pip install -r requirements.txt
    

• （可选）验证安装：

  python -m unittest 
  

层目录

我们实现了 5 种类型的 PAC 层（作为 PyTorch Module）：

• PacConv2d：标准变体
• PacConvTranspose2d：用于上采样的转置（分数步长）变体
• PacPool2d：池化变体
• PacCRF：条件随机场的均场推断
• PacCRFLoose：条件随机场的均场推断，其中均场步骤不共享权重

关于每种层的更多详细信息如下。

PacConv2d

PacConv2d 是 nn.Conv2d 的 PAC 对应版本。它接受大多数标准的 nn.Conv2d 参数（包括 in_channels、out_channels、kernel_size、bias、stride、padding、dilation，但不包括 groups 和 padding_mode），并且我们确保在使用相同参数时，PacConv2d 和 nn.Conv2d 具有完全相同的输出尺寸。 此外，还有一些可选参数：

    参数（除 Conv2d 的参数外）：
        kernel_type（str）：'gaussian' | 'inv_{alpha}_{lambda}[_asym][_fixed]'。默认值：'gaussian'
        smooth_kernel_type（str）：'none' | 'gaussian' | 'average_{sz}' | 'full_{sz}'。默认值：'none'
        normalize_kernel（bool）：默认值：False
        shared_filters（bool）：默认值：False
        filler（str）：'uniform'。默认值：'uniform'

    注意：
        - kernel_size 只能为奇数
        - padding 不得大于 :math:`dilation * (kernel_size - 1) / 2`

当用于构建计算图时，该层接受两个输入张量并生成一个输出张量：

in_ch, out_ch, g_ch = 16, 32, 8         # 输入、输出和引导通道的数量
f, b, h, w = 5, 2, 64, 64               # 滤波器大小、批次大小、输入高度和宽度
input = torch.rand(b, in_ch, h, w)
guide = torch.rand(b, g_ch, h, w)       # 引导特征（见论文公式3中的'f'）

conv = nn.Conv2d(in_ch, out_ch, f)
out_conv = conv(input)                  # 标准空间卷积

pacconv = PacConv2d(in_ch, out_ch, f)   
out_pac = pacconv(input, guide)         # PAC 
out_pac = pacconv(input, None, guide_k) # 替代接口
                                        # guide_k 是预先计算的'K'（见论文公式3）
                                        # 形状为[b, g_ch, f, f, h, w]。可以使用 packernel2d 来创建它。

请使用 pacconv2d（结合 packernel2d）以获得其功能接口。

PacConvTranspose2d

PacConvTranspose2d 是 nn.ConvTranspose2d 的 PAC 对应版本。它接受大多数标准的 nn.ConvTranspose2d 参数（包括 in_channels、out_channels、kernel_size、bias、stride、padding、output_padding、dilation，但不包括 groups 和 padding_mode），并且我们确保在使用相同参数时，PacConvTranspose2d 和 nn.ConvTranspose2d 具有完全相同的输出尺寸。 此外，还有一些可选参数：

    参数（除 ConvTranspose2d 的参数外）：
        kernel_type（str）：'gaussian' | 'inv_{alpha}_{lambda}[_asym][_fixed]'。默认值：'gaussian'
        smooth_kernel_type（str）：'none' | 'gaussian' | 'average_{sz}' | 'full_{sz}'。默认值：'none'
        normalize_kernel（bool）：默认值：False
        shared_filters（bool）：默认值：False
        filler（str）：'uniform' | 'linear'。默认值：'uniform'

    注意：
        - kernel_size 只能为奇数
        - padding 不得大于 :math:`dilation * (kernel_size - 1) / 2`

与 PacConv2d 类似，PacConvTranspose2d 也提供两种使用方式：

in_ch, out_ch, g_ch = 16, 32, 8             # 输入、输出和引导通道的数量
f, b, h, w, oh, ow = 5, 2, 8, 8, 16, 16     # 滤波器大小、批次大小、输入高度和宽度
input = torch.rand(b, in_ch, h, w)
guide = torch.rand(b, g_ch, oh, ow)         # 引导特征，注意它需要与输出的空间尺寸匹配

convt = nn.ConvTranspose2d(in_ch, out_ch，f，stride=2，padding=2，output_padding=1)
out_convt = convt(input)                    # 标准转置卷积

pacconvt = PacConvTranspose2d(in_ch，out_ch，f，stride=2，padding=2，output_padding=1)   
out_pact = pacconvt(input，guide)           # PAC 
out_pact = pacconvt(input，None，guide_k)   # 替代接口
                                            # guide_k 是预先计算的'K' 
                                            # 形状为[b，g_ch, f，f，oh，ow]。
                                            # 可以使用 packernel2d 来创建它。

请使用 pacconv_transpose2d（结合 packernel2d）以获得其功能接口。

PacPool2d

PacPool2d 是 nn.AvgPool2d 的 PAC 对应版本。它接受大多数标准的 nn.AvgPool2d 参数（包括 kernel_size、stride、padding、dilation，但不包括 ceil_mode 和 count_include_pad），并且我们确保在使用相同参数时，PacPool2d 和 nn.AvgPool2d 具有完全相同的输出尺寸。 此外，还有一些可选参数：

    参数：
        kernel_size、stride、padding、dilation
        kernel_type（str）：'gaussian' | 'inv_{alpha}_{lambda}[_asym][_fixed]'。默认值：'gaussian'
        smooth_kernel_type（str）：'none' | 'gaussian' | 'average_{sz}' | 'full_{sz}'。默认值：'none'
        channel_wise（bool）：默认值：False
        normalize_kernel（bool）：默认值：False
        out_channels（int）：对于 channel_wise 的 'inv_*'（非固定）核，必须指定。默认值：-1

    注意：
        - kernel_size 只能为奇数
        - padding 不得大于 :math:`dilation * (kernel_size - 1) / 2`

与 PacConv2d 类似，PacPool2d 也提供两种使用方式：

in_ch, g_ch = 16, 8                     # 输入和引导特征的通道数
stride, f, b, h, w = 5, 2, 64, 64       # 步幅、卷积核大小、批次大小、输入高度和宽度
input = torch.rand(b, in_ch, h, w)
guide = torch.rand(b, g_ch, h, w)       # 引导特征

pool = nn.AvgPool2d(f, stride)
out_pool = pool(input)                  # 标准的空间卷积

pacpool = PacPool2d(f, stride)   
out_pac = pacpool(input, guide)         # PAC 
out_pac = pacpool(input, None, guide_k) # 另一种接口
                                        # guide_k 是预先计算好的 'K'
                                        # 形状为 [b, g_ch, f, f, h, w]。可以使用 packernel2d 来创建它。

请使用 pacpool2d（结合 packernel2d）的功能性接口。

PacCRF 和 PacCRFLoose

这些层提供了一种便捷的方式，可以在密集预测网络的末尾添加 CRF 组件。它们在底层执行近似的均值场推理。可用的参数包括：

    Args:
        channels (int): 类别数量。
        num_steps (int): 均值场更新的步数。
        final_output (str): 'log_softmax' | 'softmax' | 'log_Q'。默认值：'log_Q'
        perturbed_init (bool): 是否对初始化进行扰动。默认值：True
        native_impl (bool): 默认值：False
        fixed_weighting (bool): 是否对一元项/二元项使用固定权重。默认值：False
        unary_weight (float): 默认值：1.0
        pairwise_kernels (dict 或 list): 二元核，详情请参见 add_pairwise_kernel()。默认值：None

使用示例：

# 创建一个针对 21 类、使用 5 步均值场推理的 CRF 层
crf = PacCRF(21, num_steps=5, unary_weight=1.0)

# 添加一个与一元项权重相等的二元项
crf.add_pairwise_kernel(kernel_size=5, dilation=1, blur=1, compat_type='4d', pairwise_weight=1.0)

# 提供了一个便捷函数，用于根据像素颜色和位置创建二元特征
edge_features = [paccrf.create_YXRGB(im, yx_scale=100.0, rgb_scale=30.0)] 
output = crf(unary, edge_features)

# 注意，我们这里使用了常量值作为 unary_weight、pairwise_weight、yx_scale 和 rgb_scale，但它们也可以是张量，并通过反向传播进行学习。

实验

联合上采样

NYU Depth V2 上的联合深度上采样

• 训练/测试划分由 Li 等 提供

• 使用我们预训练的模型之一进行测试：

  python -m task_jointUpsampling.main --load-weights weights_depth/x8_pac_weights_epoch_5000.pth \
                                      --download \
                                      --factor 8 \
                                      --model PacJointUpsample \
                                      --dataset NYUDepthV2 \
                                      --data-root data/nyu
  

  	4x	8x	16x
  双线性插值	RMSE: 5.43	RMSE: 8.36	RMSE: 12.90
  PacJointUpsample	RMSE: 2.39 | 下载	RMSE: 4.59 | 下载	RMSE: 8.09 | 下载
  PacJointUpsampleLite	RMSE: 2.55 | 下载	RMSE: 4.82 | 下载	RMSE: 8.52 | 下载
  DJIF	RMSE: 2.64 | 下载	RMSE: 5.15 | 下载	RMSE: 9.39 | 下载

• 从头开始训练：

  python -m task_jointUpsampling.main --factor 8 \
                                      --data-root data/nyu \
                                      --exp-root exp/nyu \
                                      --download \
                                      --dataset NYUDepthV2 \
                                      --epochs 5000 \
                                      --lr-steps 3500 4500
  

  有关完整的命令行选项，请参阅 python -m task_jointUpsampling.main -h。

Sintel 上的联合光流上采样

• 训练/验证划分（1 - 训练，2 - 验证）在 meta/Sintel_train_val.txt 中给出（原始来源)：

  • 验证集：133 对
    • ambush_6（全部 19 对）
    • bamboo_2（最后 25 对）
    • cave_4（最后 25 对）
    • market_6（全部 39 对）
    • temple_2（最后 25 对）
  • 训练集：剩余的 908 对

• 使用我们预训练的模型之一进行测试：

  python -m task_jointUpsampling.main --load-weights weights_flow/x8_pac_weights_epoch_5000.pth \
                                      --download \
                                      --factor 8 \
                                      --model PacJointUpsample \
                                      --dataset Sintel \
                                      --data-root data/sintel
  

  	4x	8x	16x
  双线性插值	EPE: 0.4650	EPE: 0.9011	EPE: 1.6281
  PacJointUpsample	EPE: 0.1042 | 下载	EPE: 0.2558 | 下载	EPE: 0.5921 | 下载
  DJIF	EPE: 0.1760 | 下载	EPE: 0.4382 | 下载	EPE: 1.0422 | 下载

• 从头开始训练：

  python -m task_jointUpsampling.main --factor 8 \
                                      --data-root data/sintel \
                                      --exp-root exp/sintel \
                                      --download \
                                      --dataset Sintel \
                                      --epochs 5000 \
                                      --lr-steps 3500 4500
  

  有关完整的命令行选项列表，请参阅 python -m task_jointUpsampling.main -h。

语义分割

• 使用预训练模型之一进行测试：

  python -m task_semanticSegmentation.main --data-root data/voc \ 
                                           --exp-root exp/voc \
                                           --download \
                                           --load-weights fcn8s_from_caffe.pth \
                                           --model fcn8s \
                                           --test-split val11_sbd \
                                           --test-crop -1
  

  	miou (val / test)	模型名称	权重
  主干网络 (FCN8s)	65.51% / 67.20%	fcn8s	下载
  PacCRF	68.90% / 69.82%	fcn8s_crfi5p4d5641p4d5161	下载
  PacCRF-32	68.52% / 69.41%	fcn8s_crfi5p4d5321	下载
  PacFCN（热插拔）	67.44% / 69.18%	fcn8spac	下载
  PacFCN+PacCRF	69.87% / 71.34%	fcn8spac_crfi5p4d5641p4d5161	下载

  请注意，最后两个模型需要使用参数 --test-crop 512。

• 生成预测

  使用 --eval pred 模式来保存预测结果，而不是报告分数。预测结果将保存在 exp-root/outputs_*_pred 目录下，可用于 VOC 评估服务器：

  python -m task_semanticSegmentation.main \
  --data-root data/voc \
  --exp-root exp/voc \
  --load-weights fcn8s_paccrf_epoch_30.pth \
  --test-crop -1 \
  --test-split test \
  --eval pred \
  --model fcn8s_crfi5p4d5641p4d5161 
  
  cd exp/voc
  mkdir -p results/VOC2012/Segmentation
  mv outputs_test_pred results/VOC2012/Segmentation/comp6_test_cls
  tar zcf results_fcn8s_crf.tgz results
  

  请注意，由于 VOC 的测试集没有公开的下载链接，因此在使用测试集时，需要从官方网站手动下载数据文件。只需将下载的 VOC2012test.tar 文件放置在数据根目录下并解压即可。

• 训练模型

  以下以 PacCRF 的两阶段训练为例：

  # 第一阶段：仅训练 CRF，冻结主干网络
  python -m task_semanticSegmentation.main \
  --data-root data/voc \
  --exp-root exp/voc/crf_only \
  --load-weights-backbone fcn8s_from_caffe.pth \
  --train-split train11 \
  --test-split val11_sbd \
  --train-crop 449 \
  --test-crop -1 \
  --model fcn8sfrozen_crfi5p4d5641p4d5161 \
  --epochs 40 \
  --lr 0.001 \
  --lr-steps 20
  
  # 第二阶段：联合训练 CRF 和主干网络
  python -m task_semanticSegmentation.main \
  --data-root data/voc \
  --exp-root exp/voc/joint \
  --load-weights-backbone fcn8s_from_caffe.pth \
  --load-weights exp/voc/crf_only/weights_epoch_40.pth \
  --train-split train11 \
  --test-split val11_sbd \
  --train-crop 449 \
  --test-crop -1 \
  --model fcn8s_crfi5lp4d5641p4d5161 \
  --epochs 30 \
  --lr 0.0000001 \
  --lr-steps 20
  

  有关完整的命令行选项列表，请参阅 python -m task_semanticSegmentation.main -h。

引用

如果您在研究中使用了此代码，请考虑引用我们的论文：

@inproceedings{su2019pixel,
  author    = {苏航、瓦伦·詹帕尼、孙德清、奥拉齐奥·加洛、埃里克·勒恩德-米勒、扬·考茨},
  title     = {像素自适应卷积神经网络},
  booktitle = {IEEE计算机视觉与模式识别会议（CVPR）论文集},
  year      = {2019}
}

PacNet 快速上手指南

PacNet (Pixel-Adaptive Convolutional Neural Networks) 是一个基于 PyTorch 的开源项目，实现了像素自适应卷积网络。该工具通过引入引导特征（Guidance Feature），使卷积核能够根据图像内容动态调整，广泛应用于联合上采样、深度估计等密集预测任务。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux / macOS / Windows
• Python 版本: >= 3.5 (推荐使用 Conda 虚拟环境)
• 深度学习框架: PyTorch v0.4 - 1.1 (必须包含 CUDA 支持)
  • 注意：由于项目较老，建议创建独立的旧版 PyTorch 环境以避免兼容性问题。
• 其他依赖: torchvision 及 requirements.txt 中列出的库。

国内加速建议： 安装 PyTorch 时，推荐使用清华或中科大镜像源。例如安装 PyTorch 1.1 (CUDA 10.0)：

pip install torch==1.1.0 torchvision==0.3.0 -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

1. 克隆项目并配置路径 将项目目录添加到您的 Python 路径中，以便导入模块。

   git clone https://github.com/NVlabs/pacnet.git
   cd pacnet
   export PYTHONPATH="${PYTHONPATH}:$(pwd)"
   

2. 安装依赖库 使用 pip 安装项目所需的额外依赖包。

   pip install -r requirements.txt
   

   (国内用户可添加 -i https://pypi.tuna.tsinghua.edu.cn/simple 加速下载)

3. 验证安装 (可选) 运行单元测试以确保环境配置正确。

   python -m unittest 
   

基本使用

PacNet 提供了多种核心层（如 PacConv2d, PacPool2d 等），其用法与原生 PyTorch 层类似，但需要额外传入一个引导特征 (Guide) 张量。

最简单的使用示例 (PacConv2d)

以下示例展示了如何构建一个标准的像素自适应卷积层，并执行前向传播。

import torch
import torch.nn as nn
from pacnet import PacConv2d

# 1. 定义维度参数
in_ch, out_ch, g_ch = 16, 32, 8         # 输入通道、输出通道、引导特征通道
f, b, h, w = 5, 2, 64, 64               # 卷积核尺寸、Batch size、高、宽

# 2. 创建输入张量和引导特征张量
# input: 标准输入图像特征
input = torch.rand(b, in_ch, h, w)
# guide: 引导特征 (对应论文公式 3 中的 'f')，空间尺寸需与输入一致
guide = torch.rand(b, g_ch, h, w)

# 3. 初始化 PAC 卷积层
# 参数用法与 nn.Conv2d 基本一致，支持 kernel_type, normalize_kernel 等额外参数
pacconv = PacConv2d(in_ch, out_ch, f)   

# 4. 执行前向传播
# 标准调用方式：传入 input 和 guide
out_pac = pacconv(input, guide)         

# 替代调用方式：传入预计算的核 'K' (guide_k)
# guide_k 形状应为 [b, g_ch, f, f, h, w]，可通过 packernel2d 生成
# out_pac = pacconv(input, None, guide_k) 

print(f"Output shape: {out_pac.shape}")

核心接口说明

• 输入要求: PacConv2d 接受两个主要张量：input (待处理特征) 和 guide (引导信息)。
• 尺寸一致性: 当使用相同的标准参数（如 stride, padding）时，PacConv2d 的输出尺寸与原生 nn.Conv2d 完全一致。
• 函数式接口: 除了类实例化调用外，也可使用 pacconv2d 函数配合 packernel2d 进行函数式编程。

其他可用层

项目还实现了以下变体，用法与上述类似：

• PacConvTranspose2d: 用于上采样的转置卷积。
• PacPool2d: 像素自适应池化层。
• PacCRF / PacCRFLoose: 用于密集预测任务末端的条件随机场 (CRF) 推理层。