3dmatch toolbox
1.0.0
3DMatch 是一种基于 ConvNet 的局部几何特征描述符，可对 3D 数据（即点云、深度图、网格等）进行操作。该工具箱提供了使用 3DMatch 进行几何配准和关键点匹配的代码，以及从现有 RGB-D 重建中训练 3DMatch 的代码。这是我们论文的参考实现：
PDF |网页、基准和数据集 |视频
Andy Zeng、Shuran Song、Matthias Nießner、Matthew Fisher、Jianxiong Shaw 和 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{ s s}ner, Matthias and Fisher, Matthew and Xiao, Jianxiong and Funkhouser, Thomas},
booktitle={CVPR},
year={2017}
}此代码在简化 BSD 许可证下发布（有关详细信息，请参阅许可证文件）。
所有相关信息和下载都可以在这里找到。
如果您有任何疑问或发现任何错误，请告诉我：Andy Zeng andyz[at]princeton[dot]edu
#include <random> 。我们的 3DMatch 参考实现以及此工具箱中的其他组件需要以下依赖项。在 Ubuntu 14.04 上测试。
CUDA 7.5 和 cuDNN 5.1。您可能需要向 NVIDIA 注册。以下是设置 cuDNN 5.1 的一些附加步骤。注意我们强烈建议您将不同版本的 cuDNN 安装到不同的目录（例如/usr/local/cudnn/vXX ），因为不同的软件包可能需要不同的版本。
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/OpenCV（使用 OpenCV 2.4.11 测试）
该演示使用我们预先训练的 3DMatch 描述符（使用 Marvin）和标准 RANSAC 对齐两个 3D 点云（从单视图深度图投影）。
查看 3DMatch 工具箱，编译 C++/CUDA 演示代码和 Marvin
git clone https://github.com/andyzeng/3dmatch-toolbox.git 3dmatch-toolbox
cd 3dmatch-toolbox/core
./compile.sh下载我们的 3DMatch 预训练权重
./download-weights.sh # 3dmatch-weights-snapshot-137000.marvin加载两个示例 3D 点云，计算其 TDF 体素网格体积，并计算随机表面关键点及其 3DMatch 描述符（保存到磁盘上的二进制文件）。警告：此演示仅读取以简单二进制格式保存的 3D 点云。如果您想在自己的点云格式上运行 3DMatch 演示代码，请相应地修改 demo.cu。
# Generate fragment-1.desc.3dmatch.bin and fragment-1.keypts.bin
./demo ../data/sample/3dmatch-demo/single-depth-1.ply fragment-1
# Generate fragment-2.desc.3dmatch.bin and fragment-2.keypts.bin
./demo ../data/sample/3dmatch-demo/single-depth-2.ply fragment-2 在 Matlab 中运行以下脚本：
% Load keypoints and 3DMatch descriptors and use RANSAC to register the two
% point clouds. A visualization of the aligned point clouds is saved into
% the file `result.ply` which can be viewed with Meshlab or any other 3D
% viewer. Note: there is a chance that alignment may fail on the first try
% of this demo due to bad keypoints, which are selected randomly by default.
demo ;有关如何将各种 3D 数据表示转换为截断距离函数 (TDF) 值的体素网格的说明。
有关安装 GAPS 并将示例网格（.off 文件）转换为体素网格（浮点数的二进制 .raw 文件）的说明：
cd 3dmatch-toolbox/gaps
# Install GAPS
make
# Run msh2df on example mesh file (see comments in msh2df.cpp for more instructions)
cd bin/x86_64
wget http://vision.princeton.edu/projects/2016/3DMatch/downloads/gaps/bicycle000002.off
./msh2df bicycle000002.off bicycle000002.raw -v # see comments in msh2df.cpp for more arguments
# Download visualization script
wget http://vision.princeton.edu/projects/2016/3DMatch/downloads/gaps/showTDF.m在 Matlab 中运行可视化脚本
% Visualize TDF voxel grid of mesh
showTDF ;请参阅文件夹3dmatch-toolbox/training
使用 Marvin（一种仅使用 GPU 的轻量级神经网络框架）训练 3DMatch 的代码。包括 Siamese 网络架构 .json 文件training/net.json和training/match.hpp中的CUDA/C++ Marvin 数据层，该数据层从RGB-D 重建数据集（可以从我们的项目网页下载）中随机采样对应关系。
编译马文
cd 3dmatch-toolbox/training
./compile.sh从 RGB-D 重建数据集中下载多个训练和测试场景（在此处下载更多场景）
cd ../data
mkdir train && mkdir test && mkdir backup
cd train
wget http://vision.princeton.edu/projects/2016/3DMatch/downloads/rgbd-datasets/sun3d-brown_cogsci_1-brown_cogsci_1.zip
wget http://vision.princeton.edu/projects/2016/3DMatch/downloads/rgbd-datasets/7-scenes-heads.zip
wget http://vision.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://vision.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根据data/train中保存的 RGB-D 场景的对应关系从头开始训练 3DMatch 模型
./marvin train net.json（可选）使用 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
| ——— ...请参阅文件夹3dmatch-toolbox/depth-fusion
CUDA/C++ 代码将多个注册深度图融合到 TSDF 体素体积中（Curless 和 Levoy 1996），然后可用于创建表面网格和点云。
此演示将目录data/sample/depth-fusion-demo/rgbd-frames中的 50 个注册深度图融合到 TSDF 体素体积中，并创建表面点云tsdf.ply
cd 3dmatch-toolbox/depth-fusion
./compile.sh
./demo # output saved to tsdf.ply 请参阅文件夹3dmatch-toolbox/evaluation
关键点匹配基准和几何配准基准的评估代码，以及我们论文中实验的参考实现。
请参阅文件夹3dmatch-toolbox/evaluation/keypoint-matching
可以在此处找到基准描述和排行榜。
导航到3dmatch-toolbox/evaluation/keypoint-matching并在 Matlab 中运行以下命令：
% Evaluate 3DMatch (3dmatch.log) on the validation set (validation-set-gt.log)
getError ;使用 Marvin 编译 C++/CUDA 代码以计算 3DMatch 描述符
cd 3dmatch-toolbox/evaluation/keypoint-matching
./compile.sh下载我们的 3DMatch 预训练权重
./download-weights.sh # 3dmatch-weights-snapshot-137000.marvin下载验证集和测试集
./download-validation.sh # validation-set.mat
./download-test.sh # test-set.mat在Matlab中修改并运行以下脚本：
% Runs 3DMatch on the validation set and generates 3dmatch.log
test3DMatch ;从我们的项目网页上的 RGB-D 重建数据集下载一个或多个场景。按上述方式组织文件夹层次结构。
在Matlab中修改并运行以下脚本：
makeCorresDataset ;请参阅文件夹3dmatch-toolbox/evaluation/geometric-registration
包括 Matlab 代码，用于对此处描述的几何配准基准运行评估。概述：
getKeyptsAndDesc.m - 生成场景片段的中间数据（TDF 体素体积、关键点和 3DMatch 描述符）。您还可以在此处下载我们预先计算的数据。runFragmentRegistration.m - 读取中间数据并为每对片段运行基于 RANSAC 的注册。writeLog - 从每对片段中读取注册结果并创建一个 .log 文件evaluate.m - 计算 .log 文件的精度和召回率以进行评估在 Matlab 中运行以下命令：
% Evaluate 3DMatch on the geometric registration benchmark
evaluate ;注意：合成基准中场景片段的 TDF 体素网格是使用已弃用的代码计算的，以获得准确的 TDF（请参阅deprecated/pointCloud2AccTDF.m ）。可以在此处下载在训练片段上微调的 3DMatch 预训练权重。
请参阅文件夹3dmatch-toolbox/evaluation/model-fitting-apc
包括代码和预训练模型，用于评估 3DMatch 以在 Shelf & Tote 数据集上进行模型拟合。您可以在此处下载我们预先计算的数据（对象和扫描的 TDF 体素网格体积、表面关键点、描述符和姿势预测）。对于评估示例，请运行 Matlab 脚本getError.m
请参阅文件夹3dmatch-toolbox/evaluation/mesh-correspondence-shape2pose
包含使用 3DMatch 在 Shape2Pose 数据集的网格上生成网格对应可视化的代码。您还可以在此处下载我们预先计算的数据（网格的 TDF 体素网格体积、表面关键点、3DMatch 描述符）。要快速可视化，请运行 Matlab 脚本keypointRetrieval.m 。
