{"id":18792497,"url":"https://github.com/prbonn/range-mcl","last_synced_at":"2025-04-07T12:11:09.992Z","repository":{"id":49587633,"uuid":"346635402","full_name":"PRBonn/range-mcl","owner":"PRBonn","description":"Range Image-based LiDAR Localization for Autonomous Vehicles Using Mesh Maps (chen2021icra)","archived":false,"fork":false,"pushed_at":"2023-06-27T08:10:30.000Z","size":3424,"stargazers_count":292,"open_issues_count":5,"forks_count":70,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-31T11:04:15.146Z","etag":null,"topics":["3d-lidar","lidar","localization","mcl","mesh","range-image"],"latest_commit_sha":null,"homepage":"","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/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}},"created_at":"2021-03-11T08:46:25.000Z","updated_at":"2025-03-13T08:15:05.000Z","dependencies_parsed_at":"2022-09-06T05:41:33.137Z","dependency_job_id":"f6436af8-db48-4bcb-98f5-a957ff48a52c","html_url":"https://github.com/PRBonn/range-mcl","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%2Frange-mcl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Frange-mcl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Frange-mcl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PRBonn%2Frange-mcl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PRBonn","download_url":"https://codeload.github.com/PRBonn/range-mcl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247648977,"owners_count":20972945,"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","localization","mcl","mesh","range-image"],"created_at":"2024-11-07T21:20:09.641Z","updated_at":"2025-04-07T12:11:09.971Z","avatar_url":"https://github.com/PRBonn.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Range Image-based 3D LiDAR Localization\n\nThis repo contains the code for our ICRA2021 paper: Range Image-based LiDAR Localization for Autonomous Vehicles.\n\nDeveloped by [Xieyuanli Chen](https://www.ipb.uni-bonn.de/xieyuanli-chen/), [Ignacio Vizzo](https://www.ipb.uni-bonn.de/ignacio-vizzo/), [Thomas Läbe](https://www.ipb.uni-bonn.de/thomas-laebe/) and [Jens Behley](https://www.ipb.uni-bonn.de/jens-behley/).\n \nIt uses a novel sensor model with MCL to achieve 3D LiDAR global localization and pose tracking. The sensor model compares the range image of the current LiDAR scan to the synthetic range images rendered from the triangular mesh to update the weight of particles. This method is simple but can be used with different types of LiDAR scanners in different datasets and environments without fine-tuning.\n\n\u003cimg src=\"data/figs/loc_results.gif\" width=\"800\"\u003e\n\nOnline localization demo.\n\n\n\u003cp float=\"left\"\u003e\n  \u003cimg src=\"data/figs/mesh-traj.png\" width=\"340\" /\u003e\n  \u003cimg src=\"data/figs/submap.png\" width=\"480\" /\u003e \n\u003c/p\u003e\n\nVisualizations: Left: the triangular mesh map and the localization results; Right: Sub-tile maps \n\n### Table of Contents\n0. [Introduction](#Range-Image-based-3D-LiDAR-Localization)\n1. [Publication](#Publication)\n2. [Dependencies](#Dependencies)\n3. [How to use](#How-to-use)\n4. [Related work](#Related-work)\n5. [License](#License)\n\n## Publication\nIf you use our implementation in your academic work, please cite the corresponding [paper](https://www.ipb.uni-bonn.de/pdfs/chen2021icra.pdf):\n    \n\t@inproceedings{chen2021icra,\n\t\tauthor = {X. Chen and I. Vizzo and T. L{\\\"a}be and J. Behley and C. Stachniss},\n\t\ttitle = {{Range Image-based LiDAR Localization for Autonomous Vehicles}},\n\t\tbooktitle = {Proc. of the IEEE Intl. Conf. on Robotics \\\u0026 Automation (ICRA)},\n\t\tyear = 2021\n\t}\n\n## Dependencies\n\nThe code was tested with Ubuntu **20.04** with its standard python version **3.8**.\n\nWe are using OpenGL to do achieve fast rendering, so you will need an OpenGL capable graphics\ncard (we use Nvidia cards, e.g. 2080Ti) to be fast.\n\n- System dependencies related to OpenGL:\n\n  ```bash\n  sudo apt-get update \n  sudo apt-get install libgl1-mesa-glx\n  ```\n\n- Other system dependencies:\n\n  ```bash\n  sudo apt-get update \n  sudo apt-get install libusb-1.0   # open3d 0.12.0 dependency\n  sudo apt-get install -y python3-pip\n  sudo -H pip3 install --upgrade pip\n  ```\n\n- Python dependencies (may also work with different versions than mentioned in the requirements file)\n\n  ```bash\n  sudo -H pip3 install -r requirements.txt\n  ```\n\n## How to use\n\n### Quick use\nFor a quick demo, one could download the [mesh map](https://www.ipb.uni-bonn.de/html/projects/range-mcl/mesh_kitti_07.ply) \nand LiDAR [data](https://www.ipb.uni-bonn.de/html/projects/range-mcl/kitti-07.zip), \nextract the them in the `/data` folder following the recommended [data structure](data/README.md), and then run:\n  ```bash\n  cd src/\n  python3 main_range_mcl.py\n  ```\nOne could then get the online visualization of range-based MCL as shown in the gif.\n\n### More detailed usage\nHere, we provide more detailed information about our range-image-based LiDAR localization method,\nincluding building mesh maps, evaluating the localization results and more pre-built maps of different datasets.\n\n#### Build mesh map \nTo build a mesh map, we use the Poisson surface reconstruction provided by the Open3D library.\nOne need to download the LiDAR [data](https://www.ipb.uni-bonn.de/html/projects/range-mcl/kitti-07.zip), \nextract the them in the `/data` folder following the recommended [data structure](data/README.md), and then run:\n  ```bash\n  python3 build_mesh_map.py\n  ```\n\nFor fast calculating and generating range and normal data for LiDAR scans, one could find more details [here](src/map_building/c_utils/README.md).\n\n**Important tips**\n- We used our moving object segmentation method ([code](https://github.com/PRBonn/LiDAR-MOS)) to clean the scans before building the map. \nOne could also use other methods to clean the map.\n- To build the mesh map, one needs to first get the map reference poses provided by the dataset or obtained use SLAM.\n- For the sake of demonstration, we use the same data from KITTI 07 for both mapping and localization. However, in a real application (e.g. all the experiments in the [paper](https://www.ipb.uni-bonn.de/pdfs/chen2021icra.pdf)), the data for mapping and localization are collected in different seasons of the same area.\n- For the sake of demonstration, we use the ground truth odometry poses provided by the KITTI dataset and add noise to them. In a real application, one doesn't need to add noise to the odometry information (see [motion_model.py](https://github.com/PRBonn/range-mcl/blob/main/src/motion_model.py)).\n\n#### Evaluation\nOnce finished the localization process, one would get the localization results at `/results`.\nTo evaluate the localization results, one could check the `evaluation.py`.\nFor a quick demo, one just need to run\n  ```bash\n  python3 evaluation.py\n  ```\n#### Collection of mesh maps\nNotice that, the mesh maps were generated using the data from [KITTI dataset](https://www.cvlibs.net/datasets/kitti/eval_odometry.php), [MulRan dataset](https://sites.google.com/view/mulran-pr/dataset) and [Apollo dataset](https://apollo.auto/southbay.html).\nPlease register on their official website to apply for the original data.\n\n- [KITTI sequence 07](https://www.ipb.uni-bonn.de/html/projects/range-mcl/mesh_kitti_07.ply) (original data from [KITTI dataset](https://www.cvlibs.net/datasets/kitti/eval_odometry.php))\n- [MulRan KAIST 02](https://www.ipb.uni-bonn.de/html/projects/range-mcl/mesh_mulran_kaist.ply) (original data from [MulRan dataset](https://sites.google.com/view/mulran-pr/dataset))\n- [Apollo SouthBay](https://www.ipb.uni-bonn.de/html/projects/range-mcl/mesh_apollo_southbay.ply) (original data from [Apollo dataset](https://apollo.auto/southbay.html))\n\n\n## Related work\n### [Puma](https://github.com/PRBonn/puma): Poisson Surface Reconstruction for LiDAR Odometry and Mapping\nWe also released the implementation of the algorithms described in our paper Poisson Surface Reconstruction for LiDAR Odometry and Mapping.\nThis is a LiDAR Odometry and Mapping pipeline that uses the Poisson Surface Reconstruction algorithm to build the map as a triangular mesh online.\n\n### [Overlap-localization](https://github.com/PRBonn/overlap_localization): Overlap-based 3D LiDAR Monte Carlo Localization\nWe previously also proposed a learning-based global localization method, called overlap localization.\nIt uses the [OverlapNet](https://github.com/PRBonn/OverlapNet) to train an observation model for Monte Carlo Localization and achieves global localization with 3D LiDAR scans.\n\n## License\n\nCopyright 2021, Xieyuanli Chen, Ignacio Vizzo, Thomas Läbe, 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%2Frange-mcl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprbonn%2Frange-mcl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprbonn%2Frange-mcl/lists"}