{"id":27338474,"url":"https://github.com/chenzhaiyu/polygnn","last_synced_at":"2025-04-12T15:26:45.062Z","repository":{"id":230937092,"uuid":"667584119","full_name":"chenzhaiyu/polygnn","owner":"chenzhaiyu","description":"PolyGNN: Polyhedron-based graph neural network for 3D building reconstruction from point clouds [ISPRS 2024]","archived":false,"fork":false,"pushed_at":"2025-03-13T09:17:59.000Z","size":2340,"stargazers_count":122,"open_issues_count":4,"forks_count":14,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-13T10:26:39.114Z","etag":null,"topics":["3d","building","gnn","point-cloud","reconstruction"],"latest_commit_sha":null,"homepage":"https://github.com/chenzhaiyu/polygnn","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/chenzhaiyu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-17T21:04:17.000Z","updated_at":"2025-03-13T09:18:03.000Z","dependencies_parsed_at":"2024-04-01T17:50:37.877Z","dependency_job_id":"4eacbe90-916a-4411-ab32-8a3200f32a15","html_url":"https://github.com/chenzhaiyu/polygnn","commit_stats":null,"previous_names":["chenzhaiyu/polygnn"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenzhaiyu%2Fpolygnn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenzhaiyu%2Fpolygnn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenzhaiyu%2Fpolygnn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenzhaiyu%2Fpolygnn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chenzhaiyu","download_url":"https://codeload.github.com/chenzhaiyu/polygnn/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248588225,"owners_count":21129353,"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":["3d","building","gnn","point-cloud","reconstruction"],"created_at":"2025-04-12T15:26:43.242Z","updated_at":"2025-04-12T15:26:45.047Z","avatar_url":"https://github.com/chenzhaiyu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PolyGNN\n\n-----------\n[![Paper: HTML](https://img.shields.io/badge/Paper-HTML-yellow)](https://www.sciencedirect.com/science/article/pii/S0924271624003691) \n[![Paper: PDF](https://img.shields.io/badge/Paper-PDF-green)](https://www.sciencedirect.com/science/article/pii/S0924271624003691/pdfft?md5=3d0d8b3b72cdd3f4c809d714b1292137\u0026pid=1-s2.0-S0924271624003691-main.pdf) \n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/chenzhaiyu/polygnn/main/LICENSE)\n\nPolyGNN is an implementation of the paper [*PolyGNN: Polyhedron-based Graph Neural Network for 3D Building Reconstruction from Point Clouds*](https://www.sciencedirect.com/science/article/pii/S0924271624003691). \nPolyGNN learns a piecewise planar occupancy function, supported by polyhedral decomposition, for efficient and scalable 3D building reconstruction.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://raw.githubusercontent.com/chenzhaiyu/polygnn/master/docs/architecture.png\" width=\"680\"/\u003e\n\u003c/p\u003e\n\n## 🛠️ Setup\n\n### Repository\n\nClone the repository:\n\n```bash\ngit clone https://github.com/chenzhaiyu/polygnn \u0026\u0026 cd polygnn\n```\n\n### All-in-one installation\n\nCreate a conda environment with all dependencies:\n\n```bash\nconda env create -f environment.yml \u0026\u0026 conda activate polygnn\n```\n\n### Manual installation\n\nStill easy! Create a conda environment and install [mamba](https://github.com/mamba-org/mamba) for faster parsing:\n```bash\nconda create --name polygnn python=3.10 \u0026\u0026 conda activate polygnn\nconda install mamba -c conda-forge\n```\n\nInstall the required dependencies:\n```\nmamba install pytorch torchvision sage=10.0 pytorch-cuda=11.7 pyg=2.3 pytorch-scatter pytorch-sparse pytorch-cluster torchmetrics rtree -c pyg -c pytorch -c nvidia -c conda-forge\npip install abspy==0.2.6 hydra-core hydra-colorlog omegaconf trimesh tqdm wandb plyfile\n```\n\n## 🚀 Usage\n\n### Quick start\n\nDownload the mini dataset and pretrained weights:\n\n```python\npython download.py dataset=mini\n```\nIn case you encounter issues (e.g., Google Drive limits), manually download the data and weights [here](https://drive.google.com/drive/folders/1fAwvhGtOgS8f4IldE1J4v5s0438WM24b?usp=sharing), then extract them into `./checkpoints/mini` and `./data/mini`, respectively.\nThe mini dataset contains 200 random instances (~0.07% of the full dataset).\n\nTrain PolyGNN on the mini dataset (provided for your reference and is not intended for full-scale training):\n```python\npython train.py dataset=mini\n```\nThe data will be automatically preprocessed the first time you initiate training.\n\nEvaluate PolyGNN with option to save predictions:\n```python\npython test.py dataset=mini evaluate.save=true\n```\n\nGenerate meshes from predictions:\n```python\npython reconstruct.py dataset=mini reconstruct.type=mesh\n```\n\nRemap meshes to their original CRS:\n```python\npython remap.py dataset=mini\n```\n\nGenerate reconstruction statistics:\n```python\npython stats.py dataset=mini\n```\n\n### Available configurations\n\n```python\n# check available configurations for training\npython train.py --cfg job\n\n# check available configurations for evaluation\npython test.py --cfg job\n```\nAlternatively, review the configuration file: `conf/config.yaml`.\n\n### Full dataset\n\nThe Munich dataset is available for download on [Zenodo](https://zenodo.org/records/14254264). Note that it requires 332 GB of storage when decompressed. Meshes for CRS remapping can be downloaded [here](https://drive.google.com/file/d/1hn11XMqyoPUnq-9WGfAwQq47uuUvcbi7/view?usp=drive_link).\n\n### Custom data\n\nPolyGNN requires polyhedron-based graphs as input. To prepare this from your own point clouds:\n1. Extract planar primitives using tools such as [Easy3D](https://github.com/LiangliangNan/Easy3D) or [GoCoPP](https://github.com/Ylannl/GoCoPP), preferably in [VertexGroup](https://abspy.readthedocs.io/en/latest/vertexgroup.html) format.\n2. Build [CellComplex](https://abspy.readthedocs.io/en/latest/api.html#abspy.CellComplex) from the primitives using [abspy](https://github.com/chenzhaiyu/abspy). Example code:\n   ```python\n   from abspy import VertexGroup, CellComplex\n   vertex_group = VertexGroup(vertex_group_path, quiet=True)\n   cell_complex = CellComplex(vertex_group.planes, vertex_group.aabbs,\n                              vertex_group.points_grouped, build_graph=True, quiet=True)\n   cell_complex.prioritise_planes(prioritise_verticals=True)\n   cell_complex.construct()\n   cell_complex.save(complex_path)\n   ```\n   Alternatively, you can modify [`CityDataset`](https://github.com/chenzhaiyu/polygnn/blob/67addd77a6be1d100448e3bd7523babfa063d0dd/dataset.py#L157) or [`TestOnlyDataset`](https://github.com/chenzhaiyu/polygnn/blob/67addd77a6be1d100448e3bd7523babfa063d0dd/dataset.py#L276) to accept inputs directly from [VertexGroup](https://abspy.readthedocs.io/en/latest/vertexgroup.html) or [VertexGroupReference](https://abspy.readthedocs.io/en/latest/api.html#abspy.VertexGroupReference).\n3. Structure your dataset similarly to the provided mini dataset:\n   ```bash\n   YOUR_DATASET_NAME\n   └── raw\n       ├── 03_meshes\n       │   ├── DEBY_LOD2_104572462.obj\n       │   ├── DEBY_LOD2_104575306.obj\n       │   └── DEBY_LOD2_104575493.obj\n       ├── 04_pts\n       │   ├── DEBY_LOD2_104572462.npy\n       │   ├── DEBY_LOD2_104575306.npy\n       │   └── DEBY_LOD2_104575493.npy\n       ├── 05_complexes\n       │   ├── DEBY_LOD2_104572462.cc\n       │   ├── DEBY_LOD2_104575306.cc\n       │   └── DEBY_LOD2_104575493.cc\n       ├── testset.txt\n       └── trainset.txt\n   ```\n4. To train or evaluate PolyGNN using your dataset, run the following commands:\n   ```python\n   # start training\n   python train.py dataset=YOUR_DATASET_NAME\n   \n   # start evaluation\n   python test.py dataset=YOUR_DATASET_NAME\n   ```\n   For evaluation only, you can instantiate your dataset as a [`TestOnlyDataset`](https://github.com/chenzhaiyu/polygnn/blob/67addd77a6be1d100448e3bd7523babfa063d0dd/dataset.py#L276), as in [this line](https://github.com/chenzhaiyu/polygnn/blob/94ffc9e45f0721653038bd91f33f1d4eafeab7cb/test.py#L178).\n\n## 👷 TODOs\n\n- [x] Demo with mini data and pretrained weights\n- [x] Short tutorial for getting started\n- [x] Host the full dataset\n\n## 🎓 Citation\n\nIf you use PolyGNN in a scientific work, please consider citing the paper:\n\n```bibtex\n@article{chen2024polygnn,\ntitle = {PolyGNN: Polyhedron-based graph neural network for 3D building reconstruction from point clouds},\njournal = {ISPRS Journal of Photogrammetry and Remote Sensing},\nvolume = {218},\npages = {693-706},\nyear = {2024},\nissn = {0924-2716},\ndoi = {https://doi.org/10.1016/j.isprsjprs.2024.09.031},\nurl = {https://www.sciencedirect.com/science/article/pii/S0924271624003691},\nauthor = {Zhaiyu Chen and Yilei Shi and Liangliang Nan and Zhitong Xiong and Xiao Xiang Zhu},\n}\n```\n\nThe synthetic point clouds are simulated with [pyhelios](https://github.com/chenzhaiyu/pyhelios).\nYou might also want to check out [abspy](https://github.com/chenzhaiyu/abspy) for 3D adaptive binary space partitioning and [Points2Poly](https://github.com/chenzhaiyu/points2poly) for reconstruction with deep implicit fields.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenzhaiyu%2Fpolygnn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchenzhaiyu%2Fpolygnn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenzhaiyu%2Fpolygnn/lists"}