README.md

---
title: Computer vision e piante - percorsi 6-16 anni
emoji: 🌱
colorFrom: green
colorTo: gray
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
python_version: "3.10"
license: apache-2.0
short_description: Percorsi didattici su immagini, piante e computer vision.
startup_duration_timeout: 1h
preload_from_hub:
  - Uminosachi/FastSAM FastSAM-s.pt
---

# Computer vision e piante - percorsi 6-16 anni

Lo Space mantiene un unico indirizzo e organizza quattro percorsi progressivi:

- **6-9 anni:** preparazione di schede PDF con fotografie a quadretti;
- **9-11 anni:** esplorazione di matrici di pixel, trasformazioni additive del colore e stima automatica del verde;
- **11-14 anni:** confronto progressivo fra segmentazione HSV, indice ExG e FastSAM guidato da un punto;
- **14-16 anni:** calibrazione del riferimento, segmentazione e misura, FastSAM e metodo ibrido. La documentazione tecnica dettagliata è mantenuta separata in `README_14-16.md`.


## Avvio rapido

1. Aprire la scheda della fascia interessata.
2. Caricare una fotografia. Nei moduli 6-9 e 11-14 è anche possibile usare il dataset sperimentale incluso.
3. Seguire i pulsanti nell'ordine indicato.
4. Controllare sempre la maschera o l'anteprima prima di interpretare un risultato numerico.
5. Aprire il PDF della fascia quando servono istruzioni didattiche più dettagliate.

## Dataset sperimentale

La cartella `dataset/` contiene **48 fotografie**:

- `NS` = assenza di stress idrico;
- `S` = stress idrico;
- `A`, `B`, `C` = repliche;
- `06`, `09`, `11`, `14`, `16`, `19`, `23`, `26` = giorni dal trapianto.

Il dataset completo non viene sostituito da una selezione ridotta. Può essere utilizzato quando la classe non produce fotografie proprie o quando serve confrontare immagini acquisite con un protocollo comune.

![Organizzazione del dataset](assets/screenshots/06_dataset_annotata.png)

---

## 6-9 - Piante a quadretti

![Modulo 6-9](assets/screenshots/02_6-9_annotata.png)

### Procedura

1. Caricare una fotografia oppure selezionare condizione, replica e giorno dal dataset.
2. Inserire il titolo dell'attività.
3. Scegliere il numero di righe e colonne, da 4 a 36.
4. Regolare lo schiarimento. Il valore iniziale è `0,50`.
5. Lasciare disattivata l'opzione colore per produrre una fotografia in bianco e nero; attivarla solo quando serve conservare i colori.
6. Premere **Genera la scheda PDF**.
7. Controllare l'anteprima e scaricare il PDF.

Il PDF contiene:

- titolo dell'attività;
- fotografia schiarita con griglia;
- indicazione della dimensione della griglia;
- spazio finale per annotare a mano il numero di quadratini verdi identificati o colorati.

Il programma non riconosce la pianta, non disegna contorni automatici e non introduce il conteggio dei quadratini parziali.

Guida didattica: `assets/6-9/Guida_piante_a_quadretti.pdf`.

---

## 9-11 - Pixel, colore e confronto del verde

![Modulo 9-11](assets/screenshots/03_9-11_annotata.png)

### A scuola - un solo caricamento

La fotografia viene caricata una sola volta e alimenta entrambe le attività scolastiche.

#### 1. Esplora un patch 5 x 5

1. Caricare la fotografia condivisa.
2. Fare click su un punto dell'immagine.
3. Scegliere `RGB` oppure `HSV`.
4. Osservare il grande patch 5 x 5.

Il patch contiene i colori reali dei 25 pixel selezionati. Su ogni cella sono scritti direttamente i tre valori dello spazio scelto:

- RGB: R, G e B da 0 a 255;
- HSV: H in gradi, S e V in percentuale.

Non viene mostrata una seconda matrice numerica separata: colore e valori convivono nello stesso ingrandimento.

#### 2. Laboratorio del colore

