README.md

---
title: Segmentazione di piante (Lattuga) – demo didattica
emoji: 🥬
colorFrom: green
colorTo: gray
sdk: gradio
app_file: app.py
python_version: "3.10"
license: apache-2.0
short_description: Demo segmentazione deterministica, AI e ibrida su piante.
---

# 🥬 Computer Vision in Agricoltura: Segmentazione

Questo Spazio mostra il funzionamento di una pipeline di segmentazione su fotografie di piante, con tre approcci confrontabili:

- **deterministico** (soglie su colore + geometria + morfologia),
- **AI** (FastSAM),
- **ibrido** (loop deterministico con chiamate AI).

L’obiettivo è rendere visibile il processo di segmentazione: non solo il risultato finale, ma anche i passaggi intermedi, i parametri, i casi limite e le differenze tra approcci.
In coda a questo documento sono allegati due pdf: 
- Tutorial per la riproduzione del setup sperimentale, in classe o a casa.
- Descrizione e analisi dei risultati di un esperimento condotto da noi nelle stesse condizioni (il dataset comune, vedi sotto).

---

## Caricamento immagine
L’interfaccia permette di iniziare da un’immagine del dataset incluso oppure da un file caricato manualmente. La demo è pensata per essere usata online: è sufficiente selezionare una foto e procedere.

![Caricamento immagine](assets/Fig1_cariacamento.JPG)

---

## Struttura generale: tre fasi
L’analisi è organizzata in tre schede:

1. **Calibrazione del riferimento**
2. **Segmentazione colore (deterministica)**
3. **Segmentazione AI (FastSAM)**

![Panoramica delle fasi](assets/Fig2_fasi.JPG)

---

## 📐 Fase 1 — Calibrazione del riferimento

In questa fase si calibra la **cornice di riferimento** presente nella fotografia. La calibrazione serve a standardizzare l’analisi e a rendere confrontabili fotografie di tempi diversi o di piante diverse, perché fornisce un’area di riferimento in pixel su cui rapportare le misure della pianta.

Sono disponibili due modalità:

### Modalità automatica (deterministica)
L’algoritmo utilizza l’informazione sul colore dello sfondo e della cornice per applicare una serie di soglie preimpostate e generare più maschere candidate. Su ciascun risultato cerca strutture compatibili con un quadrilatero (basandosi sulla presenza di linee rette), quindi confronta i risultati ottenuti nelle diverse iterazioni e propone una soluzione finale per consenso.

L’output è mostrato in tre pannelli:
- fotografia di partenza,
- maschera,
- geometria individuata (quadrilatero proposto).

![Fase 1 automatica](assets/Fig3_fase1_auto.JPG)

### Modalità manuale
La modalità manuale espone direttamente i parametri di soglia nei vari spazi di colore. È quindi possibile controllare in modo esplicito l’isolamento della cornice, modificando minimi e massimi degli assi selezionati.

È anche possibile campionare un colore direttamente dall’immagine con un click: il sistema aggiorna automaticamente i valori soglia costruendo un piccolo intervallo di tolleranza attorno al colore selezionato, che può poi essere rifinito manualmente.

In questo caso il terzo pannello mostrerà anche tutte le linee rette compatibili con la maschera individuata.

![Fase 1 manuale](assets/Fig4_fase1_manuale.JPG)

---

## 🌱 Fase 2 — Segmentazione colore (thresholding deterministico)

Questa fase isola la pianta tramite **sogliatura** (thresholding) e successiva pulizia della maschera.

La demo permette di lavorare sia su **spazi di colore** (HSV, RGB, LAB) sia su **ExG** i valori di default corrispondono a quelli generalmente ottimali, è possibile variarli per osservare gli effetti risultanti.

Nota importante **ExG (Excess Green)** non è uno spazio di colore: è un **indice** calcolato a partire dai canali RGB, molto usato per evidenziare la vegetazione.
Nella forma usata qui:
**ExG = 2G - R - B**


Dopo la sogliatura, la maschera può contenere:
- piccoli pixel isolati (rumore),
- buchi all’interno della regione segmentata,
- bordi irregolari.

La **pulizia morfologica** è un post-processing della maschera binaria che itera processi di erosione e dilatazione:
- **Opening** → rimuovere piccoli elementi/rumore : https://it.wikipedia.org/wiki/Apertura_(morfologia)
- **Closing** → chiudere piccoli buchi o interruzioni : https://it.wikipedia.org/wiki/Chiusura_(morfologia)
- **Open + Close** → combinazione dei due effetti

Come nella Fase 1, il click sull’immagine può essere usato per campionare un colore e inizializzare i parametri intorno a quel valore; il risultato viene aggiornato mostrando la segmentazione e l’output esportabile.

![Fase 2 segmentazione colore](assets/Fig5_fase2.JPG)

---
## 🧠 Nota introduttiva alla fase 3

La terza fase introduce l'utilizzo dell'AI con FastSAM. 
**FastSAM** è un piccolo e veloce “Segment Anything Model” (SAM), open source e orientato all’efficienza. 

