Immagini SVG con fpdf2: tracciati nel PDF Python

Usa pdf.image("logo.svg", x=20, y=20, w=60) per inserire un SVG in un documento fpdf2. La geometria SVG supportata diventa tracciati di disegno PDF. Non occorre prima renderizzare il logo in PNG. La documentazione ufficiale sugli SVG descrive questo metodo diretto e i suoi limiti.

Se non conosci ancora il formato, la guida ai file SVG spiega i tracciati e i contenitori di immagini. Anche un'importazione riuscita richiede controlli. Il file può contenere pixel incorporati, dipendere da funzionalità che l'importatore non riproduce o avere spazio vuoto intorno alla grafica. Questa guida costruisce un piccolo logo originale, lo inserisce con dimensioni esplicite e controlla il PDF risultante. Conserva un originale vettoriale esistente se lo possiedi; recuperare grafica da PNG o JPG è un passaggio separato a monte.

Inizia con un SVG noto e una versione fpdf2 fissata

Abbiamo eseguito l'esempio con Python 3.12 e fpdf2 2.8.8. È la versione verificata, non una garanzia che tutte le versioni successive si comportino allo stesso modo. La pagina ufficiale del pacchetto su PyPI documenta l'installazione con il nome di distribuzione fpdf2; l'importazione Python è fpdf.

Usa un ambiente nuovo, così l'esempio non dipende dai pacchetti di un altro progetto:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install "fpdf2==2.8.8"

Su Windows, attiva invece l'ambiente con .venv\Scripts\activate. Salva questo emblema rettangolare originale come logo.svg:

<svg xmlns="http://www.w3.org/2000/svg"
     width="120" height="80" viewBox="0 0 120 80">
  <path fill="#137d89" fill-rule="evenodd"
        d="M10 10H110V70H10Z M30 25H90V55H30Z"/>
</svg>

Ci sono due sottotracciati chiusi. Il rettangolo esterno è riempito, mentre il rettangolo interno diventa un'apertura grazie alla regola di riempimento evenodd. Non ci sono caratteri, immagini o effetti, il che rende facile diagnosticare la prima prova.

Salva il codice seguente come place_logo.py accanto all'SVG:

from pathlib import Path
from fpdf import FPDF
 
folder = Path(__file__).resolve().parent
pdf = FPDF(unit="mm")
pdf.add_page()
pdf.image(str(folder / "logo.svg"), x=20, y=20, w=60)
pdf.output(str(folder / "logo.pdf"))

Esegui python place_logo.py. Apri logo.pdf e cerca una cornice rettangolare verde petrolio vicino all'angolo superiore sinistro, con la pagina visibile attraverso il centro.

Distingui la tela SVG dal logo disegnato

La tela sorgente ha un rapporto 3:2: 120 unità di larghezza e 80 di altezza. Con w=60, questo esempio occupa una tela di 60 × 40 mm. La grafica inizia 10 unità sorgente all'interno della tela, quindi il rettangolo esterno disegnato misura 50 × 30 mm e inizia a 25, 25 mm sulla pagina. Questi calcoli derivano dalle coordinate e dalla scala dell'esempio.

Quel margine spiega perché misurare la forma colorata non dà lo stesso risultato che misurare la tela di posizionamento. Se il logo di un cliente sembra troppo piccolo, ispeziona i margini sorgente prima di aumentarne la larghezza nel PDF.

La guida alle immagini fpdf2 spiega la gestione delle dimensioni e l'opzione per mantenere le proporzioni all'interno di un riquadro specificato. Per questo primo esempio, imposta soltanto la larghezza. Se in seguito fornisci entrambe le dimensioni, verifica deliberatamente l'adattamento desiderato invece di presumere che tutti i sorgenti abbiano le stesse proporzioni.

Verifica che il PDF salvato contenga tracciati

L'anteprima PDF mostra l'aspetto, ma un'immagine può sembrare nitida a un ingrandimento moderato. Ispeziona anche il file. Abbiamo controllato l'esempio isolato con pypdf 6.1.1:

python -m pip install "pypdf==6.1.1"

from pathlib import Path
from pypdf import PdfReader
 
folder = Path(__file__).resolve().parent
page = PdfReader(folder / "logo.pdf").pages[0]
print("Page images:", len(page.images))
print(page.get_contents().get_data().decode("latin-1"))

Il nostro output ha riportato zero immagini nella pagina. Il contenuto decodificato conteneva contorni rettangolari espressi mediante operazioni di spostamento, linea e chiusura del tracciato, seguite da f*, l'operazione di riempimento pari-dispari. Insieme all'apertura renderizzata, questo sostiene la conclusione che questo esempio privo di immagini sia rimasto geometria di disegno nel PDF salvato.