La stessa fotografia viene trasferita automaticamente nel pennello. Non serve un secondo caricamento.

1. Dipingere la zona da modificare.
2. Scegliere spazio di colore, canale e variazione additiva.
3. Premere **Applica la modifica alla zona dipinta**.
4. Usare **Ripristina la fotografia originale** per ricominciare dallo stesso caricamento.

Per RGB i valori sono limitati fra 0 e 255. Per S e V sono limitati fra 0% e 100%. H è circolare: aumentando ripetutamente la tonalità si attraversa il cerchio cromatico e si ritorna al punto di partenza.

### Con la famiglia - Quale fotografia contiene più verde?

1. Caricare due fotografie, A e B.
2. Formulare una previsione prima di avviare il calcolo.
3. Premere **Confronta: quale fotografia contiene più verde?**.
4. Confrontare percentuali, overlay e maschere.

Le due fotografie vengono elaborate con le stesse soglie HSV. Nel risultato:

- la regione riconosciuta come verde conserva i colori originali;
- tutto il resto viene fortemente desaturato e scurito;
- la percentuale compare in grande sopra ogni fotografia;
- il valore maggiore viene evidenziato e accompagnato da una corona;
- le due maschere binarie utilizzate dal programma sono mostrate sotto i risultati.

La percentuale resta una stima prodotta dalle soglie HSV e va interpretata osservando anche le maschere.

Guida didattica: `assets/9-11/Guida_pixel_e_verde.pdf`.

---

## 11-14 - Confronta i metodi

![Modulo 11-14](assets/screenshots/04_11-14_annotata.png)

La stessa fotografia viene utilizzata in quattro passaggi progressivi.

### 1. Metodo cromatico automatico

Premere **Applica il metodo cromatico**. Lo Space usa soglie HSV iniziali e applica automaticamente una pulizia morfologica della maschera. Il kernel viene scelto in base alle dimensioni dell'immagine:

- `3 × 3` per immagini più piccole;
- `5 × 5` per immagini più grandi.

### 2. Modifica delle soglie HSV

Nel pannello **Modifica le soglie nello spazio HSV**, già visibile, è possibile cambiare:

- intervallo della tonalità H;
- saturazione minima e massima;
- luminosità minima e massima.

Questa sezione serve a osservare come una trasformazione dei limiti numerici modifica la maschera.

### 3. Indice ExG

Nel pannello **Prova l’indice ExG**, già visibile, l’indice viene calcolato per ogni pixel:

`ExG = 2G - R - B`

Il programma conserva i pixel per i quali ExG supera la soglia scelta e applica la stessa pulizia automatica usata dal metodo HSV.

### 4. FastSAM guidato da un punto

1. Caricare o selezionare la fotografia sorgente.
2. Raggiungere il pannello **Prova FastSAM**, già visibile nella sequenza.
3. Usare la copia sincronizzata dell'immagine presente nello stesso pannello: non è necessario tornare alla parte superiore della pagina.
4. Fare click sulla pianta e controllare il punto rosso.
5. Premere **Segmenta l'oggetto indicato**.
6. Attendere la comparsa della maschera e della sovrapposizione.

Il click registra soltanto il punto. L'inferenza parte dal pulsante, così è possibile correggere la selezione prima dell'elaborazione. Le celle **Maschera FastSAM** e **Sovrapposizione FastSAM** restano nascoste fino alla produzione di un risultato e non richiedono caricamenti.

FastSAM usa il punto come prompt e restituisce una maschera della regione associata all'oggetto selezionato. Il pulsante **Confronta l'ultimo metodo cromatico con FastSAM** affianca l'ultima sovrapposizione HSV o ExG alla sovrapposizione FastSAM.

Guide:

- `assets/11-14/Guida_confronto_segmentazioni.pdf`;
- `assets/11-14/Approfondimenti_tecnici_docenti.pdf`.

---

## 14-16 - Laboratorio di analisi

La sezione integra le funzioni del precedente `Plant_segmentation_edu` in sei pannelli sempre visibili:

