Yolo12n_Eyes_Detection

YOLOv12 Eyes Detection Model

<div align="center">

Una soluzione avanzata per la detection degli occhi utilizzando YOLOv12 e dataset custom da HuggingFace

</div>

---

📋 Summary

Questo progetto implementa un modello di object detection specializzato per l'identificazione e localizzazione degli occhi in immagini e video, basato sull'architettura YOLOv12 (You Only Look Once version 12) di Ultralytics. Il modello è addestrato su un dataset custom di high-quality disponibil su HuggingFace e offre prestazioni eccellenti per applicazioni di computer vision.

✨ Caratteristiche Principali

• 🎯 Detection accurata degli occhi con alta precisione e recall
• 🚀 Architettura YOLOv12 all'avanguardia per object detection
• 📊 Pipeline completa di training, validazione e test
• 🎥 Predizioni multi-modalità: immagini, video, webcam in tempo reale
• ⚙️ Configurazione flessibile tramite file YAML
• 📈 Monitoraggio avanzato con WandB integration
• 🔧 Design modulare per facile personalizzazione
• 💾 Output strutturato con salvataggio automatico dei risultati

---

🎯 Model Details

Model Description

Il modello implementa una rete neurale convoluzionale per la detection degli occhi basata su YOLOv12, ottimizzata per:

• Single-class detection: riconosce esclusivamente occhi
• Real-time processing: suitable for live video streams
• High accuracy: precision e recall elevati per applicazioni critiche
• Robust performance: generalizza bene su diverse condizioni di illuminazione

Architecture

• Base Model: YOLOv12n (versione nano per performance ottimali)
• Framework: Ultralytics YOLOv12
• Input Size: 640x640 pixels (configurabile)
• Output: Bounding boxes con confidence scores per detection degli occhi
• Device Support: CPU, CUDA, con supporto mixed precision

Training Configuration

training:
  epochs: 100
  batch_size: 16
  img_size: 640
  learning_rate: 0.01
  weight_decay: 0.0005
  early_stopping:
    patience: 3
    min_delta: 0.002

Performance Metrics

---

📊 Dataset Information

Dataset Source

Dataset: AndreaPorri/Eyes_Dataset_YOLO12

• Provider: HuggingFace Datasets
• Type: Custom dataset per eyes detection
• Format: YOLO format (images + labels)
• Split: Train/Validation/Test sets pre-divisi

Dataset Structure

eyes_dataset/
├── train/
│   ├── images/     # Training images
│   └── labels/     # YOLO format annotations
├── valid/
│   ├── images/     # Validation images  
│   └── labels/     # YOLO format annotations
└── test/
    ├── images/     # Test images
    └── labels/     # YOLO format annotations

Data Characteristics

• Object Class: Single class "eyes"
• Image Format: JPG, PNG supportati
• Annotation Format: YOLO (x_center, y_center, width, height) normalizzati
• Data Quality: High-quality annotations con accuratezza sub-pixel
• Preprocessing: Automatico download e preprocessing via HuggingFace Hub

Augmentation Strategy

Il training include sophisticated data augmentation:

• HSV Color Space: Hue, Saturation, Value variations
• Geometric Transformations: Rotation, translation, scaling
• Mosaic Augmentation: Improved training stability
• Horizontal Flipping: Standard augmentation technique
• Customizable Parameters: Configurabili via YAML

---

🚀 Usage

Quick Start

1. Environment Setup

# Clone/download del repository
git clone <repository-url>
cd yolo12-eyes-detection

# Installa dipendenze
pip install -r requirements.txt

2. Configuration

Modifica il file config.yaml con le tue preferenze:

# Configurazione WandB (opzionale)
wandb:
  project: "your-project-name"
  entity: "your-username" 
  api_key: "your-wandb-api-key"

# Configurazione Hardware
hardware:
  device: "auto"        # auto, cpu, cuda, cuda:0
  mixed_precision: true

# Parametri Training
training:
  epochs: 50            # Numero epoche
  batch_size: 8         # Batch size (ridotto per 8GB VRAM)
  img_size: 640         # Risoluzione input
  learning_rate: 0.01   # Learning rate

3. Training

Pipeline Completa (Training + Validazione + Test):

