Release ZipBundler 1.0.0 with guided recompression and complete Windows build

README.md

@@ -26,17 +26,66 @@ Questo e importante perche la dimensione dei file originali non coincide con la
 
 ## PDF troppo grandi
 
-Quando un PDF supera da solo il limite impostato, ZipBundler prova diversi approcci:
+Quando un PDF supera da solo il limite impostato, ZipBundler prova questi
+profili standard nell'ordine indicato, fermandosi al primo ZIP entro limite:
 
-1. Ottimizzazione interna senza perdita tramite PyMuPDF.
-2. Compressione tramite Ghostscript, se disponibile nel sistema.
-3. Ricodifica a immagini/DPI ridotti solo per PDF che non sembrano contenere testo selezionabile significativo.
+| Ordine | Profilo | Operazione | Qualita JPEG |
+| --- | --- | --- | --- |
+| 1 | Ottimizzazione senza perdita | Pulizia e compressione interna con PyMuPDF, senza rasterizzare le pagine | Non applicabile |
+| 2 | Ghostscript ebook | Preset `/ebook` | Gestita dal preset |
+| 3 | Ghostscript screen | Preset `/screen` | Gestita dal preset |
+| 4 | Qualita email | Pagine trasformate in immagini a 150 DPI | 68/100 |
+| 5 | Piu leggero | Pagine trasformate in immagini a 120 DPI | 60/100 |
+| 6 | Minimo | Pagine trasformate in immagini a 100 DPI | 54/100 |
+
+I profili 4-6 vengono saltati quando viene rilevato testo selezionabile
+significativo. I profili Ghostscript vengono saltati se il motore non e
+disponibile; nella build completa e incluso nell'EXE. Anche i profili standard
+possono ridurre sensibilmente la qualita: se rientrano nel limite vengono
+accettati automaticamente, secondo la regola scelta per il programma.
 
 La ricodifica raster dei PDF nativi e evitata quando possibile, perche puo aumentare la dimensione e far perdere testo selezionabile.
 
 Se viene creata una copia ridotta, l'originale non viene modificato. La copia viene salvata nella cartella di destinazione, dentro `_pdf_ridotti_email`.
 
