通过训练卷积神经网络比较图像块进行立体匹配

该仓库包含：

• 使用卷积神经网络计算立体匹配代价的流程；
• 在立体匹配任务上训练卷积神经网络的流程；以及
• 一种基础的立体匹配方法（基于交叉的代价聚合、半全局匹配、左右一致性检查、中值滤波和双边滤波）；

运行 KITTI 数据集需要至少 6 GB 显存的 NVIDIA GPU，而运行 Middlebury 数据集则需要 12 GB 显存。我们已在 GTX Titan（仅限 KITTI）、K80 和 GTX Titan X 上测试过代码。 代码采用 BSD 2-Clause 许可证发布。 如果您在工作中使用了本仓库中的代码，请引用我们的 论文。

@article{zbontar2016stereo,
  title={Stereo matching by training a convolutional neural network to compare image patches},
  author={Zbontar, Jure and LeCun, Yann},
  journal={Journal of Machine Learning Research},
  volume={17},
  pages={1--32},
  year={2016}
}

下载预训练网络

• KITTI 2012 快速
• KITTI 2012 精确
• KITTI 2015 快速
• KITTI 2015 精确
• Middlebury 快速
• Middlebury 精确

计算匹配代价

安装 Torch、OpenCV 2.4 和 png++。

在与本 README 文件同一目录下运行以下命令。

编译共享库：

$ cp Makefile.proto Makefile
$ make

该命令应生成两个文件：libadcensus.so 和 libcv.so。

要在 KITTI 2012 训练集中的某对立体图像上运行立体算法——

• 左侧输入图像
• 右侧输入图像

——请下载预训练网络，并使用以下参数调用 main.lua：

$ wget -P net/ https://s3.amazonaws.com/mc-cnn/net_kitti_fast_-a_train_all.t7
$ ./main.lua kitti fast -a predict -net_fname net/net_kitti_fast_-a_train_all.t7 -left https://oss.gittoolsai.com/images/jzbontar_mc-cnn_readme_84f4e654cf5b.png -right https://oss.gittoolsai.com/images/jzbontar_mc-cnn_readme_715936054685.png -disp_max 70
Writing right.bin, 1 x 70 x 370 x 1226
Writing left.bin, 1 x 70 x 370 x 1226
Writing disp.bin, 1 x 1 x 370 x 1226

前两个参数（kitti fast）用于设置立体方法的默认超参数。输出以三个二进制文件的形式存储：

• left.bin：以左图作为参考图像时，经过半全局匹配和基于交叉的代价聚合后的匹配代价。
• right.bin：与 left.bin 相同，但以右图作为参考图像。
• disp.bin：完成整个立体方法后的视差图。

使用 bin2png.lua 脚本来生成如上所示的 .png 图像：

$ luajit samples/bin2png.lua 
Writing left.png
Writing right.png
Writing disp.png

如果您希望直接使用卷积神经网络的原始输出，即不应用基于交叉的代价聚合和半全局匹配，请运行以下命令：

$ ./main.lua kitti fast -a predict -net_fname net/net_kitti_fast_-a_train_all.t7 -left https://oss.gittoolsai.com/images/jzbontar_mc-cnn_readme_84f4e654cf5b.png -right https://oss.gittoolsai.com/images/jzbontar_mc-cnn_readme_715936054685.png -disp_max 70 -sm_terminate cnn
Writing right.bin, 1 x 70 x 370 x 1226
Writing left.bin, 1 x 70 x 370 x 1226
Writing disp.bin, 1 x 1 x 370 x 1226

生成的视差图应如下所示：

• left.png
• right.png

请注意，-disp_max 70 仅作为示例。要复现我们在 KITTI 数据集上的结果，请使用 -disp_max 228。

有关如何在循环中为多对图像调用 main.lua 的示例，请参阅 predict_kitti.lua 脚本。

加载输出的二进制文件

