ScanRecapito

Contesto

Nei centri di stampa digitale di posta massiva, i file PDF destinati alla stampa arrivano spesso senza alcuna documentazione di ordinamento: né indici, né CSV, né Excel. Questo rende impossibile processare correttamente il flusso postale e ordinare i documenti per la spedizione senza intervento manuale.

La soluzione

ScanRecapito automatizza l'estrazione di dati da PDF massivi. Scansiona PDF singoli o che contengono più documenti, estrae automaticamente le anagrafiche (destinatario, indirizzo, CAP/città/provincia) dall'area configurata, gestisce il fronte-retro normalizzando la struttura con pagine bianche, compone i PDF finali e produce un CSV di tracciatura ordinato pronto per il sistema di spedizione postale.

Risultato: migliaia di lettere diventano un dataset strutturato in pochi secondi.

Nota: il progetto nasce per Windows. L'OCR delle pagine scansionate usa Tesseract (flag --OCR).

Funzionalità

• ⚡ Elaborazione parallela (rayon) di migliaia di PDF
• 🎯 Estrazione anagrafiche da area a coordinate (pdfium-render), con ancora testuale e multidocumento
• 🧩 Campi aggiuntivi via ancora/riga successiva/regex globale
• 🧾 Rilevamento bollettini di pagamento (es. TD 896, pagoPA, F24)
• 🔁 Composizione PDF: merge unico (--UNICOFILE), pagine bianche (--FIXBIANCA), rotazione (--ROTAZIONE), compressione (--COMPRESSIONE, via cpdf)
• 🔍 Validazione CAP/città/provincia con dizionario italiano
• 🌍 Gestione indirizzi esteri (--ESTERO)
• 🔎 OCR pagine scansionate (--OCR, Tesseract)
• 🖥 GUI calibratore (egui): disegna l'area, configura, avvia la pipeline, log a schermo

Requisiti

File/Strumento	Obbligatorio	Note
pdfium.dll	✅	Inclusa nella release, accanto all'exe
CAP-CITTA-PROV_ITALIAne.csv	✅	Dizionario CAP/città (dato pubblico), nel repo e incluso nella release
app.json	✅	Configurazione (creata dalla GUI o da docs/app.example.json)
cpdf	⬜	Opzionale: compressione e pagine bianche
Tesseract	⬜	Opzionale: OCR con --OCR (scaricato al primo uso — portable UB Mannheim)

Installazione rapida

1. Scarica la release (zip scan_recapito-vX.Y.Z-win64.zip) dall'ultima release su GitHub
2. Estrai in una cartella di lavoro (exe + pdfium.dll + CAP-CITTA-PROV_ITALIAne.csv)
3. Copia docs/app.example.json → app.json (o avvia la GUI e salva: la crea lei)
4. Metti i PDF in input_pdf/ ed esegui:

scan_recapito.exe

Uso CLI

scan_recapito.exe                          # elaborazione standard (usa app.json in cwd)
scan_recapito.exe --UNICOFILE --FIXBIANCA  # unico PDF con pagine bianche
scan_recapito.exe --OCR                    # OCR per PDF scansionati
scan_recapito.exe --ESTERO --ROTAZIONE --COMPRESSIONE
scan_recapito.exe --help                   # aiuto

I flag si possono scrivere con o senza -- (es. UNICOFILE = --UNICOFILE); sono case-sensitive.

Flag	Effetto
--UNICOFILE	Merge di tutti i PDF in un unico file
--FIXBIANCA	Pagine bianche per il fronte-retro
--ROTAZIONE	Rotazione Landscape → Portrait
--COMPRESSIONE	Compressione finale (cpdf)
--ESTERO	Indirizzi esteri (colonna Estero)
--OCR	OCR pagine scansionate (Tesseract)
--SILENT	Output minimo

Uso GUI

Avvia scan_recapito_gui.exe (nella stessa cartella di scan_recapito.exe):

1. Disegna Area → carica un PDF di esempio e disegna il rettangolo sull'area delle anagrafiche (8 maniglie)
2. Impostazioni & Percorsi → ancora, bollettino, cartelle
3. Campi Dinamici → campi aggiuntivi da estrarre
4. Controllo Avvio → seleziona i flag, avvia/interrompi, monitora log e CPU/RAM

Configurazione app.json

{
  "X": 305.0,
  "Y": 576.0,
  "W": 273.0,
  "H": 81.0,
  "Ancora": "FATTURA N.",
  "Multidocumento": true,
  "CercaBollettino": true,
  "StringaBollettino": "PAGAMENTO",
  "cartella_input_pdf": "./input_pdf",
  "cartella_output_pdf": "./output_pdf",
  "percorso_file_log": "./logs/elaborazione.log",
  "stringa_bollettino": "PAGAMENTO",
  "CampiAggiuntivi": []
}

• X/Y/W/H: area di estrazione in punti (origine basso-sinistra della pagina)
• Ancora: stringa che segna l'inizio di ogni anagrafica
• Multidocumento: cerca tutte le occorrenze dell'ancora
• CercaBollettino/StringaBollettino: rilevamento bollettini
• CampiAggiuntivi[]: campi extra (Strategia: ancorastessariga=0, ancorarigasuccessiva=1, regexglobale=2)

Output

• PDF elaborati: output_pdf/
• CSV di tracciatura: input_pdf/recapiti_estratti.csv — UTF-8 BOM, separatore ;

nome_file;Destinatario;Indirizzo;Cap-Loc-Prv;CAP_E;LOCALITA_E;PROV_E;Da_Pag;A_Pag;TotPag;Bollettino
lettera_001.pdf;ROSSI MARIO;VIA ROMA 100;00010 ROMA RM;;;1;1;1;B1B
lettera_001.pdf;BIANCHI GIULIA;CORSO MILANO 45;20121 MILANO MI;;;2;3;2;B2B,B3B

Manuali

• Quick Start — 2 minuti per iniziare
• Manuale Operatore — guida completa
• Configurazione di esempio
• Contribuire — linee guida per build, test e pull request

Build da sorgente

cargo build --release --workspace

Produce scan_recapito.exe (motore) e scan_recapito_gui.exe (GUI) in target/release/. ⚠️ Il profilo release usa LTO "fat": richiede ~1.5 GB di RAM e 10–20 minuti su macchine lente.

Struttura del workspace:

├── src/          ← motore CLI (main, scanner, composer, address, ocr, pdf_merge, config, utils)
├── gui/          ← crate scan_recapito_gui (eframe/egui)
└── Ico/          ← icone (embeddate negli exe in build)

Licenza

MIT — vedi LICENSE. Le dipendenze di terze parti: THIRD_PARTY_NOTICES.md.