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>年 11 月 2 日。我們的 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 。
