{"id":33279269,"url":"https://paschalidoud.github.io/neural_parts","last_synced_at":"2025-11-22T04:02:22.352Z","repository":{"id":49369218,"uuid":"348127349","full_name":"paschalidoud/neural_parts","owner":"paschalidoud","description":"Code for \"Neural Parts: Learning Expressive 3D Shape Abstractions with Invertible Neural Networks\", CVPR 2021","archived":false,"fork":false,"pushed_at":"2021-03-19T01:40:25.000Z","size":3777,"stargazers_count":170,"open_issues_count":3,"forks_count":22,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-08-24T12:49:45.795Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://paschalidoud.github.io/neural_parts","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paschalidoud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-15T21:26:44.000Z","updated_at":"2025-08-14T17:40:22.000Z","dependencies_parsed_at":"2022-09-05T03:00:32.825Z","dependency_job_id":null,"html_url":"https://github.com/paschalidoud/neural_parts","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/paschalidoud/neural_parts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paschalidoud%2Fneural_parts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paschalidoud%2Fneural_parts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paschalidoud%2Fneural_parts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paschalidoud%2Fneural_parts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paschalidoud","download_url":"https://codeload.github.com/paschalidoud/neural_parts/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paschalidoud%2Fneural_parts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285731803,"owners_count":27222214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-22T02:00:05.934Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-11-17T11:00:25.405Z","updated_at":"2025-11-22T04:02:22.347Z","avatar_url":"https://github.com/paschalidoud.png","language":"Python","funding_links":[],"categories":["Models"],"sub_categories":["3D Shape"],"readme":"## Neural Parts: Learning Expressive 3D Shape Abstractions with Invertible Neural Networks\n\u003cp\u003e\n    \u003cimg width=\"240\" alt=\"Example 1\" src=\"img/human.gif\"/\u003e\n    \u003cimg width=\"240\" alt=\"Example 2\" src=\"img/plane.gif\"/\u003e\n    \u003cimg width=\"240\" alt=\"Example 3\" src=\"img/chair.gif\"/\u003e\n\u003c/p\u003e\n\nThis repository contains the code that accompanies our CVPR 2021 paper\n[Neural Parts: Learning Expressive 3D Shape Abstractions with Invertible Neural Networks](https://paschalidoud.github.io/neural_parts)\n\nYou can find detailed usage instructions for training your own models and using our pretrained models below.\n\nIf you found this work influential or helpful for your research, please consider citing\n\n```\n@Inproceedings{Paschalidou2021CVPR,\n     title = {Neural Parts: Learning Expressive 3D Shape Abstractions with Invertible Neural Networks},\n     author = {Paschalidou, Despoina and Katharopoulos, Angelos and Geiger, Andreas and Fidler, Sanja},\n     booktitle = {Proceedings IEEE Conf. on Computer Vision and Pattern Recognition (CVPR)},\n     year = {2021}\n}\n```\n\n## Installation \u0026 Dependencies\n\nOur codebase has the following dependencies:\n\n- [numpy](https://numpy.org/doc/stable/user/install.html)\n- [cython](https://cython.readthedocs.io/en/latest/src/quickstart/build.html)\n- [pillow](https://pillow.readthedocs.io/en/stable/installation.html)\n- [pyyaml](https://pyyaml.org/wiki/PyYAMLDocumentation)\n- [torch \u0026\u0026 torchvision](https://pytorch.org/get-started/locally/)\n- [trimesh](https://github.com/mikedh/trimesh)\n- [tqdm](https://github.com/tqdm/tqdm)\n\nFor the visualizations, we use [simple-3dviz](http://simple-3dviz.com), which\nis our easy-to-use library for visualizing 3D data using Python and ModernGL and\n[matplotlib](https://matplotlib.org/) for the colormaps. Note that\n[simple-3dviz](http://simple-3dviz.com) provides a lightweight and easy-to-use\nscene viewer using [wxpython](https://www.wxpython.org/). If you wish you use\nour scripts for visualizing the reconstructed primitives, you will need to also\ninstall [wxpython](https://anaconda.org/anaconda/wxpython).\n\nThe simplest way to make sure that you have all dependencies in place is to use\n[conda](https://docs.conda.io/projects/conda/en/4.6.1/index.html). You can\ncreate a conda environment called ```neural_parts``` using\n```\nconda env create -f environment.yaml\nconda activate neural_parts\n```\n\nNext compile the extenstion modules. You can do this via\n```\npython setup.py build_ext --inplace\npip install -e .\n```\n\n## Demo\n\n![Example Output](img/example_output_1.gif)\n![Example Output](img/example_output_2.gif)\n\nYou can now test our code on various inputs. To this end, simply download some\ninput samples together with our pretrained models on D-FAUAST humans, ShapeNet chairs and ShapeNet planes\nfrom\n[here](https://drive.google.com/drive/folders/11U0q441kOXJL1tx2WLott4XNJ0m7HCLs?usp=sharing).\nNow extract the ``nerual_parts_demo.zip`` that you just downloaded in the demo\nfolder. To run our demo on the D-FAUST humans simply run\n```\npython demo.py ../config/dfaust_6.yaml --we ../demo/model_dfaust_6 --model_tag 50027_jumping_jacks:00135 --camera_target='-0.030173788,-0.10342446,-0.0021887198' --camera_position='0.076685235,-0.14528269,1.2060229' --up='0,1,0' --with_rotating_camera\n```\nThis script should create a folder ``demo/output``, where the per-primitive\nmeshes are stored as ``.obj`` files. Similarly, you can now also run the demo for the input airplane\n```\npython demo.py ../config/shapenet_5.yaml --we ../demo/model_planes_5 --model_tag 02691156:7b134f6573e7270fb0a79e28606cb167 --camera_target='-0.030173788,-0.10342446,-0.0021887198' --camera_position='0.076685235,-0.14528269,1.2060229' --up='0,1,0' --with_rotating_camera\n```\n\n## Usage\n\nAs soon as you have installed all dependencies and have obtained the\npreprocessed data, you can now start training new models from scratch, evaluate\nour pre-trained models and visualize the recovered primitives using one of our\npre-trained models.\n\n### Reconstruction\nTo generate meshes using a trained model, we provide the\n``forward_pass.py`` and the ``visualize_predictions.py`` scripts. Their\ndifference is that the first performs the forward pass and generates a\nper-primitive mesh that is saved as an ``.obj`` file. Similarly, the\n``visualize_predictions.py`` script performs the forward pass and visualizes\nthe predicted primitives using [simple-3dviz](https://simple-3dviz.com/). The\n``forward_pass.py`` script is ideal for reconstructing inputs on a heeadless\nserver and you can run it by executing\n```\npython forward_pass.py path_to_config_yaml path_to_output_dir --weight_file path_to_weight_file --model_tag MODEL_TAG\n```\nwhere the argument ``--weight_file`` specifies the path to a trained model and\nthe argument ``--model_tag`` defines the model_tag of the input to be\nreconstructed.\n\nTo run the ``visualize_predictions.py`` script you need to run\n```\npython visualize_predictions.py path_to_config_yaml path_to_output_dir --weight_file path_to_weight_file --model_tag MODEL_TAG\n```\nUsing this script, you can easily render the prediction into ``.png`` images or\na ``.gif``, as well as perform various animations by rotating the camera.\nFurthermore, you can also specify the camera position, the up vector and the\ncamera target as well as visualize the target mesh together with the predicted\nprimitives simply by adding the ``--mesh`` argument.\n\n### Evaluation\nFor evaluation of the models we provide the script ``evaluate.py``. You can run it using:\n```\npython evaluate.py path_to_config_yaml path_to_output_dir\n```\nThe script reconstructs the input and evaluates the generated meshes using a\nstandardized protocol. For each input, the script generates a ``.npz`` file\nthat contains the various metrics for that particular input. Note that this\nscript can also be executed multiple times in order to speed up the evaluation\nprocess. For example, if you wish to run the evaluation on 6 nodes, you can\nsimply run\n\n```\nfor i in {1..6}; do python evaluate.py path_to_config_yaml path_to_output_dir \u0026 done\n[1] 9489\n[2] 9490\n[3] 9491\n[4] 9492\n[5] 9493\n[6] 9494\n\nwait\nRunning code on cpu\nRunning code on cpu\nRunning code on cpu\nRunning code on cpu\nRunning code on cpu\nRunning code on cpu\n```\nAgain the script generates a per-input file in the output directory with the\ncomputed metrics.\n\n### Training\nFinally, to train a new network from scratch, we provide the\n``train_network.py`` script. To execute this script, you need to specify the\npath to the configuration file you wish to use and the path to the output\ndirectory, where the trained models and the training statistics will be saved.\nNamely, to train a new model from scratch, you simply need to run\n```\npython train_network.py path_to_config_yaml path_to_output_dir\n```\nNote tha it is also possible to start from a previously trained model by\nspecifying the ``--weight_file`` argument, which should contain the path to a\npreviously trained model. Furthermore, by using the arguments `--model_tag` and\n``--category_tag``, you can also train your network on a particular model (e.g.\na specific plane, car, human etc.) or a specific object category (e.g. planes,\nchairs etc.)\n\nNote that, if you want to use the RAdam optimizer during training, you will have\nto also install to download and install the corresponding code from [this\nrepository](https://github.com/LiyuanLucasLiu/RAdam).\n\n## License\nOur code is released under the MIT license which practically allows anyone to do anything with it.\nMIT license found in the LICENSE file.\n\n## Relevant Research\nBelow we list some papers that are relevant to our work.\n\n**Ours:**\n- Learning Unsupervised Hierarchical Part Decomposition of 3D Objects from a Single RGB Image [pdf](https://paschalidoud.github.io/),[project-page](https://superquadrics.com/hierarchical-primitives.html)\n- Superquadrics Revisited: Learning 3D Shape Parsing beyond Cuboids [pdf](https://arxiv.org/pdf/1904.09970.pdf),[project-page](https://superquadrics.com/learnable-superquadrics.html)\n\n**By Others:**\n- Learning Shape Abstractions by Assembling Volumetric Primitives [pdf](https://arxiv.org/pdf/1612.00404.pdf)\n- 3D-PRNN: Generating Shape Primitives with Recurrent Neural Networks [pdf](https://arxiv.org/abs/1708.01648.pdf)\n- Im2Struct: Recovering 3D Shape Structure From a Single RGB Image [pdf](http://openaccess.thecvf.com/content_cvpr_2018/html/Niu_Im2Struct_Recovering_3D_CVPR_2018_paper.pdf)\n- Learning shape templates with structured implicit functions [pdf](https://arxiv.org/abs/1904.06447)\n- CvxNet: Learnable Convex Decomposition [pdf](https://arxiv.org/abs/1909.05736)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/paschalidoud.github.io%2Fneural_parts","html_url":"https://awesome.ecosyste.ms/projects/paschalidoud.github.io%2Fneural_parts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/paschalidoud.github.io%2Fneural_parts/lists"}