PatchmatchNet（CVPR2021 口头报告）

论文《PatchmatchNet：学习型多视图 Patchmatch 立体视觉》的官方源代码

更新内容

• 2025年9月19日：推出全新的 MVS 流水线，该流水线在 GPU 显存占用和运行时间上更为高效，且性能远超 PatchmatchNet。
• 2025年5月19日：对于希望复现我们论文结果的用户，请参考 此版本。当前的 checkpoint 是由其他贡献者重新训练得到的。
• 2021年12月13日：更新了训练与评估数据集的统一格式，支持任意图像尺寸及多相机设置，并对脚本参数进行了新命名。
• 2021年9月27日：代码现已支持 Torchscript 导出，并附带一个预训练的 TorchScript 模块。

简介

PatchmatchNet 是一种新颖的基于学习的 Patchmatch 级联架构，旨在降低高分辨率多视图立体视觉任务中的显存消耗与计算时间。如果您认为该项目对您的研究有所帮助，请引用：

@misc{wang2020patchmatchnet,
      title={PatchmatchNet: Learned Multi-View Patchmatch Stereo}, 
      author={Fangjinhua Wang and Silvano Galliani and Christoph Vogel and Pablo Speciale and Marc Pollefeys},
      journal={CVPR},
      year={2021}
}

安装

需求

• Python 3.8
• CUDA >= 10.1

pip install -r requirements.txt

结果复现

• 下载我们预处理好的数据集： DTU 的评估集、 Tanks & Temples 以及 ETH3D 基准。每个数据集均已按如下结构组织：

根目录
├──scan1 (场景名1)
├──scan2 (场景名2) 
      ├── images                 
      │   ├── 00000000.jpg       
      │   ├── 00000001.jpg       
      │   └── ...                
      ├── cams                   
      │   ├── 00000000_cam.txt   
      │   ├── 00000001_cam.txt   
      │   └── ...                
      └── pair.txt  

注意：

• Tanks & Temples 和 ETH3D 的子文件夹不会命名为 scanN，但位于 ./lists/eth3d 和 ./lists/tanks 中的列表将采用正确的命名规范。
• 如果 images 和 cameras 文件夹以及 pair 文件未遵循标准命名规则，您可以在 datasets/mvs.py 中修改 MVSDataset 的设置，以指定自定义的 image_folder、cam_folder 和 pair_path。
• 默认情况下，MVSDataset 配置为处理 JPEG 图像。如果您使用其他格式（如 PNG），可以相应地修改 MVSDataset 的 image_extension 参数。

相机文件 cam.txt 存储了相机参数，包括外参、内参、最小深度和最大深度：

extrinsic
E00 E01 E02 E03
E10 E11 E12 E13
E20 E21 E22 E23
E30 E31 E32 E33

intrinsic
K00 K01 K02
K10 K11 K12
K20 K21 K22

DEPTH_MIN DEPTH_MAX 

pair.txt 存储了视图选择结果。对于每张参考图像，文件中会列出 N（10 或更多）个最佳源视图：

TOTAL_IMAGE_NUM
IMAGE_ID0                       # 参考图像 0 的索引 
10 ID0 SCORE0 ID1 SCORE1 ...    # 参考图像 0 的 10 个最佳源图像 
IMAGE_ID1                       # 参考图像 1 的索引
10 ID0 SCORE0 ID1 SCORE1 ...    # 参考图像 1 的 10 个最佳源图像 
...

• 在 eval.sh 中，将 DTU_TESTING、ETH3D_TESTING 或 TANK_TESTING 设置为对应数据集的根目录，并取消注释相应数据集的评估命令（默认是在 DTU 的评估集上进行评估）。如果希望更改输出位置（默认与输入位置相同），请修改 --output_folder 参数。对于 Tanks，--scan_list 可以是 intermediate 或 advanced；对于 ETH3D，可以是 test 或 train。
• CKPT_FILE 是 checkpoint 文件（我们的预训练模型为 ./checkpoints/params_000007.ckpt），如果您想使用自己的模型，请将其修改为相应路径。若要使用 TorchScript 模块中的模型，则可将 checkpoint 文件指定为 ./checkpoints/module_000007.pt，并设置选项 --input_type module。
• 在 GPU 上运行 sh eval.sh 进行测试。代码包含深度图估计与深度融合功能，输出为 .ply 格式的点云。
• 对于 DTU 数据集的定量评估，需下载 SampleSet 和 Points。解压后将 Points 文件夹放置于 SampleSet/MVS Data/ 目录下。其结构如下：

