# chetankandya/ai-robotics architecture

> Architecture diagram of the GitHub repository chetankandya/ai-robotics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chetankandya/ai-robotics
- Repository: https://github.com/chetankandya/ai-robotics

## Overview

This repository is a ROS AI-robotics course project. Its highlighted product workflow compares three reactive obstacle-avoidance approaches: fixed-window control, tabular reinforcement learning, and deep reinforcement learning. Sensors and ROS topics/services provide observations and motion commands; learning approaches also train policies. The tree additionally contains earlier occupancy-map and motion-planning work, a TST task executor, and PID tuning tools. Relationships for sampled code are shown where source demonstrates them; lab 4 pairings are documented in the README, while unsampled runtime wiring is omitted.

Main entry points: [`catkin_ws/src/air_labs/air_lab3/src/tst_executor.py`](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab3/src/tst_executor.py) (TST service), [`catkin_ws/src/air_labs/air_lab4/src/q_explore.py`](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/q_explore.py) (Q-learning trainer), [`catkin_ws/src/air_labs/air_lab2/src/ls_to_occ.cpp`](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/src/ls_to_occ.cpp) (Occupancy mapping), [`catkin_ws/src/air_labs/air_lab2/include/air_lab2/motion_planner_interface.h`](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/include/air_lab2/motion_planner_interface.h) (Planner interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mapping["Mapping and planning"]
  node_map_builder["Occupancy mapping<br/>[ls_to_occ.cpp]"]
  node_occ_grid[("Occupancy grid<br/>[occ.h]")]
  node_planner["Motion planner<br/>[motion_planner.cpp]"]
  node_planner_interface["Planner interface"]
  node_validity["State validity"]
  node_fit_query["Geometric fitting<br/>[GteApprQuery.h]"]
end

subgraph group_tasks["Task execution"]
  node_tst_service["TST service<br/>[tst_executor.py]"]
  node_drive_exec["Drive executor"]
  node_explore_exec["Explore executor"]
  node_record_exec["Record executor<br/>[record_executor.py]"]
  node_semantic_recorder["Semantic recorder"]
end

subgraph group_avoidance["Obstacle avoidance"]
  node_fixed_policy["Fixed-window policy<br/>[fixed_window.py]"]
  node_fixed_runner["Fixed-window navigation<br/>[move_to_goal.py]"]
  node_controller["Robot controller<br/>[controller.py]"]
end

subgraph group_learning["Policy learning"]
  node_q_policy["Q-learning policy<br/>[QLearn.py]"]
  node_q_trainer["Q-learning trainer<br/>[q_explore.py]"]
  node_q_runner["Q-table navigation<br/>[move_to_goal_ql.py]"]
  node_dqn_policy["Deep Q-network<br/>[dqn.py]"]
  node_dqn_trainer["DQN trainer<br/>[dqn_learn.py]"]
end

subgraph group_tuning["Controller tuning"]
  node_autotuner["PID autotuner<br/>[autotune.py]"]
  node_evaluator["Controller evaluator"]
end

node_robot(("Robot and sensors"))

node_robot -->|"sends scans"| node_map_builder
node_map_builder -->|"updates grid"| node_occ_grid
node_planner -->|"requests paths"| node_planner_interface
node_planner_interface -->|"checks states"| node_validity
node_tst_service -->|"registers executor"| node_drive_exec
node_tst_service -->|"registers executor"| node_explore_exec
node_tst_service -->|"registers executor"| node_record_exec
node_drive_exec -->|"publishes goals"| node_robot
node_explore_exec -->|"publishes waypoints"| node_robot
node_fixed_runner -.->|"uses approach"| node_fixed_policy
node_q_trainer -->|"trains policy"| node_q_policy
node_q_runner -.->|"uses Q table"| node_q_policy
node_dqn_trainer -->|"trains network"| node_dqn_policy
node_q_trainer -->|"publishes actions"| node_robot
node_controller -.->|"controls motion"| node_robot
node_semantic_recorder -.->|"records semantics"| node_robot
node_autotuner -->|"reads statistics"| node_evaluator
node_evaluator -->|"measures motion error"| node_robot

click node_map_builder "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/src/ls_to_occ.cpp"
click node_occ_grid "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/include/air_lab2/occ.h"
click node_planner "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/src/motion_planner.cpp"
click node_planner_interface "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/include/air_lab2/motion_planner_interface.h"
click node_validity "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/include/air_lab2/state_validity_checker.h"
click node_fit_query "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/include/air_lab2/Mathematics/GteApprQuery.h"
click node_tst_service "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab3/src/tst_executor.py"
click node_drive_exec "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab3/src/drive_to_executor.py"
click node_explore_exec "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab3/src/explore_executor.py"
click node_record_exec "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab3/src/record_executor.py"
click node_fixed_policy "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/fixed_window.py"
click node_fixed_runner "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/move_to_goal.py"
click node_q_policy "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/QLearn.py"
click node_q_trainer "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/q_explore.py"
click node_q_runner "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/move_to_goal_ql.py"
click node_dqn_policy "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/dqn.py"
click node_dqn_trainer "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/dqn_learn.py"
click node_controller "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/controller.py"
click node_semantic_recorder "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/record_semantic_executor.py"
click node_autotuner "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab1/src/autotune.py"
click node_evaluator "https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab1/src/evaluate_controller.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_map_builder,node_occ_grid,node_planner,node_planner_interface,node_validity,node_fit_query toneBlue
class node_tst_service,node_drive_exec,node_explore_exec,node_record_exec,node_semantic_recorder toneAmber
class node_fixed_policy,node_fixed_runner,node_controller toneMint
class node_q_policy,node_q_trainer,node_q_runner,node_dqn_policy,node_dqn_trainer toneRose
class node_autotuner,node_evaluator,node_robot toneIndigo
```

## Components

### Mapping and planning

- [Occupancy mapping](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/src/ls_to_occ.cpp): `catkin_ws/src/air_labs/air_lab2/src/ls_to_occ.cpp`
- [Occupancy grid](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/include/air_lab2/occ.h): `catkin_ws/src/air_labs/air_lab2/include/air_lab2/occ.h`
- [Motion planner](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/src/motion_planner.cpp): `catkin_ws/src/air_labs/air_lab2/src/motion_planner.cpp`
- [Planner interface](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/include/air_lab2/motion_planner_interface.h): `catkin_ws/src/air_labs/air_lab2/include/air_lab2/motion_planner_interface.h`
- [State validity](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/include/air_lab2/state_validity_checker.h): `catkin_ws/src/air_labs/air_lab2/include/air_lab2/state_validity_checker.h`
- [Geometric fitting](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab2/include/air_lab2/Mathematics/GteApprQuery.h): `catkin_ws/src/air_labs/air_lab2/include/air_lab2/Mathematics/GteApprQuery.h`

### Task execution

- [TST service](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab3/src/tst_executor.py): `catkin_ws/src/air_labs/air_lab3/src/tst_executor.py`
- [Drive executor](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab3/src/drive_to_executor.py): `catkin_ws/src/air_labs/air_lab3/src/drive_to_executor.py`
- [Explore executor](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab3/src/explore_executor.py): `catkin_ws/src/air_labs/air_lab3/src/explore_executor.py`
- [Record executor](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab3/src/record_executor.py): `catkin_ws/src/air_labs/air_lab3/src/record_executor.py`
- [Semantic recorder](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/record_semantic_executor.py): `catkin_ws/src/air_labs/air_lab4/src/record_semantic_executor.py`

### Obstacle avoidance

- [Fixed-window policy](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/fixed_window.py): `catkin_ws/src/air_labs/air_lab4/src/fixed_window.py`
- [Fixed-window navigation](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/move_to_goal.py): `catkin_ws/src/air_labs/air_lab4/src/move_to_goal.py`
- [Robot controller](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/controller.py): `catkin_ws/src/air_labs/air_lab4/src/controller.py`

### Policy learning

- [Q-learning policy](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/QLearn.py): `catkin_ws/src/air_labs/air_lab4/src/QLearn.py`
- [Q-learning trainer](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/q_explore.py): `catkin_ws/src/air_labs/air_lab4/src/q_explore.py`
- [Q-table navigation](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/move_to_goal_ql.py): `catkin_ws/src/air_labs/air_lab4/src/move_to_goal_ql.py`
- [Deep Q-network](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/dqn.py): `catkin_ws/src/air_labs/air_lab4/src/dqn.py`
- [DQN trainer](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab4/src/dqn_learn.py): `catkin_ws/src/air_labs/air_lab4/src/dqn_learn.py`

### Controller tuning

- [PID autotuner](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab1/src/autotune.py): `catkin_ws/src/air_labs/air_lab1/src/autotune.py`
- [Controller evaluator](https://github.com/chetankandya/ai-robotics/blob/master/catkin_ws/src/air_labs/air_lab1/src/evaluate_controller.py): `catkin_ws/src/air_labs/air_lab1/src/evaluate_controller.py`

### Other components

- **Robot and sensors**

## Connections

- Robot and sensors → Occupancy mapping: sends scans (evidence: `catkin_ws/src/air_labs/air_lab2/src/ls_to_occ.cpp`)
- Occupancy mapping → Occupancy grid: updates grid (evidence: `catkin_ws/src/air_labs/air_lab2/src/ls_to_occ.cpp`)
- Motion planner → Planner interface: requests paths (evidence: `catkin_ws/src/air_labs/air_lab2/src/motion_planner.cpp`)
- Planner interface → State validity: checks states (evidence: `catkin_ws/src/air_labs/air_lab2/include/air_lab2/motion_planner_interface.h`)
- TST service → Drive executor: registers executor (evidence: `catkin_ws/src/air_labs/air_lab3/src/tst_executor.py`)
- TST service → Explore executor: registers executor (evidence: `catkin_ws/src/air_labs/air_lab3/src/tst_executor.py`)
- TST service → Record executor: registers executor (evidence: `catkin_ws/src/air_labs/air_lab3/src/tst_executor.py`)
- Drive executor → Robot and sensors: publishes goals (evidence: `catkin_ws/src/air_labs/air_lab3/src/drive_to_executor.py`)
- Explore executor → Robot and sensors: publishes waypoints (evidence: `catkin_ws/src/air_labs/air_lab3/src/explore_executor.py`)
- Fixed-window navigation → Fixed-window policy: uses approach
- Q-learning trainer → Q-learning policy: trains policy (evidence: `catkin_ws/src/air_labs/air_lab4/src/q_explore.py`)
- Q-table navigation → Q-learning policy: uses Q table
- DQN trainer → Deep Q-network: trains network (evidence: `catkin_ws/src/air_labs/air_lab4/src/dqn_learn.py`)
- Q-learning trainer → Robot and sensors: publishes actions (evidence: `catkin_ws/src/air_labs/air_lab4/src/q_explore.py`)
- Robot controller → Robot and sensors: controls motion
- Semantic recorder → Robot and sensors: records semantics
- PID autotuner → Controller evaluator: reads statistics (evidence: `catkin_ws/src/air_labs/air_lab1/src/autotune.py`)
- Controller evaluator → Robot and sensors: measures motion error (evidence: `catkin_ws/src/air_labs/air_lab1/src/evaluate_controller.py`)