您可以将二进制文件映射到内存中来加载它们（例如，如果您想应用自己编写的不同的后处理步骤）。我们提供了一些常用编程语言的内存映射示例。

• Lua

    require 'torch'
    left = torch.FloatTensor(torch.FloatStorage('../left.bin')):view(1, 70, 370, 1226)
    right = torch.FloatTensor(torch.FloatStorage('../right.bin')):view(1, 70, 370, 1226)
    disp = torch.FloatTensor(torch.FloatStorage('../disp.bin')):view(1, 1, 370, 1226)
  

• Python

    import numpy as np
    left = np.memmap('../left.bin', dtype=np.float32, shape=(1, 70, 370, 1226))
    right = np.memmap('../right.bin', dtype=np.float32, shape=(1, 70, 370, 1226))
    disp = np.memmap('../disp.bin', dtype=np.float32, shape=(1, 1, 370, 1226))
  

• Matlab

    left = memmapfile('../left.bin', 'Format', 'single').Data;
    left = permute(reshape(left, [1226 370 70]), [3 2 1]);
    right = memmapfile('../right.bin', 'Format', 'single').Data;
    right = permute(reshape(right, [1226 370 70]), [3 2 1]);
    disparity = memmapfile('../disp.bin', 'Format', 'single').Data;
    disparity = reshape(disparity, [1226 370])';
  

• C

    #include <fcntl.h>
    #include <stdio.h>
    #include <sys/mman.h>
    #include <sys/stat.h>
    #include <sys/types.h>
    int main(void)
    {
        int fd;
        float *left, *right, *disp;
        fd = open("../left.bin", O_RDONLY);
        left = mmap(NULL, 1 * 70 * 370 * 1226 * sizeof(float), PROT_READ, MAP_SHARED, fd, 0);
        close(fd);
        fd = open("../right.bin", O_RDONLY);
        right = mmap(NULL, 1 * 70 * 370 * 1226 * sizeof(float), PROT_READ, MAP_SHARED, fd, 0);
        close(fd);
        fd = open("../disp.bin", O_RDONLY);
        disp = mmap(NULL, 1 * 1 * 370 * 1226 * sizeof(float), PROT_READ, MAP_SHARED, fd, 0);
        close(fd);
        return 0;
    }
  

训练

本节说明如何在 KITTI 和 Middlebury 数据集上训练卷积神经网络。

KITTI

下载以下两个数据集并解压：

• KITTI 2012，解压到 data.kitti/unzip 目录（最终应得到文件 data.kitti/unzip/training/image_0/000000_10.png）；
• KITTI 2015，解压到 data.kitti2015/unzip 目录（最终应得到文件 data.kitti2015/unzip/training/image_2/000000_10.png）。

运行预处理脚本：

$ ./preprocess_kitti.lua
dataset 2012
1
...
389
dataset 2015
1
...
400

运行 main.lua 训练网络：

$ ./main.lua kitti slow -a train_tr
kitti slow -a train_tr 
conv(in=1, out=112, k=3)
cudnn.ReLU
conv(in=112, out=112, k=3)
cudnn.ReLU
conv(in=112, out=112, k=3)
cudnn.ReLU
conv(in=112, out=112, k=3)
cudnn.ReLU
nn.Reshape(128x224)
nn.Linear(224 -> 384)
cudnn.ReLU
nn.Linear(384 -> 384)
cudnn.ReLU
nn.Linear(384 -> 384)
cudnn.ReLU
nn.Linear(384 -> 384)
cudnn.ReLU
nn.Linear(384 -> 1)
cudnn.Sigmoid
...

网络在部分训练样本上进行训练，其余样本用于验证；若要使用全部样本训练，可执行：

$ ./main.lua kitti slow -a train_all

在上述命令中使用的是 KITTI 2012 数据集。若希望使用 KITTI 2015 数据集训练，可运行：

$ ./main.lua kitti2015 slow -a train_tr

