3DMatch 工具箱

3DMatch 是一种基于 ConvNet 的局部几何特征描述符，适用于 3D 数据（即点云、深度图、网格等）。该工具箱提供了使用 3DMatch 进行几何配准和关键点匹配的代码，以及从现有 RGB-D 重建数据中训练 3DMatch 的代码。这是我们论文的参考实现：

3DMatch：从 RGB-D 重建中学习局部几何描述符

PDF | 网页、基准测试与数据集 | 视频

Andy Zeng、Shuran Song、Matthias Nießner、Matthew Fisher、Jianxiong Xiao 和 Thomas Funkhouser

IEEE 计算机视觉与模式识别会议 (CVPR) 2017 口头报告

由于 3D 扫描数据通常具有噪声、低分辨率且不完整的特点，因此在真实世界的深度图像上匹配局部几何特征是一项极具挑战性的任务。这些困难限制了当前最先进的方法的性能，而这些方法通常基于几何属性的直方图。在本文中，我们提出了 3DMatch，这是一种数据驱动的模型，能够学习局部体积块描述符，用于建立部分 3D 数据之间的对应关系。为了收集用于训练我们模型的数据，我们提出了一种无监督特征学习方法，该方法利用现有 RGB-D 重建中数百万个对应标签。实验表明，我们的描述符不仅能够在新场景中匹配局部几何以进行重建，还能够泛化到不同的任务和空间尺度（例如，亚马逊拣选挑战中的实例级物体模型对齐，以及网格曲面对应）。结果表明，3DMatch 始终以显著优势超越其他最先进的方法。

引用

如果您在工作中发现此代码有用，请考虑引用以下内容：

@inproceedings{zeng20163dmatch, 
	title={3DMatch: Learning Local Geometric Descriptors from RGB-D Reconstructions}, 
	author={Zeng, Andy and Song, Shuran and Nie{\ss}ner, Matthias and Fisher, Matthew and Xiao, Jianxiong and Funkhouser, Thomas}, 
	booktitle={CVPR}, 
	year={2017} 
}

许可证

此代码根据简化 BSD 许可证发布（详情请参阅 LICENSE 文件）。

基准测试与数据集

所有相关信息和下载均可在此处找到 这里。

联系方式

如果您有任何问题或发现任何错误，请告知我：Andy Zeng andyz[at]princeton[dot]edu

更改日志

• 2018年3月20日。 更新：为关键点匹配基准测试的测试集添加了标签（以方便使用）。
• 2017年11月2日。 修复 bug：在演示代码的 utils.hpp 中添加了 #include <random>。
• 2017年10月30日。 修复 bug：包含了 Quoc-Huy 对训练过程中偶尔出现的 NaN 错误的修复。
• 2017年10月28日。 注意：演示代码仅读取以简单二进制格式保存的 3D 点云。如果您希望在自己的点云格式上运行 3DMatch 演示代码，请相应地修改 demo.cu。
• 2017年4月6日。 注意：3DMatch 使用 cuDNN 5.1。修订了安装说明。

依赖项

我们提供的 3DMatch 参考实现以及本工具箱中的其他组件需要以下依赖项。已在 Ubuntu 14.04 上测试过。

