# zhm-real/pathplanning architecture

> Architecture diagram of the GitHub repository zhm-real/pathplanning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhm-real/pathplanning
- Repository: https://github.com/zhm-real/pathplanning

## Overview

##### Project Type and Purpose
- This is an open-source Python library of path-planning algorithms for robotics.

##### File-Structure Analysis
- Top-level directories:
- Sampling_based_Planning – 2D and 3D Rapidly-exploring Random Tree (RRT) variants and related planners
- Search_based_Planning – 2D and 3D graph‐search algorithms (A*, Dijkstra, D*, BFS, DFS, etc.)
- Support code in each planner folder: env.py (environment model), queue/queue3D.py (data structures), plotting/plot_util3D.py (visualization helpers), utils.py (misc).
- GIF subdirectories collect output animations for each algorithm.
- No external services—everything runs locally in Python.

##### Key Insights from README
- Purpose: demonstrate and animate classical path-planning algorithms.
- Animations are generated via matplotlib (implied) and saved as GIFs under “gif” subfolders.
- No web/UI layer; this is a library/tool for research and teaching.

##### Main Components
- User Interface (CLI or Notebook)
- Accepts problem definition: map/environment + start/goal
- Core PathPlanning Library
a. Search-based Module
– Search_2D
– Search_3D
b. Sampling-based Module
– rrt_2D
– rrt_3D
c. Curve Generation Module
– CurvesGenerator package
- Shared Utilities
- env.py (2D/3D)
- queue / queue3D
- utils / utils3D
- plotting / plot_util3D
- Output Generator
- GIF writer (matplotlib + imageio)

##### Component Relationships and Data Flow
1. User invokes a planner via CLI or notebook.
2. Planner module imports env.py to load/map the environment.
3. Planner uses queue and utils to grow a graph/tree, guided by heuristic functions.
4. Planner returns a raw path (waypoints).
5. CurveGeneration module takes waypoints → computes continuous spline or Dubins path.
7. GIF writer assembles frames into animation under the “gif” folder.

##### Architectural Patterns and Principles
- Package-based modularity: each algorithm family lives in its own package.
- Shared‐service modules: env, queue, utils, plotting are singletons imported by all planners.
- Separation of concerns: path computation (planner), smoothing (CurvesGenerator), and visualization (plotting + GIF writer).
- Extensibility points: adding a new planner means dropping a new .py in the appropriate package and conforming to the env/queue API.

