# arghyachatterjee/waypoint-based-3d-navigation architecture

> Architecture diagram of the GitHub repository arghyachatterjee/waypoint-based-3d-navigation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arghyachatterjee/waypoint-based-3d-navigation
- Repository: https://github.com/arghyachatterjee/waypoint-based-3d-navigation

## Overview

##### Project Type and Purpose
- This is a full-stack ROS application for ground-based autonomous navigation.
- It provides simulated environments (Gazebo), sensor simulators (Velodyne, vehicle model), perception stacks (scan generation, terrain analysis), localization interface (LOAM), motion planning (local planner), waypoint management, joystick teleop, and visualization tools.
- Users can test in simulation and later deploy to real robots.

##### File Structure
Top‐level ROS packages under src/:
- joystick_drivers – manual teleop
- loam_interface – mapping/localization adapter
- sensor_scan_generation – converts raw scans
- terrain_analysis, terrain_analysis_ext – traversability computation
- local_planner – collision-free motion planning
- vehicle_simulator – full Gazebo world + URDF + plugin
- velodyne_simulator – description + Gazebo plugins
- waypoint_example – automated waypoint publisher
- visualization_tools & waypoint_rviz_plugin – real-time plotting & RViz GUI
Each package has CMakeLists.txt, package.xml, launch files, source code, and often config/data.

##### README
- Confirms that the system leverages simulations, navigation modules (collision avoidance, terrain analysis, waypoint following), and visualization for development and deployment.
- Quick-start shows building with catkin_make, launching the simulator world, and then sending waypoints via RViz or a ROS node.

A. ROS Master
B. Simulation Stack
1. Gazebo worlds (campus, garage, forest, tunnel, indoor, real_robot)
2. vehicle_simulator node
3. velodyne_gazebo_plugins (publishing /velodyne_points)
C. Perception
1. sensor_scan_generation node (subscribes /velodyne_points → publishes sensor scans)
2. terrain_analysis & terrain_analysis_ext nodes (subscribe processed scans → publish traversability maps)
D. Localization
1. loam_interface node (connects to LOAM algorithm → publishes estimated pose)
E. Planning & Control
1. local_planner node (subscribes maps + pose + goal → publishes /cmd_vel)
2. joystick_drivers node (human input → publishes /cmd_vel_override)
F. Waypoint Management
1. waypoint_example node (automated goal generator → publishes /waypoint_goal)
2. waypoint_rviz_plugin (RViz GUI → publishes /waypoint_goal)
G. Visualization
1. visualization_tools node (collects metrics, topics → real-time plots)
2. RViz (renders robot, scan, maps, waypoints)

##### Relationships and Data Flows
– /gazebo/model_states, /odom, /joint_states → vehicle_simulator → odometry topics
– vehicle_simulator + velodyne_gazebo_plugins → /velodyne_points → sensor_scan_generation
– sensor_scan_generation → raw scan topic → terrain_analysis → /traversability_map
– loam_interface → /tf, /odom → pose estimate
– waypoint_example or RViz plugin → /waypoint_goal → local_planner
– local_planner consumes map + pose + goal → outputs /cmd_vel → vehicle_simulator
– joystick_drivers → /cmd_vel_override → vehicle_simulator (or multiplexed with planner)
– visualization_tools subscribes to topics (pose, path, scan, metrics) → plotting GUI
- ROS Master at center as message broker.

##### Architectural Patterns and Principles
- Modularity: each functionality in its own ROS package/node
- Pub/Sub and request/reply (services/actions) for loose coupling
- Separation of concerns: simulation vs perception vs planning vs control vs visualization
- Configuration via YAML, launch files, URDF XACRO for reusability
- Catkin build system for dependency management

