Vectorizer locale

Da immagini raster (PNG, JPG, WebP…) a SVG. Gira interamente sulla tua macchina, nessun servizio esterno, nessun upload.

Motore: VTracer. Sopra ci sono un layer di preprocessing, cinque preset, una CLI e una UI locale.

---

Passo 1 — Requisiti

Serve solo Python da 3.10 a 3.13. Verifica:

python --version

VTracer è scritto in Rust ma viene distribuito come wheel precompilato per Windows, macOS e Linux: non serve installare Rust.

Non usare Python 3.14: il wheel di VTracer 0.6.15 per 3.14 va in segmentation fault appena gli passi un parametro. Su macOS con Homebrew: brew install python@3.13 e poi python3.13 -m venv .venv.

---

Passo 2 — Ambiente virtuale

cd vectorizer
python3.13 -m venv .venv

Attivalo:

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

---

Passo 3 — Installazione

pip install -r requirements.txt

Se ti serve solo la CLI e vuoi restare leggero, puoi saltare Gradio:

pip install vtracer pillow numpy

---

Passo 4 — Prima vettorizzazione

python cli.py mia_immagine.png

L'SVG viene salvato accanto all'originale, con lo stesso nome. Per scegliere la destinazione:

python cli.py logo.png -o output/logo.svg

---

Passo 5 — Scegli il preset giusto

Il preset è la variabile che cambia di più il risultato. Parti sempre da qui prima di toccare i singoli parametri.

Preset	Quando usarlo
logo	Logo, icone, forme piatte con pochi colori. Massima pulizia.
lineart	Disegni al tratto, testo, scansioni, timbri. Binarizza in b/n.
illustration	Default. Illustrazioni a colori piatti, vector art, cartoon.
photo	Foto reali. Privilegia la leggerezza del file sul dettaglio.
detailed	Massimo dettaglio, senza compromessi sul peso.

python cli.py logo.png --preset logo
python cli.py schizzo.jpg --preset lineart
python cli.py foto.jpg --preset photo --max-side 800

---

Passo 6 — L'interfaccia grafica

Il modo più rapido per capire cosa fa ogni parametro: muovi gli slider e guarda il risultato.

python app.py

Si apre http://127.0.0.1:7860. Trovi l'immagine dopo il preprocessing accanto all'SVG, il peso del file, il numero di path e il bottone per scaricare.

---

Passo 7 — Elaborazione in batch

python cli.py ./cartella_immagini --batch --preset logo -o ./svg

Elabora tutti i formati riconosciuti nella cartella. Se un file va in errore, gli altri proseguono comunque.

---

Passo 8 — Usarlo come libreria

from core import vectorize_file, vectorize_image, VectorizeConfig, PRESETS
from preprocess import preprocess

# Il modo semplice
vectorize_file("input.png", "output.svg", preset="logo")

# Controllo completo
config = VectorizeConfig(
    filter_speckle=8,
    color_precision=4,
    mode="spline",
    path_precision=4,
)
img = preprocess("input.png", max_side=1000, n_colors=12)
svg = vectorize_image(img, config)   # stringa SVG, la usi come vuoi

---

Come si regolano i parametri

Preprocessing — qui si vince o si perde la qualità, più che nei parametri di VTracer.

