{"id":27306233,"url":"https://github.com/papalotis/ft-fsd-path-planning","last_synced_at":"2025-04-12T03:59:02.862Z","repository":{"id":165671835,"uuid":"524509576","full_name":"papalotis/ft-fsd-path-planning","owner":"papalotis","description":"Formula Student Driverless Path Planning Algorithm. Colorblind centerline calculation algorithm developed by FaSTTUBe. It introduces a novel approach that uses neither Delaunay Triangulation nor RRT.","archived":false,"fork":false,"pushed_at":"2025-04-11T21:00:32.000Z","size":9097,"stargazers_count":66,"open_issues_count":5,"forks_count":22,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T03:58:57.409Z","etag":null,"topics":["algorithm","autonomous-driving","driverless","formula-student","formula-student-driverless","formulastudent","formulastudentdriverless","numba","numpy","path-planning","python","robotics","scipy"],"latest_commit_sha":null,"homepage":"","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/papalotis.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}},"created_at":"2022-08-13T21:15:13.000Z","updated_at":"2025-04-11T21:00:35.000Z","dependencies_parsed_at":"2024-01-01T17:48:29.632Z","dependency_job_id":null,"html_url":"https://github.com/papalotis/ft-fsd-path-planning","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papalotis%2Fft-fsd-path-planning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papalotis%2Fft-fsd-path-planning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papalotis%2Fft-fsd-path-planning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papalotis%2Fft-fsd-path-planning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/papalotis","download_url":"https://codeload.github.com/papalotis/ft-fsd-path-planning/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248514202,"owners_count":21116900,"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":["algorithm","autonomous-driving","driverless","formula-student","formula-student-driverless","formulastudent","formulastudentdriverless","numba","numpy","path-planning","python","robotics","scipy"],"created_at":"2025-04-12T03:59:02.362Z","updated_at":"2025-04-12T03:59:02.855Z","avatar_url":"https://github.com/papalotis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ft-fsd-path-planning\n\nFaSTTUBe Formula Student Driverless Path Planning Algorithm\n\n\u003c!-- ![An animation demoing the path planning algorithm](animation.gif) --\u003e\n\n| With color information | Without color information |\n| ---------------------- | ------------------------- |\n| Autocross FSG 2019\n|  ![An animation demoing the path planning algorithm](media/fsg_color.gif#gh-light-mode-only)   ![An animation demoing the path planning algorithm](media/fsg_color_dark_mode.gif#gh-dark-mode-only) | ![An animation demoing the path planning algorithm without color](media/fsg_no_color.gif#gh-light-mode-only) ![An animation demoing the path planning algorithm without color](media/fsg_no_color_dark_mode.gif#gh-dark-mode-only)                   |\n| Skidpad |\n| ![An animation demoing the path planning algorithm](media/skidpad_color.gif#gh-light-mode-only) ![An animation demoing the path planning algorithm](media/skidpad_color_dark_mode.gif#gh-dark-mode-only) | ![An animation demoing the path planning algorithm without color](media/skidpad_no_color.gif#gh-light-mode-only) ![An animation demoing the path planning algorithm without color](media/skidpad_no_color_dark_mode.gif#gh-dark-mode-only) |\n\n\u003e [!NOTE]\n\u003e You can find an interactive demo of the algorithm \u003ca href=\"https://ft-fsd-path-planning.streamlit.app//\" target=\"_blank\"\u003ehere.\u003c/a\u003e\n\n## Updates \n\n### December 2023, July 2024 (v0.4)\n\n#### (v0.4.3)\n\n- Added `Acceleration` relocalization and stable acceleration path calculation.\n- Added caching mechanism for the sorting step (about 20% performance improvement). \n\n\u003e [!IMPORTANT]\n\u003e The caching step slightly changes the logic of the algorithm and has not been thoroughly tested. By default, the caching is disabled. To enable it, set the `experimental_performance_improvements` parameter of the `PathPlanner` class to `True`.\n\n#### (v0.4.1)\n\nAdded a property to the PathPlanner class that gives information about the relocalization process. The property is called `relocalization_info` and is a dataclass called `RelocalizationInformation`. It contains the following fields:\n\n- `translation` - A 2d array with the translation of the relocalization\n- `rotation` - A float with the rotation of the relocalization\n\nIf the relocalization process has not been run, or is not relevant (currently only Skidpad has relocalization), the property will return `None`.\n\nThe internal Skidpad frame has its origin at the center of the Skidpad, with the x-axis pointing towards the exit of the Skidpad and the y-axis pointing to the left-hand loop.\n\n#### (v0.4.0)\n\nFurther improvements were added in December 2023. The main focus was to make the Skidpad mission more robust. The algorithm now uses a different approach for the Skidpad mission, which is much simpler and does not rely on the color of the cones at all.\n\nThe logic that runs during the Skidpad mission is stateful, so if you want to use it, you will have to review the usage of the relevant classes including `PathPlanner`. More specifically, while in the past one could create a new instance of the `PathPlanner` class, for each computation, with minimal performance penalties, now this will cause the Skidpad path calculation to fail. It is recommended to create a new instance of the `PathPlanner` class when the vehicle enters `AS-READY` state and the SLAM pose has stabilized.\n\nThis version also adds `scikit-learn` as a dependency, which is used for the Skidpad mission. You may use the `summer-23` tag if you want to use the version of the algorithm that does not require `scikit-learn` and does not have the Skidpad improvements.\n\n### March 2023 (v0.3)\n\n In March 2023, a further development of this algorithm was published. The new version has two main improvements:\n\n- The algorithm can now work without color. It can use cones for which the color is known and cones for which the color is unknown at the same time.\n- Performance improvements. The algorithm is faster, with the main focus of improvement being the cone sorting step.\n\n## Introduction\n\nThis repository contains the path planning algorithm developed by FaSTTUBe for the 2021/22 and 2022/23 Formula Student seasons.\n\nThe intention of this repository is to provide teams entering the driverless category with a path planning algorithm, so that they can get up and running as fast as possible. Teams are encouraged to use this repository as a basis and adapt it to their own pipeline, as well as make changes that will improve the algorithm's performance. If your team decides to use this repository, feel free to inform us. We would be happy to hear about your experience.\n\nThe algorithm differs from other common path planning approaches in that it can very robustly handle one side of the track not being visible, for example the inside of a corner. This is a common problem in the driverless category, especially for teams with less sophisticated detection pipelines.\n\nParts that are specific to the FaSTTUBe pipeline have been removed. The algorithm is now a standalone library that can be used in any pipeline. It is a Python package that can be installed using pip.\n\nThe algorithm requires the following inputs:\n\n- The car's current position and orientation in the slam map\n- The position of the (optionally colored) cones in the slam map\n\nThe algorithm outputs:\n\n- Samples of a parameterized b-spline with the x,y and curvature of the samples\n\nThe algorithm is completely stateless. Every time it is called no previous results are\nused. The only aspect that can be used again is the path that was previously generated.\nIt is only used if the path calculation has failed.\n\nThe parts of the pipeline are also available as individual classes, so if you only\nwant to use parts of it you can do so.\n\nThe codebase is written entirely in Python and makes heavy use of NumPy, SciPy, and Numba.\n\nThe algorithm has demonstrated its success as part of the FaSTTUBe pipeline, contributing to a 2nd place finish in Trackdrive at FS Czech 2023.\n\n## Installation\n\nThe package can be installed using pip:\n\n```bash\npip install \"fsd-path-planning[demo] @ git+https://git@github.com/papalotis/ft-fsd-path-planning.git\"\n```\n\nThis will also install the dependencies needed to run the demo (cli, matplotlib, streamlit, etc.). If you don't want to install the demo dependencies, you can install the package without the `demo` extra:\n\n```bash\npip install \"fsd-path-planning @ git+https://git@github.com/papalotis/ft-fsd-path-planning.git\"\n```\n\nYou can also clone the repository and install the package locally:\n\n```bash\ngit clone https://github.com/papalotis/ft-fsd-path-planning.git\ncd ft-fsd-path-planning\npip install -e .[demo]\n```\n\nYou can again skip the `[demo]` extra if you don't want to install the demo dependencies.\n\n## Performance\n\nThe algorithm (with default parameters) is fast enough to run in real-time on a Jetson Xavier AGX 16GB on MAXN power mode. On that platform, the algorithm takes on average around 10ms from start to finish. You can run the demo to get an idea of the performance on your hardware.\n\n*Note that the first time that you run the algorithm, it will take around 30-60 seconds to compile all the Numba functions. Run the demo a second time to get a real indicator on performance.*\n\nRun the following command to run the demo on your machine:\n\n```bash\npython -m fsd_path_planning.demo\n```\n\n## Basic usage\n\n```python\nfrom fsd_path_planning import PathPlanner, MissionTypes, ConeTypes\n\npath_planner = PathPlanner(MissionTypes.trackdrive)\n# you have to load/get the data, this is just an example\nglobal_cones, car_position, car_direction = load_data() \n# global_cones is a sequence that contains 5 numpy arrays with shape (N, 2),\n# where N is the number of cones of that type\n\n# ConeTypes is an enum that contains the following values:\n# ConeTypes.UNKNOWN which maps to index 0\n# ConeTypes.RIGHT/ConeTypes.YELLOW which maps to index 1\n# ConeTypes.LEFT/ConeTypes.BLUE which maps to index 2\n# ConeTypes.START_FINISH_AREA/ConeTypes.ORANGE_SMALL which maps to index 3\n# ConeTypes.START_FINISH_LINE/ConeTypes.ORANGE_BIG which maps to index 4\n\n# car_position is a 2D numpy array with shape (2,)\n# car_direction is a 2D numpy array with shape (2,) representing the car's direction vector\n# car_direction can also be a float representing the car's direction in radians\n\npath = path_planner.calculate_path_in_global_frame(global_cones, car_position, car_direction)\n\n# path is a Mx4 numpy array, where M is the number of points in the path\n# the columns represent the spline parameter (distance along path), x, y and path curvature\n\n```\n\nTake a look at this notebook for a more detailed example: [simple_application.ipynb](fsd_path_planning/demo/simple_application.ipynb)\n\n\u003e [!TIP]\n\u003e There is no resetting functionality in the classes. If you want to reset the path planner, you can simply create a new instance of the class.\nIt is recommended to create a new instance of the relevant classes when the vehicle enters `AS-READY` state.\n\n## Previous versions\n\nAlternate versions of the algorithm are available as git tags:\n\n- `color-dependent` - The algorithm needs color information to work. This version was used in the 2021/22 season.\n- `summer-23` - The algorithm can work without color information. This version was used in the 2022/23 season.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapalotis%2Fft-fsd-path-planning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpapalotis%2Fft-fsd-path-planning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapalotis%2Fft-fsd-path-planning/lists"}