docs/NOTEBOOKS_GUIDE_IT.md

GraphoLab — Guida ai Laboratori

Guida pratica ai laboratori dimostrativi di GraphoLab sulla grafologia forense assistita dall'AI (8 lab).

---

Panoramica

La grafologia forense è l'esame scientifico della scrittura a mano e delle firme a supporto delle indagini legali. L'AI e il machine learning possono automatizzare e scalare molti compiti che gli esperti svolgono tradizionalmente in modo manuale:

Compito	Approccio AI	Applicazione Forense
Trascrizione di testo manoscritto	Transformer OCR (TrOCR / EasyOCR)	Lettere anonime, documenti storici
Autenticità della firma	Siamese Neural Network (SigNet)	Assegni, contratti, testamenti
Localizzazione firma nei documenti	Object Detection (Conditional DETR)	Pipeline di analisi documentale
Identificazione dello scrittore	Estrazione feature + classificatore	Paternità contestata
Analisi caratteristiche grafologiche	OpenCV + ML	Profiling, analisi comparativa
Riconoscimento entità nominate	Classificazione token (BERT-NER)	Persone, luoghi, organizzazioni nei documenti
OCR profondo (corsivo italiano)	Vision-Language Model (dots.ocr 1.7B)	Testamenti, corsivo, documenti complessi

---

Lab 01 — Introduzione: AI e Grafologia Forense

File: notebooks/01_intro_forensic_graphology.ipynb

Notebook in stile presentazione, senza codice eseguibile. Tratta:

• Cos'è la grafologia forense e perché è importante
• I limiti dell'analisi puramente manuale
• Come l'AI/ML può potenziare il lavoro dell'esperto
• Mappa concettuale dell'intera pipeline: acquisizione → preprocessing → analisi AI → referto forensico
• Panoramica di tutti i laboratori successivi

Prerequisiti: Nessuno. Destinatari: Tutti i livelli, inclusi stakeholder non tecnici.

---

Lab 02 — Riconoscimento del Testo Manoscritto (HTR/OCR)

File: notebooks/02_handwritten_ocr_trocr.ipynb

Utilizza TrOCR (microsoft/trocr-base-handwritten su Hugging Face) per trascrivere automaticamente testo manoscritto da immagini.

Cosa imparerai:

• Come funziona l'OCR basato su Transformer (encoder visivo BEiT + decoder testuale RoBERTa)
• Come caricare ed eseguire un modello HTR pre-addestrato tramite la libreria transformers
• Come preprocessare immagini di testo manoscritto per il modello
• Come interpretare e visualizzare l'output della trascrizione

Flusso della demo:

1. Caricare un'immagine di testo manoscritto da data/samples/
2. Eseguire l'inferenza con TrOCR
3. Visualizzare l'immagine originale affiancata al testo trascritto
4. (Opzionale) Confrontare con la trascrizione di riferimento e calcolare il CER (Character Error Rate)

Casi d'uso forensi:

• Trascrizione automatica di lettere minatorie anonime
• Digitalizzazione di documenti giudiziari manoscritti storici
• Fase di pre-elaborazione per pipeline di identificazione dell'autore

Prerequisiti: transformers, torch, Pillow

EasyOCR vs TrOCR — Confronto architetturale

L'app Gradio usa EasyOCR invece di TrOCR per l'inferenza interattiva. EasyOCR non è un Transformer — utilizza una pipeline classica CNN + RNN:

	EasyOCR	TrOCR
Architettura	CNN + BiLSTM + CTC	Transformer encoder-decoder
Rilevamento testo	CRAFT (mappa di calore CNN)	— (input a livello di riga)
Encoder visivo	CNN VGG-based	BEiT (Vision Transformer)
Decoder	LSTM bidirezionale + CTC	RoBERTa
Contesto linguistico	Limitato (LSTM locale)	Ampio (self-attention globale)
Velocità su CPU	~1–3 s/immagine	~10–20 s/immagine
Qualità corsivo italiano	Discreta	Migliore
Memoria RAM	~200 MB	~400 MB

Quando usare quale: EasyOCR è la scelta giusta per le demo interattive (veloce, poco memoria). TrOCR — e soprattutto dots.ocr (Lab 08) — sono preferibili quando la qualità della trascrizione su corsivo italiano complesso è prioritaria.

---

Lab 03 — Verifica dell'Autenticità della Firma

File: notebooks/03_signature_verification_siamese.ipynb