• --max-side : lato massimo in pixel. Abbassarlo è il rimedio più efficace contro gli SVG enormi.
• --denoise : filtro mediano, spento di default. Sul percorso a palette ridotta non serve (il voto di maggioranza sulla mappa dei colori fa lo stesso lavoro senza spostare i bordi); tienilo per le foto e per --bw.
• --colors : riduce la palette a N colori. Fondamentale sulle illustrazioni: forza aree piatte, che diventano pochi path grandi invece di migliaia di sfumature. Di default il numero è stimato automaticamente (i colori che coprono almeno l'1% dei pixel: antialiasing, rumore JPEG e ombre morbide vengono assorbiti). --colors 0 disattiva la riduzione, --colors 8 la forza a 8.
• --bw : binarizza. La soglia è calcolata con Otsu, oppure la imponi con --bw-threshold 0-255.

VTracer

Con la palette ridotta (il default) ogni colore viene tracciato da solo come layer binario e impilato: bordi ricalcati una volta sola, niente filetti né cuciture tra path adiacenti, colori esatti. color_precision, layer_difference e hierarchical contano solo nel fallback a colori (--colors 0, o più di 64 colori).

• length_threshold : lunghezza minima di un segmento. Alzarlo alleggerisce il file ma poligonizza: le curve lunghe prendono pieghe visibili, anche se lo scostamento in pixel resta piccolo. Tienilo basso.
• filter_speckle : scarta le macchie sotto N pixel. Alzalo per pulire. Non tocca le ondulazioni dei bordi: scarta componenti intere.
• corner_threshold : sotto questo angolo un punto è uno spigolo. Alto = più arrotondato. Ininfluente su forme senza spigoli veri.
• path_precision : decimali nelle coordinate. Abbassalo per alleggerire il file.
• mode : spline curve morbide, polygon spigoli netti, pixel un rettangolo per pixel.
• color_precision : 1-8 bit di colore. Abbassalo per ridurre i layer (solo fallback).

---

Problemi tipici

SVG di 20 MB. Quasi sempre stai vettorizzando una foto. Riduci --max-side a 600-800, alza filter_speckle a 10-16, abbassa color_precision a 4-5 e path_precision a 3. Usa --preset photo.

Contorni frastagliati. Nove volte su dieci il colpevole è la segmentazione, non il tracciamento: guarda il raster dopo il preprocessing (python app.py lo mostra accanto all'SVG). Se è pulito lì ma frastagliato nell'SVG, allora tocca i parametri di VTracer. Su foto e scansioni rumorose aggiungi --denoise 2.

Bande chiare fantasma dove due colori si toccano. Non dovrebbero più comparire: i pixel vengono assegnati al colore più vicino, non alla lookup dell'octree, che sul mezzo tono tra due tinte sature sbagliava. Se ne vedi ancora, quasi sempre sono aloni veri dell'originale — controlla il raster ingrandito prima di dare la colpa al vectorizer.

Il testo diventa illeggibile. La vettorizzazione non fa OCR: ricalca la forma delle lettere. Per il testo usa --preset lineart e non ridimensionare (--max-side 0). Se ti serve testo modificabile, ti serve un OCR, non un vectorizer.

Ho perso i dettagli fini. filter_speckle è troppo alto: li sta scartando. Portalo a 0-2 e usa --preset detailed.

---

Il limite da conoscere

La vettorizzazione automatica funziona molto bene su logo, icone, disegni al tratto e illustrazioni piatte. Su foto reali il risultato è sempre un mosaico di migliaia di path: tecnicamente è un SVG, ma non è vettoriale in senso utile e spesso pesa più dell'originale. Nessun tool cambia questo — è la natura del problema, non un difetto dell'implementazione.

---

Struttura

vectorizer/
├── core.py               # wrapper VTracer + preset
├── preprocess.py         # resize, denoise, quantizzazione, binarizzazione
├── cli.py                # riga di comando, con batch
├── app.py                # UI locale Gradio
├── test_core.py          # controllo rapido: python test_core.py
├── requirements.txt
└── README.md

Alternative, se vuoi valutare altro

• Potrace — lo standard storico per bianco/nero. Ottimo sui tracciati, vuole input già binarizzato.
• Autotrace — supporta il colore, ma poco mantenuto.
• imagetracer.js — se ti serve che giri nel browser senza backend.
• Inkscape — menu Tracciamento bitmap (usa potrace), e la CLI è scriptabile.
• primitive / geometrize — ricostruiscono l'immagine con forme geometriche. Risultato artistico, non tecnico.