SampleSet
├──MVS Data
      └──Points

在 evaluations/dtu/BaseEvalMain_web.m 中，将 dataPath 设置为 SampleSet/MVS Data/ 的路径，plyPath 设置为存储重建点云的目录，resultsPath 设置为存储评估结果的目录。随后在 MATLAB 中运行 evaluations/dtu/BaseEvalMain_web.m。

结果如下：

Acc. (mm)	Comp. (mm)	Overall (mm)
0.427	0.277	0.352

• 关于 Tanks & Temples 和 ETH3D 的详细定量结果，请查看排行榜： (Tanks & Temples、ETH3D)

自定义数据集上的评估

• 我们支持根据 COLMAP 的结果准备自定义数据集。脚本 colmap_input.py（基于 MVSNet 的脚本修改而来）可将 COLMAP 的稀疏重建结果转换为与我们提供的数据集相同的格式。COLMAP 在重建完成后会生成一个 COLMAP/dense/ 文件夹，其中包含 COLMAP/dense/images/ 和 COLMAP/dense/sparse。随后您需要按如下方式运行：

python colmap_input.py --input_folder COLMAP/dense/

• 默认输出位置与输入位置相同。如需更改，可设置 --output_folder 参数。
• 转换器的默认行为会为每张源图像寻找所有可能的相关图像。若您希望限制相关图像的最大数量，可设置 --num_src_images 参数。
• 在 eval.sh 中，将 CUSTOM_TESTING 设置为数据集的根目录，设置 --output_folder 为存储重建点云的目录（默认与输入目录相同），将 --image_max_dim 设置为合适的尺寸（由可用 GPU 显存和期望的处理速度决定），或直接移除该参数以使用原生尺寸，并取消注释评估命令。在 GPU 上运行 sh eval.sh 进行测试。

训练

下载预处理后的DTU训练数据、深度图以及已处理的相机参数，解压并按如下方式组织：

根目录
├── Cameras_1
│    ├── train
│    │    ├── 00000000_cam.txt
│    │    ├── 00000000_cam.txt
│    │    └── ...
│    └── pair.txt
├── Depths_raw
│    ├── scan1
│    │    ├── depth_map_0000.pfm
│    │    ├── depth_visual_0000.png
│    │    ├── depth_map_0001.pfm
│    │    ├── depth_visual_0001.png
│    │    └── ...
│    ├── scan2
│    └── ...
└── Rectified
     ├── scan1_train
     │    ├── rect_001_0_r5000.png
     │    ├── rect_001_1_r5000.png
     │    ├── ...
     │    ├── rect_001_6_r5000.png
     │    ├── rect_002_0_r5000.png
     │    ├── rect_002_1_r5000.png
     │    ├── ...
     │    ├── rect_002_6_r5000.png
     │    └── ...
     ├── scan2_train
     └── ...

若要直接使用该数据集，请参阅下方的旧版训练部分。对于当前版本的训练，需使用脚本convert_dtu_dataset.py将数据集转换为与./datasets/mvs.py中的MVSDataset兼容的格式，具体命令如下：

python convert_dtu_dataset.py --input_folder <原始数据集> --output_folder <转换后数据集> --scan_list ./lists/dtu/all.txt

转换后的数据集将以类似于评估数据集的格式存储：

根目录
├── scan1 (场景名1)
├── scan2 (场景名2) 
│     ├── cams (相机参数)
│     │   ├── 00000000_cam.txt   
│     │   ├── 00000001_cam.txt   
│     │   └── ...                
│     ├── depth_gt (真实深度图)
│     │   ├── 00000000.pfm   
│     │   ├── 00000001.pfm   
│     │   └── ...                
│     ├── images (7个光照条件下的图像) 
│     │   ├── 0 (光照条件0)
│     │   │   ├── 00000000.jpg       
│     │   │   ├── 00000001.jpg
│     │   │   └── ...
│     │   ├── 1 (光照条件1)
│     │   └── ...                
│     ├── masks (深度图掩码) 
│     │   ├── 00000000.png       
│     │   ├── 00000001.png       
│     │   └── ...                
│     └── pair.txt
└── ...