Utilizza una Siamese Neural Network (architettura SigNet) per confrontare due immagini di firme e determinare se la firma in esame è autentica o contraffatta.

Cosa imparerai:

• Il paradigma della rete siamese per il one-shot similarity learning
• Come SigNet codifica le immagini di firme in vettori di feature
• Come calcolare uno score di similarità (o distanza) tra due firme
• Come impostare una soglia decisionale per la classificazione autentica / contraffatta

Flusso della demo:

1. Caricare una firma di riferimento e una firma in esame da data/samples/
2. Estrarre gli embedding di feature con il codificatore SigNet
3. Calcolare lo score di similarità coseno
4. Visualizzare: verdetto autentica / contraffatta + score di confidenza

Casi d'uso forensi:

• Verifica di firme su assegni bancari
• Autenticazione di firme su contratti, testamenti e atti legali
• Rilevamento di firme tracciate o riprodotte digitalmente

Prerequisiti: torch, scikit-image, Pillow

Nota: I pesi SigNet pre-addestrati (models/signet.pth) sono stati addestrati sul dataset di firme GPDS. I campioni demo provengono dal database CEDAR (data/samples/genuine_N_M.png / forged_N_M.png) e sono stati pre-selezionati affinché il modello rilevi correttamente la contraffazione.

Riferimento: luizgh/sigver — implementazione SigNet e pesi pre-addestrati.

Generalizzazione a firmatari non presenti nel training set

SigNet utilizza il metric learning (rete siamese con contrastive loss), non un classificatore tradizionale. Questa è una distinzione architetturale fondamentale:

• Un classificatore impara "chi è la persona X" — non può generalizzare a identità mai viste.
• Un modello siamese/metrico impara "queste due firme provengono dalla stessa mano?" — la domanda è indipendente dall'identità e generalizza a qualsiasi firmatario, inclusi quelli mai visti durante il training.

In pratica, SigNet può essere applicata a qualsiasi coppia di firme, indipendentemente dal fatto che il firmatario sia presente in GPDS o CEDAR.

Limitazioni note:

Limitazione	Dettaglio
Bias culturale/stilistico	GPDS contiene principalmente firme brasiliane/portoghesi; firme italiane o non latine possono uscire dalla distribuzione di training
Calibrazione della soglia	La soglia 0.35 (distanza coseno) è ottimizzata su CEDAR; per firmatari con stile insolitamente compatto o elaborato potrebbe richiedere aggiustamenti
Tipo di falsificazione	Addestrato su skilled forgeries (il falsificatore ha praticato la firma); le performance su falsificazioni rozze sono generalmente migliori, su quelle professionali comparabili a un esperto umano
Qualità dell'immagine	Le performance degradano con foto di documenti su carta colorata, piegata o con timbri sovrapposti

Indicazione pratica: Usare SigNet come strumento di screening di primo livello. Non è certificato per testimonianza forense legale autonoma; i risultati devono sempre essere revisionati da un esaminatore qualificato.

---

Lab 04 — Rilevamento Firma nei Documenti (Conditional DETR)

File: notebooks/04_signature_detection_detr.ipynb

Utilizza un modello Conditional DETR fine-tuned per il rilevamento di firme (tech4humans/conditional-detr-50-signature-detector su Hugging Face) per localizzare automaticamente le firme all'interno di documenti scansionati.

Cosa imparerai:

• Come funziona la rilevazione di oggetti Conditional DETR nel contesto dell'analisi documentale
• Come caricare un modello Hugging Face con la libreria transformers
• Come eseguire l'inferenza su immagini di documenti e interpretare i bounding box
• Come visualizzare le regioni rilevate e ritagliarle per l'elaborazione successiva

Flusso della demo:

1. Caricare un'immagine di documento scansionato da data/samples/
2. Eseguire l'inferenza Conditional DETR
3. Disegnare i bounding box attorno alle firme rilevate
4. Ritagliare e salvare ciascuna firma rilevata per l'uso nel Lab 03

Casi d'uso forensi:

• Estrazione automatica di firme da documenti legali multi-pagina
• Primo passo di una pipeline: rileva → estrai → verifica
• Screening di grandi archivi documentali per la presenza di firme

Prerequisiti: transformers, timm, opencv-python, Pillow

---

Lab 05 — Identificazione dello Scrittore

File: notebooks/05_writer_identification.ipynb

Confronta le caratteristiche stilistiche di un campione manoscritto anonimo con un insieme di campioni di riferimento noti per attribuire la paternità del documento.

