{"id":18792443,"url":"https://github.com/prbonn/semantic_suma","last_synced_at":"2025-05-16T14:08:50.733Z","repository":{"id":40005461,"uuid":"199056069","full_name":"PRBonn/semantic_suma","owner":"PRBonn","description":"SuMa++: Efficient LiDAR-based Semantic SLAM (Chen et al IROS 2019)","archived":false,"fork":false,"pushed_at":"2024-03-12T16:31:46.000Z","size":37650,"stargazers_count":948,"open_issues_count":4,"forks_count":205,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-04-12T11:55:39.699Z","etag":null,"topics":["3d-lidar","lidar","rangenet-lib","semantic","slam","suma","suma-plus-plus"],"latest_commit_sha":null,"homepage":"","language":"C++","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/PRBonn.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-26T17:30:02.000Z","updated_at":"2025-04-09T03:45:40.000Z","dependencies_parsed_at":"2024-07-31T04:47:53.264Z","dependency_job_id":null,"html_url":"https://github.com/PRBonn/semantic_suma","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Fsemantic_suma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Fsemantic_suma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Fsemantic_suma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Fsemantic_suma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PRBonn","download_url":"https://codeload.github.com/PRBonn/semantic_suma/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254544146,"owners_count":22088807,"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-lidar","lidar","rangenet-lib","semantic","slam","suma","suma-plus-plus"],"created_at":"2024-11-07T21:19:52.516Z","updated_at":"2025-05-16T14:08:45.725Z","avatar_url":"https://github.com/PRBonn.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SuMa++: Efficient LiDAR-based Semantic SLAM\n\nThis repository contains the implementation of SuMa++, which generates semantic maps only using three-dimensional laser range scans.\n\nDeveloped by [Xieyuanli Chen](https://www.ipb.uni-bonn.de/people/xieyuanli-chen/) and [Jens Behley](https://www.ipb.uni-bonn.de/people/jens-behley/).\n\nSuMa++ is built upon SuMa and RangeNet++. For more details, we refer to the original project websites [SuMa](https://github.com/jbehley/SuMa) and [RangeNet++](https://github.com/PRBonn/lidar-bonnetal).\n\n_An example of using SuMa++:_\n![ptcl](./.readme/demo.gif)\n\n\n### Table of Contents\n0. [Introduction](#SuMa++:-Efficient-LiDAR-based-Semantic-SLAM)\n1. [Publication](#Publication)\n2. [Docker](#Docker)\n3. [Dependencies](#Dependencies)\n4. [Build](#Build)\n5. [How to run](#How-to-run)\n6. [More Related Work](#More-Related-Work)\n7. [Frequently Asked Questions](#Frequently-Asked-Questions)\n8. [License](#License)\n\n## Publication\n\nIf you use our implementation in your academic work, please cite the corresponding [paper](https://www.ipb.uni-bonn.de/wp-content/papercite-data/pdf/chen2019iros.pdf):  \n    \n\t@inproceedings{chen2019iros, \n\t\t\tauthor = {X. Chen and A. Milioto and E. Palazzolo and P. Giguère and J. Behley and C. Stachniss},\n\t\t\ttitle  = {{SuMa++: Efficient LiDAR-based Semantic SLAM}},\n\t\t\tbooktitle = {Proceedings of the IEEE/RSJ Int. Conf. on Intelligent Robots and Systems (IROS)},\n  \t\t\tpages = {4530--4537},\n\t\t\tyear = {2019},\n\t\t\turl = {https://www.ipb.uni-bonn.de/wp-content/papercite-data/pdf/chen2019iros.pdf}\n\t}\n \n## Docker\n\nThanks to the efforts of [Hyunggi Chang](https://github.com/changh95), we have now a dockerized version of `semantic_suma`, which takes care of the proper setup.\n\nYou can build the Docker image with the provided Dockerfile, i.e.,\n```bash\ndocker build -t semantic_suma:latest\n```\n\nand run the container by \n```bash\ndocker run -it -e \"DISPLAY=$DISPLAY\" -e \"QT_X11_NO_MITSHM=1\" -e \"XAUTHORITY=$XAUTH\" -v \"/tmp/.X11-unix:/tmp/.X11-unix:rw\" -v /kitti:/data --runtime=nvidia --net=host --ipc=host --privileged semantic_suma:latest\n```\n\nNote that it makes a volume located at `kitti` that should point to the KITTI files or another directory containing scans in the KITTI format. Follow the [How to run](#How-to-run) instructions below to execute the binary.\n\nThe GUI is visualized via X11, so prior to starting a docker container, `xhost +local:docker` command should be used to provide access to the xhost from docker.\n\n## Dependencies\n\n* catkin\n* Qt5 \u003e= 5.2.1\n* OpenGL \u003e= 4.0\n* libEigen \u003e= 3.2\n* gtsam \u003e= 4.0  (tested with [4.0.0-alpha2](https://github.com/borglab/gtsam/tree/4.0.0-alpha2))\n\nIn Ubuntu 16.04: Installing all dependencies should be accomplished by\n```bash\nsudo apt-get install build-essential cmake libgtest-dev libeigen3-dev libboost-all-dev qtbase5-dev libglew-dev libqt5libqgtk2 catkin\n```\n\nAdditionally, make sure you have [catkin-tools](https://catkin-tools.readthedocs.io/en/latest/) and the [fetch](https://github.com/Photogrammetry-Robotics-Bonn/catkin_tools_fetch) verb installed:\n```bash\nsudo apt install python-pip\nsudo pip install catkin_tools catkin_tools_fetch empy\n```\n\n## Build\n#### rangenet_lib\nTo use SuMa++, you need to first build the rangenet_lib with the TensorRT and C++ interface. \nFor more details about building and using rangenet_lib you could find in [rangenet_lib](https://github.com/PRBonn/rangenet_lib).\n\n#### SuMa++\nClone the repository in the `src` directory of the same catkin workspace where you built the rangenet_lib:\n```bash\ngit clone https://github.com/PRBonn/semantic_suma.git\n```\nDownload the additional dependencies (or clone [glow](https://github.com/jbehley/glow.git) into your catkin workspace `src` yourself):\n```bash\ncatkin deps fetch\n```\n\nFor the first setup of your workspace containing this project, you need:\n  ```bash\ncatkin build --save-config -i --cmake-args -DCMAKE_BUILD_TYPE=Release -DOPENGL_VERSION=430 -DENABLE_NVIDIA_EXT=YES\n  ```\n  \n  Where you have to set `OPENGL_VERSION` to the supported OpenGL core profile version of your system, which you can query as follows:\n\n```bash\n$ glxinfo | grep \"version\"\nserver glx version string: 1.4\nclient glx version string: 1.4\nGLX version: 1.4\nOpenGL core profile version string: 4.3.0 NVIDIA 367.44\nOpenGL core profile shading language version string: 4.30 NVIDIA [...]\nOpenGL version string: 4.5.0 NVIDIA 367.44\nOpenGL shading language version string: 4.50 NVIDIA\n```\n\n Here the line `OpenGL core profile version string: 4.3.0 NVIDIA 367.44` is important and therefore you should use `-DOPENGL_VERSION = 430`. If you are unsure you can also leave it on the default version `330`, which should be supported by all OpenGL-capable devices.\n\n If you have a NVIDIA device, like a Geforce or Quadro graphics card, you should also activate the NVIDIA extensions using `-DENABLE_NVIDIA_EXT=YES` for info about the current GPU memory usage of the program.\n\n After this setup steps, you can build with `catkin build`, since the configuration has been saved to your current Catkin profile (therefore, `--save-config` was needed).\n \n Now the project root directory (e.g. `~/catkin_ws/src/semantic_suma`) should contain a `bin` directory containing the visualizer.\n\n## How to run\n**Important Notice**\n- Before running SuMa++, you need to first build the [rangenet_lib](https://github.com/PRBonn/rangenet_lib) and download the pretrained [model](https://www.ipb.uni-bonn.de/html/projects/semantic_suma/darknet53.tar.gz).\n- You need to specify the model path in the configuration file in the `config/` folder.\n- For the first time using, rangenet_lib will take several minutes to build a `.trt` model for SuMa++.\n- SuMa++ now can only work with KITTI dataset, since the semantic segmentation may not generalize well in other environments.\n- To use SuMa++ with your own dataset, you may finetune or retrain the semantic segmentation network.\n\nAll binaries are copied to the `bin` directory of the source folder of the project. Thus,\n1. run `visualizer` in the `bin` directory by `./visualizer`,\n2. open a Velodyne directory from the KITTI Visual Odometry Benchmark and select a \".bin\" file,\n3. start the processing of the scans via the \"play button\" in the GUI.\n\n## More Related Work\n\n### [OverlapNet - Loop Closing for 3D LiDAR-based SLAM](https://github.com/PRBonn/OverlapNet)\nThis repo contains the code for our RSS2020 paper: OverlapNet - Loop Closing for 3D LiDAR-based SLAM.\n\nOverlapNet is a modified Siamese Network that predicts the overlap and relative yaw angle of a pair of range images generated by 3D LiDAR scans, which can be used for place recognition and loop closing.\n\n### [Overlap-based LiDAR Global Localization](https://github.com/PRBonn/overlap_localization)\nThis repo contains the code for our IROS2020 paper: Learning an Overlap-based Observation Model for 3D LiDAR Localization.\n\nIt uses the OverlapNet to train an observation model for Monte Carlo Localization and achieves global localization with 3D LiDAR scans.\n\n\n## Frequently Asked Questions\n- [visualizer segmentation fault](https://github.com/PRBonn/semantic_suma/issues/5)\n- [Different semantic results of suma++](https://github.com/PRBonn/semantic_suma/issues/6)\n- [How do I save the global map?](https://github.com/PRBonn/semantic_suma/issues/54)\n\n## License\n\n\nCopyright 2019, Xieyuanli Chen, Jens Behley, Cyrill Stachniss, Photogrammetry and Robotics Lab, University of Bonn.\n\nThis project is free software made available under the MIT License. For details see the LICENSE file.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprbonn%2Fsemantic_suma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprbonn%2Fsemantic_suma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprbonn%2Fsemantic_suma/lists"}