[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"tool-andyzeng--3dmatch-toolbox":3,"similar-andyzeng--3dmatch-toolbox":126},{"id":4,"github_repo":5,"name":6,"description_en":7,"description_zh":8,"ai_summary_zh":8,"readme_en":9,"readme_zh":10,"quickstart_zh":11,"use_case_zh":12,"hero_image_url":13,"owner_login":14,"owner_name":15,"owner_avatar_url":16,"owner_bio":17,"owner_company":17,"owner_location":17,"owner_email":17,"owner_twitter":17,"owner_website":18,"owner_url":19,"languages":20,"stars":54,"forks":55,"last_commit_at":56,"license":57,"difficulty_score":58,"env_os":59,"env_gpu":60,"env_ram":61,"env_deps":62,"category_tags":71,"github_topics":75,"view_count":86,"oss_zip_url":17,"oss_zip_packed_at":17,"status":87,"created_at":88,"updated_at":89,"faqs":90,"releases":125},6419,"andyzeng\u002F3dmatch-toolbox","3dmatch-toolbox","3DMatch - a 3D ConvNet-based local geometric descriptor for aligning 3D meshes and point clouds.","3dmatch-toolbox 是一套基于深度学习的开源工具包，核心功能是生成用于对齐三维网格和点云的局部几何描述符。在三维重建、机器人导航及增强现实等领域，原始扫描数据往往存在噪声大、分辨率低或缺失部分细节等问题，导致传统基于几何直方图的方法难以精准匹配局部特征。3dmatch-toolbox 通过数据驱动的方式有效解决了这一难题，它能从含噪的深度图像中学习鲁棒的体积块描述符，从而在不同场景、尺度甚至任务间建立可靠的对应关系，显著提升配准精度。\n\n该工具包不仅提供了预训练模型以直接进行几何注册和关键点匹配，还包含完整的代码供用户利用现有的 RGB-D 重建数据从头训练模型。其独特的技术亮点在于提出了一种无监督特征学习方法，能够巧妙利用海量现有重建数据中的对应标签进行训练，无需昂贵的人工标注。3dmatch-toolbox 主要面向计算机视觉研究人员、三维算法开发者以及相关领域的工程师，特别适合需要处理复杂真实世界三维数据、追求高精度匹配效果的专业用户。作为 2017 年 CVPR 口头报告论文的成果，它在多项基准测试中均表现出优于当时最先进方法的性能。","# 3DMatch Toolbox\n3DMatch is a ConvNet-based local geometric feature descriptor that operates on 3D data (i.e. point clouds, depth maps, meshes, etc.). This toolbox provides code to use 3DMatch for geometric registration and keypoint matching, as well as code to train 3DMatch from existing RGB-D reconstructions. This is the reference implementation of our paper:\n\n### 3DMatch: Learning Local Geometric Descriptors from RGB-D Reconstructions\n\n[PDF](https:\u002F\u002Farxiv.org\u002Fpdf\u002F1603.08182.pdf) | [Webpage & Benchmarks & Datasets](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F) | [Video](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=gZrsJJtDvvA)\n\n*[Andy Zeng](http:\u002F\u002Fandyzeng.com\u002F), [Shuran Song](http:\u002F\u002F3dvision.princeton.edu\u002Fpeople\u002Fshurans\u002F), [Matthias Nießner](http:\u002F\u002Fwww.niessnerlab.org\u002Fmembers\u002Fmatthias_niessner\u002Fprofile.html), [Matthew Fisher](https:\u002F\u002Fresearch.adobe.com\u002Fperson\u002Fmatt-fisher\u002F), [Jianxiong Xiao](http:\u002F\u002F3dvision.princeton.edu\u002Fpeople\u002Fxj\u002F), and [Thomas Funkhouser](http:\u002F\u002Fwww.cs.princeton.edu\u002F~funk\u002F)*\n\nIEEE Conference on Computer Vision and Pattern Recognition (CVPR) 2017 **[Oral Presentation](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=qNVZl7bCjsU&list=PL_bDvITUYucADb15njRd7geem8vxOyo6N&index=3)**\n\nMatching local geometric features on real-world depth images is a challenging task due to the noisy, low-resolution, and incomplete nature of 3D scan data. These difficulties limit the performance of current state-of-art methods, which are typically based on histograms over geometric properties. In this paper, we present 3DMatch, a data-driven model that learns a local volumetric patch descriptor for establishing correspondences between partial 3D data. To amass training data for our model, we propose an unsupervised feature learning method that leverages the millions of correspondence labels found in existing RGB-D reconstructions. Experiments show that our descriptor is not only able to match local geometry in new scenes for reconstruction, but also generalize to different tasks and spatial scales (e.g. instance-level object model alignment for the Amazon Picking Challenge, and mesh surface correspondence). Results show that 3DMatch consistently outperforms other state-of-the-art approaches by a significant margin. \n\n![Overview](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fandyzeng_3dmatch-toolbox_readme_dfdd7bea4db4.jpg)\n\n#### Citing\n\nIf you find this code useful in your work, please consider citing:\n\n```shell\n@inproceedings{zeng20163dmatch, \n\ttitle={3DMatch: Learning Local Geometric Descriptors from RGB-D Reconstructions}, \n\tauthor={Zeng, Andy and Song, Shuran and Nie{\\ss}ner, Matthias and Fisher, Matthew and Xiao, Jianxiong and Funkhouser, Thomas}, \n\tbooktitle={CVPR}, \n\tyear={2017} \n}\n```\n\n#### License\n\nThis code is released under the Simplified BSD License (refer to the LICENSE file for details).\n\n#### Benchmarks and Datasets\nAll relevant information and downloads can be found [here](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F).\n\n#### Contact\nIf you have any questions or find any bugs, please let me know: [Andy Zeng](http:\u002F\u002Fwww.cs.princeton.edu\u002F~andyz\u002F) andyz[at]princeton[dot]edu\n\n## Change Log\n* **Mar. 20, 2018.** Update: added labels for test-set of keypoint matching benchmark (for convenience).\n* **Nov. 02, 2017.** Bug fix: added `#include \u003Crandom>` to utils.hpp in demo code.\n* **Oct. 30, 2017.** Bug fix: included Quoc-Huy's fix for NaN errors that occasionally occur during training.\n* **Oct. 28, 2017.** Notice: demo code only reads 3D point clouds saved in a simple binary format. If you would like to run the 3DMatch demo code on your own point cloud format, please modify demo.cu accordingly.\n* **Apr. 06, 2017.** Notice: 3DMatch uses cuDNN 5.1. Revised install instructions.\n\n## Dependencies\n\nOur reference implementation of 3DMatch, as well as other components in this toolbox, require the following dependencies. Tested on Ubuntu 14.04.\n\n0. [CUDA 7.5](https:\u002F\u002Fdeveloper.nvidia.com\u002Fcuda-toolkit-archive) and [cuDNN 5.1](https:\u002F\u002Fdeveloper.nvidia.com\u002Fcudnn). You may need to register with NVIDIA. Below are some additional steps to set up cuDNN 5.1. **NOTE** We highly recommend that you install different versions of cuDNN to different directories (e.g., ```\u002Fusr\u002Flocal\u002Fcudnn\u002FvXX```) because different software packages may require different versions.\n\n\t```shell\n\tLIB_DIR=lib$([[ $(uname) == \"Linux\" ]] && echo 64)\n\tCUDNN_LIB_DIR=\u002Fusr\u002Flocal\u002Fcudnn\u002Fv5.1\u002F$LIB_DIR\n\techo LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CUDNN_LIB_DIR >> ~\u002F.profile && ~\u002F.profile\n\n\ttar zxvf cudnn*.tgz\n\tsudo cp cuda\u002F$LIB_DIR\u002F* $CUDNN_LIB_DIR\u002F\n\tsudo cp cuda\u002Finclude\u002F* \u002Fusr\u002Flocal\u002Fcudnn\u002Fv5.1\u002Finclude\u002F\n\t```\n\n0. OpenCV (tested with OpenCV 2.4.11)\n * Used for reading image files\n\n0. Matlab 2015b or higher (tested with Matlab 2016a)\n\n## Table of Contents\n* [Demo: Align Two Point Clouds with 3DMatch](#demo-align-two-point-clouds-with-3dmatch)\n* [Converting 3D Data to TDF Voxel Grids](#converting-3d-data-to-tdf-voxel-grids)\n* [Training 3DMatch from RGB-D Reconstructions](#training-3dmatch-from-rgb-d-reconstructions)\n* [Multi-Frame Depth TSDF Fusion](#multi-frame-depth-tsdf-fusion)\n* [Evaluation Code](#evaluation-code)\n\n## Demo: Align Two Point Clouds with 3DMatch\n\n![Demo-Teaser](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fandyzeng_3dmatch-toolbox_readme_b6dc47ff9ec6.jpg)\n\nThis demo aligns two 3D point clouds (projected from single-view depth maps) using our pre-trained 3DMatch descriptor (with Marvin) and standard RANSAC.\n\n### Instructions\n\n0. Checkout 3DMatch toolbox, compile C++\u002FCUDA demo code and Marvin\n\n\t```shell\n\tgit clone https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox.git 3dmatch-toolbox\n\tcd 3dmatch-toolbox\u002Fcore\n\t.\u002Fcompile.sh\n\t```\n\n0. Download our 3DMatch pre-trained weights\n\n\t```shell\n\t.\u002Fdownload-weights.sh # 3dmatch-weights-snapshot-137000.marvin\n\t```\n\n0. Load the two example 3D point clouds, compute their TDF voxel grid volumes, and compute random surface keypoints and their 3DMatch descriptors (saved to binary files on disk). Warning: this demo only reads 3D point clouds saved in a simple binary format. If you would like to run the 3DMatch demo code on your own point cloud format, please modify demo.cu accordingly.\n\n\t```shell\n\t# Generate fragment-1.desc.3dmatch.bin and fragment-1.keypts.bin\n\t.\u002Fdemo ..\u002Fdata\u002Fsample\u002F3dmatch-demo\u002Fsingle-depth-1.ply fragment-1\n\n\t# Generate fragment-2.desc.3dmatch.bin and fragment-2.keypts.bin\n\t.\u002Fdemo ..\u002Fdata\u002Fsample\u002F3dmatch-demo\u002Fsingle-depth-2.ply fragment-2 \n\t```\n\n0. Run the following script in Matlab:\n\n\t```matlab\n\t% Load keypoints and 3DMatch descriptors and use RANSAC to register the two\n\t% point clouds. A visualization of the aligned point clouds is saved into\n\t% the file `result.ply` which can be viewed with Meshlab or any other 3D\n\t% viewer. Note: there is a chance that alignment may fail on the first try\n\t% of this demo due to bad keypoints, which are selected randomly by default.\n\tdemo;\n\t```\n\n## Converting 3D Data to TDF Voxel Grids\n\nInstructions on how to convert from various 3D data representations into a voxel grid of Truncated Distance Function (TDF) values.\n\n0. Point cloud to TDF voxel grid (using nearest neighbor point distances)\n * See [C++\u002FCUDA demo code](https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fblob\u002Fmaster\u002Fcore\u002Fdemo.cu) (ComputeTDF) which approximates TDF values (fast) using an occupancy voxel grid.\n * Alternative: See [Matlab\u002FCUDA code](https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fblob\u002Fmaster\u002Fdeprecated\u002FpointCloud2AccTDF.m) which computes accurate TDF values but is very slow.\n * Alternative: See [Matlab code](https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fblob\u002Fmaster\u002Fevaluation\u002Fmodel-fitting-apc\u002FpointCloud2TDF.m) which also computes accurate TDF values, but works standalone on Matlab. Usually runs without memory problems if your point cloud is small.\n\n0. Mesh to TDF voxel grid (using distance transform of mesh surface with [GAPS](https:\u002F\u002Fgithub.com\u002Ftomfunkhouser\u002Fgaps)). Note that a version of GAPS is already included in this repository.\n * Instructions on installing GAPS and converting a sample mesh (.off file) into a voxel grid (binary .raw file of floats):\n\n\t```shell\n\tcd 3dmatch-toolbox\u002Fgaps\n\n\t# Install GAPS\n\tmake\n\n\t# Run msh2df on example mesh file (see comments in msh2df.cpp for more instructions)\n\tcd bin\u002Fx86_64\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fgaps\u002Fbicycle000002.off\n\t.\u002Fmsh2df bicycle000002.off bicycle000002.raw -v # see comments in msh2df.cpp for more arguments\n\n\t# Download visualization script\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fgaps\u002FshowTDF.m\n\t```\n * Run the visualization script in Matlab\n\n\t```matlab\n\t% Visualize TDF voxel grid of mesh\n\tshowTDF;\n\t```\n\n0. Depth map to TDF voxel grid\n * Project depth map into a point cloud in 3D camera space and convert from point cloud to TDF voxel grid (see above)\n * Alternative: Convert from depth map(s) into a TSDF volume (see instructions [here](#multi-frame-depth-tsdf-fusion)) and compute the absolute value of each voxel (aka. projective TDF values, which behave differently near the view boundaries and regions of missing depth)\n\n## Training 3DMatch from RGB-D Reconstructions\n\nSee folder `3dmatch-toolbox\u002Ftraining`\n\nCode for training 3DMatch with [Marvin](http:\u002F\u002Fmarvin.is\u002F), a lightweight GPU-only neural network framework. Includes Siamese network architecture .json file `training\u002Fnet.json` and a CUDA\u002FC++ Marvin data layer in `training\u002Fmatch.hpp` that randomly samples correspondences from RGB-D reconstruction datasets (which can be downloaded from our [project webpage](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets)).\n\n### Quick Start\n0. Compile Marvin\n\t\n\t```shell\n\tcd 3dmatch-toolbox\u002Ftraining\n\t.\u002Fcompile.sh\n\t```\n\n0. Download several training and testing scenes from RGB-D reconstruction datasets (download more scenes [here](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets))\n\n\t```shell\n\tcd ..\u002Fdata\n\tmkdir train && mkdir test && mkdir backup\n\tcd train\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Frgbd-datasets\u002Fsun3d-brown_cogsci_1-brown_cogsci_1.zip\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Frgbd-datasets\u002F7-scenes-heads.zip\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Frgbd-datasets\u002Fsun3d-harvard_c11-hv_c11_2.zip\n\tunzip sun3d-brown_cogsci_1-brown_cogsci_1.zip\n\tunzip 7-scenes-heads.zip\n\tunzip sun3d-harvard_c11-hv_c11_2.zip\n\tmv *.zip ..\u002Fbackup\n\tcd ..\u002Ftest\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Frgbd-datasets\u002Fsun3d-hotel_umd-maryland_hotel3.zip\n\tunzip sun3d-hotel_umd-maryland_hotel3.zip\n\tmv *.zip ..\u002Fbackup\n\tcd ..\u002F..\u002Ftraining\n\t```\n\n0. Train a 3DMatch model from scratch over correspondences from the RGB-D scenes saved in `data\u002Ftrain`\n\n\t```shell\n\t.\u002Fmarvin train net.json\n\t```\n\n0. (Optional) Train 3DMatch using pre-trained weights from a Marvin tensor file\n\n\t```shell\n\t.\u002Fmarvin train net.json your-pre-trained-weights.marvin\n\t```\n\n### Additional Setup Instructions\nYou can download more scenes from RGB-D reconstruction datasets on our [project webpage](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets). These datasets have been converted into a unified format, which is compatible with our Marvin data layer used to train 3DMatch. Save at least one scene into `data\u002Ftrain` and another scene into `data\u002Ftest` such that the folder hierarchy looks something like this:\n\n```shell\n|——— training\n     |——— core\n          |——— marvin.hpp\n          |——— ...\n|——— data\n     |——— train\n          |——— rgbd-dataset-scene-1\n               |——— seq-01\n               |——— seq-02\n               |——— camera-intrinsics.txt\n               |——— ...\n          |——— ...\n     |——— test\n          |——— rgbd-dataset-scene-2\n               |——— seq-01\n               |——— camera-intrinsics.txt\n               |——— ...\n```\n\n## Multi-Frame Depth TSDF Fusion\n\nSee folder `3dmatch-toolbox\u002Fdepth-fusion`\n\nCUDA\u002FC++ code to fuse multiple registered depth maps into a TSDF voxel volume ([Curless and Levoy 1996](http:\u002F\u002Fgraphics.stanford.edu\u002Fpapers\u002Fvolrange\u002Fvolrange.pdf)), which can then be used to create surface meshes and point clouds.\n\n### Demo\n\nThis demo fuses 50 registered depth maps from directory `data\u002Fsample\u002Fdepth-fusion-demo\u002Frgbd-frames` into a TSDF voxel volume, and creates a surface point cloud `tsdf.ply`\n\n```shell\ncd 3dmatch-toolbox\u002Fdepth-fusion\n.\u002Fcompile.sh\n.\u002Fdemo # output saved to tsdf.ply\n```\n\n## Evaluation Code\n\nSee folder `3dmatch-toolbox\u002Fevaluation`\n\nEvaluation code for the [Keypoint Matching Benchmark](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#keypoint-matching-benchmark) and [Geometric Registration Benchmark](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#geometric-registration-benchmark), as well as a reference implementation for the experiments in our [paper](https:\u002F\u002Farxiv.org\u002Fpdf\u002F1603.08182.pdf).\n\n### Keypoint Matching Benchmark\n\nSee folder `3dmatch-toolbox\u002Fevaluation\u002Fkeypoint-matching`\n\nBenchmark description and leaderboard can be found [here](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#keypoint-matching-benchmark).\n\n#### Evaluation Example\n\n0. Navigate to `3dmatch-toolbox\u002Fevaluation\u002Fkeypoint-matching` and run the following in Matlab:\n\n\t```matlab\n\t% Evaluate 3DMatch (3dmatch.log) on the validation set (validation-set-gt.log)\n\tgetError;\n\t```\n\n#### Run 3DMatch on the validation set to generate a .log file (3dmatch.log)\n\n\n0. Compile C++\u002FCUDA code to compute 3DMatch descriptors with Marvin\n\n\t```shell\n\tcd 3dmatch-toolbox\u002Fevaluation\u002Fkeypoint-matching\n\t.\u002Fcompile.sh\n\t```\n\n0. Download our 3DMatch pre-trained weights \n\n\t```shell\n\t.\u002Fdownload-weights.sh # 3dmatch-weights-snapshot-137000.marvin\n\t```\n\n0. Download the validation set and test set\n\n\t```shell\n\t.\u002Fdownload-validation.sh # validation-set.mat\n\t.\u002Fdownload-test.sh # test-set.mat\n\t```\n\n0. Modify and run the following script in Matlab:\n\n\t```matlab\n\t% Runs 3DMatch on the validation set and generates 3dmatch.log\n\ttest3DMatch;\n\t```\n\n#### Generate your own correspondence dataset from [RGB-D reconstructions](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets)\n\n0. Download one or more scenes from RGB-D reconstruction datasets on our [project webpage](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets). Organize the [folder hierarchy as above](#additional-setup-instructions).\n\n0. Modify and run the following script in Matlab:\n\n\t```matlab\n\tmakeCorresDataset;\n\t```\n\n### Geometric Registration Benchmark\n\nSee folder `3dmatch-toolbox\u002Fevaluation\u002Fgeometric-registration`\n\nIncludes Matlab code to run evaluation on the geometric registration benchmarks described [here](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#geometric-registration-benchmark). Overview:\n* `getKeyptsAndDesc.m` - generates intermediate data (TDF voxel volumes, keypoints, and 3DMatch descriptors) for the scene fragments. You can also download our pre-computed data [here](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#geometric-registration-synthetic-data). \n* `runFragmentRegistration.m` - read intermediate data and run RANSAC-based registration for every pair of fragments. \n* `writeLog` - read registration results from every pair of fragments and create a .log file\n* `evaluate.m` - compute precision and recall from .log files for evaluation\n\n#### Evaluation Example\n\nRun the following in Matlab:\n\n```matlab\n% Evaluate 3DMatch on the geometric registration benchmark\nevaluate;\n```\n\nNote: the TDF voxel grids of the scene fragments from the synthetic benchmark were computed using the deprecated code for accurate TDF (see `deprecated\u002FpointCloud2AccTDF.m`). 3DMatch pre-trained weights fine-tuned on training fragments can be downloaded [here](http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fweights\u002F3dmatch-weights-snapshot-127000-fragments-6000.marvin).\n\n### Model Fitting for 6D Object Pose Estimation in the Amazon Picking Challenge\n\nSee folder `3dmatch-toolbox\u002Fevaluation\u002Fmodel-fitting-apc`\n\nIncludes code and pre-trained models to evaluate 3DMatch for model fitting on the [Shelf & Tote dataset](http:\u002F\u002Fwww.cs.princeton.edu\u002F~andyz\u002Fapc2016). You can download our pre-computed data (TDF voxel grid volumes for objects and scans, surface keypoints, descriptors, and pose predictions) [here](http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fapc-intermediate-data.zip). For an evaluation example, run Matlab script `getError.m`\n\n### Mesh Correspondence in Shape2Pose\n\nSee folder `3dmatch-toolbox\u002Fevaluation\u002Fmesh-correspondence-shape2pose`\n\nIncludes code to generate mesh correspondence visualizations on the meshes from the [Shape2Pose dataset](http:\u002F\u002Fgfx.cs.princeton.edu\u002Fgfx\u002Fpubs\u002FKim_2014_SHS\u002Findex.php) using 3DMatch. You can also download our pre-computed data (TDF voxel grid volumes of the meshes, surface keypoints, 3DMatch descriptors) [here](http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fshape2pose.zip). For a quick visualization, run the Matlab script `keypointRetrieval.m`.","# 3DMatch 工具箱\n3DMatch 是一种基于 ConvNet 的局部几何特征描述符，适用于 3D 数据（即点云、深度图、网格等）。该工具箱提供了使用 3DMatch 进行几何配准和关键点匹配的代码，以及从现有 RGB-D 重建数据中训练 3DMatch 的代码。这是我们论文的参考实现：\n\n### 3DMatch：从 RGB-D 重建中学习局部几何描述符\n\n[PDF](https:\u002F\u002Farxiv.org\u002Fpdf\u002F1603.08182.pdf) | [网页、基准测试与数据集](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F) | [视频](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=gZrsJJtDvvA)\n\n*[Andy Zeng](http:\u002F\u002Fandyzeng.com\u002F)、[Shuran Song](http:\u002F\u002F3dvision.princeton.edu\u002Fpeople\u002Fshurans\u002F)、[Matthias Nießner](http:\u002F\u002Fwww.niessnerlab.org\u002Fmembers\u002Fmatthias_niessner\u002Fprofile.html)、[Matthew Fisher](https:\u002F\u002Fresearch.adobe.com\u002Fperson\u002Fmatt-fisher\u002F)、[Jianxiong Xiao](http:\u002F\u002F3dvision.princeton.edu\u002Fpeople\u002Fxj\u002F) 和 [Thomas Funkhouser](http:\u002F\u002Fwww.cs.princeton.edu\u002F~funk\u002F)*\n\nIEEE 计算机视觉与模式识别会议 (CVPR) 2017 **[口头报告](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=qNVZl7bCjsU&list=PL_bDvITUYucADb15njRd7geem8vxOyo6N&index=3)**\n\n由于 3D 扫描数据通常具有噪声、低分辨率且不完整的特点，因此在真实世界的深度图像上匹配局部几何特征是一项极具挑战性的任务。这些困难限制了当前最先进的方法的性能，而这些方法通常基于几何属性的直方图。在本文中，我们提出了 3DMatch，这是一种数据驱动的模型，能够学习局部体积块描述符，用于建立部分 3D 数据之间的对应关系。为了收集用于训练我们模型的数据，我们提出了一种无监督特征学习方法，该方法利用现有 RGB-D 重建中数百万个对应标签。实验表明，我们的描述符不仅能够在新场景中匹配局部几何以进行重建，还能够泛化到不同的任务和空间尺度（例如，亚马逊拣选挑战中的实例级物体模型对齐，以及网格曲面对应）。结果表明，3DMatch 始终以显著优势超越其他最先进的方法。\n\n![概述](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fandyzeng_3dmatch-toolbox_readme_dfdd7bea4db4.jpg)\n\n#### 引用\n如果您在工作中发现此代码有用，请考虑引用以下内容：\n\n```shell\n@inproceedings{zeng20163dmatch, \n\ttitle={3DMatch: Learning Local Geometric Descriptors from RGB-D Reconstructions}, \n\tauthor={Zeng, Andy and Song, Shuran and Nie{\\ss}ner, Matthias and Fisher, Matthew and Xiao, Jianxiong and Funkhouser, Thomas}, \n\tbooktitle={CVPR}, \n\tyear={2017} \n}\n```\n\n#### 许可证\n此代码根据简化 BSD 许可证发布（详情请参阅 LICENSE 文件）。\n\n#### 基准测试与数据集\n所有相关信息和下载均可在此处找到 [这里](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F)。\n\n#### 联系方式\n如果您有任何问题或发现任何错误，请告知我：[Andy Zeng](http:\u002F\u002Fwww.cs.princeton.edu\u002F~andyz\u002F) andyz[at]princeton[dot]edu\n\n## 更改日志\n* **2018年3月20日。** 更新：为关键点匹配基准测试的测试集添加了标签（以方便使用）。\n* **2017年11月2日。** 修复 bug：在演示代码的 utils.hpp 中添加了 `#include \u003Crandom>`。\n* **2017年10月30日。** 修复 bug：包含了 Quoc-Huy 对训练过程中偶尔出现的 NaN 错误的修复。\n* **2017年10月28日。** 注意：演示代码仅读取以简单二进制格式保存的 3D 点云。如果您希望在自己的点云格式上运行 3DMatch 演示代码，请相应地修改 demo.cu。\n* **2017年4月6日。** 注意：3DMatch 使用 cuDNN 5.1。修订了安装说明。\n\n## 依赖项\n\n我们提供的 3DMatch 参考实现以及本工具箱中的其他组件需要以下依赖项。已在 Ubuntu 14.04 上测试过。\n\n0. [CUDA 7.5](https:\u002F\u002Fdeveloper.nvidia.com\u002Fcuda-toolkit-archive) 和 [cuDNN 5.1](https:\u002F\u002Fdeveloper.nvidia.com\u002Fcudnn)。您可能需要注册 NVIDIA。以下是设置 cuDNN 5.1 的一些额外步骤。**注意** 我们强烈建议您将不同版本的 cuDNN 安装到不同的目录中（例如，```\u002Fusr\u002Flocal\u002Fcudnn\u002FvXX```），因为不同的软件包可能需要不同版本的 cuDNN。\n\n\t```shell\n\tLIB_DIR=lib$([[ $(uname) == \"Linux\" ]] && echo 64)\n\tCUDNN_LIB_DIR=\u002Fusr\u002Flocal\u002Fcudnn\u002Fv5.1\u002F$LIB_DIR\n\techo LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CUDNN_LIB_DIR >> ~\u002F.profile && ~\u002F.profile\n\n\ttar zxvf cudnn*.tgz\n\tsudo cp cuda\u002F$LIB_DIR\u002F* $CUDNN_LIB_DIR\u002F\n\tsudo cp cuda\u002Finclude\u002F* \u002Fusr\u002Flocal\u002Fcudnn\u002Fv5.1\u002Finclude\u002F\n\t```\n\n0. OpenCV（已用 OpenCV 2.4.11 测试）\n * 用于读取图像文件\n\n0. Matlab 2015b 或更高版本（已用 Matlab 2016a 测试）\n\n## 目录\n* [演示：使用 3DMatch 对齐两个点云](#demo-align-two-point-clouds-with-3dmatch)\n* [将 3D 数据转换为 TDF 体素网格](#converting-3d-data-to-tdf-voxel-grids)\n* [从 RGB-D 重建中训练 3DMatch](#training-3dmatch-from-rgb-d-reconstructions)\n* [多帧深度 TSDF 融合](#multi-frame-depth-tsdf-fusion)\n* [评估代码](#evaluation-code)\n\n## 演示：使用 3DMatch 对齐两个点云\n\n![演示预告](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fandyzeng_3dmatch-toolbox_readme_b6dc47ff9ec6.jpg)\n\n本演示使用我们预训练的 3DMatch 描述符（配合 Marvin）和标准 RANSAC，对两个 3D 点云（由单视图深度图投影而来）进行对齐。\n\n### 指导说明\n\n0. 克隆 3DMatch 工具箱，编译 C++\u002FCUDA 演示代码和 Marvin\n\n\t```shell\n\tgit clone https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox.git 3dmatch-toolbox\n\tcd 3dmatch-toolbox\u002Fcore\n\t.\u002Fcompile.sh\n\t```\n\n0. 下载我们预训练的 3DMatch 权重\n\n\t```shell\n\t.\u002Fdownload-weights.sh # 3dmatch-weights-snapshot-137000.marvin\n\t```\n\n0. 加载两个示例 3D 点云，计算它们的 TDF 体素网格体积，并计算随机表面关键点及其 3DMatch 描述符（保存到磁盘上的二进制文件）。警告：此演示仅读取以简单二进制格式保存的 3D 点云。如果您希望在自己的点云格式上运行 3DMatch 演示代码，请相应地修改 demo.cu。\n\n\t```shell\n\t# 生成 fragment-1.desc.3dmatch.bin 和 fragment-1.keypts.bin\n\t.\u002Fdemo ..\u002Fdata\u002Fsample\u002F3dmatch-demo\u002Fsingle-depth-1.ply fragment-1\n\n\t# 生成 fragment-2.desc.3dmatch.bin 和 fragment-2.keypts.bin\n\t.\u002Fdemo ..\u002Fdata\u002Fsample\u002F3dmatch-demo\u002Fsingle-depth-2.ply fragment-2 \n\t```\n\n0. 在 Matlab 中运行以下脚本：\n\n\t```matlab\n\t% 加载关键点和 3DMatch 描述符，并使用 RANSAC 对齐这两个点云。对齐后的点云可视化结果将保存到文件 `result.ply` 中，可以使用 Meshlab 或其他 3D 查看器查看。注意：由于默认情况下随机选择的关键点质量较差，此演示首次尝试时可能存在对齐失败的风险。\n\tdemo;\n\t```\n\n## 将3D数据转换为TDF体素网格\n\n关于如何将各种3D数据表示形式转换为截断距离函数（TDF）值的体素网格的说明。\n\n0. 点云到TDF体素网格（使用最近邻点距离）\n * 参见[C++\u002FCUDA示例代码](https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fblob\u002Fmaster\u002Fcore\u002Fdemo.cu)（ComputeTDF），它通过占用体素网格快速近似计算TDF值。\n * 替代方案：参见[Matlab\u002FCUDA代码](https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fblob\u002Fmaster\u002Fdeprecated\u002FpointCloud2AccTDF.m)，该代码可以计算精确的TDF值，但速度非常慢。\n * 替代方案：参见[Matlab代码](https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fblob\u002Fmaster\u002Fevaluation\u002Fmodel-fitting-apc\u002FpointCloud2TDF.m)，同样可以计算精确的TDF值，但可在Matlab中独立运行。如果您的点云较小，通常不会出现内存问题。\n\n0. 网格到TDF体素网格（使用[GAPS](https:\u002F\u002Fgithub.com\u002Ftomfunkhouser\u002Fgaps)对网格表面进行距离变换）。请注意，本仓库中已包含GAPS的一个版本。\n * 安装GAPS并将示例网格（.off文件）转换为体素网格（浮点数的二进制.raw文件）的说明：\n\n\t```shell\n\tcd 3dmatch-toolbox\u002Fgaps\n\n\t# 安装GAPS\n\tmake\n\n\t# 对示例网格文件运行msh2df（更多信息请参阅msh2df.cpp中的注释）\n\tcd bin\u002Fx86_64\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fgaps\u002Fbicycle000002.off\n\t.\u002Fmsh2df bicycle000002.off bicycle000002.raw -v # 更多参数请参阅msh2df.cpp中的注释\n\n\t# 下载可视化脚本\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fgaps\u002FshowTDF.m\n\t```\n * 在Matlab中运行可视化脚本\n\n\t```matlab\n\t% 可视化网格的TDF体素网格\n\tshowTDF;\n\t```\n\n0. 深度图到TDF体素网格\n * 将深度图投影到3D相机空间中的点云，并从点云转换为TDF体素网格（见上文）。\n * 替代方案：将深度图（或多帧深度图）转换为TSDF体积（参见[此处](#multi-frame-depth-tsdf-fusion)的说明），并计算每个体素的绝对值（即投影式TDF值，其在视场边界和缺失深度区域的行为有所不同）。\n\n## 使用RGB-D重建数据训练3DMatch\n\n请参阅`3dmatch-toolbox\u002Ftraining`文件夹。\n\n用于使用轻量级纯GPU神经网络框架[Marvin](http:\u002F\u002Fmarvin.is\u002F)训练3DMatch的代码。其中包括Siamese网络架构的.json文件`training\u002Fnet.json`，以及`training\u002Fmatch.hpp`中的CUDA\u002FC++ Marvin数据层，该层可从RGB-D重建数据集随机采对应点（这些数据集可从我们的[项目主页](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets)下载）。\n\n### 快速入门\n0. 编译Marvin\n\n\t```shell\n\tcd 3dmatch-toolbox\u002Ftraining\n\t.\u002Fcompile.sh\n\t```\n\n0. 从RGB-D重建数据集下载若干训练和测试场景（更多场景可[在此处](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets)下载）\n\n\t```shell\n\tcd ..\u002Fdata\n\tmkdir train && mkdir test && mkdir backup\n\tcd train\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Frgbd-datasets\u002Fsun3d-brown_cogsci_1-brown_cogsci_1.zip\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Frgbd-datasets\u002F7-scenes-heads.zip\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Frgbd-datasets\u002Fsun3d-harvard_c11-hv_c11_2.zip\n\tunzip sun3d-brown_cogsci_1-brown_cogsci_1.zip\n\tunzip 7-scenes-heads.zip\n\tunzip sun3d-harvard_c11-hv_c11_2.zip\n\tmv *.zip ..\u002Fbackup\n\tcd ..\u002Ftest\n\twget http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Frgbd-datasets\u002Fsun3d-hotel_umd-maryland_hotel3.zip\n\tunzip sun3d-hotel_umd-maryland_hotel3.zip\n\tmv *.zip ..\u002Fbackup\n\tcd ..\u002F..\u002Ftraining\n\t```\n\n0. 从`data\u002Ftrain`中保存的RGB-D场景对应的点对开始，从零训练一个3DMatch模型\n\n\t```shell\n\t.\u002Fmarvin train net.json\n\t```\n\n0. （可选）使用Marvin张量文件中的预训练权重训练3DMatch\n\n\t```shell\n\t.\u002Fmarvin train net.json your-pre-trained-weights.marvin\n\t```\n\n### 其他设置说明\n您可以在我们的[项目主页](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets)上下载更多RGB-D重建数据集。这些数据集已被转换为统一格式，与我们用于训练3DMatch的Marvin数据层兼容。请至少将一个场景保存到`data\u002Ftrain`，另一个场景保存到`data\u002Ftest`，使文件夹结构如下所示：\n\n```shell\n|——— training\n     |——— core\n          |——— marvin.hpp\n          |——— ...\n|——— data\n     |——— train\n          |——— rgbd-dataset-scene-1\n               |——— seq-01\n               |——— seq-02\n               |——— camera-intrinsics.txt\n               |——— ...\n          |——— ...\n     |——— test\n          |——— rgbd-dataset-scene-2\n               |——— seq-01\n               |——— camera-intrinsics.txt\n               |——— ...\n```\n\n## 多帧深度TSDF融合\n\n请参阅`3dmatch-toolbox\u002Fdepth-fusion`文件夹。\n\n用于将多个配准后的深度图融合为TSDF体素体积的CUDA\u002FC++代码（[Curless和Levoy 1996](http:\u002F\u002Fgraphics.stanford.edu\u002Fpapers\u002Fvolrange\u002Fvolrange.pdf)），随后可用于生成表面网格和点云。\n\n### 示例\n\n此示例将`data\u002Fsample\u002Fdepth-fusion-demo\u002Frgbd-frames`目录下的50个配准后深度图融合为TSDF体素体积，并生成一个表面点云`tsdf.ply`。\n\n```shell\ncd 3dmatch-toolbox\u002Fdepth-fusion\n.\u002Fcompile.sh\n.\u002Fdemo # 输出保存到tsdf.ply\n```\n\n## 评估代码\n\n请参阅`3dmatch-toolbox\u002Fevaluation`文件夹。\n\n用于[关键点匹配基准测试](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#keypoint-matching-benchmark)和[几何配准基准测试](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#geometric-registration-benchmark)的评估代码，以及我们[论文](https:\u002F\u002Farxiv.org\u002Fpdf\u002F1603.08182.pdf)中实验的参考实现。\n\n### 关键点匹配基准测试\n\n请参阅文件夹 `3dmatch-toolbox\u002Fevaluation\u002Fkeypoint-matching`。\n\n基准测试的说明和排行榜可以在这里找到：[http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#keypoint-matching-benchmark](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#keypoint-matching-benchmark)。\n\n#### 评估示例\n\n0. 导航到 `3dmatch-toolbox\u002Fevaluation\u002Fkeypoint-matching`，并在 MATLAB 中运行以下命令：\n\n\t```matlab\n\t% 在验证集（validation-set-gt.log）上评估 3DMatch（3dmatch.log）\n\tgetError;\n\t```\n\n#### 在验证集上运行 3DMatch 以生成 .log 文件（3dmatch.log）\n\n0. 编译 C++\u002FCUDA 代码，使用 Marvin 计算 3DMatch 描述符：\n\n\t```shell\n\tcd 3dmatch-toolbox\u002Fevaluation\u002Fkeypoint-matching\n\t.\u002Fcompile.sh\n\t```\n\n0. 下载我们的 3DMatch 预训练权重：\n\n\t```shell\n\t.\u002Fdownload-weights.sh # 3dmatch-weights-snapshot-137000.marvin\n\t```\n\n0. 下载验证集和测试集：\n\n\t```shell\n\t.\u002Fdownload-validation.sh # validation-set.mat\n\t.\u002Fdownload-test.sh # test-set.mat\n\t```\n\n0. 修改并运行以下 MATLAB 脚本：\n\n\t```matlab\n\t% 在验证集上运行 3DMatch，并生成 3dmatch.log\n\ttest3DMatch;\n\t```\n\n#### 从 [RGB-D 重建数据集](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets) 中生成您自己的对应关系数据集\n\n0. 从我们项目网页上的 RGB-D 重建数据集下载一个或多个场景：[http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#rgbd-reconstruction-datasets)。按照[上述文件夹结构](#additional-setup-instructions)组织文件夹。\n\n0. 修改并运行以下 MATLAB 脚本：\n\n\t```matlab\n\tmakeCorresDataset;\n\t```\n\n### 几何配准基准测试\n\n请参阅文件夹 `3dmatch-toolbox\u002Fevaluation\u002Fgeometric-registration`。\n\n包含用于在几何配准基准测试上进行评估的 MATLAB 代码，这些基准测试的描述见[这里](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#geometric-registration-benchmark)。概述如下：\n* `getKeyptsAndDesc.m` - 为场景片段生成中间数据（TDF 体素网格、关键点和 3DMatch 描述符）。您也可以从[这里](http:\u002F\u002F3dmatch.cs.princeton.edu\u002F#geometric-registration-synthetic-data)下载我们预先计算好的数据。\n* `runFragmentRegistration.m` - 读取中间数据，并对每一对片段执行基于 RANSAC 的配准。\n* `writeLog` - 读取每一对片段的配准结果，并创建 .log 文件。\n* `evaluate.m` - 根据 .log 文件计算精确率和召回率以进行评估。\n\n#### 评估示例\n\n在 MATLAB 中运行以下命令：\n\n```matlab\n% 在几何配准基准测试上评估 3DMatch\nevaluate;\n```\n\n注意：合成基准测试中场景片段的 TDF 体素网格是使用已弃用的精确 TDF 代码计算的（参见 `deprecated\u002FpointCloud2AccTDF.m`）。在训练片段上微调过的 3DMatch 预训练权重可以从[这里](http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fweights\u002F3dmatch-weights-snapshot-127000-fragments-6000.marvin)下载。\n\n### 亚马逊拣选挑战中的 6D 物体位姿估计模型拟合\n\n请参阅文件夹 `3dmatch-toolbox\u002Fevaluation\u002Fmodel-fitting-apc`。\n\n包含用于在 [Shelf & Tote 数据集](http:\u002F\u002Fwww.cs.princeton.edu\u002F~andyz\u002Fapc2016) 上评估 3DMatch 模型拟合的代码和预训练模型。您可以从[这里](http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fapc-intermediate-data.zip)下载我们预先计算的数据（物体和扫描的 TDF 体素网格体积、表面关键点、描述符以及位姿预测）。要进行评估示例，请运行 MATLAB 脚本 `getError.m`。\n\n### Shape2Pose 中的网格对应关系\n\n请参阅文件夹 `3dmatch-toolbox\u002Fevaluation\u002Fmesh-correspondence-shape2pose`。\n\n包含用于在 [Shape2Pose 数据集](http:\u002F\u002Fgfx.cs.princeton.edu\u002Fgfx\u002Fpubs\u002FKim_2014_SHS\u002Findex.php) 的网格上，使用 3DMatch 生成网格对应关系可视化效果的代码。您也可以从[这里](http:\u002F\u002F3dvision.princeton.edu\u002Fprojects\u002F2016\u002F3DMatch\u002Fdownloads\u002Fshape2pose.zip)下载我们预先计算的数据（网格的 TDF 体素网格体积、表面关键点、3DMatch 描述符）。要快速查看可视化效果，请运行 MATLAB 脚本 `keypointRetrieval.m`。","# 3DMatch Toolbox 快速上手指南\n\n3DMatch 是一个基于卷积神经网络（ConvNet）的局部几何特征描述子，专为 3D 数据（如点云、深度图、网格等）设计。本工具箱提供了使用 3DMatch 进行几何配准和关键点匹配的代码，以及从现有 RGB-D 重建数据中训练模型的流程。\n\n## 环境准备\n\n本参考实现主要在 **Ubuntu 14.04** 上测试通过，其他 Linux 发行版可能也需要类似的环境配置。\n\n### 系统要求与依赖\n请确保安装以下核心依赖：\n\n1.  **CUDA 与 cuDNN**\n    *   CUDA 7.5\n    *   cuDNN 5.1\n    *   *注意：建议将不同版本的 cuDNN 安装到独立目录（如 `\u002Fusr\u002Flocal\u002Fcudnn\u002Fv5.1`），以避免版本冲突。*\n\n2.  **OpenCV**\n    *   版本：2.4.11 或兼容版本（用于读取图像文件）。\n\n3.  **Matlab**\n    *   版本：2015b 或更高（推荐 2016a）。\n\n4.  **编译工具**\n    *   GCC, G++, Make 等基础构建工具。\n\n## 安装步骤\n\n### 1. 配置 cuDNN 5.1\n下载 cuDNN 后，执行以下命令将其配置到指定目录并更新环境变量：\n\n```shell\nLIB_DIR=lib$([[ $(uname) == \"Linux\" ]] && echo 64)\nCUDNN_LIB_DIR=\u002Fusr\u002Flocal\u002Fcudnn\u002Fv5.1\u002F$LIB_DIR\necho LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$CUDNN_LIB_DIR >> ~\u002F.profile && source ~\u002F.profile\n\ntar zxvf cudnn*.tgz\nsudo cp cuda\u002F$LIB_DIR\u002F* $CUDNN_LIB_DIR\u002F\nsudo cp cuda\u002Finclude\u002F* \u002Fusr\u002Flocal\u002Fcudnn\u002Fv5.1\u002Finclude\u002F\n```\n\n### 2. 克隆代码并编译核心库\n获取源代码并编译 C++\u002FCUDA 演示代码及 Marvin 框架：\n\n```shell\ngit clone https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox.git 3dmatch-toolbox\ncd 3dmatch-toolbox\u002Fcore\n.\u002Fcompile.sh\n```\n\n### 3. 下载预训练权重\n下载官方提供的预训练模型文件：\n\n```shell\ncd ..\n.\u002Fdownload-weights.sh # 将下载 3dmatch-weights-snapshot-137000.marvin\n```\n\n## 基本使用：点云配准演示\n\n本示例展示如何使用预训练的 3DMatch 描述子和 RANSAC 算法对齐两个 3D 点云。\n\n> **注意**：演示代码默认仅读取简单的二进制格式点云。如果您需要处理其他格式（如 .ply），需修改 `demo.cu` 中的读取逻辑。以下步骤假设您已准备好名为 `single-depth-1.ply` 和 `single-depth-2.ply` 的测试数据（位于 `..\u002Fdata\u002Fsample\u002F3dmatch-demo\u002F`）。\n\n### 第一步：生成特征描述子\n运行编译好的 demo 程序，计算点云的 TDF 体素网格、随机表面关键点及其 3DMatch 描述子。\n\n```shell\n# 为第一个片段生成描述子 (.desc.3dmatch.bin) 和关键点 (.keypts.bin)\n.\u002Fdemo ..\u002Fdata\u002Fsample\u002F3dmatch-demo\u002Fsingle-depth-1.ply fragment-1\n\n# 为第二个片段生成描述子和关键点\n.\u002Fdemo ..\u002Fdata\u002Fsample\u002F3dmatch-demo\u002Fsingle-depth-2.ply fragment-2 \n```\n\n### 第二步：执行配准 (Matlab)\n在 Matlab 中运行 `demo` 脚本。该脚本会加载上述生成的二进制文件，利用 RANSAC 算法计算变换矩阵并对齐点云，最终输出 `result.ply` 文件。\n\n```matlab\n% 在 Matlab 命令行中执行\ndemo;\n```\n\n*说明：由于关键点默认是随机选择的，首次运行可能会因关键点质量不佳导致配准失败。若发生此情况，重新运行 `demo` 脚本即可再次尝试。*\n\n生成的 `result.ply` 可使用 Meshlab 或其他 3D 查看器查看对齐效果。","某机器人团队正在开发一款用于仓储物流的自主抓取系统，需要将机械臂视觉传感器采集的实时点云与预建的物品 3D 模型进行高精度对齐。\n\n### 没有 3dmatch-toolbox 时\n- **抗噪能力差**：面对深度相机产生的噪声、低分辨率及数据缺失，传统基于几何直方图的方法极易失效，导致特征匹配错误率高。\n- **泛化性不足**：算法难以适应不同尺寸的物品或变化的空间尺度，针对新场景往往需要重新手工调整参数甚至重写规则。\n- **配准效率低**：在部分重叠的 3D 数据中建立对应关系耗时漫长，无法满足机械臂实时抓取所需的毫秒级响应速度。\n- **依赖人工设计**：特征描述子依赖专家经验手工构建，难以捕捉复杂的局部几何细节，导致在光滑或纹理重复区域频繁丢失目标。\n\n### 使用 3dmatch-toolbox 后\n- **鲁棒性显著提升**：利用基于卷积神经网络的局部几何描述子，能有效抑制噪声干扰，即使在数据不完整的现实扫描中也能精准匹配关键点。\n- **强大的泛化能力**：模型通过数百万 RGB-D 重建数据无监督学习而来，无需额外训练即可直接应用于不同物体实例及空间尺度的对齐任务。\n- **实时高精度配准**：显著优化了部分 3D 数据间的对应关系建立过程，大幅缩短计算时间，确保机械臂能快速锁定抓取位姿。\n- **数据驱动的特征提取**：自动学习深层体积块（Volumetric Patch）特征，不再依赖人工规则，能敏锐识别复杂曲面和细微几何结构。\n\n3dmatch-toolbox 通过将深度学习引入局部几何描述，彻底解决了真实场景下 3D 数据噪声大、不完整导致的配准难题，让机器人视觉系统更加智能可靠。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fandyzeng_3dmatch-toolbox_b6dc47ff.jpg","andyzeng","Andy Zeng","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fandyzeng_2ca80003.jpg",null,"http:\u002F\u002Fandyzeng.github.io","https:\u002F\u002Fgithub.com\u002Fandyzeng",[21,25,29,33,37,40,44,47,51],{"name":22,"color":23,"percentage":24},"C++","#f34b7d",61.1,{"name":26,"color":27,"percentage":28},"C","#555555",36,{"name":30,"color":31,"percentage":32},"MATLAB","#e16737",1.7,{"name":34,"color":35,"percentage":36},"Cuda","#3A4E3A",0.6,{"name":38,"color":17,"percentage":39},"SWIG",0.4,{"name":41,"color":42,"percentage":43},"Makefile","#427819",0.1,{"name":45,"color":46,"percentage":43},"Shell","#89e051",{"name":48,"color":49,"percentage":50},"HTML","#e34c26",0,{"name":52,"color":53,"percentage":50},"Awk","#c30e9b",897,187,"2026-04-08T16:37:45","BSD-2-Clause",5,"Linux","必需 NVIDIA GPU，需支持 CUDA 7.5","未说明",{"notes":63,"python":61,"dependencies":64},"该项目主要基于 C++\u002FCUDA 和 Matlab，而非 Python。官方仅在 Ubuntu 14.04 上测试通过。安装 cuDNN 时建议将其安装到独立目录（如 \u002Fusr\u002Flocal\u002Fcudnn\u002Fv5.1）以避免版本冲突。演示代码默认仅读取简单的二进制格式点云文件，若需使用其他格式需修改 demo.cu。训练部分需要使用 Marvin 框架。",[65,66,67,68,69,70],"CUDA 7.5","cuDNN 5.1","OpenCV 2.4.11","Matlab 2015b+","Marvin (内置轻量级 GPU 神经网络框架)","GAPS (用于网格处理，部分内置)",[72,73,74],"其他","开发框架","图像",[76,77,78,79,80,81,82,83,84,85],"3dmatch","rgbd","computer-vision","deep-learning","3d-deep-learning","geometry-processing","3d","vision","artificial-intelligence","point-cloud",2,"ready","2026-03-27T02:49:30.150509","2026-04-11T08:11:52.026717",[91,96,100,105,110,115,120],{"id":92,"question_zh":93,"answer_zh":94,"source_url":95},29066,"如何从已注册的 RGB-D 帧中提取用于训练网络的匹配点对？","给定已注册的 RGB-D 帧，你可以找到不同相机视角下相互对应的表面点。它们各自的局部区域就是用于训练网络的“匹配对”。建议查看 training\u002Fmatch.hpp 中的数据层代码以了解具体实现细节。此外，也可以使用 3D Harris 关键点，效果良好。","https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fissues\u002F2",{"id":97,"question_zh":98,"answer_zh":99,"source_url":95},29060,"在编译代码时遇到 'std::random_device' 等命名空间错误，如何解决？","这通常是因为 CUDA 编译器版本较旧或配置问题。确保你的平台支持 C++11 标准。如果只是想保存 TDF 体素网格数据，可能需要取消注释 demo.cu 文件末尾的一段代码。此外，该代码片段会导航到 core 目录并调用 .\u002Fdemo 可执行文件来计算中间数据。",{"id":101,"question_zh":102,"answer_zh":103,"source_url":104},29061,"训练网络长时间不收敛怎么办？有什么建议的初始化方法或优化器吗？","网络不收敛可能与权重初始化有关。尝试使用 PyTorch 实现的 Xavier 初始化（包含 fan_out 模式），这已被证明有效。虽然原作者提到 Marvin 的 Xavier 实现（受 Caffe 启发，不包含 fan_out）也能工作，但在使用 PyTorch 迁移时，显式指定 fan_out 的 Xavier 初始化有助于加速收敛。关于优化器，原代码使用 SGD，改为 ADAM 是否有效需结合初始化策略调整。","https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fissues\u002F11",{"id":106,"question_zh":107,"answer_zh":108,"source_url":109},29062,"运行 showTDF.m 时出现 'Color' 类型无效（期望 uint8 但得到 double）的错误，如何解决？","该工具箱的部分可视化和评估工具依赖于 MATLAB 2015a 或更高版本中的'3D 点云处理工具箱’。请升级您的 MATLAB 版本至 2015a 以上以解决此兼容性问题。","https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fissues\u002F3",{"id":111,"question_zh":112,"answer_zh":113,"source_url":114},29063,"使用自己的数据集训练时，需要预先获取相机位姿（pose）吗？","是的，如果使用自己的 RGB-D 帧进行训练，必须预先获取相机位姿。通常可以通过选择一种 3D 重建算法（例如 KinectFusion）来计算这些位姿。如果训练在第一轮迭代后卡住，请检查相机位姿是否能产生合理的场景 3D 重建，并确认深度图像格式是否正确（3DMatch 读取的是毫米单位的 16 位格式）。","https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fissues\u002F8",{"id":116,"question_zh":117,"answer_zh":118,"source_url":119},29064,"如何在 Windows 平台上将 3D 数据转换为 TDF 体素网格？需要 CUDA 吗？","可以在 Windows 上仅使用“将 3D 数据转换为 TDF 体素网格”的功能。仓库中包含一份 GAPS 代码副本，其中提供了 Visual Studio 解决方案文件，可用于在 Windows 上编译 msh2df 二进制文件。此过程不需要额外的依赖项，也不需要安装 CUDA。","https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fissues\u002F6",{"id":121,"question_zh":122,"answer_zh":123,"source_url":124},29065,"评估代码中重叠率计算的距离阈值和 KNN 搜索逻辑不一致，会影响结果吗？","这种不一致是故意的，不需要保持一致。register2Fragments.m 中的距离阈值和 KNN 计算只是用于检测闭环的启发式算法，运行在 3DMatch 之上。你可以根据自己的描述符或搜索算法自由修改这些启发式规则。但在基准测试评估时，用于计算伪地面真值（pseudo ground truth）的 getGtInfoLog.m 代码不应被修改。","https:\u002F\u002Fgithub.com\u002Fandyzeng\u002F3dmatch-toolbox\u002Fissues\u002F16",[],[127,138,146,155,163,172],{"id":128,"name":129,"github_repo":130,"description_zh":131,"stars":132,"difficulty_score":133,"last_commit_at":134,"category_tags":135,"status":87},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[136,73,74,137],"Agent","数据工具",{"id":139,"name":140,"github_repo":141,"description_zh":142,"stars":143,"difficulty_score":133,"last_commit_at":144,"category_tags":145,"status":87},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[73,74,136],{"id":147,"name":148,"github_repo":149,"description_zh":150,"stars":151,"difficulty_score":86,"last_commit_at":152,"category_tags":153,"status":87},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",150037,"2026-04-10T23:33:47",[73,136,154],"语言模型",{"id":156,"name":157,"github_repo":158,"description_zh":159,"stars":160,"difficulty_score":86,"last_commit_at":161,"category_tags":162,"status":87},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[73,74,136],{"id":164,"name":165,"github_repo":166,"description_zh":167,"stars":168,"difficulty_score":86,"last_commit_at":169,"category_tags":170,"status":87},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[171,136,74,73],"插件",{"id":173,"name":174,"github_repo":175,"description_zh":176,"stars":177,"difficulty_score":86,"last_commit_at":178,"category_tags":179,"status":87},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[171,73]]