Cosa imparerai:

• Come estrarre feature stilistiche della scrittura: HOG (Histogram of Oriented Gradients), LBP (Local Binary Patterns) e statistiche di run-length orizzontali/verticali
• Come costruire una pipeline di identificazione basata su SVM con scikit-learn (StandardScaler + SVC con kernel RBF)
• Come valutare l'accuratezza dell'identificazione tramite cross-validation
• Come presentare i risultati come lista ordinata di autori candidati con punteggi di probabilità

Flusso della demo:

1. Caricare il database di campioni di riferimento da data/samples/writer_XX/ (cinque scrittori, 41 campioni ciascuno)
2. Estrarre le feature HOG + LBP + run-length da ciascun campione
3. Addestrare un classificatore SVM (C=10, gamma="scale", probability=True)
4. Caricare un campione anonimo → lista ordinata di candidati con punteggi di probabilità

Casi d'uso forensi:

• Attribuzione di lettere minatorie anonime
• Verifica della paternità di documenti contestati
• Ricerca sulla provenienza di documenti storici

Prerequisiti: scikit-learn, scikit-image, Pillow, numpy

Nota sul dataset: La demo utilizza un database di scrittura sintetica in data/samples/writer_XX/ (cinque scrittori, 41 campioni ciascuno) generato con font TTF di sistema (Ink Free, Lucida Handwriting, Segoe Print, Segoe Script, Comic Sans) per garantire stili distinti e riproducibili. Per uso in produzione, sostituire con scansioni reali di scrittura a mano. Il IAM Handwriting Database è il benchmark forense standard.

---

Lab 06 — Analisi delle Caratteristiche Grafologiche

File: notebooks/06_graphological_feature_analysis.ipynb

Estrae e visualizza automaticamente le caratteristiche grafologiche di un campione di testo manoscritto utilizzando la computer vision classica e l'elaborazione del segnale.

Cosa imparerai:

