# nitin3560/uav-trajectory-tracking architecture

> Architecture diagram of the GitHub repository nitin3560/uav-trajectory-tracking, 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/nitin3560/uav-trajectory-tracking
- Repository: https://github.com/nitin3560/uav-trajectory-tracking

## Overview

This repository is a UAV trajectory-tracking controller comparison study. Its main workflow runs a seeded simulation, applies trajectories and fault/disturbance scenarios, executes a selected controller, and evaluates tracking and recovery. The README also describes batch comparisons, per-seed telemetry, plots, and summary metrics. The graph emphasizes the primary `src/` runtime; review-bundle and legacy controller copies are retained as distinct code where identified by the source index. Some links are documented or index-supported rather than verified from complete runtime excerpts.

Main entry points: [`src/run_one.py`](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/run_one.py) (Seeded simulation), [`src/control_core/pid_core.py`](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/control_core/pid_core.py) (PID core), [`src/controllers/pid.py`](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/pid.py) (PID controller), [`src/controllers/pid_agentic.py`](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/pid_agentic.py) (Agentic PID hybrid)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation inputs"]
  node_runner["Seeded simulation<br/>[run_one.py]"]
  node_environment["Drone environment<br/>[env_factory.py]"]
  node_trajectories["Trajectory definitions<br/>[trajectories.py]"]
  node_faults["Fault injection<br/>[fault_injector.py]"]
  node_disturbances["Wind and failures<br/>[disturbances.py]"]
end

subgraph group_control["Control strategies"]
  node_openloop["Open-loop controller<br/>[openloop.py]"]
  node_pid["PID controller<br/>[pid.py]"]
  node_agentic["Agentic PID hybrid<br/>[pid_agentic.py]"]
  node_supervisor["PID supervisor"]
  node_pidcore["PID core<br/>[pid_core.py]"]
end

subgraph group_evaluation["Evaluation outputs"]
  node_metrics["Tracking metrics<br/>[metrics.py]"]
  node_evaluation["CSV evaluation<br/>[evaluate_csv.py]"]
  node_telemetry["Per-seed telemetry<br/>[run_one.py]"]
end

subgraph group_alternates["Alternate implementations"]
  node_legacytracker["Legacy PID tracker<br/>[pid_tracker.py]"]
  node_reviewpid["Review PID hybrid<br/>[pid_agentic.py]"]
  node_casestudypid["Case-study PID hybrid<br/>[pid_agentic.py]"]
  node_casereviewpid["Case-study review hybrid<br/>[pid_agentic.py]"]
end

node_engineer(("Study runner"))

node_engineer -->|"runs"| node_runner
node_runner -->|"creates"| node_environment
node_runner -->|"uses"| node_trajectories
node_runner -->|"uses"| node_faults
node_runner -->|"uses"| node_disturbances
node_runner -->|"dispatches"| node_openloop
node_runner -->|"dispatches"| node_pid
node_runner -->|"dispatches"| node_agentic
node_runner -->|"consults"| node_supervisor
node_agentic -->|"uses"| node_pidcore
node_pid -->|"uses"| node_pidcore
node_runner -->|"computes"| node_metrics
node_runner -->|"writes"| node_telemetry
node_telemetry -.->|"evaluated by"| node_evaluation
node_runner -.->|"available via"| node_legacytracker
node_reviewpid -->|"uses"| node_pidcore
node_casestudypid -->|"uses"| node_pidcore
node_casereviewpid -->|"uses"| node_pidcore