python yolo12_eyes_detection_modular.py --mode all

Solo Training:

python yolo12_eyes_detection_modular.py --mode train

Solo Test (con modello esistente):

python yolo12_eyes_detection_modular.py --config config.yaml --mode test

Inference

Single Image Prediction

python predict_eyes.py \
  --model runs/train/yolo12_eyes/weights/best.pt \
  --source test_image.jpg \
  --conf 0.5 \
  --save predicted_image.jpg

Video Processing

python predict_eyes.py \
  --model runs/train/yolo12_eyes/weights/best.pt \
  --source video.mp4 \
  --conf 0.5 \
  --save output_video.mp4

Real-time Webcam

python predict_eyes.py \
  --model runs/train/yolo12_eyes/weights/best.pt \
  --source 0 \
  --conf 0.5

Batch Processing

python predict_eyes.py \
  --model runs/train/yolo12_eyes/weights/best.pt \
  --source images_folder/ \
  --conf 0.5 \
  --save predictions/

---

📁 Project Structure

yolo12-eyes-detection/
├── 📄 README.md                           # Questa documentazione completa
├── 📄 config.yaml                        # Configurazione principale
├── 📄 requirements.txt                   # Dipendenze Python
├── 📄 yolo12_eyes_detection_modular.py   # Script training modulare
├── 📄 predict_eyes.py                    # Script predizioni
├── 📄 ESEMPIO_USO_SEPARATO.md            # Guide d'uso dettagliate
├── 📁 data/                              # Dataset directory
│   └── eyes_dataset/                     # Dataset estratto
│       ├── train/                        # Training set
│       ├── valid/                        # Validation set  
│       ├── test/                         # Test set
│       └── data.yaml                     # Configurazione YOLO
├── 📁 runs/                              # Training outputs
│   └── train/
│       └── yolo12_eyes/                  # Run specifico
│           ├── weights/
│           │   ├── best.pt               # Modello migliore
│           │   └── last.pt               # Ultimo checkpoint
│           ├── results.png               # Grafici risultati
│           └── confusion_matrix.png      # Matrice confusione
├── 📁 risultati_eyes_detection/          # Risultati test
│   ├── validazione_finale.txt            # Risultati validazione
│   └── test_finale.txt                   # Risultati test
└── 📁 logs/                              # Log files (opzionale)

File Descriptions

---

⚙️ Configuration Options

Model Selection

Scegli la variante YOLOv12 più adatta alle tue esigenze:

model:
  size: "yolo12n.pt"    # nano: più veloce, meno accurato
  # size: "yolo12s.pt"  # small: balanced
  # size: "yolo12m.pt"  # medium: more accurate  
  # size: "yolo12l.pt"  # large: high accuracy
  # size: "yolo12x.pt"  # extra large: highest accuracy

Training Parameters

training:
  epochs: 100              # Numero epoche training
  batch_size: 16           # Batch size (riduci se OutOfMemory)
  img_size: 640            # Risoluzione input (416, 512, 640, 832)
  learning_rate: 0.01      # Learning rate iniziale
  weight_decay: 0.0005     # Regularizzazione L2
  workers: 8               # Worker threads (riduci se OMP errors)

Hardware Optimization

Per GPU con 8GB VRAM (RTX 4060):

training:
  batch_size: 8            # Ridotto per sicurezza VRAM
  workers: 2               # Ridotto per evitare OMP errors
  
hardware:
  device: "cuda:0"         # Esplicito per la GPU
  mixed_precision: true    # FP16 per risparmio memoria

Augmentation Settings

training:
  augment: true            # Abilita data augmentation
  aug_par:
    hsv_h: 0.015           # Variazione hue
    hsv_s: 0.7             # Variazione saturazione
    hsv_v: 0.4             # Variazione luminosità
    degrees: 0.0           # Rotazione massima
    translate: 0.1         # Traslazione
    scale: 0.5             # Scala
    fliplr: 0.5            # Probabilità flip orizzontale
    mosaic: 1.0            # Probabilità mosaic

---

📈 Monitoring & Results

WandB Integration

Il progetto si integra automaticamente con Weights & Biases per:

