# pi-imgen

Genera **locandine, loghi e immagini per i social** per eventi, direttamente da
[pi](https://pi.dev). Tutto in locale, senza abbonamenti a servizi di immagini.

Pensato per chi organizza eventi e non è un grafico: rispondi a qualche domanda in
italiano e ottieni i file finiti, incluso il **PDF pronto per la tipografia**.

```
/poster        una locandina completa, dal titolo al PDF per la stampa
/logo          un marchio semplice, con sfondo trasparente e SVG
/social        le stesse grafiche in tutti i formati social
/retouch       ritocca un'immagine che hai già
/presets       salva i tuoi colori, caratteri e logo
```

## Come funziona

Il trucco è **non far scrivere il testo al modello di immagini**. I modelli di
diffusione sbagliano le lettere, e sbagliano quasi sempre le accentate italiane.

```
brief  ──►  direttore artistico (LLM)  ──►  modello locale  ──►  impaginazione (Typst)  ──►  export
            palette, caratteri,            SOLO l'immagine,      caratteri veri,             PDF A3
            impaginazione, prompt          nessuna scritta       accenti giusti,             IG post
                                                                 data e luogo esatti         IG story
```

Il modello dipinge soltanto l'illustrazione. Il testo viene composto dopo, con caratteri
veri. Due conseguenze pratiche:

- **à è é ì ò ù, date e nomi dei luoghi sono sempre corretti.** Non sono pixel, sono dati.
- **Cambiare un colore o un carattere è istantaneo.** Non serve rigenerare l'immagine:
  si ricompone soltanto il testo, in meno di un secondo.

## Requisiti

- **macOS su Apple Silicon** (obbligatorio: esistono solo build arm64). Sviluppato per un
  Mac mini M4 base con 16 GB. **macOS 13** è il minimo; con **macOS 13** funziona tutto
  tranne lo scontorno in un passaggio, che richiede macOS 14 e in mancanza ripiega su
  un'alternativa — vedi [`docs/platform-notes.md`](docs/platform-notes.md).
- [`draw-things-cli`](https://github.com/drawthingsai/draw-things-community) e
  [`typst`](https://typst.app) — installati da `install.sh`.
- Spazio per i modelli (~10 GB). Possono stare su un **disco esterno**: il percorso è
  configurabile e non deve stare nella home.
- Un modello di testo per il direttore artistico, tramite un provider già configurato in
  pi. Nessun servizio di generazione immagini è richiesto o usato.

## Installazione

```bash
pi install git:git.sal.giize.com/mozempk/pi-imgen
cd ~/.pi/agent/git/git.sal.giize.com/mozempk/pi-imgen && ./install.sh
```

`install.sh` è ri-eseguibile: chiede dove tenere i modelli e dove salvare i file,
scarica i caratteri, e scrive `~/.pi/agent/pi-imgen.json`. Se lo rilanci, ripara invece
di duplicare, e **non sovrascrive i tuoi preset**.

Per aggiornare: `pi update --extensions`.

## Configurazione

Tutto ciò che è specifico della tua macchina sta in `~/.pi/agent/pi-imgen.json` — mai nel
repository. Percorso dei modelli, cartella di destinazione, e i tuoi preset di marca
(logo, colori, caratteri) restano sul tuo computer.

## Stampa

L'output per la tipografia è un PDF singolo A3 o A4 con **3 mm di abbondanza** e un
**TrimBox** corretto, caratteri incorporati, in RGB. Va bene per la grande maggioranza
delle copisterie. I crocini di taglio sono disattivati di default: i servizi di stampa
online li rifiutano, le tipografie tradizionali li chiedono — si attivano dalla
configurazione.

## Sotto il cofano

| Pezzo | Scelta |
|---|---|
| Generazione | `draw-things-cli` + `gRPCServerCLI` residente (modello caldo per le bozze) |
| Modello | Z-Image Turbo (Apache-2.0) — piccolo, veloce, e il migliore fra gli open sul testo |
| Impaginazione | Typst 0.15 — un solo binario, PDF di stampa nativo, sillabazione italiana |
| Caratteri | 22 famiglie OFL/Apache incluse nel pacchetto ([THIRD-PARTY-FONTS.md](THIRD-PARTY-FONTS.md)) |

Dettagli verificati sperimentalmente in [`docs/typst-verified.md`](docs/typst-verified.md);
requisiti di sistema e assunzioni non verificate in [`docs/platform-notes.md`](docs/platform-notes.md);
procedura di installazione e collaudo in [`docs/RUNBOOK.md`](docs/RUNBOOK.md).

## Licenza

MIT per il codice. I caratteri inclusi restano sotto le loro licenze originali (OFL 1.1 o
Apache 2.0), elencate in `THIRD-PARTY-FONTS.md` con il file di licenza di ciascuno.