-Nella GUI viene mostrata una preview affiancata originale/ridotto, con navigazione delle pagine.
+Quando serve una scelta sulla qualita, la GUI mostra una preview affiancata originale/ridotto, con navigazione delle pagine.
+
+### Compressione aggiuntiva e zoom
+
+La regola comune a PDF, immagini e conversioni Office e basata sulla dimensione
+reale dello ZIP del singolo file:
+
+1. Se un profilo standard rientra nel limite, la copia viene usata automaticamente, senza anteprima o domande.
+2. Se nessun profilo standard rientra, viene conservato il risultato con lo ZIP piu piccolo e mostrato in anteprima, indicando dimensione e limite.
+3. L'utente puo accettare esplicitamente quel risultato fuori limite oppure scegliere "Rifiuta e comprimi di piu".
+4. Ogni tentativo aggiuntivo richiede anteprima e approvazione, anche quando finalmente rientra nel limite. Ogni rifiuto passa al tentativo successivo.
+
+Non esiste piu il ripiego automatico all'originale o al profilo 200 DPI.
+La chiusura dell'anteprima o "Annulla elaborazione" interrompe il lavoro senza
+creare nuovi ZIP. All'ultimo profilo disponibile rimangono accettazione e
+annullamento: nessun risultato rifiutato viene impacchettato e non viene avviato
+un ciclo infinito. Il limite potrebbe essere inferiore alla dimensione minima
+ottenibile di un documento valido.
+
+Per i PDF, dopo ciascun rifiuto vengono proposti profili Ghostscript a 72, 60,
+48, 36 e 24 DPI, poi profili raster alle stesse risoluzioni, con qualita JPEG
+45, 38, 30, 24 e 18. L'anteprima indica il prossimo tentativo, avvertendo quando
+le pagine verranno trasformate in immagini con perdita del testo selezionabile. Ogni
+tentativo parte dall'originale e viene misurato dentro uno ZIP contenente quel
+solo PDF. I parametri Ghostscript usano i controlli di downsampling e i dizionari
+di compressione documentati in [High Level Devices](https://ghostscript.readthedocs.io/en/gs10.02.1/VectorDevices.html).
+
+L'anteprima PDF dispone di modalita Adatta e zoom dal 50%
+al 400%, con barre di scorrimento sincronizzate tra originale e copia. Il 100%
+corrisponde a 96 pixel per pollice del documento; la pagina viene renderizzata
+nuovamente a ogni livello di zoom. La rotella scorre verticalmente; con Shift
+scorre orizzontalmente. La navigazione delle pagine mantiene lo zoom scelto.
+
+Gli originali restano intatti e la ricodifica raster conserva le dimensioni
+fisiche delle pagine. In modalita CLI, se i profili standard non bastano,
+l'elaborazione si interrompe invitando a usare la GUI. Se un file fuori limite
+non ha un convertitore disponibile o abilitato, il programma segnala il problema
+e si interrompe anziche creare un pacchetto fuori limite non approvato.
 
 ## Ghostscript
 
@@ -62,11 +111,25 @@ Formati supportati:
 - BMP
 - WEBP
 
-Profili:
+Profili standard automatici, nell'ordine:
 
-- qualita alta: lato lungo massimo 2500 px
-- qualita email: lato lungo massimo 1800 px
-- massima compressione: lato lungo massimo 1200 px
+| Profilo | Lato lungo massimo | Qualita JPEG/WebP |
+| --- | --- | --- |
+| Qualita alta | 2500 pixel | 85/100 |
+| Qualita email | 1800 pixel | 75/100 |
+| Massima compressione | 1200 pixel | 60/100 |
+
+Le proporzioni vengono mantenute e le immagini piu piccole non vengono
+ingrandite. I valori di qualita sono parametri dell'encoder, non percentuali
+di dimensione risparmiata. La codifica applicata dipende dal formato:
+
+| Formato | Codifica della copia ridotta |
+| --- | --- |
+| JPEG | JPEG ottimizzato e progressivo, qualita del profilo |
+| WebP | Qualita del profilo, metodo di compressione 6 |
+| PNG | Compressione senza perdita, livello 9; riduzione dei pixel secondo il profilo |
+| TIFF | Deflate (`tiff_adobe_deflate`), riduzione dei pixel secondo il profilo |
+| BMP | BMP, riduzione dei pixel secondo il profilo |
 
 Per impostazione predefinita il formato originale viene mantenuto. Per esempio un TIFF ridotto resta TIFF.
 
@@ -78,6 +141,14 @@ Solo se questa opzione e attiva, BMP e TIFF vengono convertiti in JPEG per otten
 
 Le copie ridotte vengono salvate in `_immagini_ridotte_email`.
 
+Se i tre profili standard non bastano, il ciclo con anteprima propone lati
+massimi di 1000, 800, 600, 400, 200 e 100 pixel, con qualita JPEG/WebP 50, 40,
+30, 24, 18 e 12. Per PNG, TIFF e BMP la riduzione aggiuntiva si basa soprattutto
+sul numero di pixel; la scelta di conservare il formato resta valida.
+L'avviso Pillow per immagini molto grandi viene riportato nel registro, senza
+disabilitare il limite massimo di protezione della libreria. Per i JPEG viene
+richiesta la decodifica ridotta prima del ridimensionamento, limitando la memoria.
+
 ## File Office troppo grandi
 
 ZipBundler puo convertire file Office grandi in PDF, ma solo se la checkbox dedicata e attiva:
@@ -92,17 +163,48 @@ Formati previsti:
 
 La conversione usa Microsoft Office tramite automazione COM (`win32com`). Quindi richiede Office installato e funzionante sul PC.
 
+Non esistono profili di qualita Office separati:
+
+| Documento | Passaggio standard |
+| --- | --- |
+| DOC/DOCX | Esportazione PDF tramite Microsoft Word |
+| XLS/XLSX | Esportazione PDF tramite Microsoft Excel |
+| PPT/PPTX | Esportazione PDF tramite Microsoft PowerPoint |
+
 Le copie PDF vengono salvate in `_office_convertiti_pdf`.
 
+Se il PDF convertito entra nello ZIP, viene usato senza domande. Altrimenti
+passa per l'ottimizzazione PDF standard e, se ancora necessario, per lo stesso
+ciclo di anteprime e compressioni aggiuntive. L'anteprima confronta il PDF
+ottenuto da Office con la sua copia ricompressa.
+
 LibreOffice headless e stato valutato come opzione futura, ma non e incluso per evitare di aumentare molto il peso di un eventuale eseguibile PyInstaller.
 
+## Altri formati
+
+Per i formati non elencati viene applicata soltanto la compressione ZIP, senza
+ricodifica del contenuto. Se il file resta fuori limite e non esiste una
+conversione disponibile o abilitata, il programma segnala il problema.
+
 ## Scelte conservative
 
 - Gli originali non vengono mai modificati.
 - Le conversioni di formato sono disattivate di default.
-- Una copia ottimizzata viene accettata solo se riduce davvero il file e permette allo ZIP finale di rientrare nel limite.
+- I risultati dei profili standard entro limite vengono accettati automaticamente.
 - Sopra 18 MB viene richiesto consenso esplicito, perche la codifica email puo aumentare la dimensione effettiva del messaggio.
-- Se un file non puo essere ridotto sotto soglia, viene segnalato e inserito in un pacchetto fuori limite.
+- Uno ZIP fuori limite viene creato solo dopo approvazione esplicita e contiene soltanto il file accettato.
+
+## Verifica del flusso PDF
+
+```powershell
+python -m unittest test_pdf_workflow -v
+```
+
+I test verificano l'accettazione automatica dei profili standard entro limite,
+il ciclo rifiuto/ricompressione/anteprima, l'annullamento, il mantenimento dei
+formati immagine, i file effettivamente inseriti negli ZIP, lo zoom e gli avvisi
+Pillow. Se Ghostscript e disponibile, verificano anche la ricodifica reale con
+conservazione del testo selezionabile. I test Office simulano la conversione COM.
 
 ## Uso GUI
 
@@ -137,9 +239,12 @@ Dipendenze principali:
 
 Per Office COM serve anche `pywin32`, installato nell'ambiente in cui viene eseguito il programma.
 
-## Packaging futuro
+## Eseguibile Windows
 
-Il progetto e pensato per essere trasformato in un eseguibile Windows con PyInstaller.
+La build completa crea `dist\ZipBundler.exe`: un eseguibile portabile che
+include Python, CustomTkinter/Tcl/Tk, Pillow, PyMuPDF, pywin32 e Ghostscript.
+Sul PC di destinazione non serve installare Python o Ghostscript. Non sono
+inclusi i documenti di prova in SDS.
 
 Script disponibile:
 
@@ -150,21 +255,41 @@ Script disponibile:
 Lo script:
 
 - installa le dipendenze Python;
-- installa/aggiorna PyInstaller;
+- installa PyInstaller se necessario;
 - include lo splash screen `assets/splash.png`;
 - crea un eseguibile Windows `dist\ZipBundler.exe`;
-- prova a includere Ghostscript se trova `gswin64c`, `gswin32c` o `gs` nel PATH.
+- include Ghostscript se trova `gswin64c`, `gswin32c` o `gs` nel PATH; senza il motore la build completa si interrompe;
+- controlla l'esito dei comandi prima di dichiarare completata la build.
+
+Per ricostruire usando le dipendenze gia installate:
+
+```powershell
+.\build_exe.ps1 -SkipDependencyInstall
+```
+
+L'opzione `-SkipGhostscriptBundle` produce invece una versione incompleta del
+motore PDF avanzato, che richiede Ghostscript esterno. Non e la build completa.
+
+Verifica della build completa, da eseguire sul PC di sviluppo:
+
+```powershell
+python verify_exe.py
+```
+
+La verifica controlla i componenti incorporati nell'EXE e avvia il programma
+con Python e Ghostscript esterni esclusi dal PATH. Crea un PDF con testo
+selezionabile e una foto di prova, verifica gli ZIP finali sotto soglia, il
+mantenimento del testo PDF e il formato JPEG. Usa solo cartelle temporanee.
 
 Lo splash screen riporta `ZipBundler`, `versione 1.0` e `ai.teamstudio.it`.
 
 Componenti inclusi o gestiti:
 
 - CustomTkinter, Pillow e PyMuPDF vengono inclusi da PyInstaller come dipendenze Python;
-- Ghostscript viene incluso se rilevato in fase di build;
+- Ghostscript e incluso nella build completa, con le risorse della sua installazione;
 - Microsoft Office non viene incluso: la conversione Office -> PDF usa Office COM e richiede Office installato sul PC di destinazione.
 
 Da valutare in futuro:
 
-- gestione piu esplicita di `pywin32`;
 - eventuale icona applicativa;
 - firma dell'eseguibile, se necessaria in ambiente aziendale.