NDC

PyTorch implementation for paper Neural Dual Contouring, Zhiqin Chen, Andrea Tagliasacchi, Thomas Funkhouser, Hao Zhang.

Paper

<img src='teaser.png' />

Citation

If you find our work useful in your research, please consider citing:

@article{chen2022ndc,
  title={Neural Dual Contouring}, 
  author={Zhiqin Chen and Andrea Tagliasacchi and Thomas Funkhouser and Hao Zhang},
  journal={ACM Transactions on Graphics (Special Issue of SIGGRAPH)},
  volume = {41},
  number = {4},
  year={2022}
}

Requirements

• Python 3 with numpy, h5py, scipy, scikit-learn, trimesh, and Cython
• PyTorch 1.8 (other versions may also work)

Build Cython module:

python setup.py build_ext --inplace

Datasets and pre-trained weights

For data preparation, please see data_preprocessing.

We provide the ready-to-use datasets here.

• groundtruth_NDC.7z
• groundtruth_UNDC.7z

Backup links:

• groundtruth_NDC.7z (pwd: 1234)
• groundtruth_UNDC.7z (pwd: 1234)

We also provide the pre-trained network weights and some example shapes for quick testing.

• weights_examples.7z

Backup links:

• weights_examples.7z (pwd: 1234)

Testing on one shape

You can use the code to test a trained model on one shape. The following shows example commands for testing with the pre-trained network weights and example shapes provided above.

Basically, --test_input specifies the input file. It could be a grid of SDF or UDF values, a grid of binary occupancies, or a point cloud. The supported formats can be found in the example commands below. --input_type specifies the input type corresponding to the input file. --method specifies the method to be applied. It could be NDC, UNDC, or NDCx. NDCx is basically NDC with a more complex backbone network from our prior work Neural Marching Cubes (NMC) ; it is slower than NDC but has better reconstruction accuracy. --postprocessing indicates the result will be post-processed to remove small holes; it can only be applied to UNDC outputs.

To test on SDF input:

python main.py --test_input examples/bunny.sdf --input_type sdf --method ndc
python main.py --test_input examples/bunny.sdf --input_type sdf --method ndcx
python main.py --test_input examples/bunny.sdf --input_type sdf --method undc --postprocessing

Note that the sdf file should be produced by SDFGen in data_preprocessing. You can also use an hdf5 file to store the inputs (explained below).

To test on binary voxel input:

python main.py --test_input examples/cad.binvox --input_type voxel --method ndc
python main.py --test_input examples/cad.binvox --input_type voxel --method ndcx
python main.py --test_input examples/cad.binvox --input_type voxel --method undc --postprocessing

To test on UDF input:

python main.py --test_input examples/bunny.sdf --input_type udf --method undc --postprocessing
python main.py --test_input examples/tshirt.sdf --input_type udf --method undc --postprocessing

Note that when --input_type is specified as UDF, any input will be converted to a grid of non-negative values.

To test on point cloud input:

python main.py --test_input examples/mobius.ply --input_type pointcloud --method undc --postprocessing --point_num 1024 --grid_size 64
python main.py --test_input examples/tshirt.ply --input_type pointcloud --method undc --postprocessing --point_num 8192 --grid_size 128

Note that --point_num specifies the maximum number of input points; if the input file contains more points than the specified number, the point cloud will be sub-sampled. --grid_size specifies the size of the output grid.

You can use an hdf5 file to store the inputs for testing:

python main.py --test_input examples/cad.hdf5 --input_type sdf --method ndc
python main.py --test_input examples/cad.hdf5 --input_type voxel --method ndc
python main.py --test_input examples/cad.hdf5 --input_type udf --method undc --postprocessing
python main.py --test_input examples/cad.hdf5 --input_type pointcloud --method undc --postprocessing --point_num 4096 --grid_size 64

You can use the above commands to test a single shape from the training/testing data, which are in hdf5 format. If you need to convert shapes of other formats into hdf5, please read and modify the dataloader code.

To test on a large scene (noisy point cloud input):

