diff --git a/configuration/packages/configuring-route-server.rst b/configuration/packages/configuring-route-server.rst index 2bbb5685b6..de39f50dae 100644 --- a/configuration/packages/configuring-route-server.rst +++ b/configuration/packages/configuring-route-server.rst @@ -12,7 +12,7 @@ It may be used to fully replace freespace planning when following a particular r In this case, the planner will generate feasible paths with localized environmental information for only the future part of the route necessary. The graph itself has very few rules associated with it, but may be generated manually or automatically via AI, geometric, or probabilistic techniques. -See :ref:`route_graph_generation` for a tutorial about how to generate a graph using QGIS. +See :ref:`route_graph_generation` and :ref:`route_graph_generation_lif_editor` for a tutorial about how to generate a graph using QGIS. There are also several locations for customization using plugins: * Edge Scorer: Enables custom scoring functions for edges based on arbitrary user-defined semantic information and the chosen optimization criteria(s). diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/add_edge_fast_create.png b/tutorials/docs/images/route_graph_generation_lif_editor/add_edge_fast_create.png new file mode 100644 index 0000000000..fd3538bf8e Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/add_edge_fast_create.png differ diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/add_edge_normal.png b/tutorials/docs/images/route_graph_generation_lif_editor/add_edge_normal.png new file mode 100644 index 0000000000..0d6a5aa2ef Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/add_edge_normal.png differ diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/add_node.png b/tutorials/docs/images/route_graph_generation_lif_editor/add_node.png new file mode 100644 index 0000000000..ae44112c71 Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/add_node.png differ diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/check_geojson.png b/tutorials/docs/images/route_graph_generation_lif_editor/check_geojson.png new file mode 100644 index 0000000000..f06854e552 Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/check_geojson.png differ diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/check_geojson_1.png b/tutorials/docs/images/route_graph_generation_lif_editor/check_geojson_1.png new file mode 100644 index 0000000000..ab70e1030a Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/check_geojson_1.png differ diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/delete_edge.png b/tutorials/docs/images/route_graph_generation_lif_editor/delete_edge.png new file mode 100644 index 0000000000..1315726f0e Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/delete_edge.png differ diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/delete_node.png b/tutorials/docs/images/route_graph_generation_lif_editor/delete_node.png new file mode 100644 index 0000000000..1c6deff2d2 Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/delete_node.png differ diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/export_geojson.png b/tutorials/docs/images/route_graph_generation_lif_editor/export_geojson.png new file mode 100644 index 0000000000..9c2d2c1762 Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/export_geojson.png differ diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/frame_name.png b/tutorials/docs/images/route_graph_generation_lif_editor/frame_name.png new file mode 100644 index 0000000000..a1e90f1d69 Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/frame_name.png differ diff --git a/tutorials/docs/images/route_graph_generation_lif_editor/setup_coordinate_system.png b/tutorials/docs/images/route_graph_generation_lif_editor/setup_coordinate_system.png new file mode 100644 index 0000000000..473c1cd093 Binary files /dev/null and b/tutorials/docs/images/route_graph_generation_lif_editor/setup_coordinate_system.png differ diff --git a/tutorials/docs/route_server_tools.rst b/tutorials/docs/route_server_tools.rst new file mode 100644 index 0000000000..136366a008 --- /dev/null +++ b/tutorials/docs/route_server_tools.rst @@ -0,0 +1,37 @@ +.. _route_server_tools: + +Route Server Tools +################## + +Route Server tools are essential components in the Nav2 ecosystem that help users create, edit, and manage route graphs for robot navigation. A route graph is a representation of valid paths that a robot can follow in its environment, consisting of nodes (waypoints) and edges (connections between waypoints). These tools simplify the process of defining preferred paths and restricted areas for robot navigation. + +Unlike free-space planning, route-based navigation ensures that robots follow specific, predefined paths, which is particularly useful in: + +- Industrial environments where specific routes must be followed +- Warehouse operations requiring structured movement patterns +- Facilities with restricted areas or preferred paths +- Multi-robot coordination scenarios where predefined routes help prevent conflicts +- Large scale outdoor urban or natural environments + +Provided Tools +************** + +.. toctree:: + :maxdepth: 1 + + route_server_tools/navigation2_route_tool.rst + route_server_tools/route_graph_generation_lif_editor.rst + route_server_tools/route_graph_generation.rst + +Description +*********** + +There are several tools available for creating and editing route graphs for the Nav2 Route Server: + +1. **Nav2 Route Tool**: An Rviz panel that allows users to create, edit, and manage route graphs directly within the ROS 2 environment. It supports loading existing graphs, adding/editing/removing nodes and edges, and saving changes to files. + +2. **VDA LIF Editor**: A web-based tool that allows users to create route graphs using floor plan images. It can generate both GeoJSON and LIF formats, making it particularly useful for standardized route creation. No installation is required as it runs in a web browser. + +3. **Manual Route Graph Generation**: For those who prefer direct file editing, route graphs can be created manually in GeoJSON format using QGIS. This method provides the most control over the graph structure but requires understanding of the GeoJSON format. + +Choose the tool that best fits your needs based on your workflow and requirements. diff --git a/tutorials/docs/navigation2_route_tool.rst b/tutorials/docs/route_server_tools/navigation2_route_tool.rst similarity index 92% rename from tutorials/docs/navigation2_route_tool.rst rename to tutorials/docs/route_server_tools/navigation2_route_tool.rst index 126c3fa3ed..4c5bc7edab 100644 --- a/tutorials/docs/navigation2_route_tool.rst +++ b/tutorials/docs/route_server_tools/navigation2_route_tool.rst @@ -7,7 +7,7 @@ Using the Nav2 Route Tool - `Prerequisites`_ - `Tutorial Steps`_ -.. image:: images/Navigation2_route_tool/route_tool_demo.gif +.. image:: ../images/Navigation2_route_tool/route_tool_demo.gif :width: 90% :align: center @@ -39,7 +39,7 @@ This should open Rviz with the route tool panel on the left side and your occupa Loading a Route Graph --------------------- -.. image:: images/Navigation2_route_tool/route_load.gif +.. image:: ../images/Navigation2_route_tool/route_load.gif :width: 90% :align: center @@ -50,7 +50,7 @@ After clicking open, you should see the route graph overlaid with your occupancy Adding Nodes and Edges ---------------------- -.. image:: images/Navigation2_route_tool/route_add.gif +.. image:: ../images/Navigation2_route_tool/route_add.gif :width: 90% :align: center @@ -63,7 +63,7 @@ For edges, follow the same process with the "Edge" option selected and specifyin Editing Nodes and Edges ----------------------- -.. image:: images/Navigation2_route_tool/route_edit.gif +.. image:: ../images/Navigation2_route_tool/route_edit.gif :width: 90% :align: center @@ -77,7 +77,7 @@ Existing edges can be edited by selecting the "Edge" option, entering the ID of Removing Nodes and Edges ------------------------ -.. image:: images/Navigation2_route_tool/route_delete.gif +.. image:: ../images/Navigation2_route_tool/route_delete.gif :width: 90% :align: center @@ -90,7 +90,7 @@ You may need to toggle the visibility of the route graph in Rviz to see the chan Saving a Route Graph -------------------- -.. image:: images/Navigation2_route_tool/route_save.gif +.. image:: ../images/Navigation2_route_tool/route_save.gif :width: 90% :align: center diff --git a/tutorials/docs/route_graph_generation.rst b/tutorials/docs/route_server_tools/route_graph_generation.rst similarity index 93% rename from tutorials/docs/route_graph_generation.rst rename to tutorials/docs/route_server_tools/route_graph_generation.rst index 89cc7d49a9..25df791686 100644 --- a/tutorials/docs/route_graph_generation.rst +++ b/tutorials/docs/route_server_tools/route_graph_generation.rst @@ -32,7 +32,7 @@ Set the project coordinate reference system by selecting `Project->Properties->C | - .. image:: images/route_graph_generation/coordinate_reference_system.png + .. image:: ../images/route_graph_generation/coordinate_reference_system.png :height: 550px :width: 530px :align: center @@ -58,7 +58,7 @@ type`, `WGS 84/ Pseudo-Mercator` for `Target SRS` and set your desired path for | - .. image:: images/route_graph_generation/transformation_settings.png + .. image:: ../images/route_graph_generation/transformation_settings.png :height: 757px :width: 458px :align: center @@ -71,7 +71,7 @@ by selecting `Start Transformation`. | - .. image:: images/route_graph_generation/georeferencer.png + .. image:: ../images/route_graph_generation/georeferencer.png :height: 400px :width: 730px :align: center @@ -82,7 +82,7 @@ Close the window. Drag and drop the georeferenced raster file that was just crea | - .. image:: images/route_graph_generation/raster_layer.png + .. image:: ../images/route_graph_generation/raster_layer.png :height: 350px :width: 520px :align: center @@ -102,7 +102,7 @@ Select `Layer -> Create Layer -> New ShapeFile Layer`. Set the shapefile layer s | - .. image:: images/route_graph_generation/node_layer.png + .. image:: ../images/route_graph_generation/node_layer.png :height: 520px :width: 440px :align: center @@ -114,7 +114,7 @@ Expand the `Fields` drop down menu and select `id`. Select the `Expression Dialo | - .. image:: images/route_graph_generation/attribute_form.png + .. image:: ../images/route_graph_generation/attribute_form.png :height: 390px :width: 550px :align: center @@ -128,7 +128,7 @@ This will increment the node `id` by one every time a new node is added. The fir | - .. image:: images/route_graph_generation/expression_dialog.png + .. image:: ../images/route_graph_generation/expression_dialog.png :height: 380px :width: 470px :align: center @@ -143,7 +143,7 @@ Once complete, unselect 'Toggle Editing' and save changes. | - .. image:: images/route_graph_generation/nodes.png + .. image:: ../images/route_graph_generation/nodes.png :height: 500px :width: 1000px :align: center @@ -167,7 +167,7 @@ This will increment the edge `id` by one every time a new edge is added. The fir | - .. image:: images/route_graph_generation/edge_layer.png + .. image:: ../images/route_graph_generation/edge_layer.png :height: 520px :width: 440px :align: center @@ -185,7 +185,7 @@ Once complete, unselect 'Toggle Editing' and save changes. | - .. image:: images/route_graph_generation/edges.png + .. image:: ../images/route_graph_generation/edges.png :height: 500px :width: 1000px :align: center @@ -205,7 +205,7 @@ coordinate reference system is `WGS 84 /Pseudo-Mercator`. Press `OK`. | - .. image:: images/route_graph_generation/db_manager.png + .. image:: ../images/route_graph_generation/db_manager.png :height: 350px :width: 530px :align: center diff --git a/tutorials/docs/route_server_tools/route_graph_generation_lif_editor.rst b/tutorials/docs/route_server_tools/route_graph_generation_lif_editor.rst new file mode 100644 index 0000000000..90a1a49e01 --- /dev/null +++ b/tutorials/docs/route_server_tools/route_graph_generation_lif_editor.rst @@ -0,0 +1,175 @@ +.. _route_graph_generation_lif_editor: + +Route Graph Generation LIF Editor +********************************* + +- `Overview`_ +- `Requirements`_ +- `Tutorial Steps`_ + +Overview +======== +A route can also be created using the **VDA LIF Editor**, a web-based open-source tool. This project was developed to present floor plans in a standardized format defined by the VDA. With the VDA LIF Editor, you can generate both GeoJSON and LIF formats simultaneously. + +- Website: https://vda5050-lif-editor.vercel.app/ +- Github: https://github.com/bekirbostanci/vda5050_lif_editor + +Requirements +============ +This is an online web-based tool, so no installation is required. You can use it directly in your browser. + +Tutorial Steps +============== + +1. Create Layout +---------------- + +Click the **'Edit'** button under the **'Layout'** section in the left sidebar. This will open a new popup where you can edit the layout name. Click the **'Save'** button to save it. + +.. note:: + You can also change the layout name after creating the layout. + +| + +.. image:: ../images/route_graph_generation_lif_editor/frame_name.png + :width: 710px + :height: 330px + :align: center + +| + + +Click the **'Edit'** button under the **'Layout'** section in the left sidebar. In the popup, upload your floor plan image using the **'Background Image'** section. +After uploading the image, four input fields will appear. Set the image width and height in meters, and specify the origin coordinates (X, Y). +The origin is the bottom-left corner of the image. +Click the **'Save'** button to save and close the popup. + +.. note:: + If you don't see the image, zoom out the map and check the origin position of your image. + +| + +.. image:: ../images/route_graph_generation_lif_editor/setup_coordinate_system.png + :width: 710px + :height: 330px + :align: center + +| + +2. Node Operations +------------------ + +Add Node +~~~~~~~~ +Now you can add nodes to the map. There are two ways to do this: + +1. Click directly on the map to add a node. This will create a node automatically. If you want to change its properties, click on the node and edit its information in the right sidebar. +2. Click the **'Node'** button under the **'Create Item'** section in the left sidebar. This will display the **'Create Node'** section in the right sidebar. Fill in the node details and click **'Save'** to create the node. + +.. note:: + If the **'Fast Create'** toggle is on, you cannot create nodes using the right sidebar (method 2). You must turn the toggle off first. + +| + +.. image:: ../images/route_graph_generation_lif_editor/add_node.png + :width: 710px + :height: 330px + :align: center + +| + +Delete Node +~~~~~~~~~~~ +To delete a node, click on it (a glowing orange border will appear around the selected node), then click the **'Delete'** button in the right sidebar. + +| + +.. image:: ../images/route_graph_generation_lif_editor/delete_node.png + :width: 710px + :height: 330px + :align: center + +| + +3. Edge Operations +------------------ + +Add Edge +~~~~~~~~ +Now we can add edges to the map. There are two ways to create edges: + +1. Select a node, enter the target node ID in the **'Connected Nodes'** input in the right sidebar, and select the node from the list. This will create an edge between the selected node and the target node. + +| + +.. image:: ../images/route_graph_generation_lif_editor/add_edge_normal.png + :width: 710px + :height: 330px + :align: center + +| + +2. If the **'Fast Create'** toggle is on, clicking on the map will automatically connect the new node to the previously selected node. + +| + +.. image:: ../images/route_graph_generation_lif_editor/add_edge_fast_create.png + :width: 710px + :height: 330px + :align: center + +| + +Delete Edge +~~~~~~~~~~~ +To delete an edge, click on it (the edge color will change to orange), then click the **'Delete'** button in the right sidebar. + +| + +.. image:: ../images/route_graph_generation_lif_editor/delete_edge.png + :width: 710px + :height: 330px + :align: center + +| + +4. Check GeoJSON +---------------- +Click the **'ROS'** menu button on the top bar to view the generated GeoJSON. + +| + +.. image:: ../images/route_graph_generation_lif_editor/check_geojson.png + :width: 710px + :height: 330px + :align: center + +| + +.. image:: ../images/route_graph_generation_lif_editor/check_geojson_1.png + :width: 710px + :height: 330px + :align: center + +| + +5. Export to GeoJSON +-------------------- +You are now ready to export the node and edge layers as GeoJSON files. Click the **'Save'** button on the top bar and then select **'Export ROS GeoJSON'**. + +| + +.. image:: ../images/route_graph_generation_lif_editor/export_geojson.png + :width: 710px + :height: 330px + :align: center + +| + +6. Congratulations +------------------ +Your graph is now ready to be used by the Nav2 route! If you want to edit the graph later, you should also export the LIF file. +Click the **'Save'** button on the top bar and select **'Export LIF'**. +To edit, reopen the LIF file in the VDA LIF Editor and make your changes. You can also re-export the LIF file as GeoJSON. + +**Happy Routing!** diff --git a/tutorials/index.rst b/tutorials/index.rst index c9c35927ec..bb6766ba10 100644 --- a/tutorials/index.rst +++ b/tutorials/index.rst @@ -15,17 +15,16 @@ Nav2 Tutorials docs/using_groot.rst docs/integrating_vio.rst docs/navigation2_dynamic_point_following.rst - docs/navigation2_route_tool.rst docs/navigation2_with_keepout_filter.rst docs/navigation2_with_speed_filter.rst docs/using_docking.rst docs/using_shim_controller.rst docs/adding_smoother.rst docs/using_collision_monitor.rst - docs/route_graph_generation.rst docs/adding_a_nav2_task_server.rst docs/filtering_of_noise-induced_obstacles.rst docs/camera_calibration.rst docs/get_backtrace.rst docs/get_profile.rst docs/docker_dev.rst + docs/route_server_tools.rst