• Training Monitoring: Loss curves, validation metrics
• Model Versioning: Automatic best model tracking
• Hyperparameter Tracking: Complete configuration logging
• Performance Visualization: Interactive charts e graphs
• Collaboration: Easy sharing e comparison

Setup WandB:

1. Registrati su wandb.ai
2. Ottieni API key da wandb.ai/authorize
3. Aggiorna config.yaml con le tue credenziali

Text-based Results

I risultati vengono salvati automaticamente anche come file di testo:

# Risultati salvati in:
risultati_eyes_detection/
├── validazione_finale.txt    # Risultati validazione dettagliati
└── test_finale.txt          # Risultati test dettagliati

Formato risultati:

YOLOv12 EYES DETECTION - VALIDATION RESULTS
============================================================
Timestamp: 2024-01-15 10:30:45
Model: YOLOv12n (best.pt)
Dataset: Eyes Detection Dataset
------------------------------------------------------------

FINAL METRICS:
------------------------------
Precision:           0.987654
Recall:              0.973210
F1 Score:            0.980386
[email protected]:             0.991234
[email protected]:0.95:        0.723456

Training Artifacts

Il training produce diversi artifact:

• best.pt: Modello con migliori performance
• last.pt: Ultimo checkpoint del training
• results.png: Grafici di loss e metrics
• confusion_matrix.png: Matrice di confusione
• F1_curve.png: Curva F1-Score
• PR_curve.png: Precision-Recall curve

---

🔧 Advanced Features

Custom Early Stopping

Il sistema implementa early stopping intelligente:

training:
  custom_early_stopping: true
  early_stopping:
    patience: 3            # Epoche senza miglioramento
    min_delta: 0.002       # Miglioramento minimo (0.2%)
    print_mess: true       # Stampa messaggi di debug

Multi-Modal Validation

Validation automatica su più set:

• Validation Set: Durante il training (ad ogni epoca)
• Final Validation: Best model sul validation set
• Test Set: Best model sul test set unseen

F1-Score Calculation

Calcolo automatico F1-Score durante validation:

• Durante Training: Callback automatico per tracking
• Final Metrics: F1 incluso nei risultati finali
• Output: Console e file di testo

---

🚨 Troubleshooting

Common Issues & Solutions

1. CUDA Out of Memory

Problema: GPU memory insufficient

# Soluzione: Riduci batch size
training:
  batch_size: 4     # o 2 per sistemi con poca VRAM
  workers: 1        # Riduci workers

2. OpenMP DataLoader Worker Error

Problema: Multi-threading issues

# Aggiungi all'inizio dello script Python
import os
os.environ['KMP_DUPLICATE_LIB_OK'] = 'TRUE'
os.environ['OMP_NUM_THREADS'] = '4'
os.environ['MKL_NUM_THREADS'] = '4'

3. Model Best Not Found

Problema: Best model non trovato durante test

# Soluzione: Esegui prima il training
python yolo12_eyes_detection_modular.py --config config.yaml --mode train

4. Dataset Download Issues

Problema: Download dataset da HuggingFace fallisce

# Soluzione: Verifica connessione internet
# Il dataset viene scaricato automaticamente da:
# https://huggingface.co/datasets/AndreaPorri/Eyes_Dataset_YOLO12

Performance Optimization

For High-End GPUs (RTX 4090+)

training:
  batch_size: 32
  workers: 12
  img_size: 832  # Maggiore risoluzione

For Low-Memory GPUs (GTX 1060 6GB)

training:
  batch_size: 4
  workers: 2
  img_size: 416  # Risoluzione ridotta

CPU-Only Training

hardware:
  device: "cpu"
  mixed_precision: false

training:
  batch_size: 2      # Batch size molto ridotto
  workers: 1         # Single thread

---

🔬 Technical Details

System Requirements

Minimum Requirements

• OS: Linux, Windows, macOS
• Python: 3.8+
• RAM: 8GB minimum, 16GB recommended
• GPU: Optional, CPU training supported
• Storage: 5GB per dataset + 2GB per artifacts

Recommended Configuration

• Python: 3.9-3.11
• RAM: 32GB
• GPU: RTX 4060+ (8GB+ VRAM)
• Storage: SSD per performance ottimali

Dependencies

Il progetto utilizza un stack tecnologico moderno:

