Prefazione

Questo libro costituisce un’opera in costante aggiornamento nei settori dell’Elaborazione Digitale delle Immagini (EDI) e della Visione Artificiale (VA), concepita come materiale didattico interattivo per corsi di laurea triennale e magistrale in Informatica, Ingegneria e settori affini.

In evidenza

L’opera si fonda sulla metodologia descritta in Zampirolli et al. (2025) — estensione di Zampirolli et al. (2024), lavoro premiato nel filone Risorse e Ambienti Educativi dell’EduComp 2024. Il contenuto integra la libreria morph.py, sviluppata dall’autore.

Questo non è un libro statico. Il suo contenuto evolve continuamente man mano che gli esempi vengono migliorati, nuove sezioni vengono incorporate e gli approcci pedagogici vengono affinati sulla base dell’esperienza d’uso e del riscontro di studenti e docenti. In tal modo, l’opera è trattata come un progetto in costante evoluzione, cercando di seguire sia i progressi tecnologici sia le migliori pratiche didattiche in EDI e VA.

Contesto della prima edizione

Il contenuto di questa edizione è stato elaborato tra maggio e agosto 2026, durante la prima offerta del corso di Elaborazione Digitale delle Immagini basata su questo materiale didattico. Il corso è stato tenuto in due classi di laurea triennale — composte prevalentemente da studenti di Informatica, nel periodo mattutino — e in una classe di laurea magistrale in Informatica, tutte presso l’UFABC. Questa prima edizione rappresenta il risultato di tale offerta iniziale, consolidando il contenuto sviluppato, testato e continuamente perfezionato nel corso del periodo accademico.

La metodologia di insegnamento adottata ha seguito una sequenza strutturata in ogni lezione. Inizialmente, veniva mostrato un video breve, della durata media di 7 minuti, generato in Gemini Notebook, alternando la presentazione della parte concettuale del capitolo e la risoluzione degli Esercizi di Programmazione (EP). In questo secondo caso, quasi tutti gli EP venivano risolti durante la stessa lezione. Successivamente, veniva presentato un insieme di circa 12 slide, anch’esse generate in Gemini Notebook, aventi come fonti il PDF completo del libro e il file morph.py. Queste slide venivano prodotte a partire da un prompt specifico per la generazione del contenuto teorico e pratico di ciascun capitolo.

Dopo questa fase iniziale, restavano circa 100 minuti di lezione per l’esplorazione dei due notebook Colab del capitolo, uno teorico e uno pratico, con enfasi sui simulatori interattivi e sull’esecuzione dei blocchi di codice, consentendo agli studenti di modificare i parametri e osservarne gli effetti. Nelle lezioni svolte in laboratorio, gli studenti trasferivano le risposte degli EP sviluppate in Colab direttamente nelle attività VPL del Moodle, dove venivano sottoposte alla valutazione automatica. Questo processo di pubblicazione e utilizzo degli EP è presentato alla fine di questa prefazione.

La valutazione continua includeva simulazioni quindicinali, somministrate con il SEB (Safe Exam Browser) in Moodle, contenenti EP simili a quelli delle liste di esercizi. Ogni simulazione concedeva un bonus del 5% sul voto finale. Anche le due prove del corso utilizzavano il SEB, ma erano composte da quesiti parametrizzati generati in MCTest, la cui descrizione combina LaTeX e parametri nel formato [[code:variabile]], definiti in sezioni di Python delimitate da [[def: ... ]] nella stessa domanda. Questo processo ha permesso di generare 110 varianti di prova, sorteggiate individualmente tra gli studenti.

L’Appendice A descrive in dettaglio la creazione di tali domande in MCTest e la loro esportazione in Moodle; l’Appendice B descrive la configurazione delle attività VPL, inclusi il processo di pubblicazione degli EP; l’Appendice C presenta la configurazione del SEB per le simulazioni e le prove; l’Appendice D descrive la generazione dei video e delle slide utilizzati nelle lezioni con Gemini Notebook; e l’Appendice E dettaglia l’uso dell’Intelligenza Artificiale (IA) nella generazione di feedback socratico per attività formative e valutative, integrando la correzione automatica effettuata dal VPL.

