Waste Type Classifier

Un Jupyter Notebook interattivo che funge da suite di sperimentazione in PyTorch per la classificazione automatica di immagini di rifiuti in 8 categorie (Battery, Clothing, Glass, Metal, Organic, Papery, Plastic, Undifferentiated), con supporto a Open Set Recognition per il rigetto di campioni non riconducibili a nessuna classe nota.

Progetto sviluppato per l'esame di Machine Learning (UNISA, A.A. 2025/2026).
📄 Consulta la traccia ufficiale del progetto per il contesto e i vincoli di sviluppo completi.
📚 Report Finale (Italiano) | Final Report (English) — Analisi tecnica dei modelli, workflow sperimentale e risultati raggiunti.

Il codice non si limita ad addestrare un singolo modello: permette di configurare, eseguire e confrontare liberamente esperimenti diversi — modelli, iperparametri, strategie di augmentation, protocolli di validazione — mantenendo ogni run isolata e riproducibile.

Galleria del Notebook

📸 Cliccare per comprimere la galleria

1. Configurazione Dataset

2. Configurazione Augmentation

3. Scelta Modello

4. Configurazione Training

5. Analisi Allenamento

6. Report e Matrice di Confusione

7. Analisi Grad-CAM

8. Test Manuale da URL

Il problema

Classificare immagini di oggetti di rifiuto acquisite in condizioni eterogenee: risoluzioni diverse, sfondi variabili, immagini preprocessate (es. sfondo rimosso), più oggetti della stessa classe nella stessa foto, e categorie non pienamente rappresentate nel training set. Tre delle otto classi sono a loro volta composte da sottocategorie eterogenee (es. Glass include vetro marrone, verde e trasparente), e una classe ("Undifferentiated") raccoglie oggetti che non rientrano nelle altre sette — per questo il sistema integra un meccanismo di rigetto (OSR) oltre alla classificazione standard.

Funzionalità principali

• gestione di esperimenti multipli con salvataggio isolato per run (nessun overwrite tra prove);
• confronto strutturato tra configurazioni diverse;
• split train/validation/test configurabile, incluso K-Fold Cross Validation;
• data augmentation globale e per classe;
• training in due fasi (feature extraction + fine-tuning selettivo del backbone);
• calibrazione delle soglie di rigetto (temperature scaling + meccanismo "carveout" per le classi ambigue plastica/vetro/metallo) per l'Open Set Recognition verso la classe "Undifferentiated";
• Mixed Precision (AMP), early stopping, learning rate scheduler;
• salvataggio automatico di pesi, configurazione, metriche, grafici, report per classe e risorse computazionali (RAM, memoria GPU, throughput).

Modelli supportati

• EfficientNet-B0
• EfficientNet-B0 con Coordinate Attention (B0-CA)
• EfficientNet-B2
• EfficientNet-B3
• MobileNetV3-Small

Inizializzazione con pesi pre-addestrati; fine-tuning progressivo dei blocchi finali del backbone.

Metrica

Balanced accuracy — media dei True Positive Rate delle 8 classi — scelta per essere robusta a sbilanciamenti tra categorie.

Bal.Acc = (TPR_battery + TPR_clothing + TPR_glass + TPR_metal
           + TPR_organic + TPR_papery + TPR_plastic
           + TPR_undifferentiated) / 8

Struttura del repository

Progetto Machine Learning/
├── Waste_Classifier_Trainer.ipynb    # Notebook principale per training e validazione
├── config.yaml                       # Configurazione di default
├── requirements.txt                  # Dipendenze Python
├── scarica_dataset.py                # Script per scaricare il dataset
├── avvia_notebook.bat                # Avvio rapido su Windows
├── waste_classifier/                 # Modulo Python riutilizzabile
│   ├── __init__.py
│   └── trainer.py                    # Dataset, modelli, training e salvataggio
├── experiments/                      # Risultati generati automaticamente (per run, con timestamp)
│   └── nome_modello_timestamp/
│       ├── config.yaml
│       ├── models/
│       ├── plots/
│       └── logs/
└── dataset/                          # Dataset estratto (non incluso nel repo)

Setup

Il progetto è stato sviluppato per garantire la massima flessibilità: supporta sia l'esecuzione completa in locale sia l'esecuzione su piattaforma cloud (Google Colab), ideale qualora non si disponesse di risorse hardware adeguate o di una GPU dedicata.