0. CUDA 7.5 和 cuDNN 5.1。您可能需要注册 NVIDIA。以下是设置 cuDNN 5.1 的一些额外步骤。注意 我们强烈建议您将不同版本的 cuDNN 安装到不同的目录中（例如，/usr/local/cudnn/vXX），因为不同的软件包可能需要不同版本的 cuDNN。

   LIB_DIR=lib$([[ $(uname) == "Linux" ]] && echo 64)
   CUDNN_LIB_DIR=/usr/local/cudnn/v5.1/$LIB_DIR
   echo LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CUDNN_LIB_DIR >> ~/.profile && ~/.profile
   
   tar zxvf cudnn*.tgz
   sudo cp cuda/$LIB_DIR/* $CUDNN_LIB_DIR/
   sudo cp cuda/include/* /usr/local/cudnn/v5.1/include/
   

1. OpenCV（已用 OpenCV 2.4.11 测试）

• 用于读取图像文件

0. Matlab 2015b 或更高版本（已用 Matlab 2016a 测试）

目录

• 演示：使用 3DMatch 对齐两个点云
• 将 3D 数据转换为 TDF 体素网格
• 从 RGB-D 重建中训练 3DMatch
• 多帧深度 TSDF 融合
• 评估代码

演示：使用 3DMatch 对齐两个点云

本演示使用我们预训练的 3DMatch 描述符（配合 Marvin）和标准 RANSAC，对两个 3D 点云（由单视图深度图投影而来）进行对齐。

指导说明

0. 克隆 3DMatch 工具箱，编译 C++/CUDA 演示代码和 Marvin

   git clone https://github.com/andyzeng/3dmatch-toolbox.git 3dmatch-toolbox
   cd 3dmatch-toolbox/core
   ./compile.sh
   

1. 下载我们预训练的 3DMatch 权重

   ./download-weights.sh # 3dmatch-weights-snapshot-137000.marvin
   

2. 加载两个示例 3D 点云，计算它们的 TDF 体素网格体积，并计算随机表面关键点及其 3DMatch 描述符（保存到磁盘上的二进制文件）。警告：此演示仅读取以简单二进制格式保存的 3D 点云。如果您希望在自己的点云格式上运行 3DMatch 演示代码，请相应地修改 demo.cu。

   # 生成 fragment-1.desc.3dmatch.bin 和 fragment-1.keypts.bin
   ./demo ../data/sample/3dmatch-demo/single-depth-1.ply fragment-1
   
   # 生成 fragment-2.desc.3dmatch.bin 和 fragment-2.keypts.bin
   ./demo ../data/sample/3dmatch-demo/single-depth-2.ply fragment-2 
   

3. 在 Matlab 中运行以下脚本：

   % 加载关键点和 3DMatch 描述符，并使用 RANSAC 对齐这两个点云。对齐后的点云可视化结果将保存到文件 `result.ply` 中，可以使用 Meshlab 或其他 3D 查看器查看。注意：由于默认情况下随机选择的关键点质量较差，此演示首次尝试时可能存在对齐失败的风险。
   demo;
   

将3D数据转换为TDF体素网格

关于如何将各种3D数据表示形式转换为截断距离函数（TDF）值的体素网格的说明。

0. 点云到TDF体素网格（使用最近邻点距离）

• 参见C++/CUDA示例代码（ComputeTDF），它通过占用体素网格快速近似计算TDF值。
• 替代方案：参见Matlab/CUDA代码，该代码可以计算精确的TDF值，但速度非常慢。
• 替代方案：参见Matlab代码，同样可以计算精确的TDF值，但可在Matlab中独立运行。如果您的点云较小，通常不会出现内存问题。

0. 网格到TDF体素网格（使用GAPS对网格表面进行距离变换）。请注意，本仓库中已包含GAPS的一个版本。

• 安装GAPS并将示例网格（.off文件）转换为体素网格（浮点数的二进制.raw文件）的说明：

  cd 3dmatch-toolbox/gaps
  
  # 安装GAPS
  make
  
  # 对示例网格文件运行msh2df（更多信息请参阅msh2df.cpp中的注释）
  cd bin/x86_64
  wget http://3dvision.princeton.edu/projects/2016/3DMatch/downloads/gaps/bicycle000002.off
  ./msh2df bicycle000002.off bicycle000002.raw -v # 更多参数请参阅msh2df.cpp中的注释
  
  # 下载可视化脚本
  wget http://3dvision.princeton.edu/projects/2016/3DMatch/downloads/gaps/showTDF.m
  

• 在Matlab中运行可视化脚本

  % 可视化网格的TDF体素网格
  showTDF;
  

0. 深度图到TDF体素网格

• 将深度图投影到3D相机空间中的点云，并从点云转换为TDF体素网格（见上文）。
• 替代方案：将深度图（或多帧深度图）转换为TSDF体积（参见此处的说明），并计算每个体素的绝对值（即投影式TDF值，其在视场边界和缺失深度区域的行为有所不同）。

使用RGB-D重建数据训练3DMatch

请参阅3dmatch-toolbox/training文件夹。

用于使用轻量级纯GPU神经网络框架Marvin训练3DMatch的代码。其中包括Siamese网络架构的.json文件training/net.json，以及training/match.hpp中的CUDA/C++ Marvin数据层，该层可从RGB-D重建数据集随机采对应点（这些数据集可从我们的项目主页下载）。

快速入门

0. 编译Marvin

   cd 3dmatch-toolbox/training
   ./compile.sh
   

1. 从RGB-D重建数据集下载若干训练和测试场景（更多场景可在此处下载）

   cd ../data
   mkdir train && mkdir test && mkdir backup
   cd train
   wget http://3dvision.princeton.edu/projects/2016/3DMatch/downloads/rgbd-datasets/sun3d-brown_cogsci_1-brown_cogsci_1.zip
   wget http://3dvision.princeton.edu/projects/2016/3DMatch/downloads/rgbd-datasets/7-scenes-heads.zip
   wget http://3dvision.princeton.edu/projects/2016/3DMatch/downloads/rgbd-datasets/sun3d-harvard_c11-hv_c11_2.zip
   unzip sun3d-brown_cogsci_1-brown_cogsci_1.zip
   unzip 7-scenes-heads.zip
   unzip sun3d-harvard_c11-hv_c11_2.zip
   mv *.zip ../backup
   cd ../test
   wget http://3dvision.princeton.edu/projects/2016/3DMatch/downloads/rgbd-datasets/sun3d-hotel_umd-maryland_hotel3.zip
   unzip sun3d-hotel_umd-maryland_hotel3.zip
   mv *.zip ../backup
   cd ../../training
   

2. 从data/train中保存的RGB-D场景对应的点对开始，从零训练一个3DMatch模型

   ./marvin train net.json
   

3. （可选）使用Marvin张量文件中的预训练权重训练3DMatch

   ./marvin train net.json your-pre-trained-weights.marvin
   

其他设置说明

您可以在我们的项目主页上下载更多RGB-D重建数据集。这些数据集已被转换为统一格式，与我们用于训练3DMatch的Marvin数据层兼容。请至少将一个场景保存到data/train，另一个场景保存到data/test，使文件夹结构如下所示：

|——— training
     |——— core
          |——— marvin.hpp
          |——— ...
|——— data
     |——— train
          |——— rgbd-dataset-scene-1
               |——— seq-01
               |——— seq-02
               |——— camera-intrinsics.txt
               |——— ...
          |——— ...
     |——— test
          |——— rgbd-dataset-scene-2
               |——— seq-01
               |——— camera-intrinsics.txt
               |——— ...

多帧深度TSDF融合

请参阅3dmatch-toolbox/depth-fusion文件夹。

用于将多个配准后的深度图融合为TSDF体素体积的CUDA/C++代码（Curless和Levoy 1996），随后可用于生成表面网格和点云。

示例

此示例将data/sample/depth-fusion-demo/rgbd-frames目录下的50个配准后深度图融合为TSDF体素体积，并生成一个表面点云tsdf.ply。

cd 3dmatch-toolbox/depth-fusion
./compile.sh
./demo # 输出保存到tsdf.ply

评估代码

请参阅3dmatch-toolbox/evaluation文件夹。

用于关键点匹配基准测试和几何配准基准测试的评估代码，以及我们论文中实验的参考实现。

关键点匹配基准测试

请参阅文件夹 3dmatch-toolbox/evaluation/keypoint-matching。

基准测试的说明和排行榜可以在这里找到：http://3dmatch.cs.princeton.edu/#keypoint-matching-benchmark。

评估示例

0. 导航到 3dmatch-toolbox/evaluation/keypoint-matching，并在 MATLAB 中运行以下命令：

   % 在验证集（validation-set-gt.log）上评估 3DMatch（3dmatch.log）
   getError;
   

在验证集上运行 3DMatch 以生成 .log 文件（3dmatch.log）

0. 编译 C++/CUDA 代码，使用 Marvin 计算 3DMatch 描述符：

   cd 3dmatch-toolbox/evaluation/keypoint-matching
   ./compile.sh
   

1. 下载我们的 3DMatch 预训练权重：

   ./download-weights.sh # 3dmatch-weights-snapshot-137000.marvin
   

2. 下载验证集和测试集：

   ./download-validation.sh # validation-set.mat
   ./download-test.sh # test-set.mat
   

3. 修改并运行以下 MATLAB 脚本：

   % 在验证集上运行 3DMatch，并生成 3dmatch.log
   test3DMatch;
   

从 RGB-D 重建数据集 中生成您自己的对应关系数据集

0. 从我们项目网页上的 RGB-D 重建数据集下载一个或多个场景：http://3dmatch.cs.princeton.edu/#rgbd-reconstruction-datasets。按照上述文件夹结构组织文件夹。

1. 修改并运行以下 MATLAB 脚本：

   makeCorresDataset;
   

几何配准基准测试

请参阅文件夹 3dmatch-toolbox/evaluation/geometric-registration。

包含用于在几何配准基准测试上进行评估的 MATLAB 代码，这些基准测试的描述见这里。概述如下：

• getKeyptsAndDesc.m - 为场景片段生成中间数据（TDF 体素网格、关键点和 3DMatch 描述符）。您也可以从这里下载我们预先计算好的数据。
• runFragmentRegistration.m - 读取中间数据，并对每一对片段执行基于 RANSAC 的配准。
• writeLog - 读取每一对片段的配准结果，并创建 .log 文件。
• evaluate.m - 根据 .log 文件计算精确率和召回率以进行评估。

评估示例

在 MATLAB 中运行以下命令：

% 在几何配准基准测试上评估 3DMatch
evaluate;

注意：合成基准测试中场景片段的 TDF 体素网格是使用已弃用的精确 TDF 代码计算的（参见 deprecated/pointCloud2AccTDF.m）。在训练片段上微调过的 3DMatch 预训练权重可以从这里下载。

亚马逊拣选挑战中的 6D 物体位姿估计模型拟合

请参阅文件夹 3dmatch-toolbox/evaluation/model-fitting-apc。

包含用于在 Shelf & Tote 数据集 上评估 3DMatch 模型拟合的代码和预训练模型。您可以从这里下载我们预先计算的数据（物体和扫描的 TDF 体素网格体积、表面关键点、描述符以及位姿预测）。要进行评估示例，请运行 MATLAB 脚本 getError.m。

Shape2Pose 中的网格对应关系

请参阅文件夹 3dmatch-toolbox/evaluation/mesh-correspondence-shape2pose。

包含用于在 Shape2Pose 数据集 的网格上，使用 3DMatch 生成网格对应关系可视化效果的代码。您也可以从这里下载我们预先计算的数据（网格的 TDF 体素网格体积、表面关键点、3DMatch 描述符）。要快速查看可视化效果，请运行 MATLAB 脚本 keypointRetrieval.m。

3DMatch Toolbox 快速上手指南

3DMatch 是一个基于卷积神经网络（ConvNet）的局部几何特征描述子，专为 3D 数据（如点云、深度图、网格等）设计。本工具箱提供了使用 3DMatch 进行几何配准和关键点匹配的代码，以及从现有 RGB-D 重建数据中训练模型的流程。

环境准备

本参考实现主要在 Ubuntu 14.04 上测试通过，其他 Linux 发行版可能也需要类似的环境配置。

系统要求与依赖

请确保安装以下核心依赖：

1. CUDA 与 cuDNN

   • CUDA 7.5
   • cuDNN 5.1
   • 注意：建议将不同版本的 cuDNN 安装到独立目录（如 /usr/local/cudnn/v5.1），以避免版本冲突。

2. OpenCV

   • 版本：2.4.11 或兼容版本（用于读取图像文件）。

3. Matlab

   • 版本：2015b 或更高（推荐 2016a）。

4. 编译工具

   • GCC, G++, Make 等基础构建工具。

安装步骤

1. 配置 cuDNN 5.1

下载 cuDNN 后，执行以下命令将其配置到指定目录并更新环境变量：

LIB_DIR=lib$([[ $(uname) == "Linux" ]] && echo 64)
CUDNN_LIB_DIR=/usr/local/cudnn/v5.1/$LIB_DIR
echo LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CUDNN_LIB_DIR >> ~/.profile && source ~/.profile

tar zxvf cudnn*.tgz
sudo cp cuda/$LIB_DIR/* $CUDNN_LIB_DIR/
sudo cp cuda/include/* /usr/local/cudnn/v5.1/include/

2. 克隆代码并编译核心库

获取源代码并编译 C++/CUDA 演示代码及 Marvin 框架：

git clone https://github.com/andyzeng/3dmatch-toolbox.git 3dmatch-toolbox
cd 3dmatch-toolbox/core
./compile.sh

3. 下载预训练权重

下载官方提供的预训练模型文件：

cd ..
./download-weights.sh # 将下载 3dmatch-weights-snapshot-137000.marvin

基本使用：点云配准演示

本示例展示如何使用预训练的 3DMatch 描述子和 RANSAC 算法对齐两个 3D 点云。

注意：演示代码默认仅读取简单的二进制格式点云。如果您需要处理其他格式（如 .ply），需修改 demo.cu 中的读取逻辑。以下步骤假设您已准备好名为 single-depth-1.ply 和 single-depth-2.ply 的测试数据（位于 ../data/sample/3dmatch-demo/）。

第一步：生成特征描述子

运行编译好的 demo 程序，计算点云的 TDF 体素网格、随机表面关键点及其 3DMatch 描述子。

# 为第一个片段生成描述子 (.desc.3dmatch.bin) 和关键点 (.keypts.bin)
./demo ../data/sample/3dmatch-demo/single-depth-1.ply fragment-1

# 为第二个片段生成描述子和关键点
./demo ../data/sample/3dmatch-demo/single-depth-2.ply fragment-2 

第二步：执行配准 (Matlab)

在 Matlab 中运行 demo 脚本。该脚本会加载上述生成的二进制文件，利用 RANSAC 算法计算变换矩阵并对齐点云，最终输出 result.ply 文件。

% 在 Matlab 命令行中执行
demo;

说明：由于关键点默认是随机选择的，首次运行可能会因关键点质量不佳导致配准失败。若发生此情况，重新运行 demo 脚本即可再次尝试。

生成的 result.ply 可使用 Meshlab 或其他 3D 查看器查看对齐效果。