{"id":15032399,"url":"https://github.com/hkust-aerial-robotics/fast-planner","last_synced_at":"2025-05-14T02:09:18.107Z","repository":{"id":38153054,"uuid":"172918879","full_name":"HKUST-Aerial-Robotics/Fast-Planner","owner":"HKUST-Aerial-Robotics","description":"A Robust and Efficient Trajectory Planner for Quadrotors","archived":false,"fork":false,"pushed_at":"2024-10-24T13:12:43.000Z","size":151490,"stargazers_count":2693,"open_issues_count":81,"forks_count":697,"subscribers_count":55,"default_branch":"master","last_synced_at":"2025-04-10T20:06:29.618Z","etag":null,"topics":["aerial-robotics","autonomous-navigation","motion-planning","uav"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HKUST-Aerial-Robotics.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-02-27T13:16:48.000Z","updated_at":"2025-04-10T12:11:43.000Z","dependencies_parsed_at":"2024-12-11T22:12:04.144Z","dependency_job_id":null,"html_url":"https://github.com/HKUST-Aerial-Robotics/Fast-Planner","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/HKUST-Aerial-Robotics%2FFast-Planner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUST-Aerial-Robotics%2FFast-Planner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUST-Aerial-Robotics%2FFast-Planner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HKUST-Aerial-Robotics%2FFast-Planner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HKUST-Aerial-Robotics","download_url":"https://codeload.github.com/HKUST-Aerial-Robotics/Fast-Planner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254053249,"owners_count":22006717,"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":["aerial-robotics","autonomous-navigation","motion-planning","uav"],"created_at":"2024-09-24T20:18:17.679Z","updated_at":"2025-05-14T02:09:13.090Z","avatar_url":"https://github.com/HKUST-Aerial-Robotics.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fast-Planner\n\n**Fast-Planner** is developed aiming to enable quadrotor fast flight in complex unknown environments. It contains a rich set of carefully designed planning algorithms. It also provides a foundational code framework and algorithms that support several popular open-source drone projects, including [ego-planner](https://github.com/ZJU-FAST-Lab/ego-planner),\n[FUEL](https://github.com/HKUST-Aerial-Robotics/FUEL) and [RACER](https://github.com/SYSU-STAR/RACER), etc.\n\n**News**: \n\n- __Mar 13, 2021__: Code for fast autonomous exploration is available now! Check this [repo](https://github.com/HKUST-Aerial-Robotics/FUEL) for more details.\n\n- __Oct 20, 2020__: Fast-Planner is extended and applied to fast autonomous exploration. Check this [repo](https://github.com/HKUST-Aerial-Robotics/FUEL) for more details.\n\n__Authors__: [Boyu Zhou](http://sysu-star.com) and [Shaojie Shen](http://uav.ust.hk/group/) from the [HUKST Aerial Robotics Group](http://uav.ust.hk/), [Fei Gao](http://zju-fast.com/fei-gao/) from ZJU FAST Lab.\n\u003c!-- - __B-spline trajectory optimization guided by topological paths__:\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/HKUST-Aerial-Robotics/TopoTraj/blob/master/files/icra20_1.gif\" width = \"420\" height = \"237\"/\u003e\n  \u003cimg src=\"https://github.com/HKUST-Aerial-Robotics/TopoTraj/blob/master/files/icra20_2.gif\" width = \"420\" height = \"237\"/\u003e\n\u003c/p\u003e --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"files/raptor1.gif\" width = \"400\" height = \"225\"/\u003e\n  \u003cimg src=\"files/raptor2.gif\" width = \"400\" height = \"225\"/\u003e\n  \u003cimg src=\"files/icra20_2.gif\" width = \"400\" height = \"225\"/\u003e\n  \u003cimg src=\"files/ral19_2.gif\" width = \"400\" height = \"225\"/\u003e\n  \u003c!-- \u003cimg src=\"files/icra20_1.gif\" width = \"320\" height = \"180\"/\u003e --\u003e\n\u003c/p\u003e\n\nComplete videos: \n[video1](https://www.youtube.com/watch?v=NvR8Lq2pmPg\u0026feature=emb_logo),\n[video2](https://www.youtube.com/watch?v=YcEaFTjs-a0), \n[video3](https://www.youtube.com/watch?v=toGhoGYyoAY). \nDemonstrations about this work have been reported on the IEEE Spectrum: [page1](https://spectrum.ieee.org/automaton/robotics/robotics-hardware/video-friday-nasa-lemur-robot), [page2](https://spectrum.ieee.org/automaton/robotics/robotics-hardware/video-friday-india-space-humanoid-robot),\n[page3](https://spectrum.ieee.org/automaton/robotics/robotics-hardware/video-friday-soft-exoskeleton-glove-extra-thumb) (search for _HKUST_ in the pages).\n\nTo run this project in minutes, check [Quick Start](#1-Quick-Start). Check other sections for more detailed information.\n\nPlease kindly star :star: this project if it helps you. We take great efforts to develope and maintain it :grin::grin:.\n\n\n\n\n\n\n## Table of Contents\n\n* [Quick Start](#1-Quick-Start)\n* [Algorithms and Papers](#2-Algorithms-and-Papers)\n* [Setup and Config](#3-Setup-and-Config)\n* [Run Simulations](#4-run-simulations)\n* [Use in Your Application](#5-use-in-your-application)\n* [Updates](#6-updates)\n* [Known issues](#known-issues)\n\n\n## 1. Quick Start\n\nThis project has been tested on Ubuntu 18.04(ROS Melodic) and 20.04(ROS Noetic).\n\nFirstly, you should install __nlopt v2.7.1__:\n```\ngit clone -b v2.7.1 https://github.com/stevengj/nlopt.git\ncd nlopt\nmkdir build\ncd build\ncmake ..\nmake\nsudo make install\n```\n\nNext, you can run the following commands to install other required tools:\n```\nsudo apt-get install libarmadillo-dev\n```\n\nThen simply clone and compile our package (using ssh here):\n\n```\ncd ${YOUR_WORKSPACE_PATH}/src\ngit clone https://github.com/HKUST-Aerial-Robotics/Fast-Planner.git\ncd ../ \ncatkin_make\n```\n\nYou may check the detailed [instruction](#3-setup-and-config) to setup the project. \nAfter compilation you can start the visualization by: \n\n```\nsource devel/setup.bash \u0026\u0026 roslaunch plan_manage rviz.launch\n```\nand start a simulation (run in a new terminals): \n```\nsource devel/setup.bash \u0026\u0026 roslaunch plan_manage kino_replan.launch\n```\nYou will find the random map and the drone in ```Rviz```. You can select goals for the drone to reach using the ```2D Nav Goal``` tool. A sample simulation is showed [here](#demo1).\n\n\n## 2. Algorithms and Papers\n\nThe project contains a collection of robust and computationally efficient algorithms for quadrotor fast flight:\n* Kinodynamic path searching\n* B-spline-based trajectory optimization\n* Topological path searching and path-guided optimization\n* Perception-aware planning strategy (to appear)\n\nThese methods are detailed in our papers listed below. \n\nPlease cite at least one of our papers if you use this project in your research: [Bibtex](files/bib.txt).\n\n- [__Robust and Efficient Quadrotor Trajectory Generation for Fast Autonomous Flight__](https://ieeexplore.ieee.org/document/8758904), Boyu Zhou, Fei Gao, Luqi Wang, Chuhao Liu and Shaojie Shen, IEEE Robotics and Automation Letters (**RA-L**), 2019.\n- [__Robust Real-time UAV Replanning Using Guided Gradient-based Optimization and Topological Paths__](https://arxiv.org/abs/1912.12644), Boyu Zhou, Fei Gao, Jie Pan and Shaojie Shen, IEEE International Conference on Robotics and Automation (__ICRA__), 2020.\n- [__RAPTOR: Robust and Perception-aware Trajectory Replanning for Quadrotor Fast Flight__](https://arxiv.org/abs/2007.03465), Boyu Zhou, Jie Pan, Fei Gao and Shaojie Shen, IEEE Transactions on Robotics (__T-RO__). \n\n\nAll planning algorithms along with other key modules, such as mapping, are implemented in __fast_planner__:\n\n- __plan_env__: The online mapping algorithms. It takes in depth image (or point cloud) and camera pose (odometry) pairs as input, do raycasting to update a probabilistic volumetric map, and build an Euclidean signed distance filed (ESDF) for the planning system. \n- __path_searching__: Front-end path searching algorithms. \n  Currently it includes a kinodynamic path searching that respects the dynamics of quadrotors.\n  It also contains a sampling-based topological path searching algorithm to generate multiple topologically distinctive paths that capture the structure of the 3D environments. \n- __bspline__: A implementation of the B-spline-based trajectory representation.\n- __bspline_opt__: The gradient-based trajectory optimization using B-spline trajectory.\n- __active_perception__: Perception-aware planning strategy, which enable to quadrotor to actively observe and avoid unknown obstacles, to appear in the future.\n- __plan_manage__: High-level modules that schedule and call the mapping and planning algorithms. Interfaces for launching the whole system, as well as the configuration files are contained here.\n\nBesides the folder __fast_planner__, a lightweight __uav_simulator__ is used for testing.\n\n\n## 3. Setup and Config\n\n### Prerequisites\n\n1. Our software is developed and tested in Ubuntu 18.04(ROS Melodic) and 20.04(ROS Noetic). \n   \n2. We use [**NLopt**](https://nlopt.readthedocs.io/en/latest/NLopt_Installation) to solve the non-linear optimization problem. The __uav_simulator__ depends on the C++ linear algebra library __Armadillo__. The two dependencies can be installed by the following command.\n\nFirstly, you should install __nlopt v2.7.1__:\n```\ngit clone -b v2.7.1 https://github.com/stevengj/nlopt.git\ncd nlopt\nmkdir build\ncd build\ncmake ..\nmake\nsudo make install\n```\n\nNext, you can run the following commands to install other required tools:\n```\nsudo apt-get install libarmadillo-dev\n```\n\n### Build on ROS\n\nAfter the prerequisites are satisfied, you can clone this repository to your catkin workspace and catkin_make. A new workspace is recommended:\n\n```\n  cd ${YOUR_WORKSPACE_PATH}/src\n  git clone https://github.com/HKUST-Aerial-Robotics/Fast-Planner.git\n  cd ../\n  catkin_make\n```\n\nIf you encounter problems in this step, please first refer to existing __issues__, __pull requests__ and __Google__ before raising a new issue.\n\nNow you are ready to [run a simulation](#4-run-simulations).\n\n### Use GPU Depth Rendering (can be skipped optionally)\n\nThis step is not mandatory for running the simulations. However, if you want to run the more realistic depth camera in __uav_simulator__, installation of [CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit) is needed. Otherwise, a less realistic depth sensor model will be used.\n\n The **local_sensing** package in __uav_simulator__ has the option of using GPU or CPU to render the depth sensor measurement. By default, it is set to CPU version in CMakeLists:\n \n ```\n set(ENABLE_CUDA false)\n # set(ENABLE_CUDA true)\n ```\nHowever, we STRONGLY recommend the GPU version, because it generates depth images more like a real depth camera.\nTo enable the GPU depth rendering, set ENABLE_CUDA to true, and also remember to change the 'arch' and 'code' flags according to your graphics card devices. You can check the right code [here](https://github.com/tpruvot/ccminer/wiki/Compatibility).\n\n```\n    set(CUDA_NVCC_FLAGS \n      -gencode arch=compute_61,code=sm_61;\n    ) \n``` \nFor installation of CUDA, please go to [CUDA ToolKit](https://developer.nvidia.com/cuda-toolkit)\n\n## 4. Run Simulations\n\nRun [Rviz](http://wiki.ros.org/rviz) with our configuration firstly:\n\n```\n  \u003c!-- go to your workspace and run: --\u003e\n  source devel/setup.bash\n  roslaunch plan_manage rviz.launch\n```\n\nThen run the quadrotor simulator and __Fast-Planner__. \nSeveral examples are provided below:\n\n### Kinodynamic Path Searching \u0026 B-spline Optimization\n\nIn this method, a kinodynamic path searching finds a safe, dynamically feasible, and minimum-time initial trajectory in the discretized control space. \nThen the smoothness and clearance of the trajectory are improved by a B-spline optimization.\nTo test this method, run:\n\n```\n  \u003c!-- open a new terminal, go to your workspace and run: --\u003e\n  source devel/setup.bash\n  roslaunch plan_manage kino_replan.launch\n```\n\nNormally, you will find the randomly generated map and the drone model in ```Rviz```. At this time, you can trigger the planner using the ```2D Nav Goal``` tool. When a point is clicked in ```Rviz```, a new trajectory will be generated immediately and executed by the drone. A sample is displayed below:\n\n\u003c!-- add some gif here --\u003e\n \u003cp id=\"demo1\" align=\"center\"\u003e\n  \u003cimg src=\"files/ral19_3.gif\" width = \"480\" height = \"270\"/\u003e\n \u003c/p\u003e\n\nRelated algorithms are detailed in [this paper](https://ieeexplore.ieee.org/document/8758904).\n\n\n\n### Topological Path Searching \u0026 Path-guided Optimization\n\nThis method features searching for multiple trajectories in distinctive topological classes. Thanks to the strategy, the solution space is explored more thoroughly, avoiding local minima and yielding better solutions.\nSimilarly, run:\n\n```\n  \u003c!-- open a new terminal, go to your workspace and run: --\u003e\n  source devel/setup.bash\n  roslaunch plan_manage topo_replan.launch\n```\n\nthen you will find the random map generated and can use the ```2D Nav Goal``` to trigger the planner:\n\n\u003c!-- add some gif here --\u003e\n \u003cp align=\"center\"\u003e\n  \u003cimg src=\"files/icra20_3.gif\" width = \"480\" height = \"270\"/\u003e\n \u003c/p\u003e\n\nRelated algorithms are detailed in [this paper](https://arxiv.org/abs/1912.12644).\n\n\n### Perception-aware Replanning\n\nThe code will be released after the publication of [associated paper](https://arxiv.org/abs/2007.03465).\n\n\n## 5. Use in Your Application\n\nIf you have successfully run the simulation and want to use __Fast-Planner__ in your project,\nplease explore the files kino_replan.launch or topo_replan.launch.\nImportant parameters that may be changed in your usage are contained and documented.\n\nNote that in our configuration, the size of depth image is 640x480. \nFor higher map fusion efficiency we do downsampling (in kino_algorithm.xml, skip_pixel = 2).\nIf you use depth images with lower resolution (like 256x144), you might disable the downsampling by setting skip_pixel = 1. Also, the _depth_scaling_factor_ is set to 1000, which may need to be changed according to your device.\n\nFinally, for setup problem, like compilation error caused by different versions of ROS/Eigen, please first refer to existing __issues__, __pull request__, and __Google__ before raising a new issue. Insignificant issue will receive no reply.\n\n\n## 6. Updates\n\n- __Oct 20, 2020__: Fast-Planner is extended and applied to fast autonomous exploration. Check this [repo](https://github.com/HKUST-Aerial-Robotics/FUEL) for more details.\n  \n- __July 5, 2020__: We will release the implementation of paper: _RAPTOR: Robust and Perception-aware Trajectory Replanning for Quadrotor Fast Flight_ (submitted to TRO, under review) in the future.\n\n- __April 12, 2020__: The implementation of the ICRA2020 paper: _Robust Real-time UAV Replanning Using Guided Gradient-based Optimization and Topological Paths_ is available.\n\n- __Jan 30, 2020__: The volumetric mapping is integrated with our planner. It takes in depth image and camera pose pairs as input, do raycasting to fuse the measurements, and build a Euclidean signed distance field (ESDF) for the planning module.\n\n\n## Acknowledgements\n  We use **NLopt** for non-linear optimization.\n\n## Licence\nThe source code is released under [GPLv3](http://www.gnu.org/licenses/) license.\n\n\n## Disclaimer\nThis is research code, it is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of merchantability or fitness for a particular purpose.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkust-aerial-robotics%2Ffast-planner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhkust-aerial-robotics%2Ffast-planner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhkust-aerial-robotics%2Ffast-planner/lists"}