##### Technologies, Frameworks, Libraries
- ROS Melodic, Gazebo, RViz
- C++ nodes (src/*.cpp), Python scripts (joy_remap.py, ps3joy.py, realTimePlot.py)
- URDF / XACRO for robot description
- YAML for configuration (ps4joy.yaml, diagnostics.yaml)
- MATLAB script for path generation (.m) in local_planner

## Diagram (Mermaid)

```mermaid
graph TB
    %% Central master
    Master(("ROS Master")):::master

    %% Simulation Stack
    subgraph "Simulation Stack"
        GazeboWorlds["Gazebo Worlds"]:::simulation
        VehicleSimulator["vehicle_simulator Node"]:::simulation
        VelodynePlugins["Velodyne Gazebo Plugins"]:::simulation
        VelodyneDescription["Velodyne Description"]:::simulation
    end

    %% Perception Layer
    subgraph "Perception" 
        SensorScanGen["sensor_scan_generation Node"]:::perception
        TerrainAnalysis["terrain_analysis Node"]:::perception
        TerrainAnalysisExt["terrain_analysis_ext Node"]:::perception
    end

    %% Localization Layer
    subgraph "Localization"
        LoamInterface["loam_interface Node"]:::perception
    end

    %% Planning & Control
    subgraph "Planning & Control"
        LocalPlanner["local_planner Node"]:::planning
        JoystickPS4["joystick_drivers PS4"]:::planning
        JoystickPS3["joystick_drivers PS3"]:::planning
    end

    %% Waypoint Management
    subgraph "Waypoint Management"
        WaypointExample["waypoint_example Node"]:::waypoint
        WaypointPlugin["waypoint_rviz_plugin"]:::waypoint
    end

    %% Visualization
    subgraph "Visualization"
        VisualizationTools["visualization_tools Node"]:::visualization
        RViz["RViz"]:::visualization
    end

    %% Data Flows
    GazeboWorlds --> VehicleSimulator
    VehicleSimulator -->|" /velodyne_points"| VelodynePlugins
    VelodynePlugins --> SensorScanGen
    SensorScanGen -->|" /scan_processed"| TerrainAnalysis
    SensorScanGen -->|" /scan_processed"| TerrainAnalysisExt
    TerrainAnalysis -->|" /traversability_map"| LocalPlanner
    TerrainAnalysisExt -->|" /traversability_map_ext"| LocalPlanner
    LoamInterface -->|" /odom & /tf"| LocalPlanner
    WaypointExample -->|" /waypoint_goal"| LocalPlanner
    WaypointPlugin -->|" /waypoint_goal"| LocalPlanner
    LocalPlanner -->|" /cmd_vel"| VehicleSimulator
    JoystickPS4 -->|" /cmd_vel_override"| VehicleSimulator
    JoystickPS3 -->|" /cmd_vel_override"| VehicleSimulator
    Master --> VehicleSimulator
    Master --> VelodynePlugins
    Master --> SensorScanGen
    Master --> TerrainAnalysis
    Master --> TerrainAnalysisExt
    Master --> LoamInterface
    Master --> LocalPlanner
    Master --> JoystickPS4
    Master --> JoystickPS3
    Master --> WaypointExample
    Master --> WaypointPlugin
    Master --> VisualizationTools
    Master --> RViz
    VisualizationTools --> RViz

    %% Click Events
    click GazeboWorlds "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/vehicle_simulator/world/*.world"
    click VehicleSimulator "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/vehicle_simulator/src/vehicleSimulator.cpp"
    click VelodynePlugins "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/velodyne_simulator/velodyne_gazebo_plugins/src/GazeboRosVelodyneLaser.cpp"
    click VelodyneDescription "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/velodyne_simulator/velodyne_description/urdf/*.xacro"
    click SensorScanGen "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/sensor_scan_generation/src/sensorScanGeneration.cpp"
    click TerrainAnalysis "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/terrain_analysis/src/terrainAnalysis.cpp"
    click TerrainAnalysisExt "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/terrain_analysis_ext/src/terrainAnalysisExt.cpp"
    click LoamInterface "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/loam_interface/src/loamInterface.cpp"
    click LocalPlanner "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/local_planner/src/localPlanner.cpp"
    click JoystickPS4 "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/joystick_drivers/joy/scripts/joy_remap.py"
    click JoystickPS3 "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/joystick_drivers/ps3joy/scripts/ps3joy.py"
    click WaypointExample "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/waypoint_example/src/waypointExample.cpp"
    click WaypointPlugin "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/waypoint_rviz_plugin/src/waypoint_tool.cpp"
    click VisualizationTools "https://github.com/arghyachatterjee/waypoint-based-3d-navigation/blob/main/src/visualization_tools/src/visualizationTools.cpp"

    %% Styles
    classDef simulation fill:#add8e6,stroke:#000
    classDef perception fill:#90ee90,stroke:#000
    classDef planning fill:#f4a460,stroke:#000
    classDef waypoint fill:#d3d3f3,stroke:#000
    classDef visualization fill:#dda0dd,stroke:#000
    classDef master fill:#ffffe0,stroke:#000,stroke-dasharray: 5 5
    classDef external fill:#ffffff,stroke:#000,stroke-dasharray: 2 2
```