• Come segmentare la scrittura in parole e caratteri con OpenCV
• Come misurare: angolo di inclinazione delle lettere, spaziatura parole/caratteri, altezza e larghezza delle lettere, pressione del tratto (distribuzione dell'intensità dei pixel)
• Come costruire una dashboard visiva delle metriche grafologiche
• Come confrontare due campioni ed evidenziare le differenze

Flusso della demo:

1. Caricare un'immagine di testo manoscritto da data/samples/
2. Pre-elaborare (binarizzare, denoisare, raddrizzare)
3. Segmentare in righe, parole e caratteri
4. Calcolare e visualizzare le metriche con annotazioni sull'immagine
5. (Opzionale) Confrontare due campioni affiancati

Casi d'uso forensi:

• Supporto alla testimonianza peritale con misurazioni oggettive e riproducibili
• Rilevamento di indicatori di stress nella scrittura (variazione della pressione del tratto)
• Analisi comparativa tra un campione di riferimento e un documento contestato

Prerequisiti: opencv-python, numpy, matplotlib, scipy

---

Lab 07 — Riconoscimento Entità Nominate (NER)

File: notebooks/07_named_entity_recognition.ipynb

Utilizza un modello BERT-NER multilingue (Babelscape/wikineural-multilingual-ner) per estrarre automaticamente entità nominate — persone, organizzazioni, luoghi — da qualsiasi testo. Ideale come secondo passo dopo la trascrizione HTR.

Cosa imparerai:

• Come funziona la classificazione token BERT (schema BIO)
• Come caricare ed eseguire una pipeline NER multilingue tramite transformers
• Come visualizzare gli span di entità con evidenziazione colorata
• Come costruire una pipeline completa HTR → NER per l'analisi di documenti manoscritti

Flusso della demo:

1. NER su testo italiano (es. testamento o dichiarazione)
2. NER su testo inglese (supporto multilingue)
3. Pipeline completa: immagine manoscritto → trascrizione TrOCR → estrazione entità NER
4. Analisi della distribuzione delle entità e della confidenza

Casi d'uso forensi:

• Identificare automaticamente persone, luoghi e organizzazioni in documenti manoscritti
• Analizzare lettere anonime alla ricerca di nomi propri (nomi, indirizzi)
• Costruire un grafo delle relazioni tra entità in un corpus documentale

Prerequisiti: transformers, torch, opencv-python, Pillow, matplotlib

---

Lab 08 — dots.ocr: OCR con Vision-Language Model

File: notebooks/08_dots_ocr_vlm.ipynb

Utilizza dots.ocr (rednote-hilab/dots.ocr) — un Vision-Language Model da 1,7 miliardi di parametri — per trascrivere testo manoscritto da immagini di documenti. A differenza degli OCR CNN, il componente LLM sfrutta il contesto linguistico per correggere le ambiguità visive, risultando più efficace sul corsivo italiano.

Cosa imparerai:

• Come l'OCR basato su VLM si differenzia da TrOCR ed EasyOCR (tabella comparativa delle architetture)
• Come eseguire un check hardware e scegliere la configurazione di inferenza giusta (CPU / GPU)
• Come caricare ed eseguire dots.ocr via transformers con dtype e attention adattativi
• Come misurare e confrontare la qualità della trascrizione (CER) tra EasyOCR e dots.ocr

Flusso della demo:

1. Check hardware — rileva GPU/RAM e seleziona automaticamente CPU fp32 o CUDA bf16
2. Caricamento dots.ocr da Hugging Face (~3,5 GB bf16, ~7 GB fp32)
3. Trascrizione di un campione writer_00 (immagine singola 320×140)
4. Trascrizione del documento completo testamento_writer00.png
5. Trascrizione di campioni reali dal dataset Lorella
6. Confronto EasyOCR vs dots.ocr affiancati + misurazione CER

Casi d'uso forensi:

• OCR di alta qualità su scrittura corsiva italiana
• Documenti con tabelle, formule o layout complessi
• Quando i risultati di EasyOCR non sono sufficienti per i requisiti di accuratezza forense

Prerequisiti: transformers>=4.49, qwen_vl_utils, torch, Pillow, psutil, accelerate

Nota hardware: Su CPU (~7 GB RAM libera), l'inferenza richiede 2–5 min per immagine. Su GPU ≥8 GB VRAM, 5–10 secondi. Non adatto a demo interattive in tempo reale — usare EasyOCR nell'app Gradio.

Installazione (una tantum — vedi cella nel notebook):

git clone https://github.com/rednote-hilab/dots.ocr.git DotsOCR
pip install -e DotsOCR
pip install qwen_vl_utils accelerate

Riferimento: arxiv 2512.02498 — RedNote / Xiaohongshu, dic 2024.

---

Demo Interattiva (Gradio)

File: app/grapholab_demo.py

Un'applicazione Gradio multi-tab accessibile da browser (completamente in italiano) che aggrega nove funzionalità AI:

Tab	Funzionalità
OCR Manoscritto	Carica un'immagine (riga singola o multi-riga) → testo trascritto (EasyOCR)
Verifica Firma	Carica due firme → verdetto autentica / falsa
Rilevamento Firma	Carica un documento → immagine annotata con firme rilevate
Riconoscimento Entità	Inserisci testo → entità evidenziate + tabella riepilogativa
Identificazione Scrittore	Carica un campione di scrittura → lista di autori candidati con punteggi di probabilità
Analisi Grafologica	Carica testo manoscritto → dashboard di metriche visive
Perizia Forense Automatica	Carica documento (+ firma opzionale) → referto forense completo (7 step: rilevamento firma, HTR, NER, identificazione scrittore, grafologia, verifica firma, sintesi LLM via Ollama)
Datazione Documenti	Carica più immagini di documenti → ordinamento cronologico per data estratta (EasyOCR + dateparser)
Consulente Forense IA	Chatbot RAG: carica PDF/DOCX per arricchire la knowledge base, poi fai domande con risposta generata da un LLM Ollama locale

Avvio in locale:

# Crea e attiva un virtual environment (consigliato)
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
python app/grapholab_demo.py
# Apri http://localhost:7860

---

Esecuzione con Docker

# JupyterLab su http://localhost:8888  (token: grapholab)
docker compose up jupyter

# Demo Gradio su http://localhost:7860
docker compose up gradio

# Entrambi i servizi insieme
docker compose up

La cache dei modelli Hugging Face è memorizzata in un volume Docker dedicato (grapholab-hf-cache) e condivisa tra i due servizi. I modelli vengono scaricati una sola volta.

---

Dati di Esempio

Le immagini di esempio si trovano in data/samples/:

File	Usato in
handwritten_text_*.png	Lab 02, 05, 06
signature_genuine_*.png	Lab 03, 04
signature_forged_*.png	Lab 03
document_with_signature_*.png	Lab 04

È possibile sostituire o integrare questi file con immagini proprie per sperimentare con casi reali.