Package: abspy
Introductionabspyis a Python tool for 3Dadaptive binary space partitioningand beyond: an ambient 3D space is adaptively partitioned to form a linear cell complex with planar primitives, where an adjacency graph is dynamically obtained. The tool is designed primarily to support compact surface reconstruction and other applications as well.Key featuresManipulation of planar primitives from point cloud or reference meshLinear cell complex creation with adaptive binary space partitioning (a-BSP)Dynamic BSP-tree (NetworkXgraph) updated locally upon primitive insertionSupport of polygonal surface reconstruction with graph cutCompatible data structure withEasy3Don point cloud, primitive, mesh and cell complexRobust spatial operations underpinned by the rational ring fromSageMath's exact kernelInstallationAll-in-one installationCreate a conda environment with the latestabspyrelease and all its dependencies installed:gitclonehttps://github.com/chenzhaiyu/abspy&&cdabspy
condaenvcreate-fenvironment.yml&&condaactivateabspyManual installationStill easy! Create a conda environment and enter it:condacreate--nameabspypython=3.10&&condaactivateabspyInstall the dependencies:condainstall-cconda-forgenetworkxnumpytqdmscikit-learnmatplotlibcolorlogscipytrimeshrtreepygletsage=10.0Alternatively, you can usemambafor faster package parsing installation:condainstallmamba-cconda-forge
mambainstall-cconda-forgenetworkxnumpytqdmscikit-learnmatplotlibcolorlogscipytrimeshrtreepygletsage=10.0Preferably, the latestabspyrelease can be found and installed viaPyPI:pipinstallabspyOtherwise, you can install the latest version locally:gitclonehttps://github.com/chenzhaiyu/abspy&&cdabspy
pipinstall.Quick startExample 1 - Reconstruction from point cloudThe example loads a point cloud toVertexGroup(.vg), partitions ambient space into a cell complex, creats the adjacency graph, and extracts the object's outer surface.fromabspyimportVertexGroup,AdjacencyGraph,CellComplex# load a point cloud in VertexGroupvertex_group=VertexGroup(filepath='points.vg')# normalise point cloudvertex_group.normalise_to_centroid_and_scale()# additional planes to append (e.g., bounding planes)additional_planes=[[0,0,1,-1],[1,2,3,-4]]# initialise cell complexcell_complex=CellComplex(vertex_group.planes,vertex_group.bounds,vertex_group.obbs,vertex_group.points_grouped,build_graph=True,additional_planes=additional_planes)# refine planar primitivescell_complex.refine_planes()# prioritise certain planes (e.g., vertical ones)cell_complex.prioritise_planes(prioritise_verticals=True)# construct cell complexcell_complex.construct()# print info about cell complexcell_complex.print_info()# build adjacency graph from cell complexadjacency_graph=AdjacencyGraph(cell_complex.graph)# assign weights (e.g., occupancy by neural network prediction) to graphadjacency_graph.assign_weights_to_n_links(cell_complex.cells,attribute='area_overlap',factor=0.001,cache_interfaces=True)adjacency_graph.assign_weights_to_st_links(...)# perform graph cut to extract surface_,_=adjacency_graph.cut()# save surface model to an OBJ fileadjacency_graph.save_surface_obj('surface.obj',engine='rendering')Example 2 - Convex decomposition from meshThe example loads a mesh toVertexGroupReference, partitions ambient space into a cell complex, identify cells inside reference mesh, and visualize the cells.fromabspyimportVertexGroupReferencevertex_group_reference=VertexGroupReference(filepath='mesh.obj')# initialise cell complexcell_complex=CellComplex(vertex_group_reference.planes,vertex_group_reference.bounds,vertex_group_reference.obbs,build_graph=True)# construct cell complexcell_complex.construct()# cells inside reference meshcells_in_mesh=cell_complex.cells_in_mesh('mesh.obj',engine='distance')# save cell complex filecell_complex.save('complex.cc')# visualise the inside cellsiflen(cells_in_mesh):cell_complex.visualise(indices_cells=cells_in_mesh)Please find the usage ofabspyatAPI reference. For the data structure of a.vg/.bvgfile, please refer toVertexGroup.FAQHow can I installabspyon Windows?For Windows users, you may need to buildSageMath from sourceor install all other dependencies into apre-built SageMath environment. Otherwise, virtualization withdockermay come to the rescue.How can I useabspyfor surface reconstruction?As demonstrated inExample 1, the surface can be addressed by graph cut — in between adjacent cells where one beinginsideand the other beingoutside— exactly where the cut is performed. For more information, please refer toPoints2Polywhich wrapsabspyfor building surface reconstruction.LicenseMITCitationIf you useabspyin a scientific work, please consider citing the paper:@article{chen2022points2poly,title={Reconstructing compact building models from point clouds using deep implicit fields},journal={ISPRS Journal of Photogrammetry and Remote Sensing},volume={194},pages={58-73},year={2022},issn={0924-2716},doi={https://doi.org/10.1016/j.isprsjprs.2022.09.017},url={https://www.sciencedirect.com/science/article/pii/S0924271622002611},author={Zhaiyu Chen and Hugo Ledoux and Seyran Khademi and Liangliang Nan}}