README.md

---
language: en
tags:
  - sign-language
  - asl
  - transformer
  - pytorch
  - prototype-learning
  - curriculum-learning
---

# ASL Sign Language Recognition — Training Results

Trained by **SharoonArshad**

## Results

| Metric | Score |
|--------|-------|
| Overall macro-F1 | **77.24%** |
| Accuracy | **68.51%** |
| Rare signs F1 | **99.47%** |
| Medium signs F1 | **59.25%** |
| Common signs F1 | **58.68%** |
| Training time | **52 minutes** |

## Model Details
- **Architecture**: Transformer Encoder + Prototype Classifier
- **Parameters**: 3.57M
- **Classes**: 4,618 ASL signs
- **Input**: `[60 frames × 204 features]` body + hand landmarks
- **Training**: 3-phase curriculum (common → rare → fine-tune)

## Files

| File | Description |
|------|-------------|
| `checkpoints/asl_v3_epoch050_score0.5728.pt` | Best PyTorch checkpoint |
| `checkpoints/asl_model.onnx` | ONNX export for deployment |
| `logs/training_history.json` | Loss + F1 for all 50 epochs |
| `logs/test_results.json` | Final test set results |
| `logs/train_v4.log` | Full training log |
| `label_map.json` | Sign ID → Sign name mapping |
| `tier_info.json` | Rare / medium / common class splits |
| `class_distribution.json` | Samples per class |
| `asl_results_complete.zip` | All files in one zip |

## How to Load

```python
import torch
from model_transformer import build_model
from config import CFG

ckpt = torch.load("asl_v3_epoch050_score0.5728.pt", map_location="cpu")
CFG.model.num_classes = ckpt["cfg"]["num_classes"]  # 4618

model = build_model(CFG, feature_dim_override=204)
model.load_state_dict(ckpt["model_state"])
model.eval()

# Inference
features     = torch.zeros(1, 60, 204)  # replace with real data
padding_mask = torch.zeros(1, 60, dtype=torch.bool)
logits, _    = model(features, padding_mask)
predicted    = logits.argmax(dim=-1).item()
print(f"Predicted sign ID: {predicted}")
```