# winterwidow/asl-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/winterwidow/asl-recognition
- Repository: https://github.com/winterwidow/asl-recognition

## Overview

This repository is an ASL gesture-recognition application with two main workflows: train an SVM from labeled hand images, and recognize signs from a webcam stream. Both workflows use shared MediaPipe landmark extraction; the live workflow then smooths predictions and displays them. The README also documents PCA visualization and alternate SVM kernels. Training and prediction call sites are excerpted; visualization and dataset capabilities are documented, but their full runtime wiring was not independently inspected.

Main entry points: [`predict.py`](https://github.com/winterwidow/asl-recognition/blob/branch/predict.py) (Live Predictor), [`train.py`](https://github.com/winterwidow/asl-recognition/blob/branch/train.py) (SVM Trainer), [`utils.py`](https://github.com/winterwidow/asl-recognition/blob/branch/utils.py) (Landmark Extractor), [`predict_backup.py`](https://github.com/winterwidow/asl-recognition/blob/branch/predict_backup.py) (Image Predictor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Model Training"]
  node_datasets[("Gesture Images")]
  node_trainer["SVM Trainer<br/>[train.py]"]
  node_trained_model["Number Model<br/>[svm_model2.pkl]"]
  node_alphabet_model["Alphabet Model<br/>[svm_model.pkl]"]
  node_visualization["PCA Visualization<br/>[train.py]"]
end

subgraph group_recognition["Live Recognition"]
  node_live_predictor["Live Predictor<br/>[predict.py]"]
  node_smoother["Prediction Smoothing<br/>[predict.py]"]
  node_display["Video Overlay<br/>[predict.py]"]
  node_image_predictor["Image Predictor<br/>[predict_backup.py]"]
end

subgraph group_vision["Landmark Extraction"]
  node_landmarks["Landmark Extractor<br/>[utils.py]"]
  node_task_model["Hand Landmarker"]
end

node_user(("Operator"))
node_camera(("Webcam"))

node_user -->|"starts training"| node_trainer
node_datasets -->|"provides images"| node_trainer
node_trainer -->|"extracts features"| node_landmarks
node_trainer -->|"saves model"| node_trained_model
node_trainer -->|"plots clusters"| node_visualization
node_user -->|"starts recognition"| node_live_predictor
node_camera -->|"streams frames"| node_live_predictor
node_live_predictor -->|"extracts features"| node_landmarks
node_live_predictor -->|"loads model"| node_alphabet_model
node_live_predictor -->|"buffers predictions"| node_smoother
node_smoother -->|"stabilizes label"| node_display
node_live_predictor -->|"overlays result"| node_display
node_image_predictor -->|"extracts features"| node_landmarks
node_image_predictor -->|"loads model"| node_trained_model
node_image_predictor -->|"shows prediction"| node_display
node_landmarks -->|"uses model"| node_task_model

click node_datasets "https://github.com/winterwidow/asl-recognition/tree/branch/data"
click node_trainer "https://github.com/winterwidow/asl-recognition/blob/branch/train.py"
click node_trained_model "https://github.com/winterwidow/asl-recognition/blob/branch/svm_model2.pkl"
click node_alphabet_model "https://github.com/winterwidow/asl-recognition/blob/branch/svm_model.pkl"
click node_visualization "https://github.com/winterwidow/asl-recognition/blob/branch/train.py"
click node_landmarks "https://github.com/winterwidow/asl-recognition/blob/branch/utils.py"
click node_task_model "https://github.com/winterwidow/asl-recognition/blob/branch/hand_landmarker.task"
click node_live_predictor "https://github.com/winterwidow/asl-recognition/blob/branch/predict.py"
click node_smoother "https://github.com/winterwidow/asl-recognition/blob/branch/predict.py"
click node_display "https://github.com/winterwidow/asl-recognition/blob/branch/predict.py"
click node_image_predictor "https://github.com/winterwidow/asl-recognition/blob/branch/predict_backup.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_datasets,node_trainer,node_trained_model,node_alphabet_model,node_visualization toneBlue
class node_live_predictor,node_smoother,node_display,node_image_predictor toneAmber
class node_landmarks,node_task_model toneMint
class node_user,node_camera toneIndigo
```

## Components

### Model Training

- [Gesture Images](https://github.com/winterwidow/asl-recognition/tree/branch/data): `data`
- [SVM Trainer](https://github.com/winterwidow/asl-recognition/blob/branch/train.py): `train.py`
- [Number Model](https://github.com/winterwidow/asl-recognition/blob/branch/svm_model2.pkl): `svm_model2.pkl`
- [Alphabet Model](https://github.com/winterwidow/asl-recognition/blob/branch/svm_model.pkl): `svm_model.pkl`
- [PCA Visualization](https://github.com/winterwidow/asl-recognition/blob/branch/train.py): `train.py`

### Live Recognition

- [Live Predictor](https://github.com/winterwidow/asl-recognition/blob/branch/predict.py): `predict.py`
- [Prediction Smoothing](https://github.com/winterwidow/asl-recognition/blob/branch/predict.py): `predict.py`
- [Video Overlay](https://github.com/winterwidow/asl-recognition/blob/branch/predict.py): `predict.py`
- [Image Predictor](https://github.com/winterwidow/asl-recognition/blob/branch/predict_backup.py): `predict_backup.py`

### Landmark Extraction

- [Landmark Extractor](https://github.com/winterwidow/asl-recognition/blob/branch/utils.py): `utils.py`
- [Hand Landmarker](https://github.com/winterwidow/asl-recognition/blob/branch/hand_landmarker.task): `hand_landmarker.task`

### Other components

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

## Connections

- Operator → SVM Trainer: starts training (evidence: `README.md`)
- Gesture Images → SVM Trainer: provides images (evidence: `train.py`)
- SVM Trainer → Landmark Extractor: extracts features (evidence: `train.py`)
- SVM Trainer → Number Model: saves model (evidence: `train.py`)
- SVM Trainer → PCA Visualization: plots clusters (evidence: `README.md`)
- Operator → Live Predictor: starts recognition (evidence: `README.md`)
- Webcam → Live Predictor: streams frames (evidence: `predict.py`)
- Live Predictor → Landmark Extractor: extracts features (evidence: `predict.py`)
- Live Predictor → Alphabet Model: loads model (evidence: `predict.py`)
- Live Predictor → Prediction Smoothing: buffers predictions (evidence: `predict.py`)
- Prediction Smoothing → Video Overlay: stabilizes label (evidence: `predict.py`)
- Live Predictor → Video Overlay: overlays result (evidence: `predict.py`)
- Image Predictor → Landmark Extractor: extracts features (evidence: `predict_backup.py`)
- Image Predictor → Number Model: loads model (evidence: `predict_backup.py`)
- Image Predictor → Video Overlay: shows prediction (evidence: `predict_backup.py`)
- Landmark Extractor → Hand Landmarker: uses model (evidence: `utils.py`)
