CairoSVG: esporta PDF e PNG alla dimensione giusta

Usa cairosvg.svg2png() per un'esportazione raster e cairosvg.svg2pdf() per un PDF. Per una larghezza PNG specifica, imposta output_width; per un ingrandimento proporzionale, usa scale. parent_width fornisce il contenitore usato per risolvere le dimensioni percentuali. dpi controlla la relazione tra pixel e unità fisiche, quindi cambiarlo può influenzare diversamente le dimensioni PNG e PDF.

L'esempio qui sotto parte da un piccolo emblema SVG e controlla i file prodotti da ogni impostazione. È adatto a designer che automatizzano esportazioni di loghi e sviluppatori che preparano grafica per documenti. CairoSVG renderizza contenuto SVG esistente. Non ricalca un logo PNG in tracciati modificabili.

Parti da un SVG autonomo

Abbiamo eseguito questi esempi con Python 3.12.11 e CairoSVG 2.9.1. Installa il convertitore nella versione fissata in un ambiente di progetto:

python -m pip install "CairoSVG==2.9.1"

CairoSVG richiede anche la libreria Cairo nativa. Se l'installazione o l'importazione fallisce, segui le note per il sistema operativo nella sua documentazione di installazione.

Salva questo emblema originale a tre tracciati come emblem.svg. L'apertura quadrata rende facile notare una regola di riempimento mancante e la barra stretta fornisce un punto di controllo per i piccoli dettagli. È grafica dimostrativa scritta a mano, non una conversione PerfectVector.

<svg xmlns="http://www.w3.org/2000/svg"
     width="240" height="120" viewBox="0 0 240 120">
  <path fill="#176b63" fill-rule="evenodd"
        d="M20 100 V20 H100 V100 Z M40 40 V80 H80 V40 Z"/>
  <path fill="#e5a43a" d="M110 100 L160 20 L210 100 Z"/>
  <path fill="#24435d" d="M220 20 H230 V100 H220 Z"/>
</svg>

Le dimensioni radice descrivono il viewport di output. Il viewBox descrive il rettangolo delle coordinate interne della grafica. Qui entrambi hanno lo stesso rapporto 2:1. Mantieni questa relazione deliberata quando adatti l'esempio al tuo logo.

Esporta un originale alla dimensione richiesta

Salva questo come export_emblem.py accanto all'SVG, poi esegui python export_emblem.py:

import cairosvg
 
cairosvg.svg2png(
    url="emblem.svg",
    write_to="emblem-480.png",
    output_width=480,
)
cairosvg.svg2pdf(
    url="emblem.svg",
    write_to="emblem.pdf",
)

Il nostro PNG era di 480 × 240 pixel. La pagina PDF era di 180 × 90 punti, equivalenti a 2.5 × 1.25 pollici. Sono misure del campione fornito, non dimensioni da aspettarsi da ogni SVG.

Gli equivalenti da riga di comando sono:

cairosvg emblem.svg --output-width 480 -o emblem-480.png
cairosvg emblem.svg -o emblem.pdf

Il riferimento API e della riga di comando di CairoSVG documenta i nomi dei file in input tramite url, i byte SVG tramite bytestring e l'output su file tramite write_to. Nella CLI, l'estensione del nome del file di output seleziona il formato.

Scegli il controllo adatto al problema

Le opzioni con nomi simili rispondono a domande diverse. Il riferimento di dimensionamento di CairoSVG distingue il contenitore genitore dalle dimensioni di output richieste.

Per la nostra sorgente dimensionata in pixel, abbiamo eseguito ogni opzione indipendentemente:

L'ultima riga è la trappola: raddoppiare i DPI non ha dato più pixel PNG a questo SVG dimensionato in pixel. Ha fatto occupare meno spazio fisico nel PDF alle stesse dimensioni in pixel. Usa una dimensione di output quando il requisito di consegna è un conteggio di pixel.

Fornire entrambe le dimensioni di output imposta il rettangolo della tela; non garantisce un riquadro pienamente occupato dal logo. Le regole delle proporzioni dell'SVG e l'eventuale area vuota nel suo viewBox contano ancora. Parti da una sola dimensione di output quando vuoi le proporzioni originali, poi esamina il risultato.

Le dimensioni percentuali richiedono un genitore

Per una copia del campione la cui radice usa width="50%" height="50%", questa chiamata fornisce un genitore di 960 × 480 pixel:

cairosvg.svg2png(
    url="emblem-percent.svg",
    parent_width=960,
    parent_height=480,
    write_to="emblem-percent.png",
)

Il nostro output era di 480 × 240 pixel: metà della larghezza e metà dell'altezza del genitore. Questo spiega perché parent_width=480 non è intercambiabile con output_width=480.

Se CairoSVG segnala che la dimensione SVG è indefinita, esamina prima le dimensioni radice. Assegna al documento dimensioni positive appropriate all'uso, oppure fornisci le dimensioni del genitore quando le percentuali dipendono da esse. Non dedurre la dimensione di pagina prevista da quanto grande un browser mostra casualmente la grafica.

Le dimensioni fisiche si comportano diversamente

Cambia la radice originale in width="2.5in" height="1.25in", mantenendo il viewBox. Nel nostro test, dpi=96 ha prodotto un PNG di 240 × 120 e dpi=192 un PNG di 480 × 240. Entrambi i PDF sono rimasti di 180 × 90 punti.