• Deep Learning: PyTorch 2.5.1+cu121, Ultralytics 8.3.225
• Computer Vision: OpenCV 4.12.0, Pillow 12.0.0
• Data Processing: NumPy 2.2.6, PyYAML 6.0.3
• Configuration: OmegaConf 2.3.0
• Monitoring: WandB 0.22.3
• UI/Progress: Rich 14.2.0, Tqdm 4.67.1

Architecture Details

YOLOv12 Architecture

• Backbone: Enhanced feature extraction
• Neck: PAN (Path Aggregation Network) con modifiche
• Head: Detection head con anchor-free design
• Activation: SiLU (Swish) activation functions
• Normalization: BatchNorm con weight standardization

Training Pipeline

1. Dataset Loading: Automatic from HuggingFace
2. Preprocessing: Resize, normalization, augmentation
3. Model Initialization: Pre-trained weights loading
4. Training Loop: Gradient descent con early stopping
5. Validation: Periodic evaluation su validation set
6. Model Selection: Best model based su validation mAP
7. Testing: Final evaluation su test set unseen

---

📊 Evaluation Results

Benchmarking

Il modello viene valutato utilizzando standard metrics:

Validation Performance

🎯 VALIDATION RESULTS (Best Model)
┏━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Metrica      ┃ Valore  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ Precision    │ 0.9932  │
│ Recall       │ 0.9951  │
│ F1 Score     │ 0.9942  │
│ [email protected]      │ 0.9947  │
│ [email protected]:0.95 │ 0.8199  │
└──────────────┴─────────┘

Test Performance

🧪 TEST RESULTS (Unseen Data)
┏━━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ Metrica      ┃ Valore  ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━┩
│ Precision    │ 0.9934  │
│ Recall       │ 0.9956  │
│ F1 Score     │ 0.9945  │
│ [email protected]      │ 0.9945  │
│ [email protected]:0.95 │ 0.8149  │
└──────────────┴─────────┘

Performance Analysis

Strengths

• High Precision: >98% precision indica basso false positive rate
• Excellent Recall: >97% recall mostra buona detection capability
• Strong [email protected]: >98% su soglia IoU 50%
• Robust Generalization: Test performance close to validation

Use Cases

• Medical Imaging: Eye tracking, pupil detection
• Human-Computer Interaction: Gaze-based interfaces
• Security Systems: Liveness detection
• Research Applications: Eye movement studies
• Quality Control: Industrial eye inspection

---

🔮 Future Improvements

Planned Enhancements

Short Term

• Multi-class Detection: Supporto per diverse parti oculari
• 3D Eye Landmarks: Estensione per keypoint detection
• Real-time Optimization: Model quantization per deployment
• Web Interface: Streamlit/Gradio web app

Medium Term

• Video Tracking: Multi-frame eye tracking
• Occlusion Handling: Miglior detection in presenza di occlusion
• Cross-dataset Evaluation: Test su dataset esterni
• API Endpoint: REST API per production deployment

Long Term

• Mobile Deployment: TFLite/CoreML optimization
• Multi-modal Integration: Combinazione con audio per HCI
• Federated Learning: Distributed training capability
• Automated Pipeline: Full MLOps integration

---

📜 Osservazioni

• Prestazioni Eccellenti: Se il volto si trova in posizione naturale, occhi posizionati orizzontalmente, o leggergemnte inclunati [-30°, 30°].
• Mal Funzionamento: Non funziona bene se gli occhi sono in posizioni non naturali, come ad esempio volto ruotato 90°.

---

📜 License & Citations

License

Questo progetto è rilasciato sotto licenza cc-by-nc-sa-4.0.

Uso Commerciale: Il modello YOLOv12 originale è proprietà di Ultralytics. Consultare la loro licenza per uso commerciale.

Citations

Se utilizzi questo progetto, cita:

@software{yolo12_eyes_detection,
  title={YOLOv12 Eyes Detection Model},
  author={Andrea Porri},
  year={2025},
  url={https://github.com/your-username/yolo12-eyes-detection},
  note={Computer Vision model for eye detection using YOLOv12}
}

---

<div align="center">

---

Ultimo aggiornamento: 2025-11-07
Versione: 1.0.0
Maintainer: MiniMax Agent