##### Summary
- Packages as separate components.
- Processing flow from problem definition to final GIF animation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    UI["User Interface<br/>(CLI/Notebook)"]:::ui

    %% Planning Modules
    subgraph "Search-based Planning"
        Search2D["Search_2D"]:::planning
        Search3D["Search_3D"]:::planning
    end
    subgraph "Sampling-based Planning"
        RRT2D["rrt_2D"]:::planning
        RRT3D["rrt_3D"]:::planning
    end

    %% Curve Generation
    CurvesGen["CurvesGenerator"]:::curves

    %% Shared Utilities
    subgraph "Shared Utilities"
        Env2D_SB["env.py (2D)"]:::utils
        Env2D_RB["env.py (2D)"]:::utils
        Env3D_SB["env3D.py (3D)"]:::utils
        Env3D_RB["env3D.py (3D)"]:::utils

        Queue2D_SB["queue.py (2D)"]:::utils
        Queue2D_RB["queue.py (2D)"]:::utils
        Queue3D_SB["queue.py (3D)"]:::utils
        Queue3D_RB["queue.py (3D)"]:::utils

        Utils2D["utils.py (2D)"]:::utils
        Utils3D_RB["utils3D.py (3D)"]:::utils
        Utils3D_SB["utils3D.py (3D)"]:::utils

        Plot2D_SB["plotting.py (2D)"]:::utils
        Plot2D_RB["plotting.py (2D)"]:::utils
        Plot3D_SB["plot_util3D.py (3D)"]:::utils
        Plot3D_RB["plot_util3D.py (3D)"]:::utils
    end

    %% Output Storage
    GIF["GIF Storage"]:::storage

    %% Data Flows
    UI -->|"invoke planner"| Search2D
    UI -->|"invoke planner"| Search3D
    UI -->|"invoke planner"| RRT2D
    UI -->|"invoke planner"| RRT3D

    %% Library Imports (dashed)
    Search2D -.->|"import env"| Env2D_SB
    RRT2D    -.->|"import env"| Env2D_RB
    Search3D -.->|"import env"| Env3D_SB
    RRT3D    -.->|"import env"| Env3D_RB

    Search2D -.->|"import queue"| Queue2D_SB
    RRT2D    -.->|"import queue"| Queue2D_RB
    Search3D -.->|"import queue"| Queue3D_SB
    RRT3D    -.->|"import queue"| Queue3D_RB

    Search2D -.->|"import utils"| Utils2D
    RRT2D    -.->|"import utils"| Utils2D
    Search3D -.->|"import utils"| Utils3D_SB
    RRT3D    -.->|"import utils"| Utils3D_RB

    Search2D -.->|"import plotting"| Plot2D_SB
    RRT2D    -.->|"import plotting"| Plot2D_RB
    Search3D -.->|"import plotting"| Plot3D_SB
    RRT3D    -.->|"import plotting"| Plot3D_RB

    %% Path and Processing Flow
    Search2D -->|"waypoints"| CurvesGen
    Search3D -->|"waypoints"| CurvesGen
    RRT2D    -->|"waypoints"| CurvesGen
    RRT3D    -->|"waypoints"| CurvesGen

    CurvesGen -->|"smoothed path"| Plot2D_SB
    CurvesGen -->|"smoothed path"| Plot3D_SB
    CurvesGen -->|"smoothed path"| Plot2D_RB
    CurvesGen -->|"smoothed path"| Plot3D_RB

    Plot2D_SB -->|"frames"| GIF
    Plot3D_SB -->|"frames"| GIF
    Plot2D_RB -->|"frames"| GIF
    Plot3D_RB -->|"frames"| GIF

    %% Click Events
    click Search2D "https://github.com/zhm-real/pathplanning/tree/master/Search_based_Planning/Search_2D/"
    click Search3D "https://github.com/zhm-real/pathplanning/tree/master/Search_based_Planning/Search_3D/"
    click RRT2D "https://github.com/zhm-real/pathplanning/tree/master/Sampling_based_Planning/rrt_2D/"
    click RRT3D "https://github.com/zhm-real/pathplanning/tree/master/Sampling_based_Planning/rrt_3D/"
    click CurvesGen "https://github.com/zhm-real/pathplanning/tree/master/CurvesGenerator/"
    click Env2D_SB "https://github.com/zhm-real/pathplanning/blob/master/Search_based_Planning/Search_2D/env.py"
    click Env2D_RB "https://github.com/zhm-real/pathplanning/blob/master/Sampling_based_Planning/rrt_2D/env.py"
    click Env3D_SB "https://github.com/zhm-real/pathplanning/blob/master/Search_based_Planning/Search_3D/env3D.py"
    click Env3D_RB "https://github.com/zhm-real/pathplanning/blob/master/Sampling_based_Planning/rrt_3D/env3D.py"
    click Queue2D_SB "https://github.com/zhm-real/pathplanning/blob/master/Search_based_Planning/Search_2D/queue.py"
    click Queue2D_RB "https://github.com/zhm-real/pathplanning/blob/master/Sampling_based_Planning/rrt_2D/queue.py"
    click Queue3D_SB "https://github.com/zhm-real/pathplanning/blob/master/Search_based_Planning/Search_3D/queue.py"
    click Queue3D_RB "https://github.com/zhm-real/pathplanning/blob/master/Sampling_based_Planning/rrt_3D/queue.py"
    click Utils2D "https://github.com/zhm-real/pathplanning/blob/master/Sampling_based_Planning/rrt_2D/utils.py"
    click Utils3D_RB "https://github.com/zhm-real/pathplanning/blob/master/Sampling_based_Planning/rrt_3D/utils3D.py"
    click Utils3D_SB "https://github.com/zhm-real/pathplanning/blob/master/Search_based_Planning/Search_3D/utils3D.py"
    click Plot2D_SB "https://github.com/zhm-real/pathplanning/blob/master/Search_based_Planning/Search_2D/plotting.py"
    click Plot2D_RB "https://github.com/zhm-real/pathplanning/blob/master/Sampling_based_Planning/rrt_2D/plotting.py"
    click Plot3D_SB "https://github.com/zhm-real/pathplanning/blob/master/Search_based_Planning/Search_3D/plot_util3D.py"
    click Plot3D_RB "https://github.com/zhm-real/pathplanning/blob/master/Sampling_based_Planning/rrt_3D/plot_util3D.py"
    click GIF "https://github.com/zhm-real/pathplanning/tree/master/Search_based_Planning/gif/"

    %% Styles
    classDef planning fill:#ADD8E6,stroke:#000;
    classDef curves fill:#90EE90,stroke:#000;
    classDef utils fill:#FFFF99,stroke:#000;
    classDef ui fill:#f9f,stroke:#000,stroke-width:2px;
    classDef storage fill:#d3d3d3,stroke:#000,stroke-dasharray: 5 5;
    class UI ui
```
