PCPNet

This is our implementation of PCPNet, a network that estimates local geometric properties such as normals and curvature from point clouds.

The architecture is similar to PointNet (with a few smaller modifications), but features are computed from local patches instead of of the entire point cloud, which makes estimated local properties more accurate.

This code was written by Paul Guerrero and Yanir Kleiman, based on the excellent PyTorch implementation of PointNet by Fei Xia.

This work was presented at Eurographics 2018.

Update 18/Oct/2018: The code has been updated to pytorch 0.4, and an option for choosing the GPU or using CPU only has been added. The old version that is compatible with pytorch 0.3 is still available in the branch pytorch_0.3.

Update 21/Jun/2018: The test dataset has been updated to include one shape that was missing to exactly reproduce the results in our paper. Thanks to Itzik Ben Shabat for pointing this out! Also note that the --sparse_patches option needs to be activated when running eval_pcpnet.py to exactly reproduce the results in our paper.

Setup

[1 point] The link to your repository is provided, and the repository is accessible publicly on the web. Clone this repository:

git clone https://github.com/SoshinK/pcpnet.git
cd pcpnet

[1 point] Pull the docker image from the Dockerhub.

source docker/docker_names.sh
docker pull ilyabasharov/pcpnet:1.0.0
sh docker/start_devil.sh

[4 points] Your repository provides a Dockerfile and provides a docker image to work with the code.

source docker/docker_names.sh
sh docker/build.sh
sh docker/start_devil.sh

Quick Start

[1 point] Quickstart, with step-by-step instructions on how to reproduce the results of the project.

Download dataset, pre-trained models and to estimate point cloud properties using default settings: [1 point] Your repository provides a separate script to obtain external data.

python scripts/download_pclouds.py
python scripts/download_models.py
python eval.py

Or run local

pip install -r requirements.txt
python setup.py install

Data Format

The point cloud and its properties are stored in different files with the same name, but different extensions: .xyz for point clouds, .normals for normals and .curv for curvature values.

These files have similar formats. Each line describes one point, containing (x, y, z) coordinates separated by spaces for points and normals and (max. curvature, min. curvature) values for curvatures.

A dataset is given by a text file containing the file name (without extension) of one point cloud per line. The file name is given relative to the location of the text file.

Development

[1 point] Development, with step-by-step instructions on how to modify the project

Estimating Point Cloud Properties

[1 point] Your repository provides a separate script to perform evaluation (inference, metrics,visualization). To estimate point cloud properties using default settings:

python eval.py

This outputs unoriented normals using the single-scale normal estimation model described in the paper for the test set used in the paper. To use alternative models and data sets, either edit the default arguments defined in the first few lines of eval_pcpnet.py, or run eval_pcpnet.py with additional arguments:

python eval.py \
--indir "path/to/dataset" \
--dataset "dataset.txt" \
--models "/path/to/model/model_name"

Where dataset.txt is a dataset as described above. The model is given without the _model.pth suffix. For example the model file models/single_scale_normal_model.pth would be specified as --models "models/single_scale_normal". In addition to the model file, a file containing model hyperparameters and training parameters has to be available at the same location and with the same name, but with suffix _params.pth. Both the model and the parameters file are available for all pre-trained models and are generated when training with train_pcpnet.py.

Training

[1 point] Your repository provides a separate script to perform training and model optimization. To train PCPNet with the default settings:

python train.py

This trains the single-scale normal estimation model described in the paper on the training set used in the paper. To train on a different dataset:

python train.py \
--indir "path/to/dataset" \
--trainset "dataset.txt" \
--gpu_idx 0 \
--nepoch 2000 \
--batchSize 64

The dataset is given in the format described above. To change model settings or train a multi-scale model, --indir is input folder, --trainset is training set file name, --gpu_idx set < 0 to use CPU, --nepoch is number of epochs to train for, --batchSize is input batch size, please see the description of the input arguments in the first few lines of train_pcpnet.py.

Citation

If you use our work, please cite our paper:

@article{GuerreroEtAl:PCPNet:EG:2018,
  title   = {{PCPNet}: Learning Local Shape Properties from Raw Point Clouds}, 
  author  = {Paul Guerrero and Yanir Kleiman and Maks Ovsjanikov and Niloy J. Mitra},
  year    = {2018},
  journal = {Computer Graphics Forum},
  volume = {37},
  number = {2},
  pages = {75-85},
  doi = {10.1111/cgf.13343},
}