{"id":20399990,"url":"https://github.com/kitware/pylidar-slam","last_synced_at":"2025-04-07T17:11:04.058Z","repository":{"id":137030709,"uuid":"384479688","full_name":"Kitware/pyLiDAR-SLAM","owner":"Kitware","description":null,"archived":false,"fork":false,"pushed_at":"2021-10-12T09:14:33.000Z","size":51074,"stargazers_count":320,"open_issues_count":1,"forks_count":40,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-31T14:14:19.377Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/Kitware.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}},"created_at":"2021-07-09T15:32:24.000Z","updated_at":"2025-03-27T01:56:46.000Z","dependencies_parsed_at":"2023-04-10T01:50:23.484Z","dependency_job_id":null,"html_url":"https://github.com/Kitware/pyLiDAR-SLAM","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitware%2FpyLiDAR-SLAM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitware%2FpyLiDAR-SLAM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitware%2FpyLiDAR-SLAM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitware%2FpyLiDAR-SLAM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kitware","download_url":"https://codeload.github.com/Kitware/pyLiDAR-SLAM/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694876,"owners_count":20980733,"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":[],"created_at":"2024-11-15T04:35:52.132Z","updated_at":"2025-04-07T17:11:04.038Z","avatar_url":"https://github.com/Kitware.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pyLiDAR-SLAM\n\nThis codebase proposes modular light python and pytorch implementations of several LiDAR Odometry methods, \nwhich can easily be evaluated and compared on a set of public Datasets.\n\nIt heavily relies on [omegaconf](https://omegaconf.readthedocs.io/en/2.0_branch/) and [hydra](https://hydra.cc/), \nwhich allows us to easily test the different modules and parameters with few but structured configuration files.\n\n\nThis is a research project provided \"as-is\" without garanties, \nuse at your own risk. It is actively used for **[Kitware Vision team](https://www.kitware.fr/equipe-vision-par-odinateur/)** internal research thus is likely to be heavily extended, \nrewritten (and hopefully improved) in a near future.\n\n\n\n## Overview\n\n![KITTI Sequence 00 with pyLiDAR-SLAM](docs/data/example_pointclouds.png)\n\n*pyLIDAR-SLAM* is designed to be modular, multiple components are implemented at each stage of the pipeline.\nIts modularity can make it a bit complicated to use. We provide this [wiki](https://github.com/Kitware/pyLiDAR-SLAM/wiki) to help you navigate it.\nIf you have any questions, do not hesitate raising issues.\n\nThe documentation is organised as follows:\n\n- [`INSTALLATION:`](https://github.com/Kitware/pyLiDAR-SLAM/wiki/INSTALLATION) Describes how to install pyLiDAR-SLAM and its different components\n- [`DATASETS:`](https://github.com/Kitware/pyLiDAR-SLAM/wiki/DATASETS) Describes the different datasets integrated in pyLiDAR-SLAM, and how to install them\n- [`TOOLBOX:`](https://github.com/Kitware/pyLiDAR-SLAM/wiki/SLAM-LiDAR-Toolbox) Describes the contents of the toolbox and the different modules proposed\n- [`BENCHMARK:`](https://github.com/Kitware/pyLiDAR-SLAM/wiki/Benchmark) Describes the benchmarks supported in the Dataset **/!\\ Note:** This section is still in construction\n\nThe goal for the future is to gradually add functionalities to pyLIDAR-SLAM (Loop Closure, Motion Segmentation, Multi-Sensors, etc...).\n\n## News\n\n\u003e **[08/10/2021]:** We also introduce support for individual rosbags (Introducing naturally an overhead compared to using ROS directly, but provides the flexibility of pyLiDAR-SLAM)\n\u003e\n\u003e **[08/10/2021]:** We release code for Loop Closure with **pyLiDAR-SLAM** accompanied with a simple **PoseGraph** Optimization.\n\u003e\n\u003e **[08/10/2021]:** We release our [new work](https://arxiv.org/abs/2109.12979) on arXiv. It proposes a new state-of-the-art pure LiDAR odometry implemented in C++ (check the [project](https://github.com/jedeschaud/ct_icp) main page). python wrappings are available, and it can be used with **pyLiDAR-SLAM**.\n\n## Installation \n\nSee the wiki page [INSTALLATION](https://github.com/Kitware/pyLiDAR-SLAM/wiki/INSTALLATION) for instruction to install the code base and the modules you are interested in. \n\n### DATASETS\n\n*pyLIDAR-SLAM* incorporates different datasets, see [DATASETS](https://github.com/Kitware/pyLiDAR-SLAM/wiki/DATASETS)  for installation and setup instructions for each of these datasets.\nOnly the datasets implemented in *pyLIDAR-SLAM* are compatible with hydra's mode and the scripts `run.py` and `train.py`. \n\nBut you can define your own datasets by extending the class [`DatasetLoader`](slam/dataset/dataset.py).\n\n**New:** We support individual rosbags (without requiring a complete ROS installation). See the minimal example for more details.\n\n\n## A Minimal Example\n\n\u003e Download a rosbag (e.g. From  Rosbag Cartographer):\n[example_rosbag](https://storage.googleapis.com/cartographer-public-data/bags/backpack_3d/with_intensities/b3-2016-04-05-15-51-36.bag)\n\u003e\n\u003e **Note:** You need the `rosbag` python module installed to run this example (see [INSTALLATION](https://github.com/Kitware/pyLiDAR-SLAM/wiki/INSTALLATION) for instructions)\n\n\u003e Launch the SLAM:\n\n```\npython3 run.py num_workers=1 /          # The number of process workers to load the dataset (should be at most 1 for a rosbag)\n    slam/initialization=NI /            # The initialization considered (NI=No Initialization / CV=Constant Velocity, etc...)\n    slam/preprocessing=grid_sample /    # Preprocessing on the point clouds\n    slam/odometry=icp_odometry /        # The Odometry algorithm\n    slam.odometry.viz_debug=True /      # Whether to launch the visualization of the odometry\n    slam/loop_closure=none /            # The loop closure algorithm selected (none by default)\n    slam/backend=none /                 # The backend algorithm (none by default)\n    dataset=rosbag /                    # The dataset selected (a simple rosbag here)\n    dataset.main_topic=horizontal_laser_3d /    # The pointcloud topic of the rosbag \n    dataset.accumulate_scans=True /             # Whether to accumulate multiple messages (a sensor can return multiple scans lines or an accumulation of scans) \n    dataset.file_path=\u003cpath_to_rosbag_dir\u003e/b3-2016-04-05-15-51-36.bag / #  The path to the rosbag file \n    hydra.run.dir=.outputs/TEST_DOC   #  The log directory where the trajectory will be saved\n```\n\n\u003e This will output the trajectory, log files (including the full config) on disk at location `.outputs/TEST_DOC`.\n\u003e \n\u003e Our minimal LiDAR Odometry, is actually a naïve baseline implementation, which is mostly designed and tested on driving datasets (see the KITTI benchmark). \n\u003e Thus in many cases it will fail, be imprecise or too slow. \n\u003e \n\u003e We recommend you install the module `pyct_icp` from [our recent work](https://github.com/jedeschaud/ct_icp), which provides a much more versatile and precise LiDAR-Odometry.\n\u003e\n\u003e See [the wiki page INSTALLATION](https://github.com/Kitware/pyLiDAR-SLAM/wiki/INSTALLATION) for more details on how to install the different modules. \n\u003e If you want to visualize in real time the quality of the SLAM, consider also installing the module `pyviz3d`.\n\n\u003e Once `pyct_icp` is installed, you can modify the command line above: \n```\npython3 run.py num_workers=1 /          \n    slam/initialization=NI /            \n    slam/preprocessing=none /    \n    slam/odometry=ct_icp_robust_shaky / # The CT-ICP algorithm for shaky robot sensor (here it is for a backpack) \n    slam.odometry.viz_debug=True /      \n    slam/loop_closure=none /            \n    slam/backend=none /                 \n    dataset=rosbag /                    \n    dataset.main_topic=horizontal_laser_3d /    \n    dataset.accumulate_scans=True /             \n    dataset.file_path=\u003cpath_to_rosbag_dir\u003e/b3-2016-04-05-15-51-36.bag / \n    hydra.run.dir=.outputs/TEST_DOC   \n```\n\n\u003e It will launch pyct_icp on the same rosbag (running much faster than our python based odometry)\n\u003e\n\u003e With `pyviz3d` you should see the following reconstruction (obtained by a backpack mounting the stairs of a museum): \n\n![Minimal Example](docs/data/minimal_example.png)\n\n\n## More advanced examples / Motivation\n\n\u003e **pyLiDAR-SLAM** will progressively include more and more modules, to build more powerful and more accessible LiDAR odometries.\n\u003e\n\u003e For a more detailed / advanced usage of the toolbox please refer to our documentation in the wiki [HOME](https://github.com/Kitware/pyLiDAR-SLAM/wiki/HOME).\n\n\u003e The motivation behind the toolbox, is really to compare different modules, **hydra** is very useful for this purpose.\n\u003e\n\u003e For example the script below launches consecutively the `pyct_icp` and `icp_odometry` odometries on the same datasets. \n\n```\npython3 run.py -m /             # We specify the -m option to tell hydra to perform a sweep (or grid search on the given arguments)\n    num_workers=1 /          \n    slam/initialization=NI /            \n    slam/preprocessing=none /    \n    slam/odometry=ct_icp_robust_shaky, icp_odometry /   # The two parameters of the grid search: two different odometries\n    slam.odometry.viz_debug=True /      \n    slam/loop_closure=none /            \n    slam/backend=none /                 \n    dataset=rosbag /                    \n    dataset.main_topic=horizontal_laser_3d /    \n    dataset.accumulate_scans=True /             \n    dataset.file_path=\u003cpath_to_rosbag_dir\u003e/b3-2016-04-05-15-51-36.bag / \n    hydra.run.dir=.outputs/TEST_DOC   \n```\n\n#### Benchmarks\n\nWe use this functionality of *pyLIDAR-SLAM* to compare the performances of its different modules on different datasets.\nIn [Benchmark](https://github.com/Kitware/pyLiDAR-SLAM/wiki/Benchmark) we present the results of *pyLIDAR-SLAM* on the most popular open-source datasets. \n\nNote this work in still in construction, and we aim to improve it and make it more extensive in the future.\n\n\n#### Research results\n\n\u003e Small improvements will be regularly made to `pyLiDAR-SLAM`, However *major changes / new modules* will more likely be introduced along research articles (which we aim to integrate with this project in the future)\n\u003e\n\u003e Please check [RESEARCH](https://github.com/Kitware/pyLiDAR-SLAM/wiki/RESEARCH) to see the research papers associated to this work. \n\n\n\n\n\n### System Tested\n\n| OS            | CUDA   | pytorch  | python | hydra |\n| --- | --- | --- | --- | --- |\n| Ubuntu 18.04  | 10.2   | 1.7.1    | 3.8.8 | 1.0 |\n\n### Author\nThis is a work realised in the context of Pierre Dellenbach PhD thesis under supervision of [Bastien Jacquet](https://www.linkedin.com/in/bastienjacquet/?originalSubdomain=fr) ([Kitware](https://www.kitware.com/computer-vision/)), \nJean-Emmanuel Deschaud \u0026 François Goulette (Mines ParisTech).\n\n### Cite\n\nIf you use this work for your research, consider citing:\n\n```\n@misc{dellenbach2021s,\n      title={What's in My LiDAR Odometry Toolbox?},\n      author={Pierre Dellenbach, \n      Jean-Emmanuel Deschaud, \n      Bastien Jacquet,\n      François Goulette},\n      year={2021},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitware%2Fpylidar-slam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkitware%2Fpylidar-slam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkitware%2Fpylidar-slam/lists"}