docs/DEMO_CHECKLIST_IT.md

GraphoLab — Lista della Spesa per la Demo

Tutto ciò che serve per eseguire tutti e otto i notebook GraphoLab dall'inizio alla fine: quali modelli AI vengono scaricati automaticamente e quali immagini campione devi fornire tu.

---

Riepilogo Rapido

Cosa	Dove	Note
Ambiente Python	locale o Docker	vedi NOTEBOOKS_GUIDE_IT.md
requirements.txt installato	—	pip install -r requirements.txt
Pesi SigNet	models/signet.pth	download manuale — vedi sezione Lab 03
Immagini campione	data/samples/	vedi le sezioni per lab qui sotto
Modelli AI	scaricati automaticamente	connessione internet necessaria al primo avvio

---

Modelli AI — Scaricati Automaticamente

Tutti i modelli Hugging Face vengono recuperati al primo avvio e memorizzati nella cache locale (o nel volume Docker grapholab-hf-cache).

Modello	Scaricato da	Dimensione	Cache
TrOCR (microsoft/trocr-base-handwritten)	transformers	~400 MB	~/.cache/huggingface/
EasyOCR (modelli italiano + inglese)	easyocr	~100 MB	~/.EasyOCR/
Rilevatore firme Conditional DETR (tech4humans/conditional-detr-50-signature-detector)	transformers	~170 MB	~/.cache/huggingface/
WikiNEural NER (Babelscape/wikineural-multilingual-ner)	transformers	~700 MB	~/.cache/huggingface/
dots.ocr (rednote-hilab/dots.ocr)	transformers	~3,5 GB (bf16) / ~7 GB (fp32 CPU)	~/.cache/huggingface/

È necessaria una connessione internet al primo avvio dei Lab 02, 04, 07 e 08. Le esecuzioni successive utilizzano i modelli in cache.

dots.ocr (Lab 08) richiede anche un git clone una tantum — vedi la cella di installazione nel notebook.

Modelli AI — Download Manuale Richiesto

Modello	File	Dimensione	Fonte
SigNet (pre-addestrato su GPDS)	models/signet.pth	~63 MB	luizgh/sigver

Scarica signet.pth dal repository sigver e inseriscilo nella directory models/ prima di eseguire il Lab 03.

---

Immagini Campione — Cosa Devi Fornire

Inserisci tutte le immagini in data/samples/. Quando le immagini reali mancano, vengono generate automaticamente immagini sintetiche di fallback, quindi i notebook vengono sempre eseguiti — ma i risultati su dati sintetici non hanno valore forense reale.

Lab 01 — Introduzione

Nessuna immagine richiesta. Notebook solo testuale.

---

Lab 02 — Riconoscimento Testo Manoscritto (TrOCR)

File	Descrizione
handwritten_text_01.png	Una riga di testo manoscritto
handwritten_text_02.png	(opzionale) Secondo campione su riga singola
handwritten_multiline_01.png	Un documento manoscritto multiriga (per la pipeline HTR→NER)

Requisiti:

• Scansione o foto nitida di testo manoscritto
• Risoluzione consigliata: 300 DPI o superiore
• Sfondo bianco o chiaro, inchiostro scuro
• TrOCR è un modello a livello di riga; le immagini multiriga vengono suddivise automaticamente per proiezione orizzontale prima dell'inferenza

Confronto con trascrizione nota (opzionale): se disponi della trascrizione esatta del testo manoscritto, puoi calcolare il Character Error Rate (CER) nella sezione opzionale del Lab 02.

---

Lab 03 — Verifica della Firma (SigNet)

File	Descrizione
genuine_N_1.png	Firma di riferimento — autentica nota (scrittore N, campione 1)
genuine_N_2.png	Seconda firma autentica dello stesso scrittore
forged_N_M.png	Firma contraffatta (scrittore N, falsificazione M)

Ripeti per ogni scrittore che vuoi dimostrare (es. N = 1, 2, 3, …).

Requisiti:

• Firme isolate (nessun testo del documento circostante)
• Sfondo bianco o chiaro, inchiostro scuro
• Qualità di scansione uniforme tra i campioni della stessa persona
• Risoluzione consigliata: 300 DPI o superiore

Campioni demo pre-selezionati: il repository include coppie curate dal database di firme CEDAR. Queste coppie sono state pre-scansionate con SigNet per verificare che il modello classifichi correttamente la contraffazione (distanza coseno > 0.35). Gli scrittori 1–5 corrispondono agli scrittori CEDAR 51, 26, 34, 32 e 21.

Pesi SigNet richiesti: scarica models/signet.pth da luizgh/sigver prima di eseguire questo lab.

---

Lab 04 — Rilevamento Firma nei Documenti (Conditional DETR)

File	Descrizione
document_with_signature_01.png	Una pagina di documento scansionata con almeno una firma

File aggiuntivi opzionali: document_with_signature_02.png, document_with_signature_03.png, …

Requisiti:

• Immagine dell'intera pagina del documento (non una firma già ritagliata)
• Il modello gestisce pagine con più firme
• Risoluzione consigliata: 200–300 DPI
• Funziona su contratti, lettere, moduli, assegni bancari

