{"id":13799787,"url":"https://github.com/jkk-research/wayp_plan_tools","last_synced_at":"2025-05-13T08:32:05.790Z","repository":{"id":154182488,"uuid":"617367403","full_name":"jkk-research/wayp_plan_tools","owner":"jkk-research","description":"🏎 Waypoint and planner tools for ROS 2 with minimal dependencies.","archived":false,"fork":false,"pushed_at":"2025-03-31T15:52:55.000Z","size":281,"stargazers_count":157,"open_issues_count":9,"forks_count":17,"subscribers_count":2,"default_branch":"ros2","last_synced_at":"2025-03-31T17:02:23.332Z","etag":null,"topics":["control","pure-pursuit","pursuit","ros","ros2","ros2-humble","sze","szenergy","trajectory","waypoint","waypoint-following","waypoints-creator"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jkk-research.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":"2023-03-22T08:42:45.000Z","updated_at":"2025-03-29T10:55:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"e6a5d791-f66c-4d37-84db-31a394866775","html_url":"https://github.com/jkk-research/wayp_plan_tools","commit_stats":{"total_commits":37,"total_committers":3,"mean_commits":"12.333333333333334","dds":0.3783783783783784,"last_synced_commit":"491504ce2528b10c221fb2b4214eee5bbcc03029"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkk-research%2Fwayp_plan_tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkk-research%2Fwayp_plan_tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkk-research%2Fwayp_plan_tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jkk-research%2Fwayp_plan_tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jkk-research","download_url":"https://codeload.github.com/jkk-research/wayp_plan_tools/tar.gz/refs/heads/ros2","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253903866,"owners_count":21981762,"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":["control","pure-pursuit","pursuit","ros","ros2","ros2-humble","sze","szenergy","trajectory","waypoint","waypoint-following","waypoints-creator"],"created_at":"2024-08-04T00:01:06.124Z","updated_at":"2025-05-13T08:32:05.454Z","avatar_url":"https://github.com/jkk-research.png","language":"C++","funding_links":[],"categories":["Packages"],"sub_categories":["Application layer"],"readme":"# `wayp_plan_tools` `ROS 2` package\nWaypoint and planner tools for `ROS 2` with minimal dependencies. [![Static Badge](https://img.shields.io/badge/ROS_2-Humble-34aec5)](https://docs.ros.org/en/humble/)\n\nPlanner / control nodes:\n- `single_goal_pursuit`: Pure pursuit (for vehicles / robots), a simple cross-track error method\n- `multiple_goal_pursuit`: Multiple goal pursuit for vehicles / robots an implementation of our [paper](https://hjic.mk.uni-pannon.hu/index.php/hjic/article/view/914)\n- `stanley_control`: Stanley controller, a heading error + cross-track error method\n- `follow_the_carrot`: Follow-the-carrot, the simplest controller\n\nWaypoint nodes:\n- `waypoint_saver`: saves the waypoints to a csv\n- `waypoint_loader`: loads the waypoints from a csv to a ROS 2 topic\n- `waypoint_to_target`: translates the global waypoint array to local target waypoint(s), thus it makes possible to use the controller nodes in a standalone way\n\n\n## Build\n\nIt is assumed that the workspace is `~/ros2_ws/`.\n\n### `Terminal 1` 🔴 clone\n\n```\ncd ~/ros2_ws/src\n```\n```\ngit clone https://github.com/jkk-research/wayp_plan_tools\n```\n\n### `Terminal 1` 🔴 build\n```\ncd ~/ros2_ws\n```\n```\ncolcon build --packages-select wayp_plan_tools --symlink-install\n```\n\n### `Terminal 2` 🔵 run\n```\nsource ~/ros2_ws/install/setup.bash\n```\n```\nros2 launch wayp_plan_tools waypoint_saver.launch.py\n```\n\n# Control nodes\nIn this project the `single_goal_pursuit`, the `multiple_goal_pursuit`, `stanley_control` and the `follow_the_carrot` controllers are implemented. A high level overview about the algorithms is visible on the following figure:\n\n![](csv/control_overview01.svg)\n\n# `single_goal_pursuit` node\nThe \"classic\" pure pursuit implementation\n![](csv/control_pure_pursuit01.svg)\n\n# `multiple_goal_pursuit` node \nMultiple goal pursuit for vehicles / robots, an implementation of our [paper](https://hjic.mk.uni-pannon.hu/index.php/hjic/article/view/914)\n\n# `follow_the_carrot` node\nFollow-the-carrot, the simplest controller\n![](csv/control_follow_the_carrot01.svg)\n\n# `waypoint_to_target` node\nReads the waypoint array and speeds, from that it creates single or multiple goal points.\n\nIt also provides a `/metrics_wayp` array topic with the following  elements:\n\n| Array element | Meaning | Const\n| :--- | :--- | :---\n|`[0]` | current lateral distance to the waypoint (signed, cross-track error) | `CUR_LAT_DIST_SIGNED`\n|`[1]` | current lateral distance to the waypoint (absolute value) | `CUR_LAT_DIST_ABS`\n|`[2]` | average lateral distance over time | `AVG_LAT_DISTANCE`\n|`[3]` | maximum lateral distance over time | `MAX_LAT_DISTANCE`\n|`[4]` | current waypoint ID | `CUR_WAYPOINT_ID`\n|`[5]` | target waypoint ID | `TRG_WAYPOINT_ID`\n|`[6]` | target waypoint longitudinal distance (similar to lookahed distance, but at a waypoint) | `TRG_WAY_LON_DIST`\n|`[7]` | actual lookahead distance | `ACT_LOOK_DIST`\n|`[8]` | current cross-track error | `CUR_CROSS_TRACK`\n\n\n\u003cimg src=\"csv/lookahead01.svg\" width=60% /\u003e\n\n# `waypoint_saver` node \nSaves the waypoints to a csv. Important parameters are `file_name` and `file_dir`. Set from terminal or from a [launch file](launch/waypoint_saver.launch.py)\n\n``` py\nros2 run wayp_plan_tools waypoint_saver --ros-args -p file_name:=tmp1.csv -p file_dir:=/mnt/bag/waypoints\n```\n\n# `waypoint_loader` node\nLoads the waypoints from a csv to a ROS 2 topic. Set from terminal or from a [launch file](launch/waypoint_loader.launch.py)\n\n``` py\nros2 run wayp_plan_tools waypoint_loader --ros-args -p file_name:=tmp1.csv -p file_dir:=/mnt/bag/waypoints\n```\n\n\n# Usage with a simulator\n\nPlease refer to [github.com/jkk-research/sim_wayp_plan_tools](https://github.com/jkk-research/sim_wayp_plan_tools).\n\n![](https://raw.githubusercontent.com/jkk-research/sim_wayp_plan_tools/main/img/gz_rviz01.gif)\n\n# Cite \u0026 paper\n\nIf you use any of this code please consider citing the [paper](https://hjic.mk.uni-pannon.hu/index.php/hjic/article/view/914):\n\n```bibtex\n@Article{horvath2020multigoalpursuit, \n    title={Theoretical background and application of multiple goal pursuit trajectory follower}, \n    volume={48}, \n    url={https://hjic.mk.uni-pannon.hu/index.php/hjic/article/view/914}, \n    DOI={10.33927/hjic-2020-03}, \n    number={1}, \n    journal={Hungarian Journal of Industry and Chemistry}, \n    author={Horváth, Ernő and Pozna, Claudiu and Kőrös, Péter and Hajdu, Csaba and Ballagi, Áron}, \n    year={2020}, \n    month={Jul.}, \n    pages={11–17} \n}\n```\n\n![](csv/rviz2waypoint01.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkk-research%2Fwayp_plan_tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjkk-research%2Fwayp_plan_tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjkk-research%2Fwayp_plan_tools/lists"}