# ZipBundler versione 1.0 ZipBundler e un piccolo tool desktop per creare piu archivi ZIP indipendenti a partire da una cartella sorgente, mantenendo ogni pacchetto entro una dimensione massima configurabile. L'obiettivo pratico e preparare allegati gestibili per invio tramite posta elettronica aziendale, dove spesso il limite reale degli allegati e vicino a 20-25 MB. ## Funzioni principali - Scelta della cartella sorgente. - Scelta della cartella di destinazione. - Dimensione massima dei pacchetti tramite spinbox. - Default a 15 MB, piu prudente per l'invio email. - Avviso inline sopra 18 MB, con richiesta di accettazione esplicita. - Creazione di pacchetti `pacchetto_001.zip`, `pacchetto_002.zip`, ecc. - Verifica della dimensione reale dello ZIP finale, non della somma dei file originali. - Ottimizzazione guidata di PDF troppo grandi. - Ottimizzazione guidata di immagini troppo grandi. - Opzione esplicita per convertire formati immagine non compressi in JPEG. - Opzione esplicita per convertire file Office grandi in PDF. ## Scelta fondamentale sulla dimensione La dimensione limite viene controllata sul file `.zip` finale. Questo e importante perche la dimensione dei file originali non coincide con la dimensione dell'archivio compresso. Il programma crea ZIP temporanei di prova, misura il risultato reale e solo dopo decide se un file puo entrare nel pacchetto corrente. ## PDF troppo grandi Quando un PDF supera da solo il limite impostato, ZipBundler prova questi profili standard nell'ordine indicato, fermandosi al primo ZIP entro limite: | 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`. 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 Ghostscript e usato come motore preferenziale per ridurre PDF nativi quando e disponibile. Il programma cerca: - `gswin64c` - `gswin32c` - `gs` Se Ghostscript non e presente, il programma salta quel passaggio e continua con le altre strategie. ## Immagini troppo grandi Per le immagini viene usata Pillow. Formati supportati: - JPG/JPEG - PNG - TIFF/TIF - BMP - WEBP Profili standard automatici, nell'ordine: | 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. Esiste pero una checkbox esplicita: `Converti formati non compressi in JPEG (es. BMP/TIFF)` Solo se questa opzione e attiva, BMP e TIFF vengono convertiti in JPEG per ottenere file molto piu leggeri. 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: `Converti file Office grandi in PDF (es. DOCX -> PDF)` Formati previsti: - DOC/DOCX - XLS/XLSX - PPT/PPTX 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. - 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. - 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 ```powershell python .\zipbundler.py ``` ## Uso CLI ```powershell python .\zipbundler.py C:\percorso\cartella --output C:\percorso\output --size-mb 15 ``` Opzioni: ```powershell --convert-uncompressed-images --convert-office-to-pdf ``` ## Dipendenze Python ```powershell pip install -r requirements.txt ``` Dipendenze principali: - CustomTkinter - Pillow - PyMuPDF Per Office COM serve anche `pywin32`, installato nell'ambiente in cui viene eseguito il programma. ## Eseguibile Windows 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: ```powershell .\build_exe.ps1 -Clean ``` Lo script: - installa le dipendenze Python; - installa PyInstaller se necessario; - include lo splash screen `assets/splash.png`; - crea un eseguibile Windows `dist\ZipBundler.exe`; - 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 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: - eventuale icona applicativa; - firma dell'eseguibile, se necessaria in ambiente aziendale.