# brian-lim-tze-zhen/turtlebot4-social-navigation architecture

> Architecture diagram of the GitHub repository brian-lim-tze-zhen/turtlebot4-social-navigation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brian-lim-tze-zhen/turtlebot4-social-navigation
- Repository: https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation

## Overview

This repository implements ROS 2 social navigation for TurtleBot4: detect people, estimate their motion and social formations, represent those as costmap inputs, and let Nav2 plan and control around them. The README also documents a conversation-zone ablation and bag-based evaluation. The graph retains those branches alongside the main simulation workflow. Several runtime links are documented in the README; unsampled implementations are represented only where their paths or capabilities are supported by the tree and documentation.

Main entry points: [`ros2_ws/launch/social_perception.launch.py`](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/launch/social_perception.launch.py) (Scenario Launch), [`ros2_ws/src/social_perception/social_perception/human_kf_predictor.py`](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/human_kf_predictor.py) (Motion Predictor), [`ros2_ws/src/social_critic/src/social_critic.cpp`](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_critic/src/social_critic.cpp) (SocialCritic), [`ros2_ws/src/social_perception/social_perception/group_formation_detector.py`](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/group_formation_detector.py) (Group Formation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sim["Simulation and Launch"]
  node_gazebo["Gazebo Simulation"]
  node_turtlebot["TurtleBot4 Nav2"]
  node_launchstack["Scenario Launch"]
end

subgraph group_perception["Human Perception"]
  node_yolo["YOLO ByteTrack<br/>[yolo_detector.py]"]
  node_lidar["Lidar Detection"]
  node_fusion["Identity Fusion"]
  node_predictor["Motion Predictor"]
end

subgraph group_social["Social Representation"]
  node_formation["Group Formation"]
  node_groupcloud["Group Cloud"]
  node_personcloud["Predicted Person Cloud"]
  node_zone["Conversation Zone"]
end

subgraph group_navigation["Navigation"]
  node_socialcritic["SocialCritic<br/>[social_critic.cpp]"]
  node_criticstate["Critic State Model<br/>[social_critic.hpp]"]
  node_costmap["Nav2 Costmaps"]
end

subgraph group_evaluation["Bag Evaluation"]
  node_avoidance["Avoidance Metrics"]
  node_inspect["Run Inspector<br/>[inspect_run.py]"]
  node_predictioneval["Prediction Evaluation"]
end

node_operator(("Operator"))
node_bags[("Recorded Bags")]

node_operator -->|"launches scenario"| node_launchstack
node_launchstack -->|"starts simulation"| node_gazebo
node_launchstack -->|"starts Nav2"| node_turtlebot
node_launchstack -->|"starts perception"| node_yolo
node_launchstack -->|"starts predictor"| node_predictor
node_yolo -->|"provides detections"| node_predictor
node_lidar -->|"provides tracks"| node_fusion
node_predictor -->|"publishes predictions"| node_personcloud
node_formation -->|"publishes group data"| node_groupcloud
node_personcloud -->|"feeds local costmap"| node_costmap
node_groupcloud -->|"adds group layer"| node_costmap
node_formation -.->|"classifies groups"| node_zone
node_zone -->|"publishes global mask"| node_costmap
node_formation -->|"publishes group state"| node_socialcritic
node_predictor -->|"publishes person state"| node_socialcritic
node_socialcritic -->|"uses state model"| node_criticstate
node_socialcritic -.->|"scores trajectories"| node_turtlebot
node_operator -->|"sets goal"| node_turtlebot
node_turtlebot -.->|"records run"| node_bags
node_bags -->|"analyzes trials"| node_avoidance
node_bags -->|"inspects run"| node_inspect
node_inspect -->|"reuses metrics"| node_avoidance
node_bags -.->|"evaluates prediction"| node_predictioneval

click node_launchstack "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/launch/social_perception.launch.py"
click node_yolo "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/yolo_detector.py"
click node_lidar "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/Lidar/lidar_person_detector.py"
click node_fusion "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/Lidar/identity_fusion_node_lidar.py"
click node_predictor "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/human_kf_predictor.py"
click node_formation "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/group_formation_detector.py"
click node_groupcloud "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/social_group_cloud_node.py"
click node_personcloud "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/predicted_person_cloud_node.py"
click node_zone "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/camera_lidar/social_zone_costmap_node_sim.py"
click node_socialcritic "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_critic/src/social_critic.cpp"
click node_criticstate "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_critic/include/social_critic/social_critic.hpp"
click node_avoidance "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/analysis/analyse_avoidance.py"
click node_inspect "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/analysis/inspect_run.py"
click node_predictioneval "https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/analysis/evaluate_prediction_accuracy.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gazebo,node_turtlebot,node_launchstack toneBlue
class node_yolo,node_lidar,node_fusion,node_predictor,node_bags toneAmber
class node_formation,node_groupcloud,node_personcloud,node_zone toneMint
class node_socialcritic,node_criticstate,node_costmap toneRose
class node_avoidance,node_inspect,node_predictioneval,node_operator toneIndigo
```

## Components

### Simulation and Launch

- **Gazebo Simulation**
- **TurtleBot4 Nav2**
- [Scenario Launch](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/launch/social_perception.launch.py): `ros2_ws/launch/social_perception.launch.py`

### Human Perception

- [YOLO ByteTrack](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/yolo_detector.py): `ros2_ws/src/social_perception/social_perception/yolo_detector.py`
- [Lidar Detection](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/Lidar/lidar_person_detector.py): `ros2_ws/src/social_perception/social_perception/Lidar/lidar_person_detector.py`
- [Identity Fusion](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/Lidar/identity_fusion_node_lidar.py): `ros2_ws/src/social_perception/social_perception/Lidar/identity_fusion_node_lidar.py`
- [Motion Predictor](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/human_kf_predictor.py): `ros2_ws/src/social_perception/social_perception/human_kf_predictor.py`

### Social Representation

- [Group Formation](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/group_formation_detector.py): `ros2_ws/src/social_perception/social_perception/group_formation_detector.py`
- [Group Cloud](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/social_group_cloud_node.py): `ros2_ws/src/social_perception/social_perception/social_group_cloud_node.py`
- [Predicted Person Cloud](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/predicted_person_cloud_node.py): `ros2_ws/src/social_perception/social_perception/predicted_person_cloud_node.py`
- [Conversation Zone](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_perception/social_perception/camera_lidar/social_zone_costmap_node_sim.py): `ros2_ws/src/social_perception/social_perception/camera_lidar/social_zone_costmap_node_sim.py`

### Navigation

- [SocialCritic](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_critic/src/social_critic.cpp): `ros2_ws/src/social_critic/src/social_critic.cpp`
- [Critic State Model](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/src/social_critic/include/social_critic/social_critic.hpp): `ros2_ws/src/social_critic/include/social_critic/social_critic.hpp`
- **Nav2 Costmaps**

### Bag Evaluation

- [Avoidance Metrics](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/analysis/analyse_avoidance.py): `ros2_ws/analysis/analyse_avoidance.py`
- [Run Inspector](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/analysis/inspect_run.py): `ros2_ws/analysis/inspect_run.py`
- [Prediction Evaluation](https://github.com/brian-lim-tze-zhen/turtlebot4-social-navigation/blob/main/ros2_ws/analysis/evaluate_prediction_accuracy.py): `ros2_ws/analysis/evaluate_prediction_accuracy.py`

### Other components

- **Operator**
- **Recorded Bags**

## Connections

- Operator → Scenario Launch: launches scenario
- Scenario Launch → Gazebo Simulation: starts simulation
- Scenario Launch → TurtleBot4 Nav2: starts Nav2
- Scenario Launch → YOLO ByteTrack: starts perception (evidence: `ros2_ws/launch/social_perception.launch.py`)
- Scenario Launch → Motion Predictor: starts predictor (evidence: `ros2_ws/launch/social_perception.launch.py`)
- YOLO ByteTrack → Motion Predictor: provides detections
- Lidar Detection → Identity Fusion: provides tracks (evidence: `ros2_ws/src/social_perception/social_perception/Lidar/identity_fusion_node_lidar.py`)
- Motion Predictor → Predicted Person Cloud: publishes predictions
- Group Formation → Group Cloud: publishes group data (evidence: `ros2_ws/src/social_perception/social_perception/group_formation_detector.py`)
- Predicted Person Cloud → Nav2 Costmaps: feeds local costmap
- Group Cloud → Nav2 Costmaps: adds group layer
- Group Formation → Conversation Zone: classifies groups
- Conversation Zone → Nav2 Costmaps: publishes global mask
- Group Formation → SocialCritic: publishes group state (evidence: `ros2_ws/src/social_critic/src/social_critic.cpp`)
- Motion Predictor → SocialCritic: publishes person state (evidence: `ros2_ws/src/social_critic/src/social_critic.cpp`)
- SocialCritic → Critic State Model: uses state model (evidence: `ros2_ws/src/social_critic/src/social_critic.cpp`)
- SocialCritic → TurtleBot4 Nav2: scores trajectories
- Operator → TurtleBot4 Nav2: sets goal
- TurtleBot4 Nav2 → Recorded Bags: records run
- Recorded Bags → Avoidance Metrics: analyzes trials (evidence: `ros2_ws/analysis/analyse_avoidance.py`)
- Recorded Bags → Run Inspector: inspects run (evidence: `ros2_ws/analysis/inspect_run.py`)
- Run Inspector → Avoidance Metrics: reuses metrics (evidence: `ros2_ws/analysis/inspect_run.py`)
- Recorded Bags → Prediction Evaluation: evaluates prediction
