# tanbinrkyser/driver-facial-expression-recognition architecture

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

- Interactive diagram: https://gitdiagram.com/tanbinrkyser/driver-facial-expression-recognition
- Repository: https://github.com/tanbinrkyser/driver-facial-expression-recognition

## Overview

This repository is a PyTorch driver facial-expression recognition research prototype. Its principal workflow prepares cropped, split images, trains a dual-backbone classifier, and uses the trained model for evaluation or single-image prediction. README documents the preprocessing, transforms, loaders, and training stages; sampled source confirms the model, inference, evaluation, and Grad-CAM behavior. Preprocessing and loader wiring is summarized from the README because those implementations were not sampled.

Main entry points: [`engine.py`](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/engine.py) (ShuffleEfficientViT), [`inference_2.py`](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/inference_2.py) (Single-image inference), [`conf_matrix_2.py`](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/conf_matrix_2.py) (Test evaluation), [`explain_3.py`](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/explain_3.py) (Branch Grad-CAM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Image preparation"]
  node_crop["Face cropping<br/>[cropping.py]"]
  node_split["Train/test split"]
  node_splitdata["Cropped split data"]
  node_transforms["Image transforms"]
  node_loaders["Data loaders"]
end

subgraph group_learn["Model and training"]
  node_trainer["Two-stage training<br/>[train_final.py]"]
  node_model["ShuffleEfficientViT<br/>[engine.py]"]
  node_checkpoint["Model checkpoint"]
  node_lr["Learning-rate finder<br/>[lr_finder.py]"]
end

subgraph group_serve["Prediction and analysis"]
  node_inference["Single-image inference<br/>[inference_2.py]"]
  node_prediction["Emotion prediction"]
  node_evaluator["Test evaluation<br/>[conf_matrix_2.py]"]
  node_report["Metrics and confusion matrix"]
  node_explain["Branch Grad-CAM<br/>[explain_3.py]"]
  node_heatmaps["Attention visualizations"]
end

node_dataset["KMU-FED images"]
node_weights["Pretrained weights"]
node_user(("Image user"))

node_dataset -->|"supplies images"| node_crop
node_crop -->|"creates crops"| node_split
node_split -->|"writes split"| node_splitdata
node_splitdata -->|"provides images"| node_transforms
node_transforms -->|"transforms samples"| node_loaders
node_loaders -->|"provides batches"| node_trainer
node_trainer -->|"trains"| node_model
node_model -.->|"loads pretrained weights"| node_weights
node_trainer -->|"saves best state"| node_checkpoint
node_user -->|"submits image"| node_inference
node_inference -->|"runs prediction"| node_model
node_checkpoint -->|"loads state"| node_inference
node_inference -->|"produces label"| node_prediction
node_splitdata -->|"supplies test set"| node_evaluator
node_checkpoint -->|"loads state"| node_evaluator
node_evaluator -->|"runs evaluation"| node_model
node_evaluator -->|"reports metrics"| node_report
node_user -->|"requests explanation"| node_explain
node_checkpoint -->|"loads state"| node_explain
node_explain -->|"computes activations"| node_model
node_explain -->|"generates heatmaps"| node_heatmaps
node_loaders -->|"provides batches"| node_lr
node_lr -->|"tests learning rates"| node_model

click node_crop "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/cropping.py"
click node_split "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/dataset_preprocessing_2.py"
click node_transforms "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/data_transformation_2.py"
click node_loaders "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/create_dataloaders_2.py"
click node_trainer "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/train_final.py"
click node_model "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/engine.py"
click node_inference "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/inference_2.py"
click node_evaluator "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/conf_matrix_2.py"
click node_explain "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/explain_3.py"
click node_lr "https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/lr_finder.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_crop,node_split,node_splitdata,node_transforms,node_loaders,node_user toneBlue
class node_trainer,node_model,node_checkpoint,node_lr toneAmber
class node_inference,node_prediction,node_evaluator,node_report,node_explain,node_heatmaps toneMint
class node_dataset,node_weights toneIndigo
```

## Components

### Image preparation

- [Face cropping](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/cropping.py): `cropping.py`
- [Train/test split](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/dataset_preprocessing_2.py): `dataset_preprocessing_2.py`
- **Cropped split data**
- [Image transforms](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/data_transformation_2.py): `data_transformation_2.py`
- [Data loaders](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/create_dataloaders_2.py): `create_dataloaders_2.py`

### Model and training

- [Two-stage training](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/train_final.py): `train_final.py`
- [ShuffleEfficientViT](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/engine.py): `engine.py`
- **Model checkpoint**
- [Learning-rate finder](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/lr_finder.py): `lr_finder.py`

### Prediction and analysis

- [Single-image inference](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/inference_2.py): `inference_2.py`
- **Emotion prediction**
- [Test evaluation](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/conf_matrix_2.py): `conf_matrix_2.py`
- **Metrics and confusion matrix**
- [Branch Grad-CAM](https://github.com/tanbinrkyser/driver-facial-expression-recognition/blob/main/explain_3.py): `explain_3.py`
- **Attention visualizations**

### Other components

- **KMU-FED images**
- **Pretrained weights**
- **Image user**

## Connections

- KMU-FED images → Face cropping: supplies images
- Face cropping → Train/test split: creates crops
- Train/test split → Cropped split data: writes split
- Cropped split data → Image transforms: provides images
- Image transforms → Data loaders: transforms samples
- Data loaders → Two-stage training: provides batches
- Two-stage training → ShuffleEfficientViT: trains
- ShuffleEfficientViT → Pretrained weights: loads pretrained weights
- Two-stage training → Model checkpoint: saves best state
- Image user → Single-image inference: submits image
- Single-image inference → ShuffleEfficientViT: runs prediction
- Model checkpoint → Single-image inference: loads state
- Single-image inference → Emotion prediction: produces label
- Cropped split data → Test evaluation: supplies test set
- Model checkpoint → Test evaluation: loads state
- Test evaluation → ShuffleEfficientViT: runs evaluation
- Test evaluation → Metrics and confusion matrix: reports metrics
- Image user → Branch Grad-CAM: requests explanation
- Model checkpoint → Branch Grad-CAM: loads state
- Branch Grad-CAM → ShuffleEfficientViT: computes activations
- Branch Grad-CAM → Attention visualizations: generates heatmaps
- Data loaders → Learning-rate finder: provides batches
- Learning-rate finder → ShuffleEfficientViT: tests learning rates