Qui la sorgente definisce una dimensione fisica, quindi più pixel per pollice aumentano la risoluzione raster mantenendo la dimensione fisica della pagina PDF. Lo stesso principio permette a una pagina creata deliberatamente di usare millimetri o pollici. Controlla il riquadro della pagina PDF esportata anziché presumere che un grande conteggio di pixel significhi una pagina A4 o letter.

Se il logo deve stare in un report con testo, margini e diversi elementi, usa un passaggio di impaginazione del documento. La nostra guida al posizionamento SVG con ReportLab tratta la costruzione diretta di PDF; i controlli di risorse e dimensionamento di WeasyPrint trattano i documenti HTML.

Verifica l'esportazione, compreso ciò che è rimasto vettoriale

Abbiamo letto le intestazioni PNG con Pillow e i riquadri di pagina e i flussi di contenuto PDF con pypdf 6.10.0. Ognuno dei quattro PDF della sorgente in pixel conteneva operazioni di disegno di tracciati e zero immagini di pagina. Questo conferma la geometria vettoriale per questo campione semplice, senza immagini. Non dimostra la piena fedeltà di un SVG arbitrario.

Per controllare le dimensioni dei tuoi output, installa pillow e pypdf nello stesso ambiente ed esegui:

from PIL import Image
from pypdf import PdfReader
 
with Image.open("emblem-480.png") as image:
    print("PNG pixels:", image.size)
 
page = PdfReader("emblem.pdf").pages[0]
print("PDF points:", float(page.mediabox.width),
      float(page.mediabox.height))
print("Page images:", len(page.images))

Il riferimento di PageObject descrive mediabox e images. Il conteggio delle immagini è una diagnosi utile, ma non può dimostrare che ogni forma, font o effetto sia sopravvissuto correttamente.

Prima della consegna:

1. Apri PNG e PDF e confronta l'emblema con l'SVG. Controlla apertura, triangolo, barra e margini.
2. Verifica indipendentemente le dimensioni in pixel del PNG e le dimensioni fisiche del PDF.
3. Esamina la grafica alla dimensione d'uso prevista, compresi spazi stretti e piccoli dettagli.
4. Mantieni l'SVG originale e ripeti questi controlli dopo averlo cambiato o aver aggiornato il convertitore.

La pagina sul supporto SVG di CairoSVG afferma che l'output vettoriale viene conservato dove possibile. Le immagini raster incorporate rimangono contenuto raster. Se il file contiene un PNG in un contenitore SVG, la diagnosi delle immagini incorporate aiuta a identificarlo prima dell'esportazione.

CairoSVG è un renderer statico. Animazione, scripting, layout avanzato del testo e molti filtri sono fuori dal suo flusso supportato. La sua documentazione elenca soltanto feOffset, feBlend e feFlood come filtri supportati. Per grafica che dipende da altri effetti, confronta attentamente il risultato o esporta attraverso un'applicazione che supporta quelle funzionalità. Una chiamata di conversione riuscita, da sola, non basta.

Recupera un originale vettoriale soltanto quando serve alla sorgente

Se il logo sopravvive soltanto come PNG o JPG, PerfectVector può fornire il passaggio a monte da raster a SVG prima che CairoSVG lo esporti. Controlla forme recuperate, piccole aperture e scritte del marchio in un editor; poi salva un originale SVG autonomo. Il nostro flusso di vettorializzazione dei loghi spiega quell'esame.

Un SVG modificabile esistente può passare direttamente alla fase di esportazione. Convertirlo in PNG e ricalcarlo di nuovo scarterebbe geometria sorgente utile. Le foto possono rimanere immagini raster quando quello è il contenuto previsto.

Per un logo soltanto raster, prova la tua immagine in PerfectVector, esamina contorni e aperture dell'SVG, poi verifica sia le dimensioni in pixel sia la dimensione fisica della pagina delle tue esportazioni CairoSVG.

FAQ

Perché cambiare i DPI lascia il mio PNG della stessa dimensione? Se la radice SVG usa dimensioni in pixel, cambiare i DPI non cambia necessariamente il conteggio dei pixel PNG. In questo esempio, un SVG di 240 per 120 pixel è rimasto di quella dimensione a 192 DPI. Usa output_width o scale quando ti servono più pixel di output.

La larghezza del genitore è uguale alla larghezza di output? No. parent_width fornisce il contenitore usato per risolvere dimensioni percentuali. output_width richiede la larghezza finale di output. Una larghezza radice del 50% con parent_width di 960 si risolveva in 480 pixel nell'esempio.

CairoSVG crea sempre un PDF interamente vettoriale? No. CairoSVG conserva l'output vettoriale dove possibile, ma un SVG può includere immagini raster e funzionalità non supportate. Esamina contenuto e aspetto del PDF anziché trattare l'estensione del file come prova.

Fonti

1. Documentazione CairoSVG — Descrive installazione, API di conversione, controlli di dimensionamento e limiti di rendering.
2. Supporto SVG 1.1 di CairoSVG — Spiega conservazione del vettore, immagini incorporate e funzionalità non supportate.
3. Riferimento pypdf PageObject — Documenta le interfacce dei riquadri di pagina e delle immagini usate per esaminare il PDF.