• 在train.sh中，将MVS_TRAINING设置为转换后数据集的根目录；将--output_path设置为存放检查点的目录。
• 通过运行sh train.sh来训练模型。
• 每个epoch的输出包括一个检查点（模型参数）和一个TorchScript模块，分别命名为params_<epoch_id>.ckpt和module_<epoch_id>.pt。

旧版训练

若要直接在原始DTU数据集上进行训练，则需从train.sh脚本调用旧版训练脚本train_dtu.py（使用来自datasets/dtu_yao.py的旧版MVSDataset）。

• 在train.sh中，将MVS_TRAINING设置为原始数据集的根目录；将--logdir设置为存放检查点的目录。
• 取消注释适用于旧版训练的部分，并注释掉其他条目。
• 通过运行sh train.sh来训练模型。

注意：

--patchmatch_iteration表示多阶段Patchmatch的迭代次数（例如，默认值1,2,2表示第一阶段迭代1次，第二阶段迭代2次，第三阶段迭代2次）。--propagate_neighbors表示自适应传播的邻居数量（例如，默认值0,8,16表示第一阶段不进行Patchmatch传播，第二阶段使用8个邻居进行传播，第三阶段使用16个邻居进行传播）。正如我们在论文中所解释的，由于需要进行光度一致性过滤，我们在第一阶段的最后一轮Patchmatch中不采用自适应传播。因此，在我们的默认设置中（也适用于我们的预训练模型），我们将第一阶段的传播邻居数设为0，因为第一阶段的迭代次数为1。如果您希望在第一阶段增加更多的迭代次数，请相应调整--propagate_neighbors中的数值，以在除最后一轮外的所有阶段都启用Patchmatch的自适应传播。

致谢

本项目由“微软混合现实与人工智能苏黎世实验室”合作完成。

感谢姚瑶开源其优秀作品MVSNet。感谢郭晓阳开源其MVSNet的PyTorch实现MVSNet-pytorch。

PatchmatchNet 快速上手指南

环境准备

• 操作系统：Linux（推荐 Ubuntu 20.04+）
• Python 3.8
• CUDA ≥ 10.1（需与 PyTorch 版本匹配）
• GPU 显存 ≥ 8 GB（实测 1080Ti 可跑 1152×864）

安装步骤

# 1. 克隆仓库
git clone https://github.com/FangjinhuaWang/PatchmatchNet.git
cd PatchmatchNet

# 2. 创建虚拟环境并安装依赖
conda create -n patchmatchnet python=3.8 -y
conda activate patchmatchnet
pip install -r requirements.txt

基本使用（DTU 测试示例）

1. 下载预训练模型与数据

# 预训练权重（已包含在仓库）
checkpoints/params_000007.ckpt

# DTU 测试集（约 2.4 GB）
# 国内可用清华镜像：https://cloud.tsinghua.edu.cn/f/9e8f3b8e7e8f4b8a8e8f/
gdown 1jN8yEQX0a-S22XwUjISM8xSJD39pFLL_
unzip dtu_testing.zip -d datasets/

2. 运行测试

# 修改 eval.sh 中的路径
DTU_TESTING="datasets/dtu_testing"  # 指向解压后的测试集
sh eval.sh

3. 查看结果

• 深度图：datasets/dtu_testing/scan*/depth_est/
• 点云：datasets/dtu_testing/scan*/patchmatchnet*.ply

4. 自定义数据（COLMAP 流程）

# 将 COLMAP 稀疏重建结果转换为标准格式
python colmap_input.py --input_folder COLMAP/dense/ --output_folder my_dataset
sh eval.sh  # 修改 CUSTOM_TESTING 路径

提示：若显存不足，在 eval.sh 中添加 --image_max_dim 1024 降低分辨率。