# vash-codex/servo-facial-tracking architecture

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

- Interactive diagram: https://gitdiagram.com/vash-codex/servo-facial-tracking
- Repository: https://github.com/vash-codex/servo-facial-tracking

## Overview

This is a desktop webcam face-tracking application with an Arduino-driven servo. The user launches training or either tracking mode from the Tkinter control center; training captures face samples and builds an LBPH model, which the recognition tracker loads to follow the face and send servo angles. A separate basic mode tracks without recognition and provides animated eye styles and keyboard controls. The Arduino sketch is the hardware endpoint. The dataset is generated at runtime and is not present in the tree; firmware internals were not sampled.

Main entry points: [`face_tracker_gui.py`](https://github.com/vash-codex/servo-facial-tracking/blob/main/face_tracker_gui.py) (Mode Dispatcher), [`custom face/face_tracker_lbph.py`](https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/face_tracker_lbph.py) (Recognition Tracker), [`custom face/train_lbph.py`](https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/train_lbph.py) (Face Capture), [`face.py`](https://github.com/vash-codex/servo-facial-tracking/blob/main/face.py) (Basic Tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control Center"]
  node_gui["Tkinter GUI"]
  node_training_dispatch["Mode Dispatcher"]
end

subgraph group_recognition["Recognition Training"]
  node_capture["Face Capture<br/>[train_lbph.py]"]
  node_dataset[("Face Samples")]
  node_trainer["LBPH Trainer<br/>[train_lbph.py]"]
  node_model["LBPH Model"]
end

subgraph group_tracking["Tracking Modes"]
  node_lbph_entry["LBPH Entry"]
  node_lbph_tracker["Recognition Tracker"]
  node_basic_tracker["Basic Tracker<br/>[face.py]"]
  node_basic_serial["Basic Serial Control<br/>[face.py]"]
end

subgraph group_hardware["Servo Hardware"]
  node_serial_controller["Serial Controller"]
  node_arduino["Arduino Servo Firmware<br/>[facearduino.ino]"]
end

node_user(("Operator"))
node_webcam(("Webcam"))
node_servo(("Servo"))

node_user -->|"operates"| node_gui
node_gui -->|"launches mode"| node_training_dispatch
node_training_dispatch -->|"dispatches training"| node_capture
node_training_dispatch -->|"dispatches LBPH"| node_lbph_entry
node_training_dispatch -->|"dispatches basic"| node_basic_tracker
node_capture -->|"reads frames"| node_webcam
node_capture -->|"writes samples"| node_dataset
node_trainer -->|"loads samples"| node_dataset
node_trainer -->|"saves model"| node_model
node_lbph_entry -->|"runs tracker"| node_lbph_tracker
node_lbph_tracker -->|"loads model"| node_model
node_lbph_tracker -->|"reads frames"| node_webcam
node_lbph_tracker -->|"sends angles"| node_serial_controller
node_basic_tracker -->|"reads frames"| node_webcam
node_basic_tracker -->|"sends angles"| node_basic_serial
node_serial_controller -->|"serial commands"| node_arduino
node_basic_serial -->|"serial commands"| node_arduino
node_arduino -->|"drives"| node_servo

click node_gui "https://github.com/vash-codex/servo-facial-tracking/blob/main/face_tracker_gui.py"
click node_training_dispatch "https://github.com/vash-codex/servo-facial-tracking/blob/main/face_tracker_gui.py"
click node_capture "https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/train_lbph.py"
click node_trainer "https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/train_lbph.py"
click node_model "https://github.com/vash-codex/servo-facial-tracking/tree/main/custom%20face"
click node_lbph_entry "https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/face_tracker_lbph.py"
click node_lbph_tracker "https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/face_tracker_lbph.py"
click node_basic_tracker "https://github.com/vash-codex/servo-facial-tracking/blob/main/face.py"
click node_serial_controller "https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/face_tracker_lbph.py"
click node_basic_serial "https://github.com/vash-codex/servo-facial-tracking/blob/main/face.py"
click node_arduino "https://github.com/vash-codex/servo-facial-tracking/blob/main/facearduino/facearduino.ino"

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_gui,node_training_dispatch toneBlue
class node_capture,node_dataset,node_trainer,node_model toneAmber
class node_lbph_entry,node_lbph_tracker,node_basic_tracker,node_basic_serial toneMint
class node_serial_controller,node_arduino toneRose
class node_user,node_webcam,node_servo toneIndigo
```

## Components

### Control Center

- [Tkinter GUI](https://github.com/vash-codex/servo-facial-tracking/blob/main/face_tracker_gui.py): `face_tracker_gui.py`
- [Mode Dispatcher](https://github.com/vash-codex/servo-facial-tracking/blob/main/face_tracker_gui.py): `face_tracker_gui.py`

### Recognition Training

- [Face Capture](https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/train_lbph.py): `custom face/train_lbph.py`
- **Face Samples**
- [LBPH Trainer](https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/train_lbph.py): `custom face/train_lbph.py`
- [LBPH Model](https://github.com/vash-codex/servo-facial-tracking/tree/main/custom%20face): `custom face`

### Tracking Modes

- [LBPH Entry](https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/face_tracker_lbph.py): `custom face/face_tracker_lbph.py`
- [Recognition Tracker](https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/face_tracker_lbph.py): `custom face/face_tracker_lbph.py`
- [Basic Tracker](https://github.com/vash-codex/servo-facial-tracking/blob/main/face.py): `face.py`
- [Basic Serial Control](https://github.com/vash-codex/servo-facial-tracking/blob/main/face.py): `face.py`

### Servo Hardware

- [Serial Controller](https://github.com/vash-codex/servo-facial-tracking/blob/main/custom%20face/face_tracker_lbph.py): `custom face/face_tracker_lbph.py`
- [Arduino Servo Firmware](https://github.com/vash-codex/servo-facial-tracking/blob/main/facearduino/facearduino.ino): `facearduino/facearduino.ino`

### Other components

- **Operator**
- **Webcam**
- **Servo**

## Connections

- Operator → Tkinter GUI: operates (evidence: `README.md`)
- Tkinter GUI → Mode Dispatcher: launches mode (evidence: `face_tracker_gui.py`)
- Mode Dispatcher → Face Capture: dispatches training (evidence: `face_tracker_gui.py`)
- Mode Dispatcher → LBPH Entry: dispatches LBPH (evidence: `face_tracker_gui.py`)
- Mode Dispatcher → Basic Tracker: dispatches basic (evidence: `face_tracker_gui.py`)
- Face Capture → Webcam: reads frames (evidence: `custom face/train_lbph.py`)
- Face Capture → Face Samples: writes samples (evidence: `custom face/train_lbph.py`)
- LBPH Trainer → Face Samples: loads samples (evidence: `custom face/train_lbph.py`)
- LBPH Trainer → LBPH Model: saves model (evidence: `custom face/train_lbph.py`)
- LBPH Entry → Recognition Tracker: runs tracker (evidence: `custom face/face_tracker_lbph.py`)
- Recognition Tracker → LBPH Model: loads model (evidence: `custom face/face_tracker_lbph.py`)
- Recognition Tracker → Webcam: reads frames (evidence: `custom face/face_tracker_lbph.py`)
- Recognition Tracker → Serial Controller: sends angles (evidence: `custom face/face_tracker_lbph.py`)
- Basic Tracker → Webcam: reads frames (evidence: `face.py`)
- Basic Tracker → Basic Serial Control: sends angles (evidence: `face.py`)
- Serial Controller → Arduino Servo Firmware: serial commands (evidence: `README.md`)
- Basic Serial Control → Arduino Servo Firmware: serial commands (evidence: `README.md`)
- Arduino Servo Firmware → Servo: drives (evidence: `README.md`)
