ROS2 Version: Jazzy Jalisco
Tested On: Ubuntu 24.04 LTS Noble Numbat
This project was originally developed as part of the master’s thesis Model-Informed Global Path Planning and Control for Autonomous Vessels at the Faculty of Electrical Engineering and Computing, University of Zagreb. Earlier prototype versions of the project are available in the branches drop-down menu.
Each component of the Path Planning Module architecture follows a distinct approach and can be developed as an independent module. The current implementation represents only a part of a larger planned framework, as presented in Future Work. The referenced ROS2 packages can be upgraded or replaced in the future without affecting the module’s functionality or other system components, provided that the described communication topology is followed.
This flexibility in the implementation allows developers to experiment with implementing their custom packages. Contributions are welcome, feel free to explore and join the project!
- Installing
- Requirements
- Build Workspace
- Source Workspace
- Project Information
- ROS2 Software Architecture for Vessel Path Planning Module
- Map-Making Package : map_maker
- Path Management Package : path_planning_client
- Path-Planning package : path_planning_server
- 🔗 Example
- Future Work
- Credits
- Acknowledgments
- Map Creation
- Cost Map Visualization
- Map Publishing
- Cost Map Visualization in RViz2
- Setting Start and Goal Points
- Publishing Start and Goal Points
- Running Path Planning
- Example
git clone https://github.com/kr1zzo-FER/Path-Planning-Module-for-Autonomous-Vessels.git
On Ubuntu 24.04, there is a known issue with installing pip due to system changes.
Credits for the solution: AskUbuntu - Issues with pip in Ubuntu 24.04 LTS.
Make sure venv is installed by running:
sudo apt install python3-venv
To create a new virtual environment in a directory named .venv, run:
python3 -m venv .venv
To activate this virtual environment (which modifies the PATH environment variable), run this:
source .venv/bin/activate
Now you can install a requirements in this virtual environment:
pip install -r requirements/requirements.txt
Navigate to path_planning_ws and build the workspace using the following .sh file:
./colcon.sh
or just:
colcon build
At the end of the .bashrc, add the following line to source the ROS 2 workspace automatically.
source /home/*path_to_workspace*/Model-Informed-Path-Planning/path_planning_ws/install/setup.bashAlternatively, you can run it in the terminal every time before running the package in path_planning_ws:
source install/setup.bash
You don’t need to start every package manually — there’s a smarter way!
With the ROS2 App Launcher, you can easily run all your ROS2 packages fast and easy.
This repository started as part of the diploma thesis at the Faculty of Electrical Engineering and Computing, University of Zagreb, Laboratory for Underwater Systems and Technologies in the academic year 2023./2024. Our long-term goal is to develop the Path-Olanning Module capable of generating safe and efficient routes, either within an integrated autonomy framework or as a standalone module. This module is designed to support higher levels of autonomy by seamlessly interacting with both mission-planning and path-following systems. By leveraging the widely adopted ROS2 framework and aligning with state-of-the-art autonomy architectures, we ensure adaptability across diverse system structures.
The documentation directory contains the final thesis and conference paper submissions, offering an in-depth description of the project. The paper is writen in English so it can be used as a reference for the project, while the thesis is written in Croatian and it is yet to be translated.
Project involves the development of a modular software system architecture for vessel path planning module using Robot Operating System 2 (ROS2), version : Jazzy. The system is designed to be flexible and scalable, integrating OpenStreetMap data, RViz2 visualization tools, and advanced path planning algorithms. The architecture consists of three main stages, as outlined below.
Figure : Block diagram of the ROS2 system architecture for global vessel path planning
-
Workspace:
path_planning_ws- Organized into standard ROS2 directories:
src: Contains core packages (map_maker,path_planning_client,path_planning_server,user_action_interfaces).build,install, andlog: Support package compilation, installation, and logging.
- Organized into standard ROS2 directories:
-
Packages
-
The system architecture is divided into three logical stages, with each stage implemented as a ROS2 package:
-
1️⃣ Map-Making Package map_maker
- Purpose: Extract geographic features from OpenStreetMap and create a cost map and publish data in ROS2 framework
- Implementation:
- Makes map from OpenStreetMap data
- Utilizes the Pseudo-Mercator projection (EPSG:3857).
- Publishes cost maps via a ROS2 publisher.
- Output: Cost maps for path planning.
-
2️⃣ Path Management Package
path_planning_client- Purpose: Define start and goal coordinates using RViz2 or geographic data and data visualization in RViz2.
- Implementation:
- Employs the ROS2 action client-server mechanism for communication.
- Converts and visualizes data for coordinate setup.
- Output: Start and goal coordinates published within the ROS2 framework.
-
3️⃣ Path-Planning Package
path_planning_server- Purpose: Generate a feasible and smooth path using the D* Lite algorithm.
- Implementation:
- Interpolates waypoints for enhanced path smoothness.
- Exchanging data via the action client-server communication pattern.
- Output: Interpolated paths for vessel navigation.
-
4️⃣ Custom Interfaces Package
user_action_interfaces- Purpose: Define custom messages and actions for efficient communication between ROS2 packages.
- Implementation:
- Provides standardized message types for inter-package data exchange.
- Includes action definitions for start-goal updates, path planning requests, and feedback.
- Ensures compatibility across all system components through well-defined interfaces.
- Output: Custom message and action types for seamless communication within the ROS2 framework.
-
Communication Topology
-
The system’s communication topology is based on ROS2 principles, where packages exchange information using custom messages and actions from
user_action_interfacespackage that carry geographic coordinates (latitude and longitude) in a global coordinate format. -
Each ROS2 package receives data in a predefined format, processes it according to its specific function, and outputs results using the same structure.
-
- Shares data such as Cost maps, Visualization data and Coordinate updates.
-
- Manages path planning by:
- Submitting start/goal coordinates via requests.
- Providing raw and interpolated path information via feedback.
- Manages path planning by:
-
-
Black-Box Concept
- Geographic data is converted between global and local systems during processing.
- Ensures compatibility and modularity by exchanging data in global geographic coordinates, allowing seamless integration and upgrades.
- This modular design supports real-world applications, enabling interoperability with external systems for visualization, navigation, and control.
The map_maker ROS2 package is designed for creating and integrating geographical maps into the ROS2 framework. This package processes data to generate maps and publishes them using a ROS2 publisher. The workflow and associated programs are outlined below.
Figure : map_maker Package Architecture
-
- The package generates geographical maps by processing images and HTML data from OpenStreetMap stored in the
input_datadirectory. - The main script,
map_process.py, coordinates this process by:- Initializing parameters from the
make_map_launch.pyfile. - Iterating over
locationsdirectories ininput_datato process map data.
- Initializing parameters from the
- The package generates geographical maps by processing images and HTML data from OpenStreetMap stored in the
-
- The processed maps are saved in the
map_datadirectory and published as ROS2 messages. - The
map_publisher.pynode converts processed map data intoCoastMsg.msgformat and broadcasts it via thegps_coordinates_coasttopic.
- The processed maps are saved in the
- Map Creation involves extracting geographical data from OpenStreetMap provided in
input_datadirectory and converting it into a cost map for path planning using programs frommap_makerdirectory - Processed maps are saved in the
map_datadirectory as binary files and published as ROS2 messages - The process is outlined below and its consits of following steps:
Figure : Map Creation Process
1️⃣ Create Geographic Area Folders
- Navigate to the
input_datafolder in the ROS2 packagemap_maker. - Create subfolders named after the geographic areas of interest (e.g.,
jadranovo).
2️⃣ Download Map Data
- Visit the OpenStreetMap website.
- Select the desired region and set the zoom level to 300 meters.
- Download:
- A
.pngimage of the map (e.g.,jadranovo.png) and save it in the respective folder. - The HTML share information:
- Copy the "Share" HTML code.
- Create a file named
osm_info.txtin the same folder and paste the HTML code inside.
- A
Figure : Download image from OpenStreetMap
Figure 2: Copy HTML string from OpenStreetMap
3️⃣ Repeat the Process
- Repeat the process until you are satisified with selected region consisting of few 300 meters zoom level images
- For best results, use a zoom level of 300 meters, as it preserves topographic details while maintaining manageable file sizes.
- Ensure all folders in
input_datacontain both the.pngimage and theosm_info.txtfile.
The following commands are used to create binary map files consisting of cost maps for path planning with geographical coordinates:
ros2 launch map_maker make_map_launch.pyIf data is fetched from OpenStreetMap, the following command should be used:
ros2 launch map_maker make_map_launch.py parameter1_name:="parameter1_value" parameter2_name:="parameter2_value" ...Available parameter*_name and their default values are:
save_file_name:="jadranovo"
locations:='["sv_marko","voz","jadranovo", "kacjak", "rudine"]' -> example of fetched data from OSM for default map
grid_size:="10"
show_plot:="True"Where locations are the names of the folders in the input_data directory containing the map data.
If everything is did correctly, under directory map_maker/map_data processed map should be visible as binary file named processed_map_*save_file_name*
You can test out the created map with the following command that runs map_visualization.py script:
ros2 launch map_maker visualization_map_launch.py If you want to visualize a specific map, you can do so by running the following command with the desired map file name:
ros2 launch map_maker visualization_map_launch.py save_file:="save_file_name"Previous command visualize the maps from the map_data directory.
Figure : Example of visualized map processed_map_jadranovo
Geographic maps are stored as binary files (processed_map_save_file_name), defined in the launch file, and located in the map_data directory. These maps are published via the map_publisher.py node, which processes the data into CoastMsg.msg format for the ROS2 topic gps_coordinates_coast.
To publish the generated map using the ROS2 publisher gps_coordinates_coast, execute the following command in the Linux terminal :
ros2 launch map_maker publish_map_launch.pyIf you want to publish a specific map, you can do so by running the following command with the desired map file name:
ros2 launch map_maker publish_map_launch.py save_file:='save_file_name'The given map is visualized in RViz2, described in the next section. The different maps can be visualized by changing the save_file parameter and re-run the command without the need to re-run the RViz2 visualization command.
The path_planning_client ROS2 package is responsible for visualizing data in the RViz2 tool, managing the process of setting the start and goal points for vessel path planning, and publishing these points within the ROS2 framework using the action client and server communication mechanism. This package integrates tools for setting coordinates, visualizing planned paths, and managing the path planning and visualization process.
Figure : path_planning_client Package Architecture
-
- The
poincloud_publisher.pynode visualizes cost maps, search areas, and safe zones in RViz2. - Data is converted into ROS2 message formats (
sensor_msgs.PointCloud2,geometry_msgs.PoseStamped) for seamless visualization.
- The
-
- Start and goal points are defined through the
start_goal_publisher.pynode, which interacts with RViz2 for visualization and accepts manual updates via the terminal. - These points are published on the
start_goal_msgtopic and converted into global coordinates for path planning.
- Start and goal points are defined through the
-
Publishing Start and Goal Points to the ROS2 Framework
- The
start_goal_publisher.pynode publishes start and goal points on thestart_goal_msgtopic, enabling seamless communication between the client and server packages.
- The
Note: Dependencies include the map_maker package for geographic coordinate data published via the gps_coordinates_coast topic.
The RViz2 visualization tool is launched using the rviz2_pointcloud_launch.py launch file, which loads the prepared map_visualization.rviz configuration from the rviz2 directory and initializes the poincloud_publisher.py node; it is executed with the command: ros2 launch path_planning_client rviz2_pointcloud_launch.py.
To visualize cost maps, search areas, and safe zones in RViz2, first launch ROS2 Commands Map Publishing and then execute the following command in the Linux terminal:
ros2 launch path_planning_client rviz2_pointcloud_launch.py
Figure : RViz2 Visualization of Cost Map
There are two ways to set the start and goal points for path planning: manually via the terminal or using RViz2. The start_goal_publisher.py node is responsible for setting these points and publishing them on the start_goal_msg topic.
In Rviz2 you can use 2D Pose Estimate and 2D Nav Goal tools to set start and goal points by clicking on the map:
Figure : Setting Start and Goal Points in RViz2
To set start and goal points manually via the terminal, execute the following command in the Linux terminal:
Setting start point:
ros2 launch path_planning_client update_start_goal_launch.py
start:="[x_s,y_s]"Setting goal point:
ros2 launch path_planning_client update_start_goal_launch.py
goal:="[x_g,y_g]"Setting both start and goal points:
ros2 launch path_planning_client update_start_goal_launch.py
start:"[x_s,y_s]" goal:="[x_g,y_g]"Note: Replace [x_s,y_s] and [x_g,y_g] with the desired start and goal geographical coordinates, respectively.
When you are satisfied with the selected start and goal points, publish them to the ROS2 framework using the following command:
ros2 launch path_planning_client start_goal_client_launch.pyThe action client-server communication mechanism ensures that the start and goal points are successfully published and available for path planning and the client (provided in thiis package) awaits for the path planning server to generate the path described in the next section.
The path_planning_server ROS2 package handles global vessel path planning based on cost maps and performs path interpolation to ensure the generated paths are both optimal and feasible for execution. This package uses the D* lite algorithm for path planning and incorporates dynamic interpolation techniques for smooth path generation.
Figure : path_planning_server Package Architecture
-
- The
path_planning_server.pynode uses the D* lite algorithm to compute the optimal path based on start and goal points received from thestart_goal_client.pynode. - Parameters such as
coast_values_argandstep_sizes_argcontrol the cost map resolution and algorithm efficiency.
- The
-
- Interpolation techniques refine the raw path into a smooth and executable trajectory using programs in the
curve_generationfolder. - Parameters like
sampling_rateandoptimization_methoddetermine point distribution and curve smoothing.
- Interpolation techniques refine the raw path into a smooth and executable trajectory using programs in the
-
Feedback to the path_planning_client
- The
path_planning_server.pynode provides feedback to the client with the planned path interpolated and non-interpolated path coordinates, as well as the intermediate results for debugging purposes.
- The
📝 Note: Compared to all other packages, the path_planning_client package achieves all its objectives using a single logical loop and requires only one command to execute its entire workflow, making it highly efficient and streamlined.
To execute the launch file, run the following command in your terminal:
ros2 launch path_planning_server path_planning_server_launch.pyIf you want to change the default parameters, you can do so by running the following command with the desired parameters, for example:
ros2 launch path_planning_server path_planning_server_launch.py \
cost_values:='[10.0, 2.0, 1.5, 1.2]' \
step_sizes:='[50.0, 50.0, 100.0, 100.0]' \
speed_limits:='[2.0, 5.0, 8.0, 25.0]' \
optimization_method:='dubins' \
sampling_rate:='5.0' \
show_feedback:='True' \
show_results:='True' \
show_debug:='True' \
show_downsampling:='False' \
show_interpolation:='True'cost_values- Defines the cost values for the cost map of red, green, yellow, and free passage zones, respectively.
step_sizes- Determines the step sizes for the D* lite algorithm for red, green, yellow, and free passage zones, respectively.
speed_limits- Specifies the speed limits in nautical miles for red, green, yellow, and free passage zones for calculating travel time.
optimization_method- Defines the optimization method for path interpolation, such as Dubins curve, Bezier, curve, polynomial, Spline etc.
sampling_rate- Determines the sampling rate for path interpolation.
show_feedback- Displays feedback messages for RViz2 real-time updatesshow_debug- show intermediate results in PyPlot window for debuggingshow_results- show results in PyPlot window
Figure : Results of the path planning algorithm in PyPlot window
show_downsampling- Shows effect of the downsampling parameterstep_sizeson the path planning algorithm
Figure : Downsampling effect on the path planning algorithm
show_interpolation- Shows the effect of the interpolation method on the path planning algorithm
Figure : Interpolation effect on the path planning algorithm
- The execution time, path distance and estiamted travel time are displayed in the terminal:
Figure : Estimated travel time and distance in the terminal
- To visualize the path planning results in RViz2, ensure that all the visualization windows are closed, as it stops the RViz2 tool from updating the visualization data.
If everything is done correctly, the final path planning results should be visible in RViz2 as shown below, with both the D* Lite algorithm and path interpolation results visible:
Figure : RViz2 Visualization of the final path planning results
The following example demonstrates the complete workflow of the ROS2 system architecture for global vessel path planning. The example uses the map_maker, path_planning_client, and path_planning_server packages to generate a feasible path for a vessel navigating from the start to the goal point. in Soline Bay, Croatia
In the input_data directory there are provided few maps of Soline Bay, Croatia. To create a cost map for path planning, run the following command in the Linux terminal:
ros2 launch map_maker make_map_launch.py save_file_name:="klimno" locations:='["dramalj", "crikvenica", "selce", "rudine", "klimno", "silo", "petrina", "vodica", "melska"]' grid_size:="10" Where dramalj, crikvenica, selce, rudine, klimno, silo, petrina, vodica, melska are the names of the folders in the input_data directory containing the map data.
If everything is done correctly, the processed map should be visible in the map_data directory as a binary file named processed_map_klimno.
You can visualize the map using the following command:
ros2 launch map_maker visualization_map_launch.py save_file:="klimno"
Figure : Visualized map of Soline Bay, Croatia
To publish the generated map using the ROS2 publisher gps_coordinates_coast, execute the following command in the Linux terminal:
ros2 launch map_maker publish_map_launch.py save_file:='klimno'To visualize the cost map and open RViz2, run the following command in the Linux terminal:
ros2 launch path_planning_client rviz2_pointcloud_launch.py
Figure : RViz2 Visualization of the cost map of Soline Bay, Croatia
Open Google Maps and find the coordinates of the start and goal points in Soline Bay, Croatia. For example, the start point is at 45.164342, 14.608422 and the goal point is at 45.150569, 14.660261
Figure : Start point coordinates fetched from Google Maps
To set the start and goal points manually via the terminal, execute the following command in the Linux terminal:
ros2 launch path_planning_client update_start_goal_launch.py start:="[45.164342, 14.608422]" goal:="[45.150569, 14.660261]"The same can be done via RViz2 by using the 2D Pose Estimate and 2D Nav Goal tools, but direct terminal input is more precise.
Action client-server communication mechanism ensures that the start and goal points are successfully published and available for path planning. To start client mechanism, run the following command in the Linux terminal:
ros2 launch path_planning_client start_goal_client_launch.pyThis command will start the client mechanism and wait for the path planning server to generate the path. To execute the path planning server, run the following command in the Linux terminal:
ros2 launch path_planning_server path_planning_server_launch.pyFurthermore, you can visualize path-planninh mechanism steps in pyplot window by setting the show_results, show_interpolation, show_downsampling to True:
ros2 launch path_planning_server path_planning_server_launch.py show_results:='True' show_interpolation:='True' show_downsampling:='True'Note that the other parameters can be changed as well, as described before, but they were used in development of the system and are not necessary for the final path planning demonstration. Thus, the default parameters are used to alter the path planning algorithm results and user can change them as needed to achieve the desired results.
Figure : Soline bay final path planning results : show_results:='True'
Figure : Soline bay downsampling effect on the path planning algorithm : show_downsampling:='True'
Figure : Soline bay interpolation effect on the path planning algorithm : show_interpolation:='True'
If everything is done correctly, the final path planning results should be visible in RViz2 as shown below where both D* Lite algorithm and path interpolation results are visible:
Figure : Soline bay final path planning results in RViz2
- Replace
map_makerwith a more efficient and precise map creation tool - Extend map-making capabilities to support nautical charts, including:
- Morphology data
- Danger zone representation
- Integrate up-to-date satellite imagery for:
- Detecting dynamic environmental changes
- Enhancing navigation with static nautical maps
- Improve map generation runtime and precision
- Implement advanced algorithms for smoother and more efficient path generation
- Optimize runtime performance via C++ implementation or NumPy
- Support for:
- Multiple vessels
- Multiple goals and start points
- Local (dynamic) real-time path planning, including:
- Dynamic cost map updates from real-time data
- Dynamic risk assessment strategies
- Environmental data integration
- Obstacle, grounding, and collision avoidance
- COLREG rules compliance
- Support for field deployment:
- Adaptive path updates based on mission and cost constraints
- Seamless integration with guidance and control modules
- Risk assessment and safety analysis tools for path evaluation
- Mission-Planning module support
- Upgrade for multi-mission objective support
- Coordination with the guidance module for:
- Smooth trajectory execution
- Continuous path adjustment
- Real-time path update handling
- Integration with external systems (e.g., navigation, modem communication)
- Final modem integration and robust field testing
- GUI support
The diploma thesis project was developed by the following authors and mentors:
| Academic Title | Author | GitHub | |
|---|---|---|---|
| univ. mag. ing. inf. et comm. techn. | Enio Krizman | @kr1zzo | enio.krizman@fer.hr / krizman.enio@outlook.com |
| Academic Title | Mentor Name | |
|---|---|---|
| Doc. Dr. Sc. | Đula Nađ | dula.nad@fer.hr |
| Dr. Sc. | Nadir Kapetanović | nadir.kapetanovi@fer.hr |
The thesis was defended at the Faculty of Electrical Engineering and Computing, University of Zagreb, on the 9th of July 2024 under the supervision of the following committee members:
| Academic Title | Commitee Member | |
|---|---|---|
| Doc. Dr. Sc. | Đula Nađ | dula.nad@fer.hr |
| Prof. Dr. Sc. | Nikola Mišković | nikola.miskovic@fer.hr |
| Doc. Dr. Sc. | Fausto Miguel Pascoal Ferreira | fausto.ferreira@fer.unizg.hr |
Parts of this repository are based on the following resources and they are used for educational purposes: