{"id":13444080,"url":"https://github.com/hkust-vgd/shellnet","last_synced_at":"2025-03-20T17:33:07.540Z","repository":{"id":113748480,"uuid":"212496921","full_name":"hkust-vgd/shellnet","owner":"hkust-vgd","description":"ShellNet: Efficient Point Cloud Convolutional Neural Networks using Concentric Shells Statistics","archived":false,"fork":false,"pushed_at":"2019-10-03T05:03:17.000Z","size":81,"stargazers_count":87,"open_issues_count":15,"forks_count":23,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-28T07:42:43.658Z","etag":null,"topics":["classification","convolution","neural-networks","point-clouds","segmentation"],"latest_commit_sha":null,"homepage":"https://hkust-vgd.github.io/shellnet/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hkust-vgd.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-10-03T04:29:34.000Z","updated_at":"2024-08-27T17:42:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"495c73df-be85-4d78-9472-b78300ff13cd","html_url":"https://github.com/hkust-vgd/shellnet","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hkust-vgd%2Fshellnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hkust-vgd%2Fshellnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hkust-vgd%2Fshellnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hkust-vgd%2Fshellnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hkust-vgd","download_url":"https://codeload.github.com/hkust-vgd/shellnet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244660985,"owners_count":20489439,"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","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":["classification","convolution","neural-networks","point-clouds","segmentation"],"created_at":"2024-07-31T03:02:18.469Z","updated_at":"2025-03-20T17:33:07.200Z","avatar_url":"https://github.com/hkust-vgd.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# ShellNet: Efficient Point Cloud Convolutional Neural Networks using Concentric Shells Statistics\n\nInternational Conference on Computer Vision (ICCV) 2019 (Oral)\n\nZhiyuan Zhang, Binh-Son Hua, Sai-Kit Yeung.\n\n## Introduction\nThis is the code release of our paper about building a convolution and neural network for point cloud learning such that the training is fast and accurate. We address this problem by learning point features in regions called 'shells', which resolves point orders and produces local features altogether. Please find the details of the technique in our [project page](https://hkust-vgd.github.io/shellnet/).\n\nIf you found this paper useful in your research, please cite:\n```\n@inproceedings{zhang-shellnet-iccv19,\n    title = {ShellNet: Efficient Point Cloud Convolutional Neural Networks using Concentric Shells Statistics},\n    author = {Zhiyuan Zhang and Binh-Son Hua and Sai-Kit Yeung},\n    booktitle = {International Conference on Computer Vision (ICCV)},\n    year = {2019}\n}\n```\n\n## Installation\nThe code is based on [PointCNN](https://github.com/yangyanli/PointCNN). Please install [TensorFlow](https://www.tensorflow.org/install/), and follow the instruction in [PointNet++](https://github.com/charlesq34/pointnet2) to compile the customized TF operators in the `tf_ops` folder.  \n\nThe code has been tested with Python 3.6, TensorFlow 1.13.2, CUDA 10.0 and cuDNN 7.3 on Ubuntu 14.04.\n\n## Code Explanation\nThe core convolution, ShellConv, and the neural network, ShellNet, are defined in [shellconv.py](shellconv.py).\n\n### Convolution Parameters\nLet us take the `sconv_params` from [s3dis.py](setting/seg_s3dis.py) as an example:\n```\nss = 8 \nsconv_param_name = ('K', 'D', 'P', 'C')\nsconv_params = [dict(zip(sconv_param_name, sconv_param)) for sconv_param in\n                [\n                 (ss*4, 4, 512, 128),\n                 (ss*2, 2, 128, 256),\n                 (ss*1, 1, 32, 512)]]\n```\n`ss` indicates the shell size which is defined as the number of points contained in each shell. Each element in `sconv_params` is a tuple of `(K, D, P, C)`, where `K` is the neighborhood size, `D` is number of shells, `P` is the representative point number in the output, and `C` is the output channel number.  Each tuple specifies the parameters of one `ShellConv` layer, and they are stacked to create a deep network.\n\n### Deconvolution Parameters\nSimilarly, for deconvolution, let us look at `sdconv_params` from [s3dis.py](setting/seg_s3dis.py):\n```\nsdconv_param_name = ('K', 'D', 'pts_layer_idx', 'qrs_layer_idx')\nsdconv_params = [dict(zip(sdconv_param_name, sdconv_param)) for sdconv_param in\n                [\n                (ss*1,  1, 2, 1),\n                (ss*2,  2, 1, 0),\n                (ss*4,  4, 0, -1)]]\n```\nEach element in `sdconv_params` is a tuple of `(K, D, pts_layer_idx, qrs_layer_idx)`, where `K` and `D` have the same meaning as that in `sconv_params`, `pts_layer_idx` specifies the output of which `ShellConv` layer (from the `sconv_params`) will be the input of this `ShellDeConv` layer, and `qrs_layer_idx` specifies the output of which `ShellConv` layer (from the `sconv_params`) will be forwarded and fused with the output of this `ShellDeConv` layer. The `P` and `C` parameters of this `ShellDeConv` layer is also determined by `qrs_layer_idx`. Similarly, each tuple specifies the parameters of one `ShellDeConv` layer, and they are stacked to create a deep network.\n\n\n\n## Usage\n### Classification\n\nTo train a ShellNet model to classify shapes in the ModelNet40 dataset:\n```\ncd data_conversions\npython3 ./download_datasets.py -d modelnet\ncd ..\npython3 train_val_cls.py\npython3 test_cls_modelnet40.py -l log/cls/xxxx\n```\nOur pretrained model can be downloaded [here](https://gohkust-my.sharepoint.com/:u:/g/personal/saikit_ust_hk/EQsJFdSR6YJMsco8Dqss_3kBgTKD8rWfHQcZt7yR9rigTQ?e=3Bj4mK). Please put it to `log/cls/modelnet_pretrained` folder to test.\n\n\n### Segmentation\nWe perform segmentation with various datasets, as follows.\n\n#### ShapeNet\n```\ncd data_conversions\npython3 ./download_datasets.py -d shapenet_partseg\npython3 ./prepare_partseg_data.py -f ../../data/shapenet_partseg\ncd ..\npython3 train_val_seg.py -x seg_shapenet\npython3 test_seg_shapenet.py -l log/seg/shellconv_seg_shapenet_xxxx/ckpts/epoch-xxx\ncd evaluation\npython3 eval_shapenet_seg.py -g ../../data/shapenet_partseg/test_label -p ../../data/shapenet_partseg/test_pred_shellnet_1 -a\n```\n\n#### ScanNet\nPlease refer to ScanNet [homepage](http://www.scan-net.org) and PointNet++ preprocessed [data](https://github.com/charlesq34/pointnet2/tree/master/scannet) to download ScanNet. After that, the following script can be used for training and testing:\n```\ncd data_conversions\npython3 prepare_scannet_seg_data.py\npython3 prepare_scannet_seg_filelists.py\ncd ..\npython3 train_val_seg.py -x seg_scannet\npython3 test_seg_scannet.py -l log/seg/shellconv_seg_scannet_xxxx/ckpts/epoch-xxx\ncd evaluation\npython3 eval_scannet.py -d \u003cpath to *_pred.h5\u003e -p \u003cpath to scannet_test.pickle\u003e\n```\n\n#### S3DIS\nPlease download the [S3DIS dataset](http://buildingparser.stanford.edu/dataset.html#Download). The following script performs training and testing:\n```\ncd data_conversions\npython3 prepare_s3dis_label.py\npython3 prepare_s3dis_data.py\npython3 prepare_s3dis_filelists.py\ncd ..\npython3 train_val_seg.py -x seg_s3dis\npython3 test_seg_s3dis.py -l log/seg/shellconv_seg_s3dis_xxxx/ckpts/epoch-xxx\ncd evaluation\npython3 s3dis_merge.py -d \u003cpath to *_pred.h5\u003e\npython3 eval_s3dis.py\n```\nPlease notice that these command just for `Area 1` validation. Results on other Areas can be computed by modifying the `filelist` and `filelist_val` in [s3dis.py](setting/seg_s3dis.py).\n\n#### Semantic3D\nYou can download our preprocessed hdf5 files and labels [here](https://gohkust-my.sharepoint.com/:u:/g/personal/saikit_ust_hk/Ea_S7Yb-n7JLp1wK5xFihfYBI6vAzHWaA548ytu5k84kdQ?e=YXRcaK). Then:\n```\npython3 train_val_seg.py -x seg_semantic3d\npython3 test_seg_semantic3d.py -l log/seg/shellconv_seg_semantic3d_xxxx/ckpts/epoch-xxx\ncd evaluation\npython3 semantic3d_merge.py -d \u003cpath to *_pred.h5\u003e -v \u003creduced or full\u003e\n```\n\nIf you prefer to process the data by yourself, here are the steps we used. In general, this data preprocessing of this dataset is more involved. First, please download the original [Semantic3D dataset](http://www.semantic3d.net/view_dbase.php). We then downsample the data using this [script](https://github.com/intel-isl/Open3D-PointNet2-Semantic3D). Finally, we follow PointCNN's [script](https://github.com/yangyanli/PointCNN/tree/master/data_conversions) to split the data into training and validation set, and prepare the .h5 files. \n## License\nThis repository is released under MIT License (see LICENSE file for details).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkust-vgd%2Fshellnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhkust-vgd%2Fshellnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkust-vgd%2Fshellnet/lists"}