Configurare le impostazioni di riconoscimento
Prima di riconoscere un testo è necessario configurare correttamente Recognition settings. Il pannello di Unified Documents raccoglie OCR languages, PSM e PDF text method, tre parametri distinti che influenzano i futuri percorsi di estrazione.
Questa guida utilizza un PDF sintetico di due pagine e un’immagine PNG sintetica, già importati come Dataset canonici GX-TXT. Esamineremo il comportamento reale dei controlli e le loro condizioni di validità. Non verrà eseguito un riconoscimento OCR: la verifica effettiva dell’estrazione e della sua accuratezza appartiene alla guida successiva.
1. Preparare la Session e le sorgenti
Apri la Session GX-TXT che contiene un Dataset PDF o immagine. Avvia Viewers → Unified Documents dalla finestra principale del framework.
Per questa dimostrazione sono disponibili u05.synthetic_document, un PDF A4 di due pagine con testo già incorporato, e u05.synthetic_image, un PNG di 1200 × 780 pixel. Entrambi sono documenti didattici, privi di misure sperimentali.
2. Individuare Recognition settings
La barra superiore del Viewer contiene un controllo con l’icona delle impostazioni, identificato come Recognition settings. All’apertura della finestra il pannello è normalmente chiuso.

La sua chiusura non impedisce di consultare PDF o immagini. Le impostazioni esistono comunque e possono essere visualizzate quando si prepara un’operazione di riconoscimento.
3. Aprire il pannello
Fai clic su Recognition settings. Subito sotto la barra Source, Page, DPI e Zoom si apre la sezione omonima.

I valori predefiniti osservati sono:
| Campo | Valore iniziale |
|---|---|
| OCR languages | eng |
| PSM | 6 |
| PDF text method | Auto |
I tre controlli sono accessibili senza dover eseguire OCR o creare un nuovo Dataset.
4. OCR languages: identificare la lingua corretta
OCR languages specifica il codice della lingua o delle lingue che il motore Tesseract dovrà utilizzare quando viene effettivamente richiesto un riconoscimento ottico.
Per esempio, eng indica l’inglese e ita l’italiano. Il campo richiede gli identificativi dei pacchetti lingua installati, non parole tradotte come “inglese” o “italiano”.
5. Le lingue disponibili dipendono dall’installazione
Sul sistema utilizzato per l’esempio, Tesseract dispone sia di eng sia di ita. La lista effettiva può essere verificata in un terminale Debian con:
tesseract --list-langs
Per un testo misto inglese/italiano puoi inserire eng+ita, purché entrambe le lingue siano disponibili. La presenza del valore nella casella non costituisce, da sola, la prova che il relativo pacchetto sia installato.
La presenza di un’anteprima leggibile non equivale ancora al riconoscimento OCR del suo contenuto.
6. PSM: modalità di segmentazione della pagina
PSM significa Page Segmentation Mode. È un parametro di Tesseract che descrive come interpretare la disposizione del testo: per esempio un blocco uniforme, una pagina con impaginazione libera o singole righe.
Il valore iniziale 6 indica che l’immagine deve essere trattata come un singolo blocco uniforme di testo. È spesso utile quando una regione contiene un paragrafo o un blocco già isolato.
7. PSM 3 e il riconoscimento di una pagina
Il valore 3 indica una segmentazione automatica della pagina, senza rilevamento dell’orientamento e della scrittura.
Per una pagina con struttura variabile può essere un punto di partenza, ma non garantisce un riconoscimento migliore in ogni situazione. La scelta va valutata in rapporto al documento concreto.
8. PDF text method: scegliere la politica
PDF text method determina la politica di lettura del testo PDF nei percorsi di estrazione che utilizzano questo parametro. Non è il selettore del Dataset e non sostituisce il campo OCR workflow della scheda OCR.
Il campo è un menu di sola selezione: non accetta liberamente valori arbitrari.
9. Le tre opzioni reali del menu
Apri il menu PDF text method.

Le voci presenti nella versione verificata sono Auto, Native e OCR. Si riferiscono a tre strategie distinte per ottenere testo da una sorgente PDF compatibile.
Dopo l’apertura di un Dataset PDF, il pannello resta disponibile sopra l’anteprima, senza sostituire il documento.

