{"id":13716248,"url":"https://github.com/naturerobots/mesh_navigation","last_synced_at":"2025-05-12T09:55:24.215Z","repository":{"id":39881613,"uuid":"173430270","full_name":"naturerobots/mesh_navigation","owner":"naturerobots","description":"Mesh Navigation Stack","archived":false,"fork":false,"pushed_at":"2025-03-31T18:36:41.000Z","size":14562,"stargazers_count":629,"open_issues_count":4,"forks_count":83,"subscribers_count":20,"default_branch":"humble","last_synced_at":"2025-05-07T01:01:55.800Z","etag":null,"topics":["3d-path-planning","control","locomotion","mesh","navigation","pathplanning","ros"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/naturerobots.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-03-02T09:46:08.000Z","updated_at":"2025-05-01T20:19:54.000Z","dependencies_parsed_at":"2024-01-29T09:17:50.584Z","dependency_job_id":"ec293e28-8750-4782-825e-d42bd777f09d","html_url":"https://github.com/naturerobots/mesh_navigation","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/naturerobots%2Fmesh_navigation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naturerobots%2Fmesh_navigation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naturerobots%2Fmesh_navigation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/naturerobots%2Fmesh_navigation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/naturerobots","download_url":"https://codeload.github.com/naturerobots/mesh_navigation/tar.gz/refs/heads/humble","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253712118,"owners_count":21951687,"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":["3d-path-planning","control","locomotion","mesh","navigation","pathplanning","ros"],"created_at":"2024-08-03T00:01:08.521Z","updated_at":"2025-05-12T09:55:24.202Z","avatar_url":"https://github.com/naturerobots.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"\u003cdiv align=\"center\" min-width=519px\u003e\n  \u003cimg src=\"docs/images/mesh_navigation_logo.png\" alt=\"Mesh Navigation\" height=150 /\u003e  \n\u003c/div\u003e\n\u003ch4 align=\"center\"\u003eMobile Robot Navigation in 3D Meshes\u003c/h4\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/naturerobots/mesh_navigation_tutorials\"\u003eTutorials\u003c/a\u003e\n  \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n  \u003ca href=\"https://naturerobots.github.io/mesh_navigation_docs/\"\u003eDocumentation\u003c/a\u003e\n  \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n  \u003ca href=\"https://www.youtube.com/@nature-robots\"\u003eVideos\u003c/a\u003e\n  \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n  \u003ca href=\"https://github.com/naturerobots/move_base_flex\"\u003eMove Base Flex\u003c/a\u003e\n  \u003cspan\u003e\u0026nbsp;\u0026nbsp;•\u0026nbsp;\u0026nbsp;\u003c/span\u003e\n  \u003ca href=\"https://github.com/naturerobots/mesh_tools\"\u003eMesh Tools\u003c/a\u003e\n\n  \u003cbr /\u003e\n\u003c/div\u003e\n\n---\n\nThe *Mesh Navigation* bundle provides software for efficient robot navigation on 2D manifolds, which are represented in 3D as triangle meshes. It enables safe navigation in various complex outdoor environments by using a modularly extensible\nlayered mesh map. Layers can be loaded as plugins representing specific geometric or semantic metrics of the terrain. This allows the incorporation of obstacles in these complex outdoor environments into path and motion motion planning.\nThe layered *Mesh Map* is integrated with *Move Base Flex (MBF)*, which provides a universal ROS action interface for path planning, motion control, and for recovery behaviors. We also provide additional planner and controller plugins that run on the layered mesh map.\n\n\u003ccenter\u003e\u003cimg title=\"Demo Gif\" src=\"docs/images/demo.gif?raw=true\" alt=\"Demo Gif\" width=\"600\"\u003e\u003c/center\u003e\n\n\u003c!-- # Contents\n* [Publications](#publications)\n* [Installation](#installation)\n* [Usage Examples and Demos](#usage-examples-and-demos)\n* [Software Stack](#software-stack)\n* [Mesh Map](#mesh-map)\n* [Planners](#planners)\n* [Controllers](#controllers)\n* [Simulation](#simulation)\n* [Maintain and Contribute](#maintain-and-contribute)\n* [Build Status](#build-status) --\u003e\n\n\n# Installation\n\n### ROS Version\nThis is the active ROS 2 branch of this repository, which targets `humble`.\nIf your are looking for the old ROS 1 version, checkout the [noetic branch](https://github.com/naturerobots/mesh_navigation/tree/noetic).\n**Warning**: The ROS 1 version of mesh_navigation is not maintained anymore.\n\n### Installation from source\n* Prerequisite: A working ROS 2 installation\n* Go into a ROS 2 workspace's source directory `cd $YOUR_ROS_WS/src`.\n* Clone the repo `git clone git@github.com:naturerobots/mesh_navigation.git`\n* Get the tutorial's ROS 2 dependencies\n  * Clone source dependencies: Run `vcs import --input mesh_navigation/source_dependencies.yaml` in your ROS 2 workspace source directory.\n  * Get packaged dependencies: Run `rosdep install --from-paths . --ignore-src -r -y` from within your ROS 2 workspace source directory.\n* Build: Go to workspace root `cd $YOUR_ROS_WS` and run `colcon build --packages-up-to mesh_navigation`.\n\n# Usage Examples and Demos\n\nRecommended entrypoint for new users: Check out the **[mesh_navigation_tutorials](https://github.com/naturerobots/mesh_navigation_tutorials/tree/main)** for a ready-to-use mesh navigation stack. Complete with simulated environment, RViz config, mesh nav config, etc.\n\n\n## Demos\n\nIn the following demo videos we used the developed *continuous vector field planner* (CVP).\n\n| Dataset and Description                  | Demo Video                                                                                                               |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |\n| Botanical Garden of Osnabrück University | [![Mesh Navigation with Pluto](http://img.youtube.com/vi/qAUWTiqdBM4/0.jpg)](http://www.youtube.com/watch?v=qAUWTiqdBM4) |\n| Stone Quarry in the Forest Brockum       | [![Mesh Navigation with acorn19](http://img.youtube.com/vi/DFmv3wnIxug/0.jpg)](https://youtu.be/DFmv3wnIxug)             |\n\n### Stone Quarry in the Forest in Brockum\n\n| Colored Point Cloud | Height Diff Layer | RGB Vertex Colors |\n| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |\n| ![StoneQuarryPointCLoud](docs/images/stone_quarry/cloud.png?raw=true \"Stone Quarry Point Cloud\") | ![StoneQuarryHeightDiff](docs/images/stone_quarry/height_diff.jpg?raw=true \"Stone Quarry Height Diff\") | ![StoneQuarryVertexColors](docs/images/stone_quarry/mesh_rgb.jpg?raw=true \"Stone Quarry Vertex Colors\") |\n\n# Software Stack\n\nThis **[mesh_navigation](https://github.com/naturerobots/mesh_navigation)** stack provides a navigation server for **[Move Base Flex (MBF)](https://github.com/naturerobots/move_base_flex)**. It provides a couple of configuration files and launch files to start the navigation server with the configured layer plugins for the layered mesh map, and the configured planners and controller to perform path planning and motion control in 3D (or more specifically on 2D-manifold). \n\nThe package structure is as follows:\n\n- `mesh_navigation` The corresponding ROS meta package.\n\n- `mbf_mesh_core` contains the plugin interfaces derived from the abstract MBF plugin interfaces to initialize planner and controller plugins with one `mesh_map` instance. It provides the following three interfaces:\n  \n  - MeshPlanner - `mbf_mesh_core/mesh_planner.h`\n  - MeshController - `mbf_mesh_core/mesh_controller.h`\n  - MeshRecovery - `mbf_mesh_core/mesh_recovery.h`\n\n- `mbf_mesh_nav` contains the mesh navigation server which is built on top of the abstract MBF navigation server. It uses the plugin interfaces in `mbf_mesh_core` to load and initialize plugins of the types described above.\n\n- `mesh_map` contains an implementation of a mesh map representation building on top of the generic mesh interface implemented in **[lvr2](https://github.com/uos/lvr2)**. This package provides a layered mesh map implementation. Layers can be loaded as plugins to allow a highly configurable 3D navigation stack for robots traversing on the ground in outdoor and rough terrain.\n\n- `mesh_layers` The package provides a couple of mesh layers to compute trafficability/traversibility properties of the terrain. Furthermore, these plugins have access to the HDF5 map file and can load and store layer information. The mesh layers can be configured for the robots abilities and needs. Currently we provide the following layer plugins:\n  \n  - HeightDiffLayer - `mesh_layers/HeightDiffLayer`\n  - RoughnessLayer - `mesh_layers/RoughnessLayer`\n  - SteepnessLayer - `mesh_layers/SteepnessLayer`\n  - RidgeLayer - `mesh_layer/RidgeLayer`\n  - ClearanceLayer - `mesh_layers/ClearanceLayer`\n  - InflationLayer - `mesh_layers/InflationLayer`\n  - BorderLayer - `mesh_layers/BorderLayer`\n\n- `dijkstra_mesh_planner` contains a mesh planner plugin providing a path planning method based on Dijkstra's algorithm. It plans by using the edges of the mesh map. The propagation start a the goal pose, thus a path from every accessed vertex to the goal pose can be computed. This leads to a sub-optimal potential field, which highly depends on the mesh structure.\n\n- `cvp_mesh_planner` contains a Fast Marching Method (FMM) wave front path planner to take the 2D-manifold into account. This planner is able to plan over the surface, due to that it results in shorter paths than the `dijkstra_mesh_planner`, since it is not restricted to the edges or topology of the mesh. A comparison is shown below. Please refer to the paper `Continuous Shortest Path Vector Field Navigation on 3D Triangular Meshes for Mobile Robots`.\n\n## Mesh Map\n\n### Mesh Layers\n\nThe following table gives an overview of all currently implemented layer plugins available in the stack and the corresponding types to specify for usage in the mesh map configuration. An example mesh map configuration is shown below.\n\n#### Overview of all layers\n\n| Layer               | Plugin Type Specifier         | Description of Cost Computation          | Example Image                                                                           |\n| ------------------- | ----------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------- |\n| **HeightDiffLayer** | `mesh_layers/HeightDiffLayer` | local radius based height differences    | ![HeightDiffLayer](docs/images/costlayers/height_diff.jpg?raw=true \"Height Diff Layer\") |\n| **RoughnessLayer**  | `mesh_layers/RoughnessLayer`  | local radius based normal fluctuation    | ![RoughnessLayer](docs/images/costlayers/roughness.jpg?raw=true \"Roughness Layer\")      |\n| **SteepnessLayer**  | `mesh_layers/SteepnessLayer`  | arccos of the normal's z coordinate      | ![SteepnessLayer](docs/images/costlayers/steepness.jpg?raw=true \"Steepness Layer\")      |\n| **RidgeLayer**      | `mesh_layer/RidgeLayer`       | local radius based distance along normal | ![RidgeLayer](docs/images/costlayers/ridge.jpg?raw=true \"RidgeLayer\")                   |\n| **ClearanceLayer**  | `mesh_layers/ClearanceLayer`  | comparison of robot height and clearance along each vertex normal | ![ClearanceLayer](docs/images/costlayers/clearance.jpg?raw=true \"Clearance Layer\") |\n| **InflationLayer**  | `mesh_layers/InflationLayer`  | by distance to a lethal vertex           | ![InflationLayer](docs/images/costlayers/inflation.jpg?raw=true \"Inflation Layer\")      |\n| **BorderLayer** | `mesh_layers/BorderLayer` | give vertices close to the border a certain cost | ![BorderLayer](docs/images/costlayers/border.png?raw=true \"Border Layer\")   |\n\n## Planners\nCurrently the following planners are available:\n\n### Dijkstra Mesh Planner\n\n```yaml\n  mesh_planner:\n    type: 'dijkstra_mesh_planner/DijkstraMeshPlanner'\n```\n\n### Continuous Vector Field Planner\n\n```yaml\n  mesh_planner:\n    type: 'cvp_mesh_planner/CVPMeshPlanner'\n```\n\n### MMP Planner\n\n```yaml\n  mesh_planner:\n    type: 'mmp_planner/MMPPlanner'\n```\n\n**Note**: The MMP planner is currently only available with ROS 1 / [mmp-planner](https://github.com/naturerobots/mesh_navigation/tree/mmp-planner) branch.\n\nThe planners are compared to each other.\n\n| Vector Field Planner                                                                        | Dijkstra Mesh Planner                                                                              | ROS Global Planner on 2.5D DEM                                                     |\n| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |\n| ![VectorFieldPlanner](docs/images/stone_quarry/fmm_pot.jpg?raw=true \"Vector Field Planner\") | ![DijkstraMeshPlanner](docs/images/stone_quarry/dijkstra_pot.jpg?raw=true \"Dijkstra Mesh Planner\") | ![2D-DEM-Planner](docs/images/stone_quarry/dem_side.jpg?raw=true \"2D DEM Planner\") |\n\n## Controllers\n\n### Mesh Controller\n\n```yaml\n  mesh_controller:\n    type: 'mesh_controller/MeshController'\n```\n\n# Publications\n\nPlease reference the following papers when using the navigation stack in your scientific work.\n\n#### Continuous Shortest Path Vector Field Navigation on 3D Triangular Meshes for Mobile Robots\n```bib\n@inproceedings{puetz21cvp,\n    author = {Pütz, Sebastian and Wiemann, Thomas and Kleine Piening, Malte and Hertzberg, Joachim},\n    title = {Continuous Shortest Path Vector Field Navigation on 3D Triangular Meshes for Mobile Robots},\n    booktitle = {2021 IEEE International Conference on Robotics and Automation (ICRA)},\n    year = 2021,\n    url = {https://github.com/uos/mesh_navigation},\n    note = {Software available at \\url{https://github.com/uos/mesh_navigation}}\n}\n```\n\n#### Move Base Flex: A Highly Flexible Navigation Framework for Mobile Robots\n```bib\n@inproceedings{puetz18mbf,\n    author = {Sebastian Pütz and Jorge Santos Simón and Joachim Hertzberg},\n    title = {{Move Base Flex}: A Highly Flexible Navigation Framework for Mobile Robots},\n    booktitle = {2018 IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},\n    year = 2018,\n    month = {October},\n    url = {https://github.com/magazino/move_base_flex},\n    note = {Software available at \\url{https://github.com/magazino/move_base_flex}}\n}\n```\n\n\n# Related Work\n\n## Mesh Tools\n\nWe developed the **[Mesh Tools](https://github.com/naturerobots/mesh_tools)** as a package consisting of message definitions, RViz plugins and tools, as well as a\npersistence layer to store such maps. These tools make the benefits of annotated triangle maps available in ROS and\nallow to publish, edit and inspect such maps within the existing ROS software stack.\n\n## Mesh Localization\n\nFor the necessary localization of the robot relative to the mesh, we recommend using RMCL: [https://github.com/uos/rmcl](https://github.com/uos/rmcl). We presented the combination of both software packages at [ROSCon 2023](https://vimeo.com/879000775):\n\n\u003ca href=\"https://vimeo.com/879000775\" target=\"_blank\" \u003e\u003cimg src=\"docs/images/roscon2023_talk.png\" alt=\"MeshNav ROSCon 2023 Video\" width=\"300px\"/\u003e\u003c/a\u003e\n\n# Maintain and Contribute\nMaintainers:\n* [Matthias Holoch](mailto:matthias.holoch@naturerobots.com) (Nature Robots)\n* [Alexander Mock](https://github.com/amock) (Osnabrück University)\n* [Sebastian Pütz](mailto:sebastian.puetz@naturerobots.com) (Nature Robots, DFKI)\n\nAuthor: [Sebastian Pütz](mailto:spuetz@uos.de)\n\nWe are happy to receive improvements to the mesh navigation stack. Just open an issue. PRs are welcome!\n\n# Build Status\n\n| ROS Distro  | GitHub CI | Develop | Documentation | Source Deb | Binary Deb |\n|-------------|-----------|---------|---------------|------------|------------|\n| **Humble**  | [![Humble CI](https://github.com/naturerobots/mesh_navigation/actions/workflows/humble.yaml/badge.svg)](https://github.com/naturerobots/mesh_navigation/actions/workflows/humble.yaml) | N/A | N/A | N/A | N/A |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaturerobots%2Fmesh_navigation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnaturerobots%2Fmesh_navigation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnaturerobots%2Fmesh_navigation/lists"}