How brian-lim-tze-zhen/turtlebot4-social-navigation works
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: social_perception.launch.py Scenario Launch · human_kf_predictor.py Motion Predictor · social_critic.cpp SocialCritic · group_formation_detector.py Group Formation
Components 19
Simulation and Launch
- Gazebo Simulation
- TurtleBot4 Nav2
- Scenario Launch
ros2_ws/launch/social_perception.launch.py
Human Perception
- YOLO ByteTrack
ros2_ws/src/social_perception/social_perception/yolo_detector.py - Lidar Detection
ros2_ws/src/social_perception/social_perception/Lidar/lidar_person_detector.py - Identity Fusion
ros2_ws/src/social_perception/social_perception/Lidar/identity_fusion_node_lidar.py - Motion Predictor
ros2_ws/src/social_perception/social_perception/human_kf_predictor.py
Social Representation
- Group Formation
ros2_ws/src/social_perception/social_perception/group_formation_detector.py - Group Cloud
ros2_ws/src/social_perception/social_perception/social_group_cloud_node.py - Predicted Person Cloud
ros2_ws/src/social_perception/social_perception/predicted_person_cloud_node.py - Conversation Zone
ros2_ws/src/social_perception/social_perception/camera_lidar/social_zone_costmap_node_sim.py
Navigation
- SocialCritic
ros2_ws/src/social_critic/src/social_critic.cpp - Critic State Model
ros2_ws/src/social_critic/include/social_critic/social_critic.hpp - Nav2 Costmaps
Bag Evaluation
- Avoidance Metrics
ros2_ws/analysis/analyse_avoidance.py - Run Inspector
ros2_ws/analysis/inspect_run.py - Prediction Evaluation
ros2_ws/analysis/evaluate_prediction_accuracy.py
Other components
- Operator
- Recorded Bags
Connections 23
- Operator → Scenario Launch: launches scenario
- Scenario Launch → Gazebo Simulation: starts simulation
- Scenario Launch → TurtleBot4 Nav2: starts Nav2
- Scenario Launch → YOLO ByteTrack: starts perception
ros2_ws/launch/social_perception.launch.py - Scenario Launch → Motion Predictor: starts predictor
ros2_ws/launch/social_perception.launch.py - YOLO ByteTrack → Motion Predictor: provides detections
- Lidar Detection → Identity Fusion: provides tracks
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
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
ros2_ws/src/social_critic/src/social_critic.cpp - Motion Predictor → SocialCritic: publishes person state
ros2_ws/src/social_critic/src/social_critic.cpp - SocialCritic → Critic State Model: uses state model
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
ros2_ws/analysis/analyse_avoidance.py - Recorded Bags → Run Inspector: inspects run
ros2_ws/analysis/inspect_run.py - Run Inspector → Avoidance Metrics: reuses metrics
ros2_ws/analysis/inspect_run.py - Recorded Bags → Prediction Evaluation: evaluates prediction