# pbhatt0022/vision-follow-project architecture

> Architecture diagram of the GitHub repository pbhatt0022/vision-follow-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pbhatt0022/vision-follow-project
- Repository: https://github.com/pbhatt0022/vision-follow-project

## Overview

From the README + file tree, this is a **single-machine, real-time vision-to-control pipeline** written in **Python 3.11**. It:

- Captures frames from a **webcam** (`capture/`)
- Runs **YOLO-based person detection/tracking** (`perception/`)
- Computes **horizontal centroid error** (target center vs frame center)
- Converts error → **control signal** via **PID** (`control/`)
- Logs telemetry to disk (`outputs/logs/centroid_log.csv`)
- Runs an **offline PID replay/analysis** that versions experiments under `outputs/experiments/<timestamp>/`

It’s not yet an IoT robot system in this repo; it’s the **vision + control logic core** that is *designed* to integrate into a robot later.

1) **Online / real-time loop** (webcam → YOLO → error → (future live PID) → actuator integration)
##### Offline experiment pipeline (centroid_log.csv → PID sim → plots/artifacts)

Use the package boundaries under `src/vision_follow/` as your primary component boundaries:

##### (device I/O)
- **`src/vision_follow/capture/test_camera.py`**
- Entry point to validate camera access
- Responsibilities: open webcam, read frames, basic display/verification (likely OpenCV)

##### Perception (ML inference + tracking + telemetry)
- **`src/vision_follow/perception/yolo_detect.py`**
- YOLO inference / detection
- **`src/vision_follow/perception/yolo_track.py`**
- Main real-time script: camera loop + detect/track + compute error + optional logging

- `Perception: YOLO Detector (PyTorch/Ultralytics)`
- `Perception: Tracker + Centroid Error Calculator`

##### Control (PID + follow logic)
- **`src/vision_follow/control/pid_controller.py`**
- Core PID implementation (Kp/Ki/Kd, dt, clamps, etc.)
- **`src/vision_follow/control/follow_logic.py`**
- Higher-level follow behavior (how PID output maps to “turn left/right/stop”, etc.)
- **`src/vision_follow/control/pid_from_log.py`**
- Offline replay: reads log, runs PID, generates plots + experiment folder

- `Control: PID Controller`
- `Control: Follow Logic (decision/mapping layer)`
- `Offline Analysis: PID Replay + Plot Generator`

##### Data/artifacts (filesystem as a first-class “store”)
Even though there’s no database, the filesystem is central to reproducibility:
- `outputs/logs/centroid_log.csv`
- `outputs/experiments/<timestamp>/{plots, run_config, copied log}`

##### Model assets (local weights)
The README mentions `models/` (not present in the tree, but conceptually important).
- YOLO weights file(s) loaded by perception

##### Environment / runtime platform (deployment boundary)
The runtime is the developer machine:
- CPU or optional NVIDIA GPU (CUDA via PyTorch)
- Windows/Linux
- Python venv + `requirements*.txt`

##### Webcam → `Capture`
- Payload: `Frame (H×W×3)`
##### `Capture` → `Perception: YOLO Detector`
- Payload: `Frame`
##### `YOLO Detector` → `Tracker + Centroid Error Calculator`
- Payload: `Detections/track state (bbox, id, confidence)`
##### `Tracker + Error Calc` → `Control (future live PID)`
- Payload: `error_x (pixels or normalized)`
##### `Tracker + Error Calc` → `Telemetry Logger` → `outputs/logs/centroid_log.csv`
- Payload: timestamped `error_x` samples
- Payload: `turn_rate / angular_velocity / command`

**Important nuance for accuracy:** today, the repo clearly logs error and does offline PID; the live PID overlay/control is listed as “Next”. So either:

##### `pid_from_log.py` → `outputs/experiments/<timestamp>/`
- Artifacts: `error_plot.png`, `turn_plot.png`, `run_config.txt`, copied `centroid_log.csv`

This offline pipeline is a distinct “batch job” and should be visually separated from the real-time loop.

This repo is structured as a **pipeline with clean separation of concerns**:

- **I/O boundary**: webcam capture isolated under `capture/`
- **Compute/ML boundary**: inference + tracking isolated under `perception/`
- **Control boundary**: PID + behavior mapping isolated under `control/`
- **Reproducibility boundary**: outputs are versioned, logs are persisted, lockfile exists

**Purpose:** show who/what interacts with the system.
- Actor: `User/Developer`
- External systems: `Webcam Device`, optional `NVIDIA GPU`, optional future `Robot Platform`
- System: `Vision Follow (this repo)`

**Purpose:** show runtime blocks on the host machine.
Inside `Host Machine` boundary:
- `Python App (vision_follow)`
- `PyTorch/Ultralytics YOLO`
- `OpenCV`
- `Local Filesystem (outputs/, models/)`

