zipbundler/README.md

# 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.