10. Auto: prima il testo nativo, poi eventualmente OCR
Con Auto, il servizio di estrazione PDF tenta prima di utilizzare il testo già incorporato nel documento. Se il risultato non soddisfa la soglia minima prevista, può passare al riconoscimento da immagine.
Un PDF contenente già testo non richiede necessariamente una nuova elaborazione ottica. Tuttavia, la scelta Auto non è una garanzia di correttezza del testo finale: il risultato deve essere comunque controllato.
11. Native: leggere il testo già presente nel PDF
Con Native, il servizio tenta di estrarre il livello testuale presente nel PDF, senza passare automaticamente alla lettura OCR.

Nella figura abbiamo impostato ita, PSM 3 e Native. Il Viewer ha accettato questi valori e li ha trasferiti alla richiesta reale del processo di rendering, usando il nome interno del metodo native.
È importante distinguere questo controllo dal risultato: abbiamo verificato la configurazione e il suo passaggio alla richiesta, non eseguito un’estrazione di testo.
12. OCR: richiedere la lettura ottica dove prevista
Con OCR, il percorso di estrazione PDF che utilizza questo parametro può rasterizzare la pagina e demandare la lettura a Tesseract, anche quando il file contiene un livello di testo.
È utile conoscere questa distinzione per non confondere testo nativo e testo riconosciuto. La qualità dell’OCR dipende anche dalla lingua, dal PSM, dalla pagina e dalla leggibilità dell’immagine.
13. Un esempio con due lingue e PSM 11
Imposta OCR languages = eng+ita, PSM = 11 e PDF text method = OCR.

PSM 11 è la modalità Tesseract per il testo sparso: cerca testo in posizioni diverse senza imporre un ordine di lettura continuo. Può essere utile per etichette o scritte isolate, ma la sequenza del testo risultante andrà verificata.
Nella prova, la richiesta di rendering ha ricevuto realmente i valori eng+ita, 11 e ocr. Il rendering non ha eseguito OCR; il risultato di riconoscimento verrà verificato in un’altra procedura.
14. Il rapporto fra PDF text method e OCR workflow
Nella scheda OCR esiste anche un’opzione separata, OCR workflow, con percorsi come PDF OCR e Document OCR. Le due scelte non sono sinonimi del menu PDF text method.
Nel percorso Document OCR, l’estrazione del PDF può utilizzare la politica Auto/Native/OCR. Il percorso PDF OCR può invece passare dal riconoscimento dell’immagine rasterizzata senza utilizzare quella stessa selezione come strategia di scelta del testo nativo.
È quindi necessario controllare sia le Recognition settings sia il workflow selezionato nella scheda OCR prima di interpretare un risultato. Questa guida verifica i parametri; le effettive estrazioni e le differenze fra workflow saranno mostrate successivamente.
15. Il limite inferiore PSM: valore 0
Il campo PSM consente numeri interi da 0 a 13. Abbiamo impostato 0 e verificato che la configurazione venga accettata.

Per Tesseract, PSM 0 indica il solo rilevamento di orientamento e scrittura (OSD). È quindi un valore numericamente valido, ma non adatto a ottenere direttamente un normale testo trascritto. La validità dell’intervallo non significa che ogni modalità sia appropriata a ogni documento.
16. Il limite superiore PSM: valore 13
Il valore 13 è il limite massimo ammesso dalla configurazione.

In Tesseract, PSM 13 tratta l’immagine come una singola riga di testo grezza, evitando alcune trasformazioni specifiche. Non va selezionato indiscriminatamente per un’intera pagina con più paragrafi.
17. PSM 14: valore fuori intervallo
Inserisci 14 nel campo PSM e prova ad applicare la configurazione mediante Render page.

Il Viewer rifiuta il valore. La barra inferiore riporta la richiesta di un intero compreso fra 0 e 13; non viene avviato un nuovo rendering e la pagina precedentemente aperta rimane disponibile.
È una protezione effettiva dell’interfaccia, non un problema di leggibilità del PDF.
18. PSM non numerico: valore abc
Il campo PSM è un campo di testo, ma il servizio accetta soltanto un numero intero nel suo intervallo.