- Webcam → Python App
- Python App ↔ GPU (optional acceleration)
- Python App ↔ Filesystem (logs, experiments, weights)

**Purpose:** match the file tree 1:1 to components and entrypoints.
Components:
- `capture/test_camera.py` (entrypoint)
- `perception/yolo_track.py` (entrypoint)
- `perception/yolo_detect.py` (module)
- `control/pid_from_log.py` (entrypoint)
- `control/pid_controller.py` (module)
- `control/follow_logic.py` (module)

Show:
- which scripts call which modules
- data artifacts produced/consumed

Labels because they’re core to understanding:

- **Frame source**: “Webcam (camera-index N)”
- **Inference engine**: “YOLO (PyTorch; CPU/GPU)”
- **Key computed signal**: “Centroid horizontal error (px or normalized)”
- **Telemetry format**: “CSV log: outputs/logs/centroid_log.csv”
- **Experiment versioning**: “outputs/experiments/<timestamp>/”
- **Control output meaning**: “turn command / angular velocity (PID output)”

- Don’t imply distributed services; everything runs locally in-process today.
- **two entrypoints** clearly:
- `yolo_track.py` for online tracking/logging
- `pid_from_log.py` for offline replay/plots
- Treat “robot actuation” and “owner face recognition” as **external / future** unless you find code for them (they’re not in the current tree).

- `Perception Runner (yolo_track.py)`
- `PID Implementation (pid_controller.py)`
- `Offline Experiment Builder (pid_from_log.py)`

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Diagram 1 — System Context (C4 L1)
%% =========================
subgraph "Diagram 1 — System Context (C4 Level 1)"
direction TB

U["User / Developer"]:::actor

subgraph "Vision Follow (This Repo) — Single-machine vision-to-control core"
direction TB
SYS["Vision Follow (Python 3.11 app)"]:::system
end

WBCAM[/"Webcam Device\n(camera-index N)"/]:::external
GPU["NVIDIA GPU (optional)\nCUDA via PyTorch"]:::external
ROBOT["Robot Platform (future)\nActuation interface"]:::future

U -->|"runs scripts"| SYS
WBCAM -->|"video stream"| SYS
SYS -->|"planned control commands"| ROBOT
SYS <-->|"optional acceleration"| GPU
end

%% =========================
%% Diagram 2 — Container / Runtime View (C4 L2)
%% =========================
subgraph "Diagram 2 — Container / Runtime View (C4 Level 2)"
direction TB

subgraph "Host Machine (Windows/Linux) — Python 3.11 + Torch (+CUDA)"
direction TB

APP["Python App: vision_follow"]:::system

subgraph "Key Runtime Libraries"
direction TB
OCV["OpenCV\n(VideoCapture, display)"]:::infra
TORCH["PyTorch / Ultralytics YOLO\n(CPU/GPU inference)"]:::infra
end

subgraph "Local Filesystem"
direction TB
MODELS[("Model Weights\n(models/)")]:::datastore
OUTS[("Artifacts\noutputs/")]:::datastore
LOGCSV[("Telemetry CSV\noutputs/logs/centroid_log.csv")]:::datastore
EXPS[("Versioned Experiments\noutputs/experiments/<timestamp>/")]:::datastore
end

end

WBCAM2[/"Webcam Device"/]:::external
GPU2["NVIDIA GPU (optional)"]:::external

WBCAM2 -->|"Frame stream"| OCV
OCV -->|"Frames"| APP
APP -->|"calls"| TORCH
TORCH <-->|"CUDA kernels (optional)"| GPU2

APP -->|"loads weights"| MODELS
APP -->|"writes logs"| LOGCSV
APP -->|"writes plots + configs"| EXPS
OUTS --- LOGCSV
OUTS --- EXPS
end

%% =========================
%% Diagram 3 — Component + Dataflow View (C4 L3)
%% =========================
subgraph "Diagram 3 — Component + Dataflow View (C4 Level 3)"
direction TB

WBCAM3[/"Webcam\n(camera-index N)"/]:::external

subgraph "Online / Real-time Loop (Per frame)"
direction TB

ENTRY_TRACK["Entrypoint: Tracker Runner\n(yolo_track.py)"]:::realtime
CAP["Capture: Webcam Adapter\n(OpenCV VideoCapture)"]:::realtime
DET["Perception: YOLO Detector\n(yolo_detect.py)"]:::realtime
TRACK["Perception: Tracker + Centroid Error Calculator\n(yolo_track.py)"]:::realtime
LOGGER["Telemetry Logger\n(centroid_log.csv writer)"]:::realtime

PID_LIVE["Control: PID Controller\n(planned live use)"]:::future
FOLLOW["Control: Follow Logic\n(mapping to turn/stop)"]:::future
ACT["Robot Actuation Interface\n(future integration)"]:::future