若要训练快速架构，则使用：

$ ./main.lua kitti fast -a train_tr

训练好的网络会保存在 net/ 目录下。

$ ls net/
...
net_kitti2012_fast_-action_train_tr.t7
...

Middlebury

运行 download_middlebury.sh 脚本下载训练数据（根据网络连接速度，可能需要较长时间）：

$ ./download_middlebury.sh

数据集将被下载到 data.mb/unzip 目录。

编译 MiddEval3-SDK。最终应在你的 PATH 环境变量所列的某个目录中生成 computemask 可执行文件。

安装 ImageMagick；预处理步骤需要 convert 命令来调整图像大小。

运行预处理脚本：

$ mkdir data.mb.imperfect_gray
$ ./preprocess_mb.py imperfect gray
Adirondack
Backpack
...
testH/Staircase

首次运行预处理时速度较慢（大约需要 30 分钟），因为需要对图像进行缩放。

使用 main.lua 训练网络：

$ ./main.lua mb slow -a train_tr

其他实用命令

计算验证集上的误差率（可用于调整超参数）：

$ ./main.lua kitti fast -a test_te -net_fname net/net_kitti_fast_-a_train_tr.t7 
kitti fast -a test_te -net_fname net/net_kitti_fast_-a_train_tr.t7 
0.86836290359497        0.0082842716717202
...
0.73244595527649        0.024202708004929
0.72730183601379        0.023603160822285
0.030291934952454

快速架构在 KITTI 2012 数据集上的验证误差率为 3.029%。

***

计算在一个数据集的验证集上，由另一个数据集训练的网络的误差率。

$ ./main.lua kitti fast -a test_te -net_fname net/net_mb_fast_-a_train_all.t7
kitti fast -a test_te -net_fname net/net_mb_fast_-a_train_all.t7
2.1474301815033	0.0071447750148986
...
1.4276049137115	0.024273838024622
1.4282908439636	0.01881285579564
1.408842086792	0.021741689597834
0.031564540460366

在 KITTI 2012 数据集上测试、但由 Middlebury 数据集训练的快速架构的验证误差率为 3.156%。

***

准备提交至 KITTI 和 Middlebury 评估服务器的文件。

$ ./main.lua kitti fast -a submit -net_fname net/net_kitti_fast_-a_train_all.t7 
kitti fast -a submit -net_fname net/net_kitti_fast_-a_train_all.t7 
  adding: 000038_10.png (deflated 0%)
  adding: 000124_10.png (deflated 0%)
  ...
  adding: 000021_10.png (deflated 0%)

输出结果存储在 out/submission.zip 中，可用于提交至 KITTI 评估服务器。

***

尝试不同的网络架构：

$ ./main.lua kitti slow -a train_tr -l1 2 -fm 128 -l2 3 -nh2 512
kitti slow -a train_tr -l1 2 -fm 128 -l2 3 -nh2 512 
conv(in=1, out=128, k=3)
cudnn.ReLU
conv(in=128, out=128, k=3)
cudnn.ReLU
nn.Reshape(128x256)
nn.Linear(256 -> 512)
cudnn.ReLU
nn.Linear(512 -> 512)
cudnn.ReLU
nn.Linear(512 -> 512)
cudnn.ReLU
nn.Linear(512 -> 1)
cudnn.Sigmoid
...

***

测量在特定数据集上的运行时间：

$ ./main.lua kitti fast -a time
kitti fast -a time 
conv(in=1, out=64, k=3)
cudnn.ReLU
conv(in=64, out=64, k=3)
cudnn.ReLU
conv(in=64, out=64, k=3)
cudnn.ReLU
conv(in=64, out=64, k=3)
nn.Normalize2
nn.StereoJoin1
0.73469495773315

在 KITTI 2012 数据集上运行快速架构需要 0.73 秒。若仅关注神经网络部分的耗时，可以提前终止立体匹配过程：

