Awesome
Deep Geometric Prior for Surface Reconstruction
The reference implementaiton for the CVPR 2019 paper Deep Geometric Prior for Surface Reconstruction.
Code Overview
There are several programs in this repository explained in detail below. The documentation for each program can be seen by running it with the -h
flag. The code is also extensively commented and should be easy to follow. Please create GitHub issues or reach out to me by email if you run into any problems.
-
reconstruct_surface.py
:Compute a set of patches which represent a surface.
This program produces a dense point cloud (
out.ply
by default) and a binary file file (out.pt
by default) which can be used to regenerate the dense point cloud withexport_point_cloud.py
(this is useful for example, if you want to try different sampling densities). -
reconstruct_single_patch.py
Compute a single surface patch fitted to a point cloud.
As with
reconstruct_surface.py
, this program produces a file (defaulting toout.pt
) as output which can be used to upsample a point cloud withexport_point_cloud.py
. You can optionally plot the reconstruction withplot_reconstruction.py
. -
export_point_cloud.py
Exports a dense point cloud (
out.ply
by default) from a reconstruction the.pt
binary file produced byreconstruct_surface.py
orreconstruct_single_patch,py
.
Setting up and Running the Code
With conda
(Recommended)
All dependencies can be automatically installed with conda
using the provided environment.yml
Simply run the following from the root of the repository:
conda env create -f environment.yml
This will create a conda environment named deep-surface-prior
with all the correct dependencies installed. You can activate the environment by running:
conda activate deep-geometric-prior
Installing Dependencies Manually (Not Recommended)
If you are not using Conda, you can manually install the following dependencies:
- Python 3.6 (or later)
- PyTorch 1.0 (or later)
- NumPy 1.15 (or later)
- SciPy 1.1.0 (or later)
- FML 0.1 (or later)
- Point Cloud Utils 0.12.0 (or later)
- Mayavi 4.6.2 (or later)
Reducing Memory Usage
The Deep Geometric Prior trains an individual MLP for each surface patch in a model. Since there can be a lot of patches in a point cloud, this can lead to a high GPU memory usage when fitting all the MLPs in parallel. For this reason, we provide a --batch-size
argument to reconstruct_surface.py
which only fits --batch-size
MLPs in parallel at once. If you run out of VRAM, try decreasing this parameter.
Surface Reconstruction Benchmark Data
The scans, ground truth data and reconstructions from the paper are available for download here.
The linked zip archive contains 3 directories:
scans
contains a simulated scan of the models. The scans are generated with the surface reconstruction benchmark.ground_truth
contains a dense point cloud for each model sampled from the ground truth surface.our_reconstructions
contains a reconstructed point cloud for each model generated with our method.
Running the Deep Geometric Prior on the Surface Reconstruction Benchmark
- Make sure to install the project dependencies with conda or manually as described above.
- Download the Surface Reconstruction Benchmark Data (See above section for details).
- Extract the zip file which should produce a directory named
deep_geometric_prior_data
. - Since Deep Geometric Prior fits many neural networks over a model, it requires a lot of memory (To reduce memory usage see section above on memory usage), thus it is best to use multiple GPUs when reconstructing a model. Suppose four GPUs are available named
cuda:0
,cuda:1
,cuda:2
, andcuda:3
, then the following five commands will reconstruct the five benchmark models using those GPUs. You can change the list of devices for different configurations:
python reconstruct_surface.py deep_geometric_prior_data/scans/gargoyle.ply 0.01 1.0 20 -d cuda:0 cuda:1 cuda:2 cuda:3 -nl 25 -ng 25 -o gargoyle
python reconstruct_surface.py deep_geometric_prior_data/scans/dc.ply 0.01 1.0 20 -d cuda:0 cuda:1 cuda:2 cuda:3 -nl 25 -ng 25 -o dc
python reconstruct_surface.py deep_geometric_prior_data/scans/lord_quas.ply 0.01 1.0 10 -d cuda:0 cuda:1 cuda:2 cuda:3 -nl 25 -ng 25 -o lord_quas
python reconstruct_surface.py deep_geometric_prior_data/scans/anchor.ply 0.01 1.0 10 -d cuda:0 cuda:1 cuda:2 cuda:3 -nl 25 -ng 25 -o anchor
python reconstruct_surface.py deep_geometric_prior_data/scans/daratech.ply 0.01 1.0 10 -d cuda:0 cuda:1 cuda:2 cuda:3 -nl 25 -ng 25 -o daratech
NOTE: You may need to change the paths deep_geometric_prior_data/scans/*.ply
to point to where you extracted the zip file, and you may need to change the device arguments -d cuda:0 ...
to adapt to your system. To avoid CUDA out of memory
error use the reconstruction in batches --batch-size
.
Each of the above commands produces a ply
file and pt
file (e.g. anchor.ply
, anchor.pt
). The PLY file contains a dense upsampled point cloud and the PT file contains metadata about the reconstruction. You can use the PT file to perform further operations using example export_point_cloud.py
.