WBCAM3 -->|"Frame (H×W×3)\nper_frame"| CAP
CAP -->|"Frame\nper_frame"| DET
DET -->|"Detections / track state\n(bbox,id,conf)\nper_frame"| TRACK
TRACK -->|"Centroid horizontal error\nerror_x (px or normalized)\nper_frame"| PID_LIVE
PID_LIVE -->|"PID output\n(turn_rate / angular_velocity)\nper_frame"| FOLLOW
FOLLOW -->|"Command\n(per frame)"| ACT

TRACK -->|"timestamped error_x samples\nper_frame"| LOGGER
LOGGER -->|"append CSV"| LOGCSV3[("outputs/logs/centroid_log.csv")]:::datastore
end

subgraph "Offline / Experiment Pipeline (Batch run)"
direction TB

ENTRY_REPLAY["Entrypoint: Offline Analysis\n(pid_from_log.py)"]:::offline
PID_CORE["Control: PID Controller\n(pid_controller.py)"]:::offline
FOLLOW_CORE["Control: Follow Logic\n(follow_logic.py)"]:::offline
EXP_DIR[("outputs/experiments/<timestamp>/\nplots + run_config + copied log")]:::datastore

LOGCSV3 -->|"read CSV\nper_run"| ENTRY_REPLAY
ENTRY_REPLAY -->|"calls"| PID_CORE
ENTRY_REPLAY -->|"optional mapping"| FOLLOW_CORE
ENTRY_REPLAY -->|"write artifacts\n(error_plot,turn_plot,run_config,copy log)"| EXP_DIR
end

subgraph "Repo Ops / Docs (non-runtime)"
direction TB
REQS["Dependencies\n(requirements*.txt)"]:::infra
SCRIPTS["Setup/Repro scripts\n(scripts/*.ps1)"]:::infra
DOCS["Docs\nREADME/ARCHITECTURE/RUNBOOK/docs/"]:::infra
end

end

%% =========================
%% Click Events (from component mapping)
%% =========================
click CAP "https://github.com/pbhatt0022/vision-follow-project/tree/main/src/vision_follow/capture/"
click ENTRY_TRACK "https://github.com/pbhatt0022/vision-follow-project/blob/main/src/vision_follow/perception/yolo_track.py"
click TRACK "https://github.com/pbhatt0022/vision-follow-project/blob/main/src/vision_follow/perception/yolo_track.py"
click LOGGER "https://github.com/pbhatt0022/vision-follow-project/blob/main/src/vision_follow/perception/yolo_track.py"
click DET "https://github.com/pbhatt0022/vision-follow-project/blob/main/src/vision_follow/perception/yolo_detect.py"
click PID_CORE "https://github.com/pbhatt0022/vision-follow-project/blob/main/src/vision_follow/control/pid_controller.py"
click FOLLOW_CORE "https://github.com/pbhatt0022/vision-follow-project/blob/main/src/vision_follow/control/follow_logic.py"
click ENTRY_REPLAY "https://github.com/pbhatt0022/vision-follow-project/blob/main/src/vision_follow/control/pid_from_log.py"

click REQS "https://github.com/pbhatt0022/vision-follow-project/blob/main/requirements.txt"
click REQS "https://github.com/pbhatt0022/vision-follow-project/blob/main/requirements-lock.txt"
click REQS "https://github.com/pbhatt0022/vision-follow-project/blob/main/requirements-dev.txt"

click SCRIPTS "https://github.com/pbhatt0022/vision-follow-project/blob/main/scripts/setup_venv.ps1"
click SCRIPTS "https://github.com/pbhatt0022/vision-follow-project/blob/main/scripts/create_repro_pack.ps1"

click DOCS "https://github.com/pbhatt0022/vision-follow-project/blob/main/ARCHITECTURE.md"
click DOCS "https://github.com/pbhatt0022/vision-follow-project/blob/main/RUNBOOK.md"
click DOCS "https://github.com/pbhatt0022/vision-follow-project/blob/main/README.md"
click DOCS "https://github.com/pbhatt0022/vision-follow-project/tree/main/docs/"

%% =========================
%% Styles
%% =========================
classDef actor fill:#ffffff,stroke:#111827,stroke-width:1.5px,color:#111827
classDef system fill:#2563eb,stroke:#1e3a8a,stroke-width:1.5px,color:#ffffff
classDef external fill:#f3f4f6,stroke:#6b7280,stroke-width:1.2px,color:#111827
classDef datastore fill:#e5e7eb,stroke:#374151,stroke-width:1.2px,color:#111827
classDef infra fill:#6b7280,stroke:#111827,stroke-width:1px,color:#ffffff
classDef realtime fill:#1d4ed8,stroke:#1e3a8a,stroke-width:1.3px,color:#ffffff
classDef offline fill:#16a34a,stroke:#14532d,stroke-width:1.3px,color:#ffffff
classDef future fill:#fb923c,stroke:#9a3412,stroke-width:1.3px,color:#111827,stroke-dasharray: 6 4
```
