(1) Overview
Introduction
Navigating uneven terrain remains a fundamental challenge in mobile robotics, with critical applications in autonomous exploration, search-and-rescue, and planetary missions [10, 23, 15]. Unlike free-space navigation, terrain-aware planning must account for surface constraints, elevation, and changes in surface normals [6, 22, 25]. These constraints severely degrade the performance of standard motion planners: tree-based methods like Rapidly-exploring Random Trees (RRT) exhibit poor exploration efficiency on surface-constrained manifolds. Sampling-based planners such as Model Predictive Path Integral (MPPI) require explicit projection to remain feasible in mesh-based environments.
Despite growing interest in this domain, benchmarking planners over realistic 3D terrains remains ad hoc and fragmented. Existing tools either focus on volumetric occupancy or assume grid-based representations, with limited support for 3D mesh-based navigation workflows derived from lidar or photogrammetry pipelines. Moreover, few frameworks provide consistent interfaces for visualizing and empirically evaluating planners under surface adherence constraints. This gap hinders systematic comparison and slows progress in terrain-aware algorithm development.
To address these limitations, we present MeshNav3D—an open-source Python framework for interactive visualization and empirical evaluation of planning algorithms operating on 3D surface meshes. MeshNav3D supports terrain inputs in standard .obj and .ply formats, including those generated by lidar reconstruction tools such as Las Vegas Surface Reconstruction 2.0 (LVR2) [24]. The proposed framework provides a unified interface for integrating planners, visualizing paths, and collecting quantitative metrics on surface-constrained motion planning tasks.
Related Work
The problem of motion planning over uneven terrain has received increasing attention with the growing availability of 3D terrain data from lidar and photogrammetry [13]. Several tools exist for terrain modeling, visualization, and algorithm development, yet most fail to provide an integrated environment for benchmarking planners over 3D mesh surfaces. This section reviews key systems across three categories: terrain representation, planner evaluation frameworks, and visualization tools.
General-purpose 3D data libraries like the Point Cloud Library (PCL) [14] and Open3D [26] offer extensive functionality for point cloud processing, surface reconstruction, and mesh manipulation. These tools support standard formats such as .ply and .obj and are widely used in lidar-driven workflows. However, both frameworks are designed for geometry processing rather than planning and lack built-in mechanisms for integrating or benchmarking motion planners. Their steep learning curves and boilerplate-heavy interfaces further limit their utility for rapid experimentation in planning research.
LVR2 [24], a specialized tool for lidar-based surface reconstruction, outputs high-fidelity meshes suitable for planning tasks. Nonetheless, it focuses on data preprocessing; it does not support downstream tasks like algorithm integration, evaluation, or visualization. In contrast, MeshNav3D builds directly on outputs from tools like LVR2, enabling streamlined transitions from mesh data to empirical planner evaluation.
Several established frameworks support the development and benchmarking of motion planning algorithms. The Open Motion Planning Library (OMPL) [19] is a widely-used toolkit offering a broad selection of planners, including sampling-based and optimization-based methods. However, OMPL operates on abstract configuration spaces and lacks native support for 3D surface navigation. Adapting it for mesh-constrained planning requires non-trivial extensions to its state space and collision-checking infrastructure.
Similarly, MoveIt [1] provides a high-level interface for robotic motion planning, primarily targeting manipulator arms within structured environments. While extensible, it is built around kinematic chains and Cartesian planning spaces, making it ill-suited for mesh-based terrain navigation involving mobile robots.
Individual researchers, such as [13, 2], have contributed open-source repositories implementing their terrain-aware planning algorithms, offering valuable resources for specific use cases. Additionally, libraries like cgal [21] and PyVista [20] provide open-source implementations of algorithms such as Dijkstra’s for mesh-based pathfinding. However, these efforts remain fragmented, with no unified open-source collection of terrain planners that includes an extensible interface for integrating newer algorithms or standardized tools for benchmarking and comparison.
By comparison, MeshNav3D is purpose-built for terrain-aware planning. It integrates classical and modern planners with mesh representations out-of-the-box and exposes standardized metrics for reproducible benchmarking—capabilities not directly available in OMPL or MoveIt.
Interactive visualization is critical for developing and debugging planning algorithms. Tools like RViz [9] and Move Base Flex (MBF) [13]—both part of the Robot Operating System (ROS) ecosystem—offer robust visualization pipelines for 3D robotic environments. While powerful, they leverage ROS infrastructure, which imposes significant overhead for users not operating within the ROS stack.
In contrast, MeshNav3D provides a standalone, Python-native visualization interface tailored to mesh environments. It supports real-time inspection of planner behavior, path feasibility, and terrain constraints.
Although existing tools such as PCL, Open3D, OMPL, and RViz provide components of a terrain-aware planning pipeline, none offer an integrated solution for benchmarking surface-constrained planners over real-world mesh terrains. They are either general-purpose libraries with limited support for planning or full-stack frameworks designed for different robotic domains. MeshNav3D fills this gap by combining lightweight mesh ingestion, planner integration, interactive visualization, and empirical benchmarking into a unified and extensible framework.
Implementation and architecture
MeshNav3D architecture, shown in Figure 1, is composed of three primary subsystems: (i) a Planner Subsystem for algorithm execution and benchmarking, (ii) a Visualizer Subsystem for real-time rendering and interaction, and (iii) a lightweight User Interface to facilitate scenario configuration. This section describes the design principles and core components of the system.
Figure 1
The MeshNav3D architecture. The system ingests 3D mesh terrain data, supports dynamic planner configuration and execution, and provides real-time visualization for evaluation and debugging.
The pipeline begins with the Mesh Loader, which parses and preprocesses 3D terrain models in standard formats such as .obj and .ply. Using the PyVista library [20], the mesh is transformed into a topologically navigable surface. The system supports non-watertight meshes and noisy reconstructions, reflecting the imperfections of real-world lidar data. This terrain representation forms the basis for planner operations and visual feedback.
Planner Subsystem
The system initializes planning when the user defines start and goal points, and a PlannerConfig—a structured specification including hyperparameters (e.g., step size, time horizon) and output options (e.g., verbosity, logging path). The Planner Manager dynamically instantiates planning algorithms through a plug-and-play architecture. Each algorithm inherits from an abstract BasePlanner interface, ensuring a uniform API across built-in (e.g., Dijkstra, A*) and custom planners.
The planner computes a trajectory constrained to the terrain surface and encapsulates the outputs in a Planner Output object. Planner Output includes trajectory points, execution time, memory usage, and derived metrics such as path length and traversal optimality. MeshNav3D serializes the results in JSON and NumPy formats for downstream analysis and reproducibility.
Visualizer Subsystem
The Visualizer Subsystem renders terrain meshes and planner outputs in real time. Built on PyVista and Trimesh, the visualizer supports elevation-based coloring, interactive camera control, and trajectory overlay. Users can define start and goal positions through direct mesh interaction using the built-in point-picking tool.
Two visualization modes are supported:
SinglePlannerVisualizer — renders the trajectory of a single planner.
MultiPlannerVisualizer — overlays trajectories from multiple planners for comparative analysis.
Underlying both is the BaseVisualizer class, which exposes shared utilities such as mesh transformations and visual styling. This layered design allows researchers to rapidly switch planners, adjust viewpoints, and assess planner behaviors with minimal overhead.
System Design Principles
Modularity: Each subsystem operates independently through well-defined interfaces, allowing for seamless integration or replacement of components (e.g., planners, mesh loaders, output loggers).
Extensibility: New planners can be added by subclassing BasePlanner, without modifying core framework logic.
Interactivity: The real-time visual feedback loop enables iterative debugging, sensitivity analysis, and qualitative insight into algorithm behavior—essential for evaluating surface-constrained motion.
Inversion of Control: The framework employs inversion of control to decouple component dependencies, delegating the instantiation and orchestration of planners to the core system. This ensures that planners adhere to standardized interfaces (e.g., BasePlanner) and enables flexible configuration, allowing users to inject custom planner implementations without altering the framework’s execution flow.
Planner Implementations
MeshNav3D contains a collection of both classical and state-of-the-art, mesh planning algorithms. The approaches span classic graph search, geometric methods, and diffusion-based techniques. Below is a summary of their implementations. AStarPlanner implements standard A*, combining known path cost and Euclidean heuristics. It uses Python heapq for the priority queue to track visited nodes for path reconstruction. The method follows [4], adapted for 3D mesh surface planning. DijkstraPlanner ensures optimality via exhaustive search. Rather than a custom implementation, it uses the PyVista geodesic method for native mesh support and optimized performance. Metrics like run time and optimality were still recorded [3, 20]. FlipOutPlanner replaces graph traversal with local geometry refinement via edge flips. Based on potpourri3d’s EdgeFlipGeodesicSolver, it iteratively improves distance estimates, capped by iteration limits. Especially effective on irregular meshes [18, 17]. FastMarchingPlanner (FMM) numerically solves the Eikonal equation using a custom heap-based Fast Marching Method. Distances propagate in sorted order. Well-suited for global consistency and topological complexity [16]. For the priority queue and tracks visited nodes for path reconstruction. The method GreedyBFSPlanner (BFS) prioritizes speed over accuracy, expanding nodes based solely on goal proximity. It ignores accumulated costs, often yielding suboptimal paths. It uses a simple adjacency list and priority queue; visualization mirrors the A* approach. HeatMethodPlanner leverages the Heat Method [2] via potpourri3d’s solver, solving heat diffusion and Poisson equations to estimate distances. Paths follow the negative gradient. Fast and robust, even on noisy or irregular meshes. MMPPlanner employs the Mitchell-Mount-Papadimitriou algorithm via pygeodesic, computing exact geodesics through wavefront propagation and continuous Dijkstra expansion. Computationally heavy, but serves as a ground truth reference [11, 5]. ThetaStarPlanner adapts Theta* for meshes, incorporating line-of-sight checks to reduce detours and enable smoother paths. Uses custom heap and collision checks to preserve surface validity. More complex than A*, but better suited for coarse meshes [12].
Quality control
The codebase includes unit tests for each implemented planner, ensuring that individual components behave as expected. These tests can be executed using the command:
This provides a baseline check for correctness and helps catch regressions as the code evolves.
For functional verification, users must follow these steps to install and run the software in a clean environment:
Create and activate a Python virtual environment with version >=3.12:
Install the package:
Create a new Python file, for example test.py, and paste in one of the following code snippets.
This framework has been tested and verified to work on the following configurations:
Ubuntu 24.04, Python 3.12, running on an ASUS ROG Strix G614JU
macOS Sequoia, running on a MacBook Pro
Example usage includes:
Visualizing planners on a mesh to confirm rendering and basic pathfinding:
Running benchmarks across multiple scenarios to validate planner performance and results consistency:
To run the test script, execute:
“terrain_mesh” makes the software use the default mesh environment, but users can replace it with a path to a different mesh file to test on custom terrain configurations.
(2) Availability
Operating system
The software has been tested on and is compatible with:
Ubuntu 24.04 LTS (or newer)
macOS Sequoia (or newer)
Other Unix-like systems and Windows should work as long as they support Python, but they haven’t been tested and are not officially supported at this time.
Programming language
The codebase is written in Python 3.12 or newer. Older versions of Python will not work due to dependency and syntax requirements.
Additional system requirements
At least 8 GB of RAM is recommended for smooth operation and planner benchmarking.
A modern multi-core CPU is beneficial, especially for benchmarking multiple planners.
Disk space: <1 GB for installation, but additional space will be used for generated output files (benchmark results, visualizations).
No GPU required.
A mouse or trackpad is useful for interacting with visualizations.
Dependencies
The software requires the following Python packages (automatically installed via pip install mesh_nav_3D):
python ≥ 3.12
pyvista ≥ 0.44.2
tqdm ≥ 4.67.1
pygeodesic ≥ 0.1.11
potpourri3d ≥ 1.2.1
pydantic ≥ 2.11.2
psutil ≥ 7.0.0
pybullet ≥ 3.2.7
The project uses poetry for dependency management and reproducible builds, though it is not required for end users who install via pip.
List of Contributors
The following individuals contributed to the development of the software, including those who may not be authors of this paper, along with their roles and affiliations.
Jerome, Otobong; Lead Developer, Center of Autonomous Technologies, Innopolis University, Russia
Okeme, Christian; Contributor, Fin3 Technologies Inc., United States
Bassey, Christian; Contributor, Center of Autonomous Technologies, Innopolis University, Russia
Maloletov, Alexander; Contributor and Supervisor, Center of Autonomous Technologies, Innopolis University, Russia
Kulathunga, Geesara; Contributor and Supervisor, School of Computer Science, University of Lincoln, United Kingdom
Software location
Archive
Name: Python Package Index (PyPI)
Persistent identifier: https://pypi.org/project/mesh_nav_3D/
Licence: MIT License
Publisher: Otobong Jerome
Version published: 1.0.0
Date published: 18/04/25
Code repository
Name: GitHub
Persistent identifier: https://github.com/Stblacq/MeshNav3D
Licence: MIT License
Date published: 18/04/25
Language
The software, repository, and supporting files are written in Python. Documentation and supporting files are in English.
(3) Reuse Potential
MeshNav3D supports several key use cases that enable researchers to explore, develop, and evaluate planning algorithms for robotic navigation on complex terrains:
Visualizing Path Planning on Uneven Terrain: Researchers can use MeshNav3D to visualize paths generated by standard planners, such as Dijkstra’s algorithm, on real-world terrains with varying elevations. This capability is critical for analyzing how planners adapt to terrain constraints and for studying navigation strategies under realistic conditions. The visualization tools provide intuitive insights into path quality and planner behavior, making the software accessible to researchers studying robotic navigation or terrain-based simulations.
Development and Prototyping of New Planners: MeshNav3D’s modular framework facilitates rapid prototyping of custom planning algorithms. Researchers can extend the base Planner class to implement novel algorithms, leveraging the framework’s interactive visualization and performance metrics tools to test and refine their designs in a realistic 3D environment. For example, the software was used in [6, 8] and [7] to prototype and evaluate kinodynamic planners, demonstrating its utility in advanced navigation research.
Comparing Different Planners: The framework enables comparative evaluation of multiple planning algorithms.
Researchers can use the MultiPlannerVisualizer to visually compare planner outputs or conduct rigorous programmatic comparisons through standardized performance metrics. This feature supports algorithm selection, optimization, and benchmarking, making MeshNav3D a valuable tool for performance-driven research and development.
Beyond robotic navigation, MeshNav3D has reuse potential in related fields such as computer graphics and computational geometry, where 3D mesh processing and path planning are relevant.
The software is designed to be extensible, allowing researchers to modify or build upon its functionality. The modular architecture, centered around the Planner class, enables seamless integration of new algorithms or terrain models. Developers can customize visualization tools or extend performance metrics to suit specific research needs. Contributions or extensions can be proposed via the project’s GitHub repository (https://github.com/Stblacq/MeshNav3D), where researchers are encouraged to submit issues, feature requests, or pull requests.
Acknowledgements
We gratefully acknowledge the open-source communities and developers of Python, pyvista, pygeodesic, potpourri3d, pydantic, psutil, and pybullet for their essential libraries, which enabled critical functionality for 3D terrain processing, visualization, data validation, and simulation in MeshNav3D. Their contributions significantly supported the development of our project.
Competing Interests
The authors have no competing interests to declare.