click node_runner "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/run_one.py"
click node_environment "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/env_factory.py"
click node_trajectories "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/trajectories.py"
click node_faults "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/faults/fault_injector.py"
click node_disturbances "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/disturbances.py"
click node_openloop "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/openloop.py"
click node_pid "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/pid.py"
click node_agentic "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/pid_agentic.py"
click node_supervisor "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/agentic_supervisor.py"
click node_pidcore "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/control_core/pid_core.py"
click node_legacytracker "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/legacy/pid_tracker.py"
click node_metrics "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/metrics.py"
click node_evaluation "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/eval/evaluate_csv.py"
click node_telemetry "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/run_one.py"
click node_reviewpid "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/review_bundle/controllers/pid_agentic.py"
click node_casestudypid "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/case%20study1/src/controllers/pid_agentic.py"
click node_casereviewpid "https://github.com/nitin3560/uav-trajectory-tracking/blob/main/case%20study1/review_bundle/controllers/pid_agentic.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_runner,node_environment,node_trajectories,node_faults,node_disturbances toneBlue
class node_openloop,node_pid,node_agentic,node_supervisor,node_pidcore toneAmber
class node_metrics,node_evaluation,node_telemetry toneMint
class node_legacytracker,node_reviewpid,node_casestudypid,node_casereviewpid toneRose
class node_engineer toneIndigo
```

## Components

### Simulation inputs

- [Seeded simulation](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/run_one.py): `src/run_one.py`
- [Drone environment](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/env_factory.py): `src/env_factory.py`
- [Trajectory definitions](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/trajectories.py): `src/trajectories.py`
- [Fault injection](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/faults/fault_injector.py): `src/faults/fault_injector.py`
- [Wind and failures](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/disturbances.py): `src/disturbances.py`

### Control strategies

- [Open-loop controller](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/openloop.py): `src/controllers/openloop.py`
- [PID controller](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/pid.py): `src/controllers/pid.py`
- [Agentic PID hybrid](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/pid_agentic.py): `src/controllers/pid_agentic.py`
- [PID supervisor](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/agentic_supervisor.py): `src/controllers/agentic_supervisor.py`
- [PID core](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/control_core/pid_core.py): `src/control_core/pid_core.py`

### Evaluation outputs

- [Tracking metrics](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/metrics.py): `src/metrics.py`
- [CSV evaluation](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/eval/evaluate_csv.py): `src/eval/evaluate_csv.py`
- [Per-seed telemetry](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/run_one.py): `src/run_one.py`

### Alternate implementations

- [Legacy PID tracker](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/src/controllers/legacy/pid_tracker.py): `src/controllers/legacy/pid_tracker.py`
- [Review PID hybrid](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/review_bundle/controllers/pid_agentic.py): `review_bundle/controllers/pid_agentic.py`
- [Case-study PID hybrid](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/case%20study1/src/controllers/pid_agentic.py): `case study1/src/controllers/pid_agentic.py`
- [Case-study review hybrid](https://github.com/nitin3560/uav-trajectory-tracking/blob/main/case%20study1/review_bundle/controllers/pid_agentic.py): `case study1/review_bundle/controllers/pid_agentic.py`

### Other components

- **Study runner**

## Connections

- Study runner → Seeded simulation: runs (evidence: `README.md`)
- Seeded simulation → Drone environment: creates (evidence: `src/run_one.py`)
- Seeded simulation → Trajectory definitions: uses (evidence: `src/run_one.py`)
- Seeded simulation → Fault injection: uses (evidence: `src/run_one.py`)
- Seeded simulation → Wind and failures: uses (evidence: `src/run_one.py`)
- Seeded simulation → Open-loop controller: dispatches (evidence: `src/run_one.py`)
- Seeded simulation → PID controller: dispatches (evidence: `src/run_one.py`)
- Seeded simulation → Agentic PID hybrid: dispatches (evidence: `src/run_one.py`)
- Seeded simulation → PID supervisor: consults (evidence: `src/run_one.py`)
- Agentic PID hybrid → PID core: uses (evidence: `src/controllers/pid_agentic.py`)
- PID controller → PID core: uses (evidence: `src/controllers/pid.py`)
- Seeded simulation → Tracking metrics: computes (evidence: `src/run_one.py`)
- Seeded simulation → Per-seed telemetry: writes (evidence: `README.md`)
- Per-seed telemetry → CSV evaluation: evaluated by (evidence: `README.md`)
- Seeded simulation → Legacy PID tracker: available via
- Review PID hybrid → PID core: uses (evidence: `review_bundle/controllers/pid_agentic.py`)
- Case-study PID hybrid → PID core: uses (evidence: `case study1/src/controllers/pid_agentic.py`)
- Case-study review hybrid → PID core: uses (evidence: `case study1/review_bundle/controllers/pid_agentic.py`)