Come viene prodotto questo libro

Il contenuto di questo libro è sviluppato in Quarto ed è archiviato nella cartella all del repository github.com/fzampirolli/pdi-vc. A partire da un unico codice sorgente, il libro viene generato automaticamente e pubblicato in diversi formati, presentati nella Tabella 1.

Sebbene l’edizione in PDF registri lo stato dell’opera al termine della prima offerta del corso nel 2026, lo sviluppo del libro continua in modo permanente. A ogni aggiornamento del repository GitHub, vengono generate automaticamente nuove versioni delle pagine HTML, del PDF e dei notebook, mettendo immediatamente a disposizione dei lettori i miglioramenti.

Tabella 1: Diversi formati di pubblicazione generati automaticamente dallo stesso codice sorgente.

Formato	Descrizione
HTML	Versione per il web, con simulatori interattivi e navigazione tra i capitoli: fzampirolli.github.io/pdi-vc/
PDF	Versione adatta alla stampa o alla lettura offline: livro.pt.py.pdf
Notebook (`.ipynb`)	Compatibili con Jupyter e Google Colab, che consentono di eseguire, modificare e sperimentare gli esempi di codice e gli Esercizi di Programmazione (EP). Un filtro personalizzato mantiene i riferimenti incrociati, la numerazione di figure e tabelle, oltre a formattare automaticamente le citazioni secondo lo standard ABNT.

L’opera è pubblicata in dieci combinazioni — ogni percorso di codice (Python e C++) in cinque lingue (portoghese, inglese, francese, spagnolo e italiano). Con la cache di traduzione già popolata, una rigenerazione completa (traduzione, riesecuzione dei notebook, rendering di HTML e PDF e pubblicazione) richiede circa 72 minuti, con un parallelismo reale medio di ~5 processi (picco di 8); la prima generazione di una nuova lingua, con la cache vuota, è molto più lenta — circa 80 minuti per combinazione, come osservato nelle prime generazioni di spagnolo e italiano. La Tabella 2 riassume ogni combinazione (con la cache già popolata): numero di pagine del PDF e tempo di rendering. Questo tempo totale reale è molto inferiore alla somma dei tempi di ciascuna combinazione presa singolarmente (oltre 5 ore se eseguite una alla volta): su una CPU con molti core, più combinazioni vengono elaborate contemporaneamente, quindi il tempo totale non è la semplice somma dei tempi individuali.

Tabella 2: Numero di pagine del PDF e tempo di rendering per combinazione (parallelismo reale medio di ~5 processi, picco di 8). La combinazione base in Python/Portoghese si limita a renderizzare le uscite già registrate nei notebook sorgente; le altre rieseguono tutto il codice.

Combinazione	Percorso	Lingua	Pagine	Tempo di rend.
`py.pt`	Python	Portoghese (base)	654	~7 min
`py.en`	Python	Inglese	644	~31 min
`py.fr`	Python	Francese	666	~31 min
`py.es`	Python	Spagnolo	666	~31 min
`py.it`	Python	Italiano	658	~31 min
`cpp.pt`	C++	Portoghese	434	~26 min
`cpp.en`	C++	Inglese	426	~34 min
`cpp.fr`	C++	Francese	434	~38 min
`cpp.es`	C++	Spagnolo	430	~37 min
`cpp.it`	C++	Italiano	428	~35 min

Stato di validazione. Solo la combinazione py.pt (Python, portoghese) è la fonte curata: è lì che l’autore scrive, revisiona e valida tutto il contenuto. Le altre nove combinazioni — i percorsi in C++ e le traduzioni in inglese, francese, spagnolo e italiano — sono generate automaticamente, tramite traduzione con un modello linguistico e transpilazione del codice, e richiedono ancora una revisione dettagliata. Il punto più delicato è il testo incorporato in alcune figure: dove la versione tradotta non è ancora stata prodotta, l’immagine appare con testo in portoghese (ogni figura tradotta segue lo stesso suffisso di lingua degli altri file generati, ad esempio immagine_en.png).