$ ./main.lua kitti fast -a time -sm_terminate cnn
kitti fast -a time -sm_terminate cnn 
conv(in=1, out=64, k=3)
cudnn.ReLU
conv(in=64, out=64, k=3)
cudnn.ReLU
conv(in=64, out=64, k=3)
cudnn.ReLU
conv(in=64, out=64, k=3)
nn.Normalize2
nn.StereoJoin1
0.31126594543457

MC-CNN 快速上手指南

MC-CNN 是一个基于卷积神经网络（CNN）进行立体匹配（Stereo Matching）的开源工具，通过训练网络比较图像块来计算视差图。

环境准备

系统要求

• GPU: 必须配备 NVIDIA GPU。
  • 运行 KITTI 数据集：显存至少 6 GB。
  • 运行 Middlebury 数据集：显存至少 12 GB。
  • 已测试显卡型号：GTX Titan, K80, GTX Titan X。
• 操作系统: Linux (推荐，因涉及 .so 库编译)。

前置依赖

请确保安装以下软件库：

1. Torch: 深度学习框架。
2. OpenCV 2.4: 计算机视觉库。
3. png++: PNG 图像处理库。

提示: 国内用户安装 Torch 时若遇网络问题，可尝试配置国内镜像源或使用离线安装包。

安装步骤

1. 克隆代码与编译

在项目根目录下执行以下命令，复制配置文件并编译共享库：

cp Makefile.proto Makefile
make

编译成功后，当前目录应生成 libadcensus.so 和 libcv.so 两个文件。

2. 下载预训练模型

根据需求下载对应的预训练网络模型（.t7 文件）。以下是 KITTI 2012 的快速版模型示例：

mkdir -p net
wget -P net/ https://s3.amazonaws.com/mc-cnn/net_kitti_fast_-a_train_all.t7

可用模型列表:

• KITTI 2012/2015: 提供 fast (快速) 和 accurate (高精度) 版本。
• Middlebury: 提供 fast 和 accurate 版本。 完整下载链接请参考项目原始 README。

基本使用

以下示例演示如何使用预训练模型对一对立体图像进行视差预测。

1. 运行立体匹配

假设你有一对左右图像 kittiL.png 和 kittiR.png，执行以下命令：

./main.lua kitti fast -a predict -net_fname net/net_kitti_fast_-a_train_all.t7 -left samples/input/kittiL.png -right samples/input/kittiR.png -disp_max 70

参数说明:

• kitti fast: 设置立体匹配方法的默认超参数。
• -disp_max 70: 最大视差值（KITTI 官方评测通常设为 228，此处仅为示例）。
• 输出将生成三个二进制文件：left.bin, right.bin, disp.bin。

2. 转换结果为图片

使用提供的脚本将二进制输出转换为可视化的 PNG 图片：

luajit samples/bin2png.lua

执行后将生成：

• left.png: 左图为参考图的匹配成本图。
• right.png: 右图为参考图的匹配成本图。
• disp.png: 最终生成的视差图。

3. (可选) 仅使用 CNN 原始输出

如果你不需要后续的聚合优化（如半全局匹配 SGM），只想获取纯 CNN 的输出结果，添加 -sm_terminate cnn 参数：

./main.lua kitti fast -a predict -net_fname net/net_kitti_fast_-a_train_all.t7 -left samples/input/kittiL.png -right samples/input/kittiR.png -disp_max 70 -sm_terminate cnn

4. 读取输出数据

生成的 .bin 文件可通过内存映射（Memory Map）在多种语言中读取。

Python 示例:

import numpy as np
# 读取视差图 (形状需根据实际输出调整，示例为 1x1x370x1226)
disp = np.memmap('disp.bin', dtype=np.float32, shape=(1, 1, 370, 1226))

Lua 示例:

require 'torch'
disp = torch.FloatTensor(torch.FloatStorage('disp.bin')):view(1, 1, 370, 1226)