How bmegli/hybrid-a-star works
Project Type and Purpose
• This is an open-source C++ library/tool implementing the Hybrid A* path-planning algorithm (formerly part of ROS2 navigation2).
• It provides a reusable core planner and a separate smoother, with minimal external dependencies (OMPL, Eigen, Ceres, optional OpenCV for GUI).
Top-Level File Structure Analysis
• Core headers & implementation:
• a_star.hpp/.tpp – the Hybrid A* planner
• collision_checker.hpp – collision checking interface
• node_basic.hpp, node_se2.hpp/.cpp – state representation in SE(2)
• smoother.hpp, smoother_cost_function.hpp – post-processing smoother
• constants.hpp, options.hpp, types.hpp – configuration & data types
• Examples:
• examples/simple_example.cpp – CLI usage demo
• examples/gui_example.cpp – OpenCV-based interactive demo
• Submodules/directories:
• footprint-collision-checker – external collision-checking logic
• maps – sample or test map data
• Build system:
• CMakeLists.txt + .gitmodules – orchestrates building core, examples, links external libs
Key README Insights
• Emphasizes separation from ROS2, standalone use
• Dependencies: OMPL (for motion primitives), Eigen (linear algebra), Ceres (smoother solver), OpenCV (GUI only)
• Two main functional blocks: planner and smoother
• Examples implicitly show data-flow: select start/goal → plan → (optional) smooth → render or output
Main Components
a. Inputs
• Data (occupancy grid or costmap)
• Start & Goal Poses (from user or external module)
• Configuration/Options
b. Core Planner Module (“HybridAStarPlanner”)
• Implements the main search (a_star.hpp/.tpp)
• Utilizes NodeSE2, NodeBasic types
• Interfaces with CollisionChecker
c. Collision Checking Component
• footprint-collision-checker submodule
• collision_checker.hpp: abstracts collision-query API
d. Path Smoother Module (“PathSmoother”)
• Uses ceres-solver (smoother.hpp + smoother_cost_function.hpp)
e. Examples/Applications
• simple_example: command-line runner
• gui_example: OpenCV window, user input, visualization
f. External Libraries & Build
• CMake build orchestrator
Relationships & Data Flow
• Planner ↔ Collision Checker (bidirectional during node expansion)
• Planner outputs Raw Path → Smoother (optional)
• Smoother outputs Smoothed Path → Examples/Applications
• Examples drive user interaction and visualization
Architectural Patterns & Principles
• Modular separation: planning vs. smoothing vs. collision checking
• Dependency inversion: planner depends on CollisionChecker interface, not concrete implementation
• Single Responsibility: each .hpp/.tpp group is one coherent module
• Extension points: swap in different collision checker or smoother cost function