Con abc, l’operazione viene rifiutata. La configurazione deve essere corretta prima di riprovare. La precedente richiesta valida continua a identificare la stessa sorgente PDF.
19. PSM negativo: valore −1
Anche un numero negativo come −1 viene rifiutato.

Non è necessario riaprire o importare di nuovo la sorgente dopo un errore di inserimento: basta sostituire PSM con un intero valido, per esempio 6, e applicare nuovamente la richiesta.
20. OCR languages vuoto non è una lingua valida per OCR
Abbiamo provato a lasciare OCR languages vuoto.

Un’anteprima ottenuta con Render page può comunque riuscire: il rendering si limita a preparare l’immagine della pagina e non deve interpretarne il testo. Questo non significa che un campo lingua vuoto sia valido per il successivo riconoscimento.
Le API OCR richiedono esplicitamente un valore di lingua non vuoto. Prima di eseguire OCR, controlla quindi il contenuto del campo.
21. Un codice lingua inesistente non viene verificato dal rendering
Il campo può accettare anche una sequenza di caratteri che non corrisponde ad alcun pacchetto lingua installato.

Nel test di configurazione, un codice non disponibile è stato trasmesso alla sola richiesta di rendering. Non è stato lanciato Tesseract per riconoscere il testo, quindi non si può dedurre che quel codice funzioni in OCR.
Usa identificativi presenti nella lista effettiva di Tesseract. La disponibilità dei pacchetti non va inferita da una semplice anteprima riuscita.
22. Ripristinare una configurazione ordinaria
Per tornare a una configurazione adatta a un documento di testo inglese, imposta OCR languages = eng, PSM = 6 e PDF text method = Auto.

Abbiamo applicato questa combinazione al processo di rendering del PDF. La richiesta reale riportava eng, 6 e auto, mantenendo il medesimo Dataset e la sua impronta SHA-256.
23. Richiudere Recognition settings senza perdere i valori
Fai di nuovo clic su Recognition settings per chiudere il pannello.

La barra principale e l’anteprima rimangono visibili. I valori della configurazione non vengono cancellati: quando il pannello viene riaperto, si ritrovano i dati precedentemente impostati.
24. Le impostazioni sono condivise fra le schede
Seleziona la scheda OCR, quindi mostra nuovamente Recognition settings.

Gli stessi valori rimangono disponibili anche in questa scheda. La sezione Recognition settings è distinta dalle Options specifiche del workflow OCR, che saranno illustrate nella guida successiva.
In questa fase non abbiamo premuto Run OCR, Copy text o Publish text: nessun testo riconosciuto o Dataset derivato è stato creato.
25. Mantenimento delle impostazioni cambiando sorgente
Torna alla scheda PDF / Image, seleziona un Dataset PNG canonico e utilizza Open source.

La nuova sorgente viene aperta come immagine 1200 × 780 pixel, mentre le Recognition settings rimangono eng, PSM 6 e Auto. Anche la richiesta di rendering del PNG conserva questi parametri.
Nel nostro caso, l’immagine appare inizialmente piccola perché Zoom % mantiene circa 11% dalla precedente anteprima PDF. Questo non riduce i pixel del file originale: puoi usare Fit page per adattare la nuova sorgente alla finestra.
La voce PDF text method resta visibile nel pannello condiviso, ma la strategia Native/Auto/OCR per il testo PDF non trasforma automaticamente un’immagine raster in un PDF. I parametri saranno pertinenti secondo il successivo workflow di estrazione.
26. Procedura consigliata e prossima guida
Prima di avviare un riconoscimento, scegli il Dataset corretto con Source e verifica la riga Opened:. Mostra Recognition settings, inserisci codici lingua realmente installati, seleziona un PSM appropriato alla struttura del testo e scegli una politica PDF coerente con il tipo di documento e con il workflow OCR.
Per un normale blocco di testo inglese puoi iniziare da eng, PSM 6 e Auto; per testi misti italiano/inglese puoi utilizzare eng+ita se i due pacchetti sono installati. Evita PSM fuori intervallo e non interpretare una semplice anteprima come verifica della qualità OCR.
La guida successiva affronterà l’esecuzione reale dell’OCR, i workflow PDF OCR/Document OCR, lo Scope e gli stati dell’elaborazione, usando testi sintetici con contenuto noto e controlli indipendenti del risultato.