{"id":27338521,"url":"https://github.com/chenzhaiyu/abspy","last_synced_at":"2025-08-25T18:51:23.456Z","repository":{"id":44919782,"uuid":"340181236","full_name":"chenzhaiyu/abspy","owner":"chenzhaiyu","description":"A Python tool for 3D adaptive binary space partitioning and beyond","archived":false,"fork":false,"pushed_at":"2024-03-13T14:50:18.000Z","size":4158,"stargazers_count":61,"open_issues_count":1,"forks_count":10,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-05-06T00:02:56.730Z","etag":null,"topics":["3d","adaptive","binary-space-partition","point-cloud","python","reconstruction"],"latest_commit_sha":null,"homepage":"https://abspy.readthedocs.io/","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":"CHANGELOG.md","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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-02-18T21:23:59.000Z","updated_at":"2024-04-28T21:14:44.000Z","dependencies_parsed_at":"2023-12-15T22:06:05.996Z","dependency_job_id":"1cd27eea-4f47-430e-b260-1c8d58acddcf","html_url":"https://github.com/chenzhaiyu/abspy","commit_stats":{"total_commits":94,"total_committers":3,"mean_commits":"31.333333333333332","dds":"0.42553191489361697","last_synced_commit":"083a02ce7a2abcd81655c41295de2b25f48c9abd"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenzhaiyu%2Fabspy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenzhaiyu%2Fabspy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenzhaiyu%2Fabspy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenzhaiyu%2Fabspy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chenzhaiyu","download_url":"https://codeload.github.com/chenzhaiyu/abspy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248588275,"owners_count":21129362,"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","adaptive","binary-space-partition","point-cloud","python","reconstruction"],"created_at":"2025-04-12T15:26:55.773Z","updated_at":"2025-08-25T18:51:23.396Z","avatar_url":"https://github.com/chenzhaiyu.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/chenzhaiyu/abspy/main/docs/source/_static/images/logo.png\" width=\"480\"/\u003e\n\n-----------\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![PyPI version](https://img.shields.io/pypi/v/abspy)](https://pypi.python.org/pypi/abspy/) [![PyPI downloads](https://img.shields.io/pypi/dm/abspy?color=blue)](https://pypi.python.org/pypi/abspy/) [![Build status](https://readthedocs.org/projects/abspy/badge/)](https://abspy.readthedocs.io/en/latest/)\n\n## Introduction\n\n***abspy*** is a Python tool for 3D *adaptive binary space partitioning* and beyond. It adaptively partitions ambient 3D space into a linear cell complex using planar primitives, dynamically generating an adjacency graph in the process. Designed primarily for compact surface reconstruction, *abspy* also supports a range of other applications.\n\n\u003cdiv align=\"center\" width=\"480\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/chenzhaiyu/abspy/main/docs/source/_static/images/animation.gif\"\u003e\u003cbr\u003e\n\u003c/div\u003e\n\n## Key features\n\n* Manipulation of planar primitives from point cloud or reference mesh\n* Linear cell complex creation with adaptive binary space partitioning (a-BSP)\n* Dynamic BSP-tree ([NetworkX](https://networkx.org/) graph) updated locally upon primitive insertion\n* Support of polygonal surface reconstruction with graph cut\n* Compatible data structure with [Easy3D](https://github.com/LiangliangNan/Easy3D) on point cloud, primitive, mesh and cell complex\n* Robust spatial operations underpinned by the rational ring from [SageMath](https://www.sagemath.org/)'s exact kernel\n\n## Installation\n\n### All-in-one installation\n\nCreate a conda environment with the latest *abspy* release and all its dependencies installed:\n\n```bash\ngit clone https://github.com/chenzhaiyu/abspy \u0026\u0026 cd abspy\nconda env create -f environment.yml \u0026\u0026 conda activate abspy\n```\n\n### Manual installation\n\nStill easy! Create a conda environment and enter it: \n\n```bash\nconda create --name abspy python=3.11 \u0026\u0026 conda activate abspy\n```\n\nInstall the dependencies:\n\n```bash\n# You may replace `conda` with `mamba` for faster package parsing\n# conda install mamba -c conda-forge\nconda install -c conda-forge networkx numpy tqdm scikit-learn matplotlib colorlog scipy trimesh rtree pyglet sage=10.2 \n```\n\nPreferably, the latest *abspy* release can be found and installed via [PyPI](https://pypi.org/project/abspy/):\n\n```bash\npip install abspy\n```\n\nOtherwise, you can install the latest version locally:\n\n```bash\ngit clone https://github.com/chenzhaiyu/abspy \u0026\u0026 cd abspy\npip install .\n```\n\n## Quick start\n\n### Example 1 - Reconstruction from point cloud\n\nThe example loads a point cloud to `VertexGroup` (`.vg`), partitions ambient space into a cell complex, creates the adjacency graph, and extracts the object's outer surface.\n\n```python\nfrom abspy import VertexGroup, AdjacencyGraph, CellComplex\n\n# load a point cloud in VertexGroup\nvertex_group = VertexGroup(filepath='tutorials/data/test_points.vg')\n\n# normalise point cloud\nvertex_group.normalise_to_centroid_and_scale()\n\n# initialise cell complex\ncell_complex = CellComplex(vertex_group.planes, vertex_group.aabbs, vertex_group.obbs, vertex_group.points_grouped, build_graph=True, additional_planes=None)\n\n# refine planar primitives\ncell_complex.refine_planes()\n\n# prioritise certain planes (e.g., vertical ones)\ncell_complex.prioritise_planes(prioritise_verticals=False)\n\n# construct cell complex\ncell_complex.construct()\n\n# print info about cell complex\ncell_complex.print_info()\n\n# cells inside reference mesh\ncells_in_mesh = cell_complex.cells_in_mesh('tutorials/data/test_mesh.ply')\n\n# build adjacency graph from cell complex\nadjacency_graph = AdjacencyGraph(cell_complex.graph)\n\n# calculate volumes\nvolumes = cell_complex.volumes(multiplier=10e5)\nvolumes = [0.1 if i in cells_in_mesh else vol for i, vol in enumerate(volumes)]\n\n# assign graph weights\nadjacency_graph.assign_weights_to_n_links(cell_complex.cells, attribute='area_overlap', factor=0.000, cache_interfaces=True)\nadjacency_graph.assign_weights_to_st_links(adjacency_graph.to_dict(volumes))\n\n# perform graph cut to extract surface\n_, _ = adjacency_graph.cut()\n\n# save surface model to an OBJ file\nadjacency_graph.save_surface_obj('tutorials/output/surface.obj', engine='mesh')\n```\n\n### Example 2 - Convex decomposition from mesh\n\nThe example loads a mesh to `VertexGroupReference`, partitions ambient space into a cell complex, identifies cells inside reference mesh, and visualizes the cells.\n\n```python\nfrom abspy import VertexGroupReference\nvertex_group_reference = VertexGroupReference(filepath='tutorials/data/test_mesh.ply')\n\n# initialise cell complex\ncell_complex = CellComplex(vertex_group_reference.planes, vertex_group_reference.aabbs, vertex_group_reference.obbs, build_graph=True)\n\n# construct cell complex \ncell_complex.construct()\n\n# cells inside reference mesh\ncells_in_mesh = cell_complex.cells_in_mesh('tutorials/data/test_mesh.ply', engine='distance')\n\n# save cell complex file\ncell_complex.save('tutorials/output/complex.cc')\n\n# visualise the inside cells\nif len(cells_in_mesh):\n    cell_complex.visualise(indices_cells=cells_in_mesh)\n```\n\nPlease find the usage of *abspy* at [API reference](https://abspy.readthedocs.io/en/latest/api.html), with self-explanatory examples in [`./tutorials`](https://github.com/chenzhaiyu/abspy/blob/main/tutorials). \nFor the data structure of a `.vg`/`.bvg` file, please refer to [VertexGroup](https://abspy.readthedocs.io/en/latest/vertexgroup.html).\n\n## Testing *abspy*\n\nTo run the test suite, first install [`pytest`](https://docs.pytest.org/en/stable/), and execute all tests:\n\n```bash\npytest\n```\n\n## Contributing to *abspy*\n\nPlease see the [Contribution Guide](https://github.com/chenzhaiyu/abspy/blob/main/CONTRIBUTING.md) for more information. \n\n## FAQ\n\n* **How can I install *abspy* on Windows**\n\nFor Windows users, you may need to build [SageMath from source](https://doc.sagemath.org/html/en/installation/source.html) or install all other dependencies into a [pre-built SageMath environment](https://doc.sagemath.org/html/en/installation/binary.html). Otherwise, virtualization with [docker](https://www.docker.com/) may come to the rescue.\n\n* **How can I use *abspy* for surface reconstruction?**\n\nAs shown in [`Example 1`](https://github.com/chenzhaiyu/abspy/tree/main#example-1---reconstruction-from-point-cloud), the surface is defined between adjacent cells where one is *inside* and the other *outside*. For more information, please refer to ***[Points2Poly](https://github.com/chenzhaiyu/points2poly)*** which integrates ***abspy*** with deep implicit fields, and ***[PolyGNN](https://github.com/chenzhaiyu/polygnn)*** which learns a piecewise planar occupancy function supported by ***abspy***, for 3D building reconstruction.\n\n![adaptive](https://raw.githubusercontent.com/chenzhaiyu/abspy/main/docs/source/_static/images/surface.png)\n\n\n## License\n\nSee the [MIT](https://raw.githubusercontent.com/chenzhaiyu/abspy/main/LICENSE) license for details.\n\n## Citation\n\nIf you use *abspy* in a scientific work, please consider citing the paper:\n\n```bibtex\n@article{chen2022points2poly,\n  title = {Reconstructing compact building models from point clouds using deep implicit fields},\n  journal = {ISPRS Journal of Photogrammetry and Remote Sensing},\n  volume = {194},\n  pages = {58-73},\n  year = {2022},\n  issn = {0924-2716},\n  doi = {https://doi.org/10.1016/j.isprsjprs.2022.09.017},\n  url = {https://www.sciencedirect.com/science/article/pii/S0924271622002611},\n  author = {Zhaiyu Chen and Hugo Ledoux and Seyran Khademi and Liangliang Nan}\n}\n```\n\nTo cite the _abspy_ software package itself, please use:\n```bibtex\n@article{chen2025abspy,\n  title = {abspy: A Python package for 3D adaptive binary space partitioning and modeling},\n  journal = {Journal of Open Source Software},\n  volume = {10},\n  number = {110}, \n  pages = {7946},\n  year = {2025},\n  doi = {10.21105/joss.07946},\n  url = {https://doi.org/10.21105/joss.07946},\n  publisher = {The Open Journal},\n  author = {Zhaiyu Chen},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenzhaiyu%2Fabspy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchenzhaiyu%2Fabspy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenzhaiyu%2Fabspy/lists"}