Non applicare questa conclusione a un input diverso senza controllarlo. Una relazione può legittimamente contenere foto altrove; un SVG può contenere esso stesso un'immagine. La diagnosi dei raster incorporati aiuta a distinguere un logo composto da tracciati da una bitmap racchiusa nel markup SVG. PDF più complessi possono anche inserire contenuto di disegno in oggetti referenziati, quindi il breve script sopra è un punto di partenza per questo esempio isolato, non un controllo universale dei PDF.

Diagnostica la grafica mancante con la versione installata

Inizia eseguendo il piccolo emblema riportato sopra. Se funziona mentre il logo di produzione fallisce, hai circoscritto il problema alla grafica sorgente o alle funzionalità che usa. Conserva l'originale e semplifica una copia una funzionalità alla volta.

Le risposte storiche richiedono cautela. La nostra prova separata con la versione 2.8.8, contenente un semplice elemento <text>, ha prodotto testo HELLO estraibile, e un rettangolo con gradiente lineare di base è stato esportato correttamente. Questi controlli circoscritti non dimostrano una compatibilità completa con testo, caratteri, CSS o gradienti SVG. Mostrano però perché una vecchia affermazione secondo cui tutto il testo SVG o tutti i gradienti non sarebbero supportati può portare a una rasterizzazione inutile.

L'attuale elenco delle funzionalità SVG cita ancora limiti come marcatori, motivi, testo su tracciato e CSS complesso o esterno. Mantieni visibili gli avvisi dell'importatore durante la diagnosi e confronta la pagina salvata con il sorgente. Un registro senza avvisi, da solo, non dimostra che ogni funzionalità visiva sia sopravvissuta.

Usa un'alternativa raster quando il risultato lo richiede

Se un effetto non può essere riprodotto nella procedura scelta, decidi se conservarne l'aspetto è più importante che mantenere la geometria. Un PNG renderizzato può essere appropriato per quella parte di un documento. Controllalo alle dimensioni fisiche finali e descrivi correttamente l'output; incorporare un rendering raster non conserva i tracciati originali.

Per il logo di un marchio, scritte approvate convertite in tracciati o un'esportazione vettoriale più semplice possono essere scelte migliori. Per il testo modificabile del documento, gestisci caratteri e testo nella procedura del documento. Ricalcare uno screenshot di una frase non ne recupera la tipografia e non lo rende testo selezionabile.

Se il codice PDF esistente usa un'altra libreria Python, la procedura SVG con ReportLab ha controlli propri di importazione e dimensionamento. Cambiare libreria è una decisione di implementazione separata, quindi prova la funzionalità che causa effettivamente il problema prima di ricostruire il documento.

Prepara la grafica solo raster prima del passaggio al PDF

Quando rimane soltanto un logo PNG o JPG, il vettorializzatore di loghi di PerfectVector può preparare un candidato SVG prima dell'importazione con fpdf2. Confronta contorni, piccole aperture e regioni di colore con il sorgente, poi sottoponi il candidato agli stessi controlli di posizionamento e del PDF.

Usa il vettoriale originale se è disponibile. Le scritte esatte del marchio potrebbero richiedere di riscrivere il testo o correggerlo manualmente; la guida alla vettorializzazione dei loghi spiega questa scelta. L'emblema di questo articolo è un SVG originale scritto a mano, non un risultato misurato di conversione PerfectVector. PerfectVector prepara la grafica, mentre fpdf2 ne controlla il posizionamento nel PDF.

FAQ

fpdf2 può inserire direttamente un SVG? Sì. Passa il file SVG al metodo image e imposta posizione e dimensioni. La geometria supportata può diventare tracciati PDF, ma ispeziona il file esportato e l'aspetto della tua grafica.

fpdf2 supporta il testo SVG? La nostra prova di testo di base ha funzionato con fpdf2 2.8.8. Questo non garantisce ogni carattere, funzionalità di impaginazione o costrutto di testo su tracciato. Controlla la versione installata e prova le scritte che il documento usa effettivamente.

Perché un'immagine da 60 mm sembra più stretta di 60 mm? La dimensione richiesta si applica alla tela di posizionamento. I margini vuoti all'interno dell'SVG rimangono parte di quella tela, quindi la forma disegnata può essere più stretta.

Devo convertire il logo PNG in SVG prima di aggiungerlo? Soltanto se hai bisogno di tracciati modificabili e la grafica è adatta al ricalco. Mantieni le fotografie come immagini raster e usa un logo vettoriale originale quando esiste. Controlla un candidato ricalcato prima di inserirlo.

Fonti

1. fpdf2 — SVG — Documenta l'inserimento diretto degli SVG, il supporto delle funzionalità e i registri degli avvisi.
2. fpdf2 — Immagini — Spiega posizionamento, dimensioni e adattamento delle proporzioni delle immagini.
3. fpdf2 — Pacchetto PyPI — Identifica la distribuzione installabile e la sua convenzione di importazione Python.

Hai soltanto un logo raster? Prepara un candidato SVG con PerfectVector, ispeziona contorni e aperture, poi inseriscilo alle dimensioni richieste con fpdf2 e controlla il PDF salvato.