This repository provides the source code used in the work of "Polyhedral Complex Derivation from Piecewise Trilinear Networks," published in NeurIPS 2024. The code is designed to be linear-time efficient using the predefined PyTorch library (v1.13+), making it easy to integrate into your workflows with the package of tropical.
To set up the required Python packages, run the following command in your terminal:
pip install -r requirements.txtThis command will install the necessary dependencies for the project, ensuring a smooth execution of the provided code.
For the Stanford 3D Scanning repository,
wget http://graphics.stanford.edu/pub/3Dscanrep/bunny.tar.gz -P tropical/stanford
tar xvf tropical/stanford/bunny.tar.gz -C tropical/stanford
wget http://graphics.stanford.edu/pub/3Dscanrep/dragon/dragon_recon.tar.gz -P tropical/stanford
tar xvf tropical/stanford/dragon_recon.tar.gz -C tropical/stanford
wget http://graphics.stanford.edu/pub/3Dscanrep/happy/happy_recon.tar.gz -P tropical/stanford
tar xvf tropical/stanford/happy_recon.tar.gz -C tropical/stanford
wget http://graphics.stanford.edu/pub/3Dscanrep/armadillo/Armadillo.ply.gz -P tropical/stanford
mkdir tropical/stanford/armadillo
gzip -d tropical/stanford/Armadillo.ply.gz
mv tropical/stanford/Armadillo.ply tropical/stanford/armadillo/Armadillo.ply
wget http://graphics.stanford.edu/pub/3Dscanrep/drill.tar.gz -P tropical/stanford
tar xvf tropical/stanford/drill.tar.gz -C tropical/stanford
wget http://graphics.stanford.edu/data/3Dscanrep/lucy.tar.gz -P tropical/stanford
tar xvf tropical/stanford/lucy.tar.gz -C tropical/stanford
mkdir tropical/stanford/lucy
mv tropical/stanford/lucy.ply tropical/stanford/lucy.tgz files listed below contain subdirectories. Simply extract it into the root of the project directory.
For the tenth-reduced mesh of the Lucy [Google Drive][OneDrive],
tar xvf lucy_res10.tgz.tgz files listed below contain subdirectories. Simply extract it into the root of the project directory.
For the pretrained SDFs for the Small networks [Google Drive][OneDrive],
tar xvf stanford_small_models.tgzFor the pretrained SDFs for the Small and Large networks [Google Drive][OneDrive],
tar xvf stanford_models.tgzFor the Stanford [bunny|drill|happy|dragon|armadillo|lucy]:
python -m tropical.stanford.train -d {bunny|drill|happy|dragon|armadillo|lucy} -eNote that -h option gives you this:
usage: python -m tropical.stanford.train [-h]
[-d {bunny,dragon,happy,armadillo,drill,lucy}]
[-s SEED] [-c]
[-m {small,medium,large}] [-e] [-f]
Polyhedral complex derivation from piecewise trilinear networks
optional arguments:
-h, --help show this help message and exit
-d {bunny,dragon,happy,armadillo,drill,lucy}, --dataset {bunny,dragon,happy,armadillo,drill,lucy}
Stanford 3D scanning model name
-s SEED, --seed SEED Seed
-c, --cache Cache the trained SDF?
-m {small,medium,large}, --model_size {small,medium,large}
Model size
-e, --eval Run evaluation?
-f, --force Force flat assumption to skip curve approximation.The above script will generate the extracted meshes under the path of ./meshes. Or you could check with our generations with this command [Google Drive][OneDrive]:
tar xvf meshes.tgzThe *.ply extension refers to the Polygon File Format or Stanford Triangle Format, which is a file format commonly used to store three-dimensional data. You can easily visualize them by simply dragging and dropping them onto the website of https://3dviewer.net.
This training code is not guarantee the convergence of training nor a reliable SDF. For the reproduction, please use the attached trained SDFs with the corresponding seeds. Although the seed produced the same result with our machine, it may differ in other circumstances.
The -f option enforces the planarity assumption, bypassing curve approximation. Surprisingly, it is proved that approximating the curved hypersurface is unnecessary for precise edge subdivision. However, naively skipping this approximation can lead to failures in consecutive edge subdivision processes due to inaccuracies in identifying trilinear regions using the epsilon-tolerate sign vectors. To address this issue, we automatically modify the sign vectors to align with the engaging hypersurfaces at the current step, overriding the epsilon-based sign vectors (Def. 3.4) to set the indices of known hypersurfaces for the new vertices to one. Note that the -f option is set to True by default to ensure robustness with the learned SDF and to enhance inference speed by eliminating the need for curve approximation calculations.
In the paper, the Small bunny has a slight variation in preprocessing. We used the bunny.npy file below (though this difference is negligible) and applied a scaling factor to fit the data within the range of [-1, 1], which may affect the Chamfer distance. To utilize this preprocessing, you can use bunny_npy instead of bunny for -d option.
wget https://github.com/lzhnb/Primitive3D/raw/main/examples/data/bunny.npy -P tropical/stanford/models/.
Please note that the default Marching Cubes (MC) resolution for the pseudo-ground truth is set to 512^3 for the better accuracy. If you would like to change it to 256^3 for reproduction, please refer to tropical/stanford/train.py#L331.
Should you find this repository beneficial for your work, please consider citing it.
@inproceedings{kim2024tropical,
author = {{Kim, Jin-Hwa}},
booktitle = {Advances in Neural Information Processing Systems 37 (NeurIPS)},
title = {Polyhedral Complex Derivation from Piecewise Trilinear Networks},
year = {2024}
}
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