Le pagine HTML, il PDF e i notebook disponibili nel progetto riflettono sempre lo stato più recente dello sviluppo. Quando viene pubblicata un’edizione ufficiale, essa viene identificata da un tag nel repository GitHub, consentendo di riprodurre esattamente il contenuto corrispondente a quell’edizione. In questo modo, il lettore può seguire sia l’evoluzione continua del progetto sia recuperare qualsiasi edizione ufficiale precedentemente pubblicata.

git clone https://github.com/fzampirolli/pdi-vc.git
cd pdi-vc
git checkout <tag-da-versao>

Ogni capitolo mette a disposizione due pulsanti Esegui Colab (Figura 1), che indirizzano ad ambienti complementari:

Parte Teorica, situata all’apertura di ogni capitolo, contenente i concetti presentati ed esempi di codice eseguibili;
Parte Pratica, nella sezione Parte Pratica con Esercizi di Programmazione (EP), dedicata agli esercizi e ai loro simulatori interattivi.

Figura 1: Pulsante cliccabile **Esegui Colab**, disponibile all’inizio delle parti **Teorica** e **Pratica** di ogni capitolo, che consente l’esecuzione interattiva degli esempi e degli esercizi. Nella versione PDF, esiste un *link* HTML diretto tra l’immagine del simulatore e la sua didascalia.

La generazione dei notebook è completamente automatizzata dallo script gerar_notebooks_alunos.py, che adatta il contenuto ad ambienti interattivi, consentendone l’esecuzione senza la necessità di installare Quarto.

Uso di strumenti di Intelligenza Artificiale

La concezione, il progetto pedagogico, la struttura concettuale e il contenuto fondamentale di questo libro sono di esclusiva autorship dell’autore.

Nel processo di redazione e supporto allo sviluppo, sono stati utilizzati, nelle loro versioni gratuite, strumenti di Intelligenza Artificiale (IA), come ChatGPT, Claude, DeepSeek e Gemini, impiegati strettamente come risorse ausiliarie. Il loro uso si è limitato al supporto nella revisione e nel miglioramento dello stile testuale, all’ottimizzazione della sintassi dei codici e alla generazione assistita di illustrazioni concettuali ed esempi.

Tutte le risposte e i contenuti suggeriti da questi strumenti sono stati sottoposti a analisi critica, verifica, validazione tecnica, adattamento e integrazione da parte dell’autore, che si assume la responsabilità per il testo, i codici e le risorse pedagogiche presentate. Gli strumenti di IA non sono considerati autori o coautori dell’opera, né responsabili delle decisioni intellettuali, tecniche o pedagogiche che ne fondano il contenuto.

Si sottolinea, inoltre, che i simulatori e le risorse interattive presenti nel libro — disponibili nelle versioni HTML e Jupyter Notebook (IPYNB) — sono stati progettati e implementati come parte dell’approccio pedagogico dell’opera, con l’obiettivo di offrire una sperimentazione diretta dei concetti presentati e favorire l’autonomia di apprendimento del lettore.

Distinto dall’uso editoriale sopra descritto, il pipeline di generazione multilingua (vedi “Come questo libro è prodotto”) impiega un modello linguistico come componente ingegneristica del sistema: la traduzione automatica del contenuto tra il portoghese e altre lingue, con cache incrementale che evita di ritradurre porzioni non modificate. Questa fase utilizza l’API a pagamento di DeepSeek (modello deepseek-v4-flash); il libro completo è già stato tradotto dal portoghese in inglese, francese, spagnolo e italiano, e i Capitoli da 1 a 5 dispongono inoltre di un percorso in C++ che compila ed esegue realmente — a un costo complessivo dell’ordine di pochi dollari, grazie alla cache incrementale.

La libreria `morph.hpp`

La libreria morph.hpp (Zampirolli et al., 2025) accompagna l’intera opera come strumento di supporto all’insegnamento. Il suo obiettivo non è sostituire librerie consolidate, come OpenCV, né competere con esse in prestazioni o ampiezza. Piuttosto, cerca di rendere trasparenti gli algoritmi fondamentali di Elaborazione Digitale delle Immagini e Visione Computazionale (PDI-VC), consentendo allo studente di comprenderne l’implementazione, modificare il codice e sviluppare nuove funzionalità.

