3dmatch toolbox
1.0.0
3DMatch ist ein ConvNet-basierter Deskriptor für lokale geometrische Merkmale, der mit 3D-Daten (z. B. Punktwolken, Tiefenkarten, Netze usw.) arbeitet. Diese Toolbox bietet Code zur Verwendung von 3DMatch für die geometrische Registrierung und Schlüsselpunktanpassung sowie Code zum Trainieren von 3DMatch aus vorhandenen RGB-D-Rekonstruktionen. Dies ist die Referenzimplementierung unseres Artikels:
PDF | Webseite & Benchmarks & Datensätze | Video
Andy Zeng, Shuran Song, Matthias Nießner, Matthew Fisher, Jianxiong Xiao und Thomas Funkhouser
IEEE-Konferenz zu Computer Vision und Mustererkennung (CVPR), mündliche Präsentation 2017
Die Anpassung lokaler geometrischer Merkmale an reale Tiefenbilder ist aufgrund der verrauschten, niedrig aufgelösten und unvollständigen Natur der 3D-Scandaten eine anspruchsvolle Aufgabe. Diese Schwierigkeiten schränken die Leistung aktueller Methoden nach dem Stand der Technik ein, die typischerweise auf Histogrammen über geometrischen Eigenschaften basieren. In diesem Artikel stellen wir 3DMatch vor, ein datengesteuertes Modell, das einen lokalen volumetrischen Patch-Deskriptor lernt, um Korrespondenzen zwischen partiellen 3D-Daten herzustellen. Um Trainingsdaten für unser Modell zu sammeln, schlagen wir eine unbeaufsichtigte Feature-Learning-Methode vor, die die Millionen von Korrespondenzbezeichnungen nutzt, die in vorhandenen RGB-D-Rekonstruktionen gefunden werden. Experimente zeigen, dass unser Deskriptor nicht nur in der Lage ist, die lokale Geometrie in neuen Szenen für die Rekonstruktion abzugleichen, sondern auch auf verschiedene Aufgaben und räumliche Maßstäbe zu verallgemeinern (z. B. Objektmodellausrichtung auf Instanzebene für die Amazon Picking Challenge und Netzoberflächenkorrespondenz). Die Ergebnisse zeigen, dass 3DMatch andere hochmoderne Ansätze durchweg deutlich übertrifft.
Wenn Sie diesen Code für Ihre Arbeit nützlich finden, denken Sie bitte darüber nach, Folgendes zu zitieren:
@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}
}Dieser Code wird unter der Simplified BSD-Lizenz veröffentlicht (Einzelheiten finden Sie in der LIZENZ-Datei).
Alle relevanten Informationen und Downloads finden Sie hier.
Wenn Sie Fragen haben oder Fehler finden, lassen Sie es mich bitte wissen: Andy Zeng andyz[at]princeton[dot]edu
#include <random> zu utils.hpp im Democode hinzugefügt.Unsere Referenzimplementierung von 3DMatch sowie andere Komponenten in dieser Toolbox erfordern die folgenden Abhängigkeiten. Getestet auf Ubuntu 14.04.
CUDA 7.5 und cuDNN 5.1. Möglicherweise müssen Sie sich bei NVIDIA registrieren. Nachfolgend finden Sie einige zusätzliche Schritte zum Einrichten von cuDNN 5.1. HINWEIS Wir empfehlen dringend, dass Sie verschiedene Versionen von cuDNN in verschiedenen Verzeichnissen installieren (z. B. /usr/local/cudnn/vXX ), da unterschiedliche Softwarepakete möglicherweise unterschiedliche Versionen erfordern.
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 (getestet mit OpenCV 2.4.11)
Diese Demo richtet zwei 3D-Punktwolken (projiziert aus Einzelansicht-Tiefenkarten) mithilfe unseres vorab trainierten 3DMatch-Deskriptors (mit Marvin) und Standard-RANSAC aus.
Testen Sie die 3DMatch-Toolbox, kompilieren Sie C++/CUDA-Democode und Marvin
git clone https://github.com/andyzeng/3dmatch-toolbox.git 3dmatch-toolbox
cd 3dmatch-toolbox/core
./compile.shLaden Sie unsere vorab trainierten 3DMatch-Gewichte herunter
./download-weights.sh # 3dmatch-weights-snapshot-137000.marvinLaden Sie die beiden Beispiel-3D-Punktwolken, berechnen Sie ihre TDF-Voxel-Gittervolumina und berechnen Sie zufällige Oberflächenschlüsselpunkte und ihre 3DMatch-Deskriptoren (in Binärdateien auf der Festplatte gespeichert). Warnung: Diese Demo liest nur 3D-Punktwolken, die in einem einfachen Binärformat gespeichert sind. Wenn Sie den 3DMatch-Democode in Ihrem eigenen Punktwolkenformat ausführen möchten, ändern Sie bitte demo.cu entsprechend.
# 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 Führen Sie das folgende Skript in Matlab aus:
% 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 ;Anweisungen zum Konvertieren verschiedener 3D-Datendarstellungen in ein Voxelgitter aus TDF-Werten (Truncated Distance Function).
Anweisungen zur Installation von GAPS und zum Konvertieren eines Beispielnetzes (.off-Datei) in ein Voxelgitter (binäre .raw-Datei mit Floats):
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.mFühren Sie das Visualisierungsskript in Matlab aus
% Visualize TDF voxel grid of mesh
showTDF ; Siehe Ordner 3dmatch-toolbox/training
Code zum Trainieren von 3DMatch mit Marvin, einem leichten, reinen GPU-Framework für neuronale Netzwerke. Enthält die .json-Datei training/net.json der siamesischen Netzwerkarchitektur und eine CUDA/C++-Marvin-Datenschicht in training/match.hpp , die zufällig Korrespondenzen aus RGB-D-Rekonstruktionsdatensätzen abtastet (die von unserer Projektwebseite heruntergeladen werden können).
Kompilieren Sie Marvin
cd 3dmatch-toolbox/training
./compile.shLaden Sie mehrere Trainings- und Testszenen aus RGB-D-Rekonstruktionsdatensätzen herunter (weitere Szenen hier herunterladen)
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 Trainieren Sie ein 3DMatch-Modell von Grund auf anhand von Korrespondenzen aus den in data/train gespeicherten RGB-D-Szenen
./marvin train net.json(Optional) Trainieren Sie 3DMatch mit vorab trainierten Gewichten aus einer Marvin-Tensor-Datei
./marvin train net.json your-pre-trained-weights.marvin Weitere Szenen aus RGB-D-Rekonstruktionsdatensätzen können Sie auf unserer Projektwebseite herunterladen. Diese Datensätze wurden in ein einheitliches Format konvertiert, das mit unserer Marvin-Datenschicht kompatibel ist, die zum Trainieren von 3DMatch verwendet wird. Speichern Sie mindestens eine Szene in data/train und eine weitere Szene in data/test sodass die Ordnerhierarchie etwa so aussieht:
| ——— 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
| ——— ... Siehe Ordner 3dmatch-toolbox/depth-fusion
CUDA/C++-Code zum Zusammenführen mehrerer registrierter Tiefenkarten zu einem TSDF-Voxelvolumen (Curless und Levoy 1996), das dann zum Erstellen von Oberflächennetzen und Punktwolken verwendet werden kann.
Diese Demo verschmilzt 50 registrierte Tiefenkarten aus dem Verzeichnis data/sample/depth-fusion-demo/rgbd-frames in einem TSDF-Voxelvolumen und erstellt eine Oberflächenpunktwolke tsdf.ply
cd 3dmatch-toolbox/depth-fusion
./compile.sh
./demo # output saved to tsdf.ply Siehe Ordner 3dmatch-toolbox/evaluation
Evaluierungscode für den Keypoint Matching Benchmark und den Geometric Registration Benchmark sowie eine Referenzimplementierung für die Experimente in unserem Artikel.
Siehe Ordner 3dmatch-toolbox/evaluation/keypoint-matching
Die Benchmark-Beschreibung und die Bestenliste finden Sie hier.
Navigieren Sie zu 3dmatch-toolbox/evaluation/keypoint-matching und führen Sie Folgendes in Matlab aus:
% Evaluate 3DMatch (3dmatch.log) on the validation set (validation-set-gt.log)
getError ;Kompilieren Sie C++/CUDA-Code, um 3DMatch-Deskriptoren mit Marvin zu berechnen
cd 3dmatch-toolbox/evaluation/keypoint-matching
./compile.shLaden Sie unsere vorab trainierten 3DMatch-Gewichte herunter
./download-weights.sh # 3dmatch-weights-snapshot-137000.marvinLaden Sie den Validierungssatz und den Testsatz herunter
./download-validation.sh # validation-set.mat
./download-test.sh # test-set.matÄndern Sie das folgende Skript und führen Sie es in Matlab aus:
% Runs 3DMatch on the validation set and generates 3dmatch.log
test3DMatch ;Laden Sie eine oder mehrere Szenen aus RGB-D-Rekonstruktionsdatensätzen auf unserer Projektwebseite herunter. Organisieren Sie die Ordnerhierarchie wie oben.
Ändern Sie das folgende Skript und führen Sie es in Matlab aus:
makeCorresDataset ; Siehe Ordner 3dmatch-toolbox/evaluation/geometric-registration
Enthält Matlab-Code zur Durchführung einer Auswertung der hier beschriebenen geometrischen Registrierungs-Benchmarks. Überblick:
getKeyptsAndDesc.m – generiert Zwischendaten (TDF-Voxelvolumina, Schlüsselpunkte und 3DMatch-Deskriptoren) für die Szenenfragmente. Sie können hier auch unsere vorberechneten Daten herunterladen.runFragmentRegistration.m – Zwischendaten lesen und RANSAC-basierte Registrierung für jedes Fragmentpaar ausführen.writeLog – Registrierungsergebnisse aus jedem Fragmentpaar lesen und eine .log-Datei erstellenevaluate.m – Genauigkeit berechnen und aus .log-Dateien zur Auswertung abrufen Führen Sie Folgendes in Matlab aus:
% Evaluate 3DMatch on the geometric registration benchmark
evaluate ; Hinweis: Die TDF-Voxelgitter der Szenenfragmente aus dem synthetischen Benchmark wurden mit dem veralteten Code für genaues TDF berechnet (siehe deprecated/pointCloud2AccTDF.m ). Die vorab trainierten 3DMatch-Gewichte, die auf Trainingsfragmente abgestimmt sind, können hier heruntergeladen werden.
Siehe Ordner 3dmatch-toolbox/evaluation/model-fitting-apc
Enthält Code und vorab trainierte Modelle zur Evaluierung von 3DMatch hinsichtlich der Modellanpassung an den Shelf & Tote-Datensatz. Sie können unsere vorberechneten Daten (TDF-Voxelgittervolumina für Objekte und Scans, Oberflächenschlüsselpunkte, Deskriptoren und Posenvorhersagen) hier herunterladen. Für ein Evaluierungsbeispiel führen Sie das Matlab-Skript getError.m aus
Siehe Ordner 3dmatch-toolbox/evaluation/mesh-correspondence-shape2pose
Enthält Code zum Generieren von Netzkorrespondenzvisualisierungen auf den Netzen aus dem Shape2Pose-Datensatz mithilfe von 3DMatch. Sie können hier auch unsere vorberechneten Daten (TDF-Voxelgittervolumina der Netze, Oberflächenschlüsselpunkte, 3DMatch-Deskriptoren) herunterladen. Führen Sie für eine schnelle Visualisierung das Matlab-Skript keypointRetrieval.m aus.
