Foul Classifier

Classify football foul severity into clean / normal / yellow card / red card using a fine-tuned Qwen2-VL-2B Vision-Language Model.

Quick Start

pip install -r requirements.txt

# CLI
python -m foul_classifier path/to/foul_clip.mp4

# Web UI
uvicorn foul_classifier.web.app:app --port 8008

4-Class Labels

Label	Meaning
clean	Perfectly legal tackle, wins the ball cleanly
normal	No card needed, minor contact or technical foul
yellow	Reckless challenge, unsporting behavior, tactical foul
red	Serious foul play, violent conduct, DOGSO

Web UI

Upload a video clip and get instant classification with frame previews.

Features:

• 4-class severity (clean/normal/yellow/red) with colored badges
• Drag-and-drop upload
• OpenCV-based frame extraction (8 frames, 0.5s interval)

Dataset

• ~550 original clips (clean goals, normal play, foul tackles, red cards)
• Augmented with 100 yellow card + 11 red card clips from Serie A (infactory-ai/soccer-events)

To download the augmented data:

python scripts/download_infactory.py

Training

# Prepare dataset splits
python -m foul_classifier.training.prepare_dataset

# Extract frames
python -m foul_classifier.training.extract_frames

# Fine-tune LoRA
python -m foul_classifier.training.train

# Evaluate
python -m foul_classifier.training.evaluate

Results

Version	Accuracy	Clean Recall	Yellow Recall	Red Recall
Binary LoRA (clean/foul)	90.5%	97% precision	—	73% F1
4-class LoRA (current)	85.7%	94%	30%	86%

Model

Fine-tuned with LoRA (r=16, alpha=32) on Qwen2-VL-2B-Instruct in 4-bit. Adapter weights are in foul_classifier/models_v2/ (~74 MB).

Project Structure

foul-classifier/
├── foul_classifier/
│   ├── classifier.py          # Standalone inference class
│   ├── config.py              # Config dataclass
│   ├── frame_extractor.py     # OpenCV frame extraction
│   ├── training/
│   │   ├── train.py           # LoRA fine-tuning
│   │   ├── evaluate.py        # Test set evaluation
│   │   ├── prepare_dataset.py # Dataset splits
│   │   └── extract_frames.py  # Pre-extract training frames
│   ├── models_v2/             # LoRA adapter weights
│   └── web/
│       ├── app.py             # FastAPI server
│       ├── templates/         # Frontend HTML
│       └── static/            # CSS, JS, previews
├── data/
│   ├── clips/                 # Source video clips
│   ├── frames/                # Pre-extracted frames
│   └── splits/                # JSON train/val/test splits
└── requirements.txt