# bmegli/hybrid-a-star architecture

> Architecture diagram of the GitHub repository bmegli/hybrid-a-star, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bmegli/hybrid-a-star
- Repository: https://github.com/bmegli/hybrid-a-star

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    subgraph "Build System"
        CMake["CMakeLists.txt"]:::core
        Git[".gitmodules"]:::core
    end

    %% Inputs and Configuration
    subgraph "Inputs & Configuration"
        MapData["Map Data<br/>(maps/)"]:::data
        StartGoal["Start & Goal Poses"]:::data
        Config["Configuration<br/>(constants.hpp, options.hpp, types.hpp)"]:::data
    end

    %% Core Modules
    subgraph "Core Modules"
        Planner["HybridAStarPlanner"]:::core
        CollisionIface["CollisionChecker Interface"]:::core
        Smoother["PathSmoother"]:::core
    end

    %% External Libraries
    subgraph "External Libraries"
        OMPL["OMPL"]:::external
        Eigen["Eigen"]:::external
        Ceres["Ceres"]:::external
        OpenCV["OpenCV"]:::external
    end

    %% Examples / Applications
    subgraph "Examples / Applications"
        SimpleEx["simple_example.cpp"]:::example
        GUIEx["gui_example.cpp"]:::example
    end

    %% Data Artifacts
    subgraph "Data Artifacts"
        RawPath["Raw Path"]:::data
        SmoothPath["Smoothed Path"]:::data
    end

    %% Dependencies and Data Flow
    MapData -->|provides| Planner
    StartGoal -->|provides| Planner
    Config -->|provides| Planner
    Planner -->|queries| CollisionIface
    CollisionIface -->|uses| footprint["footprint-collision-checker/"]:::external
    Planner -->|outputs| RawPath
    RawPath -->|optional| Smoother
    Smoother -->|outputs| SmoothPath
    SmoothPath --> SimpleEx
    SmoothPath --> GUIEx

    Planner -->|links to| OMPL
    Planner -->|links to| Eigen
    Smoother -->|links to| Ceres
    GUIEx -->|uses| OpenCV

    CMake -->|builds| Planner
    CMake -->|builds| CollisionIface
    CMake -->|builds| Smoother
    CMake -->|builds| SimpleEx
    CMake -->|builds| GUIEx
    Git -->|includes| footprint

    %% Click Events
    click Planner "https://github.com/bmegli/hybrid-a-star/blob/main/a_star.hpp"
    click Planner "https://github.com/bmegli/hybrid-a-star/blob/main/a_star.tpp"
    click Planner "https://github.com/bmegli/hybrid-a-star/blob/main/node_basic.hpp"
    click Planner "https://github.com/bmegli/hybrid-a-star/blob/main/node_se2.hpp"
    click Planner "https://github.com/bmegli/hybrid-a-star/blob/main/node_se2.cpp"
    click Planner "https://github.com/bmegli/hybrid-a-star/blob/main/types.hpp"
    click CollisionIface "https://github.com/bmegli/hybrid-a-star/blob/main/collision_checker.hpp"
    click footprint "https://github.com/bmegli/hybrid-a-star/tree/main/footprint-collision-checker/"
    click Smoother "https://github.com/bmegli/hybrid-a-star/blob/main/smoother.hpp"
    click Smoother "https://github.com/bmegli/hybrid-a-star/blob/main/smoother_cost_function.hpp"
    click Smoother "https://github.com/bmegli/hybrid-a-star/blob/main/options.hpp"
    click Config "https://github.com/bmegli/hybrid-a-star/blob/main/constants.hpp"
    click Config "https://github.com/bmegli/hybrid-a-star/blob/main/options.hpp"
    click Config "https://github.com/bmegli/hybrid-a-star/blob/main/types.hpp"
    click SimpleEx "https://github.com/bmegli/hybrid-a-star/blob/main/examples/simple_example.cpp"
    click GUIEx "https://github.com/bmegli/hybrid-a-star/blob/main/examples/gui_example.cpp"
    click MapData "https://github.com/bmegli/hybrid-a-star/tree/main/maps/"
    click CMake "https://github.com/bmegli/hybrid-a-star/blob/main/CMakeLists.txt"
    click Git "https://github.com/bmegli/hybrid-a-star/blob/main/.gitmodules"

    %% Styles
    classDef core fill:#D0E4FD,stroke:#049;
    classDef external fill:#DFF2BF,stroke:#4A4;
    classDef data fill:#FFF2CC,stroke:#AA0;
    classDef example fill:#E0E0E0,stroke:#666;
```