**SAM** è un modello di segmentazione “promptable”, cioè un modello che produce maschere a partire da un prompt (ad esempio un click, un box, ecc.). 
Nella pratica, SAM è diventato un riferimento per le pipeline che usano prompt (click, box, regioni) per selezionare un oggetto, ma è molto pesante e richiede risorse computazionali importanti.

Questo progetto è pensato per essere **interattivo** e fruibile con risorse computazionali limitate. 

FastSAM è scelta utile per la demo (veloce e gratuito), ma implica un compromesso: stiamo mostrando un modello **forte ma piccolo**, e con architettura diversa dai SAM più pesanti / più recenti.

### Nota di interpretazione dei risultati (importante)
I fallimenti o i bordi non perfetti osservabili nella pipeline **AI** e **ibrida** di questa demo sono utili per capire limiti reali dei metodi, ma non vanno generalizzati.

In particolare:
- una parte dei limiti osservati dipende dalla **classe di modello** scelta,
- una parte dipende dalla **taglia del modello** e dalle risorse disponibili,
- una parte dipende dalla **pipeline locale** (le regole deterministiche introdotte da noi).

Sistemi più sofisticati (o versioni più pesanti / più recenti) riducono notevolmente questi problemi.

## 🧠 Fase 3 — Segmentazione AI (FastSAM)

La terza fase permette di confrontare due modalità operative:

- **AI con click sull’immagine** (segmentazione dell’oggetto selezionato),
- **algoritmo ibrido automatico** (loop deterministico con chiamate FastSAM).

Nel caso AI con click, il comportamento dipende dal punto selezionato: il modello segmenta l’oggetto associato a quel click.
L’esempio seguente mostra un caso importante: cliccando sul vaso, FastSAM segmenta il vaso invece della pianta.

![FastSAM: esempio di segmentazione del vaso](assets/Fig7_IA_semantica.JPG)

Nella modalità ibrida, la pipeline combina vincoli deterministici e segmentazione AI:

1. usa la cornice calibrata (Fase 1) per definire un’area valida di ricerca;
2. seleziona punti candidati all’interno dell’area (centroide e punti successivi ricavati da una logica geometrica sulla zona ancora disponibile);
3. interroga FastSAM più volte con point prompt;
4. filtra/accumula le istanze ottenute;
5. seleziona la maschera finale con una regola deterministica (ExG più alto).

![Fase 3 AI / ibrido](assets/Fig6_fase3.JPG)

---

## Casi particolari e limiti (presenti nel dataset)
Il dataset incluso contiene casi non banali, utili per osservare il comportamento reale della pipeline, ad esempio:

- casi in cui la segmentazione standard in **ExG** richiede ritocco dei parametri (campione stressato B 26 DAT),
- casi in cui la calibrazione automatica della **cornice** non è ottimale (campione non stressato B 26 DAT),
- casi in cui il metodo **ibrido** fallisce (campione stressato C 19 DAT, campione non stressato A 23 DAT ),
- casi in cui la componente **AI** seleziona o segmenta male l’oggetto (campione stressato A 9 DAT).

---

## Documenti allegati

📄 **Tutorial setup sperimentale (PDF)**  
[Apri / scarica il documento](assets/Tutorial_setup_sperimentale.pdf)


📄 **Risultati analitici e interpretazione (PDF)**  
[Apri / scarica il documento](assets/Scheda_esperimento.pdf)


---

## Approfondimenti — spazi colore, thresholding, morfologia, modelli SAM
<details>
<summary><b>Apri gli approfondimenti</b></summary>

### Video consigliato (spazi colore)
Panoramica molto chiara sugli spazi di colore (in inglese, con sottotitoli):

- https://www.youtube.com/watch?v=7KYwi2F5Ce4

---

### Segment Anything (SAM) / FastSAM / varianti efficienti

#### SAM (Segment Anything Model) — fonti ufficiali
- Paper (arXiv): https://arxiv.org/abs/2304.02643
- Repository ufficiale (Meta): https://github.com/facebookresearch/segment-anything

#### SAM 2 (immagini + video)
- Paper (arXiv): https://arxiv.org/abs/2408.00714
- Repository ufficiale (Meta): https://github.com/facebookresearch/sam2
- Pagina di ricerca Meta: https://ai.meta.com/research/sam2/

#### FastSAM (modello usato nello Space)
- Paper (arXiv): https://arxiv.org/abs/2306.12156
- Repository ufficiale: https://github.com/CASIA-IVA-Lab/FastSAM

#### Varianti/derivati efficienti o specializzati (per confronto)
- MobileSAM (lightweight SAM): https://github.com/ChaoningZhang/MobileSAM
- Paper MobileSAM / Towards Lightweight SAM for Mobile Applications: https://arxiv.org/abs/2306.14289
- HQ-SAM (high-quality masks): https://github.com/SysCV/sam-hq

---

### Spazi colore
- RGB: https://it.wikipedia.org/wiki/RGB
- HSL/HSV: https://it.wikipedia.org/wiki/HSL_e_HSV
- Spazio colore Lab: https://it.wikipedia.org/wiki/Spazio_colore_Lab

### Thresholding / sogliatura
- Metodo di Otsu: https://it.wikipedia.org/wiki/Metodo_Otsu