python main.py --test_input examples/E9uDoFAP3SH_region31.ply --input_type noisypc --method undc --postprocessing --point_num 524288 --grid_size 64 --block_num_per_dim 10

Note that the code will crop the entire scene into overlapping patches. --point_num specifies the maximum number of input points per patch. --grid_size specifies the size of the output grid per patch. --block_padding controls the boundary padding for each patch to make the patches overlap with each other so as to avoid seams; the default value is good enough in most cases. --block_num_per_dim specifies how many crops the scene will be split into. In the above command, the input point cloud will be normalized into a cube and the cube will be split into 10x10x10 patches (although some patches are empty).

Training and Testing

To train/test NDC with SDF input:

python main.py --train_float --input_type sdf --method ndc --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_NDC --checkpoint_save_frequency 50
python main.py --test_bool_float --input_type sdf --method ndc --data_dir ./groundtruth/gt_NDC

To train/test NDCx with SDF input:

python main.py --train_float --input_type sdf --method ndcx --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_NDC --checkpoint_save_frequency 50
python main.py --test_bool_float --input_type sdf --method ndcx --data_dir ./groundtruth/gt_NDC

To train/test UNDC with SDF input:

python main.py --train_bool --input_type sdf --method undc --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_UNDC --checkpoint_save_frequency 50
python main.py --train_float --input_type sdf --method undc --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_UNDC --checkpoint_save_frequency 50
python main.py --test_bool_float --input_type sdf --method undc --data_dir ./groundtruth/gt_UNDC

To train/test NDC with binary voxel input:

python main.py --train_bool --input_type voxel --method ndc --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_NDC --checkpoint_save_frequency 50
python main.py --train_float --input_type voxel --method ndc --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_NDC --checkpoint_save_frequency 50
python main.py --test_bool_float --input_type voxel --method ndc --data_dir ./groundtruth/gt_NDC

To train/test NDCx with binary voxel input:

python main.py --train_bool --input_type voxel --method ndcx --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_NDC --checkpoint_save_frequency 50
python main.py --train_float --input_type voxel --method ndcx --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_NDC --checkpoint_save_frequency 50
python main.py --test_bool_float --input_type voxel --method ndcx --data_dir ./groundtruth/gt_NDC

To train/test UNDC with binary voxel input:

python main.py --train_bool --input_type voxel --method undc --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_UNDC --checkpoint_save_frequency 50
python main.py --train_float --input_type voxel --method undc --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_UNDC --checkpoint_save_frequency 50
python main.py --test_bool_float --input_type voxel --method undc --data_dir ./groundtruth/gt_UNDC

To train/test UNDC with UDF input:

python main.py --train_bool --input_type udf --method undc --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_UNDC --checkpoint_save_frequency 50
python main.py --train_float --input_type udf --method undc --epoch 400 --lr_half_life 100 --data_dir ./groundtruth/gt_UNDC --checkpoint_save_frequency 50
python main.py --test_bool_float --input_type udf --method undc --data_dir ./groundtruth/gt_UNDC

To train/test UNDC with point cloud input:

python main.py --train_bool --input_type pointcloud --method undc --epoch 250 --lr_half_life 100 --data_dir ./groundtruth/gt_UNDC --checkpoint_save_frequency 10 --point_num 4096 --grid_size 64
python main.py --train_float --input_type pointcloud --method undc --epoch 250 --lr_half_life 100 --data_dir ./groundtruth/gt_UNDC --checkpoint_save_frequency 10 --point_num 4096 --grid_size 64
python main.py --test_bool_float --input_type pointcloud --method undc --data_dir ./groundtruth/gt_UNDC --point_num 4096 --grid_size 64

To train UNDC with noisy point cloud input, you need to prepare the augmented training data, see instructions in data_preprocessing. Then run the following commands for training.

python main.py --train_bool --input_type noisypc --method undc --epoch 20 --lr_half_life 5 --data_dir ./groundtruth/gt_UNDCa --checkpoint_save_frequency 1 --point_num 16384 --grid_size 64
python main.py --train_float --input_type noisypc --method undc --epoch 20 --lr_half_life 5 --data_dir