Output: le firme rilevate vengono ritagliate e salvate come detected_signature_N.png in data/samples/. Questi ritagli possono essere usati direttamente come input per il Lab 03.

---

Lab 05 — Identificazione dello Scrittore

Organizzato in sottodirectory per scrittore all'interno di data/samples/:

data/samples/
  writer_01/
    sample_01.png
    sample_02.png
    sample_03.png
    sample_04.png
    sample_05.png
  writer_02/
    sample_01.png
    ...
  writer_03/
    sample_01.png
    ...

Requisiti:

• Minimo 3 scrittori (di più = maggiore accuratezza)
• Minimo 5 campioni per scrittore (il notebook usa la cross-validation leave-one-out)
• Ogni campione: alcune righe di testo manoscritto continuo
• Condizioni di scansione uniformi per tutti i campioni
• Risoluzione consigliata: 300 DPI

Nota sull'addestramento: il Lab 05 addestra un classificatore SVM leggero sui campioni forniti ad ogni esecuzione del notebook. Non viene utilizzato nessun modello pre-addestrato per l'identificazione dello scrittore — i tuoi campioni sono i dati di addestramento.

---

Lab 06 — Analisi delle Caratteristiche Grafologiche

Riutilizza le immagini di testo manoscritto del Lab 02:

File	Descrizione
handwritten_text_01.png	Campione principale per l'estrazione delle caratteristiche
handwritten_text_02.png	(opzionale) Secondo campione per il confronto affiancato

Non sono necessari file aggiuntivi se i campioni del Lab 02 sono già presenti.

---

Lab 07 — Riconoscimento Entità Nominate (NER)

Nessun file immagine richiesto. Il modello NER opera direttamente su stringhe di testo.

• Demo 1 & 2: testi di esempio italiani e inglesi inclusi nel notebook — nessun file necessario.
• Demo 3 (pipeline HTR→NER): carica handwritten_multiline_01.png (condiviso con il Lab 02).

Il modello Babelscape/wikineural-multilingual-ner (~700 MB) viene scaricato automaticamente al primo avvio. Supporta 9 lingue tra cui italiano e inglese.

---

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

File	Descrizione
writer_00/sample_000.png	Campione singolo writer_00 (condiviso con Lab 05)
testamento_writer00.png	Documento testamento completo — generare con scripts/create_testamento_writer00.py
lorella/*.png	(opzionale) Campioni di scrittura reale

Requisiti:

• Primo avvio: connessione internet per il download del modello (~3,5 GB bf16 o ~7 GB fp32 su CPU)
• Su CPU: ~7 GB di RAM libera; 2–5 min per immagine
• Su GPU: ≥4 GB VRAM raccomandati

Installazione una tantum (prima del primo avvio):

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

---

Riepilogo delle Convenzioni di Denominazione

data/samples/
  handwritten_text_01.png          # Lab 02, 06
  handwritten_text_02.png          # Lab 02, 06 (opzionale)
  handwritten_multiline_01.png     # Lab 02, 07 (HTR multiriga + pipeline NER)
  genuine_1_1.png                  # Lab 03 — scrittore 1, riferimento
  genuine_1_2.png                  # Lab 03 — scrittore 1, secondo campione autentico
  forged_1_1.png                   # Lab 03 — scrittore 1, contraffatta
  genuine_2_1.png                  # Lab 03 — scrittore 2, riferimento
  ...
  document_with_signature_01.png   # Lab 04
  writer_01/sample_01.png          # Lab 05
  writer_01/sample_02.png          # Lab 05
  ...

---

Demo Minima Funzionante (5 immagini)

Per una demo rapida che copra i Lab 02, 03, 04, 06 e 07 con un insieme minimo di immagini:

1. handwritten_text_01.png — per i Lab 02 e 06
2. handwritten_multiline_01.png — per la pipeline HTR→NER del Lab 07
3. genuine_1_1.png — firma di riferimento
4. forged_1_1.png — firma contraffatta
5. document_with_signature_01.png — pagina documento per il Lab 04

Il Lab 01 non richiede nulla. Il Lab 05 richiede le sottodirectory per scrittore (non coperte da questo set minimo). Le Demo 1 & 2 del Lab 07 non richiedono alcun file.

---

Checklist Prima di Avviare i Laboratori

• Ambiente Python creato e requirements.txt installato
• Connessione internet disponibile (download modelli al primo avvio: TrOCR ~400 MB, EasyOCR ~100 MB, WikiNEural NER ~700 MB, Conditional DETR ~170 MB, dots.ocr ~3,5 GB)
• models/signet.pth scaricato da luizgh/sigver
• Directory data/samples/ presente
• Immagini di testo manoscritto inserite (handwritten_text_*.png, handwritten_multiline_01.png)
• Immagini delle firme inserite (genuine_N_M.png, forged_N_M.png)
• Scansione del documento inserita (document_with_signature_*.png)
• Sottodirectory degli scrittori popolate (writer_XX/sample_YY.png) — per il Lab 05
• JupyterLab avviato (jupyter lab oppure docker compose up jupyter)