Opzione A: Esecuzione in Locale

1 — Clonare e installare le dipendenze

git clone <url-del-repo>
cd "Progetto Machine Learning"
pip install -r requirements.txt

2 — Scaricare il dataset

Il dataset (~240 MB) non è incluso nel repository per motivi di dimensione. È disponibile su MEGA:

https://mega.nz/file/I7pTlAIC#a4C6Nq7DBcp01pq0LVZ7iLFMn9WetBONpA-TynLS9EE

È necessario scaricare il file .zip e salvarlo nella root del progetto come waste_type_identification.zip.

Non occorre estrarlo o lanciare script manualmente: l'interfaccia interattiva del notebook rileverà automaticamente l'archivio ZIP e gestirà l'estrazione.

3 — Avviare il notebook

È possibile interagire con il notebook in due modi, a seconda delle preferenze:

• Tramite IDE (es. VS Code, PyCharm, Cursor): Se l'editor dispone già delle estensioni per i notebook Jupyter ed è stato selezionato l'ambiente virtuale (.venv) come kernel, è sufficiente aprire il file Waste_Classifier_Trainer.ipynb direttamente nell'editor.
• Tramite browser (JupyterLab locale): Se si preferisce non usare un IDE, è possibile avviare un server Jupyter in locale. Su Windows, è sufficiente eseguire lo script avvia_notebook.bat. Lo script attiverà l'ambiente virtuale, controllerà la presenza del file ZIP e avvierà un'istanza locale di JupyterLab. (Nota: il sistema viene eseguito interamente in locale sulla propria macchina, non è un servizio online).

Opzione B: Esecuzione online (Google Colab)

Nel caso si volessero sfruttare i server gratuiti di Google, è possibile operare interamente su cloud:

1. Caricare l'intera cartella del progetto sul proprio Google Drive (di default il codice si aspetta che si trovi nel percorso Il mio Drive/Progetto Machine Learning/Image-Based-Waste-Classification, ma la variabile BASE_DIR nella prima cella del notebook è modificabile).
2. Scaricare il dataset ZIP da MEGA indicato nel punto precedente e caricarlo all'interno della medesima cartella su Drive.
3. Aprire il file Waste_Classifier_Trainer.ipynb (clic destro > Apri con > Google Colaboratory).
4. Impostare l'acceleratore hardware: Prima di avviare il codice, è estremamente consigliato abilitare la GPU per garantire tempi di addestramento ragionevoli. Dal menu in alto selezionare Runtime > Modifica tipo di runtime (o Runtime > Change runtime type), scegliere T4 GPU come acceleratore hardware e salvare.
5. Eseguire tutte le celle: la prima cella rileverà autonomamente l'ambiente Colab, monterà Google Drive per l'accesso ai file persistenti e si occuperà di installare eventuali dipendenze mancanti, estraendo il dataset nello storage locale di Colab per garantire prestazioni di lettura ottimali.

Workflow tipico

Tip

Interfaccia Pulita
Per un'esperienza d'uso ottimale, si consiglia di eseguire tutte le celle all'avvio e poi collassare (nascondere) le sezioni di codice. In questo modo è possibile interagire con l'intera suite di sperimentazione operando esclusivamente tramite i widget grafici di output.

1. Caricare/estrarre il dataset.
2. Scegliere lo split o abilitare la K-Fold Cross Validation.
3. Selezionare un modello da allenare.
4. Configurare augmentation, batch size, learning rate, epoche, scheduler.
5. Eseguire feature extraction e fine-tuning.
6. Calibrare le soglie OSR (τ e T) per il rigetto verso "Undifferentiated".
7. Analizzare balanced accuracy, curve di training, matrice di confusione.
8. I risultati vengono salvati automaticamente in experiments/.

Requisiti

• Python 3.8+
• PyTorch 2.0+
• Jupyter o JupyterLab
• GPU NVIDIA consigliata (il progetto è pensato per girare anche su Google Colab, con footprint di memoria GPU contenuto sia in training che in inferenza)

Note di design

• Il training set fornito non viene esteso: tutta la variabilità viene gestita tramite augmentation e strategie di validazione.
• Ogni run viene salvata in una cartella separata con timestamp, per confrontare esperimenti senza perdere risultati precedenti.
• Il modulo waste_classifier/trainer.py è pensato per essere riutilizzabile e indipendente dal notebook.