1. caricamento unico della fotografia;
2. calibrazione automatica del riferimento, con regolazione manuale immediatamente disponibile;
3. segmentazione automatica ExG e misure, con confronto manuale fra ExG, HSV, RGB e Lab;
4. FastSAM guidato da un punto;
5. metodo ibrido automatico con più interrogazioni FastSAM e selezione finale tramite ExG;
6. esportazione e documentazione.

Il dataset è lo stesso usato nelle altre fasce e rimane presente una sola volta nella cartella `dataset/`. Il modello FastSAM è condiviso con la sezione 11-14 e viene caricato una sola volta in memoria.

La guida tecnica del precedente Space, completa delle schermate reali, è conservata separatamente: [`README_14-16.md`](README_14-16.md).

Documenti originali della sezione:

- `assets/14-16/Tutorial_setup_sperimentale.pdf`;
- `assets/14-16/Scheda_esperimento.pdf`.

## Runtime ZeroGPU con FastSAM forzato su CPU

Lo Space è predisposto per essere ospitato con hardware **ZeroGPU**, ma le funzioni visibili agli utenti restano sul processo CPU:

- griglie, PDF, pixel, HSV, ExG e pulizia delle maschere vengono eseguiti su CPU;
- FastSAM viene richiamato con `device="cpu"` e il modello viene mantenuto in cache dopo il primo caricamento;
- una funzione minima decorata con `@spaces.GPU` è presente esclusivamente per soddisfare il controllo di avvio del runtime ZeroGPU e non è collegata all'interfaccia;
- poiché la funzione decorata non viene richiamata, il normale uso dello Space non richiede l'assegnazione della GPU dinamica.

Il peso `FastSAM-s.pt` viene precaricato dal repository pubblico `Uminosachi/FastSAM` durante il build. Il codice usa `hf_hub_download` per individuare il file nella cache e non dipende dal download automatico di Ultralytics durante il primo click.

### Test dopo la pubblicazione

1. Mantenere **ZeroGPU** nelle impostazioni hardware.
2. Sostituire tutti i file del repository con quelli di questo pacchetto.
3. Eseguire un **Factory reboot** per eliminare cache e dipendenze della revisione precedente.
4. Aprire la scheda 11-14 e caricare un'immagine del dataset.
5. Aprire la sezione FastSAM: la fotografia deve comparire automaticamente nel riquadro locale.
6. Fare click sulla pianta, controllare il punto rosso e premere **Segmenta l'oggetto indicato**.
7. Verificare nei container log la dicitura di avvio e, in caso di errore, il messaggio Python generato dal pulsante. Gli avvisi del browser relativi a sensori, PixiJS, telemetria o `awswaf.com` non descrivono l'errore del modello.

## Pubblicazione nello Space esistente

Per mantenere invariati i link già presenti nelle schede:

1. aprire lo Space esistente;
2. sostituire i file con il contenuto di questa cartella, senza creare un nuovo slug;
3. verificare che `dataset/` contenga 48 immagini;
4. eseguire un Factory reboot;
5. provare prima una funzione CPU;
6. aprire FastSAM, selezionare il punto nella copia sincronizzata e avviare la segmentazione.

## Documenti allegati

- `assets/14-16/Tutorial_setup_sperimentale.pdf`;
- `assets/14-16/Scheda_esperimento.pdf`;
- `assets/6-9/Guida_piante_a_quadretti.pdf`;
- `assets/9-11/Guida_pixel_e_verde.pdf`;
- `assets/11-14/Guida_confronto_segmentazioni.pdf`;
- `assets/11-14/Approfondimenti_tecnici_docenti.pdf`.

## Fonti tecniche essenziali

- FastSAM: https://docs.ultralytics.com/models/fast-sam/
- Gradio Image: https://www.gradio.app/docs/gradio/image
- Gradio ImageEditor: https://www.gradio.app/docs/gradio/imageeditor
- Hugging Face ZeroGPU: https://huggingface.co/docs/hub/spaces-zerogpu
- Configurazione e `preload_from_hub`: https://huggingface.co/docs/hub/spaces-config-reference