# tssanjayy/handgesture architecture

> Architecture diagram of the GitHub repository tssanjayy/handgesture, 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/tssanjayy/handgesture
- Repository: https://github.com/tssanjayy/handgesture

## Overview

This is a real-time hand-gesture recognition project with a data-to-model workflow and two live recognition paths: the documented Random Forest demo and a separate rule-based recognizer. The graph covers session capture, offline feature preparation and evaluation, plus live prediction and visualization. Some processing is implemented inline in the demo scripts; the README documents the main capabilities, while the sampled source provides the cited runtime relationships.

Main entry points: [`live_demo_ui.py`](https://github.com/tssanjayy/handgesture/blob/main/live_demo_ui.py) (Live ML interface), [`live_demo.py`](https://github.com/tssanjayy/handgesture/blob/main/live_demo.py) (Live ML demo), [`data_collection.py`](https://github.com/tssanjayy/handgesture/blob/main/data_collection.py) (Session collector), [`model_engineered.joblib`](https://github.com/tssanjayy/handgesture/blob/main/model_engineered.joblib) (Engineered model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Data capture"]
  node_collector["Session collector<br/>[data_collection.py]"]
  node_session_csv[("Session CSVs")]
end

subgraph group_prep["Feature preparation"]
  node_feature_builder["Feature extraction<br/>[features.py]"]
  node_feature_files[("Feature datasets")]
end

subgraph group_modeling["Modeling and evaluation"]
  node_final_eval["Final evaluation"]
  node_train_eval["Training evaluation"]
  node_model_raw["Raw model<br/>[model_raw.joblib]"]
  node_model_eng["Engineered model"]
end

subgraph group_runtime["Live recognition"]
  node_live_ui["Live ML interface<br/>[live_demo_ui.py]"]
  node_live_demo["Live ML demo<br/>[live_demo.py]"]
  node_rule_recognizer["Rule-based recognizer"]
  node_tracker["Hand tracker<br/>[hand_tracking.py]"]
end

node_operator(("User"))
node_webcam(("Webcam"))
node_mediapipe["MediaPipe Hands"]
node_opencv["OpenCV"]

node_operator -->|"labels samples"| node_collector
node_webcam -->|"provides frames"| node_collector
node_collector -->|"detects landmarks"| node_mediapipe
node_collector -->|"writes samples"| node_session_csv
node_session_csv -->|"loads sessions"| node_feature_builder
node_feature_builder -->|"writes features"| node_feature_files
node_feature_files -->|"loads datasets"| node_final_eval
node_final_eval -->|"saves model"| node_model_raw
node_final_eval -->|"saves model"| node_model_eng
node_feature_files -->|"loads datasets"| node_train_eval
node_train_eval -->|"saves model"| node_model_raw
node_train_eval -->|"saves model"| node_model_eng
node_operator -->|"selects model"| node_live_ui
node_webcam -->|"provides frames"| node_live_ui
node_live_ui -->|"detects landmarks"| node_mediapipe
node_live_ui -->|"captures and renders"| node_opencv
node_model_raw -->|"loads selected model"| node_live_ui
node_model_eng -->|"loads selected model"| node_live_ui
node_webcam -->|"provides frames"| node_live_demo
node_live_demo -->|"detects landmarks"| node_mediapipe
node_live_demo -->|"loads and predicts"| node_model_eng
node_live_demo -->|"captures and renders"| node_opencv
node_webcam -->|"provides frames"| node_rule_recognizer
node_rule_recognizer -->|"detects landmarks"| node_mediapipe
node_rule_recognizer -->|"captures and renders"| node_opencv
node_webcam -->|"provides frames"| node_tracker
node_tracker -->|"detects landmarks"| node_mediapipe
node_tracker -->|"captures and renders"| node_opencv

click node_collector "https://github.com/tssanjayy/handgesture/blob/main/data_collection.py"
click node_session_csv "https://github.com/tssanjayy/handgesture/tree/main/data"
click node_feature_builder "https://github.com/tssanjayy/handgesture/blob/main/features.py"
click node_feature_files "https://github.com/tssanjayy/handgesture/tree/main/features"
click node_final_eval "https://github.com/tssanjayy/handgesture/blob/main/final_evaluation.py"
click node_train_eval "https://github.com/tssanjayy/handgesture/blob/main/train_and_evaluate.py"
click node_model_raw "https://github.com/tssanjayy/handgesture/blob/main/model_raw.joblib"
click node_model_eng "https://github.com/tssanjayy/handgesture/blob/main/model_engineered.joblib"
click node_live_ui "https://github.com/tssanjayy/handgesture/blob/main/live_demo_ui.py"
click node_live_demo "https://github.com/tssanjayy/handgesture/blob/main/live_demo.py"
click node_rule_recognizer "https://github.com/tssanjayy/handgesture/blob/main/gesture_recognition.py"
click node_tracker "https://github.com/tssanjayy/handgesture/blob/main/hand_tracking.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_collector,node_session_csv,node_operator toneBlue
class node_feature_builder,node_feature_files toneAmber
class node_final_eval,node_train_eval,node_model_raw,node_model_eng,node_mediapipe toneMint
class node_live_ui,node_live_demo,node_rule_recognizer,node_tracker toneRose
class node_webcam,node_opencv toneIndigo
```

## Components

### Data capture

- [Session collector](https://github.com/tssanjayy/handgesture/blob/main/data_collection.py): `data_collection.py`
- [Session CSVs](https://github.com/tssanjayy/handgesture/tree/main/data): `data`

### Feature preparation

- [Feature extraction](https://github.com/tssanjayy/handgesture/blob/main/features.py): `features.py`
- [Feature datasets](https://github.com/tssanjayy/handgesture/tree/main/features): `features`

### Modeling and evaluation

- [Final evaluation](https://github.com/tssanjayy/handgesture/blob/main/final_evaluation.py): `final_evaluation.py`
- [Training evaluation](https://github.com/tssanjayy/handgesture/blob/main/train_and_evaluate.py): `train_and_evaluate.py`
- [Raw model](https://github.com/tssanjayy/handgesture/blob/main/model_raw.joblib): `model_raw.joblib`
- [Engineered model](https://github.com/tssanjayy/handgesture/blob/main/model_engineered.joblib): `model_engineered.joblib`

### Live recognition

- [Live ML interface](https://github.com/tssanjayy/handgesture/blob/main/live_demo_ui.py): `live_demo_ui.py`
- [Live ML demo](https://github.com/tssanjayy/handgesture/blob/main/live_demo.py): `live_demo.py`
- [Rule-based recognizer](https://github.com/tssanjayy/handgesture/blob/main/gesture_recognition.py): `gesture_recognition.py`
- [Hand tracker](https://github.com/tssanjayy/handgesture/blob/main/hand_tracking.py): `hand_tracking.py`

### Other components

- **User**
- **Webcam**
- **MediaPipe Hands**
- **OpenCV**

## Connections

- User → Session collector: labels samples (evidence: `data_collection.py`)
- Webcam → Session collector: provides frames (evidence: `data_collection.py`)
- Session collector → MediaPipe Hands: detects landmarks (evidence: `data_collection.py`)
- Session collector → Session CSVs: writes samples (evidence: `data_collection.py`)
- Session CSVs → Feature extraction: loads sessions (evidence: `features.py`)
- Feature extraction → Feature datasets: writes features (evidence: `features.py`)
- Feature datasets → Final evaluation: loads datasets (evidence: `final_evaluation.py`)
- Final evaluation → Raw model: saves model (evidence: `final_evaluation.py`)
- Final evaluation → Engineered model: saves model (evidence: `final_evaluation.py`)
- Feature datasets → Training evaluation: loads datasets (evidence: `train_and_evaluate.py`)
- Training evaluation → Raw model: saves model (evidence: `train_and_evaluate.py`)
- Training evaluation → Engineered model: saves model (evidence: `train_and_evaluate.py`)
- User → Live ML interface: selects model (evidence: `live_demo_ui.py`)
- Webcam → Live ML interface: provides frames (evidence: `live_demo_ui.py`)
- Live ML interface → MediaPipe Hands: detects landmarks (evidence: `live_demo_ui.py`)
- Live ML interface → OpenCV: captures and renders (evidence: `live_demo_ui.py`)
- Raw model → Live ML interface: loads selected model (evidence: `live_demo_ui.py`)
- Engineered model → Live ML interface: loads selected model (evidence: `live_demo_ui.py`)
- Webcam → Live ML demo: provides frames (evidence: `live_demo.py`)
- Live ML demo → MediaPipe Hands: detects landmarks (evidence: `live_demo.py`)
- Live ML demo → Engineered model: loads and predicts (evidence: `live_demo.py`)
- Live ML demo → OpenCV: captures and renders (evidence: `live_demo.py`)
- Webcam → Rule-based recognizer: provides frames (evidence: `gesture_recognition.py`)
- Rule-based recognizer → MediaPipe Hands: detects landmarks (evidence: `gesture_recognition.py`)
- Rule-based recognizer → OpenCV: captures and renders (evidence: `gesture_recognition.py`)
- Webcam → Hand tracker: provides frames (evidence: `hand_tracking.py`)
- Hand tracker → MediaPipe Hands: detects landmarks (evidence: `hand_tracking.py`)
- Hand tracker → OpenCV: captures and renders (evidence: `hand_tracking.py`)