È l’equivalente in C++ della morph.py: header-only (basta un #include "morph.hpp"), con gli stessi nomi di funzione nel namespace mm:: — chi già conosce mm.dil(), mm.dil0() o mm.gradm() in Python riconosce immediatamente mm::dil(), mm::dil0() e mm::gradm() in C++. Una divergenza di nome tra le due versioni è considerata un difetto della libreria, non una scelta di progetto.

Eredità Tecnica

La struttura della morph.hpp (come quella della sua controparte morph.py) ha come base strumenti di Morfologia Matematica sviluppati in Brasile, come MMachLib (Lotufo et al., 1997) e MMach (Barrera et al., 1998), oltre alla mmorph, utilizzata nell’opera di Dougherty; Lotufo (2003). Queste librerie sono state un punto di riferimento per l’insegnamento del settore per decenni.

Questa filosofia può essere osservata, ad esempio, negli operatori morfologici di dilatazione:

mm::dil0: implementazione didattica della dilatazione per elementi strutturanti planari, seguendo direttamente la definizione classica della Morfologia Matematica;
mm::dil1: implementazione didattica della dilatazione per funzioni strutturanti (kernel non planari), seguendo rigorosamente la loro formulazione matematica;
mm::dil: per impostazione predefinita, delega a mm::dil0() — la versione didattica planare, numericamente equivalente a cv::dilate per questo tipo di elemento strutturante. L’implementazione ottimizzata, basata su OpenCV (cv::dilate), entra in gioco solo se il programma viene compilato con il flag -DMM_USE_OPENCV.

Una differenza deliberata rispetto a morph.py

In Python, mm.dil() (senza suffisso) è già l’implementazione ottimizzata per impostazione predefinita. In C++, mm::dil() (stesso nome, stessa firma) diventa la versione ottimizzata solo se OpenCV viene collegato esplicitamente in fase di compilazione; senza di ciò — che è proprio il caso predefinito, incluso su Moodle/VPL — mm::dil() si comporta come mm::dil0(). Questa scelta evita che il percorso C++ dipenda da OpenCV solo per compilare ed eseguire un esercizio semplice: g++ file.cpp -o file è già sufficiente. Chi desidera la versione accelerata in locale può compilare con g++ -DMM_USE_OPENCV file.cpp -o file $(pkg-config --cflags --libs opencv4).

La libreria offre anche funzioni per lettura, visualizzazione, conversione dei colori, filtraggio e morfologia matematica tramite un’interfaccia semplice:

#include "morph.hpp"

int main() {
    mm::Image img = mm::gray(mm::read("lena.jpg"));  // lettura e conversione in scala di grigi
    mm::Image grad = mm::gradm(img);                 // gradiente morfologico
    mm::show(grad, "output.png");                    // visualizzazione (scrive su file)
}

A differenza della versione Python, mm::show() richiede un percorso di output esplicito: ogni cella di codice C++ del libro viene eseguita come processo isolato (compilato ed eseguito tramite %%writefile + !g++ ... su Colab), senza il contatore globale delle figure che ha senso solo all’interno di un unico processo Jupyter.

Inoltre, tutti i progetti del Gemini Notebook del percorso C++ includono il file morph.hpp, consentendo di consultare e discutere direttamente l’implementazione degli algoritmi presentati nel libro. In questo modo, lo studente può utilizzare il Gemini Notebook stesso come assistente di studio, ponendo domande come:

Spiega come è stata implementata la funzione mm::dil0 di morph.hpp, mostrando il codice e commentando ogni fase in modo didattico. Spiega inoltre la differenza tra mm::dil0() e mm::dil() senza il flag -DMM_USE_OPENCV.

Implementazioni didattiche e implementazioni ottimizzate

In diversi capitoli, lo stesso algoritmo viene presentato in due versioni. Le funzioni con suffisso 0, 1, ecc. (ad esempio, mm::dil0() e mm::dil1()) sono implementazioni didattiche, sviluppate per facilitare la comprensione degli algoritmi e disponibili indipendentemente dal flag di compilazione. Le funzioni senza suffisso (come mm::dil()), invece, utilizzano l’implementazione ottimizzata basata su OpenCV solo quando compilate con -DMM_USE_OPENCV; altrimenti si comportano come la versione didattica corrispondente.

Nelle attività valutate dal VPL del Moodle, la compilazione segue la modalità predefinita senza -DMM_USE_OPENCV — non per limiti di memoria (come accade con scikit-learn/scikit-image nel percorso Python), ma affinché nessun EP in C++ dipenda dalla presenza di OpenCV nell’ambiente di esecuzione. In pratica, ciò significa che, nel VPL, mm::dil() e mm::dil0() producono esattamente lo stesso risultato. In locale — ad esempio in VS Code o Google Colab — lo studente può scegliere di compilare con -DMM_USE_OPENCV per confrontare con la versione ottimizzata.

Il codice sorgente della libreria è disponibile presso:

https://github.com/fzampirolli/pdi-vc/tree/master/morph/cpp

Esercizi di Programmazione (EP) e Validazione Automatica

Ogni unità del libro include Esercizi di Programmazione (EP) pratici e di complessità crescente, progettati per consolidare i concetti presentati nel corso del capitolo. Ogni EP è accompagnato da un simulatore interattivo, disponibile nelle versioni HTML e IPYNB, che consente allo studente di manipolare parametri, visualizzare il comportamento degli algoritmi e sviluppare una comprensione intuitiva del problema prima di iniziare la sua implementazione. In questo modo, il processo di apprendimento combina sperimentazione, programmazione e validazione automatica.

La validazione delle soluzioni viene effettuata localmente dalla classe TestSuite (testsuite.py), che confronta l’output del programma con i file dei casi di test (.cases):

TestSuite("EP01_01.py").run()

Il sistema supporta più linguaggi (Python, Java, C++, C, JavaScript e R) e può essere integrato direttamente in Moodle. Per i docenti interessati alla procedura completa passo passo di pubblicazione degli EP come attività VPL, si consulti la Guida per il Docente, alla fine di questa prefazione, e l’Appendice B.

Codice aperto

Il progetto è disciplinato da principi di codice aperto. Il repository pubblico riunisce il testo, i codici, le immagini e gli script: github.com/fzampirolli/pdi-vc

Ogni versione del libro è archiviata in modo permanente su Zenodo con un DOI citabile. Per citare questo materiale in lavori accademici:

ZAMPIROLLI, Francisco de Assis. PDI+VC — Elaborazione Digitale delle Immagini e Visione Artificiale. UFABC, 2026. DOI: 10.5281/zenodo.20784605

Va altresì registrato, a proposito, che il contenuto esposto in quest’opera riflette lo sguardo critico, la proposta pedagogica e l’esperienza didattica del suo autore. Pertanto, le analisi, gli approcci e le opinioni espressi lungo questo libro rappresentano esclusivamente la comprensione del suo ideatore, non costituendo né riflettendo una posizione ufficiale o istituzionale dell’Università Federale dell’ABC (UFABC).

Prima di iniziare: Notebook in Python

Il concetto di Literate Programming (Programmazione Letterata), proposto da Donald Knuth (Knuth, 1984), costituisce il fondamento della struttura di questo materiale. La logica inverte il paradigma tradizionale: il programma è scritto per la lettura umana, assimilabile a un saggio, mentre il codice viene estratto separatamente per l’esecuzione computazionale.

Il contenuto è strutturato in notebook — documenti che intercalano celle di testo (in Markdown) e celle di codice (in Python).

Esecuzione: le celle di codice sono identificate da [ ]. L’esecuzione può essere effettuata con Shift + Enter o tramite il pulsante ▶️ dell’interfaccia.
Ambienti: i notebook possono essere eseguiti localmente, tramite Jupyter o Visual Studio Code (VS Code), nonché in ambienti cloud, come Google Colab.

Nota sul formato

In ambienti interattivi, il codice può essere modificato ed eseguito. Nelle versioni statiche (HTML o PDF), i blocchi di codice hanno finalità di lettura e riferimento, senza pregiudicare l’integrità delle spiegazioni.

Guida per il Docente: Pubblicazione degli EP su Moodle

Questa sezione è destinata ai docenti che desiderano integrare gli Esercizi di Programmazione (EP) nelle attività VPL (Virtual Programming Lab) di Moodle, integrando l’Appendice B.

Integrazione con Moodle (VPL)

Gli EP dei notebook possono essere convertiti in attività VPL su Moodle. Lo script ep_tools.py (eseguito tramite make build) automatizza l’esportazione degli EP dalla fine di ogni capitolo in due fasi:

Estrazione (make eps): genera un HTML interattivo autonomo per ogni EP, con enunciato, esempi e simulatore, in gen/book/eps/<versione>/. Vedi l’elenco completo su: https://fzampirolli.github.io/pdi-vc/eps/py.pt/index.html
Conversione (make moodle): trasforma l’HTML in un frammento autocontenuto, senza dipendenza da CSS esterni, pronto per essere incollato nell’editor di Moodle, in gen/book/eps/<versione>_moodle/. Vedi un esempio su: https://fzampirolli.github.io/pdi-vc/eps/py.pt_moodle/EP01_01.html

Inoltre, tutti i simulatori interattivi sviluppati nel corso del libro possono essere consultati direttamente su https://fzampirolli.github.io/pdi-vc/simuladores/py.pt/.

Altri percorsi e lingue

I link sopra usano py.pt come esempio. Per accedere agli EP o ai simulatori di un’altra combinazione linguaggio/lingua, basta sostituire quel segmento nell’URL — ad esempio, cpp.it per il percorso C++ in italiano: https://fzampirolli.github.io/pdi-vc/eps/cpp.it/index.html. La struttura è la stessa per tutte le combinazioni disponibili, in /eps/<versione>/, /eps/<versione>_moodle/ e /simuladores/<versione>/.

Pubblicando con make publish, queste due versioni di ogni EP sono disponibili nei link indicati. Il docente può combinare le due strategie: incollare la versione Moodle nell’editor VPL (con simulatore funzionante) e includere nell’enunciato un link alla versione completa, dove le formule vengono renderizzate correttamente da MathJax.

Revisione obbligatoria prima della pubblicazione su Moodle

Sebbene automatizzata, la conversione richiede una revisione da parte del docente a causa delle limitazioni dell’editor TinyMCE/HTML Purifier di Moodle:

Formule matematiche — TinyMCE elimina le barre rovesciate (\), corrompendo le equazioni LaTeX. Per questo motivo, la versione Moodle converte le formule semplici in HTML puro (entità come ≥, ×). Le formule complesse (\begin{cases}, matrici, integrali) possono risultare incomplete — verifica e, se necessario, riscrivile in testo o indica la versione completa tramite link.
Figure esterne — Le immagini complementari devono essere inserite manualmente nell’attività VPL.
Simulatori — Funzionano perfettamente purché utilizzino JavaScript standard con stili inline e manipolazione diretta del DOM (getElementById). Attenzione: se si includono formule in LaTeX contenenti il carattere \ in Moodle, i simulatori potrebbero smettere di funzionare.

Come Pubblicare su Moodle

Accedi alla versione Moodle dell’EP desiderato:

https://fzampirolli.github.io/pdi-vc/eps/py.pt_moodle/EPXX_YY.html

Copia il codice sorgente completo della pagina (Ctrl+U → Ctrl+A → Ctrl+C).
Su Moodle, crea l’attività VPL, accedi all’editor HTML, incolla il contenuto (Ctrl+V) e salva.
Importa i file .cases dalla cartella all/capXX/casos/ nelle impostazioni dei test VPL.

Riutilizzo dei Casi di Test

I file .cases sono compatibili con VPL, consentendo di utilizzare lo stesso set di test sia nello sviluppo locale che nella correzione automatizzata su Moodle.